@honua/mcp-server 0.2.3 → 0.2.5

package/README.md

@@ -29,6 +29,69 @@ Two modes:
 
 ## Requirements
 
+### Persistent local agent connector — source preview
+
+This branch adds `honua-agent-mcp`: one stdio connection that starts with local
+setup tools and attaches the installed Honua server's canonical MCP surface
+without replacing the client's registration. It is a source preview, not yet
+the qualified public Docker-to-map getting-started path.
+
+Start the built `dist/src/agent/cli.js` with Node from this package. The host sets
+`HONUA_AGENT_INSTALL_DIRECTORY` (default `~/.honua/local`); the agent cannot
+choose arbitrary credential files or remote URLs. Node and a local Unix-socket
+Docker engine with Compose 2.23.1 or later are required. Linux/WSL is the initial
+lane; Windows named pipes and remote Docker contexts are refused.
+
+Prompt: **"Check this machine, then set up Honua locally in Docker. Show me the
+target and available workflows when it is ready."** The agent calls
+`honua_agent_inspect_local`, obtains installation authorization, and calls
+`honua_agent_install_local` with `confirm: true`. Keep the installation tool
+timeout long enough for image pulls and database initialization (ten minutes is
+a useful starting point). If the client times out, inspect `honua_agent_status`
+and the installation before issuing another install. Cancellation of a local
+installation does not undo Docker work already started.
+
+The connector verifies readiness and the installed credential before announcing
+the server's tools. Existing installations attach on startup; after a transport
+disconnect, `honua_agent_connect` verifies the same target again. A changed
+credential identity requires a host restart. It never retries an upstream
+mutation after an uncertain response.
+
+Credentials stay in the installer's protected file and the HTTP transport. The
+local agent key has `admin:read`, `admin:write`, and `read:*`; it has no
+`admin:approve` or feature-write grant. Every upstream request carries that key,
+and the server enforces current RBAC, resource access, and governance. Discovery
+is not authorization; a denied operation remains denied. Browser human sessions
+and their approval authority are separate.
+
+This preview forwards canonical paginated tools, resources, resource templates,
+prompts, request metadata, tool progress, cancellation, and catalog-change
+notifications. It negotiates its own MCP identity and preserves the configured
+workflow view. It does not advertise subscriptions, sampling, roots,
+completions, or tasks. Durable workflow context, command reconciliation, browser
+pairing, and coordinated Console/Studio artifacts remain tracked in
+[the unified workspace workstream](https://github.com/honua-io/honua-server/issues/6297).
+
+After building the SDK and this package, maintainers can run the opt-in Docker
+handoff and process-restart check with
+`HONUA_AGENT_LIVE_ENABLED=true npm run test:unit --prefix mcp -- test/agent-local-live.test.ts`
+from the repository root. It creates and removes its own isolated Compose project.
+This tests the built connector against the installer's pinned server image; it
+does not certify the full map-making or browser journey.
+
+The packaged workflow guide is available as the MCP resource
+`honua://agent/knowledge/workflows/v1`, even before installation. Optional private
+DevOps tools can share this registration through host configuration; see
+[the host reference](../docs/unified-agent-host-configuration.md) for target and
+credential requirements and the current qualification limits.
+
+Native Console chat can use the preview `honua-agent-gateway` backend HTTP
+transport to reach this same public/private catalog. Its separate bridge key,
+workspace-turn checks and host configuration are described in that reference.
+External agents continue to use their single `honua-agent-mcp` registration.
+
+### Existing standalone and proxy modes
+
 - Node.js `>=22.12`
 - Any reachable FeatureServer/OGC endpoint (public or Honua)
 

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function runAgent(env?: NodeJS.ProcessEnv): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/agent/cli.ts"],"names":[],"mappings":";AASA,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAalF"}

package/dist/src/agent/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import path from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { isMainEntrypoint } from "../entrypoint.js";
+import { configuredDevOps } from "./devops-configuration.js";
+import { HonuaAgentGateway } from "./gateway.js";
+import { createLocalAgentRuntime, nativeWorkspaceFromEnv } from "./local-runtime.js";
+export async function runAgent(env = process.env) {
+    const directory = env.HONUA_AGENT_INSTALL_DIRECTORY ?? path.join(homedir(), ".honua", "local");
+    const runtime = createLocalAgentRuntime(directory, nativeWorkspaceFromEnv(env));
+    const devops = env.HONUA_AGENT_DEVOPS_CONFIG
+        ? await configuredDevOps(env.HONUA_AGENT_DEVOPS_CONFIG, runtime)
+        : undefined;
+    const gateway = new HonuaAgentGateway(runtime, undefined, devops);
+    const close = () => {
+        void gateway.close().catch(() => { });
+    };
+    process.stdin.once("end", close);
+    process.stdin.once("close", close);
+    await gateway.connect(new StdioServerTransport());
+}
+if (isMainEntrypoint(import.meta.url)) {
+    if (process.argv.includes("--help")) {
+        process.stdout.write("honua-agent-mcp — persistent local Honua MCP gateway\nConfigure HONUA_AGENT_INSTALL_DIRECTORY in the host; default ~/.honua/local.\n");
+    }
+    else {
+        runAgent().catch(() => {
+            process.stderr.write("Honua agent connector failed; inspect local configuration.\n");
+            process.exitCode = 1;
+        });
+    }
+}

package/dist/src/agent/devops-configuration.d.ts

@@ -0,0 +1,5 @@
+import { type DevOpsExtension } from "./devops-runtime.js";
+import type { AgentRuntime } from "./local-runtime.js";
+/** The host selects this protected file; MCP arguments cannot select executable paths or credentials. */
+export declare function configuredDevOps(file: string, runtime: AgentRuntime, fetchImpl?: typeof fetch): Promise<DevOpsExtension>;
+//# sourceMappingURL=devops-configuration.d.ts.map

package/dist/src/agent/devops-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devops-configuration.d.ts","sourceRoot":"","sources":["../../../src/agent/devops-configuration.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AAElF,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAyBxE,yGAAyG;AACzG,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,eAAe,CAAC,CAoG1B"}

package/dist/src/agent/devops-configuration.js

@@ -0,0 +1,130 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { buildUpstreamHeaders } from "../proxy.js";
+import { createDevOpsExtension } from "./devops-runtime.js";
+import { devOpsTarget } from "./devops-targets.js";
+const configuration = z
+    .object({
+    serverTargetId: z.string().min(1).max(128),
+    environment: z.string().min(1).max(128),
+    deployTargetId: z.string().min(1).max(128),
+    runtimeKind: z.enum(["aws-ecs", "aws-lambda", "aws-eks"]).default("aws-ecs"),
+    command: z.string().min(1),
+    args: z.array(z.string()).max(64).optional(),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    fixedArguments: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    provisioningScope: z
+        .object({
+        environment: z.string().min(1),
+        region: z.string().min(1),
+        namePrefix: z.string().min(1),
+        allowedImages: z.array(z.string().min(1)).min(1),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/** The host selects this protected file; MCP arguments cannot select executable paths or credentials. */
+export async function configuredDevOps(file, runtime, fetchImpl = fetch) {
+    if (!path.isAbsolute(file))
+        throw new Error("DevOps configuration requires an absolute host path");
+    const info = await lstat(file);
+    if (!info.isFile() || info.size > 65536 || (process.platform !== "win32" && (info.mode & 0o077) !== 0))
+        throw new Error("DevOps configuration must be a private, bounded regular file");
+    const config = configuration.parse(JSON.parse(await readFile(file, "utf8")));
+    const target = devOpsTarget(config.runtimeKind);
+    if (!path.isAbsolute(config.command) || (config.cwd && !path.isAbsolute(config.cwd)))
+        throw new Error("DevOps executable and working directory must be host-selected absolute paths");
+    if (config.provisioningScope && config.provisioningScope.environment !== config.environment)
+        throw new Error("Provisioning scope must match the configured environment");
+    let extension;
+    let closed = false;
+    async function get() {
+        if (closed)
+            throw new Error("Private integration closed");
+        if (!extension) {
+            extension = (async () => {
+                const connection = await runtime.resolve();
+                const base = new URL(connection.transport.remoteUrl);
+                if (!/\/mcp\/?$/.test(base.pathname))
+                    throw new Error("Private integration requires the canonical MCP endpoint");
+                base.pathname = base.pathname.replace(/mcp\/?$/, "");
+                base.search = "";
+                base.hash = "";
+                // Child operations use this same scoped agent credential. A separately configured
+                // human/admin key must never become a silent authority fallback.
+                if (!connection.transport.apiKey)
+                    throw new Error("A scoped private integration credential is required");
+                const authorize = async (action) => {
+                    const current = await runtime.resolve();
+                    requireSameConnection(connection, current);
+                    const response = await fetchImpl(new URL("api/v1/agent/devops/authorize", base), {
+                        method: "POST",
+                        redirect: "error",
+                        signal: AbortSignal.timeout(10000),
+                        headers: { ...buildUpstreamHeaders(current.transport), "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            targetId: config.serverTargetId,
+                            deployTargetId: config.deployTargetId,
+                            environment: config.environment,
+                            canonicalTool: action.canonicalTool,
+                            arguments: action.arguments,
+                        }),
+                    });
+                    if (!response.ok)
+                        throw new Error("Private integration unauthorized");
+                    const receipt = (await response.json());
+                    if (receipt.targetId !== config.serverTargetId ||
+                        receipt.deployTargetId !== config.deployTargetId ||
+                        receipt.environment !== config.environment)
+                        throw new Error("Private integration target changed");
+                    const legacyEcs = config.runtimeKind === "aws-ecs" && receipt.runtimeKind === undefined && receipt.backend === undefined;
+                    if (!legacyEcs && (receipt.runtimeKind !== config.runtimeKind || receipt.backend !== target.backend))
+                        throw new Error("Private integration runtime changed or is unsupported");
+                };
+                await authorize({ canonicalTool: null });
+                return createDevOpsExtension({
+                    ...config,
+                    env: {
+                        ...config.env,
+                        HONUA_DEVOPS_HONUA_API_BASE_URL: base.toString().replace(/\/$/, ""),
+                        HONUA_DEVOPS_HONUA_API_KEY: connection.transport.apiKey,
+                        HONUA_DEVOPS_TERRAFORM_TARGETS: target.terraformTarget,
+                        HONUA_DEVOPS_RUNTIME_KIND: config.runtimeKind,
+                        HONUA_DEVOPS_RUNTIME_BACKEND: target.backend,
+                        HONUA_DEVOPS_SERVER_TARGET_ID: config.serverTargetId,
+                        HONUA_DEVOPS_ALLOWED_ENVIRONMENTS: config.environment,
+                        HONUA_DEVOPS_DEPLOY_TARGET_ID: config.deployTargetId,
+                    },
+                }, authorize);
+            })();
+            const attempt = extension;
+            void attempt.catch(() => {
+                if (extension === attempt)
+                    extension = undefined;
+            });
+        }
+        return extension;
+    }
+    return {
+        async listTools() {
+            return (await get()).listTools();
+        },
+        async callTool(name, args, options) {
+            return (await get()).callTool(name, args, options);
+        },
+        async close() {
+            closed = true;
+            await extension?.then((value) => value.close()).catch(() => { });
+        },
+    };
+}
+function requireSameConnection(expected, actual) {
+    if (expected.target.id !== actual.target.id ||
+        expected.target.credentialId !== actual.target.credentialId ||
+        expected.transport.remoteUrl !== actual.transport.remoteUrl ||
+        expected.transport.apiKey !== actual.transport.apiKey)
+        throw new Error("Private integration identity changed; restart explicitly");
+}

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

@@ -0,0 +1,42 @@
+import { type CallToolResult, type Progress, type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type DevOpsRuntimeKind } from "./devops-targets.js";
+export declare const DEVOPS_TOOL_FAMILY = "honua.workspace.devops";
+/** Private provisioning/planning only. Day-2 operations remain on the server's canonical MCP surface. */
+export declare const DEVOPS_TOOL_ALLOWLIST: ReadonlySet<string>;
+export interface DevOpsExtension {
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+        onprogress?: (progress: Progress) => void;
+    }): Promise<CallToolResult>;
+    close(): Promise<void>;
+}
+/** Host configuration only. Never accept this configuration from an MCP tool argument. */
+export interface DevOpsProcessConfiguration {
+    command: string;
+    runtimeKind?: DevOpsRuntimeKind;
+    args?: string[];
+    cwd?: string;
+    /** Explicit child environment, including any operator credentials. Never returned to the model. */
+    env?: Record<string, string>;
+    /** Host-only bindings; absent path bindings hide handoff tools entirely. */
+    fixedArguments?: Record<string, Record<string, unknown>>;
+    provisioningScope?: {
+        environment: string;
+        region: string;
+        namePrefix: string;
+        allowedImages: string[];
+    };
+}
+export type DevOpsAuthorization = (action: {
+    canonicalTool: string | null;
+    arguments?: Readonly<Record<string, unknown>>;
+}) => Promise<void>;
+/**
+ * One optional private subprocess behind the existing public registration. Authorization is
+ * rechecked before EVERY discovery/action by the gateway against its current bound principal
+ * and target. Canonical handlers still enforce their own approval, audit and exact-plan gates.
+ * Errors are intentionally opaque; upstream exceptions may contain credentials or stderr.
+ */
+export declare function createDevOpsExtension(configuration: DevOpsProcessConfiguration, authorize: DevOpsAuthorization): DevOpsExtension;
+//# sourceMappingURL=devops-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"devops-runtime.d.ts","sourceRoot":"","sources":["../../../src/agent/devops-runtime.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,QAAQ,EACb,KAAK,IAAI,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,KAAK,iBAAiB,EAAgB,MAAM,qBAAqB,CAAC;AAG3E,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAC3D,yGAAyG;AACzG,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAgBpD,CAAC;AAEH,MAAM,WAAW,eAAe;IAC9B,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7B,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAA;KAAE,GAC5E,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,iBAAiB,CAAC,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;CACH;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE;IACzC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,0BAA0B,EACzC,SAAS,EAAE,mBAAmB,GAC7B,eAAe,CAoNjB"}

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

@@ -0,0 +1,242 @@
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CallToolResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { devOpsTarget } from "./devops-targets.js";
+const PREFIX = "honua_agent_devops_";
+export const DEVOPS_TOOL_FAMILY = "honua.workspace.devops";
+/** Private provisioning/planning only. Day-2 operations remain on the server's canonical MCP surface. */
+export const DEVOPS_TOOL_ALLOWLIST = new Set([
+    "describe_environment",
+    "find_recent_operations",
+    "provision_infrastructure",
+    "install_handoff",
+    "verify_install_handoff",
+    "plan_gitops_engine",
+    "generate_metadata_release_changeset",
+    "explain_metadata_release_changeset",
+    "plan_metadata_release_gitops",
+    "create_gitops_proposal",
+    "get_gitops_proposal",
+    "get_devops_operation_status",
+    "deploy_service_gitops",
+    "create_scoped_gitops_pull_request",
+    "revert_scoped_gitops_pull_request",
+]);
+/**
+ * One optional private subprocess behind the existing public registration. Authorization is
+ * rechecked before EVERY discovery/action by the gateway against its current bound principal
+ * and target. Canonical handlers still enforce their own approval, audit and exact-plan gates.
+ * Errors are intentionally opaque; upstream exceptions may contain credentials or stderr.
+ */
+export function createDevOpsExtension(configuration, authorize) {
+    if (!path.isAbsolute(configuration.command))
+        throw new Error("DevOps executable must be an absolute host path");
+    const runtimeKind = configuration.runtimeKind ?? "aws-ecs";
+    const target = devOpsTarget(runtimeKind);
+    // Copy configuration so a caller cannot silently change credentials/commands after binding.
+    const config = {
+        command: configuration.command,
+        args: [...(configuration.args ?? ["--mcp"])],
+        ...(configuration.cwd ? { cwd: configuration.cwd } : {}),
+        ...(configuration.env ? { env: { ...configuration.env } } : {}),
+    };
+    const bindings = structuredClone(configuration.fixedArguments ?? {});
+    const provisioningScope = configuration.provisioningScope
+        ? structuredClone(configuration.provisioningScope)
+        : undefined;
+    function enabled(name) {
+        if (name === "install_handoff")
+            return ["baseUrl", "adminKeySecretRef", "outputDirectory"].every((key) => typeof bindings[name]?.[key] === "string" && String(bindings[name][key]).length > 0);
+        if (name === "verify_install_handoff")
+            return (typeof bindings[name]?.handoffConfigPath === "string" && String(bindings[name].handoffConfigPath).length > 0);
+        if (name === "provision_infrastructure")
+            return Boolean(provisioningScope?.environment &&
+                provisioningScope.region &&
+                provisioningScope.namePrefix &&
+                provisioningScope.allowedImages.length);
+        return true;
+    }
+    function bindArguments(name, supplied) {
+        if (!enabled(name))
+            throw new Error("Host scope binding required");
+        const effective = structuredClone(supplied);
+        for (const [key, value] of Object.entries(bindings[name] ?? {})) {
+            if (effective[key] !== undefined &&
+                effective[key] !== "" &&
+                JSON.stringify(effective[key]) !== JSON.stringify(value))
+                throw new Error("Host argument binding mismatch");
+            effective[key] = value;
+        }
+        if (name === "provision_infrastructure") {
+            if (effective.stack !== runtimeKind || !provisioningScope)
+                throw new Error("Unsupported adapter");
+            if (effective.variablesJson !== undefined && typeof effective.variablesJson !== "string")
+                throw new Error("Invalid variable document type");
+            if (typeof effective.variablesJson === "string" && effective.variablesJson.length > 64 * 1024)
+                throw new Error("Variable document exceeds scope limit");
+            const variables = JSON.parse(typeof effective.variablesJson === "string" && effective.variablesJson.trim() ? effective.variablesJson : "{}");
+            if (!variables || typeof variables !== "object" || Array.isArray(variables))
+                throw new Error("Invalid variables");
+            const scoped = variables;
+            for (const [key, value] of Object.entries({
+                environment: provisioningScope.environment,
+                region: provisioningScope.region,
+                name_prefix: provisioningScope.namePrefix,
+            })) {
+                if (scoped[key] !== undefined && scoped[key] !== value)
+                    throw new Error("Cloud target scope mismatch");
+                scoped[key] = value;
+            }
+            const requireImage = (image) => {
+                if (typeof image !== "string" || !provisioningScope.allowedImages.includes(image))
+                    throw new Error("Image outside approved scope");
+            };
+            // Marketplace install.artifact.image overrides the flat Terraform variable.
+            // Validate that effective image too, rather than letting the nested input
+            // bypass the host's allowlist.
+            if (scoped.install !== undefined) {
+                if (!scoped.install || typeof scoped.install !== "object" || Array.isArray(scoped.install))
+                    throw new Error("Invalid install scope");
+                const artifact = scoped.install.artifact;
+                if (artifact !== undefined && artifact !== null) {
+                    if (typeof artifact !== "object" || Array.isArray(artifact))
+                        throw new Error("Invalid artifact scope");
+                    const image = artifact.image;
+                    if (image !== undefined && image !== null)
+                        requireImage(image);
+                }
+            }
+            if (target.imageVariable) {
+                if (scoped[target.imageVariable] !== undefined)
+                    requireImage(scoped[target.imageVariable]);
+                scoped[target.imageVariable] ??= provisioningScope.allowedImages[0];
+            }
+            for (const variable of ["honua_image", "honua_image_uri"]) {
+                if (variable !== target.imageVariable && scoped[variable] !== undefined)
+                    throw new Error("Image variable does not belong to the selected runtime");
+            }
+            effective.variablesJson = JSON.stringify(scoped);
+        }
+        return effective;
+    }
+    let pending;
+    let closed = false;
+    let progressToken = 0;
+    let generation = 0;
+    const secretValues = Object.entries(config.env ?? {})
+        .filter(([key, value]) => /secret|token|password|(?:^|_)key(?:$|_)|api_?key|credential|authorization|bearer/i.test(key) &&
+        value.length >= 4)
+        .map(([, value]) => value);
+    function scrub(value) {
+        return JSON.parse(JSON.stringify(value, (_key, field) => {
+            if (typeof field !== "string")
+                return field;
+            let text = field;
+            for (const secret of secretValues)
+                text = text.split(secret).join("[REDACTED]");
+            return text;
+        }));
+    }
+    async function connect() {
+        if (closed)
+            throw new Error("DevOps integration is closed");
+        if (!pending) {
+            const currentGeneration = ++generation;
+            pending = (async () => {
+                const client = new Client({ name: "honua-agent-devops", version: "1.0.0" }, { capabilities: {} });
+                client.onerror = () => { };
+                client.onclose = () => {
+                    if (generation === currentGeneration)
+                        pending = undefined;
+                };
+                // Ignore child stderr: operator diagnostics are not model-visible tool content.
+                const transport = new StdioClientTransport({ ...config, stderr: "ignore" });
+                try {
+                    await client.connect(transport);
+                    if (closed)
+                        throw new Error("closed");
+                    return client;
+                }
+                catch {
+                    await client.close().catch(() => { });
+                    throw new Error("Private DevOps connection failed");
+                }
+            })();
+            // A failed handshake can be retried, but a tool call is NEVER automatically replayed.
+            const attempt = pending;
+            void attempt.catch(() => {
+                if (pending === attempt)
+                    pending = undefined;
+            });
+        }
+        return pending;
+    }
+    async function catalog(client) {
+        const tools = [];
+        const cursors = new Set();
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {});
+            for (const tool of page.tools) {
+                if (!DEVOPS_TOOL_ALLOWLIST.has(tool.name) || !enabled(tool.name))
+                    continue;
+                if (tools.some((existing) => existing.name === tool.name))
+                    throw new Error("Duplicate private tool");
+                tools.push(tool);
+            }
+            cursor = page.nextCursor;
+            if (cursor && cursors.has(cursor))
+                throw new Error("Invalid private tool cursor");
+            if (cursor)
+                cursors.add(cursor);
+            if (cursors.size > 100)
+                throw new Error("Private tool catalog too large");
+        } while (cursor);
+        return tools;
+    }
+    return {
+        async listTools() {
+            try {
+                await authorize({ canonicalTool: null });
+                const tools = await catalog(await connect());
+                return scrub(tools.map((tool) => ({
+                    ...tool,
+                    name: `${PREFIX}${tool.name}`,
+                    _meta: { ...tool._meta, "honua.studio": { family: DEVOPS_TOOL_FAMILY, view: "workspace", revision: "1" } },
+                })));
+            }
+            catch {
+                throw new Error("Private DevOps discovery unavailable or unauthorized");
+            }
+        },
+        async callTool(name, args, options) {
+            const canonicalTool = name.startsWith(PREFIX) ? name.slice(PREFIX.length) : "";
+            if (!DEVOPS_TOOL_ALLOWLIST.has(canonicalTool))
+                throw new Error("Unsupported private DevOps tool");
+            try {
+                const effectiveArguments = bindArguments(canonicalTool, args);
+                await authorize({ canonicalTool, arguments: effectiveArguments });
+                const client = await connect();
+                // Discover afresh: do not use a stale descriptor after a target/policy change.
+                if (!(await catalog(client)).some((tool) => tool.name === canonicalTool))
+                    throw new Error("Private DevOps capability unavailable");
+                return scrub(await client.request({
+                    method: "tools/call",
+                    params: {
+                        name: canonicalTool,
+                        arguments: effectiveArguments,
+                        ...(options?.onprogress ? { _meta: { progressToken: ++progressToken } } : {}),
+                    },
+                }, CallToolResultSchema, { signal: options?.signal, onprogress: options?.onprogress }));
+            }
+            catch {
+                throw new Error("Private DevOps action failed or unauthorized; reconcile canonical operation state before retry");
+            }
+        },
+        async close() {
+            closed = true;
+            await pending?.then((client) => client.close()).catch(() => { });
+        },
+    };
+}

package/dist/src/agent/devops-targets.d.ts

@@ -0,0 +1,33 @@
+/** Host-selected runtimes and their canonical server actuators, never model-selected backends. */
+export declare const DEVOPS_TARGETS: {
+    readonly "aws-ecs": {
+        readonly backend: "honua-aws-ecs-alb";
+        readonly terraformTarget: "ecs";
+        readonly imageVariable: "honua_image";
+    };
+    readonly "aws-lambda": {
+        readonly backend: "honua-gitops-aws-lambda";
+        readonly terraformTarget: "lambda";
+        readonly imageVariable: "honua_image_uri";
+    };
+    readonly "aws-eks": {
+        readonly backend: "honua-kubernetes-deployment";
+        readonly terraformTarget: "eks";
+        readonly imageVariable: undefined;
+    };
+};
+export type DevOpsRuntimeKind = keyof typeof DEVOPS_TARGETS;
+export declare function devOpsTarget(runtimeKind?: DevOpsRuntimeKind): {
+    readonly backend: "honua-aws-ecs-alb";
+    readonly terraformTarget: "ecs";
+    readonly imageVariable: "honua_image";
+} | {
+    readonly backend: "honua-gitops-aws-lambda";
+    readonly terraformTarget: "lambda";
+    readonly imageVariable: "honua_image_uri";
+} | {
+    readonly backend: "honua-kubernetes-deployment";
+    readonly terraformTarget: "eks";
+    readonly imageVariable: undefined;
+};
+//# sourceMappingURL=devops-targets.d.ts.map

package/dist/src/agent/devops-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devops-targets.d.ts","sourceRoot":"","sources":["../../../src/agent/devops-targets.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAkBjB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAE5D,wBAAgB,YAAY,CAAC,WAAW,GAAE,iBAA6B;;;;;;;;;;;;EAGtE"}

package/dist/src/agent/devops-targets.js

@@ -0,0 +1,25 @@
+/** Host-selected runtimes and their canonical server actuators, never model-selected backends. */
+export const DEVOPS_TARGETS = {
+    "aws-ecs": {
+        backend: "honua-aws-ecs-alb",
+        terraformTarget: "ecs",
+        imageVariable: "honua_image",
+    },
+    "aws-lambda": {
+        backend: "honua-gitops-aws-lambda",
+        terraformTarget: "lambda",
+        imageVariable: "honua_image_uri",
+    },
+    "aws-eks": {
+        backend: "honua-kubernetes-deployment",
+        terraformTarget: "eks",
+        // The EKS infrastructure root does not install the application. Its separate
+        // workload handoff must verify the actual Deployment, Service and cluster identity.
+        imageVariable: undefined,
+    },
+};
+export function devOpsTarget(runtimeKind = "aws-ecs") {
+    if (!Object.hasOwn(DEVOPS_TARGETS, runtimeKind))
+        throw new Error("Unsupported private deployment runtime");
+    return DEVOPS_TARGETS[runtimeKind];
+}