@wardby/cli 0.6.0 → 0.7.0

package/dist/mcp/tools/runs.js

@@ -1,9 +1,11 @@
-import { McpError } from "../errors.js";
-import { agentAccess, requireAgentAccess } from "../auth/access.js";
-import { publicCodingRunResult } from "../../coding/protocol.js";
+import { requireAgentAccess } from "../auth/access.js";
+import { findReadableRun } from "./run-access.js";
+import { publicCodingRunResult, sanitizeDependencyCacheReport } from "../../coding/protocol.js";
 import { countPlanRefusals, summarizeRegistryFetches } from "../../coding/registry/report.js";
+import { summarizePackageAudit } from "../../coding/registry/audit-mode.js";
 import { storedServiceLabels } from "../../coding/services/catalog.js";
 import { textResult } from "./text-result.js";
+import { loadBudgetEvents } from "../../core/budget-events.js";
 /**
  * Run visibility (resource-sharing grants spec §3.5, A6): a run's output is
  * the triggerer's and the agent owner's, never every reader's. The owner
@@ -56,17 +58,9 @@ export function registerRunTools(mcp) {
         scope: "agents:read",
         inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"] },
         handler: async (args, ctx) => {
-            const run = await ctx.db.run.findUnique({ where: { id: args.runId } });
-            const notFound = new McpError(404, `Run "${args.runId}" not found.`);
-            if (!run)
-                throw notFound;
             // Its triggerer keeps seeing it even after losing access to the agent;
             // otherwise only the agent's owner. read on the agent is not enough.
-            if (run.triggeredById !== ctx.principal.id) {
-                const agent = await ctx.db.agent.findUnique({ where: { id: run.agentId } });
-                if (!agent || (await agentAccess(ctx, agent)) !== "owner")
-                    throw notFound;
-            }
+            const run = await findReadableRun(ctx, args.runId);
             const codingRun = await ctx.db.codingRun.findUnique({
                 where: { runId: run.id },
                 select: {
@@ -75,9 +69,16 @@ export function registerRunTools(mcp) {
                     failureCategory: true,
                     diagnosticId: true,
                     debugTrace: true,
+                    debugTraceMaxMb: true,
                     services: true,
                     resultBranch: true,
                     baseSha: true,
+                    dependencyCacheResult: true,
+                    prDescriptionOutcome: true,
+                    packageAuditMode: true,
+                    budgetBaseUsd: true,
+                    budgetReservedUsd: true,
+                    budgetLimitUsd: true,
                 },
             });
             const localPr = await ctx.db.localPullRequest.findUnique({
@@ -102,6 +103,12 @@ export function registerRunTools(mcp) {
                     refused: countPlanRefusals(registryFetches),
                 }
                 : undefined;
+            // Package audit mode, fixed at dispatch: what the registry served only
+            // because of it (empty when nothing was), read only for a run that had it.
+            const packageAuditMode = codingRun?.packageAuditMode ?? null;
+            const packageAudit = packageAuditMode
+                ? summarizePackageAudit(await ctx.db.registryAuditRecord.findMany({ where: { runId: run.id }, orderBy: { createdAt: "asc" } })).entries
+                : undefined;
             // A failed coding run's error is only an opaque id; these two say which
             // stage failed and are the key an operator searches the control-plane
             // log for (the real reason is logged there, never persisted). Both are
@@ -110,17 +117,31 @@ export function registerRunTools(mcp) {
             const diagnosticId = codingRun?.diagnosticId ?? undefined;
             // Which services the run started with ("postgres 16"); never their images or environments.
             const services = codingRun ? storedServiceLabels(codingRun.services) : [];
+            // The worker's dependency cache report (stable codes, folder names and numbers only), re-bounded on read.
+            const dependencyCache = codingRun?.dependencyCacheResult !== null && codingRun?.dependencyCacheResult !== undefined
+                ? sanitizeDependencyCacheReport(codingRun.dependencyCacheResult)
+                : undefined;
+            // Well-formed refusals only, with group, lead and agent budget filled as the run error's are.
+            const budgetEvents = await loadBudgetEvents(ctx.db, run.id);
             return textResult({
                 ...withOperatorMode(run),
+                ...(budgetEvents.length > 0 ? { budgetEvents } : {}),
+                ...(codingRun?.budgetReservedUsd != null ? { budgetReservedUsd: Number(codingRun.budgetReservedUsd) } : {}),
+                ...(codingRun?.budgetBaseUsd != null ? { budgetBaseUsd: Number(codingRun.budgetBaseUsd) } : {}),
+                // The most overrun top-ups may raise budgetReservedUsd to; absent = the reservation is the limit.
+                ...(codingRun?.budgetLimitUsd != null ? { budgetLimitUsd: Number(codingRun.budgetLimitUsd) } : {}),
                 ...(codingResult ? { codingResult } : {}),
                 ...(failureCategory ? { failureCategory } : {}),
                 ...(diagnosticId ? { diagnosticId } : {}),
                 ...(codingQueuedAt ? { codingQueuedAt } : {}),
                 // An admin turned on the debug trace: the worker's full trace is in its pod log.
                 ...(codingRun?.debugTrace ? { debugTrace: true } : {}),
+                ...(codingRun?.debugTrace && codingRun.debugTraceMaxMb ? { debugTraceMaxMb: codingRun.debugTraceMaxMb } : {}),
                 ...(services.length > 0 ? { services } : {}),
                 ...(codingRun?.resultBranch ? { resultBranch: codingRun.resultBranch } : {}),
                 ...(codingRun?.baseSha ? { baseSha: codingRun.baseSha } : {}),
+                ...(dependencyCache ? { dependencyCache } : {}),
+                ...(codingRun?.prDescriptionOutcome ? { prDescriptionOutcome: codingRun.prDescriptionOutcome } : {}),
                 ...(localPr
                     ? {
                         review: {
@@ -137,6 +158,7 @@ export function registerRunTools(mcp) {
                     }
                     : {}),
                 ...(codingRun ? { packages, packageRefusals, packagePlan } : {}),
+                ...(packageAuditMode ? { packageAuditMode, packageAudit } : {}),
             });
         },
     });

package/dist/mcp/tools/scheduling.js

@@ -1,5 +1,6 @@
 import { Prisma } from "#prisma";
 import { validateCronExpression } from "../../core/cron.js";
+import { scheduleStartFields } from "../../core/schedule-start.js";
 import { McpError } from "../errors.js";
 import { assertAgentAccess, requireAgentAccess } from "../auth/access.js";
 import { textResult } from "./text-result.js";
@@ -24,9 +25,10 @@ export function registerSchedulingTools(mcp) {
                 if (existing.kind === "coding" && !existing.codingProfile?.defaultTask) {
                     throw new McpError(400, "A default task is required before enabling a coding-agent schedule.");
                 }
+                const next = { schedule: args.schedule, timezone: args.timezone, scheduleEnabled: true };
                 return tx.agent.update({
                     where: { id: args.agentId },
-                    data: { schedule: args.schedule, timezone: args.timezone, scheduleEnabled: true },
+                    data: { ...next, ...(await scheduleStartFields(tx, existing, next)) },
                 });
             }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
             return textResult(agent);

package/dist/mcp/tools/secret-elicitation-form.js

@@ -123,6 +123,11 @@ export async function handleSecretElicitationForm(method, token, readFormBody, r
         if (!token)
             throw new Error("missing token");
         payload = await deps.verify(token);
+        // Other links share the signing key (a run transcript download, a tool's
+        // requestState): only a secret link's kind opens this form.
+        if (payload.kind !== undefined && payload.kind !== "create" && payload.kind !== "unbroker") {
+            throw new Error("not a secret link");
+        }
     }
     catch {
         html(res, 400, "<h1>Link expired</h1><p>This link is invalid or has expired. Return to your MCP client and try again.</p>");

package/dist/mcp/tools/secret-elicitation-server.d.ts

@@ -1,5 +1,11 @@
 import type { SecretFormDeps } from "./secret-elicitation-form.js";
+import { type StdioLinkHandler } from "../transport/stdio-link-host.js";
+/** The loopback path the form is served at on stdio. */
+export declare const STDIO_SECRET_PATH = "/secret";
 export interface StdioSecretElicitationHost {
     urlFor(token: string): Promise<string>;
 }
+/** The secret form as a link-host route. */
+export declare function secretFormRoute(deps: SecretFormDeps): StdioLinkHandler;
+/** A link host serving only the secret form (the composition root shares one host across routes). */
 export declare function createStdioSecretElicitationHost(deps: SecretFormDeps): StdioSecretElicitationHost;

package/dist/mcp/tools/secret-elicitation-server.js

@@ -1,64 +1,13 @@
-/**
- * stdio-only host for the secret-entry form: an ephemeral, loopback-only
- * HTTP server, started lazily on the first pending elicitation and closed
- * after a period of inactivity. stdio's MCP process has no other listener
- * (see mcp/transport/stdio.ts) — this one exists only while a secret entry
- * is actually pending, consistent with stdio's "no token; the operator is
- * trusted" model: reachable only from this same machine, and only a holder
- * of the one-time signed URL can do anything with it.
- */
-import { createServer } from "node:http";
 import { handleSecretElicitationForm, readFormBody } from "./secret-elicitation-form.js";
-/** Matches the requestState codec's own TTL (server.ts) — no point outliving the tokens it serves. */
-const IDLE_SHUTDOWN_MS = 10 * 60_000;
+import { createStdioLinkHost } from "../transport/stdio-link-host.js";
+/** The loopback path the form is served at on stdio. */
+export const STDIO_SECRET_PATH = "/secret";
+/** The secret form as a link-host route. */
+export function secretFormRoute(deps) {
+    return (req, res, token) => handleSecretElicitationForm(req.method, token, () => readFormBody(req), res, deps);
+}
+/** A link host serving only the secret form (the composition root shares one host across routes). */
 export function createStdioSecretElicitationHost(deps) {
-    let server;
-    let port = 0;
-    let idleTimer;
-    function scheduleIdleShutdown() {
-        if (idleTimer)
-            clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-            server?.close();
-            server = undefined;
-        }, IDLE_SHUTDOWN_MS);
-        idleTimer.unref();
-    }
-    async function ensureServer() {
-        if (server) {
-            scheduleIdleShutdown();
-            return port;
-        }
-        const s = createServer((req, res) => {
-            scheduleIdleShutdown();
-            const url = new URL(req.url ?? "/", "http://127.0.0.1");
-            if (url.pathname !== "/secret") {
-                res.writeHead(404).end();
-                return;
-            }
-            // A failure here must never become an unhandled rejection: that would take
-            // down the whole stdio MCP process, not just this request.
-            handleSecretElicitationForm(req.method, url.searchParams.get("t"), () => readFormBody(req), res, deps).catch(() => {
-                if (!res.headersSent)
-                    res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
-                if (!res.writableEnded)
-                    res.end("Internal error");
-            });
-        });
-        server = s;
-        await new Promise((resolve, reject) => {
-            s.once("error", reject);
-            s.listen(0, "127.0.0.1", resolve);
-        });
-        const address = s.address();
-        port = typeof address === "object" && address ? address.port : 0;
-        scheduleIdleShutdown();
-        return port;
-    }
-    return {
-        async urlFor(token) {
-            const p = await ensureServer();
-            return `http://127.0.0.1:${p}/secret?t=${encodeURIComponent(token)}`;
-        },
-    };
+    const host = createStdioLinkHost({ [STDIO_SECRET_PATH]: secretFormRoute(deps) });
+    return { urlFor: (token) => host.urlFor(STDIO_SECRET_PATH, token) };
 }

package/dist/mcp/tools/secrets.js

@@ -8,7 +8,7 @@ import { createSecret, listSecrets, attachSecret, detachSecret, deleteSecret, se
 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 { requireAgentAccess, requireBindable, requireBindingOwner } from "../auth/access.js";
 import { clearUnbrokerOutcome, getSecretElicitationOutcome, } from "./secret-elicitation.js";
 import { allowedSecretNames, brokerCompatibilityWarnings } from "./secret-broker-compat.js";
 import { textResult } from "./text-result.js";
@@ -269,7 +269,7 @@ export function registerSecretsTools(mcp, opts) {
             // (A2/S2-2): a binding hands the value to every tool the owner lets
             // read it. Not even the stdio operator crosses owners.
             const { agent } = await requireAgentAccess(ctx, args.agentId, "read");
-            requireBindingOwner(ctx, agent);
+            await requireBindable(ctx, agent);
             const ownerId = agent.ownerId;
             try {
                 // Resolved among the agent owner's secrets (== the caller here).

package/dist/mcp/tools/stop-run.d.ts

@@ -0,0 +1,2 @@
+import type { WardbyMcpServer } from "../server.js";
+export declare function registerStopRunTool(mcp: WardbyMcpServer): void;

package/dist/mcp/tools/stop-run.js

@@ -0,0 +1,82 @@
+/**
+ * stop_run: stops a run that is still pending (including a coding run queued for a slot) or
+ * running, and the delegated child runs it has in flight (src/core/stop-run.ts). A run that already
+ * finished is returned unchanged, so calling it again is harmless.
+ *
+ * Access mirrors trigger_agent: stopping a run needs execute on its agent. Runs are visible only to
+ * the agent's owner and to the run's triggerer (get_run's rule), so anyone else gets the same 404 as
+ * for a missing run; a triggerer whose access to the agent has dropped below execute gets a 403.
+ */
+import { z } from "zod";
+import { atLeast } from "../../core/grants.js";
+import { stopRun } from "../../core/stop-run.js";
+import { agentAccess, insufficientAgentAccess } from "../auth/access.js";
+import { McpError } from "../errors.js";
+import { textResult } from "./text-result.js";
+const StopRunSchema = z
+    .object({
+    runId: z.string().trim().min(1).max(128),
+    reason: z.string().trim().max(500).optional(),
+})
+    .strict();
+export function registerStopRunTool(mcp) {
+    mcp.registerTool({
+        name: "stop_run",
+        scope: "runs:trigger",
+        description: "Stop a run that is pending, queued, or running, and the sub-agent runs it delegated that are still in " +
+            "flight. The run ends as `cancelled`; a coding run's worker is stopped and opens or updates no pull " +
+            "request. A run that already finished is returned unchanged. Needs execute access to the run's agent.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                runId: { type: "string" },
+                reason: {
+                    type: "string",
+                    description: "Why the run is being stopped; recorded on the run (up to 500 characters).",
+                },
+            },
+            required: ["runId"],
+        },
+        handler: async (raw, ctx) => {
+            const parsed = StopRunSchema.safeParse(raw);
+            if (!parsed.success) {
+                const details = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+                throw new McpError(400, `Invalid stop_run arguments: ${details}`);
+            }
+            const { runId, reason } = parsed.data;
+            const notFound = new McpError(404, `Run "${runId}" not found.`);
+            const run = await ctx.db.run.findUnique({
+                where: { id: runId },
+                select: { id: true, agentId: true, triggeredById: true },
+            });
+            if (!run)
+                throw notFound;
+            const agent = await ctx.db.agent.findUnique({ where: { id: run.agentId }, select: { id: true, ownerId: true } });
+            if (!agent)
+                throw notFound;
+            const access = await agentAccess(ctx, agent);
+            const isTriggerer = run.triggeredById !== null && run.triggeredById === ctx.principal.id;
+            // Visible to the agent's owner and the run's triggerer only, exactly as get_run.
+            if (access !== "owner" && !isTriggerer)
+                throw notFound;
+            if (!atLeast("agent", access, "execute"))
+                throw insufficientAgentAccess(agent.id, "execute", access);
+            const result = await stopRun({
+                db: ctx.db,
+                executor: ctx.providers.executor,
+                runId,
+                stoppedBy: ctx.principal.id,
+                reason,
+            });
+            const message = !result.stopRequested
+                ? `Run already finished as ${result.status}; nothing was changed.`
+                : result.status === "cancelled"
+                    ? "Run stopped."
+                    : result.status === "pending" || result.status === "running"
+                        ? `Stop requested; the run is still ${result.status}. Check it again with get_run.`
+                        : `The run finished as ${result.status} before the stop took effect.`;
+            return textResult({ ...result, message });
+        },
+    });
+}

package/dist/mcp/tools/subagents.js

@@ -14,7 +14,7 @@
  */
 import { Prisma } from "#prisma";
 import { atLeast, canDelegate } from "../../core/grants.js";
-import { agentAccess, agentAccessResolver, agentNotFound, requireAgentAccess, requireBindingOwner, } from "../auth/access.js";
+import { agentAccess, agentAccessResolver, agentNotFound, requireAgentAccess, requireBindable, } from "../auth/access.js";
 import { McpError } from "../errors.js";
 import { textResult } from "./text-result.js";
 /**
@@ -68,7 +68,7 @@ export function registerSubAgentTools(mcp) {
                 throw new McpError(400, "An agent cannot be its own sub-agent.");
             }
             const { agent: parent } = await requireAgentAccess(ctx, args.parentAgentId, "read");
-            requireBindingOwner(ctx, parent);
+            await requireBindable(ctx, parent);
             // The caller could trigger the child anyway; the edge must not widen that.
             const { agent: child } = await requireAgentAccess(ctx, args.childAgentId, "execute");
             if (parent.ownerId === null) {

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

@@ -19,9 +19,9 @@ import type { WardbyMcpServer } from "../server.js";
  */
 export declare function projectTool(tool: Tool, principalId: string): {
     name: string;
+    updatedAt: Date;
     code: string;
     createdAt: Date;
-    updatedAt: Date;
     id: string;
     ownerId: string | null;
     description: string;

package/dist/mcp/tools/tools.js

@@ -11,6 +11,7 @@
  */
 import { Prisma } from "#prisma";
 import { deriveJsonSchema, validateParams } from "../../sandbox/zod-params.js";
+import { cachedZod4Compatibility, toolSubject, withZod3ToolWarnings, zod3SampleArgsWarning, zod3ToolWarnings, zod3WindowWarning, } from "../../core/zod3-window.js";
 import { runInSandbox } from "../../sandbox/run-in-sandbox.js";
 import { ToolCapabilitiesPatchSchema } from "../../sandbox/tool-capabilities.js";
 import { buildSharedDatastoreAccessor } from "../../core/datastores.js";
@@ -19,7 +20,7 @@ import { ToolAttachedError, deleteToolGuarded, hasToolChanges, prepareToolUpdate
 import { McpError } from "../errors.js";
 import { requireOwnedTool, requireStrictlyOwnedTool, assertStrictlyOwnedTool, visibleToPrincipal, canRead, } from "../auth/ownership.js";
 import { agentAccessResolver, assertAgentAccess, requireAgentAccess } from "../auth/access.js";
-import { atLeast } from "../../core/grants.js";
+import { atLeast, isPublicWritable } from "../../core/grants.js";
 import { textResult } from "./text-result.js";
 import { brokerCompatibilityWarnings } from "./secret-broker-compat.js";
 /**
@@ -102,7 +103,8 @@ export function registerToolAuthoringTools(mcp) {
                         ownerId: ctx.principal.id,
                     },
                 });
-                return textResult(tool);
+                const warnings = await zod3ToolWarnings(toolSubject(tool.name), args.paramsZod);
+                return textResult(warnings.length ? { ...tool, warnings } : tool);
             }
             catch (err) {
                 if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002") {
@@ -145,7 +147,8 @@ export function registerToolAuthoringTools(mcp) {
             // landing between the check and the write.
             try {
                 const tool = await updateToolGuarded(ctx.db, args.toolId, prepared.data, (row) => assertStrictlyOwnedTool(row, args.toolId, ctx.principal.id));
-                return textResult(tool);
+                const warnings = args.paramsZod === undefined ? [] : await zod3ToolWarnings(toolSubject(tool.name), args.paramsZod);
+                return textResult(warnings.length ? { ...tool, warnings } : tool);
             }
             catch (err) {
                 if (err instanceof ToolAttachedError) {
@@ -193,7 +196,7 @@ export function registerToolAuthoringTools(mcp) {
     mcp.registerTool({
         name: "dry_run_tool",
         scope: "tools:write",
-        description: "Test-runs tool code against sample args without persisting it. Fetch is denied by default, same as a freshly attached tool — pass allowedHosts to test code that calls fetch().",
+        description: "Test-runs tool code against sample args without persisting it. Fetch is denied by default, same as a freshly attached tool — pass allowedHosts to test code that calls fetch(). For this release a paramsZod is still compiled with Zod 3; a `warnings` list in the result means the next release, which compiles it with Zod 4 only, will reject it or treat the sample args differently.",
         inputSchema: {
             type: "object",
             properties: {
@@ -217,10 +220,19 @@ export function registerToolAuthoringTools(mcp) {
             }
             const jsonSchema = schemaResult.value;
             const validated = await validateParams(args.paramsZod, args.sampleArgs);
+            // Zod 3 compatibility window: would the next release (Zod 4 only) compile
+            // this schema, and treat the sample arguments the same way?
+            const subject = "This paramsZod";
+            const compatibility = await cachedZod4Compatibility(args.paramsZod);
+            const compatWarning = compatibility.compatible === true
+                ? zod3SampleArgsWarning(subject, validated, await validateParams(args.paramsZod, args.sampleArgs, ["v4"]))
+                : zod3WindowWarning(subject, compatibility);
+            const warnings = compatWarning ? { warnings: [compatWarning] } : {};
             if (!validated.ok) {
                 return textResult({
                     jsonSchema,
                     result: { ok: false, errorKind: validated.errorKind, errorMessage: validated.errorMessage },
+                    ...warnings,
                 });
             }
             // No real agent exists for a dry run — the caller's own principal
@@ -243,7 +255,7 @@ export function registerToolAuthoringTools(mcp) {
                 toolName: "dry_run_tool",
                 allowedFetchHosts: hosts.data.allowedHosts ?? [],
             });
-            return textResult({ jsonSchema, result: sandboxResult });
+            return textResult({ jsonSchema, result: sandboxResult, ...warnings });
         },
     });
     mcp.registerTool({
@@ -294,6 +306,9 @@ export function registerToolAuthoringTools(mcp) {
                 if (capabilitiesPassed && !isOwner) {
                     throw new McpError(403, "Only the agent's owner can grant capabilities to an attachment; ask them to re-run attach_tool with the capabilities.");
                 }
+                if (capabilitiesPassed && (await isPublicWritable(tx, agent.id))) {
+                    throw new McpError(409, `Agent "${agent.id}" is writable by everyone, so tool capabilities cannot be granted on it; revoke or lower the everyone grant first.`);
+                }
                 const existing = await tx.agentTool.findUnique({
                     where: { agentId_toolId: { agentId: args.agentId, toolId: args.toolId } },
                 });
@@ -374,19 +389,20 @@ export function registerToolAuthoringTools(mcp) {
         scope: "tools:write",
         inputSchema: { type: "object", properties: { agentId: { type: "string" } } },
         handler: async (args, ctx) => {
-            const project = (tool) => projectTool(tool, ctx.principal.id);
+            // Zod 3 window: the caller's own tools carry their warnings (cached per paramsZod text).
+            const project = (tool) => withZod3ToolWarnings(projectTool(tool, ctx.principal.id));
             if (args.agentId) {
                 const { access } = await requireAgentAccess(ctx, args.agentId, "read");
                 const rows = await ctx.db.agentTool.findMany({ where: { agentId: args.agentId }, include: { tool: true } });
                 // The agent's owner sees every tool on it (projected: code only for
                 // the tool's own owner); anyone else only tools they could see anyway.
-                return textResult(rows
+                return textResult(await Promise.all(rows
                     .map((r) => r.tool)
                     .filter((tool) => access === "owner" || canRead(tool.ownerId, ctx.principal.id))
-                    .map(project));
+                    .map(project)));
             }
             const tools = await ctx.db.tool.findMany({ where: visibleToPrincipal(ctx.principal.id) });
-            return textResult(tools.filter((tool) => canRead(tool.ownerId, ctx.principal.id)).map(project));
+            return textResult(await Promise.all(tools.filter((tool) => canRead(tool.ownerId, ctx.principal.id)).map(project)));
         },
     });
 }

package/dist/mcp/transport/stdio-link-host.d.ts

@@ -0,0 +1,20 @@
+/**
+ * stdio-only host for the signed links some tools hand out (the secret-entry
+ * form, a run transcript download): an ephemeral, loopback-only HTTP server,
+ * started lazily on the first link and closed after a period of inactivity.
+ * stdio's MCP process has no other listener (see stdio.ts); this one exists
+ * only while a link may be in use, consistent with stdio's "no token; the
+ * operator is trusted" model: reachable only from this same machine, and
+ * only a holder of a signed link can do anything with it.
+ *
+ * Request logging: none. A link's token travels in its `t` query parameter
+ * and must never be logged.
+ */
+import { type IncomingMessage, type ServerResponse } from "node:http";
+/** Handles one request for a path; receives the `t` query parameter. Must not log the token. */
+export type StdioLinkHandler = (req: IncomingMessage, res: ServerResponse, token: string | null) => Promise<void>;
+export interface StdioLinkHost {
+    /** The loopback URL for `path` carrying `token`; starts the server if it is not running. */
+    urlFor(path: string, token: string): Promise<string>;
+}
+export declare function createStdioLinkHost(routes: Record<string, StdioLinkHandler>): StdioLinkHost;

package/dist/mcp/transport/stdio-link-host.js

@@ -0,0 +1,67 @@
+/**
+ * stdio-only host for the signed links some tools hand out (the secret-entry
+ * form, a run transcript download): an ephemeral, loopback-only HTTP server,
+ * started lazily on the first link and closed after a period of inactivity.
+ * stdio's MCP process has no other listener (see stdio.ts); this one exists
+ * only while a link may be in use, consistent with stdio's "no token; the
+ * operator is trusted" model: reachable only from this same machine, and
+ * only a holder of a signed link can do anything with it.
+ *
+ * Request logging: none. A link's token travels in its `t` query parameter
+ * and must never be logged.
+ */
+import { createServer } from "node:http";
+/** Matches the requestState codec's own TTL (server.ts): no point outliving the tokens it serves. */
+const IDLE_SHUTDOWN_MS = 10 * 60_000;
+export function createStdioLinkHost(routes) {
+    let server;
+    let port = 0;
+    let idleTimer;
+    function scheduleIdleShutdown() {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            server?.close();
+            server = undefined;
+        }, IDLE_SHUTDOWN_MS);
+        idleTimer.unref();
+    }
+    async function ensureServer() {
+        if (server) {
+            scheduleIdleShutdown();
+            return port;
+        }
+        const s = createServer((req, res) => {
+            scheduleIdleShutdown();
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const handler = Object.hasOwn(routes, url.pathname) ? routes[url.pathname] : undefined;
+            if (!handler) {
+                res.writeHead(404).end();
+                return;
+            }
+            // A failure here must never become an unhandled rejection: that would take
+            // down the whole stdio MCP process, not just this request.
+            handler(req, res, url.searchParams.get("t")).catch(() => {
+                if (!res.headersSent)
+                    res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+                if (!res.writableEnded)
+                    res.end("Internal error");
+            });
+        });
+        server = s;
+        await new Promise((resolve, reject) => {
+            s.once("error", reject);
+            s.listen(0, "127.0.0.1", resolve);
+        });
+        const address = s.address();
+        port = typeof address === "object" && address ? address.port : 0;
+        scheduleIdleShutdown();
+        return port;
+    }
+    return {
+        async urlFor(path, token) {
+            const p = await ensureServer();
+            return `http://127.0.0.1:${p}${path}?t=${encodeURIComponent(token)}`;
+        },
+    };
+}

package/dist/mcp/transport/streamable-http.d.ts

@@ -8,7 +8,16 @@ import type { McpProviders } from "../context.js";
 import { type GitHubIngressDeps } from "../host-events/github-ingress.js";
 import { type JiraIngressDeps } from "../host-events/jira-ingress.js";
 import { type HostUserCallbackDeps } from "../host-events/github-user-callback.js";
+import type { BlobStore } from "../../providers/storage/types.js";
 import { type ViewerApi } from "../../viewer/http.js";
+/**
+ * close() waits this long for open requests to finish, then cuts them. A
+ * connected MCP client's event stream never ends on its own, so without a
+ * limit close() would hold shutdown until the pod is killed. On Kubernetes
+ * the load balancer has already moved traffic away by then (preStop), and
+ * clients reconnect to another instance.
+ */
+export declare const CLOSE_GRACE_MS = 10000;
 export interface HttpServerConfig {
     canonicalUri: string;
     httpBind: {
@@ -40,6 +49,10 @@ export interface StartHttpServerOptions {
     };
     /** The admin viewer API (/admin/api/*); absent = those paths answer 404. */
     viewer?: ViewerApi;
+    /** The blob store run transcripts are served from (get_run_transcript links); absent = they answer 503. */
+    blobs?: BlobStore;
+    /** How long close() lets open requests finish before cutting them (default CLOSE_GRACE_MS). */
+    closeGraceMs?: number;
 }
 export interface HttpServerHandle {
     port: number;