@theokit/sdk 4.33.1 → 4.34.0

package/dist/index.js

@@ -6,16 +6,16 @@ import './chunk-GJAGKFTR.js';
 import { Workflow, agentStep } from './chunk-BFWPZMG7.js';
 import './chunk-UVNG67DG.js';
 import './chunk-CAH3G4IS.js';
-export { Cron } from './chunk-3CMIY3N7.js';
-import { MEMORY_EMBEDDING_ADAPTERS, resolveApiKey, shouldUseFixtureMode, isFixtureApiKey, httpRequest, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-4LXCZSIC.js';
-export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-4LXCZSIC.js';
+export { Cron } from './chunk-5QMXYX3X.js';
+import { MEMORY_EMBEDDING_ADAPTERS, resolveApiKey, shouldUseFixtureMode, isFixtureApiKey, httpRequest, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-TPTHVSIG.js';
+export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-TPTHVSIG.js';
 import './chunk-2SFBB54R.js';
 import { configure, submit, list, get, cancel, subscribe } from './chunk-HRA3CPGG.js';
 export { emitRunEvent } from './chunk-HRA3CPGG.js';
-import './chunk-SDYJESYZ.js';
+import './chunk-7BTE3RXJ.js';
 import './chunk-K2BQQ445.js';
-import './chunk-F5RLC6ZH.js';
-import { discoverProviderPlugins, mapOllamaTransportError, mapOllamaHttpError } from './chunk-KT6SWUY6.js';
+import './chunk-VQ6NY4F5.js';
+import { discoverProviderPlugins, mapOllamaTransportError, mapOllamaHttpError } from './chunk-IX2LKBCD.js';
 import './chunk-6CLRANZA.js';
 import './chunk-EEZ7CFMM.js';
 import { lanceStoragePath, LanceIndex, readFactsFromMarkdown, defaultIndexPath, openMemoryDb, memoryDir } from './chunk-XAUBQMQU.js';
@@ -30,7 +30,7 @@ import './chunk-UJ7IQJAG.js';
 import './chunk-7AD3ZTZL.js';
 import './chunk-V4XRLPEF.js';
 import './chunk-5PZMMF4H.js';
-import './chunk-TOVGIP4L.js';
+import './chunk-IPHW3VKP.js';
 import './chunk-UAYYNWYJ.js';
 import './chunk-77FOZCOT.js';
 import { withCwdMutex } from './chunk-2XLKLVVR.js';
@@ -40,7 +40,7 @@ import './chunk-BXV2QUIC.js';
 import { toJsonSchema } from './chunk-4VPXM6UU.js';
 import { replaceFileAtomic } from './chunk-S2BBRVQX.js';
 import './chunk-BNIFFFH3.js';
-import './chunk-GBCQ5742.js';
+import './chunk-RKG6QFCJ.js';
 import { parseModelId } from './chunk-X2FR4OIT.js';
 import { registerBuiltins, listProviders, getCatalogCapabilities, getProviderProfile } from './chunk-KAP4GJHO.js';
 import './chunk-LU7VALW5.js';
@@ -1600,7 +1600,7 @@ function ehAgenteConstruido(m) {
   return typeof m.send === "function";
 }
 async function materializar(def, indice) {
-  const { Agent: Agent2 } = await import('./agent-LIVADAZ4.js');
+  const { Agent: Agent2 } = await import('./agent-EQQA5VGX.js');
   return Agent2.create({
     // `AgentDefinition.model` admite o sentinel `'inherit'`, que não é um id de modelo. Herdar
     // aqui significa "não declare nada e deixe o default valer" — passar o literal adiante criaria

package/dist/{inject-session-343WIDCM.cjs → inject-session-SMH56NXP.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkE33A7YIR_cjs = require('./chunk-E33A7YIR.cjs');
+var chunkG4WI3VW2_cjs = require('./chunk-G4WI3VW2.cjs');
 var chunkIT3PWBW4_cjs = require('./chunk-IT3PWBW4.cjs');
 var chunk2DYI7MIF_cjs = require('./chunk-2DYI7MIF.cjs');
 require('./chunk-TIZ4TS5V.cjs');
@@ -8,7 +8,7 @@ require('./chunk-BEURCLDV.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkE33A7YIR_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkG4WI3VW2_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
     const transcript = chunk2DYI7MIF_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-343WIDCM.cjs.map
-//# sourceMappingURL=inject-session-343WIDCM.cjs.map
+//# sourceMappingURL=inject-session-SMH56NXP.cjs.map
+//# sourceMappingURL=inject-session-SMH56NXP.cjs.map

package/dist/{inject-session-343WIDCM.cjs.map → inject-session-SMH56NXP.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-343WIDCM.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-SMH56NXP.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-RZEDWO53.js → inject-session-V5FTK72N.js}

@@ -1,4 +1,4 @@
-import { enqueueSessionWrite } from './chunk-SDYJESYZ.js';
+import { enqueueSessionWrite } from './chunk-7BTE3RXJ.js';
 import { invalidateSessionCache } from './chunk-EEZ7CFMM.js';
 import { SessionTranscript } from './chunk-Q56IYTBZ.js';
 import './chunk-S2BBRVQX.js';
@@ -21,5 +21,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-RZEDWO53.js.map
-//# sourceMappingURL=inject-session-RZEDWO53.js.map
+//# sourceMappingURL=inject-session-V5FTK72N.js.map
+//# sourceMappingURL=inject-session-V5FTK72N.js.map

package/dist/{inject-session-RZEDWO53.js.map → inject-session-V5FTK72N.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-RZEDWO53.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-V5FTK72N.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/internal/persistence/fs-session-store.d.cts

@@ -31,6 +31,21 @@ export declare class FsSessionStore implements SessionStore {
     constructor(options: FsSessionStoreOptions);
     readRecords(agentId: string): Promise<SessionRecord[]>;
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Toma o lease de escritor da sessão. Lança `SessionBusyError` quando outro processo a detém.
+     *
+     * **Explícito, e NÃO no `appendRecords`** — a revisão adversarial do M95 mediu por que isso
+     * importa: o contrato de `SessionStore` diz que "an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write)". Adquirir ali fazia o `SessionBusyError`
+     * ser **engolido**, e o resultado era pior que o problema original: em vez de dois escritores
+     * intercalarem linhas, o perdedor **perdia o turno em silêncio** — nada em disco, um aviso em
+     * stderr invisível sob a TUI, e o chamador sem como reagir.
+     *
+     * No init o erro chega a quem pode agir: o `exec` forka para um id novo, que é o que a própria
+     * mensagem do erro prescreve. É a diferença entre falhar onde dá para decidir e falhar onde só
+     * dá para perder.
+     */
+    acquire(agentId: string): Promise<void>;
     /**
      * Solta todo lease que este store detém.
      *

package/dist/internal/persistence/fs-session-store.d.ts

@@ -31,6 +31,21 @@ export declare class FsSessionStore implements SessionStore {
     constructor(options: FsSessionStoreOptions);
     readRecords(agentId: string): Promise<SessionRecord[]>;
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Toma o lease de escritor da sessão. Lança `SessionBusyError` quando outro processo a detém.
+     *
+     * **Explícito, e NÃO no `appendRecords`** — a revisão adversarial do M95 mediu por que isso
+     * importa: o contrato de `SessionStore` diz que "an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write)". Adquirir ali fazia o `SessionBusyError`
+     * ser **engolido**, e o resultado era pior que o problema original: em vez de dois escritores
+     * intercalarem linhas, o perdedor **perdia o turno em silêncio** — nada em disco, um aviso em
+     * stderr invisível sob a TUI, e o chamador sem como reagir.
+     *
+     * No init o erro chega a quem pode agir: o `exec` forka para um id novo, que é o que a própria
+     * mensagem do erro prescreve. É a diferença entre falhar onde dá para decidir e falhar onde só
+     * dá para perder.
+     */
+    acquire(agentId: string): Promise<void>;
     /**
      * Solta todo lease que este store detém.
      *

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

@@ -54,11 +54,21 @@ export interface SessionWriterLease {
  * processes, not just across async tasks in one process.
  */
 /**
- * Janela de heartbeat: um lock mais velho que isto é considerado obsoleto.
+ * Janela de obsolescência **entre máquinas** — e só entre elas.
  *
- * 30 s. Curta o bastante para não trancar o usuário por minutos depois de um crash; longa o
- * bastante para não reclamar o lock de um processo vivo que só está lento em I/O. O dono toca o
- * arquivo a cada aquisição, então um processo ativo nunca cruza a janela.
+ * 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.
+ *
+ * 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.
+ *
+ * **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.
  */
 export declare const JANELA_DE_HEARTBEAT_MS = 30000;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

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

@@ -54,11 +54,21 @@ export interface SessionWriterLease {
  * processes, not just across async tasks in one process.
  */
 /**
- * Janela de heartbeat: um lock mais velho que isto é considerado obsoleto.
+ * Janela de obsolescência **entre máquinas** — e só entre elas.
  *
- * 30 s. Curta o bastante para não trancar o usuário por minutos depois de um crash; longa o
- * bastante para não reclamar o lock de um processo vivo que só está lento em I/O. O dono toca o
- * arquivo a cada aquisição, então um processo ativo nunca cruza a janela.
+ * 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.
+ *
+ * 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.
+ *
+ * **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.
  */
 export declare const JANELA_DE_HEARTBEAT_MS = 30000;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/persistence.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkPNVDQL5Y_cjs = require('./chunk-PNVDQL5Y.cjs');
-var chunkNEPJ3TC4_cjs = require('./chunk-NEPJ3TC4.cjs');
+var chunkJYMBHNNU_cjs = require('./chunk-JYMBHNNU.cjs');
 var chunkCJVMDRQB_cjs = require('./chunk-CJVMDRQB.cjs');
 var chunkJD74LN7R_cjs = require('./chunk-JD74LN7R.cjs');
 var chunkYLQQX5W2_cjs = require('./chunk-YLQQX5W2.cjs');
@@ -83,11 +83,11 @@ Object.defineProperty(exports, "PersistenceSchema", {
 });
 Object.defineProperty(exports, "SessionBusyError", {
   enumerable: true,
-  get: function () { return chunkNEPJ3TC4_cjs.SessionBusyError; }
+  get: function () { return chunkJYMBHNNU_cjs.SessionBusyError; }
 });
 Object.defineProperty(exports, "acquireSessionWriter", {
   enumerable: true,
-  get: function () { return chunkNEPJ3TC4_cjs.acquireSessionWriter; }
+  get: function () { return chunkJYMBHNNU_cjs.acquireSessionWriter; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,

package/dist/persistence.js

@@ -1,5 +1,5 @@
 export { PersistenceSchema } from './chunk-CAH3G4IS.js';
-export { SessionBusyError, acquireSessionWriter } from './chunk-TOVGIP4L.js';
+export { SessionBusyError, acquireSessionWriter } from './chunk-IPHW3VKP.js';
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from './chunk-UAYYNWYJ.js';
 export { applyWalWithFallback, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from './chunk-77FOZCOT.js';
 export { withCwdMutex } from './chunk-2XLKLVVR.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.33.1",
+  "version": "4.34.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",

package/dist/chunk-2BYBFBNH.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/persistence/fs-session-store.ts"],"names":["acquireSessionWriter","readTranscript","transcriptPath","path","mkdir","dirname","withFileLock","appendJsonl"],"mappings":";;;;;;;;AAyDA,IAAM,cAAA,uBAAqB,GAAA,EAAyD;AAEpF,eAAe,sBAAsB,IAAA,EAA2C;AAC9E,EAAA,MAAM,SAAA,GAAY,cAAA,CAAe,GAAA,CAAI,IAAI,CAAA;AACzC,EAAA,IAAI,cAAc,MAAA,EAAW;AAC3B,IAAA,SAAA,CAAU,IAAA,EAAA;AACV,IAAA,OAAO,WAAW,IAAI,CAAA;AAAA,EACxB;AACA,EAAA,MAAM,KAAA,GAAQ,MAAMA,sCAAA,CAAqB,IAAI,CAAA;AAC7C,EAAA,cAAA,CAAe,IAAI,IAAA,EAAM,EAAE,KAAA,EAAO,IAAA,EAAM,GAAG,CAAA;AAC3C,EAAA,OAAO,WAAW,IAAI,CAAA;AACxB;AAGA,SAAS,WAAW,IAAA,EAAkC;AACpD,EAAA,IAAI,KAAA,GAAQ,KAAA;AACZ,EAAA,OAAO;AAAA,IACL,WAAA,EAAa,IAAA;AAAA,IACb,SAAS,YAA2B;AAClC,MAAA,IAAI,KAAA,EAAO;AACX,MAAA,KAAA,GAAQ,IAAA;AACR,MAAA,MAAM,OAAA,GAAU,cAAA,CAAe,GAAA,CAAI,IAAI,CAAA;AACvC,MAAA,IAAI,YAAY,MAAA,EAAW;AAC3B,MAAA,OAAA,CAAQ,IAAA,EAAA;AACR,MAAA,IAAI,OAAA,CAAQ,OAAO,CAAA,EAAG;AACtB,MAAA,cAAA,CAAe,OAAO,IAAI,CAAA;AAC1B,MAAA,MAAM,OAAA,CAAQ,MAAM,OAAA,EAAQ;AAAA,IAC9B;AAAA,GACF;AACF;AAEO,IAAM,iBAAN,MAA6C;AAAA,EACzC,QAAA;AAAA,EACA,IAAA;AAAA;AAAA,EAEA,OAAA,uBAAc,GAAA,EAAgC;AAAA,EAEvD,YAAY,OAAA,EAAgC;AAC1C,IAAA,IAAA,CAAK,WAAW,OAAA,CAAQ,OAAA;AACxB,IAAA,IAAA,CAAK,OAAO,OAAA,CAAQ,GAAA;AAAA,EACtB;AAAA,EAEA,MAAM,YAAY,OAAA,EAA2C;AAC3D,IAAA,OAAOC,iCAAeC,gCAAA,CAAe,IAAA,CAAK,UAAU,IAAA,CAAK,IAAA,EAAM,OAAO,CAAC,CAAA;AAAA,EACzE;AAAA,EAEA,MAAM,aAAA,CAAc,OAAA,EAAiB,OAAA,EAAkD;AAErF,IAAA,IAAI,OAAA,CAAQ,WAAW,CAAA,EAAG;AAC1B,IAAA,MAAMC,SAAOD,gCAAA,CAAe,IAAA,CAAK,QAAA,EAAU,IAAA,CAAK,MAAM,OAAO,CAAA;AAE7D,IAAA,MAAME,eAAMC,YAAA,CAAQF,MAAI,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAK9C,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,GAAA,CAAI,OAAO,CAAA,EAAG;AAC9B,MAAA,IAAA,CAAK,QAAQ,GAAA,CAAI,OAAA,EAAS,MAAM,qBAAA,CAAsBA,MAAI,CAAC,CAAA;AAAA,IAC7D;AACA,IAAA,MAAMG,8BAAA,CAAaH,QAAM,YAAY;AAyBnC,MAAA,KAAA,MAAW,MAAA,IAAU,OAAA,EAASI,6BAAA,CAAYJ,MAAA,EAAM,MAAM,CAAA;AAAA,IACxD,CAAC,CAAA;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,OAAA,GAAyB;AAC7B,IAAA,MAAM,SAAS,CAAC,GAAG,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AACxC,IAAA,IAAA,CAAK,QAAQ,KAAA,EAAM;AACnB,IAAA,KAAA,MAAW,KAAA,IAAS,MAAA,EAAQ,MAAM,KAAA,CAAM,OAAA,EAAQ;AAAA,EAClD;AACF","file":"chunk-2BYBFBNH.cjs","sourcesContent":["/**\n * SE41 — `FsSessionStore`, the DEFAULT reference implementation of the pluggable\n * {@link SessionStore} seam. It reads and append-writes the native Claude-shaped\n * `.jsonl` transcript at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` — the\n * exact on-disk format SE40 introduced (the file the Claude Code CLI can\n * `--continue`). Omitting `local.sessionStore` resolves to this store, so the\n * default persistence path is byte-identical to SE40 behavior.\n *\n * `readRecords` is `readTranscript(transcriptPath(...))` (a missing session →\n * `[]`, not an error — a fresh agent has no history). `appendRecords` is a TRUE\n * append: it reads the prior records, concatenates the new-turn delta, and\n * rewrites the whole line set atomically under the SE40 cross-process file lock\n * (`writeTranscript` never shrinks — the native format is an append-only\n * `parentUuid` DAG). The parent dir is created BEFORE acquiring the lock because\n * the lock's companion `<path>.lock` file needs an existing parent dir (the SE40\n * `mkdir(dirname)`-before-lock fix).\n *\n * @internal\n */\n\nimport { mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { withFileLock } from \"./file-lock.js\";\nimport { appendJsonl } from \"./jsonl.js\";\nimport { readTranscript, type SessionRecord, transcriptPath } from \"./session-transcript.js\";\nimport { acquireSessionWriter, type SessionWriterLease } from \"./session-writer.js\";\n\n/** Options identifying the on-disk transcript location for the FS default store. */\nexport interface FsSessionStoreOptions {\n  /** Transcript base dir (`~/.theokit` default, `~/.claude` for CLI interop) — already `~`-expanded. */\n  baseDir: string;\n  /** The workspace cwd whose encoded form is the transcript project dir. */\n  cwd: string;\n}\n\n/**\n * The default `SessionStore` — reads/append-writes the native `.jsonl` transcript.\n *\n * @internal\n */\n/**\n * Leases compartilhados por caminho, com contagem de referências.\n *\n * `acquireSessionWriter` é ESTRITO de propósito: duas aquisições concorrentes do mesmo caminho, e\n * exatamente uma vence — \"um lease que deixasse as duas passarem seria decorativo\" (o teste do M81\n * diz isso com todas as letras, e está certo). Esse é o contrato do primitivo, e ele não muda.\n *\n * Mas dentro de UM processo é normal existir mais de um store sobre a mesma sessão: os testes\n * golden de compactação e de sends concorrentes fazem exatamente isso, e são registro de\n * comportamento real do runtime. Aplicar o primitivo cru ali transformaria um padrão legítimo em\n * `SessionBusyError`.\n *\n * A conciliação é aqui, no consumidor do primitivo: o processo tira UM lease por caminho e conta\n * quantos stores o usam. O último a soltar libera de fato. Cross-process continua estrito — que é o\n * problema que o M81 enuncia (\"`exec resume --last` pode escrever na sessão viva da TUI\").\n */\nconst compartilhados = new Map<string, { lease: SessionWriterLease; refs: number }>();\n\nasync function adquirirCompartilhado(path: string): Promise<SessionWriterLease> {\n  const existente = compartilhados.get(path);\n  if (existente !== undefined) {\n    existente.refs++;\n    return criarProxy(path);\n  }\n  const lease = await acquireSessionWriter(path);\n  compartilhados.set(path, { lease, refs: 1 });\n  return criarProxy(path);\n}\n\n/** Um handle que decrementa a contagem; o último a soltar libera o lease de verdade. */\nfunction criarProxy(path: string): SessionWriterLease {\n  let solto = false;\n  return {\n    sessionPath: path,\n    release: async (): Promise<void> => {\n      if (solto) return;\n      solto = true;\n      const entrada = compartilhados.get(path);\n      if (entrada === undefined) return;\n      entrada.refs--;\n      if (entrada.refs > 0) return;\n      compartilhados.delete(path);\n      await entrada.lease.release();\n    },\n  };\n}\n\nexport class FsSessionStore implements SessionStore {\n  readonly #baseDir: string;\n  readonly #cwd: string;\n  /** Um lease por `agentId` — um store serve mais de uma sessão ao longo da vida do processo. */\n  readonly #leases = new Map<string, SessionWriterLease>();\n\n  constructor(options: FsSessionStoreOptions) {\n    this.#baseDir = options.baseDir;\n    this.#cwd = options.cwd;\n  }\n\n  async readRecords(agentId: string): Promise<SessionRecord[]> {\n    return readTranscript(transcriptPath(this.#baseDir, this.#cwd, agentId));\n  }\n\n  async appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void> {\n    // Empty delta → nothing to persist (avoids an unnecessary lock + rewrite).\n    if (records.length === 0) return;\n    const path = transcriptPath(this.#baseDir, this.#cwd, agentId);\n    // mkdir BEFORE the lock: withFileLock's companion `<path>.lock` needs the parent dir.\n    await mkdir(dirname(path), { recursive: true });\n    // M95 — a garantia de escritor único do M81 finalmente LIGADA. Ela existia como\n    // `acquireSessionWriter` e tinha ZERO chamadores de produção desde o dia em que foi escrita;\n    // o roadmap a registrava como entregue. Adquirido no primeiro append (leitura segue livre) e\n    // solto em `dispose()`.\n    if (!this.#leases.has(agentId)) {\n      this.#leases.set(agentId, await adquirirCompartilhado(path));\n    }\n    await withFileLock(path, async () => {\n      // M93 — acrescenta o DELTA em vez de reescrever o arquivo inteiro.\n      //\n      // Antes: `readTranscript` + `writeTranscript` de tudo, por turno. O(n) de I/O **e** de parse a\n      // cada turno, O(n²) por sessão — a nota do consumidor em `agents/lib/session/backtrack.ts`\n      // registra 1,4 MB / 3000 linhas em 200 turnos.\n      //\n      // Correto porque o formato **já é append-only**: o DAG de `parentUuid` não depende da ordem de\n      // linha, e cada registro carrega o próprio pai. `appendJsonl` **já existia no pacote** e tinha um\n      // único chamador (`eval/runner.ts`) — a primitiva estava lá, o store é que a ignorava (rung 4).\n      //\n      // O `withFileLock` permanece — mas a afirmação anterior de que \"ele é o que serializa dois\n      // `appendRecords` concorrentes\" era forte demais, e a revisão adversarial do M93 mediu isso:\n      // removê-lo não reprova nenhum teste. A razão é o próprio parágrafo acima — o DAG de\n      // `parentUuid` não depende da ordem de linha, então dois lotes intercalados reconstroem igual.\n      // O trabalho que o lock fazia (proteger um read-modify-write) sumiu junto com o rewrite.\n      //\n      // O que ele ainda cobre é a janela TOCTOU de `precisaDeQuebraAntes` (ler o último byte, depois\n      // escrever): sem ele, dois processos podem ambos concluir \"falta \\n\" e produzir uma linha em\n      // branco — que o leitor descarta, isto é, benigno. Fica como **defesa declarada, não\n      // mecanizada** (a disciplina de `error-handling.md § 4`: enumerar o resíduo em vez de deixar a\n      // ausência de teste passar por cobertura).\n      //\n      // `writeTranscript` continua existindo para **compactação**, a única operação que legitimamente\n      // reescreve o arquivo.\n      for (const record of records) appendJsonl(path, record);\n    });\n  }\n\n  /**\n   * Solta todo lease que este store detém.\n   *\n   * Sem isto o `.writer.lock` sobrevive ao processo e a próxima abertura teria de esperar a janela\n   * de heartbeat — recuperável, mas 30 s de espera para um encerramento LIMPO seria um defeito\n   * evitável. Idempotente: chamar duas vezes não é erro.\n   */\n  async dispose(): Promise<void> {\n    const leases = [...this.#leases.values()];\n    this.#leases.clear();\n    for (const lease of leases) await lease.release();\n  }\n}\n"]}