@zeroroot-ai/gibson-mcp 0.1.0

package/dist/helpers/componentize.js

@@ -0,0 +1,106 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildComponentManifest, enrollComponent, enrollmentSupported, validateComponentSpec } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { defineTool } from "../tool.js";
+import { failure, json, text } from "../tools/result.js";
+/** Componentize and enroll: produced artifacts join the fleet. */
+const KINDS = ["agent", "tool", "plugin"];
+const specSchema = {
+    kind: z.enum(KINDS).describe("Component kind."),
+    name: z.string().describe("Component name, as it will appear in the tenant registry."),
+    version: z.string().describe('Semantic version of the artifact, e.g. "0.1.0".'),
+    image: z.string().optional().describe("OCI image reference of the built artifact. Required before it can be dispatched."),
+    language: z.string().optional().describe("Language the artifact is written in, for the catalog."),
+    capabilities: z.array(z.string()).optional().describe('Agent capabilities. Required when kind is "agent".'),
+    methods: z.array(z.string()).optional().describe('Plugin method names. Required when kind is "plugin".'),
+    input_message_type: z.string().optional().describe('Fully-qualified proto input type. Required when kind is "tool".'),
+    output_message_type: z.string().optional().describe('Fully-qualified proto output type. Required when kind is "tool".'),
+    config_schema_json: z.string().optional().describe("JSON Schema for a plugin's configuration."),
+};
+export function toSpec(args) {
+    const metadata = {};
+    if (args.image)
+        metadata.image = args.image;
+    if (args.language)
+        metadata.language = args.language;
+    return {
+        kind: args.kind,
+        name: args.name,
+        version: args.version,
+        metadata,
+        ...(args.capabilities ? { capabilities: args.capabilities } : {}),
+        ...(args.methods ? { methods: args.methods } : {}),
+        ...(args.input_message_type ? { inputMessageType: args.input_message_type } : {}),
+        ...(args.output_message_type ? { outputMessageType: args.output_message_type } : {}),
+        ...(args.config_schema_json ? { configSchemaJson: args.config_schema_json } : {}),
+    };
+}
+function invalid(spec, problems) {
+    return failure("invalid component spec", `This artifact does not satisfy Gibson's ${spec.kind} contract:\n${problems.map((p) => `- ${p}`).join("\n")}`);
+}
+export function componentizeTools(ctx) {
+    const out = [
+        defineTool({
+            name: "validate_component",
+            description: "Check an artifact against Gibson's component contract without writing anything. Names every problem it finds.",
+            input: specSchema,
+            annotations: { readOnlyHint: true },
+            handler: async (args) => {
+                const spec = toSpec(args);
+                const problems = validateComponentSpec(spec);
+                if (problems.length > 0)
+                    return invalid(spec, problems);
+                return text("valid", `${spec.kind} ${spec.name}@${spec.version} satisfies the component contract.`);
+            },
+        }),
+        defineTool({
+            name: "componentize",
+            description: "Turn a built artifact into a Gibson component manifest and write it to disk. Use this after " +
+                "building a tool or agent you want to add to the fleet. Validates the artifact against " +
+                "Gibson's component contract. Does not build or push an image.",
+            input: { ...specSchema, path: z.string().optional().describe('Where to write the manifest. Defaults to "gibson-component.json".') },
+            handler: async (args) => {
+                const spec = toSpec(args);
+                const problems = validateComponentSpec(spec);
+                if (problems.length > 0)
+                    return invalid(spec, problems);
+                const manifest = buildComponentManifest(spec);
+                const target = resolve(ctx.cwd, args.path ?? "gibson-component.json");
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+                const missingImage = spec.metadata?.image
+                    ? ""
+                    : "\n\nNo image reference was given. Build and push an image, then re-run with image=<oci-ref> before you enroll. A component without an image cannot be dispatched.";
+                return text(`${spec.kind} manifest: ${spec.name}`, `Wrote a valid ${spec.kind} manifest for ${spec.name}@${spec.version} to ${target}.${missingImage}`);
+            },
+        }),
+    ];
+    if (ctx.gibson.session) {
+        const component = ctx.gibson.session.clients.component;
+        out.push(defineTool({
+            name: "enroll_component",
+            description: "Register a produced artifact with Gibson so it joins the tenant fleet. Run componentize first to check the artifact against the component contract.",
+            input: specSchema,
+            handler: async (args) => {
+                const spec = toSpec(args);
+                const problems = validateComponentSpec(spec);
+                if (problems.length > 0)
+                    return invalid(spec, problems);
+                try {
+                    const result = await enrollComponent(component, spec);
+                    const { reason } = enrollmentSupported();
+                    return text(`enrolled ${spec.name}`, `Registered ${spec.kind} ${spec.name}@${spec.version} as instance ${result.instanceId}.\n\nNote: ${reason}. It is visible in the tenant registry, but it drops out when heartbeats stop (every ${Math.round(result.heartbeatIntervalMs / 1000)}s) unless the artifact itself runs and checks in.`);
+                }
+                catch (e) {
+                    return failure("enroll failed", e.message);
+                }
+            },
+        }));
+    }
+    return out;
+}
+/** Kept exported so a caller can inspect the manifest a spec would produce. */
+export function manifestOf(args) {
+    return json(buildComponentManifest(toSpec(args)));
+}

package/dist/helpers/context.d.ts

@@ -0,0 +1,19 @@
+import type { Gibson } from "../session.js";
+import type { FindingsBackend } from "./findings.js";
+/** What every helper tool is built from. Decided once per posture. */
+export interface HelperContext {
+    gibson: Gibson;
+    /** The working directory a componentize writes into. */
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Where a finding lands in this posture. */
+    findings: FindingsBackend;
+}
+export declare function helperContext(gibson: Gibson, cwd: string, env: NodeJS.ProcessEnv): HelperContext;
+/**
+ * A finding always has somewhere to go. Under a task grant it is the typed
+ * callback RPC; as a checked-in component it is ComponentService; with no
+ * platform it is a local JSONL log, so a standalone session still records
+ * what it found instead of dropping it.
+ */
+export declare function findingsBackendFor(gibson: Gibson, env: NodeJS.ProcessEnv): FindingsBackend;

package/dist/helpers/context.js

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { gibsonFindingsBackend, localFindingsBackend, taskFindingsBackend } from "./findings.js";
+export function helperContext(gibson, cwd, env) {
+    return { gibson, cwd, env, findings: findingsBackendFor(gibson, env) };
+}
+/**
+ * A finding always has somewhere to go. Under a task grant it is the typed
+ * callback RPC; as a checked-in component it is ComponentService; with no
+ * platform it is a local JSONL log, so a standalone session still records
+ * what it found instead of dropping it.
+ */
+export function findingsBackendFor(gibson, env) {
+    if (gibson.live)
+        return taskFindingsBackend(gibson.live.harness);
+    if (gibson.session)
+        return gibsonFindingsBackend(gibson.session);
+    return localFindingsBackend(env.ZEROCOOL_FINDINGS_LOG ?? join(homedir(), ".zerocool", "findings.jsonl"));
+}

package/dist/helpers/coverage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which SDK export each helper tool comes from, and why the rest are not
+ * tools.
+ *
+ * The MCP surface is 1:1 with everything the SDK produces (gibson#1706,
+ * decision 2). The RPC half is generated, so it cannot fall behind. The
+ * helper half is hand-signed, so this table is what keeps it honest: a guard
+ * test lists the SDK's exports and fails when one is in neither map, which
+ * means a new helper cannot land in the SDK without a decision here.
+ *
+ * A reason is required, not optional. "Not a tool" with no reason is how a
+ * surface quietly loses half of itself.
+ */
+/** SDK export -> the tool built on it. Several exports may back one tool. */
+export declare const HELPER_TOOL_FOR_EXPORT: Record<string, string>;
+/** SDK export -> why it is not a tool. */
+export declare const NOT_A_TOOL: Record<string, string>;
+/**
+ * Tools with no single SDK export behind them, and where they come from.
+ * The guard walks this direction too, so a tool cannot appear with no
+ * account of itself.
+ */
+export declare const TOOL_WITHOUT_EXPORT: Record<string, string>;

package/dist/helpers/coverage.js

@@ -0,0 +1,119 @@
+/**
+ * Which SDK export each helper tool comes from, and why the rest are not
+ * tools.
+ *
+ * The MCP surface is 1:1 with everything the SDK produces (gibson#1706,
+ * decision 2). The RPC half is generated, so it cannot fall behind. The
+ * helper half is hand-signed, so this table is what keeps it honest: a guard
+ * test lists the SDK's exports and fails when one is in neither map, which
+ * means a new helper cannot land in the SDK without a decision here.
+ *
+ * A reason is required, not optional. "Not a tool" with no reason is how a
+ * surface quietly loses half of itself.
+ */
+/** SDK export -> the tool built on it. Several exports may back one tool. */
+export const HELPER_TOOL_FOR_EXPORT = {
+    buildComponentManifest: "componentize",
+    callGibsonTool: "gibson_call_tool",
+    cancelMission: "cancel_mission",
+    createMission: "create_mission",
+    createTaskMission: "create_task_mission",
+    delegateToAgent: "delegate",
+    enrollComponent: "enroll_component",
+    findSimilarAttacks: "similar_attacks",
+    findSimilarFindings: "similar_findings",
+    getAttackChains: "attack_chains",
+    getFindings: "get_findings",
+    getMissionResults: "mission_results",
+    getMissionStatus: "mission_status",
+    getRelatedFindings: "related_findings",
+    listAgents: "list_agents",
+    listGibsonPlugins: "list_gibson_plugins",
+    listGibsonTools: "list_gibson_tools",
+    listMissions: "list_missions",
+    newFinding: "submit_finding",
+    observe: "observe",
+    parseMaybeJSON: "parse_gibson_output",
+    queryGibsonPlugin: "query_plugin",
+    queryKnowledge: "recall",
+    remember: "remember",
+    runMission: "run_mission",
+    submitFinding: "submit_finding",
+    validateComponentSpec: "validate_component",
+    waitMission: "wait_mission",
+};
+/** SDK export -> why it is not a tool. */
+export const NOT_A_TOOL = {
+    // Check-in and identity. The source is decided at start and the server
+    // never mints identity (ADR-0045), so no tool may reach these.
+    CapabilityGrantClient: "the check-in client; the credential source is decided at start, never by a tool",
+    connectGibson: "the check-in itself, done once at start",
+    createGibsonClients: "builds the service clients at start",
+    discover: "reads the platform discovery document at check-in",
+    generateAgentKey: "key material; the server never mints identity (ADR-0045)",
+    jwkThumbprint: "key material",
+    loadOrGenerateHostKey: "key material",
+    publicKeyJWK: "key material",
+    signAgentJWT: "key material",
+    signHostJWT: "key material",
+    registerAgent: "registers the component at check-in, before any tool exists",
+    registerComponentAs: "registers the component at check-in, before any tool exists",
+    registerInstance: "registers this process as one instance at check-in",
+    startHeartbeat: "the check-in keeps its own registration alive",
+    normalizePlatformURL: "canonicalizes the platform URL at check-in",
+    // Transport and grant plumbing. Every tool call already rides these.
+    callbackBaseUrl: "turns a dial target into a base URL at start",
+    contextFromGrant: "derives ContextInfo from the grant; every tool call already carries it",
+    decodeGrantClaims: "reads the addressing claims off the grant at start",
+    grantInterceptor: "puts the current grant on every request",
+    openTaskHarness: "opens the callback transport at start",
+    sandboxHarness: "opens a dispatched run's harness at start",
+    sessionHarness: "the component-grant harness, chosen at start",
+    readSandboxDispatch: "reads the dispatch contract off the environment at start",
+    taskFromB64: "decodes the dispatched task at start",
+    taskKnowledge: "chooses which grant recall reads over",
+    componentKnowledge: "chooses which grant recall reads over",
+    // The session mission is started by the check-in, not by a tool
+    // (ADR-0007 decision 3: one live mission per session).
+    componentOriginator: "who creates the session mission; decided at check-in",
+    liveMissionDefinition: "the definition the session mission is created from at start",
+    startLiveMission: "starts the session mission at check-in",
+    // Serving work. This server is a client of the platform, not a worker.
+    startWorker: "a served tool's own poll loop; this server serves no work",
+    startAgentWorker: "a served agent's own poll loop; this server serves no work",
+    decodeAgentExecute: "decodes a work payload inside a worker loop",
+    decodeToolInput: "decodes a work payload inside a worker loop",
+    encodeAgentError: "encodes a worker's result",
+    encodeAgentResult: "encodes a worker's result",
+    encodeToolError: "encodes a worker's result",
+    encodeToolOutput: "encodes a worker's result",
+    // The model stays on the host's own provider (ADR-0007). The LLM shim is
+    // the opencode adapter's business and never a tool.
+    startCompletionsShim: "the local OpenAI-compatible shim; a host adapter starts it, and the model never routes through this server",
+    // Encoding and formatting the tools already do for the caller.
+    calculateRiskScore: "arithmetic on a severity and a confidence; no round trip is worth it",
+    decodeJSONBytes: "byte decoding inside other helpers",
+    decodeProperties: "decodes a graph property bag inside recall",
+    decodeValue: "decodes one graph value inside recall",
+    encodeFinding: "submit_finding encodes the finding for you",
+    formatKnowledgeForPrompt: "recall already formats its own hits",
+    validateFinding: "submit_finding validates before it submits",
+    newTask: "builds delegate's argument",
+    buildCreateMissionRequest: "shapes the request create_task_mission sends",
+    enrollmentSupported: "a fixed explanation, printed in enroll_component's answer",
+    isSeamUnavailable: "classifies a daemon error inside other helpers",
+    seamReason: "reads the daemon's own explanation inside other helpers",
+};
+/**
+ * Tools with no single SDK export behind them, and where they come from.
+ * The guard walks this direction too, so a tool cannot appear with no
+ * account of itself.
+ */
+export const TOOL_WITHOUT_EXPORT = {
+    world_view: "HarnessCallbackService.WorldView through the task harness, formatted for reading",
+    run_history: "KnowledgeSource.runHistory, which is an interface method rather than a free function",
+    application_findings: "KnowledgeSource.applicationFindings, which is an interface method rather than a free function",
+    gibson_status: "the server's own posture, which is not an SDK concept",
+    gibson_login: "the gibson CLI device flow",
+    gibson_connect: "the gibson CLI enrollment and the check-in, driven in the session",
+};

package/dist/helpers/delegate.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../registry.js";
+import type { HelperContext } from "./context.js";
+/** Delegation and missions: the network of agents in the tenant. */
+export declare function delegationTools(ctx: HelperContext): ToolDefinition[];

package/dist/helpers/delegate.js

@@ -0,0 +1,182 @@
+import { cancelMission, createMission, createTaskMission, delegateToAgent, getMissionResults, getMissionStatus, isSeamUnavailable, listAgents, listMissions, newTask, runMission, waitMission, } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { defineTool } from "../tool.js";
+import { failure, json, text } from "../tools/result.js";
+const UNWIRED = "This daemon has no agent delegation or mission management wired (gibson#1186). Complete the work directly instead.";
+/** Delegation and missions: the network of agents in the tenant. */
+export function delegationTools(ctx) {
+    const out = [];
+    const live = ctx.gibson.live;
+    if (live) {
+        out.push(defineTool({
+            name: "create_task_mission",
+            description: "Originate a mission from the tenant's checked-in catalog, by name, from inside this run. " +
+                "Use it to start a named piece of platform work; use delegate for a one-off task.",
+            input: {
+                name: z.string().describe("Catalog mission name."),
+                target_id: z.string().optional().describe("Target the mission binds to. Defaults to this run's target."),
+                params: z.record(z.string(), z.string()).optional().describe("Catalog parameters, by name."),
+                metadata: z.record(z.string(), z.unknown()).optional().describe("Free-form metadata recorded on the mission."),
+            },
+            handler: async (args) => {
+                try {
+                    return json(await createTaskMission(live.harness, {
+                        name: args.name,
+                        ...(args.target_id ? { targetId: args.target_id } : {}),
+                        ...(args.params ? { catalogParams: args.params } : {}),
+                        ...(args.metadata ? { metadata: args.metadata } : {}),
+                    }));
+                }
+                catch (e) {
+                    return failure("create_task_mission failed", e.message);
+                }
+            },
+        }));
+    }
+    if (!ctx.gibson.session)
+        return out;
+    const component = ctx.gibson.session.clients.component;
+    const seam = (e, what) => (isSeamUnavailable(e) ? text(`${what} unavailable`, UNWIRED) : failure(`${what} failed`, e.message));
+    out.push(defineTool({
+        name: "list_agents",
+        description: "List the Gibson agents in this tenant that work can be delegated to, with their capabilities and the target types they handle.",
+        input: {},
+        annotations: { readOnlyHint: true },
+        handler: async () => {
+            const { agents, unavailable } = await listAgents(component);
+            if (unavailable)
+                return text("delegation unavailable", UNWIRED);
+            if (agents.length === 0)
+                return text("no agents", "No agents are registered for this tenant.");
+            const lines = agents.map((a) => {
+                const caps = a.capabilities.length > 0 ? `, capabilities: ${a.capabilities.join(", ")}` : "";
+                const targets = a.targetTypes.length > 0 ? `, targets: ${a.targetTypes.join(", ")}` : "";
+                return `- ${a.name} (${a.version}) ${a.description}${caps}${targets}`;
+            });
+            return text(`${agents.length} agent${agents.length === 1 ? "" : "s"}`, lines.join("\n"));
+        },
+    }), defineTool({
+        name: "delegate",
+        description: "Delegate a sub-task to another Gibson agent and wait for its result. Use list_agents " +
+            "first to pick an agent whose capabilities match the task.",
+        input: {
+            agent: z.string().describe("Name of the agent to delegate to."),
+            goal: z.string().describe("What the delegate should accomplish."),
+            context: z.record(z.string(), z.unknown()).optional().describe("Target details, prior findings, or other context the delegate needs."),
+            max_turns: z.number().int().min(1).optional().describe("Cap on the delegate's LLM turns."),
+            allowed_tools: z.array(z.string()).optional().describe("Restrict the delegate to these tools."),
+        },
+        handler: async (args) => {
+            try {
+                const task = newTask(args.goal, {
+                    ...(args.context ? { Context: args.context } : {}),
+                    ...(args.max_turns || args.allowed_tools
+                        ? { Constraints: { ...(args.max_turns ? { MaxTurns: args.max_turns } : {}), ...(args.allowed_tools ? { AllowedTools: args.allowed_tools } : {}) } }
+                        : {}),
+                });
+                const result = await delegateToAgent(component, args.agent, task);
+                return text(`${args.agent}: ${result.Status}`, JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return seam(e, "delegation");
+            }
+        },
+    }), defineTool({
+        name: "create_mission",
+        description: "Create a Gibson mission from a mission definition, bound to a target. The mission is not started; call run_mission to queue it.",
+        input: {
+            definition: z.record(z.string(), z.unknown()).describe("Mission definition object (gibson.mission.v1.MissionDefinition as JSON)."),
+            target_id: z.string().describe("Identifier of the target the mission runs against."),
+            opts: z.record(z.string(), z.unknown()).optional().describe("Optional mission creation options."),
+        },
+        handler: async (args) => {
+            try {
+                return json(await createMission(component, args.definition, args.target_id, args.opts));
+            }
+            catch (e) {
+                return seam(e, "create mission");
+            }
+        },
+    }), defineTool({
+        name: "run_mission",
+        description: "Queue a created Gibson mission for execution. Returns as soon as it is queued.",
+        input: { mission_id: z.string().describe("Mission to run.") },
+        handler: async (args) => {
+            try {
+                await runMission(component, args.mission_id);
+                return text("queued", `Mission ${args.mission_id} is queued.`);
+            }
+            catch (e) {
+                return seam(e, "run mission");
+            }
+        },
+    }), defineTool({
+        name: "mission_status",
+        description: "Check a Gibson mission's status.",
+        input: { mission_id: z.string().describe("Mission to inspect.") },
+        annotations: { readOnlyHint: true },
+        handler: async (args) => {
+            try {
+                return json(await getMissionStatus(component, args.mission_id));
+            }
+            catch (e) {
+                return seam(e, "mission status");
+            }
+        },
+    }), defineTool({
+        name: "wait_mission",
+        description: "Block until a Gibson mission reaches a terminal state. Use it only when you intend to stop and wait for the result.",
+        input: {
+            mission_id: z.string().describe("Mission to wait for."),
+            timeout_ms: z.number().int().min(1).optional().describe("How long to block. Defaults to 5 minutes."),
+        },
+        handler: async (args) => {
+            try {
+                return json(await waitMission(component, args.mission_id, args.timeout_ms));
+            }
+            catch (e) {
+                return seam(e, "wait mission");
+            }
+        },
+    }), defineTool({
+        name: "mission_results",
+        description: "Read the final results of a completed Gibson mission.",
+        input: { mission_id: z.string().describe("Mission whose results to read.") },
+        annotations: { readOnlyHint: true },
+        handler: async (args) => {
+            try {
+                return json(await getMissionResults(component, args.mission_id));
+            }
+            catch (e) {
+                return seam(e, "mission results");
+            }
+        },
+    }), defineTool({
+        name: "cancel_mission",
+        description: "Request cancellation of a running Gibson mission.",
+        input: { mission_id: z.string().describe("Mission to cancel.") },
+        handler: async (args) => {
+            try {
+                await cancelMission(component, args.mission_id);
+                return text("cancel requested", `Cancellation of ${args.mission_id} is requested.`);
+            }
+            catch (e) {
+                return seam(e, "cancel mission");
+            }
+        },
+    }), defineTool({
+        name: "list_missions",
+        description: "List this tenant's missions, optionally filtered.",
+        input: { filter: z.record(z.string(), z.unknown()).optional().describe("Equality filters on mission fields.") },
+        annotations: { readOnlyHint: true },
+        handler: async (args) => {
+            try {
+                return json(await listMissions(component, args.filter ?? {}));
+            }
+            catch (e) {
+                return seam(e, "list missions");
+            }
+        },
+    }));
+    return out;
+}

package/dist/helpers/findings.d.ts

@@ -0,0 +1,24 @@
+import { type Finding, type GibsonSession, type TaskHarness } from "@zeroroot-ai/sdk";
+import type { ToolDefinition } from "../registry.js";
+import type { HelperContext } from "./context.js";
+export interface FindingsBackend {
+    submit(f: Finding): Promise<string>;
+    describe(): string;
+}
+/** Platform backend: the finding lands in the tenant knowledge graph. */
+export declare function gibsonFindingsBackend(session: GibsonSession): FindingsBackend;
+/**
+ * Task backend: the callback service's typed SubmitFinding, under the
+ * dispatch grant. Fields map from the SDK's JSON finding onto
+ * gibson.types.v1.Finding; the daemon assigns the id and the mission.
+ */
+export declare function taskFindingsBackend(harness: TaskHarness): FindingsBackend;
+/** Standalone backend: an append-only JSONL log. */
+export declare function localFindingsBackend(path: string): FindingsBackend;
+/**
+ * Findings: emit what the agent discovers. The model calls this when it
+ * finds something. Nothing here emits on its own: a file edit is not a
+ * security finding, and inventing one fills the tenant graph with noise a
+ * person then has to triage.
+ */
+export declare function findingTools(ctx: HelperContext): ToolDefinition[];

package/dist/helpers/findings.js

@@ -0,0 +1,118 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getFindings, newFinding, submitFinding } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { defineTool } from "../tool.js";
+import { failure, json, text } from "../tools/result.js";
+const SEVERITIES = ["critical", "high", "medium", "low", "info"];
+/** Platform backend: the finding lands in the tenant knowledge graph. */
+export function gibsonFindingsBackend(session) {
+    return { submit: (f) => submitFinding(session.clients.component, f), describe: () => "the tenant Gibson graph" };
+}
+/**
+ * Task backend: the callback service's typed SubmitFinding, under the
+ * dispatch grant. Fields map from the SDK's JSON finding onto
+ * gibson.types.v1.Finding; the daemon assigns the id and the mission.
+ */
+export function taskFindingsBackend(harness) {
+    const severity = (s) => ({ critical: 1, high: 2, medium: 3, low: 4, info: 5 })[s] ?? 0;
+    return {
+        submit: async (f) => {
+            const res = await harness.client.submitFinding({
+                context: harness.context,
+                finding: {
+                    id: f.id,
+                    missionId: f.mission_id,
+                    agentName: f.agent_name,
+                    title: f.title,
+                    description: f.description,
+                    category: f.category,
+                    severity: severity(f.severity),
+                    confidence: f.confidence,
+                    remediation: f.remediation ?? "",
+                    targetId: f.target_id ?? "",
+                    tags: f.tags ?? [],
+                    evidence: (f.evidence ?? []).map((e) => ({ type: e.type, title: e.title, content: e.content })),
+                },
+            });
+            if (res.error)
+                throw new Error(`SubmitFinding refused: ${res.error.message}`);
+            // The callback acknowledges without an id; the finding keeps the one
+            // newFinding minted, which is what the daemon stored.
+            return f.id;
+        },
+        describe: () => "the tenant Gibson graph (dispatch grant)",
+    };
+}
+/** Standalone backend: an append-only JSONL log. */
+export function localFindingsBackend(path) {
+    return {
+        submit: async (f) => {
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, `${JSON.stringify(f)}\n`, "utf8");
+            return f.id;
+        },
+        describe: () => path,
+    };
+}
+/**
+ * Findings: emit what the agent discovers. The model calls this when it
+ * finds something. Nothing here emits on its own: a file edit is not a
+ * security finding, and inventing one fills the tenant graph with noise a
+ * person then has to triage.
+ */
+export function findingTools(ctx) {
+    const out = [
+        defineTool({
+            name: "submit_finding",
+            description: "Record a security finding in the Gibson knowledge graph. Use this when you discover a " +
+                "real vulnerability, misconfiguration or notable security fact about the target or " +
+                "codebase. Not for progress updates or general observations.",
+            input: {
+                title: z.string().describe("One-line summary of the finding."),
+                description: z.string().describe("What the issue is, where it is, and why it matters."),
+                category: z.string().describe('Type of issue, e.g. "injection", "auth", "secrets-exposure", "misconfiguration".'),
+                severity: z.enum(SEVERITIES).describe("Impact level of the finding."),
+                confidence: z.number().min(0).max(1).optional().describe("How certain you are, from 0 to 1. Defaults to 1."),
+                evidence: z.string().optional().describe("A code excerpt, request/response, or log line."),
+                remediation: z.string().optional().describe("How to fix or mitigate the issue."),
+                target_id: z.string().optional().describe("Identifier of the affected target or component."),
+                tags: z.array(z.string()).optional().describe("Labels for filtering."),
+            },
+            handler: async (args) => {
+                const finding = newFinding({
+                    title: args.title,
+                    description: args.description,
+                    category: args.category,
+                    severity: args.severity,
+                    confidence: args.confidence,
+                    missionID: ctx.gibson.live?.missionId ?? "",
+                    agentName: ctx.gibson.agentName,
+                    ...(args.remediation ? { remediation: args.remediation } : {}),
+                    ...(args.target_id ? { targetID: args.target_id } : {}),
+                    ...(args.tags ? { tags: args.tags } : {}),
+                    ...(args.evidence ? { evidence: [{ type: "text", title: "evidence", content: args.evidence, timestamp: new Date().toISOString() }] } : {}),
+                });
+                try {
+                    const id = await ctx.findings.submit(finding);
+                    return text(`${args.severity}: ${args.title}`, `Recorded finding ${id} in ${ctx.findings.describe()}.`);
+                }
+                catch (e) {
+                    return failure("submit_finding failed", e.message);
+                }
+            },
+        }),
+    ];
+    if (ctx.gibson.session) {
+        const component = ctx.gibson.session.clients.component;
+        out.push(defineTool({
+            name: "get_findings",
+            description: "Read findings already recorded in this tenant's Gibson graph. Filter by any field the " +
+                "finding carries, for example mission_id, severity, category or target_id.",
+            input: { filter: z.record(z.string(), z.unknown()).optional().describe("Equality filters on finding fields. Omit for every finding the caller may read.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await getFindings(component, args.filter ?? {})),
+        }));
+    }
+    return out;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,17 @@
+import type { ToolDefinition } from "../registry.js";
+import type { Gibson } from "../session.js";
+import { type HelperContext } from "./context.js";
+export * from "./context.js";
+export * from "./coverage.js";
+export { componentizeTools } from "./componentize.js";
+export { delegationTools } from "./delegate.js";
+export { findingTools, gibsonFindingsBackend, localFindingsBackend, taskFindingsBackend, type FindingsBackend } from "./findings.js";
+export { knowledgeTools } from "./knowledge.js";
+export { platformToolHelpers } from "./tools.js";
+/**
+ * One tool per SDK helper (gibson#1706, decision 2), for whatever this
+ * posture can reach. A helper whose grant is absent registers no tool
+ * rather than a tool that always fails.
+ */
+export declare function helperTools(ctx: HelperContext): ToolDefinition[];
+export declare function helperToolsFor(gibson: Gibson, cwd: string, env: NodeJS.ProcessEnv): ToolDefinition[];