@honua/mcp-server 0.2.3 → 0.2.4

package/dist/src/agent/gateway.d.ts

@@ -0,0 +1,58 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { DevOpsExtension } from "./devops-runtime.js";
+import type { AgentConnection, AgentRuntime } from "./local-runtime.js";
+export type UpstreamFactory = (connection: AgentConnection, view?: string) => Promise<Client>;
+/** A gateway owns initialization; it does not impersonate the downstream client. */
+export declare function connectAgentUpstream(connection: AgentConnection, view?: string, fetchImpl?: typeof fetch): Promise<Client>;
+/** One configured installation per process. Target changes require an explicit host restart. */
+export declare class HonuaAgentGateway {
+    #private;
+    private readonly runtime;
+    private readonly upstream;
+    private readonly devops?;
+    private readonly options;
+    readonly server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    constructor(runtime: AgentRuntime, upstream?: UpstreamFactory, devops?: DevOpsExtension | undefined, options?: {
+        bootstrapTools?: boolean;
+    });
+    connect(transport: Transport): Promise<void>;
+    close(): Promise<void>;
+    /** Native HTTP discovery must not race the external connector's background attachment. */
+    prepare(view?: string): Promise<void>;
+}
+//# sourceMappingURL=gateway.d.ts.map

package/dist/src/agent/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../src/agent/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AA4B/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAC;AA0DrF,MAAM,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9F,oFAAoF;AACpF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,eAAe,EAC3B,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAMD,gGAAgG;AAChG,qBAAa,iBAAiB;;IAgB1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAlB1B,QAAQ,CAAC,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAKb;gBAUiB,OAAO,EAAE,YAAY,EACrB,QAAQ,GAAE,eAAsC,EAChD,MAAM,CAAC,EAAE,eAAe,YAAA,EACxB,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO;IAwGvD,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAqD5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,0FAA0F;IACpF,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAuH5C"}

package/dist/src/agent/gateway.js

@@ -0,0 +1,381 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, CallToolResultSchema, ErrorCode, GetPromptRequestSchema, GetPromptResultSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListPromptsResultSchema, ListResourceTemplatesRequestSchema, ListResourceTemplatesResultSchema, ListResourcesRequestSchema, ListResourcesResultSchema, ListToolsRequestSchema, ListToolsResultSchema, McpError, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ReadResourceResultSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { SERVER_VERSION } from "../index.js";
+import { WORKFLOW_VIEW_META_KEY, buildUpstreamHeaders, readWorkflowView } from "../proxy.js";
+import { WORKFLOW_KNOWLEDGE, WORKFLOW_KNOWLEDGE_URI } from "./workflow-knowledge.js";
+const PREFIX = "honua_agent_";
+const DEVOPS_PREFIX = "honua_agent_devops_";
+const knowledgeResource = {
+    uri: WORKFLOW_KNOWLEDGE_URI,
+    name: "Honua conversational GIS workflows v1",
+    description: "Versioned workflow semantics and evidence requirements; canonical tools remain authoritative.",
+    mimeType: "application/json",
+};
+const installInput = z
+    .object({
+    confirm: z.literal(true),
+    profile: z.enum(["quickstart", "gp-dev"]).default("quickstart"),
+    httpPort: z.number().int().min(1).max(65535).default(8080),
+})
+    .strict();
+const emptyInput = z.object({}).strict();
+const emptySchema = { type: "object", properties: {}, additionalProperties: false };
+const localTools = [
+    {
+        name: `${PREFIX}status`,
+        description: "Read this connector's verified target and handoff state. No credentials are returned.",
+        inputSchema: emptySchema,
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: `${PREFIX}inspect_local`,
+        description: "Inspect Docker prerequisites on this host without creating an installation.",
+        inputSchema: emptySchema,
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: `${PREFIX}connect`,
+        description: "Verify and attach the host-configured existing local installation. Replaces no active target and executes no GIS mutation.",
+        inputSchema: emptySchema,
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: `${PREFIX}install_local`,
+        description: "Install Honua into the host-configured directory, then verify authentication and attach its MCP catalog. Requires explicit installation authorization; returns no secrets.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                confirm: { const: true, type: "boolean" },
+                profile: { type: "string", enum: ["quickstart", "gp-dev"], default: "quickstart" },
+                httpPort: { type: "integer", minimum: 1, maximum: 65535, default: 8080 },
+            },
+            required: ["confirm"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+    },
+];
+/** A gateway owns initialization; it does not impersonate the downstream client. */
+export async function connectAgentUpstream(connection, view, fetchImpl) {
+    const headers = buildUpstreamHeaders(connection.transport);
+    const transport = new StreamableHTTPClientTransport(new URL(connection.transport.remoteUrl), {
+        requestInit: { headers, redirect: "manual" },
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+    const send = transport.send.bind(transport);
+    transport.send = (message, options) => {
+        if ("method" in message && message.method === "initialize" && view) {
+            return send({ ...message, params: { ...message.params, _meta: { [WORKFLOW_VIEW_META_KEY]: view } } }, options);
+        }
+        return send(message, options);
+    };
+    const client = new Client({ name: "honua-agent-gateway", version: SERVER_VERSION }, { capabilities: {} });
+    try {
+        await client.connect(transport);
+        return client;
+    }
+    catch {
+        await client.close().catch(() => { });
+        throw new Error("Upstream connection failed");
+    }
+}
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value };
+}
+/** One configured installation per process. Target changes require an explicit host restart. */
+export class HonuaAgentGateway {
+    runtime;
+    upstream;
+    devops;
+    options;
+    server = new Server({ name: "honua-agent", version: SERVER_VERSION }, {
+        capabilities: { tools: { listChanged: true }, resources: { listChanged: true }, prompts: { listChanged: true } },
+    });
+    #client;
+    #target;
+    #view;
+    #transition = false;
+    #active = 0;
+    #initialized = false;
+    #closed = false;
+    constructor(runtime, upstream = connectAgentUpstream, devops, options = {}) {
+        this.runtime = runtime;
+        this.upstream = upstream;
+        this.devops = devops;
+        this.options = options;
+        this.server.oninitialized = () => {
+            this.#initialized = true;
+            void this.#attach().catch(() => { });
+        };
+        this.server.onclose = () => {
+            this.#closed = true;
+            void this.#client?.close().catch(() => { });
+            void this.devops?.close().catch(() => { });
+        };
+        // Never log transport errors: HTTP error bodies can contain credentials.
+        this.server.onerror = () => { };
+        this.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            const bootstrap = this.options.bootstrapTools === false ? [] : localTools;
+            if (!this.#client)
+                return { tools: bootstrap };
+            const page = await this.#withClient((client) => client.request(request, ListToolsResultSchema, { signal: extra.signal }));
+            if (page.tools.some((tool) => tool.name.startsWith(PREFIX)))
+                throw new McpError(ErrorCode.InvalidRequest, "Reserved connector tool namespace collision");
+            // A missing/private integration must not make the public GIS catalog unavailable.
+            const privateTools = !request.params?.cursor && this.devops ? await this.devops.listTools().catch(() => []) : [];
+            return { ...page, tools: request.params?.cursor ? page.tools : [...bootstrap, ...privateTools, ...page.tools] };
+        });
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const token = request.params._meta?.progressToken;
+            if (request.params.name.startsWith(DEVOPS_PREFIX)) {
+                if (!this.devops)
+                    throw new McpError(ErrorCode.MethodNotFound, "Private DevOps integration is not configured");
+                return this.#withClient(() => this.devops.callTool(request.params.name, request.params.arguments ?? {}, {
+                    signal: extra.signal,
+                    ...(token === undefined
+                        ? {}
+                        : {
+                            onprogress: (progress) => {
+                                void extra
+                                    .sendNotification({
+                                    method: "notifications/progress",
+                                    params: { ...progress, progressToken: token },
+                                })
+                                    .catch(() => { });
+                            },
+                        }),
+                }));
+            }
+            if (request.params.name.startsWith(PREFIX) && this.options.bootstrapTools === false)
+                throw new McpError(ErrorCode.MethodNotFound, "Host installation tools are unavailable in native chat");
+            if (request.params.name.startsWith(PREFIX))
+                return this.#local(request.params.name, request.params.arguments ?? {});
+            return this.#withClient((client) => client.request(request, CallToolResultSchema, {
+                signal: extra.signal,
+                ...(token === undefined
+                    ? {}
+                    : {
+                        onprogress: (progress) => {
+                            void extra
+                                .sendNotification({
+                                method: "notifications/progress",
+                                params: { ...progress, progressToken: token },
+                            })
+                                .catch(() => { });
+                        },
+                    }),
+            }));
+        });
+        this.server.setRequestHandler(ListResourcesRequestSchema, async (request, extra) => {
+            if (!this.#client)
+                return { resources: [knowledgeResource] };
+            const page = await this.#withClient((client) => client.request(request, ListResourcesResultSchema, { signal: extra.signal }));
+            if (page.resources.some((resource) => resource.uri === WORKFLOW_KNOWLEDGE_URI))
+                throw new McpError(ErrorCode.InvalidRequest, "Reserved workflow knowledge URI collision");
+            return { ...page, resources: request.params?.cursor ? page.resources : [knowledgeResource, ...page.resources] };
+        });
+        this.server.setRequestHandler(ListResourceTemplatesRequestSchema, (request, extra) => !this.#client
+            ? { resourceTemplates: [] }
+            : this.#withClient((client) => client.request(request, ListResourceTemplatesResultSchema, { signal: extra.signal })));
+        this.server.setRequestHandler(ReadResourceRequestSchema, (request, extra) => request.params.uri === WORKFLOW_KNOWLEDGE_URI
+            ? {
+                contents: [
+                    { uri: WORKFLOW_KNOWLEDGE_URI, mimeType: "application/json", text: JSON.stringify(WORKFLOW_KNOWLEDGE) },
+                ],
+            }
+            : this.#withClient((client) => client.request(request, ReadResourceResultSchema, { signal: extra.signal })));
+        this.server.setRequestHandler(ListPromptsRequestSchema, (request, extra) => !this.#client
+            ? { prompts: [] }
+            : this.#withClient((client) => client.request(request, ListPromptsResultSchema, { signal: extra.signal })));
+        this.server.setRequestHandler(GetPromptRequestSchema, (request, extra) => this.#withClient((client) => client.request(request, GetPromptResultSchema, { signal: extra.signal })));
+    }
+    async connect(transport) {
+        // Capture only the upstream-owned view selector while letting Server negotiate
+        // its own identity and capabilities with the downstream client.
+        let receiver;
+        const wrapper = {
+            start: () => transport.start(),
+            close: () => transport.close(),
+            send: (message, options) => transport.send(message, options),
+            get sessionId() {
+                return transport.sessionId;
+            },
+            setProtocolVersion: (version) => transport.setProtocolVersion?.(version),
+            get onclose() {
+                return transport.onclose;
+            },
+            set onclose(value) {
+                transport.onclose = value;
+            },
+            get onerror() {
+                return transport.onerror;
+            },
+            set onerror(value) {
+                transport.onerror = value;
+            },
+            get onmessage() {
+                return receiver;
+            },
+            set onmessage(value) {
+                receiver = value;
+            },
+        };
+        transport.onmessage = (message, extra) => {
+            if ("method" in message && message.method === "initialize") {
+                try {
+                    this.#view = readWorkflowView(InitializeRequestSchema.parse(message));
+                }
+                catch {
+                    if ("id" in message)
+                        void transport
+                            .send({
+                            jsonrpc: "2.0",
+                            id: message.id,
+                            error: { code: ErrorCode.InvalidParams, message: "Invalid workflow view" },
+                        })
+                            .catch(() => { })
+                            .finally(() => transport.close());
+                    return;
+                }
+            }
+            receiver?.(message, extra);
+        };
+        await this.server.connect(wrapper);
+    }
+    async close() {
+        this.#closed = true;
+        await this.#client?.close();
+        await this.devops?.close();
+        await this.server.close();
+    }
+    /** Native HTTP discovery must not race the external connector's background attachment. */
+    async prepare(view) {
+        this.#view = view;
+        await this.#attach();
+    }
+    async #withClient(call) {
+        const client = this.#client;
+        if (!client || this.#transition)
+            throw new McpError(ErrorCode.InvalidRequest, "Honua is not attached; inspect connector status");
+        this.#active++;
+        try {
+            return await call(client);
+        }
+        catch (error) {
+            // Preserve structured tool errors (returned results), but never echo raw
+            // HTTP/protocol exception messages into a credentialed model session.
+            if (error instanceof McpError && error.code === ErrorCode.MethodNotFound)
+                throw new McpError(error.code, "Operation unavailable on the attached deployment");
+            throw new McpError(ErrorCode.InternalError, "Upstream request failed; outcome may be unknown. Inspect the existing operation before retrying a mutation.");
+        }
+        finally {
+            this.#active--;
+        }
+    }
+    async #notify() {
+        if (!this.#initialized || this.#closed)
+            return;
+        await Promise.all([
+            this.server.notification({ method: "notifications/tools/list_changed" }),
+            this.server.notification({ method: "notifications/resources/list_changed" }),
+            this.server.notification({ method: "notifications/prompts/list_changed" }),
+        ]).catch(() => { });
+    }
+    async #attach(install) {
+        if (this.#transition || this.#active)
+            throw new Error("Connector is busy");
+        if (install && this.#target)
+            throw new Error("An established target cannot be reinstalled in this session");
+        if (this.#client) {
+            if (install)
+                throw new Error("Already attached; installation cannot run in an active session");
+            return;
+        }
+        this.#transition = true;
+        let candidate;
+        try {
+            if (install)
+                await this.runtime.install(install);
+            const connection = await this.runtime.resolve();
+            if (this.#target && this.#target.id !== connection.target.id)
+                throw new Error("Target identity changed; reconnect explicitly");
+            candidate = await this.upstream(connection, this.#view);
+            const cursors = new Set();
+            let cursor;
+            do {
+                const page = await candidate.listTools(cursor ? { cursor } : undefined);
+                if (page.tools.some((tool) => tool.name.startsWith(PREFIX)))
+                    throw new Error("Reserved namespace collision");
+                cursor = page.nextCursor;
+                if (cursor && (cursors.has(cursor) || cursors.size >= 100))
+                    throw new Error("Invalid catalog pagination");
+                if (cursor)
+                    cursors.add(cursor);
+            } while (cursor);
+            if (this.#closed)
+                throw new Error("Connector closed during attachment");
+            const attached = candidate;
+            attached.onerror = () => {
+                if (this.#client === attached) {
+                    this.#client = undefined;
+                    void attached.close().catch(() => { });
+                    void this.#notify();
+                }
+            };
+            attached.onclose = () => {
+                if (this.#client === attached) {
+                    this.#client = undefined;
+                    void this.#notify();
+                }
+            };
+            attached.setNotificationHandler(ToolListChangedNotificationSchema, () => this.#notify());
+            attached.setNotificationHandler(ResourceListChangedNotificationSchema, () => this.#notify());
+            attached.setNotificationHandler(PromptListChangedNotificationSchema, () => this.#notify());
+            this.#client = attached;
+            this.#target = connection.target;
+            candidate = undefined;
+        }
+        finally {
+            await candidate?.close().catch(() => { });
+            this.#transition = false;
+            await this.#notify();
+        }
+    }
+    async #local(name, args) {
+        try {
+            if (name !== `${PREFIX}install_local`)
+                emptyInput.parse(args);
+            switch (name) {
+                case `${PREFIX}status`:
+                    return result({
+                        state: this.#transition ? "connecting" : this.#client ? "attached" : "unattached",
+                        target: this.#target ?? null,
+                        activeRequests: this.#active,
+                    });
+                case `${PREFIX}inspect_local`:
+                    return result(await this.runtime.inspect());
+                case `${PREFIX}connect`:
+                    await this.#attach();
+                    return result({ state: "attached", target: this.#target });
+                case `${PREFIX}install_local`:
+                    await this.#attach(installInput.parse(args));
+                    return result({ state: "attached", target: this.#target });
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, "Unknown connector tool");
+            }
+        }
+        catch {
+            return {
+                ...result({
+                    state: "unavailable",
+                    code: "connector-action-refused",
+                    next: "Inspect connector status and local prerequisites; do not retry uncertain mutations.",
+                }),
+                isError: true,
+            };
+        }
+    }
+}

package/dist/src/agent/local-runtime.d.ts

@@ -0,0 +1,26 @@
+import { type LocalInstallOptions } from "@honua/sdk-js/local-install";
+import type { ProxyOptions } from "../proxy.js";
+/** Preview artifacts come from host configuration, never from model tool arguments. */
+export declare function nativeWorkspaceFromEnv(env: NodeJS.ProcessEnv): LocalInstallOptions["nativeWorkspace"];
+export interface AgentTarget {
+    readonly id: string;
+    readonly endpoint: string;
+    readonly credentialId: string;
+}
+export interface AgentConnection {
+    readonly target: AgentTarget;
+    /** Transport-only configuration. Never serialize this into an MCP result. */
+    readonly transport: ProxyOptions;
+}
+export interface AgentRuntime {
+    inspect(): Promise<Record<string, unknown>>;
+    install(input: {
+        confirm: true;
+        profile: "quickstart" | "gp-dev";
+        httpPort: number;
+    }): Promise<void>;
+    resolve(): Promise<AgentConnection>;
+}
+/** The host fixes the installation root; no tool accepts credential paths or URLs. */
+export declare function createLocalAgentRuntime(directory: string, nativeWorkspace?: LocalInstallOptions["nativeWorkspace"]): AgentRuntime;
+//# sourceMappingURL=local-runtime.d.ts.map

package/dist/src/agent/local-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-runtime.d.ts","sourceRoot":"","sources":["../../../src/agent/local-runtime.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,mBAAmB,EAKzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAiErG;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,OAAO,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACrC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,GACvD,YAAY,CA4Ed"}

package/dist/src/agent/local-runtime.js

@@ -0,0 +1,152 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { arch, platform } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { inspectLocalAgentAccess, inspectLocalWorkspaceAgentAccess, installHonuaLocal, readVerifiedLocalEnv, } from "@honua/sdk-js/local-install";
+const execute = promisify(execFile);
+/** Preview artifacts come from host configuration, never from model tool arguments. */
+export function nativeWorkspaceFromEnv(env) {
+    const prefix = "HONUA_AGENT_PREVIEW_";
+    const modelNames = ["MODEL_KIND", "MODEL_ENDPOINT", "MODEL_NAME", "MODEL_REGION", "MODEL_KEY_ENV"];
+    const gatewayNames = ["GATEWAY_HTTP_URL", "GATEWAY_HTTP_KEY_ENV"];
+    const processNames = ["GP_WORKSPACE_URL", "GP_WORKSPACE_KEY_ENV"];
+    const names = [
+        "SERVER_IMAGE",
+        "CONSOLE_IMAGE",
+        "RELEASE_ID",
+        "GATEWAY_COMMAND",
+        "GATEWAY_ARGS",
+        "CONSOLE_PORT",
+        ...modelNames,
+        ...gatewayNames,
+        ...processNames,
+    ];
+    if (!names.some((name) => env[`${prefix}${name}`] !== undefined))
+        return undefined;
+    const required = (name) => {
+        const value = env[`${prefix}${name}`];
+        if (!value?.trim())
+            throw new Error(`Incomplete native workspace host configuration: ${name}`);
+        return value;
+    };
+    let gatewayArgs = [];
+    if (env.HONUA_AGENT_PREVIEW_GATEWAY_ARGS !== undefined) {
+        const parsed = JSON.parse(env.HONUA_AGENT_PREVIEW_GATEWAY_ARGS);
+        if (!Array.isArray(parsed) || !parsed.every((arg) => typeof arg === "string"))
+            throw new Error("Preview gateway arguments must be a JSON string array");
+        gatewayArgs = parsed;
+    }
+    const consolePort = env.HONUA_AGENT_PREVIEW_CONSOLE_PORT === undefined ? undefined : Number(env.HONUA_AGENT_PREVIEW_CONSOLE_PORT);
+    if (consolePort !== undefined && (!Number.isInteger(consolePort) || consolePort < 1 || consolePort > 65535))
+        throw new Error("Invalid preview Console port");
+    let modelProvider;
+    if (modelNames.some((name) => env[`${prefix}${name}`] !== undefined)) {
+        const kind = required("MODEL_KIND");
+        if (kind !== "openai" && kind !== "anthropic" && kind !== "bedrock")
+            throw new Error("Invalid preview model provider kind");
+        modelProvider = {
+            kind,
+            model: required("MODEL_NAME"),
+            ...(env.HONUA_AGENT_PREVIEW_MODEL_ENDPOINT === undefined ? {} : { endpoint: required("MODEL_ENDPOINT") }),
+            ...(env.HONUA_AGENT_PREVIEW_MODEL_REGION === undefined ? {} : { region: required("MODEL_REGION") }),
+            ...(env.HONUA_AGENT_PREVIEW_MODEL_KEY_ENV === undefined
+                ? {}
+                : { apiKeyEnvironmentVariable: required("MODEL_KEY_ENV") }),
+        };
+    }
+    const gatewayHttp = gatewayNames.some((name) => env[`${prefix}${name}`] !== undefined)
+        ? { url: required("GATEWAY_HTTP_URL"), keyEnvironmentVariable: required("GATEWAY_HTTP_KEY_ENV") }
+        : undefined;
+    const localProcesses = processNames.some((name) => env[`${prefix}${name}`] !== undefined)
+        ? { url: required("GP_WORKSPACE_URL"), keyEnvironmentVariable: required("GP_WORKSPACE_KEY_ENV") }
+        : undefined;
+    return {
+        serverImage: required("SERVER_IMAGE"),
+        consoleImage: required("CONSOLE_IMAGE"),
+        releaseId: required("RELEASE_ID"),
+        gatewayCommand: required("GATEWAY_COMMAND"),
+        gatewayArgs,
+        ...(consolePort === undefined ? {} : { consolePort }),
+        ...(modelProvider === undefined ? {} : { modelProvider }),
+        ...(gatewayHttp === undefined ? {} : { gatewayHttp }),
+        ...(localProcesses === undefined ? {} : { localProcesses }),
+    };
+}
+/** The host fixes the installation root; no tool accepts credential paths or URLs. */
+export function createLocalAgentRuntime(directory, nativeWorkspace) {
+    const root = path.resolve(directory);
+    async function docker(args) {
+        const result = await execute("docker", args, { timeout: 15_000, maxBuffer: 256 * 1024 });
+        return result.stdout.trim();
+    }
+    async function inspect() {
+        const facts = {
+            directory: root,
+            platform: platform(),
+            architecture: arch(),
+            ready: false,
+        };
+        try {
+            const context = JSON.parse(await docker(["context", "inspect"]));
+            const endpoint = process.env.DOCKER_CONTEXT
+                ? context[0]?.Endpoints.docker.Host
+                : process.env.DOCKER_HOST || context[0]?.Endpoints.docker.Host;
+            // This first local lane deliberately excludes remote engines and Windows pipes.
+            facts.localDaemon = typeof endpoint === "string" && endpoint.startsWith("unix://");
+            if (!facts.localDaemon)
+                return { ...facts, reason: "local-unix-docker-context-required" };
+            facts.engineVersion = await docker(["version", "--format", "{{.Server.Version}}"]);
+            facts.composeVersion = await docker(["compose", "version", "--short"]);
+            const version = String(facts.composeVersion)
+                .replace(/^v/, "")
+                .match(/^(\d+)\.(\d+)\.(\d+)/);
+            const compatible = version &&
+                (Number(version[1]) > 2 ||
+                    (Number(version[1]) === 2 &&
+                        (Number(version[2]) > 23 || (Number(version[2]) === 23 && Number(version[3]) >= 1))));
+            return { ...facts, ready: Boolean(compatible), ...(compatible ? {} : { reason: "compose-2.23.1-required" }) };
+        }
+        catch {
+            return { ...facts, reason: "docker-or-compose-unavailable" };
+        }
+    }
+    return {
+        inspect,
+        async install(input) {
+            if (!(await inspect()).ready)
+                throw new Error("Local Docker prerequisites are not ready");
+            await installHonuaLocal({ directory: root, profile: input.profile, httpPort: input.httpPort, nativeWorkspace });
+        },
+        async resolve() {
+            const env = await readVerifiedLocalEnv(root);
+            const workspaceCredentialPresent = env.HONUA_AGENT_API_KEY !== undefined || env.HONUA_AGENT_KEY_ID !== undefined;
+            if (workspaceCredentialPresent && (!env.HONUA_AGENT_API_KEY || !env.HONUA_AGENT_KEY_ID)) {
+                throw new Error("Native workspace credential identity is incomplete");
+            }
+            const apiKey = workspaceCredentialPresent ? env.HONUA_AGENT_API_KEY : env.HONUA_ADMIN_KEY;
+            const port = Number(env.HONUA_HTTP_PORT);
+            if (!Number.isInteger(port) || port < 1 || port > 65535 || !apiKey) {
+                throw new Error("No verified local installation");
+            }
+            const baseUrl = `http://127.0.0.1:${port}`;
+            const response = await fetch(`${baseUrl}/healthz/ready`, {
+                signal: AbortSignal.timeout(10_000),
+                redirect: "error",
+            });
+            if (!response.ok || (await response.text()).trim().toLowerCase() !== "ready") {
+                throw new Error("Installed server is not ready");
+            }
+            const fetchCredential = (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(10_000), redirect: "error" });
+            const credential = workspaceCredentialPresent
+                ? await inspectLocalWorkspaceAgentAccess(baseUrl, apiKey, env.HONUA_AGENT_KEY_ID, fetchCredential)
+                : await inspectLocalAgentAccess(baseUrl, apiKey, fetchCredential);
+            const endpoint = `${baseUrl}/mcp`;
+            const id = createHash("sha256").update(`${endpoint}\n${credential.id}`).digest("hex");
+            return {
+                target: { id, endpoint, credentialId: credential.id },
+                transport: { remoteUrl: endpoint, apiKey },
+            };
+        },
+    };
+}

package/dist/src/agent/native-cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Host-only native bridge. The browser continues to use Console's authenticated BFF. */
+export declare function runNativeAgentGateway(env?: NodeJS.ProcessEnv): Promise<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>>;
+//# sourceMappingURL=native-cli.d.ts.map

package/dist/src/agent/native-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-cli.d.ts","sourceRoot":"","sources":["../../../src/agent/native-cli.ts"],"names":[],"mappings":";AAOA,yFAAyF;AACzF,wBAAsB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,+GA6B/E"}