@synadia-ai/agent-fabric 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 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 { AgentId, PromptInterceptor, PromptOptions, QueryEvent, StreamMessage, PromptStream, Agents, Agent, Logger, AgentToolsExtension, SenderInfo, AgentToolsPromptContext, AgentToolsPromptRewrite, AgentToolsReplyContext, NatsConnectionSource } from '@synadia-ai/agents';
 import { NatsConnection } from '@nats-io/nats-core';
 
 declare const EDGE_RECORD_VERSION = 1;
@@ -165,6 +165,123 @@ interface FabricTracing {
  */
 declare function fabricTracing(options?: TraceOptions): FabricTracing;
 
+/** The inbox prefix a caller's permissions allow it to receive on. */
+declare const CALLER_INBOX_PREFIX = "_INBOX.agents";
+/** What `ask()` replies to a question from the agent when no `onQuery` is given. */
+declare const CANNOT_ANSWER = "The caller is a command line and cannot answer; continue with your best judgement.";
+/** How long `list()` and `find()` listen for agents, by default. */
+declare const DEFAULT_DISCOVER_TIMEOUT_MS = 1000;
+/** The variables {@link fabricCallerFromEnv} reads. */
+declare const NATS_URL_VAR = "NATS_URL";
+declare const NATS_CREDS_VAR = "NATS_CREDS";
+/**
+ * Why a caller could not be set up, could not find its agent, or has no
+ * root for a prompt: `config` (a missing or invalid setting), `connect`
+ * (no connection), `identity` (the server would not say who the creds
+ * file is), `not-found`, `ambiguous`, `not-sent` (the prompt ended before
+ * it went out, so it has no root).
+ */
+type FabricCallerErrorReason = "config" | "connect" | "identity" | "not-found" | "ambiguous" | "not-sent";
+/** A caller's own error: a missing setting, no connection, no identity, or no such agent. */
+declare class FabricCallerError extends Error {
+    readonly reason: FabricCallerErrorReason;
+    constructor(reason: FabricCallerErrorReason, message: string);
+}
+interface FabricCallerOptions {
+    /** The path to the creds file. */
+    readonly creds: string;
+    /**
+     * The server's URL, as the console showed it next to the creds file.
+     * Default: `NATS_URL`. There is no built-in default.
+     */
+    readonly url?: string;
+    /** The client's name, on the connection and in its identity. */
+    readonly name?: string;
+    /** Where the edge records go; `null` publishes none. Default: tracing's. */
+    readonly edgeSubject?: TraceOptions["edgeSubject"];
+}
+/** A prompt on its way: its stream, and the root of the task it starts. */
+interface CallerPrompt {
+    /** The SDK's `PromptStream`, passed through: iterate it for the reply. */
+    readonly stream: CallerStream;
+    /**
+     * The root id of the task the prompt starts. Resolves at the stream's
+     * first iteration, before any chunk arrives; await it after iteration
+     * has begun, never before. Rejects with a {@link FabricCallerError}
+     * (`not-sent`), or the stream's own error, when the prompt ends before
+     * it goes out: cancelled, refused before it was sent, or failed.
+     */
+    readonly rootId: Promise<string>;
+}
+/**
+ * The SDK's `PromptStream`, with the prompt's root settled when iteration
+ * ends or fails before the prompt went out. The messages are the SDK's,
+ * unchanged.
+ */
+declare class CallerStream implements AsyncIterable<StreamMessage> {
+    #private;
+    constructor(inner: PromptStream, sink: RootSink);
+    /** The subject the prompt is published to. */
+    get subject(): string;
+    /** Stop the stream, as `PromptStream.cancel()`. */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<StreamMessage>;
+}
+interface AskOptions extends PromptOptions {
+    /**
+     * Answers a question the agent asks mid-reply. Without it, or when it
+     * answers with nothing but whitespace, the agent is told the caller
+     * cannot answer and goes on.
+     */
+    readonly onQuery?: (query: QueryEvent) => string | Promise<string>;
+}
+/** The whole reply to a prompt, and the root of the task it started. */
+interface CallerReply {
+    readonly text: string;
+    readonly rootId: string;
+}
+interface FabricCaller {
+    /** The SDK's client, for anything beyond. */
+    readonly agents: Agents;
+    /** The URL the caller connected to. */
+    readonly url: string;
+    /** The agents on the fabric. */
+    list(opts?: {
+        readonly timeoutMs?: number;
+    }): Promise<Agent[]>;
+    /**
+     * One agent: by its prompt address, else by its kind when exactly one
+     * agent has it. Throws {@link FabricCallerError} naming what is there.
+     */
+    find(who: string, opts?: {
+        readonly timeoutMs?: number;
+    }): Promise<Agent>;
+    /**
+     * Prompt an agent: an address, a kind, or an `Agent` this caller's
+     * `list()` or `find()` returned.
+     */
+    prompt(who: string | Agent, text: string, options?: PromptOptions): Promise<CallerPrompt>;
+    /** Prompt an agent and wait for the whole reply. */
+    ask(who: string | Agent, text: string, options?: AskOptions): Promise<CallerReply>;
+    /** Close the client and the connection, then wipe the credentials. */
+    close(): Promise<void>;
+}
+/** Settles a prompt's root once: the first call wins. Internal. */
+interface RootSink {
+    resolve(rootId: string): void;
+    reject(err: unknown): void;
+}
+/** Connect a caller with a creds file. */
+declare function fabricCaller(options: FabricCallerOptions): Promise<FabricCaller>;
+/** {@link fabricCaller} from `NATS_URL` and `NATS_CREDS`. */
+declare function fabricCallerFromEnv(options?: Omit<FabricCallerOptions, "creds" | "url">): Promise<FabricCaller>;
+/**
+ * The rule {@link FabricCaller.find} applies: the agent whose prompt address
+ * is `who`, else the one agent of kind `who`; otherwise an error that names
+ * what is there.
+ */
+declare function pickAgent(found: ReadonlyArray<Agent>, who: string): Agent;
+
 /**
  * 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.
@@ -610,7 +727,9 @@ interface SpCliScratchPadOptions {
      * deployment provisions it for the agent's account and user; the first
      * commit creates it.
      */
-    readonly volume: string;
+    readonly volume?: string;
+    /** Exact public creation descriptor, imported by sp init. Requires a persistent dir. */
+    readonly bootstrapFile?: 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
@@ -662,6 +781,7 @@ declare class ScratchPadError extends Error {
 declare function spCliScratchPad(options: SpCliScratchPadOptions): ScratchPadClient;
 /** The variables {@link scratchPadFromEnv} reads. */
 declare const SCRATCHPAD_VOLUME_VAR = "SCRATCHPAD_VOLUME";
+declare const SCRATCHPAD_BOOTSTRAP_FILE_VAR = "SCRATCHPAD_BOOTSTRAP_FILE";
 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";
@@ -677,7 +797,7 @@ interface ScratchPadFromEnvOptions {
 }
 /**
  * The agent's ScratchPad as the environment configures it, or `undefined`
- * when `SCRATCHPAD_VOLUME` is unset: ScratchPad off. Reads
+ * when both `SCRATCHPAD_VOLUME` and `SCRATCHPAD_BOOTSTRAP_FILE` are unset. 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
@@ -712,7 +832,7 @@ interface LoopGuard {
 }
 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"];
+declare const CODES: readonly ["ok", "invalid", "unauthenticated", "denied", "not_found", "exists", "conflict", "fenced", "generation_retired", "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 {
@@ -766,6 +886,7 @@ interface Command {
     base: Head;
     root: ContentID;
     trace: Trace;
+    remove_path?: string;
     retention: RetentionIntent;
 }
 interface Receipt {
@@ -815,6 +936,68 @@ interface VolumeView {
     writers: WriterSlot[];
     retentions: RetentionSlot[];
     grants: GrantSlot[];
+    lifetime?: LifetimeView;
+}
+interface AdmissionBinding {
+    slot: number;
+    generation: number;
+    operation_id: string;
+}
+interface LifetimeView {
+    admission: AdmissionBinding;
+    phase: "active" | "shrinking" | "expiring";
+    expires_at: number;
+    grace_until: number;
+    max_lease_seconds: number;
+    grace_seconds: number;
+    recovery_reads: boolean;
+    reserve_objects: number;
+    reserve_bytes: number;
+}
+interface RenewRequest {
+    target: Target;
+    until: number;
+}
+interface RemovalRequest {
+    target: Target;
+    command: Command;
+}
+interface RemovalPlan extends RemovalRequest {
+    slot: number;
+    generation: number;
+    sequence: number;
+    added_objects: number;
+    added_bytes: number;
+}
+interface VolumeReleaseRequest {
+    target: Target;
+    operation_id: string;
+    end_promises: boolean;
+}
+interface ReleaseEffects {
+    objects: number;
+    bytes: number;
+    retentions: number;
+    read_grants: number;
+    access_slots: number;
+    references: number;
+}
+interface VolumeReleasePlan {
+    request: VolumeReleaseRequest;
+    incarnation: string;
+    slot: number;
+    generation: number;
+    sequence: number;
+    head: Head;
+    effects: ReleaseEffects;
+}
+interface VolumeReleaseResult {
+    target: Target;
+    slot: number;
+    generation: number;
+    operation_id: string;
+    disposed: boolean;
+    capacity_returned: boolean;
 }
 interface Limits {
     object_bytes: number;
@@ -830,6 +1013,7 @@ interface ReservedScope {
     volume: string;
     objects: number;
     bytes: number;
+    admission?: AdmissionBinding;
 }
 interface Info {
     principal: Principal;
@@ -875,6 +1059,7 @@ interface PutRequest {
 interface CreateRequest {
     volume: string;
     action: Action;
+    admission?: AdmissionBinding;
 }
 interface PublishRequest {
     target: Target;
@@ -1046,6 +1231,11 @@ declare class ScratchPadTransport {
     private view;
     info(options?: RequestOptions): Promise<Info>;
     createVolume(request: CreateRequest, options?: RequestOptions): Promise<VolumeView>;
+    renewLease(request: RenewRequest, options?: RequestOptions): Promise<VolumeView>;
+    planRemoval(request: RemovalRequest, options?: RequestOptions): Promise<RemovalPlan>;
+    applyRemoval(plan: RemovalPlan, options?: RequestOptions): Promise<Receipt>;
+    planVolumeRelease(request: VolumeReleaseRequest, options?: RequestOptions): Promise<VolumeReleasePlan>;
+    applyVolumeRelease(plan: VolumeReleasePlan, options?: RequestOptions): Promise<VolumeReleaseResult>;
     getVolume(target: Target, options?: RequestOptions): Promise<VolumeView>;
     prepare(request: PrepareRequest, options?: RequestOptions): Promise<PrepareResult>;
     putPrepared(request: PutRequest, data: Uint8Array, options?: RequestOptions): Promise<void>;
@@ -1129,7 +1319,10 @@ declare class WorkspaceStore {
 interface NativeScratchPadOptions extends ScratchPadReaderOptions {
     /** Private directory on a persistent local filesystem. One client owns it at a time. */
     dir: string;
-    volume: string;
+    /** Required unless bootstrapFile supplies the exact volume. */
+    volume?: string;
+    /** Public descriptor file. Never a credentials file or an adoption target. */
+    bootstrapFile?: string;
     /** Prompt address used only to route Fabric grant requests. It is not authentication. */
     creator: string;
     ttlSeconds?: number;
@@ -1143,10 +1336,16 @@ interface PublishResult {
     reference: string;
     receipt: Receipt;
 }
+/** Capacity returned can be known even when this release request's acceptance is unknown. */
+type VolumeReleaseOutcome = VolumeReleaseResult & {
+    acceptance_unknown?: true;
+};
 interface RecoveryResult {
     kind: string;
     reference?: string;
     receipt?: Receipt;
+    volume?: VolumeView;
+    release?: VolumeReleaseOutcome;
 }
 interface Publication {
     kind: "publish";
@@ -1172,7 +1371,18 @@ type Control = {
     kind: "close" | "apply";
     request: MaintenanceRequest;
 };
-type Pending = Publication | Control | {
+type Lifecycle = {
+    kind: "renew";
+    request: RenewRequest;
+} | {
+    kind: "remove";
+    plan: RemovalPlan;
+} | {
+    kind: "volume_release";
+    plan: VolumeReleasePlan;
+    fence_accepted?: true;
+};
+type Pending = Publication | Control | Lifecycle | {
     kind: "reset";
     writer: Writer;
 };
@@ -1182,16 +1392,22 @@ interface State {
     volume: string;
     creator: string;
     creation: Action;
+    admission?: AdmissionBinding;
     target?: Target;
     writer?: Writer;
     next: number;
     pending?: Pending;
+    renewal?: RenewRequest;
     last?: PublishResult & {
         path: string;
         ttl: number;
         resolved?: ResolvedReference;
     };
     grants: Granted[];
+    removal?: Receipt;
+    disposal?: VolumeReleaseResult;
+    disposal_plan?: VolumeReleasePlan;
+    release_acceptance_unknown?: true;
 }
 /** A native writer and Fabric adapter. It borrows the caller's authenticated connection. */
 declare class NativeScratchPad extends ScratchPadReader implements ScratchPadClient {
@@ -1202,7 +1418,7 @@ declare class NativeScratchPad extends ScratchPadReader implements ScratchPadCli
     private tail;
     private closing;
     private closePromise?;
-    constructor(transport: ScratchPadTransport, store: WorkspaceStore, state: State, scope: ReservedScope, ttl: number);
+    constructor(transport: ScratchPadTransport, store: WorkspaceStore, state: State, scope: ReservedScope | undefined, ttl: number);
     private run;
     private save;
     private change;
@@ -1219,6 +1435,26 @@ declare class NativeScratchPad extends ScratchPadReader implements ScratchPadCli
         volume: VolumeView;
         pending?: string;
     }>;
+    /** Save an absolute deadline before sending it. Retries never extend it implicitly. */
+    renewLease(until: number): Promise<VolumeView>;
+    private resumeRenewal;
+    /** Read-only plan for an initialized writer. The caller chooses the path to remove. */
+    planRemoval(path: string, options: {
+        operationId: string;
+        trace?: TraceIds;
+    }): Promise<RemovalPlan>;
+    applyRemoval(plan: RemovalPlan): Promise<Receipt>;
+    /** Lists every promise affected. EndPromises must be explicitly true to authorize release. */
+    planVolumeRelease(options: {
+        operationId: string;
+        endPromises?: boolean;
+    }): Promise<VolumeReleasePlan>;
+    applyVolumeRelease(plan: VolumeReleasePlan): Promise<VolumeReleaseOutcome>;
+    private beginLifecycle;
+    private lifecycle;
+    private releaseFenced;
+    private releaseOutcome;
+    private finishRelease;
     recover(): Promise<RecoveryResult>;
     private recoverPending;
     publishBytes(bytes: Uint8Array, path: string, options: PublishOptions): Promise<PublishResult>;
@@ -1244,7 +1480,7 @@ declare class NativeScratchPad extends ScratchPadReader implements ScratchPadCli
 }
 /** 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. */
+/** A volume or bootstrap file enables the native client on its existing connection. */
 declare function nativeScratchPadFromEnv(env: Readonly<Record<string, string | undefined>>, options: ScratchPadReaderOptions & {
     creator: string;
 }): Promise<NativeScratchPad | undefined>;
@@ -1261,6 +1497,17 @@ declare class NativeScratchPadError extends Error {
     });
 }
 
+/** The descriptor selects an exact creation request; it supplies no authority. */
+interface ScratchPadBootstrap {
+    version: 1;
+    principal: Principal;
+    volume: string;
+    admission: AdmissionBinding;
+    creation: Action;
+}
+declare const MAX_BOOTSTRAP_BYTES = 4096;
+declare function decodeScratchPadBootstrap(data: Uint8Array | string): ScratchPadBootstrap;
+
 /** 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. */
@@ -1417,6 +1664,7 @@ declare const SP_VARS: {
     readonly creds: "SP_NATS_CREDS";
     readonly dir: "SCRATCHPAD_DIR";
     readonly volume: "SCRATCHPAD_VOLUME";
+    readonly bootstrapFile: "SCRATCHPAD_BOOTSTRAP_FILE";
     readonly creator: "SP_CREATOR";
     readonly threadId: "SP_THREAD_ID";
     readonly rootId: "SP_ROOT_ID";
@@ -1429,6 +1677,7 @@ interface ScratchPadSettings {
     readonly url: string;
     readonly creds: string;
     readonly volume: string;
+    readonly bootstrapFile?: string;
     /** Unset when neither a setting nor the plugin's state directory gives one. */
     readonly dir?: string;
     /**
@@ -1526,4 +1775,4 @@ declare function readRecordedGrants(file: string): RecordedGrant[];
  */
 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 };
+export { type AdmissionBinding, type AgentExtension, type AgentExtensionContext, type AgentExtensionFactory, type AgentExtensionHandles, type AgentExtensionSettings, type AskOptions, type BuiltEdgeRecord, type BuiltServedRecord, CALLER_INBOX_PREFIX, CANNOT_ANSWER, type CallerPrompt, type CallerReply, CallerStream, DEFAULT_DISCOVER_TIMEOUT_MS, 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 FabricCaller, FabricCallerError, type FabricCallerErrorReason, type FabricCallerOptions, 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 LifetimeView, type LoopGuard, MAX_BOOTSTRAP_BYTES, NATS_CREDS_VAR, NATS_URL_VAR, 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 ReleaseEffects, type RemovalPlan, type RemovalRequest, type RenewRequest, type RequestGrantOptions, SCRATCHPAD_BIN_VAR, SCRATCHPAD_BOOTSTRAP_FILE_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 ScratchPadBootstrap, 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, type VolumeReleaseOutcome, type VolumeReleasePlan, type VolumeReleaseRequest, type VolumeReleaseResult, activeTrace, answerGrantRequest, assertValidTraceOptions, bindActiveTrace, buildEdgeRecord, buildServedRecord, countTraceRecordDropped, countTraceRecordPublished, decodeReference, decodeScratchPadBootstrap, decodeShortReference, durableHeaders, durableRunId, durableTrace, encodeGrantReply, encodeGrantRequest, encodeReference, exportScratchPad, fabricCaller, fabricCallerFromEnv, fabricTracing, findReferences, grantRequestEndpoint, grantSubject, granteeFromIdentity, isThreadId, loopGuard, loopGuardDescription, nativeScratchPad, nativeScratchPadFromEnv, pickAgent, randomThreadId, readRecordedGrants, readsReferences, referenceCreator, removeReferences, requestGrant, resolveEdgeSubject, resolveScratchPad, scratchPadExtension, scratchPadFromEnv, scratchPadReader, servedPublisher, spBinary, spCliScratchPad, spPort, traceHeaders, traceRecordCounts, unixSeconds, validHarnessThreadId, validToolCallId, withDurableTrace, withRecordedGrants };