@wardby/cli 0.7.0 → 0.8.0

package/dist/providers/coding-proxy/types.d.ts

@@ -1,6 +1,7 @@
 import { type CatalogEntry } from "../llm/catalog-types.js";
 import type { ModelPricing } from "../llm/pricing-core.js";
 import type { ProxyRefusalDetails } from "../../core/budget-events.js";
+import type { McpToolPin } from "../../core/mcp-tools.js";
 export type ProxySessionStatus = "active" | "cancelled";
 export type ProxyRequestStatus = "reserved" | "completed" | "released" | "uncertain";
 export type ProxyProtocol = "openai-responses" | "anthropic-messages";
@@ -46,6 +47,12 @@ export interface ProxySession {
     upstreamFailure?: string | null;
     /** The run's catalog entry, copied at session creation; null on sessions from before the catalog. */
     terms?: ProxyModelTerms | null;
+    /** The run's pinned MCP tools (no URLs or secrets); null when the run has none, and on older sessions. */
+    mcpTools: McpToolPin[] | null;
+    /** SHA-256 (base64url) of the run's MCP token; null when the run has no MCP tools. */
+    mcpTokenHash: string | null;
+    /** The run's MCP tools/call count so far. */
+    mcpCallCount: number;
 }
 export interface ProxyRequest {
     id: string;
@@ -89,6 +96,10 @@ export interface CreateProxySessionInput {
     budgetUsd: number;
     registryTokenHash: string;
     terms?: ProxyModelTerms;
+    /** The run's pinned MCP tools; set together with mcpTokenHash, and only when there is at least one. */
+    mcpTools?: McpToolPin[];
+    /** SHA-256 (base64url) of the run's MCP token (mcpTokenHash in src/coding/mcp-token.ts). */
+    mcpTokenHash?: string;
 }
 export interface ReserveProxyRequestInput {
     id: string;
@@ -122,6 +133,8 @@ export type ReserveProxyRequestResult = {
 export interface ProxyLedger {
     createSession(input: CreateProxySessionInput): Promise<void>;
     findSessionByCapabilityHash(capabilityHash: string): Promise<ProxySession | null>;
+    /** The session whose MCP token hashes to this; any status (the caller checks it is active and in time). */
+    findSessionByMcpTokenHash(mcpTokenHash: string): Promise<ProxySession | undefined>;
     reserve(input: ReserveProxyRequestInput): Promise<ReserveProxyRequestResult>;
     complete(requestId: string, usage: ProxyUsage, actualCostUsd: number, upstreamStatus: number): Promise<ProxyRequest>;
     release(requestId: string, upstreamStatus: number): Promise<void>;

package/dist/providers/executor/composition.js

@@ -26,6 +26,7 @@ import { RunTranscriptRecorder, loadTranscriptMaxBytes, loadTranscriptRetentionD
 import { loadAgentSecretValues } from "../../core/secret-guard.js";
 import { createBlobStore } from "../storage/index.js";
 import { ContainerExecutor, PrismaContainerExecutionStore, RunCapabilityVault } from "./container.js";
+import { loadMcpToolPins } from "../../core/mcp-tools.js";
 import { PrismaExecutionKindResolver, RoutingExecutor } from "./routing.js";
 import { createRepoAccessGate } from "../../core/repo-access.js";
 import { buildIssueTrackers } from "../issue-tracker/index.js";
@@ -116,6 +117,7 @@ export function buildConfiguredExecutor(options) {
             config: kubernetes,
             workspaceRoot,
             resolveCapability: (runId) => capabilities.get(runId),
+            resolveMcpToken: (runId) => capabilities.mcpToken(runId),
             readyTimeoutMs: kubernetes.readyTimeoutMs,
             enforcementExecTimeoutMs: kubernetes.enforcementExecTimeoutMs,
             power: options.power ?? DISABLED_POWER,
@@ -140,6 +142,7 @@ export function buildConfiguredExecutor(options) {
             workspaceRoot,
             proxyContainer: proxyContainer,
             resolveCapability: (runId) => capabilities.get(runId),
+            resolveMcpToken: (runId) => capabilities.mcpToken(runId),
             isRunActive: async (runId, handle) => {
                 const coding = await options.db.codingRun.findUnique({
                     where: { runId },
@@ -177,6 +180,8 @@ export function buildConfiguredExecutor(options) {
         vcs,
         sessions,
         capabilities,
+        // Remote MCP servers: a coding run gets its agent's pinned tools and an MCP token ([] when off).
+        mcpToolPins: (agentId, pinOptions) => loadMcpToolPins(options.db, agentId, pinOptions),
         artifactRoot,
         workerImage: config.workerImage,
         claudeWorkerImage: config.claudeWorkerImage,

package/dist/providers/executor/container.d.ts

@@ -1,6 +1,7 @@
 import { type PackageAuditEntry, type PackageAuditMode } from "../../coding/registry/audit-mode.js";
 import type { PrismaClient } from "#prisma";
 import type { RunTranscriptRecorder } from "../../coding/transcript/recorder.js";
+import { type McpToolPin } from "../../core/mcp-tools.js";
 import { type CodingProvider } from "../../coding/provider.js";
 import { type TopUpOutcome } from "../../core/budget-topup.js";
 import type { IssueTrackerRegistry } from "../issue-tracker/types.js";
@@ -172,6 +173,12 @@ export interface ContainerRunSnapshot {
     profileRepository: string | null;
     /** How the profile's repository was authorized (CodingAgentProfile.repositoryAuthorizedVia). */
     repositoryAuthorizedVia: string | null;
+    /** The run's repository was chosen from the agent's list (CodingRun.viaRepositoryLink). */
+    viaRepositoryLink: boolean;
+    /** How the agent's current write link for the run's repository was authorized; null when there is none. */
+    repositoryLinkAuthorizedVia: string | null;
+    /** The agent's write link for the run's repository still exists (always false for a run not made via a link). */
+    repositoryLinkExists: boolean;
     /** The run's catalog entry recorded at dispatch (Run.pricingSnapshot); null on runs from before the catalog. */
     pricingVersion: string | null;
     pricingSnapshot: unknown;
@@ -327,6 +334,10 @@ export interface CodingSessionController {
         budgetUsd: number;
         /** The run's catalog entry; the proxy prices and shapes the run's requests from it. */
         terms?: ProxyModelTerms;
+        /** The run's pinned MCP tools; set with mcpTokenHash, only when the agent has at least one. */
+        mcpTools?: McpToolPin[];
+        /** The hash of the run's MCP token (src/coding/mcp-token.ts); the token itself stays in the vault. */
+        mcpTokenHash?: string;
     }): Promise<{
         id: string;
         capability: string;
@@ -337,11 +348,19 @@ export interface CodingSessionController {
     /** The code of the first model-provider failure the proxy relayed for this session, if any. */
     upstreamFailure?(sessionId: string): Promise<string | null>;
 }
-/** Plain capabilities live only for the short provisioning window. */
+/**
+ * Plain capabilities live only for the short provisioning window. A run with MCP tools keeps its
+ * MCP token here too, next to the capability, so the launcher delivers it the same way; both are
+ * deleted together.
+ */
 export declare class RunCapabilityVault {
     private readonly values;
+    private readonly mcpTokens;
     set(runId: string, capability: string): void;
     get(runId: string): Promise<string>;
+    setMcpToken(runId: string, token: string): void;
+    /** The run's MCP token; undefined for a run without MCP tools (and once the launch is over). */
+    mcpToken(runId: string): Promise<string | undefined>;
     delete(runId: string): void;
 }
 export interface ContainerExecutorOptions {
@@ -352,6 +371,15 @@ export interface ContainerExecutorOptions {
     vcs: VcsProvider;
     sessions: CodingSessionController;
     capabilities: RunCapabilityVault;
+    /**
+     * The agent's MCP tool pins (composition wires loadMcpToolPins; [] when WARDBY_MCP_SERVERS=off).
+     * Absent = no coding run gets MCP tools. A run with pins gets an MCP token, delivered as
+     * WARDBY_MCP_TOKEN; one without gets neither. `readOnlyOnly` comes from the run's dispatched
+     * provider (isCodexCoding(run.provider)), never the agent's current profile.
+     */
+    mcpToolPins?: (agentId: string, options: {
+        readOnlyOnly: boolean;
+    }) => Promise<McpToolPin[]>;
     artifactRoot: string;
     /**
      * The Codex worker for the "node" toolchain (CODING_WORKER_IMAGE). Optional on a Claude-only
@@ -725,3 +753,7 @@ export declare class ContainerExecutor implements Executor {
 }
 /** Operator-facing failure text: the message plus its cause chain, redacted. */
 export declare function describeFailure(error: unknown, depth?: number): string;
+/** The agent's MCP tool pins could not be read at launch (a database error): the run fails, nothing launched. */
+export declare const MCP_PINS_UNAVAILABLE_ERROR = "coding_mcp_pins_unavailable";
+/** Its category: the run's error is coding_failure_mcp_pins_unavailable:<diagnostic id>. */
+export declare const MCP_PINS_UNAVAILABLE_CATEGORY = "mcp_pins_unavailable";

package/dist/providers/executor/container.js

@@ -3,6 +3,9 @@ import { isPackageAuditMode, mergePackageAuditReports, } from "../../coding/regi
 import { mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { withBaseCommit } from "../../coding/base-commit.js";
+import { mcpTokenHash, mintMcpToken } from "../../coding/mcp-token.js";
+import { isCodexCoding } from "../../core/mcp-tools.js";
+import { codeProviderOf } from "../../coding/code-host.js";
 import { withPullRequestDescription } from "../../coding/pr-description-note.js";
 import { withLinkedIssue } from "../../coding/linked-issue-note.js";
 import { buildClaudeContext, MAX_RECORDED_SKIPS } from "../../coding/claude-context.js";
@@ -169,6 +172,17 @@ export class PrismaContainerExecutionStore {
         });
         if (!row?.codingRun)
             return null;
+        const link = row.codingRun.viaRepositoryLink
+            ? await this.db.agentRepository.findFirst({
+                where: {
+                    agentId: row.agentId,
+                    repository: row.codingRun.repository,
+                    access: "write",
+                    triggers: { isEmpty: true },
+                },
+                select: { authorizedVia: true },
+            })
+            : null;
         return {
             runId: row.id,
             agentId: row.agentId,
@@ -219,6 +233,9 @@ export class PrismaContainerExecutionStore {
             failureCategory: row.codingRun.failureCategory,
             profileRepository: row.agent.codingProfile?.repository ?? null,
             repositoryAuthorizedVia: row.agent.codingProfile?.repositoryAuthorizedVia ?? null,
+            viaRepositoryLink: row.codingRun.viaRepositoryLink,
+            repositoryLinkExists: link !== null,
+            repositoryLinkAuthorizedVia: link?.authorizedVia ?? null,
             pricingVersion: row.pricingVersion,
             pricingSnapshot: row.pricingSnapshot,
         };
@@ -596,9 +613,14 @@ export class PrismaContainerExecutionStore {
         return changed;
     }
 }
-/** Plain capabilities live only for the short provisioning window. */
+/**
+ * Plain capabilities live only for the short provisioning window. A run with MCP tools keeps its
+ * MCP token here too, next to the capability, so the launcher delivers it the same way; both are
+ * deleted together.
+ */
 export class RunCapabilityVault {
     values = new Map();
+    mcpTokens = new Map();
     set(runId, capability) {
         if (this.values.has(runId))
             throw new Error("coding_capability_exists");
@@ -610,8 +632,18 @@ export class RunCapabilityVault {
             throw new Error("coding_capability_unavailable");
         return capability;
     }
+    setMcpToken(runId, token) {
+        if (this.mcpTokens.has(runId))
+            throw new Error("coding_mcp_token_exists");
+        this.mcpTokens.set(runId, token);
+    }
+    /** The run's MCP token; undefined for a run without MCP tools (and once the launch is over). */
+    async mcpToken(runId) {
+        return this.mcpTokens.get(runId);
+    }
     delete(runId) {
         this.values.delete(runId);
+        this.mcpTokens.delete(runId);
     }
 }
 /** A run's deduplicated served packages and refusals (see summarizeRegistryFetches), and its package audit. */
@@ -827,6 +859,20 @@ export class ContainerExecutor {
                 if (TERMINAL_STATUSES.has(beforeSession.status))
                     throw new Error("coding_run_no_longer_active");
                 const deadlineAt = new Date(this.now().getTime() + run.timeoutSec * 1_000);
+                // The agent's MCP tools, pinned for the run; only a run with some gets a token. The token is
+                // never logged: only its hash goes to the session, the value only into the vault.
+                // A Codex run's shell commands can read the token, so it gets read-only tools only; decided by
+                // the provider the run was dispatched with, which is what jobSpec launches. A failed read fails
+                // the run with a fixed code (the cause goes to the operator log only, redacted).
+                let mcpTools;
+                try {
+                    mcpTools =
+                        (await this.options.mcpToolPins?.(run.agentId, { readOnlyOnly: isCodexCoding(run.provider) })) ?? [];
+                }
+                catch (error) {
+                    throw new Error(MCP_PINS_UNAVAILABLE_ERROR, { cause: error });
+                }
+                const mcpToken = mcpTools.length > 0 ? mintMcpToken() : undefined;
                 const session = await this.options.sessions.createSession({
                     runId,
                     credentialRef: this.credentialRef(run.provider),
@@ -835,15 +881,18 @@ export class ContainerExecutor {
                     deadlineAt,
                     budgetUsd: run.budgetUsd,
                     terms: this.modelTerms(run),
+                    ...(mcpToken ? { mcpTools, mcpTokenHash: mcpTokenHash(mcpToken) } : {}),
                 });
                 spendEnabled = true;
                 sessionId = session.id;
                 this.options.capabilities.set(runId, session.capability);
+                if (mcpToken)
+                    this.options.capabilities.setMcpToken(runId, mcpToken);
                 const inputArtifact = await this.writeInput(run, deadlineAt, workspace);
                 const beforeLaunch = await this.requireCurrent(runId);
                 if (TERMINAL_STATUSES.has(beforeLaunch.status))
                     throw new Error("coding_run_no_longer_active");
-                const spec = this.jobSpec(run, inputArtifact);
+                const spec = this.jobSpec(run, inputArtifact, { mcpTools: Boolean(mcpToken) });
                 // Backends whose handle is derivable (Kubernetes) persist it first, so a crash between the
                 // launch and the write still leaves a handle `abandon()` can stop and remove the run with.
                 planned = this.options.jobs.plannedHandle?.(spec);
@@ -1005,13 +1054,21 @@ export class ContainerExecutor {
      * access. Throws RepoAccessError (refused before anything is cloned).
      */
     async authorizeRepository(run, opts) {
+        // Checked first: a local repository is otherwise authorized by the trusted roots alone.
+        if (run.viaRepositoryLink && !run.repositoryLinkExists)
+            throw new RepoAccessError("repo_access_not_authorized");
         const sameRepository = run.profileRepository !== null && run.profileRepository === run.repository;
+        const authorizedVia = run.viaRepositoryLink
+            ? run.repositoryLinkAuthorizedVia
+            : sameRepository
+                ? run.repositoryAuthorizedVia
+                : "host_permission";
         const decision = await this.options.repoAccess.authorizeUse({
             ownerId: run.ownerId,
-            provider: "github",
+            provider: codeProviderOf(run.repository),
             repository: run.repository,
             required: requiredLevel("coding"),
-            authorizedVia: sameRepository ? run.repositoryAuthorizedVia : "host_permission",
+            authorizedVia,
             retryTransient: opts.inFlight,
         });
         if (!decision.ok)
@@ -1510,7 +1567,8 @@ export class ContainerExecutor {
             status.number > 0) {
             candidates.push({ provider: "github", repository: run.repository, number: status.number });
         }
-        const closed = closingIssueNumber(description, run.repository);
+        // The closing keyword names a GitHub issue: no other host's repository has one to read.
+        const closed = codeProviderOf(run.repository) === "github" ? closingIssueNumber(description, run.repository) : undefined;
         if (closed !== undefined && !candidates.some((ref) => ref.provider === "github" && ref.number === closed)) {
             candidates.push({ provider: "github", repository: run.repository, number: closed });
         }
@@ -1724,7 +1782,8 @@ export class ContainerExecutor {
             if (!workspace)
                 throw new Error("coding_workspace_lost");
             // The same in-flight access check a push gets: a revoked owner's run edits nothing.
-            await this.authorizeRepository(run, { inFlight: true });
+            // Reloaded: the snapshot passed in predates the description reads above, and a link removed since then counts.
+            await this.authorizeRepository(await this.requireCurrent(run.runId), { inFlight: true });
             const details = {
                 summary: output.summary,
                 tests: output.tests,
@@ -1990,7 +2049,7 @@ export class ContainerExecutor {
         this.emit({ stage: "queued", runId: run.runId });
         return false;
     }
-    jobSpec(run, inputArtifact) {
+    jobSpec(run, inputArtifact, options = {}) {
         const provider = run.provider === "claude-code" ? "claude-code" : "codex";
         if (provider === "claude-code" && (!run.workerImage || !this.options.claudeToolRunnerImage)) {
             throw new Error("coding_provider_not_configured:claude-code");
@@ -2019,6 +2078,8 @@ export class ContainerExecutor {
             ...(run.dependencyCache ? { dependencyCache: true } : {}),
             // Claude Code only: the launcher gives the SDK's config dir, where the session grows, its own scratch.
             ...(run.sessionResume && provider === "claude-code" ? { sessionResume: true } : {}),
+            // Only for a run with MCP tools: the launcher then delivers WARDBY_MCP_TOKEN from the vault.
+            ...(options.mcpTools ? { mcpTools: true } : {}),
             timeoutSec: run.timeoutSec,
             limits: { ...this.options.limits, ...(run.workspaceDiskMb ? { diskMb: run.workspaceDiskMb } : {}) },
             labels: {},
@@ -2420,6 +2481,10 @@ function safeError(error) {
     const message = error instanceof Error ? error.message : "unknown";
     return `coding_executor:${redactAndTruncate(message, 200).replace(/[^A-Za-z0-9_.:-]/g, "_")}`;
 }
+/** The agent's MCP tool pins could not be read at launch (a database error): the run fails, nothing launched. */
+export const MCP_PINS_UNAVAILABLE_ERROR = "coding_mcp_pins_unavailable";
+/** Its category: the run's error is coding_failure_mcp_pins_unavailable:<diagnostic id>. */
+export const MCP_PINS_UNAVAILABLE_CATEGORY = "mcp_pins_unavailable";
 /**
  * Error-code prefixes that name their category outright, checked before the
  * substring heuristics below. Those heuristics filed every `github_*` error
@@ -2453,7 +2518,11 @@ const CATEGORY_BY_PREFIX = [
     ["coding_provider_not_configured", "preflight"],
     // A GitHub repository on a server with no GitHub App: configuration, like an unsupported service.
     ["vcs_github_not_configured", "preflight"],
+    // The same for any other host: a repository whose provider this server has not registered.
+    ["vcs_host_provider_not_configured", "preflight"],
     ["vcs_", "workspace"],
+    // The agent's MCP tool pins could not be read at launch: nothing was launched.
+    [MCP_PINS_UNAVAILABLE_ERROR, MCP_PINS_UNAVAILABLE_CATEGORY],
     // Local repositories (LocalRepoError codes): the same family as the vcs_ errors.
     ["local_", "workspace"],
     ["git_", "workspace"],

package/dist/providers/host-tools/invoke.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runs one approved snapshot of a bound tool with a restricted privileged host: fetch
+ * reaches the provider's API hosts inside this call's repository, using the operation's
+ * methods, with no redirects followed and only plain content headers, and the only secret alias is `host`. Datastores and readable secrets are
+ * absent, and console output is dropped. Never throws: every failure is a fixed code,
+ * so no tool text reaches a model, a run record or a published comment.
+ */
+import type { SandboxLimits } from "../../sandbox/eval-core.js";
+import { safeFetch } from "../../sandbox/safe-fetch.js";
+import type { SecretEntry } from "../../core/secrets.js";
+import { type HostOperation, type HostToolDeclineCode } from "./operations.js";
+export declare const HOST_SECRET_ALIAS = "host";
+export type HostToolErrorCode = "host_tool_failed" | "host_tool_timeout" | "host_tool_invalid_result" | "host_tool_invalid_params" | "host_tool_request_denied" | "host_tool_no_credential" | `host_${HostToolDeclineCode}`;
+export type HostToolResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    code: HostToolErrorCode;
+};
+export interface HostToolInvocation {
+    provider: string;
+    operation: HostOperation;
+    snapshot: {
+        code: string;
+        paramsZod: string;
+    };
+    params: Record<string, unknown>;
+    apiHosts: readonly string[];
+    pathPrefix: string;
+    credential: () => Promise<SecretEntry | undefined>;
+    fetchImpl?: typeof safeFetch;
+    limits?: Partial<SandboxLimits>;
+    /** The approved snapshot's time limit (effectiveToolTimeoutMs); absent = the default. */
+    timeoutMs?: number;
+}
+export declare function invokeHostTool(input: HostToolInvocation): Promise<HostToolResult>;

package/dist/providers/host-tools/invoke.js

@@ -0,0 +1,117 @@
+import { createPrivilegedHost } from "../../sandbox/host-functions.js";
+import { runToolCode, toolLimits } from "../../sandbox/run-in-sandbox.js";
+import { fetchTimeoutFor } from "../../sandbox/tool-timeout.js";
+import { WALL_TIME_LIMIT_MS } from "../../sandbox/limits.js";
+import { safeFetch } from "../../sandbox/safe-fetch.js";
+import { validateParams } from "../../sandbox/zod-params.js";
+import { HOST_OPERATIONS, HOST_TOOL_DECLINE_CODES, } from "./operations.js";
+import { assertHostToolHeaders, assertHostToolRequest, HostToolRequestDenied, MAX_HOST_TOOL_FETCHES, } from "./request-guard.js";
+export const HOST_SECRET_ALIAS = "host";
+const absent = async () => {
+    throw new Error("host_tool_capability_absent");
+};
+export async function invokeHostTool(input) {
+    const definition = HOST_OPERATIONS[input.operation];
+    const failures = { denied: false, noCredential: false };
+    const validated = await validateParams(input.snapshot.paramsZod, input.params);
+    if (!validated.ok)
+        return { ok: false, code: "host_tool_invalid_params" };
+    const privileged = (signal) => {
+        const inner = createPrivilegedHost({
+            agentId: `host-provider:${input.provider}`,
+            // Never reached: every bridge that would use them is `absent` below.
+            datastore: {},
+            sharedDatastore: {},
+            logTag: `host-tool:${input.operation}`,
+            allowedFetchHosts: [...input.apiHosts],
+            // Redirects are never followed here: a later hop would skip the guard, so the tool re-fetches through it.
+            fetchImpl: (u, i, o) => (input.fetchImpl ?? safeFetch)(u, i, { ...o, followRedirects: false }),
+            signal,
+            fetchTimeoutMs: fetchTimeoutFor(input.timeoutMs ?? input.limits?.wallTimeLimitMs ?? WALL_TIME_LIMIT_MS),
+            secrets: {
+                get: async () => undefined,
+                resolve: async (name) => {
+                    if (name !== HOST_SECRET_ALIAS)
+                        return undefined;
+                    let entry;
+                    try {
+                        entry = await input.credential();
+                    }
+                    catch {
+                        entry = undefined;
+                    }
+                    // A thrown or partial credential must not carry its text into tool code. Registering
+                    // checks the hosts, but a broker config can be narrowed afterwards.
+                    if (!entry || !entry.broker || input.apiHosts.some((h) => !entry.broker.hosts.includes(h))) {
+                        failures.noCredential = true;
+                        throw new Error("host_tool_no_credential");
+                    }
+                    return entry;
+                },
+            },
+        });
+        let fetches = 0;
+        return {
+            __bridge_console: async () => null,
+            __bridge_fetch: async (argsJson) => {
+                try {
+                    const [url, init, secretNames] = JSON.parse(argsJson);
+                    if (++fetches > MAX_HOST_TOOL_FETCHES)
+                        throw new HostToolRequestDenied();
+                    if (secretNames !== undefined &&
+                        !(Array.isArray(secretNames) && secretNames.every((n) => n === HOST_SECRET_ALIAS))) {
+                        throw new HostToolRequestDenied();
+                    }
+                    assertHostToolHeaders(init?.headers);
+                    assertHostToolRequest(url, init?.method ?? "GET", {
+                        apiHosts: input.apiHosts,
+                        pathPrefix: input.pathPrefix,
+                        methods: definition.methods,
+                    });
+                }
+                catch (err) {
+                    failures.denied = true;
+                    throw err;
+                }
+                return inner.__bridge_fetch(argsJson);
+            },
+            __bridge_datastoreGet: absent,
+            __bridge_datastoreSet: absent,
+            __bridge_datastoreDelete: absent,
+            __bridge_datastoreList: absent,
+            __bridge_sharedDatastoreGet: absent,
+            __bridge_sharedDatastoreSet: absent,
+            __bridge_sharedDatastoreDelete: absent,
+            __bridge_sharedDatastoreList: absent,
+            __bridge_secretsGet: absent,
+        };
+    };
+    const result = await runToolCode({
+        code: input.snapshot.code,
+        params: validated.value,
+        limits: toolLimits(input.timeoutMs, input.limits),
+        privileged,
+    });
+    // Checked first: a tool that catches a refusal must not turn it into a success.
+    if (failures.denied)
+        return { ok: false, code: "host_tool_request_denied" };
+    if (failures.noCredential)
+        return { ok: false, code: "host_tool_no_credential" };
+    if (!result.ok) {
+        return {
+            ok: false,
+            code: result.errorKind === "timeout" || result.errorKind === "cpu" ? "host_tool_timeout" : "host_tool_failed",
+        };
+    }
+    const decline = declineOf(result.value);
+    if (decline)
+        return { ok: false, code: `host_${decline}` };
+    const parsed = definition.result.safeParse(result.value);
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, code: "host_tool_invalid_result" };
+}
+function declineOf(value) {
+    if (typeof value !== "object" || value === null || !("error" in value))
+        return null;
+    const { error } = value;
+    return HOST_TOOL_DECLINE_CODES.includes(error) ? error : null;
+}

package/dist/providers/host-tools/operations.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The contract between Wardby and a host provider's bound tools. A bound tool makes
+ * one host operation; paging, markers, safeguards and wording stay in Wardby. Wardby
+ * calls each tool with `{ workspace, repo, repository, ...operation fields }`.
+ *
+ * A tool answers with its operation's result, or `{ error: <decline code> }` when the
+ * host refused. Results are untrusted and validated here, and a tool's own text never
+ * reaches a model, a run record or a comment.
+ */
+import { z } from "zod";
+export declare const HOST_TOOL_CONTRACT_VERSION = 1;
+/** What a tool may say about a host refusal: fixed words, so no tool text passes through. */
+export declare const HOST_TOOL_DECLINE_CODES: readonly ["unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "unavailable"];
+export type HostToolDeclineCode = (typeof HOST_TOOL_DECLINE_CODES)[number];
+type OperationDef = {
+    /** The HTTP methods this operation's requests may use. */
+    methods: readonly string[];
+    /** Changes nothing on the host: test_host_provider may call it. */
+    readOnly: boolean;
+    /** Which credential its `host` alias resolves to. */
+    credential: "repository" | "permission" | "none";
+    result: z.ZodType;
+};
+export declare const HOST_OPERATIONS: {
+    readonly getPullRequest: OperationDef;
+    readonly listPullRequestFiles: OperationDef;
+    readonly getDiff: OperationDef;
+    readonly findPullRequest: OperationDef;
+    readonly readFile: OperationDef;
+    readonly listFiles: OperationDef;
+    readonly listComments: OperationDef;
+    readonly listCommitStatuses: OperationDef;
+    readonly getRepositoryPermission: {
+        readonly methods: readonly ["GET"];
+        readonly readOnly: true;
+        readonly credential: "permission";
+        readonly result: z.ZodObject<{
+            permission: z.ZodEnum<{
+                read: "read";
+                write: "write";
+                none: "none";
+                triage: "triage";
+                maintain: "maintain";
+                admin: "admin";
+            }>;
+        }, z.core.$strict>;
+    };
+    readonly openPullRequest: OperationDef;
+    readonly updatePullRequest: OperationDef;
+    readonly createComment: OperationDef;
+    readonly editComment: OperationDef;
+    readonly resolveThread: OperationDef;
+    readonly submitVerdict: OperationDef;
+    readonly setCommitStatus: OperationDef;
+    readonly normalizeEvent: {
+        readonly methods: readonly [];
+        readonly readOnly: false;
+        readonly credential: "none";
+        readonly result: z.ZodUnknown;
+    };
+};
+export type HostOperation = keyof typeof HOST_OPERATIONS;
+export declare const REQUIRED_OPERATIONS: readonly HostOperation[];
+export declare function isHostOperation(name: string): name is HostOperation;
+export {};