@wardby/cli 0.6.0 → 0.7.0

package/dist/knowledge/location.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a repository's knowledge bundle lives (docs/knowledge.md, "Where the
+ * bundle lives"): the folder `.wardby/knowledge.yaml` names, else
+ * DEFAULT_KNOWLEDGE_BUNDLE_PATH. A missing, unreadable, or invalid file never
+ * fails anything: it degrades to the default, with a warning when the file
+ * exists but cannot be used.
+ */
+export declare const KNOWLEDGE_CONFIG_PATH = ".wardby/knowledge.yaml";
+export declare const KNOWLEDGE_CONFIG_MAX_BYTES: number;
+export interface KnowledgeLocation {
+    bundlePath: string;
+    /** Set when `.wardby/knowledge.yaml` exists but was ignored, saying why. */
+    warning?: string;
+}
+export type KnowledgeConfigParse = {
+    ok: true;
+    bundlePath: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** `path: <repo-relative folder>`, the file's only key. */
+export declare function parseKnowledgeConfig(text: string): KnowledgeConfigParse;
+/** A repo-relative POSIX folder, without `./` or trailing slashes, outside `.wardby/` and `.git/`. */
+export declare function normalizeBundlePath(raw: string): KnowledgeConfigParse;
+/**
+ * The bundle location, given a reader for `.wardby/knowledge.yaml` that
+ * returns null when the file does not exist. A reader that throws, like an
+ * invalid file, yields the default with a warning.
+ */
+export declare function resolveKnowledgeLocation(readConfig: () => Promise<string | null | undefined>): Promise<KnowledgeLocation>;

package/dist/knowledge/location.js

@@ -0,0 +1,78 @@
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_KNOWLEDGE_BUNDLE_PATH } from "./concept.js";
+/**
+ * Where a repository's knowledge bundle lives (docs/knowledge.md, "Where the
+ * bundle lives"): the folder `.wardby/knowledge.yaml` names, else
+ * DEFAULT_KNOWLEDGE_BUNDLE_PATH. A missing, unreadable, or invalid file never
+ * fails anything: it degrades to the default, with a warning when the file
+ * exists but cannot be used.
+ */
+export const KNOWLEDGE_CONFIG_PATH = ".wardby/knowledge.yaml";
+export const KNOWLEDGE_CONFIG_MAX_BYTES = 4 * 1024;
+const MAX_BUNDLE_PATH_LENGTH = 200;
+/** `path: <repo-relative folder>`, the file's only key. */
+export function parseKnowledgeConfig(text) {
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch {
+        return { ok: false, error: "it is not valid YAML" };
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return { ok: false, error: "it must be a mapping with a `path` key" };
+    const keys = Object.keys(doc);
+    const unknown = keys.filter((k) => k !== "path");
+    if (unknown.length > 0)
+        return { ok: false, error: `unknown key ${unknown.map((k) => `\`${k}\``).join(", ")}` };
+    const { path } = doc;
+    if (typeof path !== "string")
+        return { ok: false, error: "`path` must be a string" };
+    return normalizeBundlePath(path);
+}
+/** A repo-relative POSIX folder, without `./` or trailing slashes, outside `.wardby/` and `.git/`. */
+export function normalizeBundlePath(raw) {
+    let path = raw.trim();
+    while (path.startsWith("./"))
+        path = path.slice(2);
+    path = path.replace(/\/+$/, "");
+    if (path === "" || path === ".")
+        return { ok: false, error: "`path` must name a folder inside the repository" };
+    if (path.length > MAX_BUNDLE_PATH_LENGTH)
+        return { ok: false, error: `\`path\` must be at most ${MAX_BUNDLE_PATH_LENGTH} characters` };
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f\\]/.test(path))
+        return { ok: false, error: "`path` must be a plain POSIX path" };
+    if (path.startsWith("/"))
+        return { ok: false, error: "`path` must be relative to the repository root" };
+    const segments = path.split("/");
+    if (segments.some((s) => s === "" || s === "." || s === ".."))
+        return { ok: false, error: "`path` must not contain empty, `.` or `..` segments" };
+    if (segments[0] === ".wardby" || segments[0] === ".git")
+        return { ok: false, error: "`path` must not be inside `.wardby/` or `.git/`" };
+    return { ok: true, bundlePath: path };
+}
+/**
+ * The bundle location, given a reader for `.wardby/knowledge.yaml` that
+ * returns null when the file does not exist. A reader that throws, like an
+ * invalid file, yields the default with a warning.
+ */
+export async function resolveKnowledgeLocation(readConfig) {
+    let text;
+    try {
+        text = await readConfig();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH, warning: ignoredWarning(`it could not be read (${reason})`) };
+    }
+    if (text === null || text === undefined)
+        return { bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH };
+    const parsed = parseKnowledgeConfig(text);
+    if (!parsed.ok)
+        return { bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH, warning: ignoredWarning(parsed.error) };
+    return { bundlePath: parsed.bundlePath };
+}
+function ignoredWarning(reason) {
+    return `${KNOWLEDGE_CONFIG_PATH} was ignored because ${reason}; using ${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/.`;
+}

package/dist/mcp/auth/access.d.ts

@@ -38,16 +38,17 @@ export declare function assertAgentAccess<A extends AgentRef>(ctx: McpRequestCon
 export declare function requireAgentAccess(ctx: McpRequestContext, id: string, required: AgentLevel | "owner", db?: Pick<PrismaClient, "agent" | "resourceGrant">): Promise<{
     agent: {
         name: string;
+        updatedAt: Date;
         model: string;
         budgetUsd: import("@prisma/client-runtime-utils").Decimal;
         maxTurns: number;
-        createdAt: Date;
-        updatedAt: Date;
         kind: import("#prisma").AgentKind;
+        createdAt: Date;
         id: string;
         ownerId: string | null;
         nativeExecutionMode: import("#prisma").NativeExecutionMode;
         systemPrompt: string;
+        allowedOverrunPercent: number;
         schedule: string | null;
         timezone: string;
         scheduleEnabled: boolean;
@@ -68,6 +69,13 @@ export declare function requireAgentAccess(ctx: McpRequestContext, id: string, r
  * it can adopt the agent first (make_owner / grants adopt-public).
  */
 export declare function requireBindingOwner(ctx: McpRequestContext, agent: AgentRef): void;
+/**
+ * requireBindingOwner, plus: nothing owner-held may be bound to an agent
+ * everyone can write (anyone could then rewrite it to use the binding).
+ */
+export declare function requireBindable(ctx: McpRequestContext, agent: AgentRef, db?: GrantDb): Promise<void>;
+/** The public-write half of requireBindable, for paths that skip the owner check (an admin's adminOverride). */
+export declare function requireNotPublicWritable(agent: AgentRef, db: GrantDb): Promise<void>;
 /** Prisma where for agent listings: own rows plus rows granted >= read; the operator sees all. */
 export declare function readableAgentsWhere(ctx: McpRequestContext, db?: GrantDb): Promise<Prisma.AgentWhereInput>;
 /** One grant lookup for a whole listing: returns agent -> the caller's access. */

package/dist/mcp/auth/access.js

@@ -1,4 +1,4 @@
-import { atLeast, effectiveAccess, grantedAccessMap, grantedIds } from "../../core/grants.js";
+import { atLeast, effectiveAccess, grantedAccessMap, grantedIds, isPublicWritable, } from "../../core/grants.js";
 import { McpError } from "../errors.js";
 export function agentNotFound(id) {
     return new McpError(404, `Agent "${id}" not found.`);
@@ -42,6 +42,20 @@ export function requireBindingOwner(ctx, agent) {
         throw new McpError(403, `Only the owner of agent "${agent.id}" can change its bindings.`);
     }
 }
+/**
+ * requireBindingOwner, plus: nothing owner-held may be bound to an agent
+ * everyone can write (anyone could then rewrite it to use the binding).
+ */
+export async function requireBindable(ctx, agent, db = ctx.db) {
+    requireBindingOwner(ctx, agent);
+    await requireNotPublicWritable(agent, db);
+}
+/** The public-write half of requireBindable, for paths that skip the owner check (an admin's adminOverride). */
+export async function requireNotPublicWritable(agent, db) {
+    if (await isPublicWritable(db, agent.id)) {
+        throw new McpError(409, `Agent "${agent.id}" is writable by everyone, so nothing can be bound to it; revoke or lower the everyone grant first.`);
+    }
+}
 /** Prisma where for agent listings: own rows plus rows granted >= read; the operator sees all. */
 export async function readableAgentsWhere(ctx, db = ctx.db) {
     if (ctx.operator)

package/dist/mcp/auth/ownership.d.ts

@@ -26,8 +26,8 @@ export declare function visibleToPrincipal(principalId: string): {
 };
 export declare function requireOwnedBudgetGroup(db: PrismaClient, id: string, principalId: string): Promise<{
     name: string;
-    createdAt: Date;
     updatedAt: Date;
+    createdAt: Date;
     id: string;
     ownerId: string | null;
     dailyBudgetUsd: import("@prisma/client-runtime-utils").Decimal | null;
@@ -37,8 +37,8 @@ export declare function requireOwnedBudgetGroup(db: PrismaClient, id: string, pr
 }>;
 export declare function requireReadableBudgetGroup(db: Pick<PrismaClient, "budgetGroup">, id: string, principalId: string): Promise<{
     name: string;
-    createdAt: Date;
     updatedAt: Date;
+    createdAt: Date;
     id: string;
     ownerId: string | null;
     dailyBudgetUsd: import("@prisma/client-runtime-utils").Decimal | null;
@@ -50,8 +50,8 @@ export declare function requireOwnedSecret(db: PrismaClient, id: string, princip
 export declare function requireOwnedWebhook(db: PrismaClient, id: string, principalId: string): Promise<void>;
 export declare function requireOwnedDatastore(db: PrismaClient, id: string, principalId: string): Promise<{
     name: string;
-    createdAt: Date;
     updatedAt: Date;
+    createdAt: Date;
     id: string;
     ownerId: string | null;
 }>;
@@ -72,14 +72,14 @@ export declare function assertStrictlyOwnedTool(tool: Tool | null, id: string, p
  * triggered them. No canRead/null=public path exists here on purpose.
  */
 export declare function requireOwnedTask(db: PrismaClient, taskId: string, principalId: string): Promise<{
+    updatedAt: Date;
     error: import("@prisma/client/runtime/client").JsonValue | null;
-    status: import("#prisma").TaskStatus;
     runId: string | null;
-    createdAt: Date;
-    updatedAt: Date;
-    kind: import("#prisma").TaskKind;
     result: import("@prisma/client/runtime/client").JsonValue | null;
+    kind: import("#prisma").TaskKind;
+    createdAt: Date;
     id: string;
+    status: import("#prisma").TaskStatus;
     principalId: string | null;
     inputRequests: import("@prisma/client/runtime/client").JsonValue | null;
     inputResponses: import("@prisma/client/runtime/client").JsonValue | null;

package/dist/mcp/auth/self-hosted/credentials.d.ts

@@ -23,10 +23,10 @@ export declare function lockUser(tx: AuthDb, id: string): Promise<{
         subject: string;
     };
 } & {
-    status: string;
-    createdAt: Date;
     updatedAt: Date;
+    createdAt: Date;
     id: string;
+    status: string;
     roles: string[];
     displayName: string | null;
     principalId: string;
@@ -58,11 +58,11 @@ export declare class IdentityService {
     }>;
     revokeKey(keyId: string): Promise<void>;
     listUsers(): Prisma.PrismaPromise<{
+        id: string;
         status: string;
         principal: {
             subject: string;
         };
-        id: string;
         roles: string[];
         displayName: string | null;
     }[]>;

package/dist/mcp/auth/self-hosted/session.d.ts

@@ -16,10 +16,10 @@ export declare class Sessions {
                 subject: string;
             };
         } & {
-            status: string;
-            createdAt: Date;
             updatedAt: Date;
+            createdAt: Date;
             id: string;
+            status: string;
             roles: string[];
             displayName: string | null;
             principalId: string;

package/dist/mcp/host-events/github-ingress.d.ts

@@ -33,6 +33,8 @@ export interface GitHubIngressDeps {
     }>;
     /** Accounts served in addition to the App's owner (WARDBY_GITHUB_ALLOWED_ACCOUNTS). */
     allowedAccounts: () => ReadonlySet<string>;
+    /** False = no reply explaining why a mention started nothing (WARDBY_MENTION_EXPLANATIONS). */
+    mentionExplanations?: boolean;
     /** Removes the App from an installation on an account that isn't served; absent = ignore only. */
     uninstallInstallation?: (installationId: number) => Promise<void>;
     now?: () => Date;

package/dist/mcp/host-events/github-ingress.js

@@ -99,7 +99,7 @@ export async function handleGitHubEventIngress(req, deps) {
                 : {}),
         };
     }
-    const event = normalizeGitHubEvent(eventName, payload, app);
+    const event = normalizeGitHubEvent(eventName, payload, app, (dropped) => log.info({ ...dropped, deliveryId }, "mention ignored: its author did not pass the pre-filter"));
     // An event we don't act on must never claim the delivery id: recording it
     // here would let a later, real delivery of the same id (GitHub does reuse
     // ids across distinct redeliveries of what it considers the same event)
@@ -130,6 +130,7 @@ export async function handleGitHubEventIngress(req, deps) {
             repoAccess: deps.repoAccess,
             ...(deps.issueTrackers ? { issueTrackers: deps.issueTrackers } : {}),
             mentionHandle: app.slug,
+            ...(deps.mentionExplanations === false ? { mentionExplanations: false } : {}),
         });
         log.info({ event: event.kind, repository: event.repository, deliveryId, runIds: routed.runIds }, "host event routed");
         return {

package/dist/mcp/index.d.ts

@@ -12,6 +12,12 @@ export declare function localOperatorContext(principal: Principal, providers: Mc
 export declare function registerAllTools(mcp: WardbyMcpServer, opts: {
     secretElicitationUrl: SecretElicitationUrlBuilder;
     secretElicitationProtocol: boolean;
+    /** Builds a get_run_transcript download URL for a minted token; absent = transcripts are not served. */
+    runTranscriptUrl?: (token: string) => Promise<string>;
+    /** Whether a blob store is configured to serve run transcripts from. */
+    blobStoreConfigured?: boolean;
+    /** Which host serves those links (default http). */
+    runTranscriptAudience?: "stdio" | "http";
     /** Rebuilds the process's installed model CatalogStore after set_model/disable_model/reset_model. */
     refreshModelCatalog?: () => Promise<void>;
 }): void;

package/dist/mcp/index.js

@@ -13,8 +13,11 @@
  * missing `AUTH_JWKS_URI`/`AUTH_SIGNING_KEY` a deployment running stdio-only
  * never needed to set.
  */
-import { loadProviderConfig, loadMcpConfig, loadShutdownDrainSeconds, loadAuthConfig, loadGitHubEventConfig, loadJiraConfig, loadGitHubVcsConfig, } from "../config/providers.js";
+import { startupTestSimulators } from "../config/test-simulators.js";
+import { loadProviderConfig, loadMcpConfig, loadShutdownDrainSeconds, loadAuthConfig, loadGitHubEventConfig, loadJiraConfig, loadGitHubVcsConfig, loadBlobStoreConfig, } from "../config/providers.js";
 import { prisma } from "../core/db.js";
+import { guardDatastore, guardAgentMemory } from "../core/secret-guarded-stores.js";
+import { createDbSecretWriteGuard } from "../core/secret-guard.js";
 import { waitForInFlightRuns } from "../core/in-flight-runs.js";
 import { NativeEngine } from "../core/engine-native.js";
 import { resolveLlmRegistrations, RoutingLlmProvider } from "../providers/llm/index.js";
@@ -35,6 +38,7 @@ import { loadGitHubAllowedAccounts } from "../config/github-allowed-accounts.js"
 import { buildMcpServer } from "./server.js";
 import { buildPower } from "../core/power-composition.js";
 import { countUnattendedSchedules, unattendedSchedulesWarning } from "./unattended-schedules.js";
+import { logZod3ToolWarnings } from "../core/zod3-window.js";
 import { runStdioServer } from "./transport/stdio.js";
 import { startHttpServer } from "./transport/streamable-http.js";
 import { resolvePrincipal } from "./auth/principal.js";
@@ -53,6 +57,7 @@ import { registerTriggerTool } from "./tools/trigger.js";
 import { registerToolAuthoringTools } from "./tools/tools.js";
 import { registerSchedulingTools } from "./tools/scheduling.js";
 import { registerRunTools } from "./tools/runs.js";
+import { registerStopRunTool } from "./tools/stop-run.js";
 import { registerCostReportTools } from "./tools/cost-report.js";
 import { registerDatastoreTools } from "./tools/datastore.js";
 import { registerSubAgentTools } from "./tools/subagents.js";
@@ -62,9 +67,14 @@ import { registerIssueProjectTools } from "./tools/issue-projects.js";
 import { registerNotificationChannelTools } from "./tools/notification-channels.js";
 import { registerHostAccountTools } from "./tools/host-accounts.js";
 import { registerMemoryTools } from "./tools/memory.js";
+import { registerPackageTools } from "./tools/packages.js";
 import { registerSecretsTools } from "./tools/secrets.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
-import { createStdioSecretElicitationHost } from "./tools/secret-elicitation-server.js";
+import { STDIO_SECRET_PATH, secretFormRoute } from "./tools/secret-elicitation-server.js";
+import { createStdioLinkHost } from "./transport/stdio-link-host.js";
+import { registerRunTranscriptTool } from "./tools/run-transcript.js";
+import { handleRunTranscriptDownload, RUN_TRANSCRIPT_DOWNLOAD_PATH } from "./tools/run-transcript-download.js";
+import { createBlobStore } from "../providers/storage/index.js";
 import { SECRET_ELICITATION_PATH } from "./tools/secret-elicitation-form.js";
 import { installWorkflowEventRecorder } from "../core/notifications.js";
 import { logger } from "../core/logger.js";
@@ -118,6 +128,13 @@ export function registerAllTools(mcp, opts) {
     registerToolAuthoringTools(mcp);
     registerSchedulingTools(mcp);
     registerRunTools(mcp);
+    const runTranscriptUrl = opts.runTranscriptUrl;
+    registerRunTranscriptTool(mcp, {
+        downloadUrl: runTranscriptUrl ?? (() => Promise.reject(new Error("run transcripts are not served here"))),
+        blobStoreConfigured: runTranscriptUrl !== undefined && opts.blobStoreConfigured === true,
+        audience: opts.runTranscriptAudience ?? "http",
+    });
+    registerStopRunTool(mcp);
     registerCostReportTools(mcp);
     registerDatastoreTools(mcp);
     registerSubAgentTools(mcp);
@@ -127,6 +144,7 @@ export function registerAllTools(mcp, opts) {
     registerNotificationChannelTools(mcp);
     registerHostAccountTools(mcp);
     registerMemoryTools(mcp);
+    registerPackageTools(mcp);
     registerSecretsTools(mcp, {
         buildElicitationUrl: opts.secretElicitationUrl,
         protocolElicitation: opts.secretElicitationProtocol,
@@ -143,8 +161,9 @@ export function buildMcpProviders() {
     const llm = new RoutingLlmProvider(llmResult.registrations);
     const engine = new NativeEngine();
     const secrets = buildSecretCipher(providerConfig);
-    const datastore = new PostgresDatastore(prisma, secrets);
-    const memory = new PostgresAgentMemory(prisma);
+    const secretGuard = createDbSecretWriteGuard(prisma, secrets);
+    const datastore = guardDatastore(new PostgresDatastore(prisma, secrets), secretGuard);
+    const memory = guardAgentMemory(new PostgresAgentMemory(prisma), secretGuard);
     const reviewHosts = buildReviewHosts(process.env, prisma);
     const issueTrackers = buildIssueTrackers();
     const hostUserAuthorizers = buildHostUserAuthorizers();
@@ -183,6 +202,7 @@ export function buildMcpProviders() {
         providerConfig,
         repoAccess,
         power,
+        secretCipher: secrets,
         // Sandbox-mode native runs (docs/native-sandbox.md); undefined when NATIVE_SANDBOX_LAUNCHER is unset.
         nativeSandbox: buildNativeSandboxExecutor({ db: prisma, providers: nativeProviders, power }),
     });
@@ -233,6 +253,8 @@ export function warmUpExecutor(executor) {
 /** The real CLI entry point: `wardby mcp`. Reads config from the environment, starts stdio or HTTP per MCP_TRANSPORT. */
 export async function startMcp(options = {}) {
     const mcpConfig = loadMcpConfig();
+    // WARDBY_TEST_SIMULATORS (test only): refuses to start beside production configuration.
+    startupTestSimulators("server");
     // Parsed up front so a malformed value fails at startup, not at shutdown.
     const drainSeconds = loadShutdownDrainSeconds();
     // Parsed now so a malformed list stops startup instead of failing every event.
@@ -251,15 +273,32 @@ export async function startMcp(options = {}) {
     warmUpExecutor(providers.executor);
     if (!options.schedulerAttached)
         await warnIfNothingWillFireSchedules();
+    // Zod 3 compatibility window: one warning per custom tool the next release breaks. In the background.
+    void logZod3ToolWarnings(prisma, mcpLog);
+    // Run transcripts (get_run_transcript) are served from the blob store they were stored in.
+    const blobStoreConfig = loadBlobStoreConfig();
+    const blobs = blobStoreConfig ? createBlobStore(blobStoreConfig) : undefined;
     if (mcpConfig.transport === "stdio") {
         const mcp = buildMcpServer({ providers, db: prisma, config: { canonicalUri: STDIO_PLACEHOLDER_URI } });
-        const secretElicitationHost = createStdioSecretElicitationHost({
-            verify: (token) => mcp.verifyRequestState(token),
-            secrets: providers.secrets,
-            db: prisma,
+        // One loopback server for every signed link a stdio tool hands out.
+        const linkHost = createStdioLinkHost({
+            [STDIO_SECRET_PATH]: secretFormRoute({
+                verify: (token) => mcp.verifyRequestState(token),
+                secrets: providers.secrets,
+                db: prisma,
+            }),
+            [RUN_TRANSCRIPT_DOWNLOAD_PATH]: (req, res, token) => handleRunTranscriptDownload(req.method, token, res, {
+                verify: (t) => mcp.verifyRequestState(t),
+                audience: "stdio",
+                db: prisma,
+                blobs,
+            }),
         });
         registerAllTools(mcp, {
-            secretElicitationUrl: (token) => secretElicitationHost.urlFor(token),
+            secretElicitationUrl: (token) => linkHost.urlFor(STDIO_SECRET_PATH, token),
+            runTranscriptUrl: (token) => linkHost.urlFor(RUN_TRANSCRIPT_DOWNLOAD_PATH, token),
+            runTranscriptAudience: "stdio",
+            blobStoreConfigured: blobs !== undefined,
             secretElicitationProtocol: mcpConfig.secretElicitationProtocol,
             refreshModelCatalog: () => modelCatalog.refreshNow(),
         });
@@ -291,10 +330,17 @@ export async function startMcp(options = {}) {
     const authProviderKind = providerConfig.auth === "self-hosted" ? "self-hosted" : "delegating";
     const authProvider = buildAuthProvider(providerConfig.auth, authConfig, prisma);
     const selfHosted = authProviderKind === "self-hosted" ? authProvider : undefined;
-    const mcp = buildMcpServer({ providers, db: prisma, config: { canonicalUri: mcpConfig.canonicalUri } });
+    const mcp = buildMcpServer({
+        providers,
+        db: prisma,
+        config: { canonicalUri: mcpConfig.canonicalUri },
+        deriveRequestStateKey: true,
+    });
     const httpOrigin = canonicalUrl(mcpConfig.canonicalUri).origin;
     registerAllTools(mcp, {
         secretElicitationUrl: (token) => Promise.resolve(`${httpOrigin}${SECRET_ELICITATION_PATH}?t=${encodeURIComponent(token)}`),
+        runTranscriptUrl: (token) => Promise.resolve(`${httpOrigin}${RUN_TRANSCRIPT_DOWNLOAD_PATH}?t=${encodeURIComponent(token)}`),
+        blobStoreConfigured: blobs !== undefined,
         secretElicitationProtocol: mcpConfig.secretElicitationProtocol,
         refreshModelCatalog: () => modelCatalog.refreshNow(),
     });
@@ -319,6 +365,7 @@ export async function startMcp(options = {}) {
                 webhookSecret: eventConfig.webhookSecret,
                 appIdentity: (opts) => githubApp.appIdentity(opts),
                 allowedAccounts: () => allowedAccounts,
+                mentionExplanations: eventConfig.mentionExplanations,
                 uninstallInstallation: (id) => githubApp.deleteInstallation(id),
             },
         }
@@ -385,6 +432,7 @@ export async function startMcp(options = {}) {
         hostEvents,
         hostUserAuth,
         viewer,
+        blobs,
     });
     const cleanupTimer = selfHosted
         ? setInterval(() => {

package/dist/mcp/server.d.ts

@@ -25,6 +25,14 @@
 import { type McpServerFactory, type InputRequiredResult } from "@modelcontextprotocol/server";
 import type { PrismaClient } from "#prisma";
 import type { McpRequestContext, McpProviders } from "./context.js";
+/**
+ * Most array elements plus object members one `tools/call` may carry
+ * (GHSA-46jr-4wx8-v453). Validating an argument tree costs memory per node, so
+ * without a bound one request inside the 1 MiB body limit could hold a very
+ * large tree. The largest legitimate input is a datastore value, itself capped
+ * at 1 MiB; 100,000 nodes leaves ample room for any realistic value.
+ */
+export declare const MAX_TOOL_INPUT_ELEMENTS = 100000;
 export interface ToolSpec<Args = Record<string, unknown>> {
     name: string;
     description?: string;
@@ -58,6 +66,11 @@ export interface BuildMcpServerOptions {
     config: McpServerConfig;
     /** Testability hook for REQUEST_STATE_KEY — defaults to process.env, matching buildSecretCipher's convention. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * HTTP transport: with REQUEST_STATE_KEY unset, derive the requestState key from SECRET_APP_KEY so
+     * every instance sharing that key verifies every other instance's tokens. stdio leaves it off.
+     */
+    deriveRequestStateKey?: boolean;
 }
 export interface DiscoverResultLike {
     capabilities: {

package/dist/mcp/server.js

@@ -23,7 +23,7 @@
  * whole connection.
  */
 import { McpServer, fromJsonSchema, createRequestStateCodec, CLIENT_CAPABILITIES_META_KEY, } from "@modelcontextprotocol/server";
-import { randomBytes } from "node:crypto";
+import { hkdfSync, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { requireScope } from "./auth/resource-server.js";
 import { McpError, mapPrismaError } from "./errors.js";
@@ -33,17 +33,35 @@ import { grantedIds } from "../core/grants.js";
 import { logger } from "../core/logger.js";
 /** The package version, reported in MCP server info (package.json sits two levels up from src/mcp and dist/mcp). */
 const SERVER_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+/**
+ * Most array elements plus object members one `tools/call` may carry
+ * (GHSA-46jr-4wx8-v453). Validating an argument tree costs memory per node, so
+ * without a bound one request inside the 1 MiB body limit could hold a very
+ * large tree. The largest legitimate input is a datastore value, itself capped
+ * at 1 MiB; 100,000 nodes leaves ample room for any realistic value.
+ */
+export const MAX_TOOL_INPUT_ELEMENTS = 100_000;
 const REQUEST_STATE_KEY_BYTES = 32;
+/** HKDF info for the requestState key derived from SECRET_APP_KEY; never reused for another key. */
+const REQUEST_STATE_KEY_INFO = "wardby/mcp/request-state/http/v1";
 /**
  * REQUEST_STATE_KEY (hex, 32 bytes) shares the requestState HMAC key across
- * instances — see the requestStateCodec construction below. Unset falls back
- * to a fresh random key, which is correct for stdio and single-instance HTTP
- * and is NOT an error: only a multi-instance HTTP deployment needs this set.
+ * instances — see the requestStateCodec construction below. Unset, the HTTP
+ * transport derives it from SECRET_APP_KEY (HKDF-SHA256, a label of its own),
+ * which every instance of one deployment already shares, so a multi-instance
+ * deployment needs no extra setting; the derived key reveals nothing about
+ * SECRET_APP_KEY. Without either, or on stdio, it is a fresh random key per
+ * process, which is correct when nothing outside that process verifies its
+ * tokens (and keeps stdio tokens from verifying on the HTTP server).
  */
-function loadRequestStateKey(env) {
+function loadRequestStateKey(env, derive) {
     const hex = env.REQUEST_STATE_KEY;
-    if (!hex)
-        return randomBytes(REQUEST_STATE_KEY_BYTES);
+    if (!hex) {
+        const appKey = derive && env.SECRET_APP_KEY ? Buffer.from(env.SECRET_APP_KEY, "hex") : undefined;
+        if (appKey?.length !== REQUEST_STATE_KEY_BYTES)
+            return randomBytes(REQUEST_STATE_KEY_BYTES);
+        return new Uint8Array(hkdfSync("sha256", appKey, Buffer.alloc(0), REQUEST_STATE_KEY_INFO, REQUEST_STATE_KEY_BYTES));
+    }
     const key = Buffer.from(hex, "hex");
     if (key.length !== REQUEST_STATE_KEY_BYTES) {
         throw new Error(`REQUEST_STATE_KEY must be ${REQUEST_STATE_KEY_BYTES} bytes of hex (${REQUEST_STATE_KEY_BYTES * 2} hex chars); got ${key.length} bytes.`);
@@ -76,16 +94,16 @@ export function buildMcpServer(opts) {
     // against the codec's implementation) — safe to call verifyRequestState()
     // from outside a real MCP request (the secret-elicitation browser form).
     //
-    // REQUEST_STATE_KEY, when set, lets a token minted by one process verify
-    // on another — required for the secret-elicitation round trip (mint,
-    // browser-form POST, polling retry) to work under a multi-instance HTTP
+    // REQUEST_STATE_KEY (or, over HTTP, the key derived from SECRET_APP_KEY)
+    // lets a token minted by one process verify on another — required for the
+    // secret-elicitation round trip (mint, browser-form POST, polling retry)
+    // and the run-transcript download to work under a multi-instance HTTP
     // deployment, where those three legs can land on three different
     // processes (see secret-elicitation.ts's matching Postgres-backed outcome
-    // store). stdio and single-instance HTTP need no configuration: with the
-    // env var unset, a fresh random key per process is fine, since nothing
-    // outside this same running server ever needs to verify a token it minted.
+    // store). stdio needs no configuration: a fresh random key per process is
+    // fine, since nothing outside that running server verifies its tokens.
     const requestStateCodec = createRequestStateCodec({
-        key: loadRequestStateKey(opts.env ?? process.env),
+        key: loadRequestStateKey(opts.env ?? process.env, opts.deriveRequestStateKey ?? false),
         ttlSeconds: 600,
     });
     function mcpReqOf(sdkCtx) {
@@ -125,6 +143,7 @@ export function buildMcpServer(opts) {
         const mcpServer = new McpServer({ name: "wardby", version: SERVER_VERSION }, {
             requestState: { verify: (state, ctx) => requestStateCodec.verify(state, ctx) },
             instructions: SERVER_INSTRUCTIONS,
+            maxToolInputElements: MAX_TOOL_INPUT_ELEMENTS,
         });
         mcpServer.server.registerCapabilities({ extensions: { [TASKS_EXTENSION_ID]: {} } });
         for (const spec of specs) {

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

@@ -1,2 +1,6 @@
 import type { WardbyMcpServer } from "../server.js";
+/** The warning create_agent / update_agent return (not a refusal): wardby can't tell how old a custom image is. */
+export declare const DEPENDENCY_CACHE_IMAGE_WARNING = "dependencyCache is on and this agent runs its own worker image (workerImageRef): rebuild that image FROM the wardby release that includes the dependency cache before its next run, or the run fails at input (worker_input_failed). See the dependency-cache help article.";
+export declare const SESSION_RESUME_IMAGE_WARNING = "sessionResume is on and this agent runs its own worker image (workerImageRef): rebuild that image FROM the wardby release that includes session resume before its next run, or the run fails at input (worker_input_failed).";
+export declare const SESSION_RESUME_NO_STORE_WARNING = "sessionResume is on but this server has no blob store (BLOB_STORE), so transcripts are not kept. See the resume-runs-locally help article.";
 export declare function registerAgentTools(mcp: WardbyMcpServer): void;