@synadia-ai/agent-fabric 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1529 @@
+import { RequestInterceptor, AgentServiceExtraEndpoint, AgentService } from '@synadia-ai/agent-service';
+import { AgentId, PromptInterceptor, Agents, Logger, AgentToolsExtension, SenderInfo, Agent, AgentToolsPromptContext, AgentToolsPromptRewrite, AgentToolsReplyContext, NatsConnectionSource } from '@synadia-ai/agents';
+import { NatsConnection } from '@nats-io/nats-core';
+
+declare const EDGE_RECORD_VERSION = 1;
+/** Default subject edge records are published to — the tenant-side short
+ * form; the account's import qualifies it to `TRACE.{account}.edges`. */
+declare const DEFAULT_EDGE_SUBJECT = "TRACE.edges";
+/** The envelope fields that carry the lineage to the receiver. */
+declare const THREAD_ID_FIELD = "thread_id";
+declare const ROOT_ID_FIELD = "root_id";
+/** The headers an agent stamps on its model requests (see {@link traceHeaders}). */
+declare const THREAD_ID_HEADER = "X-Synadia-Thread-ID";
+declare const ROOT_ID_HEADER = "X-Synadia-Root-ID";
+/**
+ * Tracing configuration for {@link fabricTracing}; `{}` takes every
+ * default.
+ */
+interface TraceOptions {
+    /**
+     * Where edge records are published. `null` selects propagate-only mode
+     * — mint IDs and forward lineage, but publish no edge records.
+     */
+    readonly edgeSubject?: string | null;
+}
+/**
+ * Throws {@link NatsAgentError} when `options.edgeSubject` names a subject
+ * that can never be published to: empty, an empty token, whitespace or
+ * NUL, or a wildcard. Publishing is fail-open, so without this check a
+ * misconfigured subject would only ever show up as a warning on every
+ * prompt; checking where the options are accepted makes it fail at
+ * construction instead.
+ */
+declare function assertValidTraceOptions(options: TraceOptions | undefined): void;
+/**
+ * How many trace records this process has published and dropped so far —
+ * `edge` records today, counted from process start. Process-wide, not per
+ * client: the records are written by whichever client a prompt handler
+ * happens to use, while the agent service that owns the heartbeat is
+ * another object; one counter for the process is the one they share. The
+ * host reports both numbers as `records_published` and `records_dropped`
+ * in its heartbeat's extras (`fabricTracing().heartbeatExtras`), so
+ * whoever consumes the heartbeat knows how many records this process
+ * failed to publish.
+ */
+interface TraceRecordCounts {
+    /**
+     * Records handed to the connection for publishing. Handed, not
+     * delivered: a record lost after that — a reconnect buffer that
+     * overflowed, a process that exited before the flush — is not seen
+     * here. The counts cover what this process could observe; nothing past
+     * the connection is visible to them.
+     */
+    readonly published: number;
+    /**
+     * Records that were due but never went out: no identity to sign them
+     * with, or a publish that threw. "Due" means the prompt the record
+     * describes actually went out — a prompt never iterated or rejected by
+     * validation owes no record and counts nothing. A record in
+     * propagate-only mode (`edgeSubject: null`) is never due either.
+     */
+    readonly dropped: number;
+}
+/** Count one trace record published. Called by the edge publisher. */
+declare function countTraceRecordPublished(): void;
+/** Count one trace record dropped. Called by the edge publisher. */
+declare function countTraceRecordDropped(): void;
+/** A snapshot of the process-wide {@link TraceRecordCounts}. */
+declare function traceRecordCounts(): TraceRecordCounts;
+/** Identity of the prompt execution running in the current async context. */
+interface TraceScope {
+    /** This execution's own thread ID — the parent of any thread it spawns. */
+    readonly threadId: string;
+    /** The tree's root thread ID, inherited unchanged; equals `threadId` on a root. */
+    readonly rootId: string;
+    /**
+     * Where in this execution any thread it spawns next was sent out: how
+     * many times it has stamped trace headers on a model request so far.
+     * Deliberately mutable and shared — work spawned inside the handler
+     * holds the same scope object, so its turns count against this
+     * execution.
+     */
+    turnCountHint: number;
+}
+/**
+ * Run `fn` with `scope` as the ambient execution (what the host
+ * interceptor does around a prompt handler). AsyncLocalStorage restores
+ * the previous binding on exit, so nothing leaks into the next request.
+ */
+declare function bindActiveTrace<T>(scope: TraceScope, fn: () => T): T;
+/** The ambient {@link TraceScope}, or `undefined` outside a bound handler. */
+declare function activeTrace(): TraceScope | undefined;
+/**
+ * Headers for every model request this execution issues.
+ *
+ * An agent stamps these on each completion request so the model proxy
+ * files the call under the right thread and tree without seeing any NATS
+ * traffic. Hierarchy is the edge records' job, so the proxy needs no
+ * parent or tool-call header.
+ *
+ * `{}` outside a traced handler, so harness code needs no plumbing and
+ * degrades to nothing.
+ *
+ * Each call counts against this execution: the running total is recorded
+ * on the edge of any thread it spawns afterwards.
+ */
+declare function traceHeaders(): Record<string, string>;
+/** Length in hex characters of a thread ID — 128 bits. */
+declare const THREAD_ID_HEX_LEN = 32;
+/**
+ * `true` iff `value` has the shape of a thread ID: exactly
+ * {@link THREAD_ID_HEX_LEN} lowercase hex characters. Ids arriving on the
+ * wire are untrusted input that ends up in the headers an agent stamps on
+ * its model requests, so a receiver adopts nothing that is not shaped
+ * exactly like what the packages mint.
+ */
+declare function isThreadId(value: string): boolean;
+declare function randomThreadId(): string;
+/** Longest accepted tool call id, in Unicode code points. */
+declare const TOOL_CALL_ID_MAX = 256;
+declare function validToolCallId(toolCallId: string): boolean;
+/** One built edge record: its wire bytes and the id that de-duplicates it. */
+interface BuiltEdgeRecord {
+    readonly recordId: string;
+    readonly payload: Uint8Array;
+}
+/**
+ * One edge record, ready to publish. The record id comes back alongside
+ * the payload: the publisher signs with it as the `Agent-Sender` nonce,
+ * which the SDK's signed publish also stamps as `Nats-Msg-Id`, so body,
+ * header and message id carry one id and a stream de-duplicates a record
+ * it already stored. Its 32 hex characters fit the nonce's
+ * `[A-Za-z0-9_-]{1,64}`.
+ *
+ * `agent` is the writer — the caller that spawned the thread, the parent
+ * side of the edge — in canonical `{account}.{user}` form. It is the same
+ * identity that signs the record's `Agent-Sender` header, so a consumer
+ * can cross-check the body against the verified header.
+ */
+declare function buildEdgeRecord(agent: AgentId, threadId: string, parentId: string | null, rootId: string, toolCallId: string | null, turnCountHint: number): BuiltEdgeRecord;
+
+/** The key of `PromptOptions.context` the caller interceptor reads the tool call ID from. */
+declare const TOOL_CALL_ID_CONTEXT_KEY = "toolCallId";
+/** What {@link fabricTracing} returns: the SDK's three hooks, ready to pass in. */
+interface FabricTracing {
+    /** For the caller: `new Agents({ ..., interceptors: [tracing.promptInterceptor] })`. */
+    readonly promptInterceptor: PromptInterceptor;
+    /** For the host: `new AgentService({ ..., interceptors: [tracing.requestInterceptor] })`. */
+    readonly requestInterceptor: RequestInterceptor;
+    /**
+     * For the host: `new AgentService({ ..., heartbeatExtras: tracing.heartbeatExtras })`.
+     * `records_published` and `records_dropped` — the process-wide
+     * {@link traceRecordCounts} — read fresh for every heartbeat and status
+     * reply. `{}` in propagate-only mode, which publishes no records and
+     * would otherwise report a constant 0/0 that looks like a healthy zero.
+     */
+    readonly heartbeatExtras: () => Readonly<Record<string, unknown>>;
+}
+/**
+ * Tracing for an agent on the fabric, as the protocol SDK's hooks.
+ *
+ * Throws `NatsAgentError` for an `edgeSubject` that can never be published
+ * to (see {@link assertValidTraceOptions}). `options.edgeSubject` defaults
+ * to {@link DEFAULT_EDGE_SUBJECT}; `null` is propagate-only mode.
+ */
+declare function fabricTracing(options?: TraceOptions): FabricTracing;
+
+/**
+ * The served prompt's trace as a run's input carries it, in this key
+ * order. Wire form: the same keys and order in both packages.
+ */
+interface DurableTrace {
+    readonly thread_id: string;
+    readonly root_id: string;
+}
+/**
+ * The run id that joins a durable run to the task that started it:
+ * `<thread_id>-<tool call id>`, the active trace's thread and the model's
+ * tool-call id, with every character of the tool-call id outside
+ * `[A-Za-z0-9_-]` replaced by `_`. Pass it as the run id when the run is
+ * started; the run's children and generations keep it as their prefix.
+ *
+ * `undefined` outside a traced prompt handler: there is no served thread to
+ * name. Pick a run id of your own then; that run joins no task.
+ *
+ * Throws {@link NatsAgentError} when the tool-call id is empty, longer than
+ * the trace accepts (`TOOL_CALL_ID_MAX` code points) or not valid Unicode.
+ */
+declare function durableRunId(toolCallId: string): string | undefined;
+/**
+ * The active trace as `{ thread_id, root_id }`, for the run's input under a
+ * key of your choosing; {@link durableHeaders} turns it back into the
+ * proxy's headers inside a step. `undefined` outside a traced prompt
+ * handler.
+ *
+ * Unlike `traceHeaders()`, it counts no model turn: it starts no model call.
+ */
+declare function durableTrace(): DurableTrace | undefined;
+/**
+ * The two headers the model proxy reads, `X-Synadia-Thread-ID` and
+ * `X-Synadia-Root-ID`, from a trace a run's input carries, for a model call
+ * inside a step. The call then lands on the thread that started the run.
+ *
+ * The input is read back from the run's journal, so it is checked as
+ * untrusted: `{}` unless both ids have the shape of a thread id. `{}` for
+ * `undefined` or `null` as well, so a run started outside a traced handler
+ * makes its model calls without the headers.
+ */
+declare function durableHeaders(trace: DurableTrace | null | undefined): Record<string, string>;
+/**
+ * Run `fn` inside the trace a run's input carries, as the prompt's handler
+ * ran inside it: a prompt sent to another agent from `fn` writes its edge
+ * under the thread that started the run, in the same tree, and
+ * `traceHeaders()` inside `fn` gives the same two headers as
+ * {@link durableHeaders}. For a step of a durable run, which a worker runs
+ * outside the prompt's async scope.
+ *
+ * `turnCount` is how many model calls the run has made so far; it becomes
+ * the turn count hint of any edge `fn` writes. A `traceHeaders()` call
+ * inside `fn` counts one more, as it does in a handler.
+ *
+ * A trace that is missing or not shaped like thread ids binds nothing: `fn`
+ * runs as it would outside a traced handler. Throws {@link NatsAgentError}
+ * when `turnCount` is not a whole number, 0 or more.
+ */
+declare function withDurableTrace<T>(trace: DurableTrace | null | undefined, turnCount: number, fn: () => T): T;
+
+declare const SERVED_RECORD_VERSION = 1;
+/**
+ * The version of a record that carries a `reason`: the schema's version 2
+ * added the field. A record without one stays version 1, byte for byte what
+ * it was.
+ */
+declare const SERVED_RECORD_REASON_VERSION = 2;
+/**
+ * The harnesses whose plugins write `served` records: the ones that cannot
+ * put the fabric's headers on their own model calls. PI can, and writes
+ * none. The value is what the proxy files the harness's calls under
+ * (the fabric's design, §8.1).
+ */
+type Harness = "claude" | "openclaw";
+/** `start` when the prompt arrives, `end` when the turn is over. */
+type ServedPhase = "start" | "end";
+/** How the turn ended: answered, failed, or expired on the request's TTL. */
+type ServedStatus = "ok" | "error" | "timeout";
+/**
+ * How a prompt ended when the model did not end it with its own reply, on
+ * `end` only; absent when the model replied. `final_text`: the plugin sent
+ * the turn's final text as the reply (status `ok`); `no_reply`: the turn
+ * ended with no reply and no final text; `shutdown`: the plugin stopped
+ * with the prompt open; `delivery`: the prompt could not be handed to the
+ * harness; `expired`: the prompt outlived the plugin's limit (status
+ * `timeout`).
+ */
+type ServedReason = "final_text" | "no_reply" | "shutdown" | "delivery" | "expired";
+/** Longest accepted harness thread id, in Unicode code points. */
+declare const HARNESS_THREAD_ID_MAX = 256;
+/**
+ * `true` iff `value` can be the harness thread id a served record names:
+ * a non-empty string of at most {@link HARNESS_THREAD_ID_MAX} code points
+ * — counted as the Python package's `len()` counts, not in UTF-16 units —
+ * with no whitespace or control character (the class the SDK holds a
+ * subject token to: the id is matched against a header value the proxy
+ * saw, and a header value can never hold those) and no lone surrogate,
+ * which has no UTF-8 form. Claude Code's session id and OpenClaw's 32-hex
+ * trace id pass; the packages accept exactly the same ids.
+ */
+declare function validHarnessThreadId(value: unknown): value is string;
+/** Now, in unix seconds — the served record's `ts` resolution. */
+declare function unixSeconds(): number;
+/** One built served record: its wire bytes and the id that de-duplicates it. */
+interface BuiltServedRecord {
+    readonly recordId: string;
+    readonly payload: Uint8Array;
+}
+/**
+ * One served record, ready to publish. The record id comes back alongside
+ * the payload: the publisher signs with it as the `Agent-Sender` nonce,
+ * which the SDK's signed publish also stamps as `Nats-Msg-Id`, so body,
+ * header and message id carry one id and a stream de-duplicates a record
+ * it already stored. Its 32 hex characters fit the nonce's
+ * `[A-Za-z0-9_-]{1,64}`.
+ *
+ * `agent` is the plugin's own identity, the executing agent, in canonical
+ * `{account}.{user}` form — the same identity that signs the record.
+ * `threadId` and `rootId` are the served prompt's, from its scope.
+ * `harnessThreadId` is the harness's own id, bare — never prefixed — and
+ * must pass {@link validHarnessThreadId}. `status` is required on `end`
+ * and must be absent on `start`. `ts` is unix seconds: when the prompt
+ * arrived for `start`, when the turn ended for `end`; now by default.
+ * `reason` ({@link ServedReason}) says how an `end` came about when the
+ * model did not reply itself; it is refused on `start`, like `status`, and
+ * a record that carries it is version {@link SERVED_RECORD_REASON_VERSION}.
+ *
+ * Throws `Error` for a record the contract would refuse, so a plugin's
+ * mistake is its own and never a malformed record on the wire.
+ */
+declare function buildServedRecord(agent: AgentId, threadId: string, rootId: string, harness: Harness, harnessThreadId: string, phase: ServedPhase, status?: ServedStatus, ts?: number, reason?: ServedReason): BuiltServedRecord;
+interface ServedPublisherOptions {
+    /**
+     * The plugin's own client: it signs every record as its identity, which
+     * is also the record's `agent`. Without a signer nothing is published —
+     * an unsigned record cannot be attributed — the publisher warns once and
+     * each record owed counts as dropped.
+     */
+    readonly agents: Agents;
+    /**
+     * Where the records go: the edge subject, the same the plugin's tracing
+     * runs with. {@link DEFAULT_EDGE_SUBJECT} by default.
+     */
+    readonly subject?: string;
+    /** Where a refused binding or a failed publish is reported; the console by default. */
+    readonly logger?: Logger;
+}
+/**
+ * One prompt's served pair. `bind` names the harness thread id once and
+ * publishes `start`, stamped with the prompt's arrival — the moment
+ * {@link ServedPublisher.beginTurn} was called — however late the id
+ * becomes known; `settle` records the outcome when the turn ends and
+ * publishes `end` if the id is known. An id bound after settling is
+ * refused: the pair is the turn's window, not something to backfill. Both
+ * are synchronous and return at once; the records go out behind them.
+ */
+interface ServedTurn {
+    /**
+     * The harness's own id for this prompt's turn, bare. An unusable id
+     * (see {@link validHarnessThreadId}) is refused with a warning and the
+     * prompt gets no pair; a second binding is ignored, with a warning when
+     * it names another id.
+     */
+    bind(harnessThreadId: string): void;
+    /**
+     * End the turn. `atMs` is the turn's end in milliseconds since the epoch,
+     * as the plugin's events report it; now by default. `reason` is how the
+     * prompt ended when the model did not reply itself ({@link ServedReason}),
+     * carried on `end`. A second call does nothing.
+     */
+    settle(status: ServedStatus, atMs?: number, reason?: ServedReason): void;
+}
+/**
+ * Publishes served records through the plugin's client, one after another
+ * in the order they were due, so a pair's `end` never overtakes its
+ * `start` on the wire and two prompts' pairs interleave as they happened.
+ * See {@link servedPublisher}.
+ */
+declare class ServedPublisher {
+    #private;
+    constructor(options: ServedPublisherOptions);
+    /** Where the records go. */
+    get subject(): string;
+    /**
+     * Start a prompt's pair: `scope` is the served prompt's trace scope —
+     * the one the fabric's request interceptor bound around the handler,
+     * `activeTrace()` inside it — and `harness` the one whose id `bind` will
+     * name. The arrival, `start`'s `ts`, is now.
+     */
+    beginTurn(scope: TraceScope, harness: Harness): ServedTurn;
+    /**
+     * Publish one signed record, after every record handed over before it.
+     * Fail-open and asynchronous: the returned promise never rejects and
+     * nothing awaits it on the prompt path. A record that cannot go out — no
+     * signer, a client already closed, a publish that threw — is logged and
+     * counts as dropped; one that went out counts as published. Every record
+     * moves the process-wide {@link traceRecordCounts}.
+     */
+    publish(scope: TraceScope, harness: Harness, harnessThreadId: string, phase: ServedPhase, status: ServedStatus | undefined, ts: number, reason?: ServedReason): Promise<void>;
+    /**
+     * Resolves once every record handed to `publish` so far has been signed
+     * and handed to the connection, or dropped. For shutdown and tests.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * The served records' publisher for a harness plugin's add-on, over the
+ * plugin's own client: `agents.publishSigned` with the record id as nonce,
+ * on `subject` ({@link DEFAULT_EDGE_SUBJECT} by default), the records in
+ * the order they were due, every one counted on the process-wide
+ * {@link traceRecordCounts}. Per served prompt the add-on calls
+ * {@link ServedPublisher.beginTurn} with the prompt's scope, `bind`s the
+ * harness's id once it knows it, and `settle`s with the outcome;
+ * {@link ServedPublisher.flush} before the plugin stops.
+ */
+declare function servedPublisher(options: ServedPublisherOptions): ServedPublisher;
+
+/** Prefix of the expanded reference token. */
+declare const REFERENCE_PREFIX = "sp-ref:";
+declare const SHORT_REFERENCE_PREFIX = "sp-r1:";
+/**
+ * The service metadata key an agent that reads the references it is handed
+ * registers, with the value `"true"` (the SDK's `extraMetadata`). A caller
+ * hands a reference, and grants read on it, only to an agent that says so.
+ * In the style of the protocol's `attachments_ok`.
+ */
+declare const READS_REFERENCES_KEY = "scratchpad_refs_ok";
+/** The served prompt's thread and root, as `activeTrace()` reports them. */
+interface TraceIds {
+    readonly threadId: string;
+    readonly rootId: string;
+}
+/**
+ * The principal ScratchPad grants to: the two halves of an agent identity,
+ * `<account>.<user>`, both public NKEYs on the fabric.
+ */
+interface Grantee {
+    readonly account: string;
+    readonly user: string;
+}
+/**
+ * How a grant came about. `first-hand`: the agent granted an agent it
+ * handed the reference itself — the verified caller of its reply, or the
+ * agent it prompted with a reference of its own. `on-request`: the agent
+ * granted an agent because another agent asked it to (`grant-request.ts`).
+ * Only a first-hand grant entitles its holder to ask for another agent, or
+ * access could be relayed from agent to agent without end.
+ */
+type GrantKind = "first-hand" | "on-request";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * What the policy needs of the agent's ScratchPad: its own volume, and a
+ * ledger of the read grants it made. ScratchPad knows the grants but not
+ * how they came about; that is the agent's own knowledge, so the
+ * implementation keeps the ledger.
+ */
+interface ScratchPad {
+    /** Resolve reference metadata through the implementation's authenticated client. */
+    resolveReference?(reference: string, trace?: TraceIds): MaybePromise<{
+        readonly creator: string;
+    }>;
+    /** Whether `reference` points into this agent's own volume, where it may grant. */
+    owns(reference: string): MaybePromise<boolean>;
+    /**
+     * Grant `grantee` read on the one path `reference` names, until the
+     * grant's expiry, and note it in the ledger as `kind` (`first-hand` when
+     * not given). Only for a reference into this agent's own volume. `trace`
+     * and `toolCallId` label the grant, so it shows under the served prompt
+     * and the tool call that caused it.
+     */
+    grantRead(reference: string, grantee: Grantee, trace: TraceIds | undefined, toolCallId?: string, kind?: GrantKind): MaybePromise<void>;
+    /**
+     * The live grant this agent made to `grantee` on what `reference` points
+     * at, by kind; `undefined` when there is none or it has expired. A
+     * first-hand grant still running is not hidden by a later one made on
+     * request.
+     */
+    granted(reference: string, grantee: Grantee): MaybePromise<GrantKind | undefined>;
+}
+/** Every reference token in `text`, in order, repeats included. */
+declare function findReferences(text: string): string[];
+/**
+ * `text` with reference tokens taken out — every one, or only those in
+ * `only` — and the trailing spaces and extra blank lines that leaves
+ * behind tidied away.
+ */
+declare function removeReferences(text: string, only?: ReadonlyArray<string>): string;
+/**
+ * The prompt address of the agent that made `reference`, as the token says;
+ * `undefined` for a token that names none or does not decode.
+ */
+declare function referenceCreator(reference: string): string | undefined;
+/** Whether an agent's registration metadata says it reads references. */
+declare function readsReferences(metadata: Readonly<Record<string, string>>): boolean;
+/**
+ * The grantee behind an identity as discovery or a verified sender reports
+ * it. Throws for anything that is not `<account>.<user>`.
+ */
+declare function granteeFromIdentity(identity: string): Grantee;
+
+/** What the requester sends (`sp-grant-request.json`). */
+interface GrantRequest {
+    /** The reference, exactly as the requester was given it. */
+    readonly reference: string;
+    /** The identity, `<account>.<user>`, of the agent that should be able to read it. */
+    readonly grantee: string;
+    /**
+     * The requester's served thread and the tool call the handoff belongs to,
+     * so the creator's grant shows under the call that caused it. Labels
+     * only, never authority.
+     */
+    readonly trace?: {
+        readonly thread_id: string;
+        readonly root_id: string;
+        readonly tool_call_id?: string;
+    };
+}
+/** What the creator answers (`sp-grant-reply.json`). */
+type GrantReply = {
+    readonly granted: true;
+} | {
+    readonly granted: false;
+    readonly reason: string;
+};
+/** The name of the creator's extra endpoint, and the verb of its subject. */
+declare const GRANT_REQUEST_ENDPOINT = "sp-grant";
+/**
+ * How long the requester waits for the creator's answer. The creator runs
+ * one ScratchPad operation before it answers, so longer than the SDK's two
+ * seconds for a signed request.
+ */
+declare const DEFAULT_GRANT_REQUEST_TIMEOUT_MS = 10000;
+/**
+ * Where the agent at `promptAddress` takes grant requests: the same subject
+ * with the verb changed. Derived, never taken from what another agent says,
+ * so a request only ever goes to the creator's own subject. Throws for a
+ * subject that is not a prompt address.
+ */
+declare function grantSubject(promptAddress: string): string;
+/** A request's bytes, as both packages write them: the schema's key order. */
+declare function encodeGrantRequest(request: GrantRequest): string;
+/** A reply's bytes, as both packages write them. */
+declare function encodeGrantReply(reply: GrantReply): string;
+interface RequestGrantOptions {
+    /** How long to wait for the answer. Default {@link DEFAULT_GRANT_REQUEST_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+/**
+ * The requester's side: ask the agent at `creatorAddress` to grant what
+ * `request` names, signed as `agents`' identity. Never throws: no answer,
+ * or an answer that is not a grant, is a refusal with its reason in words.
+ */
+declare function requestGrant(agents: Agents, creatorAddress: string, request: GrantRequest, options?: RequestGrantOptions): Promise<GrantReply>;
+/**
+ * The creator's rule, for a requester whose signature verified. `requester`
+ * is that verified sender ID; `payload` the request's body. Never throws.
+ * {@link grantRequestEndpoint} runs it after the SDK's `SenderGate`; a host
+ * that takes grant requests some other way must verify the sender first.
+ */
+declare function answerGrantRequest(requester: string, payload: string, scratchPad: ScratchPad, logger?: Logger): Promise<GrantReply>;
+interface GrantRequestEndpointOptions {
+    /** This agent's own prompt address; the endpoint sits next to it. */
+    readonly promptAddress: string;
+    /** This agent's ScratchPad: the volume it may grant on, and its ledger. */
+    readonly scratchPad: ScratchPad;
+    /** Refusals at `info`, failures at `error`. Default: silent. */
+    readonly logger?: Logger;
+}
+/**
+ * The creator's side, as an extra endpoint for the agent's `AgentService`
+ * (`extraEndpoints: [grantRequestEndpoint({ ... })]`): it answers every
+ * grant request by the rule at the top of this file. Several instances of
+ * one agent share the work, in the `agents` queue group.
+ */
+declare function grantRequestEndpoint(options: GrantRequestEndpointOptions): AgentServiceExtraEndpoint;
+
+/** The field `discover_agents` entries get. */
+declare const READS_SCRATCHPAD_REFERENCES_FIELD = "reads_scratchpad_references";
+interface ScratchPadExtensionOptions {
+    /** The agent's own ScratchPad, behind the port. */
+    readonly scratchPad: ScratchPad;
+    /**
+     * The client grant requests are signed and sent with, and creators are
+     * looked up through: the one `AgentTools` runs on, with the agent's
+     * signer.
+     */
+    readonly agents: Agents;
+    /** How long a lookup of a creator waits; unset, the SDK's discovery default. */
+    readonly discoverTimeoutMs?: number;
+    /** How long a creator's answer is waited for. Default 10 seconds. */
+    readonly grantRequestTimeoutMs?: number;
+}
+/** The extension; build it with {@link scratchPadExtension}. */
+declare class ScratchPadExtension implements AgentToolsExtension {
+    #private;
+    /**
+     * For the agent's `AgentService` (`interceptors: [...]`): remembers the
+     * references in every prompt it serves.
+     */
+    readonly requestInterceptor: RequestInterceptor;
+    constructor(options: ScratchPadExtensionOptions);
+    /**
+     * Note the references in `text` as given to this agent: what it
+     * committed, or received some way the hooks do not see.
+     */
+    remember(text: string): void;
+    /**
+     * The reply side: before a reply carrying `reference`, this agent's own,
+     * goes out, remember it and grant the served prompt's sender read on it,
+     * first-hand — only a sender whose signature verified, since a grant
+     * names a principal and an unsigned claim proves none. `true` when
+     * granted, so the reference may go into the reply; `false` for a sender
+     * that did not verify. Throws when the reference is not this agent's own
+     * or the grant fails. The commit itself stays the agent's.
+     */
+    grantCaller(reference: string, sender: SenderInfo | undefined): Promise<boolean>;
+    /** The discovery fields hook. */
+    discoveryFields(agent: Agent): Record<string, unknown>;
+    /** The prompt rewrite hook. */
+    beforePrompt(ctx: AgentToolsPromptContext): Promise<AgentToolsPromptRewrite | void>;
+    /** The reply look hook. */
+    afterReply(ctx: AgentToolsReplyContext): void;
+}
+/** The ScratchPad extension for `AgentTools` (`extensions: [...]`). */
+declare function scratchPadExtension(options: ScratchPadExtensionOptions): ScratchPadExtension;
+
+/**
+ * The agent's ScratchPad: the {@link ScratchPad} port, which the rules for
+ * references run on, and the commit and read the agent makes itself.
+ */
+interface ScratchPadClient extends ScratchPad {
+    /**
+     * Publish `text` at `path` in this agent's volume, retained for ten
+     * minutes, and return the reference token the CLI made for it.
+     */
+    commit(text: string, path: string, trace: TraceIds | undefined): Promise<string>;
+    /** Fetch the exact content a reference token names, as text. */
+    read(reference: string, trace: TraceIds | undefined): Promise<string>;
+}
+interface SpCliScratchPadOptions {
+    /**
+     * The volume this agent writes to, by name: letters and digits only. The
+     * deployment provisions it for the agent's account and user; the first
+     * commit creates it.
+     */
+    readonly volume: string;
+    /**
+     * The agent's own connection source: `sp` authenticates the same way. It
+     * takes a URL with a credentials file; it reads no NATS context, and an
+     * nkey seed alone is not a form it accepts.
+     */
+    readonly nats: NatsConnectionSource;
+    /** The `sp` binary. Default `sp` on PATH. */
+    readonly bin?: string;
+    /**
+     * A private directory for the CLI's workspace; created if missing, and
+     * used by its real path. Keep it across restarts: it records the volume
+     * and any command still to finish. Default `scratchpad-<volume>` under
+     * the temp directory.
+     */
+    readonly dir?: string;
+    /** How long a read grant lasts, in seconds. Default and ceiling ten minutes. */
+    readonly grantTtlS?: number;
+    /**
+     * This agent's prompt address, written into every reference it makes, so
+     * an agent handed one knows whom to ask before passing it on. A commit
+     * needs it.
+     */
+    readonly creator?: string;
+}
+/** The `sp` binary when none is given: the one on PATH. */
+declare const DEFAULT_SP_BIN = "sp";
+/**
+ * How long a read grant lasts at most: long enough for the receiving agent
+ * to read what it was handed when it starts on the prompt, short enough
+ * that the access does not outlive the task. A grant also never outlives
+ * the reference it is on.
+ */
+declare const DEFAULT_GRANT_TTL_S = 600;
+/**
+ * A refusal or failure from `sp`: its error code, and whether the outcome
+ * is unknown — a mutation that may still have taken effect.
+ */
+declare class ScratchPadError extends Error {
+    readonly code: string;
+    readonly unknown: boolean;
+    constructor(message: string, code: string, unknown: boolean);
+}
+/**
+ * Commit, read and grant by reference, through one `sp` binary and one
+ * volume: the {@link ScratchPadClient} an agent hands to
+ * `scratchPadExtension()` and `grantRequestEndpoint()` and commits and reads
+ * with itself.
+ */
+declare function spCliScratchPad(options: SpCliScratchPadOptions): ScratchPadClient;
+/** The variables {@link scratchPadFromEnv} reads. */
+declare const SCRATCHPAD_VOLUME_VAR = "SCRATCHPAD_VOLUME";
+declare const SCRATCHPAD_BIN_VAR = "SCRATCHPAD_BIN";
+declare const SCRATCHPAD_DIR_VAR = "SCRATCHPAD_DIR";
+declare const SCRATCHPAD_GRANT_TTL_S_VAR = "SCRATCHPAD_GRANT_TTL_S";
+/** What {@link scratchPadFromEnv} takes besides the environment. */
+interface ScratchPadFromEnvOptions {
+    /** This agent's prompt address, written into every reference it makes. */
+    readonly creator?: string;
+    /**
+     * The agent's connection source, when it is not the environment's
+     * `NATS_CONTEXT`, or `NATS_CREDS` with `NATS_URL`.
+     */
+    readonly nats?: NatsConnectionSource;
+}
+/**
+ * The agent's ScratchPad as the environment configures it, or `undefined`
+ * when `SCRATCHPAD_VOLUME` is unset: ScratchPad off. Reads
+ * `SCRATCHPAD_VOLUME`, `SCRATCHPAD_BIN`, `SCRATCHPAD_DIR` and
+ * `SCRATCHPAD_GRANT_TTL_S`, and, unless `options.nats` is given, the
+ * connection the agent's own configuration reads: `NATS_CREDS` with
+ * `NATS_URL` (default `nats://127.0.0.1:4222`), or `NATS_CONTEXT`, which
+ * `sp` cannot use. An empty variable counts as unset. Throws for a grant TTL
+ * that is not a positive number, and, like {@link spCliScratchPad}, for a
+ * connection `sp` cannot use: a NATS context without credentials, or no
+ * credentials at all.
+ */
+declare function scratchPadFromEnv(env?: Readonly<Record<string, string | undefined>>, options?: ScratchPadFromEnvOptions): ScratchPadClient | undefined;
+
+/** The §9 code the guard refuses with. */
+declare const LOOP_GUARD_CODE = 409;
+/** The description the refused caller sees, for `rootId`. */
+declare function loopGuardDescription(rootId: string): string;
+interface LoopGuard {
+    /** For the service, after the fabric's tracing interceptor. */
+    readonly requestInterceptor: RequestInterceptor;
+    /** For the plugin's client, next to the fabric's prompt interceptor. */
+    readonly promptInterceptor: PromptInterceptor;
+    /**
+     * For the add-on's `aroundToolCall`: runs `run` once, synchronously, and
+     * returns its value untouched, a promise included. `scope` is the served
+     * request's, the one tracing bound around its handler; with another or
+     * none the call is only run.
+     */
+    aroundToolCall<T>(scope: TraceScope | undefined, run: () => T): T;
+    /** `true` while a served request of tree `rootId` is open. */
+    serving(rootId: string): boolean;
+    /** `true` while a served request of tree `rootId` waits on a call it made. */
+    waiting(rootId: string): boolean;
+}
+declare function loopGuard(): LoopGuard;
+
+declare const CODES: readonly ["ok", "invalid", "unauthenticated", "denied", "not_found", "exists", "conflict", "fenced", "intent_changed", "capacity", "summary_limit", "closed", "epoch_changed", "expired", "corrupt", "incomplete", "busy", "unknown", "unavailable", "internal"];
+type Code = (typeof CODES)[number];
+type ContentID = string;
+interface Principal {
+    account: string;
+    user: string;
+}
+interface Trace {
+    thread_id?: string;
+    root_id?: string;
+    tool_call_id?: string;
+}
+interface Action {
+    operation_id: string;
+    trace: Trace;
+}
+interface Target {
+    volume: string;
+    creation_id: string;
+}
+interface Head {
+    generation: number;
+    root: ContentID;
+}
+interface Writer {
+    slot: number;
+    generation: number;
+}
+interface RetentionIntent {
+    enabled: boolean;
+    slot: number;
+    generation: number;
+    until: number;
+}
+interface RetentionHandle {
+    slot: number;
+    generation: number;
+}
+interface GrantHandle {
+    slot: number;
+    generation: number;
+}
+interface RetentionOrigin {
+    writer: Writer;
+    number: number;
+}
+interface Command {
+    creation_id: string;
+    writer: Writer;
+    number: number;
+    operation_id: string;
+    base: Head;
+    root: ContentID;
+    trace: Trace;
+    retention: RetentionIntent;
+}
+interface Receipt {
+    volume: string;
+    principal: Principal;
+    command: Command;
+    head: Head;
+    retention: RetentionHandle;
+}
+interface WriterSlot {
+    generation: number;
+    number: number;
+    principal?: Principal;
+    write: boolean;
+    receipt?: Receipt;
+}
+interface RetentionValue {
+    root: ContentID;
+    until: number;
+    origin: RetentionOrigin;
+}
+interface RetentionSlot {
+    generation: number;
+    pin?: RetentionValue;
+}
+interface GrantValue {
+    principal: Principal;
+    root: ContentID;
+    path: string;
+    directory: boolean;
+    retention: RetentionHandle;
+    until: number;
+}
+interface GrantSlot {
+    generation: number;
+    grant?: GrantValue;
+}
+interface VolumeView {
+    target: Target;
+    owner: Principal;
+    head: Head;
+    revision: number;
+    closed: boolean;
+    epoch: number;
+    objects: number;
+    bytes: number;
+    writers: WriterSlot[];
+    retentions: RetentionSlot[];
+    grants: GrantSlot[];
+}
+interface Limits {
+    object_bytes: number;
+    read_bytes: number;
+    control_bytes: number;
+    reply_bytes: number;
+    writers: number;
+    retentions: number;
+    grants: number;
+    grant_seconds: number;
+}
+interface ReservedScope {
+    volume: string;
+    objects: number;
+    bytes: number;
+}
+interface Info {
+    principal: Principal;
+    scopes: ReservedScope[];
+    limits: Limits;
+}
+interface ContentObject {
+    kind: "chnk" | "fobj" | "tree";
+    id: ContentID;
+}
+interface ObjectSpec {
+    object: ContentObject;
+    length: number;
+}
+type AllocationState = "reserved" | "verifying" | "verified" | "refused";
+interface ObjectProgress extends ObjectSpec {
+    state: AllocationState;
+    next: number;
+    code: Code;
+}
+interface PrepareRequest {
+    target: Target;
+    objects: ObjectSpec[];
+}
+interface PrepareResult {
+    epoch: number;
+    objects: ObjectProgress[];
+}
+interface VerifyRequest {
+    target: Target;
+    epoch: number;
+    objects: ContentObject[];
+}
+interface VerifyResult {
+    epoch: number;
+    objects: ObjectProgress[];
+}
+interface PutRequest {
+    target: Target;
+    object: ContentObject;
+    epoch: number;
+}
+interface CreateRequest {
+    volume: string;
+    action: Action;
+}
+interface PublishRequest {
+    target: Target;
+    command: Command;
+}
+interface RetainRequest {
+    target: Target;
+    slot: number;
+    generation: number;
+    root: ContentID;
+    until: number;
+    action: Action;
+}
+interface ReleaseRequest {
+    target: Target;
+    handle: RetentionHandle;
+}
+interface GrantIssueRequest {
+    target: Target;
+    slot: number;
+    generation: number;
+    principal: Principal;
+    root: ContentID;
+    path: string;
+    retention: RetentionHandle;
+    until: number;
+    action: Action;
+}
+interface RevokeRequest {
+    target: Target;
+    handle: GrantHandle;
+    action: Action;
+}
+interface PathRequest {
+    target: Target;
+    root: ContentID;
+    path: string;
+    trace: Trace;
+}
+interface ReadRequest extends PathRequest {
+    offset: number;
+    length: number;
+}
+interface ListRequest extends PathRequest {
+    offset: number;
+    limit: number;
+}
+interface Stat {
+    type: "file" | "directory" | "symlink";
+    object: ContentID;
+    size: number;
+    sha256: string;
+    executable: boolean;
+    link_target?: string;
+}
+interface Entry {
+    name: string;
+    type: "file" | "directory" | "symlink";
+    object: ContentID;
+    executable: boolean;
+    link_target?: string;
+}
+interface ListResult {
+    entries: Entry[];
+    next: number;
+    done: boolean;
+}
+interface ReadResult {
+    stat: Stat;
+    offset: number;
+    data: Uint8Array;
+}
+interface MaintenanceRequest {
+    target: Target;
+    revision: number;
+}
+interface CollectionReport {
+    inventory_objects: number;
+    inventory_bytes: number;
+    live_objects: number;
+    live_bytes: number;
+    candidate_objects: number;
+    candidate_bytes: number;
+    delete_objects: number;
+}
+interface CollectionResult {
+    volume: VolumeView;
+    collection: CollectionReport;
+}
+
+interface Reference {
+    version: 2;
+    creator: string;
+    account: string;
+    target: Target;
+    root: string;
+    generation: number;
+    path: string;
+    retention: RetentionHandle;
+    expires_at: number;
+}
+declare function encodeReference(reference: Reference): string;
+declare function decodeReference(token: string): Reference;
+
+interface ShortReference {
+    route: string;
+    creation_id: string;
+    retention: RetentionHandle;
+    path_index: number;
+}
+interface ReferenceSpec {
+    creator: string;
+    paths: string[];
+}
+interface ResolvedReference {
+    short: string;
+    expanded: Reference;
+}
+interface ReferenceCapabilities {
+    enabled: boolean;
+    version: number;
+    prefix: string;
+    token_bytes: number;
+    paths_per_retention: number;
+    max_intent_bytes: number;
+    max_metadata_bytes: number;
+}
+interface ReferencePublishRequest extends PublishRequest {
+    reference: ReferenceSpec;
+}
+interface ReferencePublishResult {
+    receipt: Receipt;
+    references: ResolvedReference[];
+}
+interface ReferenceResolveRequest {
+    reference: string;
+    trace: Trace;
+}
+interface ReferenceStatResult {
+    reference: ResolvedReference;
+    stat: Stat;
+}
+/** Decode the locator only. The service verifies its metadata verifier. */
+declare function decodeShortReference(token: string): ShortReference;
+interface ReferenceRetainRequest {
+    retain: RetainRequest;
+    reference: ReferenceSpec;
+}
+interface ReferenceRetainResult {
+    volume: VolumeView;
+    references: ResolvedReference[];
+}
+
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+interface TransportOptions {
+    timeoutMs?: number;
+}
+/** One request per operation on a borrowed NATS connection. No retry or identity override. */
+declare class ScratchPadTransport {
+    private readonly nc;
+    readonly timeoutMs: number;
+    constructor(nc: NatsConnection, options?: TransportOptions);
+    private within;
+    private exchange;
+    private control;
+    private matching;
+    private view;
+    info(options?: RequestOptions): Promise<Info>;
+    createVolume(request: CreateRequest, options?: RequestOptions): Promise<VolumeView>;
+    getVolume(target: Target, options?: RequestOptions): Promise<VolumeView>;
+    prepare(request: PrepareRequest, options?: RequestOptions): Promise<PrepareResult>;
+    putPrepared(request: PutRequest, data: Uint8Array, options?: RequestOptions): Promise<void>;
+    verify(request: VerifyRequest, options?: RequestOptions): Promise<VerifyResult>;
+    publish(request: PublishRequest, options?: RequestOptions): Promise<Receipt>;
+    /** Unknown reference verbs on older services return invalid. Other failures propagate. */
+    referenceInfo(options?: RequestOptions): Promise<ReferenceCapabilities | undefined>;
+    private referencePublication;
+    referencePublish(request: ReferencePublishRequest, options?: RequestOptions): Promise<ReferencePublishResult>;
+    referenceReceipt(request: ReferencePublishRequest, options?: RequestOptions): Promise<ReferencePublishResult>;
+    referenceResolve(request: ReferenceResolveRequest, options?: RequestOptions): Promise<ResolvedReference>;
+    referenceStat(request: ReferenceResolveRequest, options?: RequestOptions): Promise<ReferenceStatResult>;
+    referenceRetain(request: ReferenceRetainRequest, options?: RequestOptions): Promise<ReferenceRetainResult>;
+    resetWriter(target: Target, writer: Writer, options?: RequestOptions): Promise<Writer>;
+    retain(request: RetainRequest, options?: RequestOptions): Promise<VolumeView>;
+    release(request: ReleaseRequest, options?: RequestOptions): Promise<VolumeView>;
+    issueGrant(request: GrantIssueRequest, options?: RequestOptions): Promise<GrantHandle>;
+    revokeGrant(request: RevokeRequest, options?: RequestOptions): Promise<VolumeView>;
+    stat(request: PathRequest, options?: RequestOptions): Promise<Stat>;
+    list(request: ListRequest, options?: RequestOptions): Promise<ListResult>;
+    read(request: ReadRequest, options?: RequestOptions): Promise<ReadResult>;
+    closeVolume(request: MaintenanceRequest, options?: RequestOptions): Promise<VolumeView>;
+    planCollection(request: MaintenanceRequest, options?: RequestOptions): Promise<CollectionReport>;
+    applyCollection(request: MaintenanceRequest, options?: RequestOptions): Promise<CollectionResult>;
+}
+
+declare const DEFAULT_READ_LIMIT_BYTES: number;
+interface ScratchPadReaderOptions {
+    nc: NatsConnection;
+    timeoutMs?: number;
+}
+interface ReadBytesOptions {
+    limitBytes?: number;
+    trace?: TraceIds;
+}
+/** Authenticated reads through a borrowed NATS connection; no workspace needed. */
+declare class ScratchPadReader {
+    protected readonly transport: ScratchPadTransport;
+    readonly principal: Principal;
+    private readonly expansions;
+    constructor(transport: ScratchPadTransport, principal: Principal);
+    protected reference(token: string): Reference;
+    protected checkedReference(reference: Reference): Reference;
+    private checkDeadline;
+    protected cacheReference(pair: ResolvedReference): void;
+    /** Expand either form for programmatic use. Metadata supplies no read authority. */
+    resolveReference(token: string, trace?: TraceIds): Promise<Reference>;
+    private openFile;
+    private chunks;
+    /** Returns bytes only after size, logical digest and canonical file identity agree. */
+    readBytes(token: string, options?: ReadBytesOptions): Promise<Uint8Array>;
+    /** Bytes are provisional until iteration completes without error. Consume to EOF
+     * and publish a downloaded file only after success; early cancellation is unverified.
+     * The caller must set an explicit whole-file size allowance.
+     */
+    readStream(token: string, options: ReadBytesOptions & {
+        limitBytes: number;
+    }): AsyncGenerator<Uint8Array>;
+    read(reference: string, trace?: TraceIds): Promise<string>;
+}
+declare function scratchPadReader(options: ScratchPadReaderOptions): Promise<ScratchPadReader>;
+
+/** One private local database, exclusively owned for the client's lifetime. */
+declare class WorkspaceStore {
+    private readonly db;
+    private readonly directory;
+    private poisoned;
+    private closed;
+    private constructor();
+    static open(directory: string): Promise<WorkspaceStore>;
+    private usable;
+    load(): unknown;
+    save(state: unknown, afterRemote?: boolean, clearObjects?: boolean): void;
+    clearObjects(): void;
+    putObject(ordinal: number, object: ContentObject, data: Uint8Array): void;
+    objects(): ObjectSpec[];
+    bytes(object: ContentObject): Uint8Array;
+    close(): void;
+}
+
+interface NativeScratchPadOptions extends ScratchPadReaderOptions {
+    /** Private directory on a persistent local filesystem. One client owns it at a time. */
+    dir: string;
+    volume: string;
+    /** Prompt address used only to route Fabric grant requests. It is not authentication. */
+    creator: string;
+    ttlSeconds?: number;
+}
+interface PublishOptions {
+    operationId: string;
+    ttlSeconds?: number;
+    trace?: TraceIds;
+}
+interface PublishResult {
+    reference: string;
+    receipt: Receipt;
+}
+interface RecoveryResult {
+    kind: string;
+    reference?: string;
+    receipt?: Receipt;
+}
+interface Publication {
+    kind: "publish";
+    command: Command;
+    path: string;
+    ttl: number;
+    expiry_revision?: number;
+    reference?: ReferenceSpec;
+}
+interface Granted {
+    request: GrantIssueRequest;
+    handle: GrantHandle;
+    kind: GrantKind;
+}
+type Control = {
+    kind: "grant";
+    request: GrantIssueRequest;
+    provenance: GrantKind;
+} | {
+    kind: "release";
+    request: ReleaseRequest;
+} | {
+    kind: "close" | "apply";
+    request: MaintenanceRequest;
+};
+type Pending = Publication | Control | {
+    kind: "reset";
+    writer: Writer;
+};
+interface State {
+    version: 1;
+    principal: Principal;
+    volume: string;
+    creator: string;
+    creation: Action;
+    target?: Target;
+    writer?: Writer;
+    next: number;
+    pending?: Pending;
+    last?: PublishResult & {
+        path: string;
+        ttl: number;
+        resolved?: ResolvedReference;
+    };
+    grants: Granted[];
+}
+/** A native writer and Fabric adapter. It borrows the caller's authenticated connection. */
+declare class NativeScratchPad extends ScratchPadReader implements ScratchPadClient {
+    private readonly store;
+    private state;
+    private readonly scope;
+    private readonly ttl;
+    private tail;
+    private closing;
+    private closePromise?;
+    constructor(transport: ScratchPadTransport, store: WorkspaceStore, state: State, scope: ReservedScope, ttl: number);
+    private run;
+    private save;
+    private change;
+    private target;
+    private ensureTarget;
+    private initialize;
+    private reset;
+    /** Explicitly abandon writer recovery, fencing the exact generation observed by describe(). */
+    resetWriter(options: {
+        expectedGeneration: number;
+        target?: Target;
+    }): Promise<Writer>;
+    describe(): Promise<{
+        volume: VolumeView;
+        pending?: string;
+    }>;
+    recover(): Promise<RecoveryResult>;
+    private recoverPending;
+    publishBytes(bytes: Uint8Array, path: string, options: PublishOptions): Promise<PublishResult>;
+    /** A publication replaces the head with one file at path. Older references keep their retained roots. */
+    publishStream(source: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, path: string, options: PublishOptions): Promise<PublishResult>;
+    private publish;
+    private samePublication;
+    private resumePublish;
+    private fenceExpired;
+    private accept;
+    private upload;
+    commit(value: string, path: string, trace: TraceIds | undefined): Promise<string>;
+    owns(token: string): boolean | Promise<boolean>;
+    granted(token: string, grantee: Grantee): GrantKind | undefined | Promise<GrantKind | undefined>;
+    grantRead(token: string, grantee: Grantee, trace?: TraceIds, toolCallId?: string, kind?: GrantKind): Promise<void>;
+    /** Release a completed handoff. Refuses while any live grant names its retention. */
+    release(token: string): Promise<void>;
+    /** Collect unreferenced content in this client's own maintenance interval. */
+    maintain(): Promise<VolumeView>;
+    private maintainInternal;
+    private control;
+    close(): Promise<void>;
+}
+/** Construct a native client without creating a remote volume until first use. */
+declare function nativeScratchPad(options: NativeScratchPadOptions): Promise<NativeScratchPad>;
+/** Environment configuration for SDK agents, using their existing connection. */
+declare function nativeScratchPadFromEnv(env: Readonly<Record<string, string | undefined>>, options: ScratchPadReaderOptions & {
+    creator: string;
+}): Promise<NativeScratchPad | undefined>;
+
+/** A failed request. `unknown` means a mutation may already have taken effect. */
+declare class NativeScratchPadError extends Error {
+    readonly code: Code;
+    readonly unknown: boolean;
+    readonly local: boolean;
+    constructor(code: Code, message: string, options?: {
+        unknown?: boolean;
+        local?: boolean;
+        cause?: unknown;
+    });
+}
+
+/** The one setting: the edge subject, in the config entry's `options`. */
+declare const EDGE_SUBJECT_OPTION = "edgeSubject";
+/** The same setting as a variable, read when the option is not given. */
+declare const EDGE_SUBJECT_VAR = "SYNADIA_FABRIC_EDGE_SUBJECT";
+/**
+ * The edge subject an add-on runs with: the config entry's
+ * `options.edgeSubject` when the key is there (`null` is propagate-only:
+ * lineage without records), else `SYNADIA_FABRIC_EDGE_SUBJECT` when set,
+ * else the fabric's default. The value is returned as given; the package
+ * validates it (`assertValidTraceOptions`) and throws for one that can
+ * never be published to, which stops the add-on's factory — the plugin
+ * then logs the error and starts plain, so a misconfigured subject is
+ * visible at start rather than as a warning on every prompt.
+ */
+declare function resolveEdgeSubject(options: Readonly<Record<string, unknown>>, env?: NodeJS.ProcessEnv): string | null;
+
+/**
+ * The harnesses that expose this extension point. Named apart from the
+ * served record's `Harness` (`served.ts`), which is the proxy's word for a
+ * harness, not the plugin's.
+ */
+type PluginHarness = "pi" | "openclaw" | "claude-code";
+/** The plugin's resolved settings, as the factory sees them before connect. */
+interface AgentExtensionSettings {
+    /** The address tokens: `agents.prompt.<token>.<owner>.<name>`. */
+    readonly owner: string;
+    /**
+     * The name token as configured. The plugin checks it for a collision once
+     * on the bus and may suffix it; the definitive address is
+     * `service.subject.prompt` in `started()`.
+     */
+    readonly name: string;
+    readonly senderIdentity: "off" | "signed";
+    readonly minSenderTrust: "any" | "signed";
+    /** Where the plugin keeps its files, when it has such a directory. */
+    readonly stateDir?: string;
+    /** The plugin's configuration as read, unknown keys included; read-only. */
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/** What the plugin knows when it loads the module, before it connects. */
+interface AgentExtensionContext {
+    readonly harness: PluginHarness;
+    readonly plugin: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly settings: AgentExtensionSettings;
+    /** The `options` of this module's config entry, verbatim; `{}` when the variable named it. */
+    readonly options: Readonly<Record<string, unknown>>;
+    /** The plugin's logger, in the SDK's `Logger` shape. */
+    readonly logger: Logger;
+}
+/** A served prompt, as the harness's events name it. */
+interface ServedRequest {
+    /** The plugin's id for the request, unique in the process. */
+    readonly id: string;
+    /** The envelope's fields the protocol does not define (§5.6), as decoded. */
+    readonly extras: Readonly<Record<string, unknown>>;
+    /** The verified sender's id, when the signature verified. */
+    readonly caller?: string;
+    /** Claude Code only: the session the prompt was delivered to, when known. */
+    readonly sessionId?: string;
+}
+type Outcome = "ok" | "error" | "timeout";
+/**
+ * Claude Code: how a prompt ended when the model did not end it with its
+ * own reply, `promptEnded`'s fourth argument; absent when it did.
+ * `final_text`: the turn ended without a reply and the plugin sent the
+ * turn's final text as the reply (outcome `ok`); `no_reply`: no reply and
+ * no final text; `shutdown`: the plugin stopped with the prompt open;
+ * `delivery`: the prompt could not be handed to the harness (all three
+ * `error`); `expired`: the prompt outlived the plugin's limit (`timeout`).
+ * The same values as the served record's `reason`.
+ */
+type EndReason = "final_text" | "no_reply" | "shutdown" | "delivery" | "expired";
+/**
+ * The harness's events. A notification is called and forgotten; a wrapper
+ * is called by the plugin around one of its own steps and must call `run`
+ * once, synchronously, and return its value, a promise included. A wrapper
+ * may be an async function: the plugin still takes `run`'s own value, and
+ * the wrapper must call `run` once, before its first `await`, so the step
+ * keeps its timing. Every harness calls the first three; PI also
+ * `aroundInject` and `providerHeaders`, OpenClaw `aroundDispatch`, Claude
+ * Code `sessionStarted` and `turnStopped`. One shape serves all three.
+ */
+interface HarnessEvents {
+    /** Inside the prompt handler, after every interceptor ran. */
+    promptAccepted?(request: ServedRequest): void;
+    /**
+     * When the plugin settles the request. Claude Code passes `reason` when
+     * the model did not end the prompt with its own reply.
+     */
+    promptEnded?(request: ServedRequest, outcome: Outcome, atMs: number, reason?: EndReason): void;
+    /** Around every agent-tool call, with the request the model works in. */
+    aroundToolCall?<T>(request: ServedRequest | undefined, toolName: string, run: () => T): T;
+    /** PI: around the hand-over of the prompt to PI's loop (`pi.sendUserMessage()`). */
+    aroundInject?<T>(request: ServedRequest, run: () => T): T;
+    /** PI: headers to add to a provider request while `request` is PI's active turn. */
+    providerHeaders?(request: ServedRequest): Readonly<Record<string, string>> | undefined;
+    /**
+     * OpenClaw: around the turn's dispatch
+     * (`dispatchInboundDirectDmWithRuntime()`). Asynchronous: the extension
+     * calls `run` once and returns its promise.
+     */
+    aroundDispatch?<T>(request: ServedRequest, run: () => Promise<T>): Promise<T>;
+    /** Claude Code: a session started, from its hook. */
+    sessionStarted?(sessionId: string, source: string): void;
+    /** Claude Code: a turn stopped, from its hook. */
+    turnStopped?(sessionId: string | undefined, atMs: number): void;
+}
+/** The live handles, once the plugin is on the bus. */
+interface AgentExtensionHandles {
+    readonly agents: Agents;
+    readonly service: AgentService;
+}
+/** What the factory returns. */
+interface AgentExtension {
+    readonly name: string;
+    /** For the plugin's `Agents` client: `new Agents({ interceptors })`. */
+    readonly promptInterceptors?: ReadonlyArray<PromptInterceptor>;
+    /** For the plugin's `AgentService`, before the plugin's own interceptors. */
+    readonly requestInterceptors?: ReadonlyArray<RequestInterceptor>;
+    /** For the plugin's `AgentService`: `heartbeatExtras`. */
+    readonly heartbeatExtras?: () => Readonly<Record<string, unknown>>;
+    /** For the plugin's `AgentTools`: `extensions`. */
+    readonly toolExtensions?: ReadonlyArray<AgentToolsExtension>;
+    /**
+     * Keys for the service's registration metadata, read once before the
+     * service starts. A key is one or more of `A-Z a-z 0-9 _ - .`, a value a
+     * string; anything else fails the plugin's start. The plugin's own keys
+     * and the protocol's registration keys win over an entry of the same name
+     * (`agents/EXTENSIONS.md` in `synadia-agents`, from #218).
+     */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** After the service started. Awaited, bounded by the plugin. */
+    started?(handles: AgentExtensionHandles): void | Promise<void>;
+    /** Before the plugin stops its service. Awaited, bounded by the plugin. */
+    stopping?(): void | Promise<void>;
+    /** The harness's events. */
+    readonly events?: HarnessEvents;
+}
+/** The module's one default export. */
+type AgentExtensionFactory = (ctx: AgentExtensionContext) => AgentExtension | Promise<AgentExtension>;
+
+/** The config entry's option that holds ScratchPad's settings. */
+declare const SCRATCHPAD_OPTION = "scratchpad";
+/**
+ * The variables `scripts/sp` reads. The connection has names of its own,
+ * not `NATS_URL` and `NATS_CREDS`, which a plugin may read as its own
+ * connection (OpenClaw's does) and which the add-on therefore never sets.
+ */
+declare const SP_VARS: {
+    readonly url: "SP_NATS_URL";
+    readonly creds: "SP_NATS_CREDS";
+    readonly dir: "SCRATCHPAD_DIR";
+    readonly volume: "SCRATCHPAD_VOLUME";
+    readonly creator: "SP_CREATOR";
+    readonly threadId: "SP_THREAD_ID";
+    readonly rootId: "SP_ROOT_ID";
+    readonly callerAccount: "SP_CALLER_ACCOUNT";
+    readonly callerUser: "SP_CALLER_USER";
+    readonly grants: "SP_GRANTS_FILE";
+};
+/** What ScratchPad was resolved to at start. */
+interface ScratchPadSettings {
+    readonly url: string;
+    readonly creds: string;
+    readonly volume: string;
+    /** Unset when neither a setting nor the plugin's state directory gives one. */
+    readonly dir?: string;
+    /**
+     * The file `scripts/sp` records its grants in, beside the workspace:
+     * `<dir>.grants`. Unset without a workspace, and then the grants the
+     * model makes do not entitle anyone to a grant request.
+     */
+    readonly grants?: string;
+}
+type Env = Record<string, string | undefined>;
+/**
+ * ScratchPad's settings as the options, the environment and the plugin's
+ * NATS context give them, or `undefined` when ScratchPad is off: no volume,
+ * or a connection `sp` cannot use, which is logged.
+ */
+declare function resolveScratchPad(ctx: AgentExtensionContext, env: Env): Promise<ScratchPadSettings | undefined>;
+/** Sets the start-time variables. */
+declare function exportScratchPad(settings: ScratchPadSettings, env: Env): void;
+/**
+ * The per-prompt variables, keyed to one request at a time: `enter` sets
+ * them for a request, `leave` clears them only if that request still holds
+ * them, so the end of a prompt never clears the next one's.
+ */
+declare class ServedPromptEnv {
+    #private;
+    private readonly env;
+    constructor(env: Env);
+    enter(request: ServedRequest, scope: TraceScope | undefined): void;
+    leave(request: ServedRequest): void;
+}
+/**
+ * The sp binary an add-on ships for this machine in `skillDir` (its
+ * `skill/scratchpad`), or `SCRATCHPAD_BIN`; `undefined` on a platform it is
+ * not built for. The add-on's own grants run it directly, with the flags
+ * `scripts/sp` would add.
+ */
+declare function spBinary(env: Env, skillDir: string): string | undefined;
+/**
+ * The fabric package's ScratchPad extension, for the plugin's `AgentTools`
+ * and its service, before it can exist: it needs the plugin's `Agents`
+ * client and this agent's address, which arrive in `started()`, after the
+ * factory returned its hooks. Until then it keeps the prompts it serves, to
+ * remember their references once it is built.
+ *
+ * One addition to the extension: the harness's model publishes with
+ * `scripts/sp`, which the extension does not see, and the extension hands on
+ * only what the agent was given. So a reference into its own volume is remembered as
+ * given before the prompt rewrite looks, exactly as an SDK-built agent
+ * remembers what it commits.
+ */
+declare class ScratchPadHandOn implements AgentToolsExtension {
+    #private;
+    readonly requestInterceptor: RequestInterceptor;
+    /**
+     * Builds the extension, once the plugin's client is on the bus. Given the
+     * plugin's service, also answers grant requests for what this agent
+     * published, on the endpoint an SDK-built agent serves them on
+     * (`grantRequestEndpoint`), added through the service's own
+     * `addEndpoint`, since the plugin builds its service before the add-on
+     * could name an extra endpoint. Several instances of one agent share the
+     * work, as an SDK-built agent's do.
+     */
+    start(options: {
+        readonly scratchPad: ScratchPad;
+        readonly agents: Agents;
+        readonly service?: AgentService;
+        readonly logger?: Logger;
+    }): void;
+    discoveryFields(agent: Agent): Record<string, unknown>;
+    beforePrompt(ctx: AgentToolsPromptContext): Promise<AgentToolsPromptRewrite | void>;
+    afterReply(ctx: AgentToolsReplyContext): void;
+}
+/**
+ * The ScratchPad port over the add-on's packaged sp, for its own grants and
+ * the grant requests it answers, with the grants `scripts/sp` recorded.
+ */
+declare function spPort(settings: ScratchPadSettings, creator: string, env: Env, skillDir: string): ScratchPad | undefined;
+/** One grant `scripts/sp` recorded. */
+interface RecordedGrant {
+    readonly expiresAt: number;
+    readonly grantee: Grantee;
+    readonly reference: string;
+}
+/** The grants recorded in `file`; none when it does not exist. Malformed lines are skipped. */
+declare function readRecordedGrants(file: string): RecordedGrant[];
+/**
+ * `port`, whose ledger also holds the grants `scripts/sp` recorded in `file`.
+ * The wrapper grants only to the served prompt's caller, the agent the
+ * harness's model handed its reply to, so each is first-hand, as an
+ * SDK-built agent's grant to the caller of its reply is: its holder may ask
+ * for one more agent. A first-hand grant of the port's own comes first;
+ * the port's answer stands when nothing live is recorded. The reference
+ * must be the one granted on, token for token, as the requester was given
+ * it. `now` is seconds since the epoch.
+ */
+declare function withRecordedGrants(port: ScratchPad, file: string, now?: () => number): ScratchPad;
+
+export { type AgentExtension, type AgentExtensionContext, type AgentExtensionFactory, type AgentExtensionHandles, type AgentExtensionSettings, type BuiltEdgeRecord, type BuiltServedRecord, DEFAULT_EDGE_SUBJECT, DEFAULT_GRANT_REQUEST_TIMEOUT_MS, DEFAULT_GRANT_TTL_S, DEFAULT_READ_LIMIT_BYTES, DEFAULT_SP_BIN, type DurableTrace, EDGE_RECORD_VERSION, EDGE_SUBJECT_OPTION, EDGE_SUBJECT_VAR, type EndReason, type FabricTracing, GRANT_REQUEST_ENDPOINT, type GrantKind, type GrantReply, type GrantRequest, type GrantRequestEndpointOptions, type Grantee, HARNESS_THREAD_ID_MAX, type Harness, type HarnessEvents, LOOP_GUARD_CODE, type LoopGuard, NativeScratchPad, NativeScratchPadError, type NativeScratchPadOptions, type Outcome, type PluginHarness, type PublishOptions, type PublishResult, READS_REFERENCES_KEY, READS_SCRATCHPAD_REFERENCES_FIELD, REFERENCE_PREFIX, ROOT_ID_FIELD, ROOT_ID_HEADER, type ReadBytesOptions, type RecordedGrant, type RecoveryResult, type Reference, type RequestGrantOptions, SCRATCHPAD_BIN_VAR, SCRATCHPAD_DIR_VAR, SCRATCHPAD_GRANT_TTL_S_VAR, SCRATCHPAD_OPTION, SCRATCHPAD_VOLUME_VAR, SERVED_RECORD_REASON_VERSION, SERVED_RECORD_VERSION, SHORT_REFERENCE_PREFIX, SP_VARS, type ScratchPad, type ScratchPadClient, ScratchPadError, ScratchPadExtension, type ScratchPadExtensionOptions, type ScratchPadFromEnvOptions, ScratchPadHandOn, ScratchPadReader, type ScratchPadReaderOptions, type ScratchPadSettings, type ServedPhase, ServedPromptEnv, ServedPublisher, type ServedPublisherOptions, type ServedReason, type ServedRequest, type ServedStatus, type ServedTurn, type ShortReference, type SpCliScratchPadOptions, THREAD_ID_FIELD, THREAD_ID_HEADER, THREAD_ID_HEX_LEN, TOOL_CALL_ID_CONTEXT_KEY, TOOL_CALL_ID_MAX, type TraceIds, type TraceOptions, type TraceRecordCounts, type TraceScope, activeTrace, answerGrantRequest, assertValidTraceOptions, bindActiveTrace, buildEdgeRecord, buildServedRecord, countTraceRecordDropped, countTraceRecordPublished, decodeReference, decodeShortReference, durableHeaders, durableRunId, durableTrace, encodeGrantReply, encodeGrantRequest, encodeReference, exportScratchPad, fabricTracing, findReferences, grantRequestEndpoint, grantSubject, granteeFromIdentity, isThreadId, loopGuard, loopGuardDescription, nativeScratchPad, nativeScratchPadFromEnv, randomThreadId, readRecordedGrants, readsReferences, referenceCreator, removeReferences, requestGrant, resolveEdgeSubject, resolveScratchPad, scratchPadExtension, scratchPadFromEnv, scratchPadReader, servedPublisher, spBinary, spCliScratchPad, spPort, traceHeaders, traceRecordCounts, unixSeconds, validHarnessThreadId, validToolCallId, withDurableTrace, withRecordedGrants };