@wardby/cli 0.6.0 → 0.8.0

package/dist/mcp/tools/packages.js

@@ -0,0 +1,195 @@
+/**
+ * approve_audited_packages: promotes what package audit mode recorded on a
+ * run (docs/coding-packages.md#package-audit-mode) into the agent's package
+ * allowlist, as bare names. Only `top-level` records are promoted by
+ * default; an `unknown` one (a direct download, or after a plan fallback)
+ * may really be a dependency of an allowlisted package, so it is promoted
+ * only when `names` lists it. A `transitive` one follows its parent once that is allowlisted,
+ * and an `allowed` one is already on the allowlist graph (it was recorded
+ * only for the advisories full mode served past, which approving cannot
+ * waive). For a parent run, each coding sub-run's names go to that sub-run's
+ * own agent. Same gate as packageAllowlist: packages:approve or agents:admin,
+ * and only the agent's owner. Every agent is checked before any is written,
+ * and all are written in one transaction, so a refusal changes nothing.
+ * Package audit mode itself is left as it is.
+ */
+import { Prisma } from "#prisma";
+import { z } from "zod";
+import { matchRoot, parseAllowlist } from "../../coding/registry/allowlist.js";
+import { UNKNOWN_RELATION_LABEL } from "../../coding/registry/audit-mode.js";
+import { REGISTRY_ADAPTERS } from "../../coding/registry/adapters.js";
+import { logger } from "../../core/logger.js";
+import { agentAccess } from "../auth/access.js";
+import { requireAnyScope } from "../auth/resource-server.js";
+import { McpError } from "../errors.js";
+import { textResult } from "./text-result.js";
+const packagesLog = logger.child({ module: "mcp-packages" });
+/** codingProfile.packageAllowlist's own cap per ecosystem (coding/profile.ts). */
+const MAX_ALLOWLIST_ENTRIES = 256;
+const ApproveSchema = z
+    .object({
+    runId: z.string().trim().min(1).max(128),
+    names: z.array(z.string().min(1).max(256)).min(1).max(MAX_ALLOWLIST_ENTRIES).optional(),
+})
+    .strict();
+export function registerPackageTools(mcp) {
+    mcp.registerTool({
+        name: "approve_audited_packages",
+        scope: "agents:write",
+        description: "Add the packages a run installed under package audit mode to its agent's codingProfile.packageAllowlist, as " +
+            "bare names (the top-level records in get_run's packageAudit; their dependencies then follow through the " +
+            "allowlist graph). Records with relation unknown may be dependencies of allowlisted packages: they are added only " +
+            "when `names` lists them, and are returned as `unknown` otherwise. For a parent run, each coding sub-run's " +
+            "packages go to that sub-run's agent; nothing is changed unless every agent can be. `names` limits it to those " +
+            "names. Needs packages:approve or agents:admin, and only the agent's owner may use it. Does not turn package " +
+            "audit mode off.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                runId: { type: "string", description: "The run whose package audit to approve (get_run's packageAudit)." },
+                names: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Only these package names (as get_run lists them), including any with relation unknown to add; omitted means every top-level one.",
+                },
+            },
+            required: ["runId"],
+        },
+        handler: async (raw, ctx) => {
+            const parsed = ApproveSchema.safeParse(raw);
+            if (!parsed.success) {
+                const details = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+                throw new McpError(400, `Invalid approve_audited_packages arguments: ${details}`);
+            }
+            const { runId, names } = parsed.data;
+            // The same gate as changing packageAllowlist through update_agent.
+            requireAnyScope(ctx, ctx.canonicalUri, "packages:approve", "agents:admin");
+            // Visible to the agent's owner and the run's triggerer only, exactly as get_run.
+            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;
+            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;
+            }
+            // The coding runs whose records count, with the agent each one belongs to.
+            const coding = await ctx.db.codingRun.findUnique({ where: { runId }, select: { runId: true } });
+            const targets = coding
+                ? [{ runId, agentId: run.agentId }]
+                : (await ctx.db.run.findMany({
+                    where: { parentRunId: runId },
+                    select: { id: true, agentId: true, codingRun: { select: { runId: true } } },
+                }))
+                    .filter((child) => child.codingRun)
+                    .map((child) => ({ runId: child.id, agentId: child.agentId }));
+            const agentOf = new Map(targets.map((target) => [target.runId, target.agentId]));
+            const records = targets.length > 0
+                ? await ctx.db.registryAuditRecord.findMany({
+                    where: { runId: { in: targets.map((target) => target.runId) } },
+                    select: { runId: true, ecosystem: true, name: true, relation: true },
+                    orderBy: { createdAt: "asc" },
+                })
+                : [];
+            const wanted = names ? new Set(names) : null;
+            /** agentId -> ecosystem -> names to add, first-seen order. */
+            const byAgent = new Map();
+            /** Unknown-relation names left out (not named), per ecosystem + name. */
+            const skippedUnknown = new Map();
+            const topLevel = new Set(records.filter((r) => r.relation === "top-level").map((r) => `${r.runId}\0${r.ecosystem}\0${r.name}`));
+            for (const record of records) {
+                if (record.relation !== "top-level" && record.relation !== "unknown")
+                    continue;
+                if (wanted ? !wanted.has(record.name) : record.relation !== "top-level") {
+                    if (!wanted && !topLevel.has(`${record.runId}\0${record.ecosystem}\0${record.name}`))
+                        skippedUnknown.set(`${record.ecosystem}\0${record.name}`, {
+                            ecosystem: record.ecosystem,
+                            name: record.name,
+                        });
+                    continue;
+                }
+                const agentId = agentOf.get(record.runId);
+                const ecosystems = byAgent.get(agentId) ?? new Map();
+                byAgent.set(agentId, ecosystems);
+                ecosystems.set(record.ecosystem, (ecosystems.get(record.ecosystem) ?? new Set()).add(record.name));
+            }
+            // One transaction: every agent is checked (owner, coding, the cap) before any is written.
+            const results = await ctx.db.$transaction(async (tx) => {
+                const planned = [];
+                for (const [agentId, ecosystems] of byAgent) {
+                    const agent = await tx.agent.findUnique({ where: { id: agentId }, include: { codingProfile: true } });
+                    if (!agent?.codingProfile || agent.kind !== "coding") {
+                        throw new McpError(400, `Agent "${agentId}" is not a coding agent.`);
+                    }
+                    // Strict, like update_agent's coding profile: the owner only.
+                    if (agent.ownerId === null || agent.ownerId !== ctx.principal.id) {
+                        throw new McpError(403, `Agent "${agentId}": only its owner can change its package allowlist.`);
+                    }
+                    const current = (agent.codingProfile.packageAllowlist ?? {});
+                    const parsedCurrent = parseAllowlist(current, REGISTRY_ADAPTERS);
+                    const next = Object.fromEntries(Object.entries(current).map(([ecosystem, entries]) => [ecosystem, [...entries]]));
+                    const added = {};
+                    for (const [ecosystem, candidates] of ecosystems) {
+                        const adapter = REGISTRY_ADAPTERS.get(ecosystem);
+                        if (!adapter)
+                            continue;
+                        const entries = parsedCurrent.get(ecosystem) ?? [];
+                        const list = next[ecosystem] ?? [];
+                        for (const name of candidates) {
+                            // Already allowed (exactly, by a ranged entry, or a wildcard): an entry's range is the owner's.
+                            if (list.includes(name) || matchRoot(entries, adapter.normalizeName(name)))
+                                continue;
+                            list.push(name);
+                            (added[ecosystem] ??= []).push(name);
+                        }
+                        if (list.length > MAX_ALLOWLIST_ENTRIES) {
+                            throw new McpError(400, `Agent "${agentId}": approving these would put ${list.length} ${ecosystem} entries on its allowlist; the limit is ${MAX_ALLOWLIST_ENTRIES}. Approve fewer with \`names\`, or replace some entries with a scope wildcard. Nothing was changed.`);
+                        }
+                        if (list.length > 0)
+                            next[ecosystem] = list;
+                    }
+                    // Every added name is a registry name the proxy normalized: still parsed, so the stored allowlist stays valid.
+                    parseAllowlist(next, REGISTRY_ADAPTERS);
+                    planned.push({ agentId, added, packageAllowlist: next });
+                }
+                for (const result of planned) {
+                    if (Object.keys(result.added).length === 0)
+                        continue;
+                    await tx.codingAgentProfile.update({
+                        where: { agentId: result.agentId },
+                        data: { packageAllowlist: result.packageAllowlist },
+                    });
+                }
+                return planned;
+            }, { isolationLevel: Prisma.TransactionIsolationLevel.Serializable });
+            for (const result of results) {
+                const count = Object.values(result.added).reduce((sum, list) => sum + list.length, 0);
+                if (count > 0) {
+                    packagesLog.info({
+                        event: "coding.package_audit.promoted",
+                        agentId: result.agentId,
+                        runId,
+                        added: count,
+                        by: ctx.principal.id,
+                    }, "audited packages added to the allowlist");
+                }
+            }
+            const unknown = [...skippedUnknown.values()];
+            return textResult({
+                runId,
+                agents: results,
+                ...(unknown.length > 0
+                    ? {
+                        unknown,
+                        unknownNote: `${UNKNOWN_RELATION_LABEL.toLowerCase()}. List one in \`names\` to add it.`,
+                    }
+                    : {}),
+            });
+        },
+    });
+}

package/dist/mcp/tools/repositories.js

@@ -12,8 +12,9 @@
  * See docs/private/2026-09-26-repo-access-authorization-spec-and-plan.md.
  */
 import { Prisma } from "#prisma";
-import { isLocalRepository, normalizeGitHubRepository, normalizeLocalRepository } from "../../coding/protocol.js";
-import { requireAgentAccess, requireBindingOwner } from "../auth/access.js";
+import { CodingBaseRefSchema, isLocalRepository, normalizeGitHubRepository, normalizeLocalRepository, } from "../../coding/protocol.js";
+import { codeProviderOf, normalizeHostedRepository } from "../../coding/code-host.js";
+import { assertAgentAccess, requireAgentAccess, requireBindable, requireBindingOwner, requireNotPublicWritable, } from "../auth/access.js";
 import { authorizeRepositoryForSet, canonicalLocalRepository } from "../auth/repo-authorization.js";
 import { requireScope } from "../auth/resource-server.js";
 import { McpError } from "../errors.js";
@@ -27,6 +28,9 @@ function normalizeRepository(provider, repository) {
             return normalizeLocalRepository(repository);
         if (provider === "github")
             return normalizeGitHubRepository(repository);
+        const normalized = normalizeHostedRepository(repository);
+        if (codeProviderOf(normalized) === provider)
+            return normalized;
     }
     catch {
         // fall through
@@ -58,7 +62,7 @@ export function registerRepositoryTools(mcp) {
     mcp.registerTool({
         name: "link_repository",
         scope: "agents:write",
-        description: "Links a native agent you own to a repository on a code-review host, with its access, event triggers, and checkName. " +
+        description: "Links an agent you own to a repository on a code-review host, with its access, event triggers, and checkName. " +
             "Triggers: pull_request (review each PR push), mention (answer @mentions), push (start on merges to the default branch), " +
             "review_fix (automatic review fix rounds). The review_fix trigger makes this agent the one wardby starts, automatically " +
             "and without a human comment, when wardby's own review check requests changes on a pull request a wardby coding run " +
@@ -68,9 +72,10 @@ export function registerRepositoryTools(mcp) {
             "pull_request trigger, and is unique per repository. waitForCi (only with the pull_request trigger) holds this agent's " +
             "review on a pushed head until that head's own CI finishes, instead of racing it; APPROVE is refused while CI on the " +
             "head is failing or still running. Re-linking an already-linked repository replaces its access, triggers, checkName, " +
-            "reviewFixMaxRounds, and waitForCi (an omitted field is cleared, not kept) and re-checks access — always send the full " +
-            "desired state. A local repository (local:/abs/path, inside the server's trusted roots) takes no triggers or checkName: " +
-            "it supports manual reviews only (trigger_agent with review).",
+            "reviewFixMaxRounds, waitForCi, markReadyWhenPassing, and baseRef (an omitted field is cleared, not kept) and re-checks access " +
+            "— always send the full desired state. A local repository (local:/abs/path, inside the server's trusted roots) takes " +
+            "no triggers or checkName: it supports manual reviews only (trigger_agent with review). " +
+            "On a coding agent, adds a repository its runs may work in, with write access and no triggers: a GitHub repository or a local one.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
@@ -92,6 +97,17 @@ export function registerRepositoryTools(mcp) {
                     description: "Only with the pull_request trigger: hold this agent's review on a pushed head until that head's own CI " +
                         "finishes, instead of racing it (default false).",
                 },
+                markReadyWhenPassing: {
+                    type: "boolean",
+                    description: "Only on a write link: mark the draft pull requests this agent, or a coding agent it delegated to " +
+                        "(directly or through sub-agents), opens here ready for review, once, " +
+                        "after every Wardby review check passed, CI is green and the wardby merge order check (if any) " +
+                        "is success (default false).",
+                },
+                baseRef: {
+                    type: "string",
+                    description: "Coding agents only: the base branch for runs in this repository. Default: the coding profile's baseRef.",
+                },
                 adminOverride: {
                     type: "boolean",
                     description: "Admins only (agents:admin with the admin role): approve this link without checking GitHub access, recorded as an admin approval. Allowed on any agent that has an owner, not only the admin's own.",
@@ -106,16 +122,21 @@ export function registerRepositoryTools(mcp) {
             let agent;
             if (args.adminOverride === true) {
                 requireScope(ctx, ctx.canonicalUri, "agents:admin");
-                agent = await ctx.db.agent.findUnique({ where: { id: args.agentId } });
+                agent = await ctx.db.agent.findUnique({
+                    where: { id: args.agentId },
+                    include: { codingProfile: { select: { repository: true } } },
+                });
                 if (!agent)
                     throw new McpError(404, `Agent "${args.agentId}" not found.`);
+                await requireNotPublicWritable(agent, ctx.db);
             }
             else {
-                agent = (await requireAgentAccess(ctx, args.agentId, "read")).agent;
-                requireBindingOwner(ctx, agent);
-            }
-            if (agent.kind !== "native") {
-                throw new McpError(400, "Repository links are for native agents only; coding agents use codingProfile.repository.");
+                const row = await ctx.db.agent.findUnique({
+                    where: { id: args.agentId },
+                    include: { codingProfile: { select: { repository: true } } },
+                });
+                agent = (await assertAgentAccess(ctx, row, args.agentId, "read")).agent;
+                await requireBindable(ctx, agent);
             }
             const provider = args.provider ?? (isLocalRepository(args.repository) ? "local" : "github");
             if ((provider === "local") !== isLocalRepository(args.repository)) {
@@ -125,6 +146,32 @@ export function registerRepositoryTools(mcp) {
                 ? await canonicalLocalRepository(args.repository)
                 : normalizeRepository(provider, args.repository);
             const triggers = [...new Set(args.triggers ?? [])];
+            if (agent.kind === "coding") {
+                if (args.access !== "write")
+                    throw new McpError(400, "A coding agent's repository link needs write access.");
+                // As codingProfile.repository: anything else would pass here and fail every run at dispatch.
+                // What a coding run can work in, matching the coding profile.
+                if (provider !== "github" && provider !== "local") {
+                    throw new McpError(400, "A coding agent's repository link must be a GitHub repository or a local: path.");
+                }
+                if (triggers.length > 0 ||
+                    args.checkName !== undefined ||
+                    args.reviewFixMaxRounds !== undefined ||
+                    args.waitForCi !== undefined ||
+                    args.markReadyWhenPassing !== undefined) {
+                    throw new McpError(400, "A coding agent's repository link takes no triggers, checkName, reviewFixMaxRounds, waitForCi or markReadyWhenPassing.");
+                }
+                if (agent.codingProfile?.repository === repository) {
+                    throw new McpError(400, `${repository} is already its default repository (codingProfile.repository).`);
+                }
+            }
+            else if (args.baseRef !== undefined) {
+                throw new McpError(400, "baseRef applies only to a coding agent's repository link.");
+            }
+            const parsedBaseRef = args.baseRef === undefined ? null : CodingBaseRefSchema.safeParse(args.baseRef);
+            if (parsedBaseRef && !parsedBaseRef.success)
+                throw new McpError(400, "baseRef must be a safe branch ref.");
+            const baseRef = parsedBaseRef ? parsedBaseRef.data : null;
             if (provider === "local") {
                 if (triggers.length > 0)
                     throw new McpError(400, "local repositories support manual review only");
@@ -154,6 +201,10 @@ export function registerRepositoryTools(mcp) {
             if (waitForCi && !triggers.includes("pull_request")) {
                 throw new McpError(400, "waitForCi needs the pull_request trigger.");
             }
+            const markReadyWhenPassing = args.markReadyWhenPassing ?? false;
+            if (markReadyWhenPassing && args.access !== "write") {
+                throw new McpError(400, "markReadyWhenPassing needs write access.");
+            }
             // The host call happens before, and outside, the serializable transaction.
             const authorization = await authorizeRepositoryForSet(ctx, {
                 ownerId: agent.ownerId,
@@ -172,6 +223,8 @@ export function registerRepositoryTools(mcp) {
                         checkName,
                         reviewFixMaxRounds,
                         waitForCi,
+                        markReadyWhenPassing,
+                        baseRef,
                         ...authorization,
                     };
                     return tx.agentRepository.upsert({

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

@@ -0,0 +1,16 @@
+import type { PrismaClient, Run } from "#prisma";
+import type { McpRequestContext } from "../context.js";
+import { type GrantDb } from "../../core/grants.js";
+/** Who is asking to read a run: a principal, and whether it is the stdio local operator. */
+export interface RunReader {
+    principalId: string;
+    operator?: boolean;
+}
+/**
+ * Run visibility (resource-sharing grants spec §3.5, A6): a run's triggerer
+ * keeps seeing it even after losing access to the agent; otherwise only the
+ * agent's owner (or the stdio operator). Read on the agent is not enough.
+ */
+export declare function canReadRun(db: GrantDb & Pick<PrismaClient, "agent">, run: Pick<Run, "agentId" | "triggeredById">, reader: RunReader): Promise<boolean>;
+/** The run, when the caller may read it (canReadRun); otherwise the same 404 a missing run gets. */
+export declare function findReadableRun(ctx: McpRequestContext, runId: string): Promise<Run>;

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

@@ -0,0 +1,25 @@
+import { McpError } from "../errors.js";
+import { effectiveAccess } from "../../core/grants.js";
+/**
+ * Run visibility (resource-sharing grants spec §3.5, A6): a run's triggerer
+ * keeps seeing it even after losing access to the agent; otherwise only the
+ * agent's owner (or the stdio operator). Read on the agent is not enough.
+ */
+export async function canReadRun(db, run, reader) {
+    if (run.triggeredById !== null && run.triggeredById === reader.principalId)
+        return true;
+    const agent = await db.agent.findUnique({ where: { id: run.agentId }, select: { id: true, ownerId: true } });
+    if (!agent)
+        return false;
+    return ((await effectiveAccess(db, "agent", agent, reader.principalId, { operator: reader.operator === true })) === "owner");
+}
+/** The run, when the caller may read it (canReadRun); otherwise the same 404 a missing run gets. */
+export async function findReadableRun(ctx, runId) {
+    const run = await ctx.db.run.findUnique({ where: { id: runId } });
+    const notFound = new McpError(404, `Run "${runId}" not found.`);
+    if (!run)
+        throw notFound;
+    if (!(await canReadRun(ctx.db, run, { principalId: ctx.principal.id, operator: ctx.operator })))
+        throw notFound;
+    return run;
+}

package/dist/mcp/tools/run-transcript-download.d.ts

@@ -0,0 +1,30 @@
+import type { ServerResponse } from "node:http";
+import type { PrismaClient } from "#prisma";
+import type { BlobStore } from "../../providers/storage/types.js";
+import { RUN_TRANSCRIPT_DOWNLOAD_PATH, RUN_TRANSCRIPT_LINK_TTL_MS, TRANSCRIPT_META_HEADER, TRANSCRIPT_SESSION_HEADER, TRANSCRIPT_SHA256_HEADER } from "../../coding/transcript/download-protocol.js";
+export { RUN_TRANSCRIPT_DOWNLOAD_PATH, RUN_TRANSCRIPT_LINK_TTL_MS, TRANSCRIPT_META_HEADER, TRANSCRIPT_SESSION_HEADER, TRANSCRIPT_SHA256_HEADER, };
+/**
+ * Which host serves a link. A stdio link (which may carry the operator flag) is never accepted by
+ * the HTTP route, even when REQUEST_STATE_KEY is shared and its signature verifies there.
+ */
+export type RunTranscriptLinkAudience = "stdio" | "http";
+export interface RunTranscriptLinkPayload {
+    kind: "run-transcript";
+    runId: string;
+    principalId: string;
+    /** The host that minted the link, and the only one that serves it. */
+    aud: RunTranscriptLinkAudience;
+    /** The stdio local operator: owner of every run for access checks. Only ever on a stdio link. */
+    operator?: boolean;
+    /** Epoch ms after which the link is refused. */
+    exp: number;
+}
+export interface RunTranscriptDownloadDeps {
+    verify: (token: string) => Promise<unknown>;
+    /** The host serving this route: only links minted for it are accepted. */
+    audience: RunTranscriptLinkAudience;
+    db: Pick<PrismaClient, "run" | "agent" | "resourceGrant" | "codingRun" | "runTranscript">;
+    blobs: BlobStore | undefined;
+    now?: () => Date;
+}
+export declare function handleRunTranscriptDownload(method: string | undefined, token: string | null, res: ServerResponse, deps: RunTranscriptDownloadDeps): Promise<void>;

package/dist/mcp/tools/run-transcript-download.js

@@ -0,0 +1,129 @@
+/**
+ * The download behind `get_run_transcript`'s link: a short-lived signed token
+ * (the MCP server's requestState codec, so HMAC + expiry) that names one run
+ * and the principal it was minted for. Served by both hosts: the HTTP
+ * transport's mounted route (streamable-http.ts) and, on stdio, the
+ * ephemeral loopback server (stdio-link-host.ts).
+ *
+ * The token is a bearer capability. It travels only in the `t` query
+ * parameter; nothing here logs it, and no response or error echoes it.
+ * Every refusal is a fixed code. On download, access is checked again
+ * (canReadRun, as get_run) for the principal in the token, so a link stops
+ * working when that principal loses access.
+ */
+import { createHash } from "node:crypto";
+import { canReadRun } from "./run-access.js";
+import { RUN_TRANSCRIPT_DOWNLOAD_PATH, RUN_TRANSCRIPT_LINK_TTL_MS, TRANSCRIPT_META_HEADER, TRANSCRIPT_SESSION_HEADER, TRANSCRIPT_SHA256_HEADER, } from "../../coding/transcript/download-protocol.js";
+// The route path and headers are shared with `wardby resume` (download-protocol.ts).
+export { RUN_TRANSCRIPT_DOWNLOAD_PATH, RUN_TRANSCRIPT_LINK_TTL_MS, TRANSCRIPT_META_HEADER, TRANSCRIPT_SESSION_HEADER, TRANSCRIPT_SHA256_HEADER, };
+const STATUS = {
+    link_invalid: 403,
+    not_found: 404,
+    transcript_expired: 410,
+    transcript_unavailable: 503,
+    transcript_corrupt: 500,
+};
+function refuse(res, code) {
+    res
+        .writeHead(STATUS[code], {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+    })
+        .end(JSON.stringify({ error: code }));
+}
+function isPayload(value) {
+    const v = value;
+    return (!!v &&
+        v.kind === "run-transcript" &&
+        typeof v.runId === "string" &&
+        typeof v.principalId === "string" &&
+        typeof v.exp === "number" &&
+        (v.aud === "stdio" || v.aud === "http") &&
+        (v.operator === undefined || typeof v.operator === "boolean") &&
+        // The operator flag belongs to stdio only.
+        !(v.aud === "http" && v.operator !== undefined));
+}
+export async function handleRunTranscriptDownload(method, token, res, deps) {
+    if (method !== "GET") {
+        res.writeHead(405, { allow: "GET", "cache-control": "no-store" }).end();
+        return;
+    }
+    const now = (deps.now ?? (() => new Date()))();
+    let payload;
+    try {
+        if (!token)
+            throw new Error("missing");
+        payload = await deps.verify(token);
+    }
+    catch {
+        refuse(res, "link_invalid");
+        return;
+    }
+    if (!isPayload(payload) || payload.aud !== deps.audience || payload.exp <= now.getTime()) {
+        refuse(res, "link_invalid");
+        return;
+    }
+    const run = await deps.db.run.findUnique({
+        where: { id: payload.runId },
+        select: { id: true, agentId: true, triggeredById: true },
+    });
+    if (!run || !(await canReadRun(deps.db, run, { principalId: payload.principalId, operator: payload.operator }))) {
+        refuse(res, "not_found");
+        return;
+    }
+    const [row, codingRun] = await Promise.all([
+        deps.db.runTranscript.findUnique({ where: { runId: run.id } }),
+        deps.db.codingRun.findUnique({
+            where: { runId: run.id },
+            select: { repository: true, headRef: true, resultBranch: true, baseSha: true, provider: true },
+        }),
+    ]);
+    if (!row || !codingRun || row.status !== "stored" || !row.blobKey || !row.sha256 || !row.sessionId) {
+        refuse(res, "not_found");
+        return;
+    }
+    if (row.expiresAt.getTime() <= now.getTime()) {
+        refuse(res, "transcript_expired");
+        return;
+    }
+    if (!deps.blobs) {
+        refuse(res, "transcript_unavailable");
+        return;
+    }
+    let bytes;
+    try {
+        bytes = await deps.blobs.get(row.blobKey);
+    }
+    catch {
+        refuse(res, "transcript_unavailable");
+        return;
+    }
+    // The stored object must still be what was recorded.
+    if (createHash("sha256").update(bytes).digest("hex") !== row.sha256) {
+        refuse(res, "transcript_corrupt");
+        return;
+    }
+    const meta = {
+        runId: run.id,
+        sessionId: row.sessionId,
+        provider: row.provider,
+        repository: codingRun.repository,
+        headRef: codingRun.headRef,
+        resultBranch: codingRun.resultBranch,
+        baseSha: codingRun.baseSha,
+        sha256: row.sha256,
+    };
+    res
+        .writeHead(200, {
+        "content-type": "application/gzip",
+        "content-length": String(bytes.byteLength),
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        [TRANSCRIPT_SHA256_HEADER]: row.sha256,
+        [TRANSCRIPT_SESSION_HEADER]: row.sessionId,
+        [TRANSCRIPT_META_HEADER]: Buffer.from(JSON.stringify(meta)).toString("base64url"),
+    })
+        .end(bytes);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * get_run_transcript: the way to continue a coding run's session locally.
+ * The transcript itself never enters the caller's context: the tool returns
+ * a short-lived signed download link and the command that imports it
+ * (`npx @wardby/cli@latest resume -`, which reads the link from standard input). Same access as get_run.
+ */
+import type { WardbyMcpServer } from "../server.js";
+import { type RunTranscriptLinkAudience } from "./run-transcript-download.js";
+/** Builds the download URL for a minted token (HTTP: the canonical origin; stdio: the loopback server). */
+export type RunTranscriptUrlBuilder = (token: string) => Promise<string>;
+export interface RunTranscriptToolOptions {
+    downloadUrl: RunTranscriptUrlBuilder;
+    /** Whether the server has a blob store to serve transcripts from. */
+    blobStoreConfigured: boolean;
+    /** The host that serves the links this server mints (stdio's loopback server, or the HTTP route). */
+    audience: RunTranscriptLinkAudience;
+    now?: () => Date;
+}
+export declare function registerRunTranscriptTool(mcp: WardbyMcpServer, opts: RunTranscriptToolOptions): void;

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

@@ -0,0 +1,70 @@
+import { textResult } from "./text-result.js";
+import { findReadableRun } from "./run-access.js";
+import { RUN_TRANSCRIPT_LINK_TTL_MS, } from "./run-transcript-download.js";
+/** What each status other than `stored` means, for the caller. */
+const MEANINGS = {
+    none: "No transcript was recorded for this run. Turn on codingProfile.sessionResume for the agent; it applies to runs started after that.",
+    too_large: "The run's transcript was larger than RUN_TRANSCRIPT_MAX_BYTES, so it was not stored.",
+    not_captured: "No transcript was stored for this run (see reason): for example the server had no blob store, the run was stopped or timed out, or it never finished a turn.",
+    failed: "Storing this run's transcript failed (see reason). Nothing was stored.",
+    expired: "The transcript was deleted after RUN_TRANSCRIPT_RETENTION_DAYS.",
+    unavailable: "The transcript was stored, but this server has no blob store configured to serve it from.",
+    unsupported: "Resuming this kind of run locally is not supported yet: only Claude Code coding runs can be resumed.",
+};
+function notStored(runId, status, reason) {
+    return textResult({ runId, status, ...(reason ? { reason } : {}), meaning: MEANINGS[status] });
+}
+export function registerRunTranscriptTool(mcp, opts) {
+    mcp.registerTool({
+        name: "get_run_transcript",
+        description: "Get a short-lived download link for a Claude Code coding run's session transcript, and the command that continues the session locally (npx @wardby/cli@latest resume -, which asks for the link). Give the user the command and the link to run in a terminal inside a clone of the run's repository; do not fetch the link yourself. Same access as get_run. The link works for 10 minutes.",
+        scope: "agents:read",
+        inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"] },
+        handler: async (args, ctx) => {
+            const run = await findReadableRun(ctx, args.runId);
+            const codingRun = await ctx.db.codingRun.findUnique({
+                where: { runId: run.id },
+                select: { provider: true, repository: true, headRef: true, resultBranch: true, baseSha: true },
+            });
+            if (!codingRun)
+                return notStored(run.id, "unsupported", "not_a_coding_run");
+            if (codingRun.provider !== "claude-code")
+                return notStored(run.id, "unsupported", "provider_unsupported");
+            const row = await ctx.db.runTranscript.findUnique({ where: { runId: run.id } });
+            if (!row)
+                return notStored(run.id, "none");
+            if (row.status !== "stored" || !row.sessionId)
+                return notStored(run.id, row.status, row.reason);
+            const now = (opts.now ?? (() => new Date()))();
+            if (row.expiresAt.getTime() <= now.getTime())
+                return notStored(run.id, "expired");
+            if (!opts.blobStoreConfigured)
+                return notStored(run.id, "unavailable", "no_blob_store");
+            const exp = now.getTime() + RUN_TRANSCRIPT_LINK_TTL_MS;
+            const payload = {
+                kind: "run-transcript",
+                runId: run.id,
+                principalId: ctx.principal.id,
+                aud: opts.audience,
+                ...(ctx.operator && opts.audience === "stdio" ? { operator: true } : {}),
+                exp,
+            };
+            const url = await opts.downloadUrl(await mcp.mintRequestState(payload));
+            const linkExpiresAt = new Date(exp).toISOString();
+            return textResult({
+                runId: run.id,
+                status: "stored",
+                sessionId: row.sessionId,
+                provider: codingRun.provider,
+                repository: codingRun.repository,
+                branch: codingRun.resultBranch ?? codingRun.headRef,
+                baseSha: codingRun.baseSha,
+                sizeBytes: row.sizeBytes,
+                expiresAt: row.expiresAt.toISOString(),
+                download: { url, expiresAt: linkExpiresAt },
+                command: "npx @wardby/cli@latest resume -",
+                note: "Run the command in a terminal, inside a clone of the repository (not needed for a local: repository), and paste download.url when it asks. Reading the link this way keeps it out of shell history and the process list. The link is a credential for this transcript until it expires: do not share it.",
+            });
+        },
+    });
+}