@wardby/cli 0.1.0

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

@@ -0,0 +1,18 @@
+import type { PrismaClient } from "@prisma/client";
+import { startDenyPortListener } from "./deny-port.js";
+import { startCodingProxyServer, type CodingProxyServerHandle } from "./server.js";
+import type { ProxyAuditSink } from "./types.js";
+export interface CodingProxyRuntimeOptions {
+    db: PrismaClient;
+    env?: NodeJS.ProcessEnv;
+    startServer?: typeof startCodingProxyServer;
+    startDenyPort?: typeof startDenyPortListener;
+    audit?: ProxyAuditSink;
+    onRequest?: (event: {
+        protocol: "openai-responses" | "anthropic-messages" | "other";
+        status: number;
+        durationMs: number;
+    }) => void;
+}
+/** Starts the trusted proxy with the fixed worker-only Docker endpoint, plus the deny port the enforcement witness probes. */
+export declare function startConfiguredCodingProxy(options: CodingProxyRuntimeOptions): Promise<CodingProxyServerHandle>;

package/dist/providers/coding-proxy/runtime.js

@@ -0,0 +1,39 @@
+import { CODING_PROXY_ALIAS, CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "../jobs/docker-isolation.js";
+import { startDenyPortListener } from "./deny-port.js";
+import { EnvironmentCredentialResolver } from "./environment-credentials.js";
+import { CodingProxy } from "./proxy.js";
+import { PrismaProxyLedger } from "./prisma-ledger.js";
+import { startCodingProxyServer } from "./server.js";
+/** Starts the trusted proxy with the fixed worker-only Docker endpoint, plus the deny port the enforcement witness probes. */
+export async function startConfiguredCodingProxy(options) {
+    const env = options.env ?? process.env;
+    const proxy = new CodingProxy({
+        ledger: new PrismaProxyLedger(options.db),
+        credentials: new EnvironmentCredentialResolver(env),
+        audit: options.audit,
+    });
+    const startServer = options.startServer ?? startCodingProxyServer;
+    const server = await startServer(proxy, {
+        host: "0.0.0.0",
+        port: CODING_PROXY_PORT,
+        expectedHost: `${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
+        onRequest: options.onRequest,
+    });
+    let deny;
+    try {
+        deny = await (options.startDenyPort ?? startDenyPortListener)("0.0.0.0", CODING_PROXY_DENY_PORT);
+    }
+    catch (error) {
+        // A proxy without its witness must not stay up: the launcher's gate would never be able to
+        // prove a policy is enforced, and every launch would fail at the gate instead of at startup.
+        await server.close();
+        throw error;
+    }
+    return {
+        port: server.port,
+        close: async () => {
+            await deny.close();
+            await server.close();
+        },
+    };
+}

package/dist/providers/coding-proxy/secure-fetch.d.ts

@@ -0,0 +1,9 @@
+import { type Resolver } from "../../sandbox/fetch-policy.js";
+import { requestPinned } from "../../sandbox/safe-fetch.js";
+export declare const PROXY_EGRESS_ERROR = "proxy_egress_blocked";
+export interface PinnedProxyFetchOptions {
+    allowedHosts: string[];
+    resolve?: Resolver;
+    connect?: typeof requestPinned;
+}
+export declare function createPinnedProxyFetch(options: PinnedProxyFetchOptions): typeof globalThis.fetch;

package/dist/providers/coding-proxy/secure-fetch.js

@@ -0,0 +1,72 @@
+import { isIP } from "node:net";
+import { Readable } from "node:stream";
+import { FetchPolicyError, normalizeHost, resolveDestination } from "../../sandbox/fetch-policy.js";
+import { requestPinned } from "../../sandbox/safe-fetch.js";
+export const PROXY_EGRESS_ERROR = "proxy_egress_blocked";
+function blocked(cause) {
+    return new Error(PROXY_EGRESS_ERROR, { cause });
+}
+function responseHeaders(message) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(message.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                headers.append(name, item);
+        else
+            headers.set(name, value);
+    }
+    return headers;
+}
+export function createPinnedProxyFetch(options) {
+    const allowedHosts = options.allowedHosts.map(normalizeHost);
+    if (allowedHosts.length === 0 || allowedHosts.some((host) => isIP(host) !== 0))
+        throw blocked();
+    return async (input, init = {}) => {
+        try {
+            if (typeof input !== "string" && !(input instanceof URL))
+                throw blocked();
+            const url = input.toString();
+            const parsed = new URL(url);
+            if (parsed.protocol !== "https:" || isIP(normalizeHost(parsed.hostname)) !== 0)
+                throw blocked();
+            if (init.redirect && init.redirect !== "error")
+                throw blocked();
+            if (init.body !== undefined && init.body !== null && typeof init.body !== "string")
+                throw blocked();
+            const destination = await resolveDestination(url, {
+                allowedHosts,
+                allowPrivateHosts: false,
+                restrictToAllowedHosts: true,
+                resolve: options.resolve,
+            });
+            const signal = init.signal ?? new AbortController().signal;
+            const headers = Object.fromEntries(new Headers(init.headers).entries());
+            const message = await (options.connect ?? requestPinned)(destination, { method: init.method, headers, body: init.body }, signal);
+            const status = message.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                message.destroy();
+                throw blocked();
+            }
+            if (status < 100 || status > 599) {
+                message.destroy();
+                throw blocked();
+            }
+            const noBody = status === 204 || status === 205 || status === 304;
+            const body = noBody ? null : Readable.toWeb(message);
+            return new Response(body, {
+                status,
+                statusText: message.statusMessage,
+                headers: responseHeaders(message),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === PROXY_EGRESS_ERROR)
+                throw error;
+            if (error instanceof FetchPolicyError)
+                throw blocked(error);
+            throw error;
+        }
+    };
+}

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

@@ -0,0 +1,17 @@
+import { type CodingProxy } from "./proxy.js";
+import type { ProxyProtocol } from "./types.js";
+export interface CodingProxyServerConfig {
+    host: string;
+    port: number;
+    expectedHost?: string;
+    onRequest?: (event: {
+        protocol: ProxyProtocol | "other";
+        status: number;
+        durationMs: number;
+    }) => void;
+}
+export interface CodingProxyServerHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startCodingProxyServer(proxy: CodingProxy, config: CodingProxyServerConfig): Promise<CodingProxyServerHandle>;

package/dist/providers/coding-proxy/server.js

@@ -0,0 +1,139 @@
+import { createServer } from "node:http";
+import { HTTP_LIMITS, HttpBoundaryError, readBody } from "../../mcp/transport/http-limits.js";
+import { logger } from "../../core/logger.js";
+import { CodingProxyError, PROXY_MAX_BODY_BYTES } from "./proxy.js";
+const proxyLog = logger.child({ module: "coding-proxy" });
+function sendError(response, status, code) {
+    response
+        .writeHead(status, { "content-type": "application/json", "cache-control": "no-store" })
+        .end(JSON.stringify({ error: { type: code, message: code } }));
+}
+function bearer(value) {
+    if (!value?.startsWith("Bearer ") || value.indexOf(" ", 7) !== -1)
+        return "";
+    return value.slice(7);
+}
+function routeProtocol(method, url) {
+    if (method !== "POST")
+        return undefined;
+    if (url === "/v1/responses")
+        return "openai-responses";
+    if (url === "/v1/messages" || url === "/v1/messages?beta=true")
+        return "anthropic-messages";
+    return undefined;
+}
+function responseSink(response) {
+    return {
+        start(status, headers) {
+            if (!response.destroyed)
+                response.writeHead(status, headers);
+        },
+        write(chunk) {
+            if (response.destroyed)
+                return Promise.reject(new Error("client_disconnected"));
+            return new Promise((resolve, reject) => response.write(chunk, (error) => (error ? reject(error) : resolve())));
+        },
+        end() {
+            if (!response.destroyed)
+                response.end();
+        },
+        destroy() {
+            if (!response.destroyed)
+                response.destroy();
+        },
+    };
+}
+export async function startCodingProxyServer(proxy, config) {
+    const server = createServer({ maxHeaderSize: 16 * 1024, requireHostHeader: true }, (request, response) => {
+        const startedAt = performance.now();
+        const protocol = routeProtocol(request.method, request.url) ?? "other";
+        response.once("finish", () => {
+            try {
+                config.onRequest?.({ protocol, status: response.statusCode, durationMs: performance.now() - startedAt });
+            }
+            catch (error) {
+                proxyLog.warn({ event: "metrics.observe_failed", err: error }, "coding proxy metrics observer failed");
+            }
+        });
+        void (async () => {
+            if (config.expectedHost && request.headers.host !== config.expectedHost) {
+                sendError(response, 403, "invalid_host");
+                return;
+            }
+            if (request.method === "HEAD" && request.url === "/api/hello") {
+                response.writeHead(200, { "cache-control": "no-store" }).end();
+                return;
+            }
+            const protocol = routeProtocol(request.method, request.url);
+            if (!protocol) {
+                sendError(response, 404, "not_found");
+                return;
+            }
+            if (request.headers["content-type"]?.split(";", 1)[0].trim().toLowerCase() !== "application/json") {
+                sendError(response, 415, "unsupported_content_type");
+                return;
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), HTTP_LIMITS.requestMs);
+            let rawBody;
+            try {
+                rawBody = await readBody(request, PROXY_MAX_BODY_BYTES, controller.signal);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            // x-client-request-id is a tracing identifier that Codex may reuse across a multi-request tool loop.
+            const requestKeyHeader = request.headers["idempotency-key"];
+            const apiKeyHeader = request.headers["x-api-key"];
+            const anthropicBetaHeader = request.headers["anthropic-beta"];
+            const capability = protocol === "anthropic-messages"
+                ? request.headers.authorization === undefined && typeof apiKeyHeader === "string"
+                    ? apiKeyHeader
+                    : ""
+                : apiKeyHeader === undefined
+                    ? bearer(request.headers.authorization)
+                    : "";
+            await proxy.execute({
+                bearer: capability,
+                protocol,
+                rawBody,
+                requestKey: Array.isArray(requestKeyHeader) ? undefined : requestKeyHeader,
+                anthropicBeta: Array.isArray(anthropicBetaHeader) ? "" : anthropicBetaHeader,
+            }, responseSink(response));
+        })().catch((error) => {
+            if (response.headersSent) {
+                if (!response.destroyed)
+                    response.destroy();
+                return;
+            }
+            if (error instanceof CodingProxyError || error instanceof HttpBoundaryError) {
+                proxyLog.info({ event: "request.rejected", code: error instanceof CodingProxyError ? error.code : error.message }, "coding proxy request rejected");
+                sendError(response, error.status, error instanceof CodingProxyError ? error.code : error.message);
+                return;
+            }
+            // The client (an untrusted worker) still gets only "internal_error";
+            // the operator needs the reason. This log is control-plane side and the
+            // serializer redacts token-shaped values -- without it an upstream
+            // failure is indistinguishable from any other 500 (cost a live smoke
+            // several blind runs).
+            proxyLog.error({ event: "request.failed", err: error }, "coding proxy request failed");
+            sendError(response, 500, "internal_error");
+        });
+    });
+    server.requestTimeout = HTTP_LIMITS.requestMs;
+    server.headersTimeout = HTTP_LIMITS.headersMs;
+    server.keepAliveTimeout = 5_000;
+    server.maxRequestsPerSocket = 100;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(config.port, config.host, resolve);
+    });
+    const address = server.address();
+    return {
+        port: typeof address === "object" && address ? address.port : config.port,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+            server.closeIdleConnections();
+        }),
+    };
+}

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

@@ -0,0 +1,99 @@
+import type { ModelPricing } from "../llm/pricing.js";
+export type ProxySessionStatus = "active" | "cancelled";
+export type ProxyRequestStatus = "reserved" | "completed" | "released" | "uncertain";
+export type ProxyProtocol = "openai-responses" | "anthropic-messages";
+export interface PricingSnapshot extends ModelPricing {
+    version: string;
+}
+export interface ProxyUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+}
+export interface ProxySession {
+    id: string;
+    runId: string;
+    capabilityHash: string;
+    credentialRef: string;
+    protocol: ProxyProtocol;
+    allowedModels: string[];
+    deadlineAt: Date;
+    budgetUsd: number;
+    status: ProxySessionStatus;
+}
+export interface ProxyRequest {
+    id: string;
+    sessionId: string;
+    requestKey: string;
+    requestFingerprint: string;
+    model: string;
+    status: ProxyRequestStatus;
+    reservationUsd: number;
+    actualCostUsd?: number;
+    pricing: PricingSnapshot;
+    usage?: ProxyUsage;
+    upstreamStatus?: number;
+}
+export interface CreateProxySessionInput {
+    id: string;
+    runId: string;
+    capabilityHash: string;
+    credentialRef: string;
+    protocol: ProxyProtocol;
+    allowedModels: string[];
+    deadlineAt: Date;
+    budgetUsd: number;
+}
+export interface ReserveProxyRequestInput {
+    id: string;
+    sessionId: string;
+    requestKey: string;
+    requestFingerprint: string;
+    model: string;
+    reservationUsd: number;
+    pricing: PricingSnapshot;
+    now: Date;
+}
+export type ReserveProxyRequestResult = {
+    outcome: "reserved";
+    request: ProxyRequest;
+} | {
+    outcome: "duplicate";
+    request: ProxyRequest;
+} | {
+    outcome: "budget_exhausted";
+} | {
+    outcome: "inactive";
+    reason: "cancelled" | "expired";
+};
+export interface ProxyLedger {
+    createSession(input: CreateProxySessionInput): Promise<void>;
+    findSessionByCapabilityHash(capabilityHash: string): Promise<ProxySession | null>;
+    reserve(input: ReserveProxyRequestInput): Promise<ReserveProxyRequestResult>;
+    complete(requestId: string, usage: ProxyUsage, actualCostUsd: number, upstreamStatus: number): Promise<ProxyRequest>;
+    release(requestId: string, upstreamStatus: number): Promise<void>;
+    markUncertain(requestId: string, upstreamStatus?: number): Promise<void>;
+    cancelSession(sessionId: string): Promise<void>;
+    getRequest(requestId: string): Promise<ProxyRequest | null>;
+}
+export interface ProxyAuditEvent {
+    type: "session.created" | "session.cancelled" | "request.reserved" | "request.rejected" | "request.released" | "request.uncertain" | "response.completed";
+    runId: string;
+    requestId?: string;
+    model?: string;
+    status?: number;
+    reason?: string;
+    reservationUsd?: number;
+    costUsd?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+export type ProxyAuditSink = (event: ProxyAuditEvent) => void;
+export interface CredentialResolver {
+    resolve(reference: string): Promise<string>;
+}

package/dist/providers/coding-proxy/types.js

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

package/dist/providers/datastore/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./postgres.js";

package/dist/providers/datastore/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./postgres.js";

package/dist/providers/datastore/postgres.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Postgres-backed default Datastore adapter, via the `DatastoreEntry` table.
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { Datastore, DatastoreSetOptions, DatastoreValue } from "./types.js";
+import type { SecretCipher } from "../secrets/types.js";
+export type DatastoreDb = Pick<PrismaClient, "datastoreEntry" | "datastore" | "$queryRaw">;
+export declare class PostgresDatastore implements Datastore {
+    private readonly db;
+    private readonly cipher?;
+    constructor(db: DatastoreDb, cipher?: SecretCipher | undefined);
+    get(agentId: string, key: string): Promise<DatastoreValue | undefined>;
+    set(agentId: string, key: string, value: DatastoreValue, opts?: DatastoreSetOptions): Promise<void>;
+    delete(agentId: string, key: string): Promise<void>;
+    list(agentId: string, prefix?: string): Promise<string[]>;
+    getShared(datastoreId: string, key: string): Promise<DatastoreValue | undefined>;
+    setShared(datastoreId: string, key: string, value: DatastoreValue, opts?: DatastoreSetOptions): Promise<void>;
+    deleteShared(datastoreId: string, key: string): Promise<void>;
+    listShared(datastoreId: string, prefix?: string): Promise<string[]>;
+}

package/dist/providers/datastore/postgres.js

@@ -0,0 +1,130 @@
+/**
+ * Postgres-backed default Datastore adapter, via the `DatastoreEntry` table.
+ */
+import { boundedJson, boundedString } from "../../sandbox/bounded-json.js";
+import { BRIDGE_INPUT_BYTES } from "../../sandbox/limits.js";
+/**
+ * A `pii: true` value is stored as a base64url cipher blob, which runs
+ * ~33% larger than its plaintext plus a small fixed iv/tag overhead. Capping
+ * the plaintext here (rather than at BRIDGE_INPUT_BYTES) guarantees the
+ * encrypted blob still clears the read-side BRIDGE_INPUT_BYTES guard below —
+ * a plaintext allowed right up to that guard would otherwise encrypt into an
+ * unreadable row.
+ */
+const PII_PLAINTEXT_BYTES = 750_000;
+export class PostgresDatastore {
+    db;
+    cipher;
+    constructor(db, cipher) {
+        this.db = db;
+        this.cipher = cipher;
+    }
+    async get(agentId, key) {
+        boundedString(key, 1024);
+        const rows = await this.db.$queryRaw `
+      SELECT CASE WHEN octet_length("value"::text) <= ${BRIDGE_INPUT_BYTES} THEN "value" ELSE NULL END AS "value",
+             octet_length("value"::text) > ${BRIDGE_INPUT_BYTES} AS "oversized",
+             "pii" AS "pii"
+      FROM "DatastoreEntry" WHERE "agentId" = ${agentId} AND "key" = ${key}`;
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        if (row.oversized)
+            throw new Error("datastore_value_limit");
+        if (!row.pii)
+            return row.value;
+        if (!this.cipher)
+            throw new Error("datastore_pii_cipher_unavailable");
+        const plaintext = await this.cipher.decrypt(row.value);
+        return JSON.parse(plaintext);
+    }
+    async set(agentId, key, value, opts) {
+        boundedString(key, 1024);
+        if (!opts?.pii) {
+            boundedJson(value, BRIDGE_INPUT_BYTES);
+            await this.db.datastoreEntry.upsert({
+                where: { agentId_key: { agentId, key } },
+                create: { agentId, key, value: value, pii: false, keyId: null },
+                update: { value: value, pii: false, keyId: null },
+            });
+            return;
+        }
+        if (!this.cipher)
+            throw new Error("datastore_pii_cipher_unavailable");
+        const plaintext = boundedJson(value, PII_PLAINTEXT_BYTES);
+        const ciphertext = await this.cipher.encrypt(plaintext);
+        const keyId = this.cipher.keyId();
+        await this.db.datastoreEntry.upsert({
+            where: { agentId_key: { agentId, key } },
+            create: { agentId, key, value: ciphertext, pii: true, keyId },
+            update: { value: ciphertext, pii: true, keyId },
+        });
+    }
+    async delete(agentId, key) {
+        await this.db.datastoreEntry.deleteMany({ where: { agentId, key } });
+    }
+    async list(agentId, prefix) {
+        boundedString(prefix ?? "", 1024);
+        const entries = await this.db.$queryRaw `
+      SELECT CASE WHEN octet_length("key") <= 1024 THEN "key" ELSE NULL END AS "key"
+      FROM "DatastoreEntry" WHERE "agentId" = ${agentId} AND starts_with("key", ${prefix ?? ""})
+      ORDER BY "key" LIMIT 1001`;
+        if (entries.length > 1000 || entries.some((e) => e.key === null))
+            throw new Error("datastore_list_limit");
+        return entries.map((e) => e.key);
+    }
+    async getShared(datastoreId, key) {
+        boundedString(key, 1024);
+        const rows = await this.db.$queryRaw `
+      SELECT CASE WHEN octet_length("value"::text) <= ${BRIDGE_INPUT_BYTES} THEN "value" ELSE NULL END AS "value",
+             octet_length("value"::text) > ${BRIDGE_INPUT_BYTES} AS "oversized",
+             "pii" AS "pii"
+      FROM "DatastoreEntry" WHERE "datastoreId" = ${datastoreId} AND "key" = ${key}`;
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        if (row.oversized)
+            throw new Error("datastore_value_limit");
+        if (!row.pii)
+            return row.value;
+        if (!this.cipher)
+            throw new Error("datastore_pii_cipher_unavailable");
+        const plaintext = await this.cipher.decrypt(row.value);
+        return JSON.parse(plaintext);
+    }
+    async setShared(datastoreId, key, value, opts) {
+        boundedString(key, 1024);
+        if (!opts?.pii) {
+            boundedJson(value, BRIDGE_INPUT_BYTES);
+            await this.db.datastoreEntry.upsert({
+                where: { datastoreId_key: { datastoreId, key } },
+                create: { datastoreId, key, value: value, pii: false, keyId: null },
+                update: { value: value, pii: false, keyId: null },
+            });
+            return;
+        }
+        if (!this.cipher)
+            throw new Error("datastore_pii_cipher_unavailable");
+        const plaintext = boundedJson(value, PII_PLAINTEXT_BYTES);
+        const ciphertext = await this.cipher.encrypt(plaintext);
+        const keyId = this.cipher.keyId();
+        await this.db.datastoreEntry.upsert({
+            where: { datastoreId_key: { datastoreId, key } },
+            create: { datastoreId, key, value: ciphertext, pii: true, keyId },
+            update: { value: ciphertext, pii: true, keyId },
+        });
+    }
+    async deleteShared(datastoreId, key) {
+        await this.db.datastoreEntry.deleteMany({ where: { datastoreId, key } });
+    }
+    async listShared(datastoreId, prefix) {
+        boundedString(prefix ?? "", 1024);
+        const entries = await this.db.$queryRaw `
+      SELECT CASE WHEN octet_length("key") <= 1024 THEN "key" ELSE NULL END AS "key"
+      FROM "DatastoreEntry" WHERE "datastoreId" = ${datastoreId} AND starts_with("key", ${prefix ?? ""})
+      ORDER BY "key" LIMIT 1001`;
+        if (entries.length > 1000 || entries.some((e) => e.key === null))
+            throw new Error("datastore_list_limit");
+        return entries.map((e) => e.key);
+    }
+}

package/dist/providers/datastore/scoped.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wraps a `Datastore` so every operation is confined to keys under one of
+ * the tool attachment's declared prefixes (OWASP LLM08 — Excessive Agency
+ * fix). Reads/lists on a disallowed key behave like the key doesn't exist
+ * (consistent with a plain cache-miss); a write outside every allowed
+ * prefix throws loudly instead — a tool author needs to know their write
+ * was rejected, not silently believe it landed.
+ */
+import type { Datastore } from "./types.js";
+export declare function scopeDatastore(datastore: Datastore, allowedPrefixes: readonly string[]): Datastore;

package/dist/providers/datastore/scoped.js

@@ -0,0 +1,46 @@
+function isAllowed(key, allowedPrefixes) {
+    return allowedPrefixes.some((prefix) => key.startsWith(prefix));
+}
+export function scopeDatastore(datastore, allowedPrefixes) {
+    return {
+        async get(agentId, key) {
+            if (!isAllowed(key, allowedPrefixes))
+                return undefined;
+            return datastore.get(agentId, key);
+        },
+        async set(agentId, key, value, opts) {
+            if (!isAllowed(key, allowedPrefixes))
+                throw new Error("datastore_prefix_not_allowed");
+            await datastore.set(agentId, key, value, opts);
+        },
+        async delete(agentId, key) {
+            if (!isAllowed(key, allowedPrefixes))
+                return;
+            await datastore.delete(agentId, key);
+        },
+        async list(agentId, prefix) {
+            const keys = await datastore.list(agentId, prefix);
+            return keys.filter((key) => isAllowed(key, allowedPrefixes));
+        },
+        // Shared-store access has its own dedicated scoping (scopeSharedDatastoreAccessor,
+        // src/core/datastores.ts) applied separately to the unscoped provider — these four
+        // methods are unreachable through a scopeDatastore(...)-wrapped object in this
+        // codebase's call graph. This wrapper is the security boundary for the
+        // private per-agent store, though, so rather than quietly pass an
+        // unreachable-today call straight through to the unscoped datastore (a
+        // hole waiting to happen if that ever changes), every shared-store
+        // method throws — same fail-closed posture as an unscoped write above.
+        async getShared() {
+            throw new Error("datastore_shared_access_not_allowed");
+        },
+        async setShared() {
+            throw new Error("datastore_shared_access_not_allowed");
+        },
+        async deleteShared() {
+            throw new Error("datastore_shared_access_not_allowed");
+        },
+        async listShared() {
+            throw new Error("datastore_shared_access_not_allowed");
+        },
+    };
+}

package/dist/providers/datastore/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Datastore seam — key/value state scoped per agent, exposed to sandboxed
+ * tools as `datastore.*`. The one new seam Phase 3 introduces (Medium host
+ * API surface); a cloud KV can swap in later via the same provider-config
+ * pattern as the other seams.
+ */
+export type DatastoreValue = null | boolean | number | string | DatastoreValue[] | {
+    [key: string]: DatastoreValue;
+};
+export interface DatastoreSetOptions {
+    /**
+     * Opt-in, never inferred: encrypts the value at rest (AES-256-GCM, same
+     * cipher as Secret) instead of storing it as plain JSON. Costs an
+     * encrypt/decrypt round trip on every set/get of that key, so reserve it
+     * for values that actually carry PII.
+     */
+    pii?: boolean;
+}
+export interface Datastore {
+    get(agentId: string, key: string): Promise<DatastoreValue | undefined>;
+    set(agentId: string, key: string, value: DatastoreValue, opts?: DatastoreSetOptions): Promise<void>;
+    delete(agentId: string, key: string): Promise<void>;
+    /** Lists keys (not values) under an optional prefix, scoped to the agent. */
+    list(agentId: string, prefix?: string): Promise<string[]>;
+    /** Sibling methods for a named shared store (see Datastore/AgentDatastore
+     *  in schema.prisma), keyed by datastoreId instead of agentId. */
+    getShared(datastoreId: string, key: string): Promise<DatastoreValue | undefined>;
+    setShared(datastoreId: string, key: string, value: DatastoreValue, opts?: DatastoreSetOptions): Promise<void>;
+    deleteShared(datastoreId: string, key: string): Promise<void>;
+    listShared(datastoreId: string, prefix?: string): Promise<string[]>;
+}

package/dist/providers/datastore/types.js

@@ -0,0 +1,7 @@
+/**
+ * Datastore seam — key/value state scoped per agent, exposed to sandboxed
+ * tools as `datastore.*`. The one new seam Phase 3 introduces (Medium host
+ * API surface); a cloud KV can swap in later via the same provider-config
+ * pattern as the other seams.
+ */
+export {};