@honua/mcp-server 0.2.3 → 0.2.4

package/dist/src/agent/native-cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import path from "node:path";
+import { isMainEntrypoint } from "../entrypoint.js";
+import { createLocalAgentRuntime } from "./local-runtime.js";
+import { createNativeAgentHttpServer } from "./native-http.js";
+/** Host-only native bridge. The browser continues to use Console's authenticated BFF. */
+export async function runNativeAgentGateway(env = process.env) {
+    const port = Number(env.HONUA_AGENT_GATEWAY_PORT ?? "7863");
+    const host = env.HONUA_AGENT_GATEWAY_HOST ?? "127.0.0.1";
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("Invalid gateway port");
+    if (!["127.0.0.1", "::1", "0.0.0.0"].includes(host))
+        throw new Error("Gateway host must be an explicit listen address");
+    const server = createNativeAgentHttpServer({
+        runtime: createLocalAgentRuntime(env.HONUA_AGENT_INSTALL_DIRECTORY ?? path.join(homedir(), ".honua", "local")),
+        bridgeKey: env.HONUA_AGENT_GATEWAY_KEY ?? "",
+        ...(env.HONUA_AGENT_DEVOPS_CONFIG ? { devopsConfiguration: env.HONUA_AGENT_DEVOPS_CONFIG } : {}),
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const close = () => {
+        server.closeAllConnections();
+        server.close();
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+    server.once("close", () => {
+        process.removeListener("SIGINT", close);
+        process.removeListener("SIGTERM", close);
+    });
+    return server;
+}
+if (isMainEntrypoint(import.meta.url)) {
+    if (process.argv.includes("--help")) {
+        process.stdout.write("honua-agent-gateway — authenticated native HTTP bridge over the unified Honua MCP gateway.\nConfigure HONUA_AGENT_INSTALL_DIRECTORY and HONUA_AGENT_GATEWAY_KEY on the host. Default listen address: 127.0.0.1:7863.\n");
+    }
+    else {
+        runNativeAgentGateway().catch(() => {
+            process.stderr.write("Native Honua gateway failed; inspect host configuration.\n");
+            process.exitCode = 1;
+        });
+    }
+}

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

@@ -0,0 +1,18 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { AgentRuntime } from "./local-runtime.js";
+export interface NativeGatewayOptions {
+    runtime: AgentRuntime;
+    /** Independent backend bridge credential. Never supplied by a browser or a model. */
+    bridgeKey: string;
+    devopsConfiguration?: string;
+    fetchImpl?: typeof fetch;
+    maxSessions?: number;
+    idleTimeoutMs?: number;
+}
+/**
+ * Backend-only HTTP transport over the same gateway used by external agents.
+ * Sessions pin identity/workspace; AsyncLocalStorage pins each concurrent request's turn.
+ * Every request rereads the captured turn under the actual agent credential.
+ */
+export declare function createNativeAgentHttpServer(options: NativeGatewayOptions): import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+//# sourceMappingURL=native-http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"native-http.d.ts","sourceRoot":"","sources":["../../../src/agent/native-http.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAgB,MAAM,WAAW,CAAC;AAOpF,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUxE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,YAAY,CAAC;IACtB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyCD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB,wEAgOxE"}

package/dist/src/agent/native-http.js

@@ -0,0 +1,261 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { InitializeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { buildUpstreamHeaders, readWorkflowView } from "../proxy.js";
+import { configuredDevOps } from "./devops-configuration.js";
+import { DEVOPS_TOOL_FAMILY } from "./devops-runtime.js";
+import { HonuaAgentGateway, connectAgentUpstream } from "./gateway.js";
+class Refusal extends Error {
+    status;
+    constructor(status) {
+        super("Native gateway request refused");
+        this.status = status;
+    }
+}
+function header(request, name, optional = false) {
+    const values = request.rawHeaders.filter((_value, index) => index % 2 === 0 && request.rawHeaders[index]?.toLowerCase() === name);
+    const value = request.headers[name];
+    if (optional && values.length === 0)
+        return "";
+    if (values.length !== 1 || typeof value !== "string" || !value || value.length > 8192)
+        throw new Refusal(400);
+    return value;
+}
+function identifier(value) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(value))
+        throw new Refusal(400);
+    return value;
+}
+function sameSecret(left, right) {
+    const supplied = Buffer.from(left, "utf8");
+    const expected = Buffer.from(right, "utf8");
+    return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
+function samePrincipal(expected, current) {
+    return (expected.workspaceId === current.workspaceId &&
+        expected.targetId === current.targetId &&
+        expected.partition === current.partition &&
+        expected.connection.target.id === current.connection.target.id &&
+        expected.connection.target.credentialId === current.connection.target.credentialId &&
+        expected.connection.transport.remoteUrl === current.connection.transport.remoteUrl &&
+        sameSecret(expected.connection.transport.apiKey ?? "", current.connection.transport.apiKey ?? ""));
+}
+/**
+ * Backend-only HTTP transport over the same gateway used by external agents.
+ * Sessions pin identity/workspace; AsyncLocalStorage pins each concurrent request's turn.
+ * Every request rereads the captured turn under the actual agent credential.
+ */
+export function createNativeAgentHttpServer(options) {
+    if (Buffer.byteLength(options.bridgeKey) < 32)
+        throw new Error("A separate bridge key of at least 32 bytes is required");
+    const network = options.fetchImpl ?? fetch;
+    const bindings = new AsyncLocalStorage();
+    const sessions = new Map();
+    let initializing = 0;
+    const maximum = options.maxSessions ?? 32;
+    const idle = options.idleTimeoutMs ?? 600_000;
+    if (!Number.isInteger(maximum) || maximum < 1 || maximum > 128 || !Number.isFinite(idle) || idle < 1000)
+        throw new Error("Invalid native gateway session limits");
+    async function authorize(request) {
+        if (request.headers.origin || request.headers.authorization)
+            throw new Refusal(403);
+        if (!sameSecret(header(request, "x-honua-gateway-key"), options.bridgeKey))
+            throw new Refusal(403);
+        const workspaceId = identifier(header(request, "x-honua-workspace"));
+        const turnId = identifier(header(request, "x-honua-turn"));
+        const partition = identifier(header(request, "x-honua-operator-partition"));
+        const supplied = header(request, "x-api-key");
+        const connection = await options.runtime.resolve();
+        if (!connection.transport.apiKey ||
+            connection.transport.authToken ||
+            sameSecret(connection.transport.apiKey, options.bridgeKey) ||
+            !sameSecret(supplied, connection.transport.apiKey))
+            throw new Refusal(403);
+        const base = new URL(connection.transport.remoteUrl);
+        const response = await network(new URL(`/api/v1/agent/workspaces/${workspaceId}/turns/${turnId}`, base), {
+            headers: buildUpstreamHeaders(connection.transport),
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new Refusal(response.status >= 500 ? 503 : 403);
+        const turn = (await response.json());
+        if (turn.turnId !== turnId ||
+            turn.context?.workspaceId !== workspaceId ||
+            typeof turn.context.targetId !== "string" ||
+            typeof turn.context.tenantId !== "string" ||
+            !turn.context.tenantId)
+            throw new Refusal(403);
+        return { workspaceId, turnId, targetId: identifier(turn.context.targetId), partition, connection };
+    }
+    const boundFetch = async (input, init) => {
+        const binding = bindings.getStore();
+        if (!binding)
+            throw new Error("A verified native turn is required for upstream requests");
+        const url = new URL(input instanceof Request ? input.url : String(input));
+        if (url.origin !== new URL(binding.connection.transport.remoteUrl).origin)
+            throw new Error("Native upstream origin mismatch");
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
+        headers.set("X-Honua-Workspace", binding.workspaceId);
+        headers.set("X-Honua-Turn", binding.turnId);
+        return network(input, { ...init, headers, redirect: "error" });
+    };
+    function boundRuntime(initial) {
+        return {
+            inspect: async () => ({ ready: true, targetId: initial.targetId }),
+            install: async () => {
+                throw new Error("Native chat cannot bootstrap the host");
+            },
+            resolve: async () => {
+                const binding = bindings.getStore();
+                if (!binding || !samePrincipal(initial, binding))
+                    throw new Error("Native gateway identity changed");
+                const connection = await options.runtime.resolve();
+                if (!samePrincipal(initial, { ...binding, connection }))
+                    throw new Error("Native gateway credential changed");
+                return connection;
+            },
+        };
+    }
+    async function privateExtension(runtime) {
+        return options.devopsConfiguration ? configuredDevOps(options.devopsConfiguration, runtime, boundFetch) : undefined;
+    }
+    async function body(request) {
+        if (!String(request.headers["content-type"] ?? "")
+            .toLowerCase()
+            .startsWith("application/json"))
+            throw new Refusal(415);
+        const chunks = [];
+        let length = 0;
+        for await (const chunk of request) {
+            const bytes = Buffer.from(chunk);
+            length += bytes.length;
+            if (length > 256 * 1024)
+                throw new Refusal(413);
+            chunks.push(bytes);
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new Refusal(400);
+        }
+    }
+    async function handle(request, response) {
+        response.setHeader("Cache-Control", "no-store");
+        if (request.url !== "/mcp" && request.url !== "/capabilities")
+            throw new Refusal(404);
+        if (!["GET", "POST", "DELETE"].includes(request.method ?? ""))
+            throw new Refusal(405);
+        const binding = await authorize(request);
+        await bindings.run(binding, async () => {
+            if (request.url === "/capabilities") {
+                if (request.method !== "GET")
+                    throw new Refusal(405);
+                const extension = await privateExtension(boundRuntime(binding));
+                let available = false;
+                try {
+                    available = Boolean(extension && (await extension.listTools()).length);
+                }
+                catch {
+                    /* Private authorization failure never widens the native catalog. */
+                }
+                finally {
+                    await extension?.close();
+                }
+                response.setHeader("Content-Type", "application/json");
+                response.end(JSON.stringify({
+                    schemaVersion: "honua.agent-gateway.capabilities.v1",
+                    targetId: binding.targetId,
+                    workspaceId: binding.workspaceId,
+                    turnId: binding.turnId,
+                    toolFamilies: available ? [DEVOPS_TOOL_FAMILY] : [],
+                }));
+                return;
+            }
+            const sessionId = header(request, "mcp-session-id", true);
+            let session = sessionId ? sessions.get(sessionId) : undefined;
+            if (sessionId && (!session || !samePrincipal(session.binding, binding)))
+                throw new Refusal(403);
+            const parsed = request.method === "POST" ? await body(request) : undefined;
+            if (!session) {
+                const initialization = InitializeRequestSchema.safeParse(parsed);
+                if (sessionId || request.method !== "POST" || !initialization.success)
+                    throw new Refusal(400);
+                if (sessions.size + initializing >= maximum)
+                    throw new Refusal(429);
+                initializing++;
+                let gateway;
+                try {
+                    const runtime = boundRuntime(binding);
+                    gateway = new HonuaAgentGateway(runtime, (connection, view) => connectAgentUpstream(connection, view, boundFetch), await privateExtension(runtime), { bootstrapTools: false });
+                    // Attach before initialize's response so immediate discovery is authoritative.
+                    await gateway.prepare(readWorkflowView(initialization.data));
+                    const id = randomUUID();
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => id,
+                        enableJsonResponse: true,
+                    });
+                    await gateway.connect(transport);
+                    session = { binding, gateway, transport, touched: Date.now(), active: 0 };
+                    sessions.set(id, session);
+                    const previous = transport.onclose;
+                    transport.onclose = () => {
+                        sessions.delete(id);
+                        previous?.();
+                    };
+                }
+                catch (error) {
+                    await gateway?.close().catch(() => { });
+                    throw error;
+                }
+                finally {
+                    initializing--;
+                }
+            }
+            session.touched = Date.now();
+            session.active++;
+            try {
+                await session.transport.handleRequest(request, response, parsed);
+            }
+            finally {
+                session.active--;
+                session.touched = Date.now();
+            }
+        });
+    }
+    const server = createServer((request, response) => {
+        void handle(request, response).catch((error) => {
+            if (!response.headersSent) {
+                response.writeHead(error instanceof Refusal ? error.status : 503, {
+                    "Content-Type": "application/json",
+                    "Cache-Control": "no-store",
+                });
+                response.end('{"error":"Native gateway request unavailable or unauthorized"}');
+            }
+            else
+                response.end();
+        });
+    });
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 30_000;
+    const sweep = setInterval(() => {
+        for (const [id, session] of sessions) {
+            if (session.active === 0 && Date.now() - session.touched > idle) {
+                sessions.delete(id);
+                void session.gateway.close().catch(() => { });
+            }
+        }
+    }, Math.min(idle, 30_000));
+    sweep.unref();
+    server.once("close", () => {
+        clearInterval(sweep);
+        for (const session of sessions.values())
+            void session.gateway.close().catch(() => { });
+        sessions.clear();
+    });
+    return server;
+}

package/dist/src/agent/workflow-knowledge.d.ts

@@ -0,0 +1,73 @@
+/** Versioned semantic guidance, not an executor or a claim of live qualification. */
+export declare const WORKFLOW_KNOWLEDGE_URI = "honua://agent/knowledge/workflows/v1";
+export declare const WORKFLOW_KNOWLEDGE: {
+    readonly schemaVersion: "honua.agent-workflow-knowledge/v1";
+    readonly knowledgeVersion: "2026-10-17.2";
+    readonly qualification: "contract-guidance-only";
+    readonly authority: readonly ["Use discovered canonical tool schemas; these workflow descriptions never grant authorization.", "Bind every step to the current principal, tenant and target. Recheck credentials and RBAC on each action.", "Persist resource, operation and command references from canonical responses. Model prose cannot create a verified observation.", "After a lost mutation response reconcile the durable command/operation before retry; never infer failure from a timeout.", "The human approval inbox and approving principal are distinct from the agent. AwaitingApproval is a successful handoff, not a published result.", "Keep bootstrap secrets, cloud credentials, signing keys and private environment values outside model context."];
+    readonly workflows: readonly [{
+        readonly id: "local-bootstrap";
+        readonly intent: "Evaluate Honua locally from one persistent MCP registration.";
+        readonly preconditions: readonly ["Host-selected installation directory", "Local Docker and compatible Compose", "Explicit authorization to install"];
+        readonly actions: readonly ["honua_agent_inspect_local", "honua_agent_install_local", "honua_agent_connect", "honua_agent_status"];
+        readonly inputReferences: readonly ["host installation profile"];
+        readonly outputReferences: readonly ["verified target id", "credential id without credential value"];
+        readonly observedOutcomes: readonly ["Docker readiness", "authenticated server MCP negotiation", "separate human pairing where required"];
+        readonly failureRule: "Installation output alone is not a verified or human-paired connection.";
+    }, {
+        readonly id: "shared-workspace-context";
+        readonly intent: "Continue the same authorized GIS task through chat, Console forms and Studio.";
+        readonly preconditions: readonly ["Discovered honua_workspace_* tools", "Actual paired workspace and explicit browser view references", "Current workspace membership, target and resource authorization"];
+        readonly actions: readonly ["honua_workspace_get", "honua_workspace_set_context when changing selection or task; retain expectedRevision", "honua_workspace_create_turn before execution; capture the submitted contextRevision", "honua_workspace_get_turn for the active prompt instead of rereading a later selection", "honua_workspace_get_draft and honua_workspace_patch_draft for an existing publish-layer form", "honua_workspace_submit_draft with a persistent commandId", "honua_workspace_get_command before retrying a submission with an unknown outcome", "honua_workspace_append_message for conversation text, never for verified operation receipts"];
+        readonly inputReferences: readonly ["workspace id", "view id", "target id", "context revision", "selected service/layer references", "task reference from an actual canonical response"];
+        readonly outputReferences: readonly ["immutable turn id", "shared draft id and revision", "command id", "canonical operation/proposal id"];
+        readonly observedOutcomes: readonly ["current authorized selection", "frozen prompt target", "shared form revision", "canonical command state"];
+        readonly failureRule: "Do not invent browser/workspace references, overwrite dirty forms or retarget an existing turn after navigation. A Studio task binds its real draft id/generation/package key; a workflow-package task binds its immutable package id/version/content hash. A local custom-code run is not a server workflow-package task. Native chat supplies request bindings through its backend; external clients must use the discovered explicit workspace tool contracts and must not assume automatic header binding.";
+    }, {
+        readonly id: "data-and-services";
+        readonly intent: "Connect or import data, publish a service and verify a query.";
+        readonly preconditions: readonly ["Verified current target", "Caller import/connect and publish permissions", "Explicit source and destination"];
+        readonly actions: readonly ["Discover connection/import tools", "Validate source schema and geometry/CRS", "Execute canonical import or connection", "Publish via discovered service/layer tool", "Query the published layer"];
+        readonly inputReferences: readonly ["connection/source reference", "upload/artifact reference", "destination schema"];
+        readonly outputReferences: readonly ["import job id", "service id", "layer id or protocol-neutral source reference"];
+        readonly observedOutcomes: readonly ["terminal import outcome", "service catalog entry", "query result with expected schema and representative data"];
+        readonly failureRule: "An accepted job or publish request is not successful ingestion or query verification.";
+    }, {
+        readonly id: "studio-map-and-publication";
+        readonly intent: "Compose/style a map or app, save/reopen its version and publish it for an audience.";
+        readonly preconditions: readonly ["Actual service/layer references", "Shared target and selection", "Current draft revision", "Caller draft/publish permissions"];
+        readonly actions: readonly ["Discover Studio tool schemas", "Create/edit draft under current policy", "Validate", "Save immutable version", "Read/reopen saved version", "Publish using canonical publication tool", "Verify published audience access"];
+        readonly inputReferences: readonly ["draft id and revision", "service/layer/style references", "intended audience"];
+        readonly outputReferences: readonly ["draft id", "version id", "publication operation/proposal id", "published app/map reference"];
+        readonly observedOutcomes: readonly ["saved content reread", "unrelated edits preserved", "Published or AwaitingApproval receipt", "audience access checked after Published"];
+        readonly failureRule: "On conflict reread/reconcile against current revision. On AwaitingApproval preserve proposal id and hand off to the human inbox; do not claim publication.";
+    }, {
+        readonly id: "processes";
+        readonly intent: "Run a built-in process graph or develop separately sandboxed Python/.NET code and map its output.";
+        readonly preconditions: readonly ["Discovered Processes capabilities", "Input resource references", "Explicit built-in versus custom-code execution mode"];
+        readonly actions: readonly ["Snapshot inputs and graph/code immutably", "Validate/build in the selected adapter", "Run with bounded resources", "Read sanitized diagnostics", "Correct and rerun as a new snapshot when needed", "Import output with normal artifact/import tools", "Query/map the imported output"];
+        readonly inputReferences: readonly ["graph definition or isolated code snapshot", "input artifact/layer ids", "adapter/runtime version"];
+        readonly outputReferences: readonly ["snapshot/build/run ids", "diagnostic references", "output artifact id", "imported layer reference"];
+        readonly observedOutcomes: readonly ["failed and corrected run statuses", "cancellation status when requested", "output schema/CRS", "query/map evidence"];
+        readonly failureRule: "Do not mix built-in/custom-code graphs or claim syntax-valid code executed. A run artifact is not an imported layer.";
+    }, {
+        readonly id: "cloud-git-and-recovery";
+        readonly intent: "Optionally provision ECS, version scoped GIS configuration, and operate Honua through canonical governed actions.";
+        readonly preconditions: readonly ["Optional private DevOps configured by host", "Per-action credential/RBAC check", "Explicit ECS target/environment", "Human-reviewed plan and configured approval"];
+        readonly actions: readonly ["Describe environment", "Plan aws-ecs via private canonical executor", "Bind separate signed approval to exact saved-plan digest", "Apply exact approved plan", "Emit and verify secretless handoff", "Generate scoped metadata Git change set", "Create scoped review commit/PR through create_scoped_gitops_pull_request with the exact configured base", "Propose config recovery through revert_scoped_gitops_pull_request; separate humans review/merge/approve", "Request version update or recovery through server-owned ops/proposals"];
+        readonly inputReferences: readonly ["ECS provisioning operation and plan digest", "separate approval receipt", "server metadata release package", "current and candidate revision", "known-good revision/recovery policy"];
+        readonly outputReferences: readonly ["provision binding", "verified handoff receipt", "Git commit/PR ids", "canonical proposal/deploy operation ids", "recovery evidence"];
+        readonly observedOutcomes: readonly ["exact-plan executor outcome", "authenticated handoff", "scoped Git diff and commit reread", "terminal server deployment outcome", "prior revision restored and rejected candidate quarantined only when qualified recovery is proven"];
+        readonly failureRule: "ECS provisioning does not qualify ECS version rollback/recovery. Lambda/EKS require real adapters and separate proof. Metadata change-set generation does not write Git; optional scoped PR/revert adapters write only deterministic review branches and never merge or submit deployment. Syntax/contract tests do not establish live cloud qualification.";
+    }, {
+        readonly id: "day2-operations";
+        readonly intent: "Inspect health and propose version/recovery operations without a parallel execution or approval loop.";
+        readonly preconditions: readonly ["Authenticated server target", "Discovered honua_ops_* and honua_propose_* capabilities", "Caller operation permissions"];
+        readonly actions: readonly ["Read canonical health/findings", "Inspect supported operation schema and protection capability", "Create scoped server proposal", "Hand proposal to separate human approval inbox", "Observe canonical operation and verify actual service state"];
+        readonly inputReferences: readonly ["target id", "findings/evidence refs", "current/candidate/prior revisions where applicable"];
+        readonly outputReferences: readonly ["proposal id", "operation id", "approval/audit reference", "observed service revision"];
+        readonly observedOutcomes: readonly ["AwaitingApproval or canonical execution outcome", "version/health reread", "recovery qualification bound to exact backend and server artifact"];
+        readonly failureRule: "Agent cannot approve its own proposal. Missing adapter/protection evidence is unsupported or unqualified; do not synthesize a rollback or call private experimental rollback.";
+    }];
+};
+//# sourceMappingURL=workflow-knowledge.d.ts.map

package/dist/src/agent/workflow-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-knowledge.d.ts","sourceRoot":"","sources":["../../../src/agent/workflow-knowledge.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAC7E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyOrB,CAAC"}

package/dist/src/agent/workflow-knowledge.js

@@ -0,0 +1,230 @@
+/** Versioned semantic guidance, not an executor or a claim of live qualification. */
+export const WORKFLOW_KNOWLEDGE_URI = "honua://agent/knowledge/workflows/v1";
+export const WORKFLOW_KNOWLEDGE = {
+    schemaVersion: "honua.agent-workflow-knowledge/v1",
+    knowledgeVersion: "2026-10-17.2",
+    qualification: "contract-guidance-only",
+    authority: [
+        "Use discovered canonical tool schemas; these workflow descriptions never grant authorization.",
+        "Bind every step to the current principal, tenant and target. Recheck credentials and RBAC on each action.",
+        "Persist resource, operation and command references from canonical responses. Model prose cannot create a verified observation.",
+        "After a lost mutation response reconcile the durable command/operation before retry; never infer failure from a timeout.",
+        "The human approval inbox and approving principal are distinct from the agent. AwaitingApproval is a successful handoff, not a published result.",
+        "Keep bootstrap secrets, cloud credentials, signing keys and private environment values outside model context.",
+    ],
+    workflows: [
+        {
+            id: "local-bootstrap",
+            intent: "Evaluate Honua locally from one persistent MCP registration.",
+            preconditions: [
+                "Host-selected installation directory",
+                "Local Docker and compatible Compose",
+                "Explicit authorization to install",
+            ],
+            actions: ["honua_agent_inspect_local", "honua_agent_install_local", "honua_agent_connect", "honua_agent_status"],
+            inputReferences: ["host installation profile"],
+            outputReferences: ["verified target id", "credential id without credential value"],
+            observedOutcomes: [
+                "Docker readiness",
+                "authenticated server MCP negotiation",
+                "separate human pairing where required",
+            ],
+            failureRule: "Installation output alone is not a verified or human-paired connection.",
+        },
+        {
+            id: "shared-workspace-context",
+            intent: "Continue the same authorized GIS task through chat, Console forms and Studio.",
+            preconditions: [
+                "Discovered honua_workspace_* tools",
+                "Actual paired workspace and explicit browser view references",
+                "Current workspace membership, target and resource authorization",
+            ],
+            actions: [
+                "honua_workspace_get",
+                "honua_workspace_set_context when changing selection or task; retain expectedRevision",
+                "honua_workspace_create_turn before execution; capture the submitted contextRevision",
+                "honua_workspace_get_turn for the active prompt instead of rereading a later selection",
+                "honua_workspace_get_draft and honua_workspace_patch_draft for an existing publish-layer form",
+                "honua_workspace_submit_draft with a persistent commandId",
+                "honua_workspace_get_command before retrying a submission with an unknown outcome",
+                "honua_workspace_append_message for conversation text, never for verified operation receipts",
+            ],
+            inputReferences: [
+                "workspace id",
+                "view id",
+                "target id",
+                "context revision",
+                "selected service/layer references",
+                "task reference from an actual canonical response",
+            ],
+            outputReferences: [
+                "immutable turn id",
+                "shared draft id and revision",
+                "command id",
+                "canonical operation/proposal id",
+            ],
+            observedOutcomes: [
+                "current authorized selection",
+                "frozen prompt target",
+                "shared form revision",
+                "canonical command state",
+            ],
+            failureRule: "Do not invent browser/workspace references, overwrite dirty forms or retarget an existing turn after navigation. A Studio task binds its real draft id/generation/package key; a workflow-package task binds its immutable package id/version/content hash. A local custom-code run is not a server workflow-package task. Native chat supplies request bindings through its backend; external clients must use the discovered explicit workspace tool contracts and must not assume automatic header binding.",
+        },
+        {
+            id: "data-and-services",
+            intent: "Connect or import data, publish a service and verify a query.",
+            preconditions: [
+                "Verified current target",
+                "Caller import/connect and publish permissions",
+                "Explicit source and destination",
+            ],
+            actions: [
+                "Discover connection/import tools",
+                "Validate source schema and geometry/CRS",
+                "Execute canonical import or connection",
+                "Publish via discovered service/layer tool",
+                "Query the published layer",
+            ],
+            inputReferences: ["connection/source reference", "upload/artifact reference", "destination schema"],
+            outputReferences: ["import job id", "service id", "layer id or protocol-neutral source reference"],
+            observedOutcomes: [
+                "terminal import outcome",
+                "service catalog entry",
+                "query result with expected schema and representative data",
+            ],
+            failureRule: "An accepted job or publish request is not successful ingestion or query verification.",
+        },
+        {
+            id: "studio-map-and-publication",
+            intent: "Compose/style a map or app, save/reopen its version and publish it for an audience.",
+            preconditions: [
+                "Actual service/layer references",
+                "Shared target and selection",
+                "Current draft revision",
+                "Caller draft/publish permissions",
+            ],
+            actions: [
+                "Discover Studio tool schemas",
+                "Create/edit draft under current policy",
+                "Validate",
+                "Save immutable version",
+                "Read/reopen saved version",
+                "Publish using canonical publication tool",
+                "Verify published audience access",
+            ],
+            inputReferences: ["draft id and revision", "service/layer/style references", "intended audience"],
+            outputReferences: ["draft id", "version id", "publication operation/proposal id", "published app/map reference"],
+            observedOutcomes: [
+                "saved content reread",
+                "unrelated edits preserved",
+                "Published or AwaitingApproval receipt",
+                "audience access checked after Published",
+            ],
+            failureRule: "On conflict reread/reconcile against current revision. On AwaitingApproval preserve proposal id and hand off to the human inbox; do not claim publication.",
+        },
+        {
+            id: "processes",
+            intent: "Run a built-in process graph or develop separately sandboxed Python/.NET code and map its output.",
+            preconditions: [
+                "Discovered Processes capabilities",
+                "Input resource references",
+                "Explicit built-in versus custom-code execution mode",
+            ],
+            actions: [
+                "Snapshot inputs and graph/code immutably",
+                "Validate/build in the selected adapter",
+                "Run with bounded resources",
+                "Read sanitized diagnostics",
+                "Correct and rerun as a new snapshot when needed",
+                "Import output with normal artifact/import tools",
+                "Query/map the imported output",
+            ],
+            inputReferences: [
+                "graph definition or isolated code snapshot",
+                "input artifact/layer ids",
+                "adapter/runtime version",
+            ],
+            outputReferences: [
+                "snapshot/build/run ids",
+                "diagnostic references",
+                "output artifact id",
+                "imported layer reference",
+            ],
+            observedOutcomes: [
+                "failed and corrected run statuses",
+                "cancellation status when requested",
+                "output schema/CRS",
+                "query/map evidence",
+            ],
+            failureRule: "Do not mix built-in/custom-code graphs or claim syntax-valid code executed. A run artifact is not an imported layer.",
+        },
+        {
+            id: "cloud-git-and-recovery",
+            intent: "Optionally provision ECS, version scoped GIS configuration, and operate Honua through canonical governed actions.",
+            preconditions: [
+                "Optional private DevOps configured by host",
+                "Per-action credential/RBAC check",
+                "Explicit ECS target/environment",
+                "Human-reviewed plan and configured approval",
+            ],
+            actions: [
+                "Describe environment",
+                "Plan aws-ecs via private canonical executor",
+                "Bind separate signed approval to exact saved-plan digest",
+                "Apply exact approved plan",
+                "Emit and verify secretless handoff",
+                "Generate scoped metadata Git change set",
+                "Create scoped review commit/PR through create_scoped_gitops_pull_request with the exact configured base",
+                "Propose config recovery through revert_scoped_gitops_pull_request; separate humans review/merge/approve",
+                "Request version update or recovery through server-owned ops/proposals",
+            ],
+            inputReferences: [
+                "ECS provisioning operation and plan digest",
+                "separate approval receipt",
+                "server metadata release package",
+                "current and candidate revision",
+                "known-good revision/recovery policy",
+            ],
+            outputReferences: [
+                "provision binding",
+                "verified handoff receipt",
+                "Git commit/PR ids",
+                "canonical proposal/deploy operation ids",
+                "recovery evidence",
+            ],
+            observedOutcomes: [
+                "exact-plan executor outcome",
+                "authenticated handoff",
+                "scoped Git diff and commit reread",
+                "terminal server deployment outcome",
+                "prior revision restored and rejected candidate quarantined only when qualified recovery is proven",
+            ],
+            failureRule: "ECS provisioning does not qualify ECS version rollback/recovery. Lambda/EKS require real adapters and separate proof. Metadata change-set generation does not write Git; optional scoped PR/revert adapters write only deterministic review branches and never merge or submit deployment. Syntax/contract tests do not establish live cloud qualification.",
+        },
+        {
+            id: "day2-operations",
+            intent: "Inspect health and propose version/recovery operations without a parallel execution or approval loop.",
+            preconditions: [
+                "Authenticated server target",
+                "Discovered honua_ops_* and honua_propose_* capabilities",
+                "Caller operation permissions",
+            ],
+            actions: [
+                "Read canonical health/findings",
+                "Inspect supported operation schema and protection capability",
+                "Create scoped server proposal",
+                "Hand proposal to separate human approval inbox",
+                "Observe canonical operation and verify actual service state",
+            ],
+            inputReferences: ["target id", "findings/evidence refs", "current/candidate/prior revisions where applicable"],
+            outputReferences: ["proposal id", "operation id", "approval/audit reference", "observed service revision"],
+            observedOutcomes: [
+                "AwaitingApproval or canonical execution outcome",
+                "version/health reread",
+                "recovery qualification bound to exact backend and server artifact",
+            ],
+            failureRule: "Agent cannot approve its own proposal. Missing adapter/protection evidence is unsupported or unqualified; do not synthesize a rollback or call private experimental rollback.",
+        },
+    ],
+};