@zeroroot-ai/gibson-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,70 @@
+import { createRequire } from "node:module";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+/** The package version, read from package.json beside dist. */
+export function packageVersion() {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const SERVER_NAME = "gibson";
+/**
+ * Bind one MCP protocol server to a transport. Every server reads the same
+ * registry: the stdio path has one, the HTTP path has one per session. A
+ * registry change reaches each attached server as `tools/list_changed`.
+ */
+export async function attachServer(binding, transport) {
+    const resources = binding.resources ?? [];
+    const prompts = binding.prompts ?? [];
+    const server = new Server({ name: SERVER_NAME, version: packageVersion() }, {
+        capabilities: {
+            tools: { listChanged: true },
+            ...(resources.length > 0 ? { resources: {} } : {}),
+            ...(prompts.length > 0 ? { prompts: {} } : {}),
+        },
+        ...(binding.instructions ? { instructions: binding.instructions } : {}),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: binding.registry.list().map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            ...(t.annotations ? { annotations: t.annotations } : {}),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => binding.registry.call(req.params.name, req.params.arguments ?? {}, {
+        headers: extra.requestInfo?.headers,
+        signal: extra.signal,
+    }));
+    if (resources.length > 0) {
+        server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+            resources: resources.map((r) => ({ uri: r.uri, name: r.name, title: r.title, description: r.description, mimeType: r.mimeType })),
+        }));
+        server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+            const resource = resources.find((r) => r.uri === req.params.uri);
+            if (!resource)
+                throw new Error(`no resource ${req.params.uri}`);
+            return { contents: [await resource.read()] };
+        });
+    }
+    if (prompts.length > 0) {
+        server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: prompts.map((p) => ({ name: p.name, title: p.title, description: p.description, arguments: p.arguments })),
+        }));
+        server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+            const prompt = prompts.find((p) => p.name === req.params.name);
+            if (!prompt)
+                throw new Error(`no prompt ${req.params.name}`);
+            return prompt.get(req.params.arguments ?? {});
+        });
+    }
+    const off = binding.registry.onChange(() => {
+        void server.sendToolListChanged().catch(() => { });
+    });
+    server.onclose = () => off();
+    await server.connect(transport);
+    return server;
+}

package/dist/session.d.ts

@@ -0,0 +1,41 @@
+import { connectGibson, openTaskHarness, startLiveMission, type GibsonSession, type KnowledgeSource, type LiveMission, type MissionOriginator } from "@zeroroot-ai/sdk";
+import type { Settings } from "./config.js";
+import { type Log } from "./log.js";
+import { type Mode } from "./mode.js";
+import { type CheckInSource } from "./source.js";
+export { DEFAULT_AGENT_NAME } from "./config.js";
+/** Everything the tools need, decided once per connect. */
+export interface Gibson {
+    source: CheckInSource;
+    mode: Mode;
+    reason: string;
+    agentName: string;
+    hostKeyPath: string;
+    settings: Settings;
+    session?: GibsonSession;
+    live?: LiveMission;
+    knowledge?: KnowledgeSource;
+    /** The mission run this dispatched process belongs to, when the launch named one. */
+    runId?: string;
+    /** Release the mission and the component registration. Idempotent. */
+    close(): Promise<void>;
+}
+export interface OpenGibsonOptions {
+    settings: Settings;
+    log: Log;
+    /** The process environment, for the dispatched-grant contract. */
+    env?: NodeJS.ProcessEnv;
+    /** Test seams. */
+    connect?: typeof connectGibson;
+    start?: typeof startLiveMission;
+    harness?: typeof openTaskHarness;
+    originate?: MissionOriginator;
+    hostKeyExists?: (path: string) => boolean;
+    trust?: (path: string) => Promise<void>;
+}
+/**
+ * Pick the check-in source, check in, then make the session a live mission.
+ * Fails open at every step (ADR-0005): a platform failure lands one posture
+ * down, never in a refusal to start.
+ */
+export declare function openGibson(opts: OpenGibsonOptions): Promise<Gibson>;

package/dist/session.js

@@ -0,0 +1,170 @@
+import { existsSync } from "node:fs";
+import { componentKnowledge, connectGibson, openTaskHarness, SANDBOX_ENV, startLiveMission, taskKnowledge, } from "@zeroroot-ai/sdk";
+import { submitMission } from "./cli.js";
+import { TAG } from "./log.js";
+import { decideMode } from "./mode.js";
+import { decideSource } from "./source.js";
+import { trustCA } from "./tls.js";
+export { DEFAULT_AGENT_NAME } from "./config.js";
+/**
+ * Pick the check-in source, check in, then make the session a live mission.
+ * Fails open at every step (ADR-0005): a platform failure lands one posture
+ * down, never in a refusal to start.
+ */
+export async function openGibson(opts) {
+    const { settings, log } = opts;
+    const env = opts.env ?? {};
+    const { hostKeyPath, agentName } = settings;
+    const hostKeyExists = (opts.hostKeyExists ?? existsSync)(hostKeyPath);
+    const decision = decideSource({
+        grant: env[SANDBOX_ENV.grant],
+        callbackEndpoint: env[SANDBOX_ENV.callbackEndpoint],
+        bootstrapToken: settings.bootstrapToken,
+        hostKeyExists,
+    });
+    for (const note of decision.notes)
+        log(`${TAG} check-in: ${note}`);
+    if (decision.source === "dispatched")
+        return openDispatched(env, settings, log, opts);
+    const source = decision.source;
+    const mode = decideMode({ platformURL: settings.platformURL, bootstrapToken: settings.bootstrapToken, hostKeyExists, targetId: settings.targetId }, hostKeyPath);
+    const standalone = (reason) => ({ source, mode: "standalone", reason, agentName, hostKeyPath, settings, close: async () => { } });
+    if (mode.mode === "standalone") {
+        log(`${TAG} ${source === "none" ? "not checked in" : "standalone"}: ${mode.reason}`);
+        return standalone(mode.reason);
+    }
+    if (settings.caCertPath) {
+        try {
+            await (opts.trust ?? trustCA)(settings.caCertPath);
+        }
+        catch (e) {
+            log(`${TAG} CA at ${settings.caCertPath} not loaded: ${e.message}`);
+        }
+    }
+    // The bootstrap token is passed ONLY when no host key exists yet. Replaying a
+    // one-time token on every start would be rejected (gibson
+    // capabilitygrant_register.go:134-155).
+    const bootstrapToken = source === "bootstrap" ? settings.bootstrapToken : undefined;
+    let session;
+    try {
+        session = await (opts.connect ?? connectGibson)({
+            platformURL: settings.platformURL,
+            daemonURL: settings.daemonURL,
+            bootstrapToken,
+            hostKeyPath,
+            agentName,
+            agentMode: "interactive",
+            agent: { name: agentName, version: "0.0.0", capabilities: ["code"] },
+        });
+    }
+    catch (e) {
+        const reason = `Gibson connect failed: ${e.message}`;
+        log(`${TAG} ${reason}; continuing standalone`);
+        return standalone(reason);
+    }
+    log(`${TAG} checked in via ${source === "bootstrap" ? "the bootstrap token (first check-in)" : "the registered host key"} as ${agentName} (component_scope=${session.componentScope})`);
+    if (source === "bootstrap")
+        log(`${TAG} host key written to ${hostKeyPath}; the bootstrap token is spent`);
+    const component = {
+        source,
+        mode: "component",
+        reason: mode.reason,
+        agentName,
+        hostKeyPath,
+        settings,
+        session,
+        knowledge: componentKnowledge(session.clients.component),
+        close: async () => session.stop(),
+    };
+    if (mode.mode === "component") {
+        log(`${TAG} component posture: ${mode.reason}`);
+        return component;
+    }
+    let live;
+    try {
+        live = await (opts.start ?? startLiveMission)(session, {
+            agentName,
+            targetId: settings.targetId,
+            // The person originates the session mission through the CLI login
+            // session; the component only claims its dispatch (gibson ADR-0063,
+            // ADR-0007 decision 3: one live mission per session).
+            originate: opts.originate ?? ((definition, targetId) => submitMission(definition, targetId, { env, gibsonURL: settings.platformURL, tenant: settings.tenant })),
+            harness: { insecure: settings.callbackInsecure },
+        });
+    }
+    catch (e) {
+        const reason = `live mission failed: ${e.message}`;
+        log(`${TAG} ${reason}; continuing as a component`);
+        return { ...component, reason };
+    }
+    log(`${TAG} live mission ${live.missionId} (work ${live.workId}); reads and writes use the task grant`);
+    let closed = false;
+    return {
+        source,
+        mode: "live",
+        reason: "",
+        agentName,
+        hostKeyPath,
+        settings,
+        session,
+        live,
+        knowledge: taskKnowledge(live.harness),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await live.end({ output: { ended: "session closed" } });
+            }
+            finally {
+                session.stop();
+            }
+        },
+    };
+}
+/**
+ * The dispatched source: the daemon launched this process with a grant and
+ * a callback endpoint. The launch already decided everything; the server
+ * opens the task harness from the grant and serves the tools that run under
+ * it. No host key, no check-in, no mission creation, no state file.
+ *
+ * A grant the harness cannot open still fails open: the process serves
+ * standalone with the reason in `gibson_status`, so the run's log says why
+ * the tools are missing instead of the sandbox dying with no tool surface.
+ */
+async function openDispatched(env, settings, log, opts) {
+    const endpoint = env[SANDBOX_ENV.callbackEndpoint];
+    const token = env[SANDBOX_ENV.grant];
+    const runId = env[SANDBOX_ENV.missionRunId] || undefined;
+    if (settings.caCertPath) {
+        await (opts.trust ?? trustCA)(settings.caCertPath).catch((e) => log(`${TAG} CA not loaded: ${e.message}`));
+    }
+    const base = { source: "dispatched", hostKeyPath: settings.hostKeyPath, settings, ...(runId ? { runId } : {}) };
+    let harness;
+    try {
+        harness = (opts.harness ?? openTaskHarness)({ endpoint, token, insecure: settings.callbackInsecure });
+    }
+    catch (e) {
+        const reason = `dispatched grant unusable: ${e.message}`;
+        log(`${TAG} ${reason}; continuing standalone`);
+        return { ...base, mode: "standalone", reason, agentName: settings.agentName, close: async () => { } };
+    }
+    const missionId = harness.context.missionId;
+    const live = {
+        missionId,
+        workId: runId ?? harness.context.taskId,
+        harness,
+        // The dispatched process reports completion by exiting; the launcher owns the node.
+        end: async () => harness.stop(),
+    };
+    log(`${TAG} dispatched: mission ${missionId}${runId ? ` run ${runId}` : ""} as ${harness.context.agentName}; reads and writes use the dispatch grant`);
+    return {
+        ...base,
+        mode: "task",
+        reason: "",
+        agentName: harness.context.agentName,
+        live,
+        knowledge: taskKnowledge(harness),
+        close: async () => harness.stop(),
+    };
+}

package/dist/source.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The check-in source: how this server gets its credential (gibson#1706,
+ * decision 4). Three, chosen by what is present at start, never mixed.
+ *
+ *  - `dispatched`: the daemon launched the process. `GIBSON_CG_JWT` and
+ *    `GIBSON_CALLBACK_ENDPOINT` are the only credential. The server joins
+ *    the run it was launched for: no enrollment, no state file, no mission.
+ *  - `bootstrap`: a person minted a one-time bootstrap token earlier and this
+ *    host has no key yet. The server checks in unattended with it once, and
+ *    the host key carries every later start.
+ *  - `enrolled`: the host key exists. The server checks in with it.
+ *  - `none`: nothing is present. The server exposes `gibson_login` and
+ *    `gibson_connect`, the device flow through the `gibson` CLI, and a person
+ *    enrolls the host in the session.
+ *
+ * Priority: dispatched wins. The server never mints identity (ADR-0045).
+ */
+export type CheckInSource = "dispatched" | "bootstrap" | "enrolled" | "none";
+export interface SourceInputs {
+    grant?: string;
+    callbackEndpoint?: string;
+    bootstrapToken?: string;
+    hostKeyExists: boolean;
+}
+export interface SourceDecision {
+    source: CheckInSource;
+    /** What was present but ignored, one line each, for the log. */
+    notes: string[];
+}
+export declare function decideSource(i: SourceInputs): SourceDecision;

package/dist/source.js

@@ -0,0 +1,23 @@
+export function decideSource(i) {
+    const notes = [];
+    if (i.grant && i.callbackEndpoint) {
+        if (i.hostKeyExists)
+            notes.push("a host key exists, but the dispatched grant wins; the host key is ignored");
+        if (i.bootstrapToken)
+            notes.push("GIBSON_BOOTSTRAP_TOKEN is set, but the dispatched grant wins; the token is ignored");
+        return { source: "dispatched", notes };
+    }
+    if (i.grant)
+        notes.push("GIBSON_CG_JWT is set without GIBSON_CALLBACK_ENDPOINT; the grant is ignored");
+    if (i.callbackEndpoint)
+        notes.push("GIBSON_CALLBACK_ENDPOINT is set without GIBSON_CG_JWT; the endpoint is ignored");
+    if (i.hostKeyExists) {
+        if (i.bootstrapToken) {
+            notes.push("GIBSON_BOOTSTRAP_TOKEN is set, but this host has a key; the token is ignored (a one-time token cannot be replayed)");
+        }
+        return { source: "enrolled", notes };
+    }
+    if (i.bootstrapToken)
+        return { source: "bootstrap", notes };
+    return { source: "none", notes };
+}

package/dist/state.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The handoff between the MCP server and a host's hook processes.
+ *
+ * A hook runs as a separate process and cannot reach the server's session.
+ * The server writes one small file per working directory: the ambient
+ * knowledge block for a session-start hook, and the live-mission coordinates
+ * for a session-end hook. The files live in the state directory beside the
+ * host key. The task grant in the live file is bounded (30 minutes, renewed
+ * by the server), and a hook that finds a stale one fails open.
+ *
+ * The directory is `~/.zerocool/`, not a per-host subdirectory: the server
+ * is host-agnostic. A dispatched run writes no state file at all.
+ */
+export interface LiveState {
+    missionId: string;
+    workId: string;
+    endpoint: string;
+    token: string;
+    insecure: boolean;
+    /** Unix ms. */
+    writtenAt: number;
+}
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function keyFor(cwd: string): string;
+export declare function writeAmbient(dir: string, cwd: string, block: string): Promise<void>;
+export declare function readAmbient(dir: string, cwd: string): Promise<string>;
+export declare function writeLive(dir: string, cwd: string, state: LiveState): Promise<void>;
+export declare function readLive(dir: string, cwd: string): Promise<LiveState | undefined>;
+export declare function clearLive(dir: string, cwd: string): Promise<void>;

package/dist/state.js

@@ -0,0 +1,37 @@
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+export function stateDir(env = process.env) {
+    return env.ZEROCOOL_STATE_DIR ?? join(homedir(), ".zerocool");
+}
+export function keyFor(cwd) {
+    return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+export async function writeAmbient(dir, cwd, block) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(join(dir, `ambient-${keyFor(cwd)}.md`), block, { encoding: "utf8", mode: 0o600 });
+}
+export async function readAmbient(dir, cwd) {
+    try {
+        return await readFile(join(dir, `ambient-${keyFor(cwd)}.md`), "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+export async function writeLive(dir, cwd, state) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(join(dir, `live-${keyFor(cwd)}.json`), JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
+}
+export async function readLive(dir, cwd) {
+    try {
+        return JSON.parse(await readFile(join(dir, `live-${keyFor(cwd)}.json`), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function clearLive(dir, cwd) {
+    await rm(join(dir, `live-${keyFor(cwd)}.json`), { force: true });
+}

package/dist/tls.d.ts

@@ -0,0 +1 @@
+export declare function trustCA(path: string): Promise<void>;

package/dist/tls.js

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import tls from "node:tls";
+/**
+ * Trust a private CA for every TLS client in this process, at runtime.
+ *
+ * A self-hosted Gibson (kind, on-prem) fronts its edge with its own CA. Node
+ * reads NODE_EXTRA_CA_CERTS only at start, and the connect happens mid-session,
+ * so the CA is added through `tls.setDefaultCACertificates` (Node 22.15+).
+ * Both `fetch` (the Capability Grant register call) and the gRPC transports
+ * use the default CA set, so one call covers all of them.
+ */
+const trusted = new Set();
+export async function trustCA(path) {
+    if (trusted.has(path))
+        return;
+    const pem = await readFile(path, "utf8");
+    tls.setDefaultCACertificates([...tls.getCACertificates("default"), pem]);
+    trusted.add(path);
+}

package/dist/tool.d.ts

@@ -0,0 +1,17 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z, type ZodRawShape } from "zod";
+import type { JsonSchema, ToolAnnotations, ToolContext, ToolDefinition } from "./registry.js";
+/**
+ * A hand-signed tool: a zod shape for the input, a typed handler. The JSON
+ * Schema the host sees is derived from the shape, so a description written
+ * once on a field reaches the model.
+ */
+export interface ToolSpec<S extends ZodRawShape> {
+    name: string;
+    description: string;
+    input: S;
+    annotations?: ToolAnnotations;
+    handler: (args: z.infer<z.ZodObject<S>>, ctx: ToolContext) => Promise<CallToolResult>;
+}
+export declare function jsonSchemaOf(shape: ZodRawShape): JsonSchema;
+export declare function defineTool<S extends ZodRawShape>(spec: ToolSpec<S>): ToolDefinition;

package/dist/tool.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { failure } from "./tools/result.js";
+export function jsonSchemaOf(shape) {
+    const raw = z.toJSONSchema(z.object(shape), { io: "input" });
+    delete raw.$schema;
+    return { ...raw, type: "object" };
+}
+export function defineTool(spec) {
+    const schema = z.object(spec.input);
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: jsonSchemaOf(spec.input),
+        ...(spec.annotations ? { annotations: spec.annotations } : {}),
+        handler: async (raw, ctx) => {
+            const parsed = schema.safeParse(raw);
+            if (!parsed.success)
+                return failure(`${spec.name}: invalid arguments`, z.prettifyError(parsed.error));
+            return spec.handler(parsed.data, ctx);
+        },
+    };
+}

package/dist/tools/connect.d.ts

@@ -0,0 +1,24 @@
+import { type CliOptions } from "../cli.js";
+import type { ToolDefinition } from "../registry.js";
+import { type Gibson, type OpenGibsonOptions } from "../session.js";
+/**
+ * gibson_login and gibson_connect: the in-session path to a platform, for a
+ * host with no key and no token. `gibson_login` starts the CLI device flow
+ * and returns the URL and code. `gibson_connect` enrolls through the CLI
+ * session, trusts the private CA, checks in, picks the target, starts the
+ * live mission and swaps the tool set live. The settings it learns are
+ * persisted, so later sessions connect on their own.
+ */
+export interface ConnectDeps {
+    open?: Pick<OpenGibsonOptions, "connect" | "start" | "hostKeyExists" | "trust" | "harness">;
+    cli?: CliOptions;
+}
+export interface ConnectTarget {
+    current(): Gibson;
+    /** Replace the connection and re-register the posture's tools. */
+    upgrade(next: Gibson): Promise<void>;
+}
+export declare function loginTool(target: ConnectTarget, env: NodeJS.ProcessEnv, deps: ConnectDeps): ToolDefinition;
+export declare function connectTool(target: ConnectTarget, env: NodeJS.ProcessEnv, cwd: string, deps: ConnectDeps): ToolDefinition;
+/** What a coding workspace is, as a URL: its git origin, else the directory. */
+export declare function workspaceURL(cwd: string): Promise<string>;

package/dist/tools/connect.js

@@ -0,0 +1,115 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { createTarget, enrollIdentity, listTargets, startLogin } from "../cli.js";
+import { loadSettings, writeConfig } from "../config.js";
+import { log } from "../log.js";
+import { openGibson } from "../session.js";
+import { defineTool } from "../tool.js";
+import { failure, text } from "./result.js";
+import { describeGibson } from "./status.js";
+export function loginTool(target, env, deps) {
+    return defineTool({
+        name: "gibson_login",
+        description: "Sign in to a Gibson platform as the person running this session. Starts the gibson CLI device " +
+            "flow and returns a URL and a code. The person opens the URL, confirms the code, and then calls " +
+            "gibson_connect. Needed once per host, and again when the login session expires.",
+        input: {
+            platform_url: z.string().optional().describe("Platform URL, e.g. https://api.example.com. Defaults to the last one used."),
+        },
+        handler: async (args) => {
+            const s = target.current().settings;
+            try {
+                const p = await startLogin({ ...deps.cli, env, gibsonURL: args.platform_url ?? s.platformURL });
+                return text("sign in", `Open ${p.url} and confirm the code ${p.code}. The CLI waits for the approval. When it is approved, call gibson_connect.`);
+            }
+            catch (e) {
+                return failure("gibson_login failed", e.message);
+            }
+        },
+    });
+}
+export function connectTool(target, env, cwd, deps) {
+    const cli = (s) => ({ ...deps.cli, env, gibsonURL: s.platformURL, tenant: s.tenant });
+    return defineTool({
+        name: "gibson_connect",
+        description: "Connect this session to a Gibson platform without a restart: enroll this host through the gibson " +
+            "CLI login session if needed, check in, pick the target, start the live mission, and add the " +
+            "platform tools. The settings are kept, so later sessions connect on their own. Call gibson_status afterwards.",
+        input: {
+            platform_url: z.string().optional().describe("Platform URL. Defaults to the gibson CLI login session or the saved config."),
+            target_id: z.string().optional().describe("Target id for the live mission. Defaults to the only target in the tenant."),
+            create_target: z.string().optional().describe("Create a target with this name when none exists, and use it."),
+            target_url: z.string().optional().describe("URL of the target to create. Defaults to the workspace's git origin, or file://<cwd>."),
+            bootstrap_token: z.string().optional().describe("One-time enrollment token. Only when the CLI cannot mint one."),
+            ca_cert_path: z.string().optional().describe("Path to a private CA to trust. Defaults to the CLI session's CA."),
+            callback_insecure: z.boolean().optional().describe("Dial the callback endpoint without TLS. Local daemons only."),
+        },
+        handler: async (args) => {
+            const base = await loadSettings(env);
+            const s = {
+                ...base,
+                platformURL: args.platform_url ?? base.platformURL,
+                targetId: args.target_id ?? base.targetId,
+                caCertPath: args.ca_cert_path ?? base.caCertPath,
+                callbackInsecure: args.callback_insecure ?? base.callbackInsecure,
+                bootstrapToken: args.bootstrap_token ?? base.bootstrapToken,
+            };
+            if (!s.platformURL) {
+                return failure("no platform", "Pass platform_url, or call gibson_login first so the CLI session names the platform.");
+            }
+            const hostKeyExists = (deps.open?.hostKeyExists ?? existsSync)(s.hostKeyPath);
+            try {
+                if (!hostKeyExists && !s.bootstrapToken) {
+                    s.bootstrapToken = await enrollIdentity(s.agentName, cli(s));
+                }
+                if (!s.targetId) {
+                    if (args.create_target) {
+                        s.targetId = await createTarget(args.create_target, args.target_url ?? (await workspaceURL(cwd)), cli(s));
+                    }
+                    else {
+                        const targets = await listTargets(cli(s));
+                        if (targets.length === 1)
+                            s.targetId = targets[0].id;
+                        else if (targets.length === 0) {
+                            return failure("no target", "The tenant has no target. Call gibson_connect again with create_target set to a name for this workspace.");
+                        }
+                        else {
+                            return failure("choose a target", `The tenant has ${targets.length} targets. Call gibson_connect again with target_id:\n${targets.map((t) => `- ${t.id}  ${t.name} (${t.type}, ${t.status})`).join("\n")}`);
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                return failure("gibson_connect failed", e.message);
+            }
+            await writeConfig(env, {
+                platformURL: s.platformURL,
+                targetId: s.targetId,
+                ...(s.caCertPath ? { caCertPath: s.caCertPath } : {}),
+                ...(s.daemonURL ? { daemonURL: s.daemonURL } : {}),
+                callbackInsecure: s.callbackInsecure,
+            });
+            const previous = target.current();
+            await previous.close().catch(() => { });
+            const next = await openGibson({ settings: s, log, env, ...deps.open });
+            await target.upgrade(next);
+            const body = describeGibson(next);
+            return next.mode === "live" ? text("connected", body) : failure("connected, but not live", body);
+        },
+    });
+}
+/** What a coding workspace is, as a URL: its git origin, else the directory. */
+export async function workspaceURL(cwd) {
+    try {
+        const { stdout } = await promisify(execFile)("git", ["-C", cwd, "remote", "get-url", "origin"]);
+        const remote = stdout.trim();
+        if (remote)
+            return remote;
+    }
+    catch {
+        // not a git checkout, or no origin
+    }
+    return `file://${cwd}`;
+}

package/dist/tools/result.d.ts

@@ -0,0 +1,7 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** One text block. MCP has no title/metadata split, so the title leads the text. */
+export declare function text(title: string, body: string, isError?: boolean): CallToolResult;
+/** Error text for a failure the model can act on. */
+export declare function failure(title: string, body: string): CallToolResult;
+/** A JSON document as the one text block, plus the structured copy. */
+export declare function json(value: unknown): CallToolResult;

package/dist/tools/result.js

@@ -0,0 +1,16 @@
+/** One text block. MCP has no title/metadata split, so the title leads the text. */
+export function text(title, body, isError = false) {
+    return { content: [{ type: "text", text: title ? `${title}\n\n${body}` : body }], ...(isError ? { isError } : {}) };
+}
+/** Error text for a failure the model can act on. */
+export function failure(title, body) {
+    return text(title, body, true);
+}
+/** A JSON document as the one text block, plus the structured copy. */
+export function json(value) {
+    const body = JSON.stringify(value, null, 2);
+    return {
+        content: [{ type: "text", text: body }],
+        ...(value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}),
+    };
+}

package/dist/tools/status.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from "../registry.js";
+import type { Gibson } from "../session.js";
+/** One tool that says how this session is connected to Gibson and why. */
+export declare function statusTool(current: () => Gibson): ToolDefinition;
+export declare function describeGibson(g: Gibson): string;