@theokit/sdk 4.37.2 → 4.39.0

package/dist/internal/persistence/index.js

@@ -1,11 +1,11 @@
 export { PersistenceSchema } from '../../chunk-CAH3G4IS.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome, migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-ZW345YOI.js';
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-YHZXBDAW.js';
-export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-GLUWH6JO.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome, migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-YP67XZES.js';
+export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-BQDUEG4C.js';
+export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-AECV3G5Z.js';
 export { withCwdMutex } from '../../chunk-2XLKLVVR.js';
-export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-56OXYUZE.js';
-import '../../chunk-CD73YHEH.js';
-import '../../chunk-TAPQWDW2.js';
+export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-KX7JV5KM.js';
+import '../../chunk-SG5ZWT6C.js';
+import '../../chunk-IVSD7L22.js';
 import { open } from 'fs/promises';
 
 async function createExclusive(path, data, options) {

package/dist/internal/persistence/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;AAgCA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACjBO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS sem honor de O_EXCL é documentado (D61 — mesma postura do\n * `withFileLock`); SDK target é ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":[],"mappings":";;;;;;;;;;AAgCA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACjBO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.js","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Atomically create `path` with `data`. Returns true iff this call\n * created the file (race-free under POSIX-compliant filesystems).\n *\n * @internal\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * @internal\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Execute a CAS UPDATE. Returns true iff the actual changes count matches\n * `expectedChanges`. SQL errors (invalid syntax, closed db) propagate.\n *\n * @internal\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}

package/dist/internal/persistence/paths.d.cts

@@ -10,15 +10,15 @@
  *     `path.join(cwd, ".theokit")` in callers — use this function so tests
  *     and overrides stay consistent.
  *
- *     M94 — este comentário dizia "the ONLY canonical resolver", e deixou de ser verdade: o
- *     transcript ganhou `transcriptRoot()`, que é **home-ancorado** (`~/.theokit`) com o mesmo
- *     override por `THEOKIT_HOME`. Os dois defaults diferem de propósito — unificar moveria o
- *     transcript de todo mundo que NÃO define a variável, que é uma migração de dados e não um
+ *     M94 — this comment said "the ONLY canonical resolver", and stopped being true: the
+ *     transcript gained `transcriptRoot()`, which is **home-anchored** (`~/.theokit`) with the same
+ *     `THEOKIT_HOME` override. The two defaults differ on purpose — unifying would move the
+ *     transcript of everyone who does NOT set the variable, which is a data migration and not a
  *     re-export.
  *
- *     Consequência que merece estar escrita: **sem `THEOKIT_HOME` o estado segue partido em dois**
- *     — registry em `<cwd>/.theokit`, transcript em `~/.theokit`. O M94 unifica só para quem define
- *     a variável. Unificar os dois defaults é trabalho de outro milestone.
+ *     A consequence worth writing down: **without `THEOKIT_HOME` the state stays split in two**
+ *     — registry in `<cwd>/.theokit`, transcript in `~/.theokit`. M94 unifies only for those who set
+ *     the variable. Unifying both defaults is another milestone's work.
  *   - `getProfilesRoot()` is intentionally home-anchored (not affected by
  *     `THEOKIT_HOME`) so `theokit profile list` discovers all profiles
  *     regardless of which is active.

package/dist/internal/persistence/paths.d.ts

@@ -10,15 +10,15 @@
  *     `path.join(cwd, ".theokit")` in callers — use this function so tests
  *     and overrides stay consistent.
  *
- *     M94 — este comentário dizia "the ONLY canonical resolver", e deixou de ser verdade: o
- *     transcript ganhou `transcriptRoot()`, que é **home-ancorado** (`~/.theokit`) com o mesmo
- *     override por `THEOKIT_HOME`. Os dois defaults diferem de propósito — unificar moveria o
- *     transcript de todo mundo que NÃO define a variável, que é uma migração de dados e não um
+ *     M94 — this comment said "the ONLY canonical resolver", and stopped being true: the
+ *     transcript gained `transcriptRoot()`, which is **home-anchored** (`~/.theokit`) with the same
+ *     `THEOKIT_HOME` override. The two defaults differ on purpose — unifying would move the
+ *     transcript of everyone who does NOT set the variable, which is a data migration and not a
  *     re-export.
  *
- *     Consequência que merece estar escrita: **sem `THEOKIT_HOME` o estado segue partido em dois**
- *     — registry em `<cwd>/.theokit`, transcript em `~/.theokit`. O M94 unifica só para quem define
- *     a variável. Unificar os dois defaults é trabalho de outro milestone.
+ *     A consequence worth writing down: **without `THEOKIT_HOME` the state stays split in two**
+ *     — registry in `<cwd>/.theokit`, transcript in `~/.theokit`. M94 unifies only for those who set
+ *     the variable. Unifying both defaults is another milestone's work.
  *   - `getProfilesRoot()` is intentionally home-anchored (not affected by
  *     `THEOKIT_HOME`) so `theokit profile list` discovers all profiles
  *     regardless of which is active.

package/dist/internal/persistence/session-transcript.d.cts

@@ -10,6 +10,12 @@ export interface SessionTranscriptOptions {
 export interface AssistantTurn {
     text?: string;
     thinking?: string;
+    /**
+     * theokit#122 — the provider's signature for the thinking block. Written into the `thinking`
+     * record block (`Block` already declared `signature?`), so a resumed session can replay the block
+     * exactly as the provider issued it.
+     */
+    thinkingSignature?: string;
     toolCalls?: Array<{
         id: string;
         name: string;
@@ -57,16 +63,16 @@ export declare function reconstructMessages(records: readonly SessionRecord[]):
 /**
  * Raiz do estado de transcript.
  *
- * `THEOKIT_HOME` vence; o fallback é `~/.theokit`. Home-ancorado de propósito, e NÃO
- * `getTheokitHome(cwd)` de `paths.ts`: aquele faz fallback para `<cwd>/.theokit`, e trocar
- * por ele moveria o transcript de todo mundo que **não** define a variável. O irmão com a
- * forma certa é `catalog-source-models-dev.ts` (M94 ADR-2).
+ * `THEOKIT_HOME` wins; the fallback is `~/.theokit`. Home-anchored on purpose, and NOT
+ * `paths.ts`'s `getTheokitHome(cwd)`: that one falls back to `<cwd>/.theokit`, and switching
+ * by it would move the transcript of everyone who does **not** set the variable. The sibling with the
+ * right shape is `catalog-source-models-dev.ts` (M94 ADR-2).
  *
- * Antes do M94 esta função ignorava a env, então quem a definia tinha o estado partido em
- * dois em silêncio — as sessões continuavam em `~/.theokit` enquanto o resto do SDK migrava.
+ * Before M94 this function ignored the env var, so whoever set it had their state split in
+ * two silently — sessions stayed in `~/.theokit` while the rest of the SDK migrated.
  */
 export declare function transcriptRoot(): string;
-/** @deprecated Use {@link transcriptRoot}. Mantido como alias — mesmo valor. */
+/** @deprecated Use {@link transcriptRoot}. Kept as an alias — same value. */
 export declare function defaultBaseDir(): string;
 /**
  * Expand a leading `~` / `~/` to the user's home dir. `node:path` does NOT expand `~`, so a

package/dist/internal/persistence/session-transcript.d.ts

@@ -10,6 +10,12 @@ export interface SessionTranscriptOptions {
 export interface AssistantTurn {
     text?: string;
     thinking?: string;
+    /**
+     * theokit#122 — the provider's signature for the thinking block. Written into the `thinking`
+     * record block (`Block` already declared `signature?`), so a resumed session can replay the block
+     * exactly as the provider issued it.
+     */
+    thinkingSignature?: string;
     toolCalls?: Array<{
         id: string;
         name: string;
@@ -57,16 +63,16 @@ export declare function reconstructMessages(records: readonly SessionRecord[]):
 /**
  * Raiz do estado de transcript.
  *
- * `THEOKIT_HOME` vence; o fallback é `~/.theokit`. Home-ancorado de propósito, e NÃO
- * `getTheokitHome(cwd)` de `paths.ts`: aquele faz fallback para `<cwd>/.theokit`, e trocar
- * por ele moveria o transcript de todo mundo que **não** define a variável. O irmão com a
- * forma certa é `catalog-source-models-dev.ts` (M94 ADR-2).
+ * `THEOKIT_HOME` wins; the fallback is `~/.theokit`. Home-anchored on purpose, and NOT
+ * `paths.ts`'s `getTheokitHome(cwd)`: that one falls back to `<cwd>/.theokit`, and switching
+ * by it would move the transcript of everyone who does **not** set the variable. The sibling with the
+ * right shape is `catalog-source-models-dev.ts` (M94 ADR-2).
  *
- * Antes do M94 esta função ignorava a env, então quem a definia tinha o estado partido em
- * dois em silêncio — as sessões continuavam em `~/.theokit` enquanto o resto do SDK migrava.
+ * Before M94 this function ignored the env var, so whoever set it had their state split in
+ * two silently — sessions stayed in `~/.theokit` while the rest of the SDK migrated.
  */
 export declare function transcriptRoot(): string;
-/** @deprecated Use {@link transcriptRoot}. Mantido como alias — mesmo valor. */
+/** @deprecated Use {@link transcriptRoot}. Kept as an alias — same value. */
 export declare function defaultBaseDir(): string;
 /**
  * Expand a leading `~` / `~/` to the user's home dir. `node:path` does NOT expand `~`, so a

package/dist/internal/persistence/session-writer.d.cts

@@ -45,6 +45,17 @@ export declare class SessionBusyError extends TheokitAgentError {
 export interface SessionWriterLease {
     readonly sessionPath: string;
     release(): Promise<void>;
+    /**
+     * Re-stamp the ownership record, so a **live** owner never crosses the staleness window.
+     *
+     * Idempotent and cheap: one `write` of a ~80-byte JSON. Call it on the path that already writes to
+     * the session — appending a turn — and the cross-host window stops being a lie about liveness.
+     *
+     * A no-op after `release()`: renewing a lease you no longer hold would re-create the lock file and
+     * hand this process ownership it gave up. That is the one direction of this API that could
+     * *create* the double-writer it exists to prevent.
+     */
+    renew(): void;
 }
 /**
  * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
@@ -54,21 +65,27 @@ export interface SessionWriterLease {
  * processes, not just across async tasks in one process.
  */
 /**
- * Janela de obsolescência **entre máquinas** — e só entre elas.
+ * Staleness window **between machines** — and only between them.
  *
- * 30 s a partir da AQUISIÇÃO. O nome "heartbeat" seria mentira: o registro é gravado uma vez, na
- * tomada do lease, e **não** é renovado a cada escrita. A versão anterior deste comentário dizia
- * "o dono toca o arquivo a cada aquisição, então um processo ativo nunca cruza a janela" — falso
- * duas vezes, e a revisão adversarial mediu as duas.
+ * 30 s from ACQUISITION. Calling it a "heartbeat" would be a lie: the record is written once, when
+ * the lease is taken, and is **not** renewed on every write. An earlier version of this comment
+ * claimed "the owner touches the file on every acquisition, so a live process never crosses the
+ * window" — false twice over, and adversarial review measured both.
  *
- * No **mesmo host** isso não importa: `reclamavel` decide pelo `pid`, que é exato, e a idade não
- * entra na conta. Entre hosts, importa e é um limite real: um dono remoto **vivo** perde o lease
- * depois de 30 s, porque não há como perguntar a outra máquina se o processo dela existe.
+ * On the **same host** this does not matter: `reclaimable` decides by `pid`, which is exact, and age
+ * never enters the calculation. Across hosts it does matter, and it is a real limit: a **live**
+ * remote owner loses the lease after 30 s, because there is no way to ask another machine whether
+ * its process still exists.
  *
- * **Resíduo declarado, não mecanizado** (a disciplina de `error-handling.md § 4`): renovar o
- * registro a cada append fecharia essa janela, ao custo de um `write` por turno num arquivo que
- * hoje é escrito uma vez por sessão. Não foi feito, e o caso multi-host não é o que motiva este
- * milestone — o enunciado é `exec` e TUI na mesma máquina.
+ * **The residue is now closable by the caller** (`agent-builder#118`). `SessionWriterLease.renew()`
+ * re-stamps the record; calling it on the path that already writes to the session — appending a turn
+ * — keeps a live owner from ever crossing the window. It costs one `write` of ~80 bytes on a file
+ * that was previously written once per session.
+ *
+ * It is `renew()` and not an internal timer on purpose. A timer inside the lease would keep the event
+ * loop alive (or need `unref` plus its own teardown), and it would renew a lease belonging to a
+ * process that is hung rather than working — which is precisely the state the window exists to
+ * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
-export declare const JANELA_DE_HEARTBEAT_MS = 30000;
+export declare const HEARTBEAT_WINDOW_MS = 30000;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/internal/persistence/session-writer.d.ts

@@ -45,6 +45,17 @@ export declare class SessionBusyError extends TheokitAgentError {
 export interface SessionWriterLease {
     readonly sessionPath: string;
     release(): Promise<void>;
+    /**
+     * Re-stamp the ownership record, so a **live** owner never crosses the staleness window.
+     *
+     * Idempotent and cheap: one `write` of a ~80-byte JSON. Call it on the path that already writes to
+     * the session — appending a turn — and the cross-host window stops being a lie about liveness.
+     *
+     * A no-op after `release()`: renewing a lease you no longer hold would re-create the lock file and
+     * hand this process ownership it gave up. That is the one direction of this API that could
+     * *create* the double-writer it exists to prevent.
+     */
+    renew(): void;
 }
 /**
  * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.
@@ -54,21 +65,27 @@ export interface SessionWriterLease {
  * processes, not just across async tasks in one process.
  */
 /**
- * Janela de obsolescência **entre máquinas** — e só entre elas.
+ * Staleness window **between machines** — and only between them.
  *
- * 30 s a partir da AQUISIÇÃO. O nome "heartbeat" seria mentira: o registro é gravado uma vez, na
- * tomada do lease, e **não** é renovado a cada escrita. A versão anterior deste comentário dizia
- * "o dono toca o arquivo a cada aquisição, então um processo ativo nunca cruza a janela" — falso
- * duas vezes, e a revisão adversarial mediu as duas.
+ * 30 s from ACQUISITION. Calling it a "heartbeat" would be a lie: the record is written once, when
+ * the lease is taken, and is **not** renewed on every write. An earlier version of this comment
+ * claimed "the owner touches the file on every acquisition, so a live process never crosses the
+ * window" — false twice over, and adversarial review measured both.
  *
- * No **mesmo host** isso não importa: `reclamavel` decide pelo `pid`, que é exato, e a idade não
- * entra na conta. Entre hosts, importa e é um limite real: um dono remoto **vivo** perde o lease
- * depois de 30 s, porque não há como perguntar a outra máquina se o processo dela existe.
+ * On the **same host** this does not matter: `reclaimable` decides by `pid`, which is exact, and age
+ * never enters the calculation. Across hosts it does matter, and it is a real limit: a **live**
+ * remote owner loses the lease after 30 s, because there is no way to ask another machine whether
+ * its process still exists.
  *
- * **Resíduo declarado, não mecanizado** (a disciplina de `error-handling.md § 4`): renovar o
- * registro a cada append fecharia essa janela, ao custo de um `write` por turno num arquivo que
- * hoje é escrito uma vez por sessão. Não foi feito, e o caso multi-host não é o que motiva este
- * milestone — o enunciado é `exec` e TUI na mesma máquina.
+ * **The residue is now closable by the caller** (`agent-builder#118`). `SessionWriterLease.renew()`
+ * re-stamps the record; calling it on the path that already writes to the session — appending a turn
+ * — keeps a live owner from ever crossing the window. It costs one `write` of ~80 bytes on a file
+ * that was previously written once per session.
+ *
+ * It is `renew()` and not an internal timer on purpose. A timer inside the lease would keep the event
+ * loop alive (or need `unref` plus its own teardown), and it would renew a lease belonging to a
+ * process that is hung rather than working — which is precisely the state the window exists to
+ * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
-export declare const JANELA_DE_HEARTBEAT_MS = 30000;
+export declare const HEARTBEAT_WINDOW_MS = 30000;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/internal/runtime/concurrency/subagent-credentials.d.ts

@@ -0,0 +1,35 @@
+/**
+ * theokit#148 — the parent's credentials, delivered through the CALL, not through the tool object.
+ *
+ * ## The class of bug this replaces
+ *
+ * Credential inheritance used to ride a property installed on the subagent tool object — first a
+ * unique `Symbol()`, then `Symbol.for` after #143. Both are the same shape of contract: "this
+ * object will reach the dispatcher with an extra property intact". Nothing enforces that, and it
+ * broke twice for two different reasons:
+ *
+ *  - **Module duplication** (#142/#143): `tsup splitting: false` inlined a separate copy of the
+ *    module into each public entry, so the two copies disagreed on a unique `Symbol()` key. Fixed at
+ *    the build level by M78's `splitting: true`, but the fragile contract remained.
+ *  - **Object normalization** (#148): any layer that rebuilds the tool from its known fields drops
+ *    the property. `@theokit/agents`' `toCompiledTool` does exactly that, and had to add an explicit
+ *    `Object.getOwnPropertySymbols` copy loop to compensate — a band-aid the SDK's contract forced
+ *    onto a consumer. A named field would have been dropped by the same four-field rebuild, which is
+ *    why "make it a typed field" alone does not close this.
+ *
+ * ## Why the async scope closes it
+ *
+ * What survives a rebuild is not the object — it is the CALL. A normalizing wrapper builds a new
+ * object but still invokes the original handler, inside the parent run's async context. So
+ * credentials published on that context reach the handler regardless of what the tool object looks
+ * like by then. There is no property left for a layer to drop.
+ *
+ * It also fixes a defect the per-object slot could not: credentials were stored per tool INSTANCE,
+ * so one subagent tool shared by two agents got last-writer-wins. The scope is per run.
+ *
+ * Nothing is exposed to third-party tool code: the store is module-private, credentials never touch
+ * a handler's `ctx`, and `currentInheritedSubAgentCredentials` is `@internal`.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/fixtures/fixture-run-base.d.ts

@@ -1,7 +1,7 @@
 import type { ModelSelection } from "../../../types/agent.js";
 import type { ConversationTurn } from "../../../types/conversation.js";
 import type { SDKMessage } from "../../../types/messages.js";
-import type { Run, RunOperation, RunResult, RunStatus } from "../../../types/run.js";
+import type { Run, RunOperation, RunResult, RunStatus, RunTimelineEvent } from "../../../types/run.js";
 import type { FixtureScript } from "./fixture-types.js";
 export declare abstract class FixtureRunBase implements Run {
     readonly id: string;
@@ -19,6 +19,16 @@ export declare abstract class FixtureRunBase implements Run {
     protected resolveTermination: (value: RunResult) => void;
     protected terminated: boolean;
     private eventNotifier;
+    /**
+     * theokit#140 - the run's single ordered timeline: structural events and live token/tool deltas,
+     * in the order they actually occurred.
+     *
+     * Kept alongside `script.events` rather than replacing it. `stream()` is the SDKMessage view and
+     * stays byte-identical for every existing consumer; this is the complete view, and a consumer
+     * picks one. Merging them would have changed `stream()`'s element type - a breaking change for
+     * an additive feature.
+     */
+    protected readonly timeline: RunTimelineEvent[];
     constructor(options: FixtureRunBaseOptions);
     abstract bootstrap(): void;
     /**
@@ -27,24 +37,46 @@ export declare abstract class FixtureRunBase implements Run {
      * consumers of `stream()` wake up and yield it.
      */
     protected notifyNewEvents(): void;
+    /**
+     * theokit#140 - every event of this run, in true order, from ONE source.
+     *
+     * ## The defect this replaces
+     *
+     * A consumer that needed tool calls interleaved with tokens had to fuse two surfaces by hand:
+     * `stream()`, which was batched and post-completion, and `SendOptions.onDelta`, which was live.
+     * Neither was complete alone - `onDelta` has no `run_started`/`system`, and `stream()` had no
+     * token granularity - so the entire reconciliation, including its dedup, lived in the consumer.
+     * `@theokit/agents` carried ~200 lines of exactly that, and it is the documented root of its
+     * ordering bug (theokit#47), its namespace-dedup bug (#138) and its missing terminal frame (#142).
+     *
+     * The ordering is not reconstructed here. Both kinds are appended by the loop AS THEY HAPPEN, so
+     * arrival order IS model order - there is nothing to sort, and no timestamp heuristic to get
+     * wrong.
+     *
+     * `callId` is whatever the SDK's own `tool_call` events carry, so a consumer no longer holds two
+     * id namespaces and no longer has to correlate them.
+     */
+    events(): AsyncGenerator<RunTimelineEvent, void>;
+    /** theokit#140 - append to the timeline and wake `events()`. */
+    protected pushTimeline(event: RunTimelineEvent): void;
     stream(): AsyncGenerator<SDKMessage, void>;
     /**
-     * theokit#101 — quando o run termina em erro, `stream()` tem de DIZER.
+     * theokit#101 — when the run ends in error, `stream()` has to SAY SO.
      *
-     * O erro sempre existiu: o loop o registra em `ctx.error` e `wait()` devolve
-     * `status: 'error'` com a mensagem. Só o `stream()` não o mencionava — ele drena
-     * `script.events` e para. Uma falha de provider (404 "No endpoints found", auth, timeout)
-     * produzia um turno que parecia bem-sucedido e vazio, em TODA superfície que consome o
+     * The error always existed: the loop records it in `ctx.error` and `wait()` returns
+     * `status: 'error'` with the message. Only `stream()` failed to mention it — it drains
+     * `script.events` and stops. A provider failure (404 "No endpoints found", auth, timeout)
+     * produced a turn that looked successful and empty, on EVERY surface consuming the
      * stream: HTTP web, MCP, stdio, TUI in-process.
      *
-     * Erro silencioso é o pior tipo (Regra Inquebrável 8). E a assimetria era o que o tornava
-     * difícil de diagnosticar: quem depurasse por `wait()` via o erro e não reproduziria o
-     * relato de quem depurava pelo stream.
+     * A silent error is the worst kind (Unbreakable Rule 8). And the asymmetry was what made it
+     * hard to diagnose: anyone debugging via `wait()` saw the error and would not reproduce the
+     * report of anyone debugging via the stream.
      *
-     * Emite `SDKStatusMessage` com `status: "ERROR"` — o tipo JÁ EXISTE na união `SDKMessage`
-     * e já é esperado por quem consome. Um tipo novo seria breaking para todo consumidor que
-     * faz switch exaustivo; este é aditivo, e um consumidor que ignore `status` simplesmente
-     * segue como antes — nunca pior que hoje.
+     * It emits `SDKStatusMessage` with `status: "ERROR"` — the type ALREADY EXISTS in the `SDKMessage` union
+     * and is already expected by consumers. A new type would be breaking for every consumer doing
+     * an exhaustive switch; this one is additive, and a consumer ignoring `status` simply
+     * behaves as before — never worse than today.
      */
     private terminalErrorEvent;
     wait(): Promise<RunResult>;

package/dist/internal/runtime/lifecycle/goal-marker.d.ts

@@ -1,13 +1,13 @@
 /**
- * O marcador de continuação do goal-loop — num módulo FOLHA, de propósito.
+ * The goal-loop's continuation marker — in a LEAF module, on purpose.
  *
- * Ele vivia em `goal-loop.ts` e era importado por `run-until.ts`, que o `goal-loop` por sua vez
- * importa de volta. O ciclo estava quebrado em runtime (a volta é `import type` + `await import()`
- * dinâmico), mas o detector de ciclos conta a aresta dinâmica — e contar import dinâmico como ciclo
- * torna o gate impossível de satisfazer sem abandonar a técnica canônica de quebrar ciclos.
+ * It lived in `goal-loop.ts` and was imported by `run-until.ts`, which `goal-loop` in turn
+ * imports back. The cycle was broken at runtime (the return edge is `import type` + a dynamic
+ * `await import()`), but the cycle detector counts the dynamic edge — and counting a dynamic import as a cycle
+ * makes the gate impossible to satisfy without abandoning the canonical cycle-breaking technique.
  *
- * Uma constante compartilhada por dois módulos que se conhecem é o caso-escola de extração para
- * folha: ninguém precisa importar o outro para conhecê-la. Some o ciclo em QUALQUER detector, sem
- * política de ferramenta e sem mudar uma linha de comportamento.
+ * A constant shared by two modules that know each other is the textbook case for extraction into a
+ * leaf: neither needs to import the other to know it. The cycle disappears under ANY detector, with no
+ * tool policy and without changing a line of behavior.
  */
 export declare const GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";

package/dist/internal/security/index.cjs

@@ -1,51 +1,51 @@
 'use strict';
 
 require('../../chunk-MUUQ2WFJ.cjs');
-var chunkYBFDBOUN_cjs = require('../../chunk-YBFDBOUN.cjs');
-require('../../chunk-MHCKWQR3.cjs');
-var chunkLTCOPATU_cjs = require('../../chunk-LTCOPATU.cjs');
+var chunk7YBJZS5P_cjs = require('../../chunk-7YBJZS5P.cjs');
+require('../../chunk-IHFNRNTJ.cjs');
+var chunkBCQ3E2ZG_cjs = require('../../chunk-BCQ3E2ZG.cjs');
 
 
 
 Object.defineProperty(exports, "ForbiddenPathError", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.ForbiddenPathError; }
+  get: function () { return chunk7YBJZS5P_cjs.ForbiddenPathError; }
 });
 Object.defineProperty(exports, "PathTraversalError", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.PathTraversalError; }
+  get: function () { return chunk7YBJZS5P_cjs.PathTraversalError; }
 });
 Object.defineProperty(exports, "assertNoSymlinkEscape", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.assertNoSymlinkEscape; }
+  get: function () { return chunk7YBJZS5P_cjs.assertNoSymlinkEscape; }
 });
 Object.defineProperty(exports, "isForbiddenPath", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.isForbiddenPath; }
+  get: function () { return chunk7YBJZS5P_cjs.isForbiddenPath; }
 });
 Object.defineProperty(exports, "safePathJoin", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.safePathJoin; }
+  get: function () { return chunk7YBJZS5P_cjs.safePathJoin; }
 });
 Object.defineProperty(exports, "sanitizeIdentifier", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.sanitizeIdentifier; }
+  get: function () { return chunk7YBJZS5P_cjs.sanitizeIdentifier; }
 });
 Object.defineProperty(exports, "validateArtifactPath", {
   enumerable: true,
-  get: function () { return chunkYBFDBOUN_cjs.validateArtifactPath; }
+  get: function () { return chunk7YBJZS5P_cjs.validateArtifactPath; }
 });
 Object.defineProperty(exports, "addPattern", {
   enumerable: true,
-  get: function () { return chunkLTCOPATU_cjs.addPattern; }
+  get: function () { return chunkBCQ3E2ZG_cjs.addPattern; }
 });
 Object.defineProperty(exports, "maskToken", {
   enumerable: true,
-  get: function () { return chunkLTCOPATU_cjs.maskToken; }
+  get: function () { return chunkBCQ3E2ZG_cjs.maskToken; }
 });
 Object.defineProperty(exports, "redactSecrets", {
   enumerable: true,
-  get: function () { return chunkLTCOPATU_cjs.redactSecrets; }
+  get: function () { return chunkBCQ3E2ZG_cjs.redactSecrets; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/security/index.js

@@ -1,6 +1,6 @@
 import '../../chunk-FD2UT76F.js';
-export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin, sanitizeIdentifier, validateArtifactPath } from '../../chunk-WDGCZDRG.js';
-import '../../chunk-CD73YHEH.js';
-export { addPattern, maskToken, redactSecrets } from '../../chunk-TAPQWDW2.js';
+export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin, sanitizeIdentifier, validateArtifactPath } from '../../chunk-J3UK2GMN.js';
+import '../../chunk-SG5ZWT6C.js';
+export { addPattern, maskToken, redactSecrets } from '../../chunk-IVSD7L22.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/internal/session/agent-session-store.d.ts

@@ -11,6 +11,7 @@
  *
  * @internal
  */
+import type { ConversationTurn } from "../../types/conversation.js";
 import type { SessionStore } from "../../types/session-store.js";
 import type { SessionMessage } from "./session-types.js";
 /** The turn to persist: the user's text plus the rich per-turn conversation view. */

package/dist/internal/session/agent-session.d.ts

@@ -1,27 +1,27 @@
 import type { SessionMessage } from "./session-types.js";
 export { hydratedKeys, invalidateSessionCache, sessions, transcriptKey, } from "./session-cache.js";
 /**
- * Teto de sessões mantidas em memória.
+ * Ceiling on sessions kept in memory.
  *
- * O runtime só lê a sessão **ativa**; o resto é cache puro, reconstruível do transcript em disco.
- * 32 é folgado de propósito — o caminho primário de remoção é o `descartarSessao()` explícito no
- * fim da vida do agente, e este teto é rede de segurança contra um processo de vida longa que roda
- * centenas de sessões (risco #2 do plano: um teto apertado poderia evictar sessão ainda referenciada
- * por um fluxo assíncrono em voo).
+ * The runtime only reads the **active** session; the rest is pure cache, rebuildable from the
+ * on-disk transcript. 32 is deliberately generous — the primary removal path is the explicit
+ * `discardSession()` at the end of the agent's life, and this ceiling is a safety net against a
+ * long-lived process running hundreds of sessions (plan risk #2: a tight ceiling could evict a
+ * session still referenced by an in-flight async path).
  */
-export declare const TETO_DE_SESSOES_EM_CACHE = 32;
+export declare const MAX_CACHED_SESSIONS = 32;
 /**
- * Apaga a escrituração de módulo do agente e devolve quantas entradas saíram.
+ * Erases the agent's module bookkeeping and returns how many entries were removed.
  *
  * M95 — `invalidateSessionCache` limpava **dois** dos quatro mapas (`sessions`, `hydratedKeys`);
- * `pendingWrites` e `recordCounts` nunca eram tocados por id, então cresciam pela vida do processo.
- * Nenhum dos dois é grande por entrada — o vazamento é de contagem, não de volume — mas cache sem
- * dono da remoção é cache que só cresce.
+ * `pendingWrites` and `recordCounts` were never touched by id, so they grew for the life of the
+ * process. Neither is large per entry — the leak is in count, not volume — but a cache with no owner
+ * for removal is a cache that only grows.
  *
- * Devolve a contagem para que o chamador possa provar a remoção; um segundo descarte devolve 0,
- * que é o que torna o teste de idempotência possível sem expor os mapas.
+ * Returns the count so the caller can prove the removal; a second discard returns 0, which is what
+ * makes the idempotency test possible without exposing the maps.
  */
-export declare function descartarSessao(cwd: string, agentId: string): number;
+export declare function discardSession(cwd: string, agentId: string): number;
 export declare function getSessionMessages(agentId: string): SessionMessage[];
 export declare function clearSession(agentId: string): void;
 /**