@zeroroot-ai/gibson-mcp 0.1.0

package/dist/discovery.js

@@ -0,0 +1,132 @@
+import { callGibsonTool, listGibsonPlugins, listGibsonTools, queryGibsonPlugin } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { formatToolResult } from "./helpers/tools.js";
+import { TAG } from "./log.js";
+import { defineTool } from "./tool.js";
+/**
+ * Checked-in platform tools and plugins, discovered at runtime.
+ *
+ * The fleet changes while a session runs: a tool a person enrols now should
+ * be callable in the same session. So discovery repeats, and the registry's
+ * `tools/list_changed` notification is what tells every attached host to
+ * ask again.
+ *
+ * Each discovered tool registers on its own, named `gibson_<tool>`, so the
+ * model sees its description rather than one opaque dispatcher. The catalog
+ * carries no JSON Schema, only a proto message type name, so the wrapper
+ * takes one free-form `input` object and names the type it must match.
+ * `gibson_call_tool` stays registered either way: discovery answers
+ * `Unimplemented` on some daemons (gibson#1186).
+ */
+export const DISCOVERY_INTERVAL_MS = 60_000;
+/** `gibson_<tool>`, with anything not legal in an MCP tool name replaced. */
+export function toolKey(name) {
+    return `gibson_${name.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+}
+export function pluginKey(name) {
+    return `gibson_plugin_${name.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+}
+export function discoveredTool(session, t) {
+    const schemaNote = t.inputMessageType ? ` Input must match the Gibson message type ${t.inputMessageType}.` : "";
+    return defineTool({
+        name: toolKey(t.name),
+        description: `${t.description || `Gibson tool "${t.name}"`}${schemaNote} Runs through the Gibson harness, authorized and metered.`,
+        input: {
+            input: z.record(z.string(), z.unknown()).describe(`Input object for the ${t.name} tool.`),
+            timeout_ms: z.number().int().min(1).optional().describe("Per-call timeout in milliseconds."),
+        },
+        handler: async (args) => formatToolResult(t.name, await callGibsonTool(session.clients.component, { name: t.name, input: args.input, ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}) })),
+    });
+}
+export function discoveredPlugin(session, p) {
+    const methods = p.methods.length > 0 ? ` Methods: ${p.methods.join(", ")}.` : "";
+    return defineTool({
+        name: pluginKey(p.name),
+        description: `${p.description || `Gibson plugin "${p.name}"`}${methods} Runs through the Gibson harness, authorized and metered.`,
+        input: {
+            method: z.string().describe(`Method to call on the ${p.name} plugin.`),
+            params: z.record(z.string(), z.unknown()).optional().describe("Method parameters."),
+        },
+        handler: async (args) => formatToolResult(`${p.name}.${args.method}`, await queryGibsonPlugin(session.clients.component, { plugin: p.name, method: args.method, params: args.params ?? {} })),
+    });
+}
+/**
+ * Poll the catalog and keep the registered set equal to it.
+ *
+ * A pass that cannot reach the catalog leaves the set alone. Dropping every
+ * discovered tool because one poll failed would take working tools away from
+ * a session mid-task over a transient fault.
+ */
+export function startDiscovery(opts) {
+    const { group, session, log } = opts;
+    const interval = opts.intervalMs ?? DISCOVERY_INTERVAL_MS;
+    const registered = new Map();
+    let stopped = false;
+    let timer;
+    const refresh = async () => {
+        const [discovery, plugins] = await Promise.all([
+            listGibsonTools(session.clients.component),
+            listGibsonPlugins(session.clients.component).catch(() => []),
+        ]);
+        if (discovery.unavailable && plugins.length === 0) {
+            return { tools: 0, plugins: 0, note: discovery.unavailable, changed: false };
+        }
+        const wanted = new Map();
+        for (const t of discovery.tools)
+            wanted.set(toolKey(t.name), discoveredTool(session, t));
+        for (const p of plugins)
+            wanted.set(pluginKey(p.name), discoveredPlugin(session, p));
+        // Collected before anything is removed: the map is mutated below, and
+        // deleting from it mid-iteration skips entries.
+        const gone = [];
+        for (const name of registered.keys()) {
+            if (!wanted.has(name))
+                gone.push(name);
+        }
+        let changed = false;
+        group.batch(() => {
+            for (const name of gone) {
+                group.remove(name);
+                registered.delete(name);
+                changed = true;
+            }
+            for (const [name, def] of wanted) {
+                if (registered.has(name))
+                    continue;
+                // A helper or a generated tool already owns this name: leave it be.
+                if (group.has(name))
+                    continue;
+                group.register(def);
+                registered.set(name, def);
+                changed = true;
+            }
+        });
+        return { tools: discovery.tools.length, plugins: plugins.length, ...(discovery.unavailable ? { note: discovery.unavailable } : {}), changed };
+    };
+    const tick = async () => {
+        if (stopped)
+            return;
+        try {
+            const outcome = await refresh();
+            if (outcome.changed)
+                log(`${TAG} discovery: ${outcome.tools} tool(s), ${outcome.plugins} plugin(s) registered`);
+        }
+        catch (e) {
+            // Keep what is registered: a transient fault must not take working
+            // tools away from a session mid-task.
+            log(`${TAG} discovery failed, keeping the current set: ${e.message}`);
+        }
+    };
+    if (interval > 0) {
+        timer = setInterval(() => void tick(), interval);
+        timer.unref?.();
+    }
+    return {
+        refresh,
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+        },
+    };
+}

package/dist/flags.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The bin's flags.
+ *
+ *  - `--transport stdio` (default): the laptop path. The host spawns the
+ *    server and talks over stdin and stdout.
+ *  - `--transport http --listen 127.0.0.1:<port>`: the sandbox path. The
+ *    member driver runs one server for the life of the sandbox and swaps
+ *    the grant per turn through it (slice A4). Only a loopback address is
+ *    accepted: a control endpoint that swaps credentials never sits on a
+ *    network interface.
+ *  - `--stream-limit <n>`: how many messages a server-streaming RPC tool
+ *    collects before it returns with `truncated: true` (slice A2).
+ */
+export type TransportKind = "stdio" | "http";
+export interface Listen {
+    host: string;
+    port: number;
+}
+export interface Flags {
+    transport: TransportKind;
+    listen: Listen;
+    streamLimit: number;
+    help: boolean;
+    version: boolean;
+}
+export declare const DEFAULT_LISTEN = "127.0.0.1:7788";
+export declare const DEFAULT_STREAM_LIMIT = 500;
+export declare function isLoopback(host: string): boolean;
+/** `host:port`, `[v6]:port`, or a bare port on 127.0.0.1. */
+export declare function parseListen(raw: string): Listen;
+export declare function parseFlags(argv: string[]): Flags;
+export declare function usage(): string;

package/dist/flags.js

@@ -0,0 +1,85 @@
+import { parseArgs } from "node:util";
+export const DEFAULT_LISTEN = "127.0.0.1:7788";
+export const DEFAULT_STREAM_LIMIT = 500;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+export function isLoopback(host) {
+    return LOOPBACK_HOSTS.has(host) || host.startsWith("127.");
+}
+/** `host:port`, `[v6]:port`, or a bare port on 127.0.0.1. */
+export function parseListen(raw) {
+    const s = raw.trim();
+    let host;
+    let portText;
+    const v6 = /^\[([^\]]+)\]:(\d+)$/.exec(s);
+    if (v6) {
+        host = v6[1];
+        portText = v6[2];
+    }
+    else if (/^\d+$/.test(s)) {
+        host = "127.0.0.1";
+        portText = s;
+    }
+    else {
+        const i = s.lastIndexOf(":");
+        if (i <= 0)
+            throw new Error(`--listen ${JSON.stringify(raw)} is not host:port`);
+        host = s.slice(0, i);
+        portText = s.slice(i + 1);
+    }
+    const port = Number(portText);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`--listen ${JSON.stringify(raw)} has no valid port`);
+    if (!isLoopback(host)) {
+        throw new Error(`--listen ${JSON.stringify(raw)} is not a loopback address; the HTTP transport serves localhost only`);
+    }
+    return { host, port };
+}
+export function parseFlags(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: false,
+        options: {
+            transport: { type: "string", default: "stdio" },
+            listen: { type: "string", default: DEFAULT_LISTEN },
+            "stream-limit": { type: "string", default: String(DEFAULT_STREAM_LIMIT) },
+            help: { type: "boolean", short: "h", default: false },
+            version: { type: "boolean", default: false },
+        },
+    });
+    const transport = values.transport;
+    if (transport !== "stdio" && transport !== "http") {
+        throw new Error(`--transport must be stdio or http, got ${JSON.stringify(transport)}`);
+    }
+    const streamLimit = Number(values["stream-limit"]);
+    if (!Number.isInteger(streamLimit) || streamLimit < 1) {
+        throw new Error(`--stream-limit must be a positive integer, got ${JSON.stringify(values["stream-limit"])}`);
+    }
+    return {
+        transport,
+        listen: parseListen(values.listen),
+        streamLimit,
+        help: values.help,
+        version: values.version,
+    };
+}
+export function usage() {
+    return [
+        "gibson-mcp: the Gibson MCP server.",
+        "",
+        "  gibson-mcp [--transport stdio]",
+        `  gibson-mcp --transport http [--listen ${DEFAULT_LISTEN}]`,
+        "",
+        "Flags:",
+        "  --transport stdio|http   stdio (default) for a host that spawns the server; http for a sandbox.",
+        `  --listen host:port       loopback address for the HTTP transport (default ${DEFAULT_LISTEN}).`,
+        `  --stream-limit n         messages a streaming RPC tool returns before it truncates (default ${DEFAULT_STREAM_LIMIT}).`,
+        "  --version                print the package version.",
+        "  -h, --help               this text.",
+        "",
+        "Check-in source, decided from the environment, never mixed:",
+        "  GIBSON_CG_JWT + GIBSON_CALLBACK_ENDPOINT   dispatched: the daemon launched this process.",
+        "  GIBSON_BOOTSTRAP_TOKEN (no host key yet)   pre-minted token: first check-in, host key thereafter.",
+        "  otherwise                                  enrolled: host key, or gibson_login then gibson_connect.",
+    ].join("\n");
+}

package/dist/generated/tools.d.ts

@@ -0,0 +1,15 @@
+import type { GenService } from "@bufbuild/protobuf/codegenv2";
+export interface GeneratedMethodDoc {
+    /** The generated property name, which is also the client method. */
+    method: string;
+    /** The RPC's leading proto comment, as one line. */
+    description: string;
+}
+export interface GeneratedServiceDoc {
+    service: GenService<any>;
+    description: string;
+    methods: GeneratedMethodDoc[];
+}
+export declare const GENERATED_SERVICES: GeneratedServiceDoc[];
+/** Every RPC of every service, counted at generate time. */
+export declare const GENERATED_RPC_COUNT = 188;

package/dist/generated/tools.js

@@ -0,0 +1,276 @@
+import { AgentService } from "@zeroroot-ai/sdk/gen/gibson/agent/v1/agent_pb.js";
+import { AgentIdentityService } from "@zeroroot-ai/sdk/gen/gibson/agentidentity/v1/agent_identity_pb.js";
+import { BankService } from "@zeroroot-ai/sdk/gen/gibson/bank/v1/bank_pb.js";
+import { ComponentService } from "@zeroroot-ai/sdk/gen/gibson/component/v1/component_pb.js";
+import { DaemonService } from "@zeroroot-ai/sdk/gen/gibson/daemon/v1/daemon_pb.js";
+import { GraphService } from "@zeroroot-ai/sdk/gen/gibson/graph/v1/graph_pb.js";
+import { HarnessCallbackService } from "@zeroroot-ai/sdk/gen/gibson/harness/v1/harness_callback_pb.js";
+import { IdentityService } from "@zeroroot-ai/sdk/gen/gibson/identity/v1/identity_pb.js";
+import { JobService } from "@zeroroot-ai/sdk/gen/gibson/job/v1/job_pb.js";
+import { PluginInvokeService } from "@zeroroot-ai/sdk/gen/gibson/plugin/v1/invoke_pb.js";
+import { PluginAdminService } from "@zeroroot-ai/sdk/gen/gibson/pluginadmin/v1/plugin_admin_pb.js";
+import { ToolService } from "@zeroroot-ai/sdk/gen/gibson/tool/v1/tool_pb.js";
+export const GENERATED_SERVICES = [
+    {
+        service: AgentService,
+        description: "",
+        methods: [
+            { method: "getDescriptor", description: "" },
+            { method: "getSlotSchema", description: "" },
+            { method: "execute", description: "" },
+            { method: "health", description: "" },
+        ],
+    },
+    {
+        service: AgentIdentityService,
+        description: "AgentIdentityService provisions and manages machine identities for agents, tools, and plugins.",
+        methods: [
+            { method: "createAgentIdentity", description: "CreateAgentIdentity provisions a new machine identity for an agent, tool, or plugin. Returns a one-time capability-grant bootstrap_token that cannot be recovered after this call (ADR-0045 — the unified enrollment credential for every kind)." },
+            { method: "listAgentIdentities", description: "ListAgentIdentities returns all agent/tool/plugin identities provisioned in the caller's tenant, with optional kind filtering and pagination." },
+            { method: "revokeAgentIdentity", description: "RevokeAgentIdentity permanently revokes a machine identity. Existing JWTs stop validating within the IdP token TTL (<=60 seconds). Idempotent on already-revoked principals (returns NotFound)." },
+        ],
+    },
+    {
+        service: BankService,
+        description: "BankService creates, reads, updates and deletes banks, lists their members, and relays the in-sandbox subscription sign in to the owner. People and platform services call it. A dispatched component reaches banks through gibson.job.v1.JobService and the harness callback under its own grant, not through this service.",
+        methods: [
+            { method: "createBank", description: "CreateBank declares a bank. The daemon starts to launch members until desired_count of them run. The caller owns the bank unless tenant_owned is true." },
+            { method: "getBank", description: "GetBank returns one bank by id." },
+            { method: "listBanks", description: "ListBanks returns the banks of the caller's tenant, newest first." },
+            { method: "updateBank", description: "UpdateBank changes desired_count and the policies of a bank. A field that is absent keeps its value. The login shape, the agent and the model are fixed at creation." },
+            { method: "deleteBank", description: "DeleteBank drains every member, closes their open jobs with verdict ABANDONED, and removes the bank." },
+            { method: "listMembers", description: "ListMembers returns the members of a bank with their last reported status." },
+            { method: "startSignIn", description: "StartSignIn asks a member at NEEDS_SIGN_IN to run the Anthropic sign in inside its sandbox. Follow it with StreamSignIn to read the URL and the code prompt, then SubmitSignInCode. Only the owner signs in: the subscription is theirs." },
+            { method: "streamSignIn", description: "StreamSignIn relays the sign-in flow of one member: the URL to open, the code prompt when the flow asks for one, and done or error at the end. The stream closes after done or error." },
+            { method: "submitSignInCode", description: "SubmitSignInCode passes the code the person got from Anthropic to the sign-in flow that runs inside the member's sandbox." },
+        ],
+    },
+    {
+        service: ComponentService,
+        description: "ComponentService is the central gRPC service that all Gibson components (agents, tools, and plugins) connect to. Components register themselves, receive work via long-polling, submit results, and access harness operations (LLM completion, tool calls, plugin queries, findings, memory) through the proxy RPCs defined here.",
+        methods: [
+            { method: "registerComponent", description: "RegisterComponent announces a component to Gibson and receives connection configuration including heartbeat and poll intervals." },
+            { method: "heartbeat", description: "Heartbeat sends a periodic health pulse. The response indicates whether the component is still considered registered and may carry config updates." },
+            { method: "pollWork", description: "PollWork long-polls for work items assigned to this component instance. Returns when a work item is available or the server-side timeout expires. Authorized by can_poll_work, not can_execute: PollWork/SubmitResult are the receive-side of dispatch (how a component gets its work), distinct from CallTool/RunMission's drive-side (how a component directs the platform). Sharing can_execute would let a poll-only grant also drive missions. can_poll_work is modeled as `can_execute or can_receive_work`, so existing can_execute holders keep polling unchanged." },
+            { method: "submitResult", description: "SubmitResult returns the execution result for a previously polled work item. Authorized by can_poll_work — see PollWork's comment for why this receive-side RPC does not share can_execute with the drive-side RPCs." },
+            { method: "complete", description: "Complete proxies an LLM completion request through the agent harness." },
+            { method: "completeStream", description: "CompleteStream proxies a streaming LLM completion request through the agent harness." },
+            { method: "callTool", description: "CallTool proxies a tool execution request through the agent harness." },
+            { method: "queryPlugin", description: "QueryPlugin proxies a plugin query request through the agent harness." },
+            { method: "submitFinding", description: "SubmitFinding submits a security finding through the agent harness." },
+            { method: "listAvailablePlugins", description: "ListAvailablePlugins returns all plugins registered in the system along with their catalog metadata, health status, and configuration schema." },
+            { method: "enablePlugin", description: "EnablePlugin activates a plugin for the calling tenant, optionally supplying an initial configuration JSON blob." },
+            { method: "disablePlugin", description: "DisablePlugin deactivates a plugin for the calling tenant." },
+            { method: "updatePluginConfig", description: "UpdatePluginConfig replaces the configuration for an already-enabled plugin." },
+            { method: "getPluginConfig", description: "GetPluginConfig retrieves the current configuration and schema for a plugin." },
+            { method: "testPluginConnection", description: "TestPluginConnection validates connectivity and credentials for a plugin without persisting any state changes." },
+            { method: "listTenantPlugins", description: "ListTenantPlugins returns the plugin access records for the calling tenant." },
+            { method: "completeWithTools", description: "CompleteWithTools proxies an LLM completion with tool definitions for function-calling support. Returns the response including any tool calls." },
+            { method: "completeStructured", description: "CompleteStructured proxies an LLM completion requesting JSON output conforming to the supplied schema." },
+            { method: "callToolStream", description: "CallToolStream proxies a tool execution with server-side streaming of progress, partial results, warnings, and the final output." },
+            { method: "queueToolWork", description: "QueueToolWork submits a batch of tool invocations for parallel execution and returns a job ID for tracking." },
+            { method: "toolResults", description: "ToolResults streams results for a previously queued tool batch as each invocation completes." },
+            { method: "listTools", description: "ListTools returns descriptors for all tools visible to the caller's tenant." },
+            { method: "delegateToAgent", description: "DelegateToAgent dispatches a sub-task to another agent and returns its result." },
+            { method: "listAgents", description: "ListAgents returns descriptors for all agents visible to the caller's tenant." },
+            { method: "queryNodes", description: "QueryNodes searches the knowledge graph using hybrid vector + graph scoring." },
+            { method: "findSimilarAttacks", description: "FindSimilarAttacks returns attack patterns semantically similar to the given content." },
+            { method: "getAttackChains", description: "GetAttackChains returns multi-hop attack paths from a starting technique." },
+            { method: "findSimilarFindings", description: "FindSimilarFindings returns findings semantically similar to the given finding." },
+            { method: "getRelatedFindings", description: "GetRelatedFindings returns findings related to the given finding via graph edges." },
+            { method: "getFindings", description: "GetFindings queries previously submitted findings with optional filters." },
+            { method: "getRunFindings", description: "GetRunFindings queries findings scoped to a specific mission run or across all runs." },
+            { method: "createMission", description: "CreateMission creates a new sub-mission." },
+            { method: "runMission", description: "RunMission queues a mission for execution." },
+            { method: "getMissionStatus", description: "GetMissionStatus returns the current status of a mission." },
+            { method: "waitMission", description: "WaitMission blocks until a mission completes or the timeout expires." },
+            { method: "listMissions", description: "ListMissions returns missions matching the given filter." },
+            { method: "cancelMission", description: "CancelMission requests cancellation of a running mission." },
+            { method: "getMissionResults", description: "GetMissionResults returns the final results of a completed mission." },
+            { method: "getCredential", description: "GetCredential retrieves a tenant-scoped credential by name." },
+            { method: "getTaxonomySchema", description: "GetTaxonomySchema returns the current taxonomy definition." },
+            { method: "getMissionRunHistory", description: "GetMissionRunHistory returns summaries of previous mission runs." },
+            { method: "reportStepHints", description: "ReportStepHints reports planning step hints from an agent back to the orchestrator." },
+        ],
+    },
+    {
+        service: DaemonService,
+        description: "DaemonService provides the gRPC API for Gibson daemon client communication. This service exposes operational daemon functionality including mission execution, agent management, and real-time event streaming for the TUI and SDK clients.",
+        methods: [
+            { method: "connect", description: "Connect establishes a client connection to the daemon. Returns connection metadata and daemon version info." },
+            { method: "ping", description: "Ping checks if the daemon is responsive. Used for health checks and connection validation." },
+            { method: "status", description: "Status returns the current daemon status including uptime, service endpoints, and component counts." },
+            { method: "subscribe", description: "Subscribe establishes an event stream for TUI real-time updates. Streams mission events, agent events, finding events, etc." },
+            { method: "runMission", description: "RunMission starts a mission and streams execution events. The stream remains open until the mission completes or is stopped." },
+            { method: "stopMission", description: "StopMission gracefully stops a running mission." },
+            { method: "createMission", description: "CreateMission creates a new mission with target and mission-definition reference. Supports both referenced and inline configurations." },
+            { method: "createTarget", description: "CreateTarget registers a new target and returns its server-minted UUID. The id field of the supplied target is ignored; the daemon mints it." },
+            { method: "getTarget", description: "GetTarget returns a single target by its UUID." },
+            { method: "listTargets", description: "ListTargets returns the calling tenant's targets, narrowed by TargetFilter." },
+            { method: "updateTarget", description: "UpdateTarget replaces a target's metadata. The id field is the lookup key and is never changed." },
+            { method: "deleteTarget", description: "DeleteTarget removes a target by its UUID." },
+            { method: "listMissions", description: "ListMissions returns all missions (past and active)." },
+            { method: "pauseMission", description: "PauseMission pauses a running mission at the next clean checkpoint boundary. If force is true, pauses immediately without waiting for a clean boundary." },
+            { method: "resumeMission", description: "ResumeMission resumes a paused mission from its last checkpoint. Returns a stream of mission events as execution continues." },
+            { method: "getMissionHistory", description: "GetMissionHistory returns all runs for a mission name, showing the complete history of mission executions with the same mission name." },
+            { method: "listMissionDefinitions", description: "ListMissionDefinitions returns all installed mission definitions." },
+            { method: "createMissionDefinition", description: "CreateMissionDefinition registers a structured mission definition with the daemon. This is the API-only replacement for the removed InstallMission RPC: the daemon does not clone git repositories or parse YAML; callers submit a fully-formed MissionDefinition proto (serialized from JSON in the CLI via protojson, or constructed natively in the dashboard)." },
+            { method: "updateMissionDefinition", description: "UpdateMissionDefinition replaces the content of an existing mission definition. The name field of the embedded definition is the lookup key. All other fields replace the stored definition; the server-assigned ID and original timestamps are preserved. Returns codes.NotFound if no definition with that name exists. Spec: gibson#437." },
+            { method: "getMissionDefinition", description: "GetMissionDefinition returns the full structured proto for a single installed mission definition, looked up by name. Use this instead of ListMissionDefinitions when the caller knows the definition name and needs every author-facing field (workspace, constraints, per-node retry/data/reuse policies). Returns codes.NotFound when the name is not registered. Spec: mission-author-experience M5 (gibson#134)." },
+            { method: "getMissionGraph", description: "GetMissionGraph returns the renderable flow-chart projection of a mission definition: typed nodes (boxes), data-flow edges, derived entry/exit, and per-node positions. The daemon computes the topology and a deterministic auto-layout from the mission DAG, then overlays any saved layout from the mission layout store (SaveMissionLayout) so hand-arranged positions win. This keeps the dashboard a pure renderer — it never re-derives topology. Presentation only: nothing here affects mission execution. Spec: MissionGraph epic (sdk#278)." },
+            { method: "getMissionLayout", description: "GetMissionLayout returns the saved diagram layout (per-node positions + viewport) for a mission definition, or an empty layout when none has been saved. The layout store is separate from the mission definition record — the mission work-schema carries no presentation state. Keyed by mission_definition_id. Spec: MissionGraph epic (sdk#278)." },
+            { method: "saveMissionLayout", description: "SaveMissionLayout persists a hand-arranged diagram layout for a mission definition into the layout store. Layout-only: it never mutates the mission definition, its nodes/edges/configs, or its cue_source. The optional expected_version enables optimistic concurrency — a stale write (the layout changed underneath) is rejected rather than clobbering. Keyed by mission_definition_id. Spec: MissionGraph epic (sdk#278)." },
+            { method: "listAgents", description: "ListAgents returns all registered agents from the etcd registry." },
+            { method: "getAgentStatus", description: "GetAgentStatus returns the current status of a specific agent." },
+            { method: "listTools", description: "ListTools returns all registered tools from the etcd registry." },
+            { method: "listPlugins", description: "ListPlugins returns all registered plugins from the etcd registry." },
+            { method: "getCapabilityManifest", description: "GetCapabilityManifest returns the signed, versioned capability manifest for the calling principal in their resolved tenant. SDKs call this on session start and on invalidation events. The ADK calls it at scaffold time to discover what components, permissions, cross-component rules, and runtime limits apply." },
+            { method: "watchManifestInvalidations", description: "WatchManifestInvalidations streams ManifestInvalidationEvents to the caller whenever their resolved tenant's manifest is invalidated (FGA mutation, component registry change, tier update). Heartbeats are emitted periodically to keep the stream alive." },
+            { method: "queryPlugin", description: "QueryPlugin executes a method on a plugin and returns the result. The plugin must be registered in the etcd registry." },
+            { method: "startComponent", description: "StartComponent starts a component (agent, tool, or plugin) by kind and name. The component must be installed in the local database." },
+            { method: "stopComponent", description: "StopComponent stops a running component (agent, tool, or plugin) by kind and name. If force is true, sends SIGKILL immediately instead of graceful SIGTERM." },
+            { method: "buildComponent", description: "BuildComponent rebuilds a component (agent, tool, or plugin) from source. Useful for rebuilding after manual code changes." },
+            { method: "showComponent", description: "ShowComponent returns detailed information about a component. Includes manifest, status, paths, and lifecycle information." },
+            { method: "getComponentLogs", description: "GetComponentLogs streams log entries for a component. Supports follow mode for continuous streaming and line limits." },
+            { method: "getMyPermissions", description: "GetMyPermissions returns the current user's role, is_admin flag, component grants, and team memberships for the current tenant. Used by the dashboard's PermissionsCache to gate UI elements without per-click daemon calls. Auth: self-mode (spec: self-mode-authz). The hotfix `unauthenticated: true` is replaced with `self: true + allowed_identities: USER`. This RPC may be called before the active-tenant cookie is set (which made the earlier `tenant_from_identity` FGA check fail with \"no tenant derivable\"), so no FGA tuple lookup is performed. The four defense layers are preserved: (a) Envoy `jwt_authn` validates the Zitadel JWT before ext-authz. (b) ext-authz mints X-Gibson-Identity-Subject from the verified sub — clients cannot forge it. (c) The daemon's SPIFFE mTLS init is fail-closed (zero-trust-hardening Req 1) so non-Envoy callers cannot reach the listener. (d) ext-authz enforces allowed_identities: only USER tokens are accepted. The handler scopes the response strictly to the caller's verified subject." },
+            { method: "listMyMemberships", description: "ListMyMemberships returns every tenant the authenticated caller is a member of, with the caller's role per tenant. Identity comes from the call context; no tenant_id parameter — this RPC discovers the caller's tenants. Used by the dashboard at sign-in time to populate the tenant picker / set the active-tenant cookie. Auth: self-mode (spec: self-mode-authz). The hotfix `unauthenticated: true` is replaced with `self: true + allowed_identities: USER`. By definition this RPC runs before the caller's active tenant is known, so a `tenant_from_identity` deriver would always fail \"no tenant derivable\". The same four defense layers as GetMyPermissions apply; see that method for the full contract. The handler self-scopes the membership list to the verified caller subject." },
+            { method: "renewCapabilityGrant", description: "RenewCapabilityGrant mints a fresh capability-grant JWT for an ongoing mission task whose existing CG-JWT is approaching its ≤30-minute expiry. Long-running missions (vuln research, broad recon sweeps, multi-host fuzzing) call this before their current CG-JWT expires so callbacks keep flowing without dispatching a fresh task. Authorization: the caller MUST present a valid (non-expired) CG-JWT whose subject matches the request's agent_id and whose mission_id/task_id match the request. Renewal is rate-limited per agent to prevent abuse. Spec: unified-identity-and-authorization Requirement 5.8." },
+            { method: "validateMissionCUE", description: "ValidateMissionCUE compiles a CUE mission snippet and returns diagnostics. Powers the dashboard CUE editor's real-time error squiggles, and is now callable by ADK/SDK users with a single user token. An empty diagnostics list means the source is valid." },
+            { method: "completeMissionCUE", description: "CompleteMissionCUE returns completion candidates at a cursor position. Powers the dashboard CUE editor's auto-complete." },
+            { method: "hoverMissionCUE", description: "HoverMissionCUE returns type and documentation for a position in CUE source. Powers the dashboard CUE editor's hover tooltip." },
+        ],
+    },
+    {
+        service: GraphService,
+        description: "GraphService serves per-tenant knowledge-graph reads and a server-streaming update feed. Every RPC routes through Pool.For(tenant).Neo4j() server-side and is gated by the FGA tenant.member relation at ext-authz.",
+        methods: [
+            { method: "getTenantGraph", description: "GetTenantGraph returns the full per-tenant subgraph subject to a server-side node-count cap. Use limit + include_labels to narrow scope." },
+            { method: "getMissionGraph", description: "GetMissionGraph returns the subgraph touched by a single mission run. Mission ownership is enforced by FGA + by `WHERE m.tenant_id = $tenant` in the underlying Cypher (defense in depth)." },
+            { method: "queryPaths", description: "QueryPaths runs a bounded path query from `from_node_id` to either a specific `to_node_id` or any node of `to_node_kind`, up to `max_depth`. Server caps: depth ≤ 10, paths ≤ 100, query timeout 5s." },
+            { method: "watchGraphUpdates", description: "WatchGraphUpdates server-streams new node/edge writes for the calling tenant. Subscribers should treat the stream as a UX hint, not a source of truth — drops are possible under load. Reconnect with exponential backoff; fall back to polling GetTenantGraph if the stream stays unhealthy." },
+            { method: "getFindingCounts", description: "GetFindingCounts returns finding counts grouped by severity or category. Replaces the dashboard's prior direct-Neo4j paths in gibson-client.ts (getKPIs, getFindingsBySeverity, getFindingsByCategory) and app/api/findings/counts/route.ts." },
+            { method: "getFindingTimeSeries", description: "GetFindingTimeSeries returns finding counts bucketed by day for the last N days (default 30, max 365). Missing days are returned as zero buckets." },
+            { method: "getGraphStats", description: "GetGraphStats returns aggregate stats for the per-tenant knowledge graph: node counts by label, total edges, last-write timestamp." },
+            { method: "getGraphSummary", description: "GetGraphSummary returns an LLM-friendly text summary of the per-tenant graph plus structured stats. Server-side caches results for 60s per tenant." },
+            { method: "getGraphContext", description: "GetGraphContext returns a focus node and its bounded neighborhood, used by the chatbot to enrich its system prompt. Returns an empty response (focus_node unset) on missing node or NotProvisioned — does NOT error, so the chatbot prompt never breaks." },
+            { method: "getFindings", description: "GetFindings returns a paginated, filterable list of findings (and vulnerabilities) for the calling tenant. Replaces the dashboard's direct-Neo4j paths in app/api/findings/route.ts, app/api/missions/[id]/findings/route.ts, and the iteration backing findings export. Spec: dashboard-neo4j-crud-removal Req 1." },
+        ],
+    },
+    {
+        service: HarnessCallbackService,
+        description: "HarnessCallbackService provides the harness interface for agents executing in standalone mode. The SDK's CallbackHarness forwards all harness operations to the orchestrator via this service.",
+        methods: [
+            { method: "lLMComplete", description: "LLM Operations" },
+            { method: "lLMCompleteWithTools", description: "" },
+            { method: "lLMCompleteStructured", description: "" },
+            { method: "lLMStream", description: "" },
+            { method: "callToolProto", description: "Tool Operations" },
+            { method: "callToolProtoStream", description: "" },
+            { method: "listTools", description: "" },
+            { method: "searchTools", description: "SearchTools returns a small, ranked, authz-filtered set of tools matching a query — the meta-tool surface agents use instead of receiving every tool (ADR-0047 facet 5). Per-tool authorization is enforced inside the handler; this RPC-level gate only checks that the caller may use the harness." },
+            { method: "queueToolWork", description: "Tool Work Queue Operations" },
+            { method: "toolResults", description: "" },
+            { method: "queryPlugin", description: "Plugin Operations" },
+            { method: "listPlugins", description: "" },
+            { method: "delegateToAgent", description: "Agent Operations" },
+            { method: "listAgents", description: "" },
+            { method: "submitFinding", description: "Finding Operations" },
+            { method: "observe", description: "Observe emits a typed observation into the World (ADR-0007). The brain resolves identity and topology; scope is derived server-side from context." },
+            { method: "worldView", description: "WorldView returns the caller's server-projected slice of the tenant World (ADR-0012, sdk#341's read half). It is the counterpart to Observe: Observe is the agent's only write, WorldView its only read. The slice is projected by the daemon from the mission record it created — the tenant that owns the World and the scope that bounds the slice are read there, never from this request. WorldViewRequest carries no tenant field and no scope field, so an agent cannot name another tenant's World or a wider slice: both are unrepresentable rather than rejected." },
+            { method: "queryNodes", description: "Knowledge Operations The knowledge-graph READ surface. It exists on ComponentService too, and that duplication is deliberate: without it here, a dispatched run holding only its task-scoped callback grant cannot read the tenant graph, and the agent would have to keep a component-scoped grant alive purely to call recall — which defeats the point of scoping the dispatch at all. See zerocool-plugins ADR-0006 and docs/adr/0001-callback-knowledge-reads.md. Read-only by construction. The write half is NOT mirrored: the projector is the sole graph writer (ADR-0012), and sdk#451 already removed the generic graph-write RPC from ComponentService." },
+            { method: "findSimilarAttacks", description: "" },
+            { method: "getAttackChains", description: "" },
+            { method: "findSimilarFindings", description: "" },
+            { method: "getRelatedFindings", description: "" },
+            { method: "getFindings", description: "" },
+            { method: "applicationFindings", description: "ApplicationFindings answers the one lifecycle question the reads above cannot: for this Application, what is still open, and does anything actually run the code it is in (gibson#1669). The reads above are hybrid vector-and-graph SEARCH — text or embedding, a node-type filter, top-k. Reachability is a TRAVERSAL: is this Package inside an Image that a Deployment of this Application runs, and does that Deployment expose a Host. No top-k over a node-type filter answers it. It is one bounded question rather than a Cypher surface, deliberately: an agent able to send arbitrary Cypher would be a second unaudited path into the tenant graph, and the traversal an agent needs is knowable in advance." },
+            { method: "getRunFindings", description: "" },
+            { method: "getMissionRunHistory", description: "" },
+            { method: "getPlanContext", description: "Planning Operations" },
+            { method: "reportStepHints", description: "" },
+            { method: "recordSpan", description: "Distributed Tracing Operations" },
+            { method: "recordSpans", description: "" },
+            { method: "getCredential", description: "Credential Operations" },
+            { method: "getTaxonomySchema", description: "Taxonomy Operations" },
+            { method: "generateNodeID", description: "" },
+            { method: "validateFinding", description: "" },
+            { method: "validateGraphNode", description: "" },
+            { method: "validateRelationship", description: "" },
+            { method: "createMission", description: "Mission Management Operations These enable agents to autonomously create, run, and manage missions" },
+            { method: "runMission", description: "" },
+            { method: "getMissionStatus", description: "" },
+            { method: "waitForMission", description: "" },
+            { method: "listMissions", description: "" },
+            { method: "cancelMission", description: "" },
+            { method: "getMissionResults", description: "" },
+            { method: "authorize", description: "Authorization Operations Authorize checks whether the calling component's current work execution is permitted to perform action on resource. The daemon resolves the run_id to a (user_id, tenant_id) pair and consults FGA." },
+            { method: "workspaceList", description: "WorkspaceList returns metadata for every workspace configured for the calling component's active mission. Returns an empty list when the mission has no workspaces." },
+            { method: "workspaceGetInfo", description: "WorkspaceGetInfo returns name + path for a single workspace. An empty name resolves to the mission's primary workspace (single-repo case). Returns NOT_FOUND when no workspace with that name exists." },
+            { method: "workspaceReadFile", description: "WorkspaceReadFile reads a file from the named workspace. Path is relative to the workspace root. Files larger than 16 MB return RESOURCE_EXHAUSTED; a streaming variant is deferred to a follow-on spec." },
+            { method: "workspaceWriteFile", description: "WorkspaceWriteFile writes content to a file in the named workspace. Path is relative to the workspace root. Content larger than 16 MB returns RESOURCE_EXHAUSTED; a streaming variant is deferred." },
+            { method: "workspaceListFiles", description: "WorkspaceListFiles returns paths matching the given glob pattern, relative to the workspace root. Result sets larger than 10,000 paths are truncated to the first 10,000 with truncated=true on the response." },
+            { method: "workspaceCommit", description: "WorkspaceCommit stages all changes in the workspace and creates a commit with the given message. Returns the commit SHA." },
+            { method: "workspacePush", description: "WorkspacePush pushes committed changes to the remote configured for the workspace. Returns PERMISSION_DENIED on auth failure against the remote." },
+            { method: "devboxExec", description: "DevboxExec runs one command in the caller's session Devbox — a session-lifetime sandbox resolved (and lazily created on first call) by (tenant, session_id), then REUSED across calls in that session. This is deliberately distinct from the per-call SANDBOXED tool path (CallToolProto), which stays one microVM per call; a Devbox holds working state (checkouts, build caches) that per-call isolation would throw away between commands." },
+            { method: "putSessionContext", description: "Session-context store: an opaque, versioned blob per (tenant, session_id), persisted in the per-tenant dataplane store. The daemon never interprets the bytes — the component owns its own format. This is the TRUSTED home for a session's local context; it must never be written to the untrusted Devbox volume (that invariant is the client's to keep, but this store is why keeping it costs nothing). Writes are guarded by an etag (If-Match) so concurrent writers cannot clobber each other; the server enforces a TTL and a size cap." },
+            { method: "getSessionContext", description: "" },
+            { method: "deleteSessionContext", description: "" },
+            { method: "subscribeInput", description: "SubscribeInput streams the inputs for the calling member, in order, across every job it holds. Each Input carries the per-turn grant the member uses for every tool call of that turn. The stream stays open for the life of the member." },
+            { method: "pullJob", description: "PullJob returns the next queued job of the calling member's bank, or nothing when the queue is empty. A member with a free slot calls it after each heartbeat. The daemon assigns the job to the member." },
+            { method: "reportJobState", description: "ReportJobState tells the daemon a job moved to WORKING or WAITING, and names the Claude Code session that holds it so a restart can resume it. A member never reports CLOSED: a scorer closes the job." },
+            { method: "reportDeliverable", description: "ReportDeliverable records one outward result the driver performed at wrap-up: a pushed branch or an opened merge request." },
+            { method: "openJob", description: "OpenJob opens a job on a bank from a dispatched agent, under its grant. It mirrors gibson.job.v1.JobService.OpenJob." },
+            { method: "sendInput", description: "SendInput sends the next message to an open job from a dispatched agent, under its grant. It mirrors gibson.job.v1.JobService.SendInput." },
+            { method: "closeJob", description: "CloseJob closes a job with a verdict and a score from a dispatched agent, under its grant. A verification agent is the usual caller. It mirrors gibson.job.v1.JobService.CloseJob." },
+        ],
+    },
+    {
+        service: IdentityService,
+        description: "IdentityService exposes the \"describe me\" RPC.",
+        methods: [
+            { method: "whoAmI", description: "WhoAmI returns the caller's effective FGA grants. When target_principal_id is set, the caller MUST be tenant_admin on the target's tenant — otherwise the daemon returns PermissionDenied. Identity is derived from ext-authz-emitted headers, never from the request body." },
+        ],
+    },
+    {
+        service: JobService,
+        description: "JobService opens jobs on a bank, sends them input, closes them, and reads them back. People and platform services call it. A dispatched component uses the mirrored OpenJob, SendInput and CloseJob on gibson.harness.v1.HarnessCallbackService under its own grant.",
+        methods: [
+            { method: "openJob", description: "OpenJob opens a job on a bank. The daemon routes it to a member with a free slot, or queues it, or spills it per the bank policy. Set member_id to pin the job to one member of that bank." },
+            { method: "sendInput", description: "SendInput sends the next message to an open job. The daemon mints the per-turn grant and delivers the input to the member that holds the job." },
+            { method: "closeJob", description: "CloseJob closes a job with a verdict and a score. The member runs one wrap-up turn, performs the deliverables, removes the worktrees, and archives the transcript. Only a scorer closes a job: a person, a verification agent, or the job node executor." },
+            { method: "getJob", description: "GetJob returns one job by id." },
+            { method: "listJobs", description: "ListJobs returns jobs of the caller's tenant, newest first. Filter by bank, by member, or by state." },
+            { method: "streamJobEvents", description: "StreamJobEvents follows one job: inputs, state changes, deliverables and the close. The stream starts with the backlog after since_seq, then follows live until the job closes." },
+        ],
+    },
+    {
+        service: PluginInvokeService,
+        description: "PluginInvokeService is the tool-callable RPC for invoking plugin methods. Tools call PluginInvoke; the daemon validates authz, looks up an active plugin install, enqueues a work item via the existing ComponentService PollWork model, awaits SubmitResult, and forwards the result to the tool. Plugin business methods themselves are NOT defined here — the plugin's manifest declares its own method set per the plugin-runtime manifest spec, and the dispatch is by method-name string carried in PluginInvokeRequest.",
+        methods: [
+            { method: "pluginInvoke", description: "PluginInvoke routes a typed invocation to a serving plugin install." },
+        ],
+    },
+    {
+        service: PluginAdminService,
+        description: "PluginAdminService manages plugin installs and their secret bindings.",
+        methods: [
+            { method: "listPluginInstalls", description: "ListPluginInstalls returns all plugin installs for the tenant." },
+            { method: "getPluginInstall", description: "GetPluginInstall returns one install by ID." },
+            { method: "registerPlugin", description: "RegisterPlugin atomically registers a plugin per Spec 2 R3.1: validates manifest, creates the Zitadel plugin_principal SA, writes per-binding FGA can_resolve tuples (creating any inline secrets in the broker), returns the bootstrap token. Any partial failure rolls back all created state." },
+            { method: "editPluginSecretBinding", description: "EditPluginSecretBinding modifies an existing binding (rebind to a different existing secret). Used by the plugin detail page's bindings table." },
+            { method: "revokePluginSecretBinding", description: "RevokePluginSecretBinding removes an FGA can_resolve tuple between the plugin and a secret. Emits a secret_access_revoked audit event." },
+        ],
+    },
+    {
+        service: ToolService,
+        description: "",
+        methods: [
+            { method: "getDescriptor", description: "" },
+            { method: "execute", description: "" },
+            { method: "health", description: "" },
+            { method: "streamExecute", description: "" },
+        ],
+    },
+];
+/** Every RPC of every service, counted at generate time. */
+export const GENERATED_RPC_COUNT = 188;

package/dist/helpers/componentize.d.ts

@@ -0,0 +1,19 @@
+import { type ComponentSpec } from "@zeroroot-ai/sdk";
+import type { ToolDefinition } from "../registry.js";
+import type { HelperContext } from "./context.js";
+export interface SpecArgs {
+    kind: string;
+    name: string;
+    version: string;
+    image?: string;
+    language?: string;
+    capabilities?: string[];
+    methods?: string[];
+    input_message_type?: string;
+    output_message_type?: string;
+    config_schema_json?: string;
+}
+export declare function toSpec(args: SpecArgs): ComponentSpec;
+export declare function componentizeTools(ctx: HelperContext): ToolDefinition[];
+/** Kept exported so a caller can inspect the manifest a spec would produce. */
+export declare function manifestOf(args: SpecArgs): unknown;