service ToolWorkflowService {
  rpc CreateWorkflow(CreateWorkflowRequest) returns (CreateWorkflowResponse);
  rpc GetWorkflow(GetWorkflowRequest) returns (GetWorkflowResponse);
  rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse);
  rpc UpdateWorkflow(UpdateWorkflowRequest) returns (UpdateWorkflowResponse);
  rpc DeleteWorkflow(DeleteWorkflowRequest) returns (DeleteWorkflowResponse);
}

message Workflow {
  string id = 1;
  string name = 2;
  string description = 3;
  string api_spec_id = 4;
  string input_schema_json = 5;   // JSON Schema, serialized as a string
  repeated WorkflowStep steps = 6;
}

message WorkflowStep {
  string name = 1;
  string operation_id = 2;
  string body_template = 3;
  map<string, string> extractors = 4;
  string on_error = 5;             // "AbortWorkflow" | "Continue" | "RetryN(<n>)"
}

message WorkflowSummary {
  string id = 1;
  string name = 2;
  string description = 3;
}

service GatewayInvocationService {
  rpc InvokeWorkflow(InvokeWorkflowRequest) returns (InvokeWorkflowResponse);
  rpc InvokeCli(InvokeCliRequest) returns (InvokeCliResponse);
  rpc ExploreApi(ExploreApiRequest) returns (ExploreApiResponse);
  rpc ListTools(ListToolsRequest) returns (ListToolsResponse);
}

message InvokeWorkflowRequest {
  string execution_id = 1;
  string workflow_name = 2;
  string input_json = 3;            // JSON-encoded input matching the workflow's input_schema
  string zaru_user_token = 4;       // Optional end-user token for tenant-scoped credential resolution
  string tenant_id = 5;
}

message InvokeWorkflowResponse {
  string result_json = 1;
}

message FsalMount {
  string volume_id = 1;
  string mount_path = 2;
  bool read_only = 3;
  string remote_path = 4;
}

message InvokeCliRequest {
  string execution_id = 1;
  string tool_name = 2;
  string subcommand = 3;
  repeated string args = 4;
  repeated FsalMount fsal_mounts = 5;
  string tenant_id = 6;
}

message InvokeCliResponse {
  int32 exit_code = 1;
  string stdout = 2;
  string stderr = 3;
}

message ToolSummary {
  string name = 1;
  string description = 2;
  string kind = 3;                  // "workflow" | "cli" | "native"
  string input_schema_json = 4;     // Full JSON Schema for the tool's input
  repeated string tags = 5;
  string category = 6;
}

# Install codegen plugins (one-time).
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate from the proto file.
protoc \
  --go_out=./gen --go_opt=paths=source_relative \
  --go-grpc_out=./gen --go-grpc_opt=paths=source_relative \
  -I path/to/aegis-proto/proto \
  path/to/aegis-proto/proto/seal_gateway.proto

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"

    sgw "your-module/gen"
)

func main() {
    conn, err := grpc.NewClient(
        "gateway-host:50055",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        log.Fatalf("dial: %v", err)
    }
    defer conn.Close()

    client := sgw.NewToolWorkflowServiceClient(conn)

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+operatorJWT)

    resp, err := client.ListWorkflows(ctx, &sgw.ListWorkflowsRequest{})
    if err != nil {
        log.Fatalf("ListWorkflows: %v", err)
    }
    for _, w := range resp.Workflows {
        fmt.Printf("- %s (%s): %s\n", w.Name, w.Id, w.Description)
    }
}

# Install codegen tooling.
pip install grpcio grpcio-tools

# Generate Python stubs.
python -m grpc_tools.protoc \
  -I path/to/aegis-proto/proto \
  --python_out=./gen \
  --grpc_python_out=./gen \
  path/to/aegis-proto/proto/seal_gateway.proto

import json
import grpc

from gen import seal_gateway_pb2 as sgw
from gen import seal_gateway_pb2_grpc as sgw_grpc

OPERATOR_JWT = "eyJ..."

channel = grpc.insecure_channel("gateway-host:50055")
client  = sgw_grpc.GatewayInvocationServiceStub(channel)

# The orchestrator-trusted invocation path: no operator auth needed for
# InvokeWorkflow over gRPC. (Add metadata if you front the gRPC port with
# a service mesh that asserts identity.)
request = sgw.InvokeWorkflowRequest(
    execution_id  = "exec-8a9f7b3c",
    workflow_name = "create-github-issue",
    input_json    = json.dumps({
        "owner": "100monkeys-ai",
        "repo":  "aegis",
        "title": "Tracked from gRPC client",
        "body":  "Body content here.",
    }),
    tenant_id     = "tenant-acme",
)

response = client.InvokeWorkflow(request)
print(json.loads(response.result_json))

metadata = (("authorization", f"Bearer {OPERATOR_JWT}"),)
stub = sgw_grpc.ToolWorkflowServiceStub(channel)
resp = stub.ListWorkflows(sgw.ListWorkflowsRequest(), metadata=metadata)
for w in resp.workflows:
    print(w.id, w.name, w.description)

npm install --save @grpc/grpc-js @bufbuild/protobuf
npm install --save-dev @bufbuild/protoc-gen-es

npx buf generate path/to/aegis-proto/proto/seal_gateway.proto \
  --template buf.gen.yaml

version: v1
plugins:
  - plugin: es
    out: gen
    opt: target=ts

import * as grpc from "@grpc/grpc-js";
import {
  GatewayInvocationServiceClient,
  ListToolsRequest,
} from "./gen/seal_gateway_pb";

const client = new GatewayInvocationServiceClient(
  "gateway-host:50055",
  grpc.credentials.createInsecure(),
);

const req = new ListToolsRequest();

client.listTools(req, (err, resp) => {
  if (err) throw err;
  for (const t of resp.getToolsList()) {
    console.log(t.getName(), t.getKind(), t.getDescription());
  }
});

const md = new grpc.Metadata();
md.add("authorization", `Bearer ${operatorJWT}`);
client.listWorkflows(new ListWorkflowsRequest(), md, (err, resp) => { /* ... */ });