@wardby/cli 0.5.3 → 0.6.0

package/dist/mcp/tools/secrets.js

@@ -4,26 +4,109 @@
  * value/ciphertext at the source); this file adds ownership on top.
  */
 import { inputRequired, inputResponse } from "@modelcontextprotocol/server";
-import { createSecret, listSecrets, attachSecret, detachSecret, deleteSecret } from "../../core/secrets.js";
+import { createSecret, listSecrets, attachSecret, detachSecret, deleteSecret, setSecretBroker, } from "../../core/secrets.js";
+import { brokerConfigHash, parseSecretBrokerConfig } from "../../core/secret-broker-config.js";
 import { McpError } from "../errors.js";
 import { requireOwnedSecret } from "../auth/ownership.js";
 import { requireAgentAccess, requireBindingOwner } from "../auth/access.js";
-import { getSecretElicitationOutcome } from "./secret-elicitation.js";
+import { clearUnbrokerOutcome, getSecretElicitationOutcome, } from "./secret-elicitation.js";
+import { allowedSecretNames, brokerCompatibilityWarnings } from "./secret-broker-compat.js";
 import { textResult } from "./text-result.js";
+const BROKER_SCHEMA_DOC = '{ hosts: exact hostnames, pathPrefixes?: ["/..."], placement: { kind: "header", name, format containing {value} } | { kind: "query", name } | { kind: "body", field } | { kind: "aws-sigv4", region, service } }';
+/** Validates a caller-supplied broker config; an invalid one is the caller's 400. */
+function parseBrokerArg(input) {
+    try {
+        return parseSecretBrokerConfig(input);
+    }
+    catch (err) {
+        throw new McpError(400, err instanceof Error ? err.message : String(err));
+    }
+}
+/** Maps core/secrets.ts's coded errors to MCP statuses; anything else propagates unchanged. */
+function mapSecretError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.startsWith("secret_not_found"))
+        throw new McpError(404, message);
+    if (message.startsWith("secret_broker_config_invalid") || message.startsWith("secret_broker_value_invalid")) {
+        throw new McpError(400, message);
+    }
+    throw err;
+}
+/**
+ * Non-blocking warnings: tools that can see this secret (under any alias it is
+ * attached as) but still read it with secrets.get(), which a brokered secret refuses.
+ */
+async function brokerWarningsForSecret(db, ownerId, name) {
+    const bindings = await db.agentSecret.findMany({
+        where: { secret: { ownerId, name } },
+        select: { agentId: true, boundName: true },
+    });
+    if (!bindings.length)
+        return [];
+    const aliasesByAgent = new Map();
+    for (const b of bindings) {
+        const aliases = aliasesByAgent.get(b.agentId) ?? new Set();
+        aliases.add(b.boundName);
+        aliasesByAgent.set(b.agentId, aliases);
+    }
+    const attachments = await db.agentTool.findMany({
+        where: { agentId: { in: [...aliasesByAgent.keys()] } },
+        include: { tool: { select: { name: true, code: true } } },
+    });
+    const warnings = new Set();
+    for (const a of attachments) {
+        const tools = [{ name: a.tool.name, code: a.tool.code, allowedSecrets: allowedSecretNames(a.allowedSecrets) }];
+        for (const w of brokerCompatibilityWarnings(tools, aliasesByAgent.get(a.agentId)))
+            warnings.add(w);
+    }
+    return [...warnings];
+}
+function withWarnings(body, warnings) {
+    return warnings.length ? { ...body, warnings } : body;
+}
+async function findOwnSecret(ctx, name) {
+    const secret = await ctx.db.secret.findUnique({ where: { ownerId_name: { ownerId: ctx.principal.id, name } } });
+    if (!secret)
+        throw new McpError(404, `secret_not_found: no secret named "${name}"`);
+    return secret;
+}
 export function registerSecretsTools(mcp, opts) {
     mcp.registerTool({
         name: "create_secret",
         scope: "secrets:write",
-        description: 'Creates a secret. Omit "value" to enter it securely via a one-time browser link instead of passing it as a plaintext argument.',
+        description: 'Creates a secret. Omit "value" to enter it securely via a one-time browser link instead of passing it as a plaintext argument. Pass "broker" ({ hosts, pathPrefixes?, placement }) to make it brokered: tools can then only send it to those hosts with fetch(url, { secrets: [name] }) and can never read it. See the help article "brokered-secrets".',
         inputSchema: {
             type: "object",
-            properties: { name: { type: "string" }, value: { type: "string" } },
+            properties: {
+                name: { type: "string" },
+                value: { type: "string" },
+                broker: { type: "object", description: `Optional broker config: ${BROKER_SCHEMA_DOC}` },
+            },
             required: ["name"],
         },
         handler: async (args, ctx) => {
+            const broker = args.broker === undefined ? undefined : parseBrokerArg(args.broker);
             if (args.value !== undefined) {
-                const secret = await createSecret(args.name, args.value, ctx.principal.id, ctx.providers.secrets, ctx.db);
-                return textResult({ id: secret.id, name: secret.name, keyId: secret.keyId, createdAt: secret.createdAt });
+                let secret;
+                try {
+                    secret = await createSecret(args.name, args.value, ctx.principal.id, ctx.providers.secrets, ctx.db, {
+                        broker,
+                        via: "mcp",
+                    });
+                }
+                catch (err) {
+                    mapSecretError(err);
+                }
+                // A fresh broker config supersedes any earlier, browser-confirmed removal still on record.
+                if (broker)
+                    await clearUnbrokerOutcome(ctx.principal.id, args.name, ctx.db);
+                return textResult({
+                    id: secret.id,
+                    name: secret.name,
+                    keyId: secret.keyId,
+                    createdAt: secret.createdAt,
+                    broker: secret.broker == null ? null : parseSecretBrokerConfig(secret.broker),
+                });
             }
             if (opts.protocolElicitation) {
                 const state = ctx.mcpReq.requestState();
@@ -43,7 +126,12 @@ export function registerSecretsTools(mcp, opts) {
                     throw new McpError(400, existingOutcome.error);
                 return textResult(existingOutcome.secret);
             }
-            const payload = { ownerId: ctx.principal.id, secretName: args.name };
+            const payload = {
+                ownerId: ctx.principal.id,
+                secretName: args.name,
+                kind: "create",
+                ...(broker ? { broker } : {}),
+            };
             const token = await mcp.mintRequestState(payload);
             const url = await opts.buildElicitationUrl(token);
             if (opts.protocolElicitation) {
@@ -66,6 +154,95 @@ export function registerSecretsTools(mcp, opts) {
             });
         },
     });
+    mcp.registerTool({
+        name: "set_secret_broker",
+        scope: "secrets:write",
+        description: 'Sets or changes a secret\'s broker config ({ hosts, pathPrefixes?, placement }), so tools can only send it to those hosts with fetch(url, { secrets: [name] }) and never read it. broker: null removes brokering, which must be confirmed by a person in the browser link this returns. Every change is audited. See the help article "brokered-secrets".',
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                broker: {
+                    type: ["object", "null"],
+                    description: `The broker config ${BROKER_SCHEMA_DOC}, or null to remove brokering (browser-confirmed).`,
+                },
+            },
+            required: ["name", "broker"],
+        },
+        handler: async (args, ctx) => {
+            const ownerId = ctx.principal.id;
+            if (args.broker !== null) {
+                const broker = parseBrokerArg(args.broker);
+                await findOwnSecret(ctx, args.name);
+                let change;
+                try {
+                    change = await setSecretBroker(ctx.db, ctx.providers.secrets, {
+                        ownerId,
+                        name: args.name,
+                        broker,
+                        actorId: ownerId,
+                        via: "mcp",
+                    });
+                }
+                catch (err) {
+                    mapSecretError(err);
+                }
+                await clearUnbrokerOutcome(ownerId, args.name, ctx.db);
+                const warnings = await brokerWarningsForSecret(ctx.db, ownerId, args.name);
+                return textResult(withWarnings({ name: args.name, before: change.before, broker: change.after }, warnings));
+            }
+            // broker: null — never removed here. Only a person submitting the
+            // browser form (fulfillUnbrokerElicitation) removes it; this call hands
+            // out the link and, once that has happened, reports it.
+            if (opts.protocolElicitation) {
+                const state = ctx.mcpReq.requestState();
+                if (state) {
+                    const view = inputResponse(ctx.mcpReq.inputResponses, "confirmUnbroker");
+                    if (view.kind === "elicit" && view.action !== "accept") {
+                        throw new McpError(400, `Removing brokering was ${view.action}d.`);
+                    }
+                }
+            }
+            const existingOutcome = await getSecretElicitationOutcome(ownerId, args.name, ctx.db, "unbroker");
+            if (existingOutcome) {
+                if (!existingOutcome.ok)
+                    mapSecretError(new Error(existingOutcome.error));
+                return textResult({ unbrokered: true, secret: existingOutcome.secret });
+            }
+            const secret = await findOwnSecret(ctx, args.name);
+            if (secret.broker == null) {
+                // Nothing to remove, so nothing for a person to confirm.
+                const metadata = (await listSecrets(ownerId, ctx.db)).find((s) => s.id === secret.id);
+                return textResult({ unbrokered: true, secret: metadata });
+            }
+            // The hash pins the link to the config being confirmed: if it changes before
+            // the person submits, fulfillUnbrokerElicitation refuses (secret_broker_changed).
+            const payload = {
+                ownerId,
+                secretName: args.name,
+                kind: "unbroker",
+                brokerHash: brokerConfigHash(parseSecretBrokerConfig(secret.broker)),
+            };
+            const token = await mcp.mintRequestState(payload);
+            const url = await opts.buildElicitationUrl(token);
+            if (opts.protocolElicitation) {
+                return inputRequired({
+                    requestState: token,
+                    inputRequests: {
+                        confirmUnbroker: inputRequired.elicitUrl({
+                            url,
+                            message: `Confirm removing brokering for secret "${args.name}" in your browser.`,
+                        }),
+                    },
+                });
+            }
+            return textResult({
+                status: "pending",
+                message: `Open this link in your browser to confirm removing brokering for secret "${args.name}", then call set_secret_broker again with broker: null to finish.`,
+                url,
+            });
+        },
+    });
     mcp.registerTool({
         name: "list_secrets",
         scope: "secrets:write",

package/dist/mcp/tools/tools.d.ts

@@ -25,8 +25,8 @@ export declare function projectTool(tool: Tool, principalId: string): {
     id: string;
     ownerId: string | null;
     description: string;
-    paramsZod: string;
     jsonSchema: import("@prisma/client/runtime/client").JsonValue;
+    paramsZod: string;
 } | {
     id: string;
     name: string;

package/dist/mcp/tools/tools.js

@@ -21,6 +21,7 @@ import { requireOwnedTool, requireStrictlyOwnedTool, assertStrictlyOwnedTool, vi
 import { agentAccessResolver, assertAgentAccess, requireAgentAccess } from "../auth/access.js";
 import { atLeast } from "../../core/grants.js";
 import { textResult } from "./text-result.js";
+import { brokerCompatibilityWarnings } from "./secret-broker-compat.js";
 /**
  * Names the agents the caller can read (its own and ones granted to it)
  * and only counts the rest, so a refusal never reveals another principal's
@@ -48,6 +49,22 @@ export function projectTool(tool, principalId) {
         ? { id: tool.id, name: tool.name, description: tool.description, public: true }
         : { id: tool.id, name: tool.name, description: tool.description, public: false, ownerIsCaller: false };
 }
+/**
+ * Non-blocking: which of the secrets just granted to this attachment are
+ * brokered on the agent, and does the tool still read them with
+ * secrets.get()? Reveals only that fact about a tool the caller may not own
+ * (attach_tool already lets the agent's owner grant capabilities to such code).
+ */
+async function brokeredSecretWarnings(db, agentId, tool, allowedSecrets) {
+    if (!tool || !allowedSecrets?.length)
+        return [];
+    const bindings = await db.agentSecret.findMany({
+        where: { agentId, boundName: { in: [...allowedSecrets] } },
+        include: { secret: { select: { broker: true } } },
+    });
+    const brokered = new Set(bindings.filter((b) => b.secret.broker != null).map((b) => b.boundName));
+    return brokerCompatibilityWarnings([{ ...tool, allowedSecrets }], brokered);
+}
 /** Refuses a name one of the runner's built-ins would shadow (see core/tool-names.ts). */
 function assertToolNameAllowed(name) {
     const reason = reservedToolNameReason(name);
@@ -232,7 +249,7 @@ export function registerToolAuthoringTools(mcp) {
     mcp.registerTool({
         name: "attach_tool",
         scope: "tools:write",
-        description: "Attaches a tool to an agent (needs write on the agent). The four capability fields (allowedSecrets, allowedDatastorePrefixes, allowedHosts, allowedSharedDatastorePrefixes) are the agent owner's to grant: anyone else passing one gets 403, and their attachment runs with none until the owner re-runs attach_tool with the capabilities. When the owner grants an attachment it had not granted before (someone else attached it, or the agent changed owner), every capability not passed is reset to empty, so state each one you want. Granting capabilities to a tool someone else owns vouches for code you can't read (only its owner sees it); the tool's owner can't change it while it's attached to your agent, and detaching drops your grant.",
+        description: "Attaches a tool to an agent (needs write on the agent). The four capability fields (allowedSecrets, allowedDatastorePrefixes, allowedHosts, allowedSharedDatastorePrefixes) are the agent owner's to grant: anyone else passing one gets 403, and their attachment runs with none until the owner re-runs attach_tool with the capabilities. When the owner grants an attachment it had not granted before (someone else attached it, or the agent changed owner), every capability not passed is reset to empty, so state each one you want. Granting capabilities to a tool someone else owns vouches for code you can't read (only its owner sees it); the tool's owner can't change it while it's attached to your agent, and detaching drops your grant. Granting a brokered secret lets the tool send it only via fetch(url, { secrets: [name] }), never read it; the result includes warnings when the tool calls secrets.get() on one.",
         inputSchema: {
             type: "object",
             properties: {
@@ -263,6 +280,7 @@ export function registerToolAuthoringTools(mcp) {
                 throw new McpError(400, `Invalid tool capabilities: ${patch.error.issues.map((i) => i.message).join("; ")}`);
             }
             const capabilitiesPassed = Object.values(patch.data).some((value) => value !== undefined);
+            let attachedTool;
             await ctx.db.$transaction(async (tx) => {
                 const { agent } = await assertAgentAccess(ctx, await tx.agent.findUnique({ where: { id: args.agentId } }), args.agentId, "write", tx);
                 if (agent.kind === "coding") {
@@ -290,6 +308,7 @@ export function registerToolAuthoringTools(mcp) {
                 // The runtime dispatches by name, and names are only unique per
                 // owner: a second same-named tool on one agent would be a
                 // duplicate tool name to the model and silently shadow one of them.
+                attachedTool = { name: tool.name, code: tool.code };
                 const clash = await findSameNamedAttachedTool(tx, args.agentId, tool);
                 if (clash) {
                     // The clashing tool may be another principal's private one (a
@@ -330,7 +349,8 @@ export function registerToolAuthoringTools(mcp) {
                     update: ownerGrant,
                 });
             }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
-            return textResult({ attached: true });
+            const warnings = await brokeredSecretWarnings(ctx.db, args.agentId, attachedTool, patch.data.allowedSecrets);
+            return textResult(warnings.length ? { attached: true, warnings } : { attached: true });
         },
     });
     mcp.registerTool({

package/dist/native-worker/composition.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Builds the native sandbox executor from configuration (NATIVE_SANDBOX_*, docs/native-sandbox.md),
+ * or nothing when the native sandbox is not configured — sandbox-mode runs then fail closed.
+ */
+import { type Power } from "../core/power.js";
+import type { NativeRunProviders, RunnerDb } from "../core/runner.js";
+import { type GatewayLedgerDb } from "./ledger.js";
+import type { KubernetesApi } from "../providers/jobs/kubernetes-api.js";
+import { NativeSandboxExecutor, type ManagedWorkerLauncher } from "./sandbox-executor.js";
+import { type WarmWorkerLauncher } from "./warm-pool.js";
+import { type WarmPoolDb } from "./warm-pool-ledger.js";
+export declare function buildNativeSandboxExecutor(options: {
+    db: RunnerDb & GatewayLedgerDb & WarmPoolDb;
+    /** Read at call time: the composition root patches `executor` on after wrapping this one. */
+    providers: NativeRunProviders;
+    env?: NodeJS.ProcessEnv;
+    /** Tests only: replaces the launcher. */
+    launcher?: ManagedWorkerLauncher & Partial<WarmWorkerLauncher>;
+    /** Tests only: replaces the kubeconfig-backed client for NATIVE_SANDBOX_LAUNCHER=kubernetes. */
+    kubernetesApi?: KubernetesApi;
+    /** Low-power mode: the shared Power the Kubernetes launcher wakes the native gateway through. */
+    power?: Power;
+}): NativeSandboxExecutor | undefined;

package/dist/native-worker/composition.js

@@ -0,0 +1,77 @@
+/**
+ * Builds the native sandbox executor from configuration (NATIVE_SANDBOX_*, docs/native-sandbox.md),
+ * or nothing when the native sandbox is not configured — sandbox-mode runs then fail closed.
+ */
+import { loadNativeSandboxConfig } from "../config/providers.js";
+import { DISABLED_POWER } from "../core/power.js";
+import { lowPowerActive } from "../core/power-composition.js";
+import { nativeGatewayUrl } from "./docker-isolation.js";
+import { DockerNativeWorkerLauncher } from "./docker-launcher.js";
+import { PrismaGatewayLedger } from "./ledger.js";
+import { KubernetesNativeWorkerLauncher } from "./kubernetes-launcher.js";
+import { ClientNodeKubernetesApi } from "../providers/jobs/kubernetes-client.js";
+import { SANDBOX_RUN_MAX_SEC } from "../core/runner.js";
+import { NativeSandboxExecutor } from "./sandbox-executor.js";
+import { PooledWorkerLauncher } from "./warm-pool.js";
+import { PrismaWarmPoolLedger } from "./warm-pool-ledger.js";
+export function buildNativeSandboxExecutor(options) {
+    const env = options.env ?? process.env;
+    const config = loadNativeSandboxConfig(env);
+    if (!config)
+        return undefined;
+    // Only when low-power mode is actually on (as buildPower decides); otherwise it is ignored.
+    if (config.warmPoolSize > 0 && lowPowerActive(env)) {
+        throw new Error("WARDBY_LOW_POWER=1 requires NATIVE_SANDBOX_WARM_POOL_SIZE=0: an always-on warm pool defeats scale-to-zero.");
+    }
+    const limits = { cpus: config.cpus, memoryMb: config.memoryMb, pids: config.pids };
+    const markReady = (runId) => new PrismaGatewayLedger(options.db).markNetworkReadyForRun(runId);
+    const cold = options.launcher ??
+        (config.launcher === "kubernetes"
+            ? new KubernetesNativeWorkerLauncher({
+                api: options.kubernetesApi ?? new ClientNodeKubernetesApi({ context: config.context }),
+                namespace: config.namespace,
+                image: config.workerImage,
+                limits,
+                gatewayService: config.gatewayService,
+                runtimeClassName: config.runtimeClassName,
+                platform: config.platform,
+                priorityClassName: config.priorityClassName,
+                readyTimeoutMs: config.readyTimeoutMs,
+                enforcementTimeoutMs: config.enforcementTimeoutMs,
+                gatewayUrl: config.gatewayUrl,
+                deadlineSeconds: SANDBOX_RUN_MAX_SEC,
+                power: options.power ?? DISABLED_POWER,
+                // Isolation proven inside the pod: the gateway may now serve the run.
+                onNetworkProven: markReady,
+            })
+            : new DockerNativeWorkerLauncher({
+                image: config.workerImage,
+                gatewayContainer: config.gatewayContainer,
+                limits,
+            }));
+    // The pool also starts with size 0 when the launcher can run one: its first tick removes workers
+    // left from an earlier configuration, and nothing runs after that.
+    const launcher = isWarmCapable(cold)
+        ? new PooledWorkerLauncher({
+            ledger: new PrismaWarmPoolLedger(options.db),
+            launcher: cold,
+            size: config.warmPoolSize,
+            maxAgeMs: config.warmMaxAgeMs,
+            warmTimeoutMs: config.launcher === "kubernetes"
+                ? (config.readyTimeoutMs ?? 120_000) + (config.enforcementTimeoutMs ?? 30_000)
+                : 120_000,
+            onDelivered: markReady,
+        })
+        : cold;
+    return new NativeSandboxExecutor({
+        db: options.db,
+        providers: options.providers,
+        launcher,
+        // Kubernetes resolves the gateway's ClusterIP per launch (resolveGatewayUrl) unless overridden.
+        gatewayUrl: config.gatewayUrl ?? nativeGatewayUrl(),
+        maxConcurrent: config.maxConcurrent,
+    });
+}
+function isWarmCapable(launcher) {
+    return typeof launcher.startWarm === "function" && typeof launcher.deliver === "function";
+}

package/dist/native-worker/docker-isolation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Docker objects for one sandbox-mode native run (docs/native-sandbox.md),
+ * built the way the coding launcher builds its own (providers/jobs/
+ * docker-isolation.ts): an internal per-run network whose only other member is
+ * the native gateway container, and a single-use worker container that can
+ * reach nothing else — no internet, no database, no Docker socket. Names carry
+ * an opaque hash of the run id, never the id itself.
+ */
+export declare const NATIVE_WORKER_UID = 10001;
+export declare const NATIVE_GATEWAY_ALIAS = "wardby-native-gateway";
+export declare const NATIVE_GATEWAY_PORT = 8790;
+/** The gateway's witness port: never reachable from a worker (see coding-proxy/deny-port.ts). */
+export declare const NATIVE_GATEWAY_DENY_PORT = 8791;
+export declare const NATIVE_WORKER_TMP_MB = 64;
+export interface NativeWorkerLimits {
+    cpus: number;
+    memoryMb: number;
+    pids: number;
+}
+export declare const DEFAULT_NATIVE_WORKER_LIMITS: NativeWorkerLimits;
+export interface NativeIsolationNames {
+    network: string;
+    worker: string;
+}
+export declare function nativeIsolationNames(runId: string): NativeIsolationNames;
+/** The label value tying a Docker object to its run, without exposing the run id. */
+export declare function nativeRunLabel(runId: string): string;
+/** A warm pool worker's name (native sandbox phase 6): its random token, never a run's hash. */
+export declare function nativeWarmWorkerName(token: string): string;
+export declare function nativeWarmIsolationNames(token: string): NativeIsolationNames;
+/** Docker's label filter for every warm pool object, and the label carrying its token. */
+export declare const NATIVE_WARM_LABEL_FILTER = "io.wardby.pool=warm";
+export declare const NATIVE_WARM_TOKEN_LABEL = "io.wardby.warm-worker";
+/** Docker's label filter for every native worker object (the janitor lists by it). */
+export declare const NATIVE_WORKER_LABEL_FILTER = "io.wardby.component=native-worker";
+export declare function buildNativeNetworkCreateArgs(runId: string): string[];
+export declare function buildNativeWarmNetworkCreateArgs(token: string): string[];
+/** Joins the gateway container to the run's network under the name workers dial. */
+export declare function buildGatewayConnectArgs(runId: string, gatewayContainer: string): string[];
+export declare function gatewayConnectArgs(network: string, gatewayContainer: string): string[];
+export declare function buildGatewayDisconnectArgs(runId: string, gatewayContainer: string): string[];
+export declare function gatewayDisconnectArgs(network: string, gatewayContainer: string): string[];
+/**
+ * `docker run -i` for the worker: its WorkerInput (capability included) arrives on stdin, so the
+ * capability is never in its environment, argv, labels, or `docker inspect`. Not `--rm`: the
+ * executor reads the exit code, then removes it.
+ */
+export declare function buildNativeWorkerRunArgs(input: {
+    runId: string;
+    image: string;
+    limits: NativeWorkerLimits;
+}): string[];
+/**
+ * `docker run -d` for a warm pool worker: no input yet. It waits for one written into its /tmp by
+ * `docker exec -i` after a run claims it (warm-delivery.ts), so the capability still never reaches
+ * its environment, argv, or labels.
+ */
+export declare function buildNativeWarmWorkerRunArgs(input: {
+    token: string;
+    image: string;
+    limits: NativeWorkerLimits;
+    waitMs: number;
+}): string[];
+/** The URL a worker dials: the gateway's alias on its own run network. */
+export declare function nativeGatewayUrl(port?: number): string;

package/dist/native-worker/docker-isolation.js

@@ -0,0 +1,183 @@
+/**
+ * Docker objects for one sandbox-mode native run (docs/native-sandbox.md),
+ * built the way the coding launcher builds its own (providers/jobs/
+ * docker-isolation.ts): an internal per-run network whose only other member is
+ * the native gateway container, and a single-use worker container that can
+ * reach nothing else — no internet, no database, no Docker socket. Names carry
+ * an opaque hash of the run id, never the id itself.
+ */
+import { isImmutableDockerImage, isolationToken } from "../providers/jobs/docker-isolation.js";
+import { createHash } from "node:crypto";
+import { WARM_INPUT_FILE } from "./warm-delivery.js";
+export const NATIVE_WORKER_UID = 10001;
+export const NATIVE_GATEWAY_ALIAS = "wardby-native-gateway";
+export const NATIVE_GATEWAY_PORT = 8790;
+/** The gateway's witness port: never reachable from a worker (see coding-proxy/deny-port.ts). */
+export const NATIVE_GATEWAY_DENY_PORT = 8791;
+export const NATIVE_WORKER_TMP_MB = 64;
+const LABEL_MANAGED = "io.wardby.managed=true";
+const LABEL_COMPONENT = "io.wardby.component=native-worker";
+export const DEFAULT_NATIVE_WORKER_LIMITS = { cpus: 1, memoryMb: 512, pids: 128 };
+export function nativeIsolationNames(runId) {
+    const token = isolationToken(runId);
+    return { network: `wardby-nnet-${token}`, worker: `wardby-native-${token}` };
+}
+/** The label value tying a Docker object to its run, without exposing the run id. */
+export function nativeRunLabel(runId) {
+    return createHash("sha256").update(runId).digest("hex");
+}
+function labels(runId) {
+    return [
+        "--label",
+        LABEL_MANAGED,
+        "--label",
+        LABEL_COMPONENT,
+        "--label",
+        `io.wardby.run-sha256=${nativeRunLabel(runId)}`,
+    ];
+}
+/** A warm pool worker's name (native sandbox phase 6): its random token, never a run's hash. */
+export function nativeWarmWorkerName(token) {
+    if (!/^[0-9a-f]{20}$/.test(token))
+        throw new Error("native_sandbox_invalid_warm_token");
+    return `wardby-nwarm-${token}`;
+}
+export function nativeWarmIsolationNames(token) {
+    return { network: `wardby-nwnet-${token}`, worker: nativeWarmWorkerName(token) };
+}
+/** Docker's label filter for every warm pool object, and the label carrying its token. */
+export const NATIVE_WARM_LABEL_FILTER = "io.wardby.pool=warm";
+export const NATIVE_WARM_TOKEN_LABEL = "io.wardby.warm-worker";
+function warmLabels(token) {
+    return [
+        "--label",
+        LABEL_MANAGED,
+        "--label",
+        LABEL_COMPONENT,
+        "--label",
+        NATIVE_WARM_LABEL_FILTER,
+        "--label",
+        `${NATIVE_WARM_TOKEN_LABEL}=${token}`,
+    ];
+}
+/** Docker's label filter for every native worker object (the janitor lists by it). */
+export const NATIVE_WORKER_LABEL_FILTER = LABEL_COMPONENT;
+export function buildNativeNetworkCreateArgs(runId) {
+    return networkCreateArgs(nativeIsolationNames(runId).network, labels(runId));
+}
+export function buildNativeWarmNetworkCreateArgs(token) {
+    return networkCreateArgs(nativeWarmIsolationNames(token).network, warmLabels(token));
+}
+function networkCreateArgs(network, objectLabels) {
+    return [
+        "network",
+        "create",
+        "--driver",
+        "bridge",
+        "--internal",
+        "--ipv6=false",
+        "--opt",
+        "com.docker.network.bridge.gateway_mode_ipv4=isolated",
+        "--opt",
+        "com.docker.network.bridge.gateway_mode_ipv6=isolated",
+        ...objectLabels,
+        network,
+    ];
+}
+/** Joins the gateway container to the run's network under the name workers dial. */
+export function buildGatewayConnectArgs(runId, gatewayContainer) {
+    return gatewayConnectArgs(nativeIsolationNames(runId).network, gatewayContainer);
+}
+export function gatewayConnectArgs(network, gatewayContainer) {
+    return ["network", "connect", "--alias", NATIVE_GATEWAY_ALIAS, network, gatewayContainer];
+}
+export function buildGatewayDisconnectArgs(runId, gatewayContainer) {
+    return gatewayDisconnectArgs(nativeIsolationNames(runId).network, gatewayContainer);
+}
+export function gatewayDisconnectArgs(network, gatewayContainer) {
+    return ["network", "disconnect", "--force", network, gatewayContainer];
+}
+/**
+ * `docker run -i` for the worker: its WorkerInput (capability included) arrives on stdin, so the
+ * capability is never in its environment, argv, labels, or `docker inspect`. Not `--rm`: the
+ * executor reads the exit code, then removes it.
+ */
+export function buildNativeWorkerRunArgs(input) {
+    const names = nativeIsolationNames(input.runId);
+    return workerRunArgs({ ...input, names, mode: ["-i"], env: [], objectLabels: labels(input.runId) });
+}
+/**
+ * `docker run -d` for a warm pool worker: no input yet. It waits for one written into its /tmp by
+ * `docker exec -i` after a run claims it (warm-delivery.ts), so the capability still never reaches
+ * its environment, argv, or labels.
+ */
+export function buildNativeWarmWorkerRunArgs(input) {
+    return workerRunArgs({
+        ...input,
+        names: nativeWarmIsolationNames(input.token),
+        mode: ["-d"],
+        env: [
+            "--env",
+            `NATIVE_WORKER_INPUT_FILE=${WARM_INPUT_FILE}`,
+            "--env",
+            `NATIVE_WORKER_INPUT_WAIT_MS=${Math.floor(input.waitMs)}`,
+        ],
+        objectLabels: warmLabels(input.token),
+    });
+}
+function workerRunArgs(input) {
+    const { image, limits, names } = input;
+    if (!isImmutableDockerImage(image)) {
+        throw new Error("native_sandbox_image_not_pinned: the worker image must be a digest (repo@sha256:...) or a local image id.");
+    }
+    return [
+        "run",
+        ...input.mode,
+        "--name",
+        names.worker,
+        "--pull",
+        "never",
+        "--user",
+        `${NATIVE_WORKER_UID}:${NATIVE_WORKER_UID}`,
+        "--network",
+        names.network,
+        "--read-only",
+        "--tmpfs",
+        `/tmp:rw,noexec,nosuid,nodev,size=${NATIVE_WORKER_TMP_MB}m`,
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges=true",
+        "--security-opt",
+        "seccomp=builtin",
+        "--cgroupns",
+        "private",
+        "--ipc",
+        "none",
+        "--cpus",
+        String(limits.cpus),
+        "--memory",
+        `${limits.memoryMb}m`,
+        "--memory-swap",
+        `${limits.memoryMb}m`,
+        "--memory-swappiness",
+        "0",
+        "--pids-limit",
+        String(limits.pids),
+        "--restart",
+        "no",
+        "--log-driver",
+        "local",
+        "--log-opt",
+        "max-size=1m",
+        "--log-opt",
+        "max-file=2",
+        ...input.env,
+        ...input.objectLabels,
+        image,
+    ];
+}
+/** The URL a worker dials: the gateway's alias on its own run network. */
+export function nativeGatewayUrl(port = NATIVE_GATEWAY_PORT) {
+    return `http://${NATIVE_GATEWAY_ALIAS}:${port}/native-gateway/v1/call`;
+}