@theokit/sdk 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 5.15.0
+
+### Minor Changes
+
+- [#913](https://github.com/usetheokit/theokit-sdk/pull/913) [`f944093`](https://github.com/usetheokit/theokit-sdk/commit/f9440934f33df86054a24a33120d40f7028789ec) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - `@theokit/sdk/sandbox` ships `DockerSandbox`, a `SandboxBackend` that runs each command in a
+  throwaway container with a read-only root filesystem, no network by default, dropped capabilities and
+  the workspace as the only writable mount, so a shell command cannot write outside its workspace.
+
+- [#942](https://github.com/usetheokit/theokit-sdk/pull/942) [`ccaac78`](https://github.com/usetheokit/theokit-sdk/commit/ccaac78d735e0bbd6b7cb91fcfb019fbb0492d35) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - `McpStdioServerConfig` and `McpHttpServerConfig` accept `sequential: true` ([#932](https://github.com/usetheokit/theokit-sdk/issues/932)). The calls a model makes to that server's tools in one step then run one at a time, in the order the model listed them, and the results still come back in call order. Calls to other servers or to non-MCP tools in the same step are not held behind them. Without the option the calls still run at once. Use it for a stateful server such as Playwright MCP, where a snapshot must wait for the navigation before it.
+
+- [#879](https://github.com/usetheokit/theokit-sdk/pull/879) [`de5c7bd`](https://github.com/usetheokit/theokit-sdk/commit/de5c7bdc65c6e9b01b1aa02c84069bfc00e03edf) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - New `SqliteSessionStore` (exported from `@theokit/sdk` and `@theokit/sdk/persistence`): a `SessionStore` backed by one SQLite file, passed as `local.sessionStore`. `Agent.transcript`, `injectSessionTurn` and `compact` now read from the agent's configured `local.sessionStore` instead of always opening the JSONL file.
+
+### Patch Changes
+
+- [#905](https://github.com/usetheokit/theokit-sdk/pull/905) [`418b27c`](https://github.com/usetheokit/theokit-sdk/commit/418b27ceed5931bdce846b743f1e348df6ae2f46) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - `registerProvider` lowercases a profile's name and aliases, and `getProviderProfile` looks names up
+  in lowercase, so a profile registered as `AcmeAI` with alias `AcmeX` is reached by routes naming
+  either. This replaces the router's "register it in lowercase" errors for mixed-case names and
+  aliases (their two tests now assert routing instead), since such a registration can no longer occur.
+
+- [#896](https://github.com/usetheokit/theokit-sdk/pull/896) [`419ba63`](https://github.com/usetheokit/theokit-sdk/commit/419ba631cb248ec6ab8e9e8432aee26b1a93b618) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - `skills.enabled` now restricts the local runtime: a skill not named in it is neither listed nor readable.
+
+- [#940](https://github.com/usetheokit/theokit-sdk/pull/940) [`7f21de1`](https://github.com/usetheokit/theokit-sdk/commit/7f21de1b73d9fd62c4d6f26f220b87a7b8540dfe) Thanks [@aifactory-paulohenriquevn](https://github.com/apps/aifactory-paulohenriquevn)! - Correction to the 5.12.0 note on malformed chat-completions `prompt_tokens`: the dropped count is left out of the per-call `LlmFinish` and no input budget event is emitted for it, and the SDK writes `provider reported an unusable inputTokens (…)` to the diagnostics sink. `RunResult.usage` and `usage.requests[]` still read that count as `inputTokens: 0`, because `TokenUsage.inputTokens` is a required number; only a consumer with a diagnostics sink can tell a dropped count from a real zero. The diagnostic prints `NaN` in place of the value the provider sent.
+
 ## 5.14.0
 
 ### Minor Changes

package/dist/{agent-Dfw3VsIX.d.ts → agent-B6C9i_qu.d.ts}

@@ -1,214 +1,7 @@
-import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aV as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-a3fW1xUK.js';
+import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aW as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-CnwPODYH.js';
+import { a as SessionStore } from './session-store-Dh07jr9N.js';
 import { M as ModelSelection, C as CustomTool, P as PermissionMode } from './agent-prims-CZyxfCmS.js';
 
-/**
- * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
- * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * `SessionRecord` — the native on-disk transcript record shape (SE40).
- *
- * The theokit session format IS the Claude Code record shape: a
- * `uuid`/`parentUuid` DAG of records with structured
- * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
- * pluggable {@link SessionStore} seam operates over.
- *
- * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
- * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
- * re-exports it for back-compat while owning the record builders + reader.
- *
- * @public
- */
-/** A content block inside {@link TranscriptMessage}. */
-type TranscriptBlock = {
-    type: "text";
-    text: string;
-} | {
-    type: "thinking";
-    thinking?: string;
-    signature?: string;
-} | {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: unknown;
-} | {
-    type: "tool_result";
-    tool_use_id: string;
-    content: unknown;
-    is_error?: boolean;
-};
-/**
- * The message body of a {@link SessionRecord}.
- *
- * **It is NOT called `SessionMessage`** — that name already exists in
- * `internal/session/session-types.ts` with the shape `{role, text}`, incompatible with this one.
- * Reusing an exported name for a new shape is
- * precisely the silent break M91 cost two patches to undo.
- *
- * Parsing from disk stays **tolerant** (`readTranscript` skips a malformed line): what changes here
- * is the **type**, not leniency — records written by earlier versions stay readable.
- *
- * @public
- */
-interface TranscriptMessage {
-    role: "user" | "assistant";
-    content: TranscriptBlock[];
-    /**
-     * The three fields below appear **only** on the assistant record, and come from the writer
-     * (`SessionTranscript.appendAssistant`). Declared optional because the user record does not carry
-     * them — measured in the writer itself, not assumed.
-     */
-    id?: string;
-    type?: "message";
-    model?: string;
-}
-/**
- * One transcript record — a single line of the session JSONL file, and the unit the pluggable
- * `SessionStore` seam reads and writes.
- *
- * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
- * and is `null` at the root. Thread a session by following those links; a reader that assumes file
- * order is linear will mis-thread one that branched.
- *
- * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
- * so it is optional even on records you would expect to be conversational, and `type` is what tells
- * you which you are holding.
- *
- * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
- * Every record you receive is well-formed, but the file may have contained more than you got back,
- * so this is not the type to use for an exact-count audit of what was written.
- *
- * @public
- */
-interface SessionRecord {
-    type: "user" | "assistant" | "system";
-    uuid: string;
-    parentUuid: string | null;
-    sessionId: string;
-    timestamp: string;
-    isSidechain?: boolean;
-    userType?: string;
-    cwd?: string;
-    version?: string;
-    subtype?: string;
-    compactMetadata?: {
-        preTokens: number;
-        trigger: string;
-    };
-    /**
-     * The message body, in the shape the transcript writer actually writes.
-     *
-     * M94 — it was `Record<string, unknown>`, and the consumer recovered the type with a cast on every read.
-     * The shape **has always been fixed** (`SessionTranscript.appendToolResults` / `#push` produce
-     * it); it simply was not declared. It stays optional because system records carry no message.
-     */
-    message?: TranscriptMessage;
-}
-
-/**
- * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
- *
- * A minimal, two-method port so an external store (Postgres / Redis / KV /
- * durable object) can be the **primary store AND resume source** — the
- * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
- * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
- * NOT that removed ~10-method adapter: the seam is JUST record read/append over
- * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
- * delete / objective methods).
- *
- * The SDK ships a real default implementation, `FsSessionStore`, that reads and
- * append-writes the native Claude-shaped `.jsonl` transcript — omitting
- * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
- * consumer change). Injected via `local.sessionStore` for external stores.
- *
- * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
- * abstracts a persistence model away; this one is defined in terms of the
- * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
- * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
- * `transcriptPath`, `transcriptRoot`) are published on purpose at
- * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
- *
- * That is the whole design and the reason the seam is two methods rather than
- * ten: the format is the contract, and a store implements read/append over it.
- * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
- * describe where the DEFAULT `FsSessionStore` puts files, not where an external
- * store must.
- *
- * Consistency contract: `appendRecords` is append-only and ordering-preserving.
- * The FS default serializes appends per agent with a cross-process file lock;
- * external implementations own (and MUST document) their own concurrency
- * guarantees for two hosts appending to the same `agentId`.
- *
- * @public
- */
-
-/**
- * The pluggable session-store seam. Exactly two methods over the native
- * {@link SessionRecord} shape.
- *
- * @public
- */
-interface SessionStore {
-    /**
-     * Return every persisted record for `agentId`, in append order. A session
-     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
-     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
-     * records via the native DAG reader, so the shape MUST be the exact
-     * {@link SessionRecord} the SDK writes.
-     *
-     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
-     * MUST throw a typed error rather than silently returning `[]` — a silent
-     * empty read would masquerade as "no history" and drop the conversation.
-     */
-    readRecords(agentId: string): Promise<SessionRecord[]>;
-    /**
-     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
-     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
-     * format is an append-only `parentUuid` DAG (compaction is a new-root
-     * `compact_boundary` record, still an append).
-     *
-     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
-     * is never blocked by store I/O — an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write). An external store that
-     * must guarantee durability should make `appendRecords` resilient (retry /
-     * durable write) internally. This differs from {@link SessionStore.readRecords},
-     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
-     */
-    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
-    /**
-     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
-     *
-     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
-     * working unchanged — declaring it here does not require it, which is the whole reason it is
-     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
-     * method through an `as unknown` cast against an interface that never mentioned it, so a
-     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
-     * two-method interface, implemented two methods, and never learned the hook was there.
-     *
-     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
-     * to the caller, because another process holding the session is a decision the caller has to make
-     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
-     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
-     * by contract anyway.
-     */
-    acquire?(agentId: string): Promise<void>;
-    /**
-     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
-     *
-     * Called on agent disposal. A rejection is not handled specially.
-     */
-    release?(agentId: string): Promise<void>;
-    /**
-     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
-     *
-     * Called once, on agent disposal, after {@link SessionStore.release}.
-     */
-    dispose?(): Promise<void>;
-}
-
 /**
  * A discovered skill's metadata. The skill BODY is never included — only the
  * strict frontmatter fields plus the resolved `source` path.
@@ -299,8 +92,12 @@ interface BudgetUsageEvent {
     readonly tokens: number;
     /** Provider/model identifier (e.g., `"openai/gpt-4o-mini"`). */
     readonly model: string;
-    /** Whether this is an input (prompt) or output (completion) measurement. */
-    readonly type: "input" | "output";
+    /**
+     * Whether this is an input (uncached prompt), output (completion), `cache_read` (prompt tokens
+     * served from the provider's cache) or `cache_write` (prompt tokens written to it) measurement.
+     * A tracker that has no separate rate for the cache types should treat them as input.
+     */
+    readonly type: "input" | "output" | "cache_read" | "cache_write";
     /** Optional ISO 8601 timestamp; defaults to now() if omitted. */
     readonly at?: string;
 }
@@ -1362,7 +1159,8 @@ type SystemPromptResolver = (ctx: SystemPromptContext) => string | Promise<strin
  */
 interface SkillsSettings {
     /**
-     * Names of skills the parent agent may invoke. When omitted, every
+     * Names of skills the local runtime loads: a skill not named here cannot be listed or read.
+     * When omitted, every
      * discovered skill is enabled.
      */
     enabled?: string[];
@@ -1778,6 +1576,18 @@ interface AgentOptions {
         conversationId: string;
         userId?: string;
     }) => Promise<void> | void;
+    /**
+     * Start a fresh conversation when the agent has been idle this many minutes.
+     *
+     * Checked at the start of a local `send`: when more than this long has passed since the previous
+     * `send` on the same agent began, the in-memory conversation is cleared first, so the model
+     * receives no prior messages and `onBeforeSend` reports `previousMessageCount: 0`. Absent (the
+     * default), or not a positive finite number, never resets. The first send of a process has no
+     * previous send, so it never resets. The on-disk transcript is not deleted.
+     *
+     * @public
+     */
+    sessionIdleResetMinutes?: number;
     /**
      * Fires before each `agent.send`. `previousMessageCount` is the count of
      * messages already persisted BEFORE the current send adds the user
@@ -2070,4 +1880,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BuiltinToolName as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SessionRecord as a1, type SessionStore as a2, type SettingSource as a3, Skill as a4, type SkillsResolver as a5, type SkillsResolverContext as a6, type SystemPromptContext as a7, type SystemPromptMemoryFact as a8, type TelemetrySettings as a9, type ToolCallSummary as aa, type ToolContext as ab, type ToolResultTransformContext as ac, type TransformContext as ad, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type BudgetTracker as l, type MemoryProvider as m, type PreToolCallDecision as n, type ActiveMemoryPassArgs as o, type ActiveMemoryPassResult as p, type AgentSubagentDescription as q, type AgentToolDescription as r, type BudgetCheck as s, type BudgetTotal as t, type BudgetUsageEvent as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };
+export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BuiltinToolName as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SettingSource as a1, Skill as a2, type SkillsResolver as a3, type SkillsResolverContext as a4, type SystemPromptContext as a5, type SystemPromptMemoryFact as a6, type TelemetrySettings as a7, type ToolCallSummary as a8, type ToolContext as a9, type ToolResultTransformContext as aa, type TransformContext as ab, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type BudgetTracker as l, type MemoryProvider as m, type PreToolCallDecision as n, type ActiveMemoryPassArgs as o, type ActiveMemoryPassResult as p, type AgentSubagentDescription as q, type AgentToolDescription as r, type BudgetCheck as s, type BudgetTotal as t, type BudgetUsageEvent as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };

package/dist/{agent-DExqjqYy.d.cts → agent-B6FQad6P.d.cts}

@@ -1,214 +1,7 @@
-import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aV as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-DwzHcuxy.cjs';
+import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aW as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-BA_6_wtc.cjs';
+import { a as SessionStore } from './session-store-Dh07jr9N.cjs';
 import { M as ModelSelection, C as CustomTool, P as PermissionMode } from './agent-prims-CZyxfCmS.cjs';
 
-/**
- * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
- * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * `SessionRecord` — the native on-disk transcript record shape (SE40).
- *
- * The theokit session format IS the Claude Code record shape: a
- * `uuid`/`parentUuid` DAG of records with structured
- * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
- * pluggable {@link SessionStore} seam operates over.
- *
- * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
- * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
- * re-exports it for back-compat while owning the record builders + reader.
- *
- * @public
- */
-/** A content block inside {@link TranscriptMessage}. */
-type TranscriptBlock = {
-    type: "text";
-    text: string;
-} | {
-    type: "thinking";
-    thinking?: string;
-    signature?: string;
-} | {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: unknown;
-} | {
-    type: "tool_result";
-    tool_use_id: string;
-    content: unknown;
-    is_error?: boolean;
-};
-/**
- * The message body of a {@link SessionRecord}.
- *
- * **It is NOT called `SessionMessage`** — that name already exists in
- * `internal/session/session-types.ts` with the shape `{role, text}`, incompatible with this one.
- * Reusing an exported name for a new shape is
- * precisely the silent break M91 cost two patches to undo.
- *
- * Parsing from disk stays **tolerant** (`readTranscript` skips a malformed line): what changes here
- * is the **type**, not leniency — records written by earlier versions stay readable.
- *
- * @public
- */
-interface TranscriptMessage {
-    role: "user" | "assistant";
-    content: TranscriptBlock[];
-    /**
-     * The three fields below appear **only** on the assistant record, and come from the writer
-     * (`SessionTranscript.appendAssistant`). Declared optional because the user record does not carry
-     * them — measured in the writer itself, not assumed.
-     */
-    id?: string;
-    type?: "message";
-    model?: string;
-}
-/**
- * One transcript record — a single line of the session JSONL file, and the unit the pluggable
- * `SessionStore` seam reads and writes.
- *
- * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
- * and is `null` at the root. Thread a session by following those links; a reader that assumes file
- * order is linear will mis-thread one that branched.
- *
- * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
- * so it is optional even on records you would expect to be conversational, and `type` is what tells
- * you which you are holding.
- *
- * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
- * Every record you receive is well-formed, but the file may have contained more than you got back,
- * so this is not the type to use for an exact-count audit of what was written.
- *
- * @public
- */
-interface SessionRecord {
-    type: "user" | "assistant" | "system";
-    uuid: string;
-    parentUuid: string | null;
-    sessionId: string;
-    timestamp: string;
-    isSidechain?: boolean;
-    userType?: string;
-    cwd?: string;
-    version?: string;
-    subtype?: string;
-    compactMetadata?: {
-        preTokens: number;
-        trigger: string;
-    };
-    /**
-     * The message body, in the shape the transcript writer actually writes.
-     *
-     * M94 — it was `Record<string, unknown>`, and the consumer recovered the type with a cast on every read.
-     * The shape **has always been fixed** (`SessionTranscript.appendToolResults` / `#push` produce
-     * it); it simply was not declared. It stays optional because system records carry no message.
-     */
-    message?: TranscriptMessage;
-}
-
-/**
- * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
- * `tests/lint/types-name-their-owner.test.ts` re-derives it.
- *
- * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
- *
- * A minimal, two-method port so an external store (Postgres / Redis / KV /
- * durable object) can be the **primary store AND resume source** — the
- * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
- * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
- * NOT that removed ~10-method adapter: the seam is JUST record read/append over
- * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
- * delete / objective methods).
- *
- * The SDK ships a real default implementation, `FsSessionStore`, that reads and
- * append-writes the native Claude-shaped `.jsonl` transcript — omitting
- * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
- * consumer change). Injected via `local.sessionStore` for external stores.
- *
- * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
- * abstracts a persistence model away; this one is defined in terms of the
- * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
- * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
- * `transcriptPath`, `transcriptRoot`) are published on purpose at
- * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
- *
- * That is the whole design and the reason the seam is two methods rather than
- * ten: the format is the contract, and a store implements read/append over it.
- * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
- * describe where the DEFAULT `FsSessionStore` puts files, not where an external
- * store must.
- *
- * Consistency contract: `appendRecords` is append-only and ordering-preserving.
- * The FS default serializes appends per agent with a cross-process file lock;
- * external implementations own (and MUST document) their own concurrency
- * guarantees for two hosts appending to the same `agentId`.
- *
- * @public
- */
-
-/**
- * The pluggable session-store seam. Exactly two methods over the native
- * {@link SessionRecord} shape.
- *
- * @public
- */
-interface SessionStore {
-    /**
-     * Return every persisted record for `agentId`, in append order. A session
-     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
-     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
-     * records via the native DAG reader, so the shape MUST be the exact
-     * {@link SessionRecord} the SDK writes.
-     *
-     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
-     * MUST throw a typed error rather than silently returning `[]` — a silent
-     * empty read would masquerade as "no history" and drop the conversation.
-     */
-    readRecords(agentId: string): Promise<SessionRecord[]>;
-    /**
-     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
-     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
-     * format is an append-only `parentUuid` DAG (compaction is a new-root
-     * `compact_boundary` record, still an append).
-     *
-     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
-     * is never blocked by store I/O — an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write). An external store that
-     * must guarantee durability should make `appendRecords` resilient (retry /
-     * durable write) internally. This differs from {@link SessionStore.readRecords},
-     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
-     */
-    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
-    /**
-     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
-     *
-     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
-     * working unchanged — declaring it here does not require it, which is the whole reason it is
-     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
-     * method through an `as unknown` cast against an interface that never mentioned it, so a
-     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
-     * two-method interface, implemented two methods, and never learned the hook was there.
-     *
-     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
-     * to the caller, because another process holding the session is a decision the caller has to make
-     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
-     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
-     * by contract anyway.
-     */
-    acquire?(agentId: string): Promise<void>;
-    /**
-     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
-     *
-     * Called on agent disposal. A rejection is not handled specially.
-     */
-    release?(agentId: string): Promise<void>;
-    /**
-     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
-     *
-     * Called once, on agent disposal, after {@link SessionStore.release}.
-     */
-    dispose?(): Promise<void>;
-}
-
 /**
  * A discovered skill's metadata. The skill BODY is never included — only the
  * strict frontmatter fields plus the resolved `source` path.
@@ -299,8 +92,12 @@ interface BudgetUsageEvent {
     readonly tokens: number;
     /** Provider/model identifier (e.g., `"openai/gpt-4o-mini"`). */
     readonly model: string;
-    /** Whether this is an input (prompt) or output (completion) measurement. */
-    readonly type: "input" | "output";
+    /**
+     * Whether this is an input (uncached prompt), output (completion), `cache_read` (prompt tokens
+     * served from the provider's cache) or `cache_write` (prompt tokens written to it) measurement.
+     * A tracker that has no separate rate for the cache types should treat them as input.
+     */
+    readonly type: "input" | "output" | "cache_read" | "cache_write";
     /** Optional ISO 8601 timestamp; defaults to now() if omitted. */
     readonly at?: string;
 }
@@ -1362,7 +1159,8 @@ type SystemPromptResolver = (ctx: SystemPromptContext) => string | Promise<strin
  */
 interface SkillsSettings {
     /**
-     * Names of skills the parent agent may invoke. When omitted, every
+     * Names of skills the local runtime loads: a skill not named here cannot be listed or read.
+     * When omitted, every
      * discovered skill is enabled.
      */
     enabled?: string[];
@@ -1778,6 +1576,18 @@ interface AgentOptions {
         conversationId: string;
         userId?: string;
     }) => Promise<void> | void;
+    /**
+     * Start a fresh conversation when the agent has been idle this many minutes.
+     *
+     * Checked at the start of a local `send`: when more than this long has passed since the previous
+     * `send` on the same agent began, the in-memory conversation is cleared first, so the model
+     * receives no prior messages and `onBeforeSend` reports `previousMessageCount: 0`. Absent (the
+     * default), or not a positive finite number, never resets. The first send of a process has no
+     * previous send, so it never resets. The on-disk transcript is not deleted.
+     *
+     * @public
+     */
+    sessionIdleResetMinutes?: number;
     /**
      * Fires before each `agent.send`. `previousMessageCount` is the count of
      * messages already persisted BEFORE the current send adds the user
@@ -2070,4 +1880,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BuiltinToolName as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SessionRecord as a1, type SessionStore as a2, type SettingSource as a3, Skill as a4, type SkillsResolver as a5, type SkillsResolverContext as a6, type SystemPromptContext as a7, type SystemPromptMemoryFact as a8, type TelemetrySettings as a9, type ToolCallSummary as aa, type ToolContext as ab, type ToolResultTransformContext as ac, type TransformContext as ad, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type BudgetTracker as l, type MemoryProvider as m, type PreToolCallDecision as n, type ActiveMemoryPassArgs as o, type ActiveMemoryPassResult as p, type AgentSubagentDescription as q, type AgentToolDescription as r, type BudgetCheck as s, type BudgetTotal as t, type BudgetUsageEvent as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };
+export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BuiltinToolName as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SettingSource as a1, Skill as a2, type SkillsResolver as a3, type SkillsResolverContext as a4, type SystemPromptContext as a5, type SystemPromptMemoryFact as a6, type TelemetrySettings as a7, type ToolCallSummary as a8, type ToolContext as a9, type ToolResultTransformContext as aa, type TransformContext as ab, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type BudgetTracker as l, type MemoryProvider as m, type PreToolCallDecision as n, type ActiveMemoryPassArgs as o, type ActiveMemoryPassResult as p, type AgentSubagentDescription as q, type AgentToolDescription as r, type BudgetCheck as s, type BudgetTotal as t, type BudgetUsageEvent as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };

package/dist/{agent-T34LCGQM.js → agent-DRDGUU6T.js}

@@ -1,25 +1,26 @@
-export { Agent } from './chunk-GARVAUCU.js';
+export { Agent } from './chunk-5M5GQYBM.js';
 import './chunk-HWMGR3HA.js';
-import './chunk-3ONIVO2I.js';
+import './chunk-23SS4ID4.js';
 import './chunk-K2BQQ445.js';
-import './chunk-2C24NSNV.js';
+import './chunk-3BBTHFGJ.js';
 import './chunk-HJ2LV464.js';
 import './chunk-2SFBB54R.js';
-import './chunk-H7G65PNI.js';
+import './chunk-VCQ37TC5.js';
 import './chunk-H73MEMQB.js';
 import './chunk-QK2ERTO3.js';
-import './chunk-DF77RBF4.js';
-import './chunk-AB4OPJLD.js';
-import './chunk-ZOL3L4EH.js';
-import './chunk-5AR6O7GW.js';
+import './chunk-LCCT5ZXJ.js';
+import './chunk-RGVMJU57.js';
+import './chunk-IOBHFP2E.js';
+import './chunk-NK5EOTDY.js';
 import './chunk-2XC6KDJM.js';
-import './chunk-ZJAYFSVI.js';
+import './chunk-7ACS6P5Z.js';
 import './chunk-24MGQDK3.js';
 import './chunk-AGO5S5WD.js';
 import './chunk-HKCKOAIO.js';
 import './chunk-KCM3RMKR.js';
 import './chunk-XJ3WU5CZ.js';
 import './chunk-KVNWIAO4.js';
+import './chunk-X7CE7Y5W.js';
 import './chunk-OLJOI4LK.js';
 import './chunk-FD2UT76F.js';
 import './chunk-7I5Z3UBJ.js';
@@ -39,18 +40,18 @@ import './chunk-XESYJ4JC.js';
 import './chunk-WE22OXQA.js';
 import './chunk-MLJDW2YK.js';
 import './chunk-KU5O7WPK.js';
-import './chunk-354F3OF5.js';
-import './chunk-Q5EWJPRY.js';
+import './chunk-FGGVSHDW.js';
+import './chunk-PPU2D4FZ.js';
 import './chunk-MLGETTYX.js';
 import './chunk-M4U24U6G.js';
-import './chunk-RN3XDZGS.js';
+import './chunk-WM646HEN.js';
 import './chunk-YMVTUV5K.js';
 import './chunk-Q7UG242V.js';
 import './chunk-SZQFCHU6.js';
-import './chunk-NVQSBRG6.js';
+import './chunk-CBBT42VX.js';
 import './chunk-R7WIIPUR.js';
-import './chunk-ULEK4OM4.js';
-import './chunk-CJN5CEI3.js';
+import './chunk-YKNBTHMD.js';
+import './chunk-RZL2W4C3.js';
 import './chunk-AGACYRJ2.js';
 import './chunk-3GTN4HOO.js';
 import './chunk-QD6B6W6I.js';
@@ -58,5 +59,5 @@ import './chunk-5IUDICRK.js';
 import './chunk-Q7GYMXVC.js';
 import './chunk-TNFOU6SB.js';
 import './chunk-3OY6H3I7.js';
-//# sourceMappingURL=agent-T34LCGQM.js.map
-//# sourceMappingURL=agent-T34LCGQM.js.map
+//# sourceMappingURL=agent-DRDGUU6T.js.map
+//# sourceMappingURL=agent-DRDGUU6T.js.map

package/dist/{agent-T34LCGQM.js.map → agent-DRDGUU6T.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-T34LCGQM.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-DRDGUU6T.js"}