@theokit/sdk 5.12.1 → 5.14.0

package/dist/sandbox/shell-escape.d.ts

@@ -2,7 +2,19 @@
  * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`
  * command string. `execute` runs via `/bin/sh -c`, so any untrusted value
  * (repo URL, ref, path) MUST be quoted to prevent command injection.
+ */
+/**
+ * Quotes `arg` as one word for POSIX `sh`, for a command line you build yourself and hand to
+ * `SandboxBackend.execute`. A value from outside cannot end the word and start another command,
+ * whatever it holds: quotes, `$()`, backticks, newlines, backslashes. An empty string comes back as
+ * `''`. Quoting does not stop the program you call from reading a leading dash as an option, so put
+ * `--` before the value for one that parses options. The derived helpers and `provisionRepo` use this
+ * same quoter.
  *
- * @internal
+ * Wrap `arg` in single quotes, escaping embedded single quotes (`'\''`). A backslash before a quote,
+ * a backslash or the end is written outside the quotes too (`'\\'`), so the word parses the same
+ * under fish, which reads `\'` and `\\` inside single quotes as escapes, as under sh (B-600): the PTY
+ * runs the sandbox wrap under the user's `$SHELL`. After the first pass an original quote reads
+ * `'\''`, whose own backslash is always followed by `''`, so the second pass never matches it.
  */
-export {};
+export declare function shellEscapePosix(arg: string): string;

package/dist/sandbox/types.d.cts

@@ -52,6 +52,21 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * What a {@link SandboxBackend} states about its outbound network. It is a statement the backend
+ * makes about itself, for a caller that wants to ask before it trusts: this package enforces nothing
+ * from it, and a custom backend is responsible for the claim being true.
+ *
+ * `"unrestricted"` means a command can reach whatever the host can. `"none"` means it cannot reach
+ * the network at all. `"allowlist"` means it can reach only the destinations in `allow`, written as
+ * the backend's own firewall spells them (usually domain names); the field is meaningful only with
+ * that mode. A backend that says nothing leaves `networkPolicy` undefined, which is not the same as
+ * `"unrestricted"`: it means the backend makes no claim either way.
+ */
+export interface SandboxNetworkPolicy {
+    readonly mode: "unrestricted" | "allowlist" | "none";
+    readonly allow?: readonly string[];
+}
 /**
  * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
  * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
@@ -98,16 +113,36 @@ export declare class SandboxNotAvailableError extends TheokitAgentError {
  * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
  * package does not ship — write it against these two methods.
  *
+ * Two optional members let a backend say more about itself. {@link SandboxBackend.networkPolicy}
+ * states its egress: `LocalSandbox` declares `"unrestricted"`, `LinuxSandbox` declares `"none"` when
+ * bubblewrap unshares the network, and a backend that does not override it states nothing. Nothing in
+ * this package enforces an allowlist, so `"allowlist"` is only ever a claim a custom backend makes
+ * for itself. {@link SandboxBackend.dispose} releases what the backend holds, and the owner of the
+ * backend calls it.
+ *
  * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
  * backend whose `execute` is not a POSIX shell must override them as well.
  */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
+    /**
+     * What this backend states about its outbound network, or `undefined` when it states nothing.
+     * Read it to check an isolation claim before trusting a backend; do not read `undefined` as
+     * "unrestricted". A subclass sets it as a field, and it is a statement only: the backend must
+     * enforce it itself.
+     */
+    readonly networkPolicy?: SandboxNetworkPolicy;
     constructor(config?: SandboxConfig);
     abstract execute(command: string, opts?: {
         timeoutMs?: number;
     }): Promise<ExecuteResult>;
     abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    /**
+     * Releases whatever the backend holds, such as a VM or a container. The default does nothing,
+     * which is correct for a backend that holds nothing, so existing subclasses need no change. Safe
+     * to call more than once. The owner of the backend calls it; nothing in this package does.
+     */
+    dispose(): Promise<void>;
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
     glob(pattern: string, cwd?: string): Promise<string[]>;
@@ -141,3 +176,13 @@ export declare abstract class SandboxBackend {
 export type SandboxProvider<Ctx = unknown> = SandboxBackend | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);
 /** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */
 export declare function resolveSandbox<Ctx>(provider: SandboxProvider<Ctx>, ctx: Ctx): Promise<SandboxBackend>;
+/** Codex's three canonical sandbox modes; lives in this leaf module so bwrap.ts and deny-read.ts need not import each other. */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/** Result of probing for bubblewrap. Detection never throws. */
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/sandbox/types.d.ts

@@ -52,6 +52,21 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * What a {@link SandboxBackend} states about its outbound network. It is a statement the backend
+ * makes about itself, for a caller that wants to ask before it trusts: this package enforces nothing
+ * from it, and a custom backend is responsible for the claim being true.
+ *
+ * `"unrestricted"` means a command can reach whatever the host can. `"none"` means it cannot reach
+ * the network at all. `"allowlist"` means it can reach only the destinations in `allow`, written as
+ * the backend's own firewall spells them (usually domain names); the field is meaningful only with
+ * that mode. A backend that says nothing leaves `networkPolicy` undefined, which is not the same as
+ * `"unrestricted"`: it means the backend makes no claim either way.
+ */
+export interface SandboxNetworkPolicy {
+    readonly mode: "unrestricted" | "allowlist" | "none";
+    readonly allow?: readonly string[];
+}
 /**
  * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
  * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
@@ -98,16 +113,36 @@ export declare class SandboxNotAvailableError extends TheokitAgentError {
  * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
  * package does not ship — write it against these two methods.
  *
+ * Two optional members let a backend say more about itself. {@link SandboxBackend.networkPolicy}
+ * states its egress: `LocalSandbox` declares `"unrestricted"`, `LinuxSandbox` declares `"none"` when
+ * bubblewrap unshares the network, and a backend that does not override it states nothing. Nothing in
+ * this package enforces an allowlist, so `"allowlist"` is only ever a claim a custom backend makes
+ * for itself. {@link SandboxBackend.dispose} releases what the backend holds, and the owner of the
+ * backend calls it.
+ *
  * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
  * backend whose `execute` is not a POSIX shell must override them as well.
  */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
+    /**
+     * What this backend states about its outbound network, or `undefined` when it states nothing.
+     * Read it to check an isolation claim before trusting a backend; do not read `undefined` as
+     * "unrestricted". A subclass sets it as a field, and it is a statement only: the backend must
+     * enforce it itself.
+     */
+    readonly networkPolicy?: SandboxNetworkPolicy;
     constructor(config?: SandboxConfig);
     abstract execute(command: string, opts?: {
         timeoutMs?: number;
     }): Promise<ExecuteResult>;
     abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    /**
+     * Releases whatever the backend holds, such as a VM or a container. The default does nothing,
+     * which is correct for a backend that holds nothing, so existing subclasses need no change. Safe
+     * to call more than once. The owner of the backend calls it; nothing in this package does.
+     */
+    dispose(): Promise<void>;
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
     glob(pattern: string, cwd?: string): Promise<string[]>;
@@ -141,3 +176,13 @@ export declare abstract class SandboxBackend {
 export type SandboxProvider<Ctx = unknown> = SandboxBackend | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);
 /** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */
 export declare function resolveSandbox<Ctx>(provider: SandboxProvider<Ctx>, ctx: Ctx): Promise<SandboxBackend>;
+/** Codex's three canonical sandbox modes; lives in this leaf module so bwrap.ts and deny-read.ts need not import each other. */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/** Result of probing for bubblewrap. Detection never throws. */
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/{sdk-agent-4-dXI2GS.d.cts → sdk-agent-DwzHcuxy.d.cts}

@@ -1577,6 +1577,17 @@ interface ToolResultGuardOptions {
     /** Redact common PII patterns (email, phone) in tool-result content. */
     redactPii?: boolean;
 }
+/**
+ * B-564 — how old a tool result may get, in tool rounds, before its content is pruned from the
+ * next LLM request (`SendOptions.pruneToolResults`). Contract type owned by `types/`; the
+ * implementation lives in `internal/agent-loop/prune-tool-results.ts`, which re-exports this.
+ *
+ * @public
+ */
+interface PruneToolResultsOptions {
+    /** Keep the newest `olderThanRounds` tool rounds whole; an integer of at least 1. */
+    olderThanRounds: number;
+}
 /**
  * Lifecycle status of a {@link Run}.
  *
@@ -1868,7 +1879,7 @@ interface SDKUserMessage {
  *
  * ## Which options do I need?
  *
- * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * Twenty-two optional fields with genuinely different audiences, so most callers read all of them to
  * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
  * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
  * have added surface to remove surface, and the harm here is the READING cost, not a representable
@@ -1878,7 +1889,7 @@ interface SDKUserMessage {
  * | If you are… | you want |
  * |---|---|
  * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
- * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `pruneToolResults`, `perToolTimeoutMs` |
  * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
  * | orchestrating agents | `origin`, `task`, `context` |
  * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
@@ -2023,6 +2034,20 @@ interface SendOptions {
      * @public
      */
     toolResultGuard?: ToolResultGuardOptions;
+    /**
+     * B-564 — opt-in pruning of aged tool results. With `{ olderThanRounds: n }`, the content of
+     * every tool result older than `n` tool rounds is replaced by a short stub in each request the
+     * run's agent loop sends (its `toolUseId` and `isError` kept; session compaction is not pruned); the transcript the run keeps, persists and resumes
+     * from stays whole. `olderThanRounds` must be an integer of at least 1, else the send fails
+     * with `ConfigurationError` code `invalid_prune_tool_results` before any provider call.
+     * Undefined = no pruning (the request is unchanged). Pruning trades request size against
+     * prefix-cache reuse: each new round turns one more previously sent result into a stub, so the
+     * request prefix changes from that message onward on providers that cache message prefixes.
+     * The cache-hit cost was not measured.
+     *
+     * @public
+     */
+    pruneToolResults?: PruneToolResultsOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —
@@ -2557,4 +2582,4 @@ interface InvalidateCacheOptions {
     applyNow?: boolean;
 }
 
-export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, ToolCall as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, ResolvedProviderRoute as a7, RunCompactBoundaryEvent as a8, RunCompletionCheckEvent as a9, SDKProvidersManager as aA, SDKRequestMessage as aB, SDKStatusMessage as aC, SDKSystemMessage as aD, SDKTaskMessage as aE, SDKThinkingMessage as aF, SDKToolUseMessage as aG, SDKUserMessage as aH, SDKUserMessageEvent as aI, SendOptions as aJ, ShellCommand as aK, ShellConversationTurn as aL, ShellOutput as aM, ShellOutputDeltaUpdate as aN, StepCompletedUpdate as aO, StepStartedUpdate as aP, StreamToCompletionResult as aQ, SummaryCompletedUpdate as aR, SummaryStartedUpdate as aS, SummaryUpdate as aT, SystemPromptSkillRef as aU, TextDeltaUpdate as aV, ThinkingCompletedUpdate as aW, ThinkingDeltaUpdate as aX, ThinkingMessage as aY, TokenDeltaUpdate as aZ, TokenUsage as a_, RunErrorDetail as aa, RunEvent as ab, RunGitInfo as ac, RunMemoryDegradedEvent as ad, RunPermissionDeniedEvent as ae, RunRateLimitEvent as af, RunStatus as ag, RunTaskCompletedEvent as ah, RunTaskStartedEvent as ai, RunTaskUpdatedEvent as aj, RunTimelineEvent as ak, RunToCompletionOptions as al, RunToCompletionResult as am, RunToolProgressEvent as an, RunTripwireEvent as ao, RunUntilIterator as ap, SDKAgentPlugins as aq, SDKAgentSkillDetail as ar, SDKAgentSkills as as, SDKArtifact as at, SDKAssistantMessage as au, SDKContextManager as av, SDKImage as aw, SDKImageDimension as ax, SDKObjectDelta as ay, SDKPluginMetadata as az, Run as b, ToolCallCompletedUpdate as b0, ToolCallStartedUpdate as b1, ToolResult as b2, ToolResultGuardOptions as b3, ToolUseBlock as b4, TurnEndedUpdate as b5, UserMessage as b6, UserMessageAppendedUpdate as b7, Verdict as b8, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };
+export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, TokenUsage as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, PruneToolResultsOptions as a7, ResolvedProviderRoute as a8, RunCompactBoundaryEvent as a9, SDKPluginMetadata as aA, SDKProvidersManager as aB, SDKRequestMessage as aC, SDKStatusMessage as aD, SDKSystemMessage as aE, SDKTaskMessage as aF, SDKThinkingMessage as aG, SDKToolUseMessage as aH, SDKUserMessage as aI, SDKUserMessageEvent as aJ, SendOptions as aK, ShellCommand as aL, ShellConversationTurn as aM, ShellOutput as aN, ShellOutputDeltaUpdate as aO, StepCompletedUpdate as aP, StepStartedUpdate as aQ, StreamToCompletionResult as aR, SummaryCompletedUpdate as aS, SummaryStartedUpdate as aT, SummaryUpdate as aU, SystemPromptSkillRef as aV, TextDeltaUpdate as aW, ThinkingCompletedUpdate as aX, ThinkingDeltaUpdate as aY, ThinkingMessage as aZ, TokenDeltaUpdate as a_, RunCompletionCheckEvent as aa, RunErrorDetail as ab, RunEvent as ac, RunGitInfo as ad, RunMemoryDegradedEvent as ae, RunPermissionDeniedEvent as af, RunRateLimitEvent as ag, RunStatus as ah, RunTaskCompletedEvent as ai, RunTaskStartedEvent as aj, RunTaskUpdatedEvent as ak, RunTimelineEvent as al, RunToCompletionOptions as am, RunToCompletionResult as an, RunToolProgressEvent as ao, RunTripwireEvent as ap, RunUntilIterator as aq, SDKAgentPlugins as ar, SDKAgentSkillDetail as as, SDKAgentSkills as at, SDKArtifact as au, SDKAssistantMessage as av, SDKContextManager as aw, SDKImage as ax, SDKImageDimension as ay, SDKObjectDelta as az, Run as b, ToolCall as b0, ToolCallCompletedUpdate as b1, ToolCallStartedUpdate as b2, ToolResult as b3, ToolResultGuardOptions as b4, ToolUseBlock as b5, TurnEndedUpdate as b6, UserMessage as b7, UserMessageAppendedUpdate as b8, Verdict as b9, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };

package/dist/{sdk-agent-CTOJlWA_.d.ts → sdk-agent-a3fW1xUK.d.ts}

@@ -1577,6 +1577,17 @@ interface ToolResultGuardOptions {
     /** Redact common PII patterns (email, phone) in tool-result content. */
     redactPii?: boolean;
 }
+/**
+ * B-564 — how old a tool result may get, in tool rounds, before its content is pruned from the
+ * next LLM request (`SendOptions.pruneToolResults`). Contract type owned by `types/`; the
+ * implementation lives in `internal/agent-loop/prune-tool-results.ts`, which re-exports this.
+ *
+ * @public
+ */
+interface PruneToolResultsOptions {
+    /** Keep the newest `olderThanRounds` tool rounds whole; an integer of at least 1. */
+    olderThanRounds: number;
+}
 /**
  * Lifecycle status of a {@link Run}.
  *
@@ -1868,7 +1879,7 @@ interface SDKUserMessage {
  *
  * ## Which options do I need?
  *
- * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * Twenty-two optional fields with genuinely different audiences, so most callers read all of them to
  * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
  * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
  * have added surface to remove surface, and the harm here is the READING cost, not a representable
@@ -1878,7 +1889,7 @@ interface SDKUserMessage {
  * | If you are… | you want |
  * |---|---|
  * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
- * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `pruneToolResults`, `perToolTimeoutMs` |
  * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
  * | orchestrating agents | `origin`, `task`, `context` |
  * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
@@ -2023,6 +2034,20 @@ interface SendOptions {
      * @public
      */
     toolResultGuard?: ToolResultGuardOptions;
+    /**
+     * B-564 — opt-in pruning of aged tool results. With `{ olderThanRounds: n }`, the content of
+     * every tool result older than `n` tool rounds is replaced by a short stub in each request the
+     * run's agent loop sends (its `toolUseId` and `isError` kept; session compaction is not pruned); the transcript the run keeps, persists and resumes
+     * from stays whole. `olderThanRounds` must be an integer of at least 1, else the send fails
+     * with `ConfigurationError` code `invalid_prune_tool_results` before any provider call.
+     * Undefined = no pruning (the request is unchanged). Pruning trades request size against
+     * prefix-cache reuse: each new round turns one more previously sent result into a stub, so the
+     * request prefix changes from that message onward on providers that cache message prefixes.
+     * The cache-hit cost was not measured.
+     *
+     * @public
+     */
+    pruneToolResults?: PruneToolResultsOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —
@@ -2557,4 +2582,4 @@ interface InvalidateCacheOptions {
     applyNow?: boolean;
 }
 
-export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, ToolCall as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, ResolvedProviderRoute as a7, RunCompactBoundaryEvent as a8, RunCompletionCheckEvent as a9, SDKProvidersManager as aA, SDKRequestMessage as aB, SDKStatusMessage as aC, SDKSystemMessage as aD, SDKTaskMessage as aE, SDKThinkingMessage as aF, SDKToolUseMessage as aG, SDKUserMessage as aH, SDKUserMessageEvent as aI, SendOptions as aJ, ShellCommand as aK, ShellConversationTurn as aL, ShellOutput as aM, ShellOutputDeltaUpdate as aN, StepCompletedUpdate as aO, StepStartedUpdate as aP, StreamToCompletionResult as aQ, SummaryCompletedUpdate as aR, SummaryStartedUpdate as aS, SummaryUpdate as aT, SystemPromptSkillRef as aU, TextDeltaUpdate as aV, ThinkingCompletedUpdate as aW, ThinkingDeltaUpdate as aX, ThinkingMessage as aY, TokenDeltaUpdate as aZ, TokenUsage as a_, RunErrorDetail as aa, RunEvent as ab, RunGitInfo as ac, RunMemoryDegradedEvent as ad, RunPermissionDeniedEvent as ae, RunRateLimitEvent as af, RunStatus as ag, RunTaskCompletedEvent as ah, RunTaskStartedEvent as ai, RunTaskUpdatedEvent as aj, RunTimelineEvent as ak, RunToCompletionOptions as al, RunToCompletionResult as am, RunToolProgressEvent as an, RunTripwireEvent as ao, RunUntilIterator as ap, SDKAgentPlugins as aq, SDKAgentSkillDetail as ar, SDKAgentSkills as as, SDKArtifact as at, SDKAssistantMessage as au, SDKContextManager as av, SDKImage as aw, SDKImageDimension as ax, SDKObjectDelta as ay, SDKPluginMetadata as az, Run as b, ToolCallCompletedUpdate as b0, ToolCallStartedUpdate as b1, ToolResult as b2, ToolResultGuardOptions as b3, ToolUseBlock as b4, TurnEndedUpdate as b5, UserMessage as b6, UserMessageAppendedUpdate as b7, Verdict as b8, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };
+export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, TokenUsage as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, PruneToolResultsOptions as a7, ResolvedProviderRoute as a8, RunCompactBoundaryEvent as a9, SDKPluginMetadata as aA, SDKProvidersManager as aB, SDKRequestMessage as aC, SDKStatusMessage as aD, SDKSystemMessage as aE, SDKTaskMessage as aF, SDKThinkingMessage as aG, SDKToolUseMessage as aH, SDKUserMessage as aI, SDKUserMessageEvent as aJ, SendOptions as aK, ShellCommand as aL, ShellConversationTurn as aM, ShellOutput as aN, ShellOutputDeltaUpdate as aO, StepCompletedUpdate as aP, StepStartedUpdate as aQ, StreamToCompletionResult as aR, SummaryCompletedUpdate as aS, SummaryStartedUpdate as aT, SummaryUpdate as aU, SystemPromptSkillRef as aV, TextDeltaUpdate as aW, ThinkingCompletedUpdate as aX, ThinkingDeltaUpdate as aY, ThinkingMessage as aZ, TokenDeltaUpdate as a_, RunCompletionCheckEvent as aa, RunErrorDetail as ab, RunEvent as ac, RunGitInfo as ad, RunMemoryDegradedEvent as ae, RunPermissionDeniedEvent as af, RunRateLimitEvent as ag, RunStatus as ah, RunTaskCompletedEvent as ai, RunTaskStartedEvent as aj, RunTaskUpdatedEvent as ak, RunTimelineEvent as al, RunToCompletionOptions as am, RunToCompletionResult as an, RunToolProgressEvent as ao, RunTripwireEvent as ap, RunUntilIterator as aq, SDKAgentPlugins as ar, SDKAgentSkillDetail as as, SDKAgentSkills as at, SDKArtifact as au, SDKAssistantMessage as av, SDKContextManager as aw, SDKImage as ax, SDKImageDimension as ay, SDKObjectDelta as az, Run as b, ToolCall as b0, ToolCallCompletedUpdate as b1, ToolCallStartedUpdate as b2, ToolResult as b3, ToolResultGuardOptions as b4, ToolUseBlock as b5, TurnEndedUpdate as b6, UserMessage as b7, UserMessageAppendedUpdate as b8, Verdict as b9, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };

package/dist/skills.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk7WARNHWW_cjs = require('./chunk-7WARNHWW.cjs');
+var chunk3UMPP553_cjs = require('./chunk-3UMPP553.cjs');
 require('./chunk-3KIUY67P.cjs');
 require('./chunk-SA6K24NB.cjs');
 require('./chunk-6XQLTQB6.cjs');
@@ -11,15 +11,15 @@ require('./chunk-RNXXYF22.cjs');
 
 Object.defineProperty(exports, "buildSkillsBlock", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.buildSkillsBlock; }
+  get: function () { return chunk3UMPP553_cjs.buildSkillsBlock; }
 });
 Object.defineProperty(exports, "discoverSkills", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.discoverSkills; }
+  get: function () { return chunk3UMPP553_cjs.discoverSkills; }
 });
 Object.defineProperty(exports, "loadSkillInstructions", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.loadSkillInstructions; }
+  get: function () { return chunk3UMPP553_cjs.loadSkillInstructions; }
 });
 //# sourceMappingURL=skills.cjs.map
 //# sourceMappingURL=skills.cjs.map

package/dist/skills.js

@@ -1,4 +1,4 @@
-export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-NHOEXFZT.js';
+export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-2HXTNVLM.js';
 import './chunk-PKRPV3R7.js';
 import './chunk-UKMBRMGT.js';
 import './chunk-Q7UG242V.js';

package/dist/stream-object-AS4YYM4B.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunk2XWAYCFM_cjs = require('./chunk-2XWAYCFM.cjs');
+require('./chunk-PDOXYXWX.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-CEGU5AVD.cjs');
+require('./chunk-RNXXYF22.cjs');
+
+
+
+Object.defineProperty(exports, "StreamObjectError", {
+  enumerable: true,
+  get: function () { return chunk2XWAYCFM_cjs.StreamObjectError; }
+});
+Object.defineProperty(exports, "streamObjectImpl", {
+  enumerable: true,
+  get: function () { return chunk2XWAYCFM_cjs.streamObjectImpl; }
+});
+//# sourceMappingURL=stream-object-AS4YYM4B.cjs.map
+//# sourceMappingURL=stream-object-AS4YYM4B.cjs.map

package/dist/{stream-object-TEEK3CAX.cjs.map → stream-object-AS4YYM4B.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-TEEK3CAX.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-AS4YYM4B.cjs"}

package/dist/stream-object-EKM4WGTI.js

@@ -0,0 +1,7 @@
+export { StreamObjectError, streamObjectImpl } from './chunk-CYWOJA6B.js';
+import './chunk-DFBWYETS.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-TNFOU6SB.js';
+import './chunk-3OY6H3I7.js';
+//# sourceMappingURL=stream-object-EKM4WGTI.js.map
+//# sourceMappingURL=stream-object-EKM4WGTI.js.map

package/dist/{stream-object-R6SMYV4R.js.map → stream-object-EKM4WGTI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-R6SMYV4R.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-EKM4WGTI.js"}

package/dist/stream-object.d.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
 import { StructuredOutputError } from "./errors.js";
-import type { LocalOptions, ModelSelection } from "./types/agent.js";
+import type { BuiltinToolName, LocalOptions, MemorySettings, ModelSelection } from "./types/agent.js";
 import type { ProviderRoutingSettings } from "./types/providers.js";
 /**
  * Options accepted by {@link Agent.streamObject}. Same shape as
@@ -26,6 +26,19 @@ export interface StreamObjectOptions<T extends ZodType> {
      * when the right env key is set under a different provider name.
      */
     providers?: ProviderRoutingSettings;
+    /**
+     * Builtin tools removed from the transient agent's catalogue, forwarded to
+     * {@link AgentOptions.withheldBuiltinTools}. Absent ⇒ unchanged default: the agent holds
+     * `shell`. Pass `["shell"]` for a step that must only produce JSON. The `output` tool is
+     * never withheld.
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    /**
+     * Memory settings for the transient agent, forwarded to {@link AgentOptions.memory}.
+     * Absent ⇒ unchanged default (a session transcript is written). Pass `{ enabled: false }`
+     * for a step that must leave no transcript.
+     */
+    memory?: MemorySettings;
 }
 /**
  * Recursive partial — `T` where every nested field becomes optional.

package/dist/subagents-loader.d.cts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-Cn0sphpA.cjs';
-import './sdk-agent-4-dXI2GS.cjs';
+import { a as AgentDefinition } from './agent-DExqjqYy.cjs';
+import './sdk-agent-DwzHcuxy.cjs';
 import './agent-prims-CZyxfCmS.cjs';
 import 'zod';
 import './errors-base-B5g01neU.cjs';

package/dist/subagents-loader.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-CVzDy_Oj.js';
-import './sdk-agent-CTOJlWA_.js';
+import { a as AgentDefinition } from './agent-Dfw3VsIX.js';
+import './sdk-agent-a3fW1xUK.js';
 import './agent-prims-CZyxfCmS.js';
 import 'zod';
 import './errors-base-B5g01neU.js';

package/dist/types/agent.d.ts

@@ -344,6 +344,12 @@ export interface SkillsSettings {
      * default `<cwd>/.theokit/skills`. Absent ⇒ the default root.
      */
     skillsDir?: string;
+    /**
+     * B-546 — directories (each containing `<name>/SKILL.md`) an application ships inside its own
+     * package. They are read AFTER the project roots and plugin bundles, so a workspace skill of the
+     * same name always wins, and they are kept even when `skillsDir` replaces the default roots.
+     */
+    bundledDirs?: string[];
     /**
      * M22 — code-defined skills (from `createSkill`) merged with the discovered ones. An inline skill
      * overrides a discovered file skill of the same name.
@@ -581,7 +587,14 @@ export interface AgentOptions {
      *
      * - **Named-enable settings** — `{ enabled: ["name", ...] }`. Selects which
      *   file-discovered plugin providers (under `.theokit/plugins/`) are active.
-     *   Plugin sources must also be active via `local.settingSources`.
+     *   Plugin sources must also be active via `local.settingSources`. A folder
+     *   under `<cwd>/.theokit/plugins/` whose `PLUGIN.md` names an `entry` has
+     *   that entry imported and its default export (a `kind: "general"` plugin)
+     *   registered, but only when the folder's absolute realpath is listed in
+     *   `~/.theokit/plugins/trusted-workspace-plugins.json` (a JSON array, read on
+     *   each `Agent.create`). The provider trust list never authorizes a workspace
+     *   folder. An untrusted folder is listed and never imported; foreign roots
+     *   are never imported.
      * - **Code `Plugin` objects** — an array of `Plugin` instances, e.g.
      *   `plugins: [Handoff.asPlugin({ ... })]`. These are registered directly by
      *   the runtime (`extractCodePlugins`); no `settingSources` entry is needed.

package/dist/types/run.d.ts

@@ -24,6 +24,17 @@ export interface ToolResultGuardOptions {
     /** Redact common PII patterns (email, phone) in tool-result content. */
     redactPii?: boolean;
 }
+/**
+ * B-564 — how old a tool result may get, in tool rounds, before its content is pruned from the
+ * next LLM request (`SendOptions.pruneToolResults`). Contract type owned by `types/`; the
+ * implementation lives in `internal/agent-loop/prune-tool-results.ts`, which re-exports this.
+ *
+ * @public
+ */
+export interface PruneToolResultsOptions {
+    /** Keep the newest `olderThanRounds` tool rounds whole; an integer of at least 1. */
+    olderThanRounds: number;
+}
 /**
  * Lifecycle status of a {@link Run}.
  *
@@ -315,7 +326,7 @@ export interface SDKUserMessage {
  *
  * ## Which options do I need?
  *
- * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * Twenty-two optional fields with genuinely different audiences, so most callers read all of them to
  * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
  * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
  * have added surface to remove surface, and the harm here is the READING cost, not a representable
@@ -325,7 +336,7 @@ export interface SDKUserMessage {
  * | If you are… | you want |
  * |---|---|
  * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
- * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `pruneToolResults`, `perToolTimeoutMs` |
  * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
  * | orchestrating agents | `origin`, `task`, `context` |
  * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
@@ -470,6 +481,20 @@ export interface SendOptions {
      * @public
      */
     toolResultGuard?: ToolResultGuardOptions;
+    /**
+     * B-564 — opt-in pruning of aged tool results. With `{ olderThanRounds: n }`, the content of
+     * every tool result older than `n` tool rounds is replaced by a short stub in each request the
+     * run's agent loop sends (its `toolUseId` and `isError` kept; session compaction is not pruned); the transcript the run keeps, persists and resumes
+     * from stays whole. `olderThanRounds` must be an integer of at least 1, else the send fails
+     * with `ConfigurationError` code `invalid_prune_tool_results` before any provider call.
+     * Undefined = no pruning (the request is unchanged). Pruning trades request size against
+     * prefix-cache reuse: each new round turns one more previously sent result into a stub, so the
+     * request prefix changes from that message onward on providers that cache message prefixes.
+     * The cache-hit cost was not measured.
+     *
+     * @public
+     */
+    pruneToolResults?: PruneToolResultsOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —

package/dist/workflow-as-tool.d.ts

@@ -14,13 +14,14 @@
  * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
  * EXPLAINING the trap quoted the tag verbatim and re-armed it.
  */
-import type { ZodType, z } from "zod";
+import { type ZodType, z } from "zod";
 import { TheokitAgentError } from "./errors.js";
 import type { CustomTool } from "./types/agent.js";
-import type { WorkflowRun } from "./types/workflow.js";
+import type { WorkflowResumeOptions, WorkflowRun } from "./types/workflow.js";
 /**
- * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
- * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
+ * Raised by a {@link workflowAsTool} or {@link workflowResumeTool} tool when the
+ * run does not reach `status: "completed"` (a step failed, the run was cancelled,
+ * or it suspended without `reportSuspended`, which returns a report instead).
  * The dispatch converts it to a `tool_result(isError)`.
  *
  * @public
@@ -47,6 +48,22 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
     description: string;
     /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
     inputSchema: T;
+    /**
+     * When `true`, a run that suspends returns `{"status":"suspended","runId":…,"stepId":…}` instead of
+     * raising {@link WorkflowToolError}, so the model can hand the run id to a
+     * {@link workflowResumeTool}. The report carries ids only, never the suspended payload; `stepId` is
+     * `null` for a run that carries no step result. Default `false`.
+     */
+    reportSuspended?: boolean;
+}
+/** Spec for {@link workflowResumeTool}. */
+export interface WorkflowResumeToolSpec {
+    /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
+    name: string;
+    /** Description surfaced to the LLM — when the agent should resume a suspended run. */
+    description: string;
+    /** Report a run that suspends again instead of raising, as in {@link WorkflowAsToolSpec}. */
+    reportSuspended?: boolean;
 }
 /**
  * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
@@ -54,7 +71,8 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
  * The handler validates the model's args against `spec.inputSchema`, runs the
  * workflow, and returns its output (a string as-is, else JSON). A run that does not
  * reach `status: "completed"` raises a typed {@link WorkflowToolError} (workflow
- * step errors do NOT throw — they surface via `run.status === "failed"`).
+ * step errors do NOT throw — they surface via `run.status === "failed"`), except a
+ * suspended run with `spec.reportSuspended`, which returns the suspended report.
  *
  * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
  * `Workflow` class directly.
@@ -64,3 +82,19 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
 export declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
     run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
 }, spec: WorkflowAsToolSpec<T>): CustomTool;
+/**
+ * B-677 — a {@link CustomTool} that resumes a suspended run of `workflow` by its run id, with an
+ * optional payload validated against the suspend step's schema. It returns the run's output like
+ * {@link workflowAsTool}; a run that suspends again keeps the same run id and is reported or raised
+ * per `spec.reportSuspended`. Snapshot errors (`WorkflowSnapshotNotFoundError` for an unknown or
+ * already-resumed id, `WorkflowResumeWorkflowMismatchError` for a run another workflow suspended,
+ * `WorkflowResumeStepNotFoundError` when `workflow` lacks the suspended step) and payload validation
+ * errors propagate to the dispatch.
+ *
+ * `workflow` must be the committed instance from `Workflow.create().commit()`. The default snapshot
+ * store is in memory and process-local: a host that resumes across processes configures a persistent
+ * backend. This tool resumes any run id it is given; deciding who may approve a run is the host's job.
+ *
+ * @public
+ */
+export declare function workflowResumeTool(workflow: WorkflowResumeOptions["workflow"], spec: WorkflowResumeToolSpec): CustomTool;

package/dist/workflow-errors.d.ts

@@ -137,6 +137,22 @@ export declare class WorkflowResumeStepNotFoundError extends TheokitAgentError {
     readonly name = "WorkflowResumeStepNotFoundError";
     constructor(stepId: string, workflowName: string);
 }
+/**
+ * Thrown by `Workflow.resume()` (and so by a `workflowResumeTool` tool) when the snapshot for the run
+ * id was written by a workflow of another name. The snapshot is left in the store, so the workflow
+ * that suspended the run can still resume it.
+ *
+ * Without this check the default store, one process-global memory store, would let workflow B run
+ * its own tail on workflow A's accumulated input whenever both declare a step with the suspended id.
+ * `name` is a label, not an identity: two workflows that share a name are not told apart here.
+ */
+export declare class WorkflowResumeWorkflowMismatchError extends TheokitAgentError {
+    readonly runId: string;
+    readonly snapshotWorkflowName: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeWorkflowMismatchError";
+    constructor(runId: string, snapshotWorkflowName: string, workflowName: string);
+}
 /**
  * Aggregate failure from parallel branches.
  *