/** * The estate relay (wicked-core#1018): a governed worker's estate calls, through the broker. * * # Why * * A seat on the container floor has no estate. The host's stores (`memory.db`, the knowledge * store, the run's code graph) are SQLite files that must not be mounted into the seat's Linux VM * (WAL `-shm` across the Docker Desktop file share, with the daemon writing the same file from the * host, is a corruption risk), the seat image ships no `wicked-estate-mcp`, and the container * passes only the variables the carrier set, so no store pin reaches it. Garden's estate shim * therefore failed closed in every container seat: no blast radius, hotspots or recall, and no * capture proposal (run b445). * * The seat already has one way out: the broker, `POST /api/v1/mcp/call {token, subject, args}`, * reached through its gateway with a token bound to its unit. So the shim sends its estate calls * there as the reserved subject `mcp:estate/`, and this module answers them on the host. * * # What it allows, and how it is scoped * * - **Who**: the unit the token is bound to, resolved by the engine (`Core.resolveEstateScope`), * never anything the worker sends. An unknown or dead token is `invalid_token` (401). * - **What**: the read-only lookups garden's skills use ({@link ESTATE_READ_TOOLS}) and * `proposal.submit`, which lands an INERT proposal: nothing is recalled or applied until a human * approves it on the review queue. Every other estate tool is refused. The server is spawned * `--readonly`, so even a tool missing from this list could not write. * - **Which store**: graph lookups open the run's own code graph (the one the engine vouched for * and hands a host seat as `WICKED_ESTATE_DB`), and are refused when the run has none; memory, * knowledge and proposals use this daemon's stores, as its own memory surface does. * - **Which project**: a recall's facet intent and a proposal's facets are set to the run's * project and repo (and a project or repo the run does not have is removed), so a worker * neither reads another project's faceted memories nor files a proposal under one. Provenance * (`run_id`, `run_unit`, `run_agent`) is stamped by the server from the unit, never from args. * - **How much**: numeric size arguments are clamped ({@link ARG_CAPS}), each call has a deadline * ({@link ESTATE_RELAY_TIMEOUT_MS}), at most {@link ESTATE_RELAY_CONCURRENCY} run at once, and * a result over {@link ESTATE_RELAY_MAX_RESULT_BYTES} is withheld with a remedy. The broker's * per-unit call budget covers relayed calls too. * * Every relayed call is recorded like any brokered call (`calls.ndjson`, `/ws`, the bus), and a * landed proposal is also written to the audit trail against its run. */ import { type EstateMcpIo } from '../core/estate-mcp-client.js'; export { ESTATE_SERVER } from './classify.js'; /** The graph lookups a seat may make (read-only; each reads the run's code graph). */ export declare const ESTATE_GRAPH_TOOLS: ReadonlySet; /** Every read-only tool the relay answers: the graph lookups plus memory and knowledge recall. */ export declare const ESTATE_READ_TOOLS: ReadonlySet; /** The one write: an inert proposal for human review. */ export declare const ESTATE_PROPOSAL_TOOL = "proposal.submit"; export declare const ESTATE_RELAY_TIMEOUT_MS = 30000; export declare const ESTATE_RELAY_CONCURRENCY = 4; export declare const ESTATE_RELAY_MAX_RESULT_BYTES: number; /** The upper bound for each numeric size argument a worker may pass; a larger value is lowered. */ export declare const ARG_CAPS: Readonly>; /** What the engine resolved a token to (`Core.resolveEstateScope`). */ export interface EstateUnitScope { unit: { runId: string; ord: number; attempt: number; phase: string; seat: string; }; projectId: string | null; repoId: string | null; codeGraphDb: string | null; } /** One relayed call as the estate server answered it: its MCP envelope, or its JSON-RPC error. */ export type EstateRelayAnswer = { result: Record; } | { rpcError: { code: number | null; message: string; }; }; export interface EstateRelayInvocation { tool: string; args: Record; scope: EstateUnitScope; timeoutMs: number; } /** Runs one call against the estate server. Throws on a transport fault or the deadline. */ export type EstateInvoker = (call: EstateRelayInvocation) => Promise; /** Why a call is refused before it reaches estate. */ export interface EstateRefusal { ruleId: string; reason: string; remedy: string; } export declare function isEstateTool(tool: string): boolean; /** Refuse a call the relay never makes, or one the run's scope cannot answer; `null` = relay it. */ export declare function estateRefusal(tool: string, scope: EstateUnitScope, memoryDb: string, exists?: (p: string) => boolean): EstateRefusal | null; /** * The arguments estate is actually sent: capped, and scoped to the run (module doc). A worker's own * `provenance` is dropped: the server stamps it from the unit. * * A proposal for a run with no project keeps the worker's own `facets.project` (garden requires * one), since there is no run project to set; only `repo` is then the run's. */ export declare function scopeEstateArgs(tool: string, args: Record, scope: EstateUnitScope): Record; /** * The estate server's environment for one relayed call (module doc: which store, whose provenance), * built on `base`, the daemon's env as every crew child gets it (`childEnvWithBootEstateDb`). */ export declare function estateRelayEnv(scope: EstateUnitScope, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv; /** A counting gate: at most `max` callers hold it at once; the rest wait in order. */ export declare class Semaphore { private readonly max; private active; private readonly waiters; constructor(max: number); run(fn: () => Promise): Promise; } /** The real invocation: a spawn-per-call `wicked-estate-mcp --readonly` with {@link estateRelayEnv}. */ export declare function defaultEstateInvoker(io?: Pick): EstateInvoker; /** A landed proposal, for the audit trail (run, unit, the queue id, never the payload). */ export interface EstateProposalLanded { runId: string; ord: number; attempt: number; seat: string; proposalId: string; kindType: string; callId: string; } export interface EstateRelayDeps { /** `Core.resolveEstateScope`, read per call; `null` = the linked engine predates it. */ resolver: () => ((requestJson: string) => Promise) | null; invoke?: EstateInvoker; /** The daemon's memory store path (proposals land there). Default {@link resolveMemoryDbPath}. */ memoryDb?: () => string; exists?: (path: string) => boolean; timeoutMs?: number; concurrency?: number; maxResultBytes?: number; /** Called once per landed proposal. Never throws into the call. */ onProposal?: (landed: EstateProposalLanded) => void; } /** The relay's resolved dependencies, as the broker drives them. */ export declare class EstateRelay { private readonly deps; readonly invoke: EstateInvoker; readonly timeoutMs: number; readonly maxResultBytes: number; private readonly gate; constructor(deps: EstateRelayDeps); /** The token's unit and scope. Throws the engine's `invalid_token:` / `bad_request:` / other errors. */ resolve(token: string): Promise; refusal(tool: string, scope: EstateUnitScope): EstateRefusal | null; run(call: EstateRelayInvocation): Promise; landed(landed: EstateProposalLanded): void; } /** The MCP envelope a relayed JSON-RPC error is handed back as: a tool error carrying its code. */ export declare function rpcErrorEnvelope(error: { code: number | null; message: string; }): Record; /** The proposal id in a `proposal.submit` envelope (`content[0].text` is `{"id": …}`), or `null`. */ export declare function proposalIdOf(result: Record): string | null; //# sourceMappingURL=estate-relay.d.ts.map