@wardby/cli 0.1.0

package/dist/mcp/index.js

@@ -0,0 +1,187 @@
+import { loadProviderConfig, loadMcpConfig, loadAuthConfig } from "../config/providers.js";
+import { prisma } from "../core/db.js";
+import { NativeEngine } from "../core/engine-native.js";
+import { resolveLlmRegistrations, RoutingLlmProvider } from "../providers/llm/index.js";
+import { PostgresDatastore } from "../providers/datastore/index.js";
+import { PostgresAgentMemory } from "../providers/memory/index.js";
+import { buildConfiguredExecutor, buildExecutor } from "../providers/executor/index.js";
+import { buildSecretCipher } from "../providers/secrets/index.js";
+import { buildAuthProvider } from "../providers/auth/index.js";
+import { buildMcpServer } from "./server.js";
+import { countUnattendedSchedules, unattendedSchedulesWarning } from "./unattended-schedules.js";
+import { runStdioServer } from "./transport/stdio.js";
+import { startHttpServer } from "./transport/streamable-http.js";
+import { resolvePrincipal } from "./auth/principal.js";
+import { SCOPES_SUPPORTED } from "./auth/resource-server.js";
+import { canonicalUrl } from "./transport/http-limits.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerBudgetGroupTools } from "./tools/budget-groups.js";
+import { registerModelTools } from "./tools/models.js";
+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 { registerDatastoreTools } from "./tools/datastore.js";
+import { registerSubAgentTools } from "./tools/subagents.js";
+import { registerMemoryTools } from "./tools/memory.js";
+import { registerSecretsTools } from "./tools/secrets.js";
+import { registerWebhookTools } from "./tools/webhooks.js";
+import { createStdioSecretElicitationHost } from "./tools/secret-elicitation-server.js";
+import { SECRET_ELICITATION_PATH } from "./tools/secret-elicitation-form.js";
+import { logger } from "../core/logger.js";
+const mcpLog = logger.child({ module: "mcp-index" });
+const SELF_HOSTED_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // hourly
+/** Says out loud at startup when enabled schedules exist that nothing in this process will fire (see ./unattended-schedules.ts). */
+async function warnIfNothingWillFireSchedules() {
+    try {
+        const message = unattendedSchedulesWarning(await countUnattendedSchedules(prisma));
+        if (message)
+            mcpLog.warn(message);
+    }
+    catch (err) {
+        // Advisory only - never let it stop the server coming up.
+        mcpLog.debug({ err }, "could not check for unattended schedules");
+    }
+}
+/** Placeholder identifier for stdio, which has no HTTP endpoint to name. Never surfaced: stdio's fixed context always holds every scope, so no scope challenge is ever built against it. */
+const STDIO_PLACEHOLDER_URI = "urn:wardby:local-stdio";
+/** Registers the full Phase 4 tool surface — every module, in one place. */
+export function registerAllTools(mcp, opts) {
+    registerAgentTools(mcp);
+    registerBudgetGroupTools(mcp);
+    registerModelTools(mcp);
+    registerTriggerTool(mcp);
+    registerToolAuthoringTools(mcp);
+    registerSchedulingTools(mcp);
+    registerRunTools(mcp);
+    registerDatastoreTools(mcp);
+    registerSubAgentTools(mcp);
+    registerMemoryTools(mcp);
+    registerSecretsTools(mcp, {
+        buildElicitationUrl: opts.secretElicitationUrl,
+        protocolElicitation: opts.secretElicitationProtocol,
+    });
+    registerWebhookTools(mcp);
+}
+/** Builds the real provider set (LLM/engine/datastore/secrets/executor) — shared by both transports. */
+export function buildMcpProviders() {
+    const providerConfig = loadProviderConfig();
+    const llmResult = resolveLlmRegistrations();
+    if (llmResult.kind !== "registrations") {
+        throw new Error("No LLM credentials present. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, and/or BEDROCK_REGION (or AWS_REGION).");
+    }
+    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);
+    // `nativeProviders` is passed by reference into buildExecutor, and native
+    // runs it drives read `this.providers.executor` at call time (not at
+    // construction time) — so patching `.executor` on afterward, once the
+    // full RoutingExecutor exists, is enough for a native run's own
+    // delegate_to_<boundName> dispatch to reach a coding-kind sub-agent
+    // through the same composed executor everything else uses. There's no
+    // way to hand the native executor a reference to its own wrapping
+    // RoutingExecutor before that wrapper is constructed.
+    const nativeProviders = { llm, engine, datastore, secrets, memory };
+    const nativeExecutor = buildExecutor(providerConfig, nativeProviders, prisma);
+    const executor = buildConfiguredExecutor({ native: nativeExecutor, db: prisma, providerConfig });
+    nativeProviders.executor = executor;
+    return { providers: { llm, engine, datastore, secrets, executor, memory } };
+}
+/** Awaits `promise` (if any), logging and swallowing a rejection instead of propagating it. */
+async function closeQuietly(promise, what) {
+    try {
+        await promise;
+    }
+    catch (err) {
+        mcpLog.warn({ err }, `${what} failed during MCP shutdown`);
+    }
+}
+/** 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();
+    const providers = options.providers ?? buildMcpProviders().providers;
+    await providers.executor.launch?.();
+    if (!options.schedulerAttached)
+        await warnIfNothingWillFireSchedules();
+    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,
+        });
+        registerAllTools(mcp, {
+            secretElicitationUrl: (token) => secretElicitationHost.urlFor(token),
+            secretElicitationProtocol: mcpConfig.secretElicitationProtocol,
+        });
+        // stdio never carries per-call AuthInfo — one fixed, fully-trusted
+        // local identity for the whole connection, per the design's own
+        // "stdio local mode: no token; the operator is trusted."
+        const principal = await resolvePrincipal(mcpConfig.localPrincipal, prisma);
+        mcp.setFixedContext({
+            principal,
+            scopes: new Set(SCOPES_SUPPORTED),
+            canonicalUri: STDIO_PLACEHOLDER_URI,
+            providers,
+            db: prisma,
+            clientSupportsTasks: false,
+            // Placeholder — server.ts's resolveCtx overwrites this with the
+            // current call's real mcpReq on every dispatch.
+            mcpReq: { requestState: () => undefined },
+        });
+        const stdio = runStdioServer(mcp);
+        return {
+            close: async () => {
+                await closeQuietly(stdio.close(), "stdio transport close");
+                await closeQuietly(providers.executor.close?.(), "executor close");
+            },
+        };
+    }
+    if (!mcpConfig.canonicalUri) {
+        throw new Error("MCP_CANONICAL_URI is required when MCP_TRANSPORT=http.");
+    }
+    if (!mcpConfig.httpBind) {
+        throw new Error("MCP_HTTP_BIND is required when MCP_TRANSPORT=http.");
+    }
+    const providerConfig = loadProviderConfig();
+    const authConfig = loadAuthConfig();
+    if (!authConfig.audience || canonicalUrl(mcpConfig.canonicalUri).href !== canonicalUrl(authConfig.audience).href) {
+        throw new Error("MCP_CANONICAL_URI and AUTH_AUDIENCE must be identical normalized URLs.");
+    }
+    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 httpOrigin = canonicalUrl(mcpConfig.canonicalUri).origin;
+    registerAllTools(mcp, {
+        secretElicitationUrl: (token) => Promise.resolve(`${httpOrigin}${SECRET_ELICITATION_PATH}?t=${encodeURIComponent(token)}`),
+        secretElicitationProtocol: mcpConfig.secretElicitationProtocol,
+    });
+    const http = await startHttpServer({
+        mcp,
+        config: {
+            canonicalUri: canonicalUrl(mcpConfig.canonicalUri).href,
+            httpBind: mcpConfig.httpBind,
+            authProviderKind,
+            authorizationServer: authConfig.issuer,
+            allowedOrigins: mcpConfig.allowedOrigins,
+        },
+        auth: { authProvider, db: prisma, providers },
+        selfHosted,
+    });
+    const cleanupTimer = selfHosted
+        ? setInterval(() => {
+            selfHosted.cleanup().catch((err) => mcpLog.warn({ err }, "self-hosted auth cleanup failed"));
+        }, SELF_HOSTED_CLEANUP_INTERVAL_MS)
+        : undefined;
+    return {
+        close: async () => {
+            if (cleanupTimer)
+                clearInterval(cleanupTimer);
+            await closeQuietly(http.close(), "HTTP transport close");
+            await closeQuietly(providers.executor.close?.(), "executor close");
+        },
+    };
+}

package/dist/mcp/jsonrpc.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JSON-RPC 2.0 envelope types, re-exported from the real MCP SDK rather than
+ * hand-rolled: @modelcontextprotocol/server already implements the
+ * 2026-07-28 wire format (including the stateless per-request `_meta`
+ * envelope), and hand-rolling a second, subtly-incompatible copy would be
+ * pure risk for no benefit.
+ */
+export type { JSONRPCMessage, JSONRPCRequest, JSONRPCNotification } from "@modelcontextprotocol/server";

package/dist/mcp/jsonrpc.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/server.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The MCP server core: wraps @modelcontextprotocol/server's McpServer with
+ * wardby's own ToolSpec contract (scope-gated, McpRequestContext-aware).
+ *
+ * Architecture note (adapted from the plan during implementation): the SDK
+ * already provides correct, spec-compliant serving entries —
+ * `createMcpHandler` (HTTP, Task 7) and `serveStdio` (stdio, below) — both
+ * of which construct a fresh McpServer per request/connection from a cheap,
+ * side-effect-free `McpServerFactory`. Hand-rolling message dispatch
+ * ourselves (an earlier draft of this file did exactly that) turned out to
+ * require re-deriving the 2026-07-28 stateless per-request `_meta` envelope
+ * by hand — fragile and exactly the kind of protocol-fidelity risk the real
+ * SDK exists to remove. This file instead accumulates ToolSpecs and exposes
+ * an `McpServerFactory`; the transports (this file's `runStdioServer` /
+ * Task 7's HTTP transport) call it exactly the way the SDK expects.
+ *
+ * Auth threading: per-tool-call caller identity travels as the SDK's own
+ * `AuthInfo.extra.principal` (an in-process object reference, never
+ * serialized — see the official `scoped-tools` example, which enforces
+ * scope the same way, inside each tool handler via `ctx.http?.authInfo`).
+ * stdio has no per-call AuthInfo at all (serveStdio never sets it), so
+ * `setFixedContext` supplies one fixed LOCAL_PRINCIPAL identity for the
+ * whole connection.
+ */
+import { type McpServerFactory, type InputRequiredResult } from "@modelcontextprotocol/server";
+import type { PrismaClient } from "@prisma/client";
+import type { McpRequestContext, McpProviders } from "./context.js";
+export interface ToolSpec<Args = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    /** Scope(s) required to call this tool — checked before the handler ever runs. */
+    scope: string | string[];
+    /**
+     * A plain JSON Schema object (matching this codebase's existing
+     * JSON-Schema-first tool convention — see src/sandbox/deriveJsonSchema).
+     * Converted via the SDK's own `fromJsonSchema()` rather than accepted as
+     * a zod raw shape: `McpServer.registerTool`'s zod-shape overload requires
+     * REAL zod v4, and `@modelcontextprotocol/server` bundles its own nested
+     * zod@4.5.4 copy — any zod v4 wardby itself installs (even the exact
+     * same version) is a structurally-incompatible separate module instance.
+     * JSON Schema has no such identity problem.
+     */
+    inputSchema?: Record<string, unknown>;
+    handler: (args: Args, ctx: McpRequestContext) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent?: unknown;
+    } | InputRequiredResult>;
+}
+export interface McpServerConfig {
+    canonicalUri: string;
+}
+export interface BuildMcpServerOptions {
+    providers: McpProviders;
+    db: PrismaClient;
+    config: McpServerConfig;
+    /** Testability hook for REQUEST_STATE_KEY — defaults to process.env, matching buildSecretCipher's convention. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface DiscoverResultLike {
+    capabilities: {
+        extensions?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+}
+export interface WardbyMcpServer {
+    registerTool<Args = Record<string, unknown>>(spec: ToolSpec<Args>): void;
+    /**
+     * Registers a custom JSON-RPC method (e.g. the Tasks extension's
+     * tasks/get, tasks/cancel, tasks/update — there is no npm runtime package
+     * for the extension, see Task 6's ledger note, so these are hand-wired
+     * the same way this SDK itself expects any custom method to be added:
+     * `Server.setRequestHandler`). Scope is enforced BEFORE the handler runs,
+     * exactly like registerTool — a custom method is not exempt from the
+     * scope gate just because it isn't a tool.
+     */
+    registerRequestHandler(method: string, scope: string | string[], handler: (params: unknown, ctx: McpRequestContext) => Promise<unknown>): void;
+    /** Passed directly to createMcpHandler (Task 7) / serveStdio (below). */
+    factory: McpServerFactory;
+    /** Local capability introspection without a protocol round-trip. */
+    discover(): Promise<DiscoverResultLike>;
+    /** stdio only: the one fixed identity every call in this connection resolves to. */
+    setFixedContext(ctx: McpRequestContext | undefined): void;
+    /**
+     * Seals `payload` into the opaque `requestState` string a multi-round-trip
+     * tool hands back via `inputRequired({ requestState })`. Backed by one
+     * HMAC codec created for the life of this `WardbyMcpServer` (stable across
+     * every `factory()` call, so state minted on one call verifies on a
+     * later one) — see the module doc for why the key never needs to be
+     * shared beyond this process.
+     */
+    mintRequestState<T>(payload: T): Promise<string>;
+    /**
+     * Verifies a `requestState`-shaped token OUTSIDE the normal MCP request
+     * path — used by the secret-elicitation browser form (stdio's ephemeral
+     * local server, or the HTTP transport's mounted route), which receives
+     * the token via a URL query param rather than the protocol's own
+     * `requestState` field. Throws on a malformed, tampered, or expired
+     * token. Uses the same codec as `mintRequestState`/the SDK's own
+     * `ServerOptions.requestState.verify` hook, so a token is valid on
+     * either path interchangeably.
+     */
+    verifyRequestState<T>(token: string): Promise<T>;
+}
+export declare function buildMcpServer(opts: BuildMcpServerOptions): WardbyMcpServer;

package/dist/mcp/server.js

@@ -0,0 +1,203 @@
+/**
+ * The MCP server core: wraps @modelcontextprotocol/server's McpServer with
+ * wardby's own ToolSpec contract (scope-gated, McpRequestContext-aware).
+ *
+ * Architecture note (adapted from the plan during implementation): the SDK
+ * already provides correct, spec-compliant serving entries —
+ * `createMcpHandler` (HTTP, Task 7) and `serveStdio` (stdio, below) — both
+ * of which construct a fresh McpServer per request/connection from a cheap,
+ * side-effect-free `McpServerFactory`. Hand-rolling message dispatch
+ * ourselves (an earlier draft of this file did exactly that) turned out to
+ * require re-deriving the 2026-07-28 stateless per-request `_meta` envelope
+ * by hand — fragile and exactly the kind of protocol-fidelity risk the real
+ * SDK exists to remove. This file instead accumulates ToolSpecs and exposes
+ * an `McpServerFactory`; the transports (this file's `runStdioServer` /
+ * Task 7's HTTP transport) call it exactly the way the SDK expects.
+ *
+ * Auth threading: per-tool-call caller identity travels as the SDK's own
+ * `AuthInfo.extra.principal` (an in-process object reference, never
+ * serialized — see the official `scoped-tools` example, which enforces
+ * scope the same way, inside each tool handler via `ctx.http?.authInfo`).
+ * stdio has no per-call AuthInfo at all (serveStdio never sets it), so
+ * `setFixedContext` supplies one fixed LOCAL_PRINCIPAL identity for the
+ * whole connection.
+ */
+import { McpServer, fromJsonSchema, createRequestStateCodec, CLIENT_CAPABILITIES_META_KEY, } from "@modelcontextprotocol/server";
+import { randomBytes } from "node:crypto";
+import { requireScope } from "./auth/resource-server.js";
+import { McpError } from "./errors.js";
+import { TASKS_EXTENSION_ID, clientSupportsTasks } from "./capabilities.js";
+import { visibleToPrincipal } from "./auth/ownership.js";
+import { logger } from "../core/logger.js";
+const REQUEST_STATE_KEY_BYTES = 32;
+/**
+ * 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.
+ */
+function loadRequestStateKey(env) {
+    const hex = env.REQUEST_STATE_KEY;
+    if (!hex)
+        return randomBytes(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.`);
+    }
+    return key;
+}
+/**
+ * Shown to every connecting client at session start (Claude Code and other
+ * compliant clients surface this directly to the calling assistant) — the
+ * main discovery channel for "you can run a wardby agent's prompt
+ * yourself, right now, instead of only via its schedule/trigger." Paired
+ * with the per-agent MCP prompts registered below, which are the concrete,
+ * one-call way to actually do it.
+ */
+const SERVER_INSTRUCTIONS = 'wardby hosts reusable LLM agents (a system prompt, model, budget, and attached tools) that normally run on a schedule or webhook trigger. Every agent\'s full system prompt is available via list_agents/get_agent ("systemPrompt" field), and agents you can see are also registered as MCP prompts by name — you can adopt an agent\'s instructions and run them yourself, in this session, right now. This is a good way to shift work like code review left: e.g., before committing, run the "systemPrompt" of a code-review agent against your own working tree using your own tools, rather than waiting for a separately triggered run. Where a pulled prompt names a wardby-specific sandboxed tool, use your own equivalent tool for the same purpose instead.';
+/** The MCP prompt body for one Agent — the message a client injects when a user invokes it (e.g. as a slash command). */
+function agentPromptText(agent) {
+    return [
+        `You are adopting the instructions of wardby agent "${agent.name}" (model "${agent.model}") to run directly in this session, instead of waiting for its schedule/trigger.`,
+        "Follow the instructions below as this conversation's operating instructions. Where they name a specific wardby tool that isn't available here, use your own equivalent tool for the same purpose instead.",
+        "---",
+        agent.systemPrompt,
+    ].join("\n\n");
+}
+export function buildMcpServer(opts) {
+    const specs = [];
+    const requestHandlers = [];
+    let fixedContext;
+    // No `bind` callback, so `ctx` is never read by mint()/verify() (confirmed
+    // 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
+    // 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.
+    const requestStateCodec = createRequestStateCodec({
+        key: loadRequestStateKey(opts.env ?? process.env),
+        ttlSeconds: 600,
+    });
+    function mcpReqOf(sdkCtx) {
+        return {
+            inputResponses: sdkCtx.mcpReq?.inputResponses,
+            requestState: sdkCtx.mcpReq?.requestState ?? (() => undefined),
+        };
+    }
+    function resolveCtx(sdkCtx) {
+        const authInfo = sdkCtx.http?.authInfo;
+        const extra = authInfo?.extra;
+        if (extra?.principal) {
+            return {
+                principal: extra.principal,
+                scopes: new Set(authInfo.scopes),
+                canonicalUri: opts.config.canonicalUri,
+                providers: opts.providers,
+                db: opts.db,
+                mcpReq: mcpReqOf(sdkCtx),
+                clientSupportsTasks: clientSupportsTasks(
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- ESLint's type-checked view of `envelope` disagrees with the real tsc build; the cast is load-bearing there.
+                sdkCtx.mcpReq?.envelope?.[CLIENT_CAPABILITIES_META_KEY]),
+            };
+        }
+        if (fixedContext)
+            return { ...fixedContext, mcpReq: mcpReqOf(sdkCtx) };
+        throw new McpError(401, "No authenticated context available for this call.");
+    }
+    function registerTool(spec) {
+        specs.push(spec);
+    }
+    function registerRequestHandler(method, scope, handler) {
+        requestHandlers.push({ method, scope: Array.isArray(scope) ? scope : [scope], handler });
+    }
+    const factory = async () => {
+        const mcpServer = new McpServer({ name: "wardby", version: "0.0.0" }, {
+            requestState: { verify: (state, ctx) => requestStateCodec.verify(state, ctx) },
+            instructions: SERVER_INSTRUCTIONS,
+        });
+        mcpServer.server.registerCapabilities({ extensions: { [TASKS_EXTENSION_ID]: {} } });
+        for (const spec of specs) {
+            const requiredScopes = Array.isArray(spec.scope) ? spec.scope : [spec.scope];
+            mcpServer.registerTool(spec.name, {
+                description: spec.description,
+                inputSchema: spec.inputSchema ? fromJsonSchema(spec.inputSchema) : undefined,
+            }, async (args, sdkCtx) => {
+                const ctx = resolveCtx(sdkCtx);
+                requireScope(ctx, opts.config.canonicalUri, ...requiredScopes);
+                return spec.handler(args, ctx);
+            });
+        }
+        // Non-spec (extension) methods need a { params, result } schema bundle
+        // — setRequestHandler only resolves schemas from the method name for
+        // spec methods (see docs/advanced/custom-methods.md). A permissive
+        // passthrough JSON Schema on both sides keeps this generic: real
+        // validation of taskId/etc. happens inside each handler, not here.
+        const PERMISSIVE_SCHEMA = fromJsonSchema({ type: "object", additionalProperties: true });
+        for (const { method, scope, handler } of requestHandlers) {
+            mcpServer.server.setRequestHandler(method, { params: PERMISSIVE_SCHEMA }, async (params, sdkCtx) => {
+                const ctx = resolveCtx(sdkCtx);
+                requireScope(ctx, opts.config.canonicalUri, ...scope);
+                return (await handler(params, ctx));
+            });
+        }
+        // One MCP prompt per Agent this connection can see, so a client that
+        // supports the prompts UI (e.g. a slash-command picker) can run a
+        // wardby agent directly — the concrete half of the "shift left"
+        // discovery story SERVER_INSTRUCTIONS introduces. Identity isn't
+        // reliably known yet for an HTTP connection at this point (resolveCtx
+        // resolves it per-dispatch from the SDK's own per-call ServerContext,
+        // not at factory time) — stdio's fixedContext IS set by now
+        // (mcp/index.ts calls setFixedContext before serveStdio ever invokes
+        // this factory), so stdio sees every agent it owns plus public ones;
+        // HTTP conservatively falls back to public-only until this factory can
+        // see request-scoped identity. A DB hiccup here must not break tool
+        // registration — this is a discoverability nicety, not core function.
+        try {
+            const where = fixedContext ? visibleToPrincipal(fixedContext.principal.id) : { ownerId: null };
+            const agents = await opts.db.agent.findMany({ where });
+            for (const agent of agents) {
+                mcpServer.registerPrompt(agent.name, {
+                    title: agent.name,
+                    description: `Run wardby agent "${agent.name}" (model ${agent.model}) directly in this session, instead of via its schedule/trigger.`,
+                }, () => ({
+                    messages: [{ role: "user", content: { type: "text", text: agentPromptText(agent) } }],
+                }));
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, "failed to register agent prompts — continuing without them");
+        }
+        return mcpServer;
+    };
+    async function discover() {
+        const probe = (await factory({ era: "modern" }));
+        return { capabilities: probe.server.getCapabilities() };
+    }
+    function setFixedContext(ctx) {
+        fixedContext = ctx;
+    }
+    function mintRequestState(payload) {
+        return requestStateCodec.mint(payload);
+    }
+    function verifyRequestState(token) {
+        // `ctx` is unused by verify() when no `bind` is configured (see the
+        // codec construction above) — this cast stands in for the real
+        // ServerContext an MCP request would supply.
+        return requestStateCodec.verify(token, {});
+    }
+    return {
+        registerTool,
+        registerRequestHandler,
+        factory,
+        discover,
+        setFixedContext,
+        mintRequestState,
+        verifyRequestState,
+    };
+}

package/dist/mcp/tasks/manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Task manager: maps a Run's lifecycle onto the MCP Tasks extension
+ * (io.modelcontextprotocol/tasks, schema 2026-07-28 — field names verified
+ * against the extension's own reference TypeScript, not guessed). A "run"
+ * task's live status/result is always DERIVED from Run.status on read —
+ * the persisted Task row's own `status` column is the task's independent
+ * lifecycle stamp, mutated only by createRunTask (-> working) and
+ * cancelTask (-> cancelled, a terminal task-level state that intentionally
+ * doesn't unwind even if the underlying run later finishes on its own —
+ * cancellation is cooperative and eventually consistent, per the
+ * extension's own spec language).
+ */
+import type { PrismaClient, Task } from "@prisma/client";
+export type TaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled";
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface TaskFields {
+    taskId: string;
+    status: TaskStatus;
+    statusMessage?: string;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttlMs: number | null;
+    pollIntervalMs?: number;
+}
+export type CreateTaskResult = TaskFields & {
+    resultType: "task";
+};
+export type GetTaskResult = (TaskFields & {
+    resultType: "complete";
+    status: "working";
+}) | (TaskFields & {
+    resultType: "complete";
+    status: "input_required";
+    inputRequests: Record<string, unknown>;
+}) | (TaskFields & {
+    resultType: "complete";
+    status: "completed";
+    result: Record<string, unknown>;
+}) | (TaskFields & {
+    resultType: "complete";
+    status: "failed";
+    error: JsonRpcErrorObject;
+}) | (TaskFields & {
+    resultType: "complete";
+    status: "cancelled";
+});
+export declare function createTaskResult(row: Task, ttlMs: number): CreateTaskResult;
+/** Starts a run-backed task: persists the Task row BEFORE returning, so a client's first tasks/get always finds it. */
+export declare function createRunTask(runId: string, principalId: string, db: PrismaClient, ttlMs: number): Promise<CreateTaskResult>;
+/** Reads a task's current state, deriving a run task's status from the live Run.status. */
+export declare function getTask(taskId: string, db: PrismaClient): Promise<GetTaskResult>;
+/**
+ * Cooperatively stops a task's underlying run (best-effort — cancellation
+ * is eventually consistent). A no-op when the run has already reached a
+ * terminal status on its own; the stop hook is never called for a run
+ * that's already finished.
+ */
+export declare function cancelTask(taskId: string, db: PrismaClient, stopRun: (runId: string) => Promise<void>): Promise<void>;
+export {};