agentenkit 0.3.0 → 0.4.0

package/dist/core/context.js

@@ -2,6 +2,7 @@ import { generateText } from 'ai';
 import { publish } from './publish.js';
 import { fillTokens, providerMeta, recordCall } from './usage.js';
 import { wireId } from './types.js';
+import { promptHistory, summaryOf } from './messages.js';
 /** Universal context ceiling across all models (§2.6) */
 export const CONTEXT_TOKEN_CEILING = 265_000;
 const DEFAULT_NATIVE_WINDOWS = {
@@ -37,7 +38,7 @@ export const estimateTokens = (content) => Math.ceil(JSON.stringify(content).len
 export async function contextUsage(deps, threadId, model) {
     const budgetTokens = contextBudget(deps, model) - deps.config.contextOutputReserveTokens;
     // The main agent's stream only — a nested run's turns are its own (§2.7)
-    const history = await deps.storage.messages.list(threadId, { agentId: null });
+    const history = promptHistory(await deps.storage.messages.list(threadId, { agentId: null }));
     return {
         usedTokens: history.reduce((sum, m) => sum + estimateTokens(m.content), 0),
         budgetTokens,
@@ -48,31 +49,47 @@ export async function contextUsage(deps, threadId, model) {
 // Returns a history array guaranteed to fit the model's budget. Compaction is
 // durable: the summary is persisted as a Message, so every client and every
 // reconnect replay (§2.2) reconstructs the exact same context.
-export async function compactContext(deps, threadId, model) {
+//
+// The summary records the last message it covers, and the prompt carries the
+// summary and only what came after (see promptHistory), so a thread compacts
+// once each time it grows past the trigger, not on every run.
+export async function compactContext(deps, threadId, model, opts = {}) {
     const budget = contextBudget(deps, model) - deps.config.contextOutputReserveTokens;
     // Scoped to the main agent: unscoped, delegated turns would be compacted
     // into — and then fed back through — the parent's prompt (§2.7)
-    const history = await deps.storage.messages.list(threadId, { agentId: null });
+    const history = promptHistory(await deps.storage.messages.list(threadId, { agentId: null }));
     const total = history.reduce((sum, m) => sum + estimateTokens(m.content), 0);
     if (total <= budget * deps.config.compactionTrigger)
         return history;
     // Keep the most recent tail verbatim ...
-    const tail = [];
+    let tailStart = history.length;
     let tailTokens = 0;
-    for (const m of [...history].reverse()) {
-        if (tailTokens + estimateTokens(m.content) > budget * deps.config.contextTailShare)
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const t = estimateTokens(history[i].content);
+        if (tailTokens + t > budget * deps.config.contextTailShare)
             break;
-        tail.unshift(m);
-        tailTokens += estimateTokens(m.content);
+        tailStart = i;
+        tailTokens += t;
+    }
+    // ... starting at a user turn. Cut anywhere else and the tail can open on a
+    // tool result whose call went into the summary, which no provider accepts.
+    // The first user turn inside the budget, or failing that the last one before.
+    tailStart = userTurnAtOrAfter(history, tailStart);
+    const older = history.slice(0, tailStart);
+    const tail = history.slice(tailStart);
+    const coversUpTo = [...older].reverse().find((m) => !summaryOf(m))?.id;
+    if (!coversUpTo) {
+        // Nothing new to summarize: one turn is larger than the tail's share. It
+        // goes as it is; the estimate is rough, and the provider decides.
+        warnOverBudget(deps, threadId, total, budget);
+        return history;
     }
-    const older = history.slice(0, history.length - tail.length);
-    if (older.length === 0)
-        return history; // single oversized turn — blocked by the input guards above
     // ... and summarize everything before it with a cheap model, named in config
     // so a registry that has never heard of 'gpt-4o-mini' can point this at its
-    // own (§2.6). Naming the key in the error matters: resolveModel throws from
-    // deep inside compaction, on a run that never mentioned this model, so the
-    // bare "Unknown model" says nothing about where it came from.
+    // own (§2.6): the last summary and the turns since, never the whole history
+    // again. Naming the key in the error matters: resolveModel throws from deep
+    // inside compaction, on a run that never mentioned this model, so the bare
+    // "Unknown model" says nothing about where it came from.
     const compactionModel = deps.config.compactionModel;
     let compactor;
     try {
@@ -87,20 +104,23 @@ export async function compactContext(deps, threadId, model) {
         prompt: 'Summarize the following conversation history into a dense context brief ' +
             '(decisions, open threads, key facts) for an AI agent:\n\n' +
             older.map((m) => `${m.role}: ${JSON.stringify(m.content)}`).join('\n'),
+        ...(opts.abortSignal ? { abortSignal: opts.abortSignal } : {}),
     });
     const summary = await deps.storage.messages.append(threadId, {
         role: 'system',
-        content: { type: 'CONTEXT_SUMMARY', text },
+        content: { type: 'CONTEXT_SUMMARY', text, coversUpTo },
     });
     // Compaction is a model call the platform made on its own account (§2.6),
     // so it gets its own priced row like any other (§4). Kind 'compaction' keeps
     // it separable: nobody asked for this call, and it is worth being able to
-    // see what the platform's own housekeeping costs.
+    // see what the platform's own housekeeping costs. It is billed to the run it
+    // served, so it is on that run's bill and under its cap.
     //
     // The cache hit is reported in provider metadata, never in `usage` —
     // attributing without it books every cached prompt at the full input price.
     const meta = rest.providerMetadata ?? rest.experimental_providerMetadata;
-    await recordCall(deps, threadId, {
+    const usageRow = {
+        ...(opts.runId ? { runId: opts.runId } : {}),
         agentId: null,
         kind: 'compaction',
         step: 0,
@@ -109,8 +129,39 @@ export async function compactContext(deps, threadId, model) {
         outcome: 'finished',
         providerMetadata: providerMeta(meta, rest.response),
         ...fillTokens(usage, meta),
-    });
+    };
+    if (opts.ledger)
+        await opts.ledger.record(deps, threadId, usageRow);
+    else
+        await recordCall(deps, threadId, usageRow);
     await publish(deps, threadId, 'CONTEXT_COMPACTED', { summarizedMessages: older.length });
-    return [summary, ...tail];
+    const out = [summary, ...tail];
+    // Still over the window: a tail turn alone is larger than it. The next run
+    // compacts from this summary on, so this never loops; the call goes as it is
+    // and the provider decides, but it is worth saying.
+    warnOverBudget(deps, threadId, out.reduce((sum, m) => sum + estimateTokens(m.content), 0), budget);
+    return out;
+}
+/** Move a tail start onto a user turn: the first one at or after `start`, or
+ *  failing that the last one before it. With no user turn at all, the tail is
+ *  empty. */
+function userTurnAtOrAfter(history, start) {
+    for (let i = start; i < history.length; i += 1)
+        if (history[i].role === 'user')
+            return i;
+    for (let i = Math.min(start, history.length) - 1; i >= 0; i -= 1) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return history.length;
+}
+/** Log a prompt estimated past the whole window. */
+function warnOverBudget(deps, threadId, used, budget) {
+    if (used <= budget)
+        return;
+    const log = (deps.log ?? console);
+    log.warn?.('prompt larger than the context window after compaction', {
+        threadId, estimatedTokens: used, budgetTokens: budget,
+    });
 }
 //# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAkB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEzD,yDAAyD;AACzD,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAE7C,MAAM,sBAAsB,GAA2B;IACrD,QAAQ,EAAE,OAAO;IACjB,aAAa,EAAE,OAAO;IACtB,mBAAmB,EAAE,OAAO;IAC5B,gBAAgB,EAAE,SAAS;CAC5B,CAAC;AAEF;;yDAEyD;AACzD,MAAM,UAAU,aAAa,CAAC,IAAkB,EAAE,KAAa;IAC7D,IAAI,QAA4B,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;IACD,MAAM,MAAM,GACV,QAAQ;QACR,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC;QAClC,sBAAsB,CAAC,KAAK,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC;IACnC,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAC5D,CAAC;AAED;;;iCAGiC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAgB,EAAE,EAAE,CACjD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAEhD;kDACkD;AAClD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAkB,EAClB,QAAgB,EAChB,KAAa;IAEb,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC;IACzF,yEAAyE;IACzE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7F,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1E,YAAY;QACZ,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC;QACzE,QAAQ,EAAE,OAAO,CAAC,MAAM;KACzB,CAAC;AACJ,CAAC;AAcD,8EAA8E;AAC9E,4EAA4E;AAC5E,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAkB,EAClB,QAAgB,EAChB,KAAa,EACb,OAAuB,EAAE;IAEzB,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC;IACnF,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE7F,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB;QAAE,OAAO,OAAO,CAAC;IAEpE,yCAAyC;IACzC,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,UAAU,GAAG,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,gBAAgB;YAAE,MAAM;QAClE,SAAS,GAAG,CAAC,CAAC;QACd,UAAU,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,4EAA4E;IAC5E,2EAA2E;IAC3E,8EAA8E;IAC9E,SAAS,GAAG,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACvE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,yEAAyE;QACzE,kEAAkE;QAClE,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,yDAAyD;IACzD,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;IACpD,IAAI,SAAS,CAAC;IACd,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,0BAA0B;YAC1E,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,YAAY,CAAC;QAClD,KAAK,EAAE,SAAS,CAAC,QAAQ,EAAE;QAC3B,MAAM,EACJ,0EAA0E;YAC1E,2DAA2D;YAC3D,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACxE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE;QAC3D,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE;KACvD,CAAC,CAAC;IAEH,0EAA0E;IAC1E,6EAA6E;IAC7E,0EAA0E;IAC1E,6EAA6E;IAC7E,yDAAyD;IACzD,EAAE;IACF,qEAAqE;IACrE,4EAA4E;IAC5E,MAAM,IAAI,GACP,IAAY,CAAC,gBAAgB,IAAK,IAAY,CAAC,6BAA6B,CAAC;IAChF,MAAM,QAAQ,GAAa;QACzB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,CAAC;QACP,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC;QAC3C,OAAO,EAAE,UAAU;QACnB,gBAAgB,EAAE,YAAY,CAAC,IAAI,EAAG,IAAY,CAAC,QAAQ,CAAC;QAC5D,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC;KAC3B,CAAC;IACF,IAAI,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;;QAC/D,MAAM,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,mBAAmB,EAAE,EAAE,kBAAkB,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzF,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,6EAA6E;IAC7E,oDAAoD;IACpD,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACnG,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;aAEa;AACb,SAAS,iBAAiB,CAAC,OAAqB,EAAE,KAAa;IAC7D,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;IAC1F,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC;AAED,oDAAoD;AACpD,SAAS,cAAc,CAAC,IAAkB,EAAE,QAAgB,EAAE,IAAY,EAAE,MAAc;IACxF,IAAI,IAAI,IAAI,MAAM;QAAE,OAAO;IAC3B,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAoD,CAAC;IACrF,GAAG,CAAC,IAAI,EAAE,CAAC,wDAAwD,EAAE;QACnE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM;KACtD,CAAC,CAAC;AACL,CAAC"}

package/dist/core/deleteThread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deleteThread.d.ts","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D;;;;;;;;;sEASsE;AACtE,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}
+{"version":3,"file":"deleteThread.d.ts","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAM9D;;;;;;;;;sEASsE;AACtE,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAoD7B"}

package/dist/core/deleteThread.js

@@ -1,5 +1,7 @@
 import { publishNotice } from './publish.js';
-import { redriveKey, runIdKey } from './keys.js';
+import { segmentKey } from './segment.js';
+import { attemptsKey, redriveKey, runIdKey } from './keys.js';
+import { closeIfOpen } from './engine.js';
 /** The §3.2 deletion behavior: one call removes the thread and everything
  *  that follows it — messages, events, usage rows, subagent runs — plus the
  *  thread's hot kv keys (state cache, run lock, event seq, retry counter).
@@ -14,21 +16,48 @@ export async function deleteThread(deps, threadId) {
     const thread = await deps.storage.threads.get(threadId);
     if (!thread)
         return { accepted: false, error: 'Thread not found' };
-    if (thread.state === 'RUNNING') {
+    if (thread.state === 'RUNNING' || thread.state === 'QUEUED') {
         return { accepted: false, error: 'Thread has an active run — stop it before deleting' };
     }
+    // The platform's own records for the thread close first (§2.9): a run still
+    // open here can never be worked on again once the thread is gone.
+    const runs = await deps.admin.runs.listByThread(threadId).catch(() => []);
+    for (const run of runs) {
+        if (!run.endedAt)
+            await closeIfOpen(deps, run.id, 'deleted');
+    }
+    // Its run streams go now rather than at their grace window's end. The
+    // record says which it had, so it is read before the cascade takes it.
+    const segments = await deps.storage.events.list(threadId, { types: ['RUN_STARTED'] }).catch(() => []);
     // Cascade: messages, events, usage, runs follow the thread (§3.2)
     await deps.storage.threads.delete(threadId);
+    for (const e of segments) {
+        const { streamId } = e.payload;
+        if (streamId)
+            await deps.streams?.delete(streamId).catch(() => undefined);
+    }
+    // The platform's own history of the thread goes with it: a deleted thread
+    // must not live on in operational views. Best effort, like every admin
+    // write; the caller's data is already gone.
+    await deps.admin.threads.delete(threadId).catch((err) => {
+        (deps.log ?? console).error('admin history of a deleted thread not removed', { threadId, err });
+    });
     // Live UIs subscribed to the thread channel learn it ceased to exist —
     // bus-only notice (seq 0, never persisted: the event log is gone with it)
     await publishNotice(deps, threadId, 'THREAD_DELETED', { threadId });
     // Hot cache cleanup — a deleted thread must not resurrect from kv
     await deps.kv.del(`agent:state:${threadId}`);
     await deps.kv.del(`agent:lock:${threadId}`);
-    await deps.kv.del(`agent:seq:${threadId}`);
-    await deps.kv.del(`agent:attempts:${threadId}`);
+    await deps.kv.del(`agent:seq:${threadId}`); // the counter older releases kept
+    await deps.kv.del(attemptsKey(threadId));
     await deps.kv.del(runIdKey(threadId));
     await deps.kv.del(redriveKey(threadId));
+    // The retry counters are per run, so every run the thread had is swept.
+    for (const run of runs) {
+        await deps.kv.del(attemptsKey(run.id));
+        await deps.kv.del(redriveKey(run.id));
+        await deps.kv.del(segmentKey(run.id));
+    }
     return { accepted: true };
 }
 //# sourceMappingURL=deleteThread.js.map

package/dist/core/deleteThread.js.map

@@ -1 +1 @@
-{"version":3,"file":"deleteThread.js","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD;;;;;;;;;sEASsE;AACtE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAkB,EAClB,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IACnE,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC;IAC1F,CAAC;IAED,kEAAkE;IAClE,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE5C,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEpE,kEAAkE;IAClE,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,eAAe,QAAQ,EAAE,CAAC,CAAC;IAC7C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC5C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,QAAQ,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,QAAQ,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IAExC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"deleteThread.js","sourceRoot":"","sources":["../../src/core/deleteThread.ts"],"names":[],"mappings":"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"}

package/dist/core/engine.d.ts

@@ -1,17 +1,22 @@
 import type { RuntimePorts } from '../ports/runtime.js';
-import type { ExecutionState, ProviderOptions } from './types.js';
+import type { ExecutionState, JobKind, ProviderOptions } from './types.js';
 import type { TokenAttribution } from './usage.js';
 import type { RegisteredAgent } from './agent.js';
 import { type AgentRunState } from './state.js';
 export { countTokens } from './usage.js';
 export { executeStep, isParked, runLoop, type LoopInput, type LoopOutcome, type RunLedger, type StepResult } from './loop.js';
-/** The safety cap (§2.1) must be either absent (unbounded apart from
- *  maxSteps) or a positive number — `0`/negative/NaN would silently disable
- *  the cap and let a run spend without bound. */
+/** A cap (§2.1, §4) is absent, 0 (no cap from this level: the next level's
+ *  applies), or a positive number. A negative or non-finite one is a bug in
+ *  the caller and is refused, never read as "no cap". The same rule as the Go
+ *  runtime, whose zero value can only mean "not set". */
 export declare function validateTokenBudget(value: number | undefined, label: string): void;
 /** Tools the engine treats as destructive: parked behind parkForApproval
  *  (§2.5) instead of executing directly. Purely a marker — see withHitl. */
 export declare function markRequiresConfirmation<T extends object>(t: T): T;
+/** Close a run record that can never be worked on again (§2.9): the thread is
+ *  gone, or a newer run replaced this one. Without this the record stays
+ *  open for ever and every "in flight" count carries it. */
+export declare function closeIfOpen(deps: RuntimePorts, runId: string | undefined, stopReason: FinalizeInput['stopReason']): Promise<void>;
 /** The engine (§2.1, §5.6). Worker-side only — runs are dispatched via the
  *  queue (§2.8) and may outlive any HTTP response.
  *
@@ -23,16 +28,20 @@ export declare function markRequiresConfirmation<T extends object>(t: T): T;
  *  the SDK.
  *
  *  Concurrency: acquires the per-thread run lock (`agent:lock:{threadId}`,
- *  SET NX + lease) before any work — two workers can never run one thread,
- *  and a crashed worker's lock expires instead of blocking forever (§3.4).
- *  Returns 'lock-conflict' when the lock is held, so callers can tell a
- *  genuine no-op apart from a completed run. */
+ *  SET NX + lease) before any work, and renews it while it works — two
+ *  workers can never run one thread, and a crashed worker's lock expires
+ *  instead of blocking forever (§3.4). Returns 'lock-conflict' when the lock
+ *  is held, so callers can tell a genuine no-op apart from a completed run,
+ *  and 'lock-lost' when the lock could not be kept. */
 export interface ExecuteInput {
     threadId: string;
     model: string;
     /** This dispatch's run id (§2.1). A job without one keeps the old
      *  behavior: no staleness check, and no redrive on a lock conflict. */
     runId?: string;
+    /** The job's delivery id (see `RunJob.dispatchId`). Absent on a call that
+     *  did not come off the queue; the lock then makes one up. */
+    dispatchId?: string;
     /** Epoch ms at enqueue, for the queue-wait measurement (§2.9). */
     enqueuedAt?: number;
     /** The run's state (§2.10) — carried so a redrive keeps it. */
@@ -42,15 +51,32 @@ export interface ExecuteInput {
      *  what the caller asked for. */
     costBudgetMicros?: number;
     providerOptions?: ProviderOptions;
+    /** The run's own step cap (§2.1); 0 or absent keeps the config's. */
+    maxSteps?: number;
+    /** Epoch ms of the run's first dispatch (see RunJob.dispatchedAt). */
+    dispatchedAt?: number;
+    /** The caller's tenant (see RunJob.partitionKey). */
+    partitionKey?: string;
+    /** Why the job exists (see RunJob.kind). */
+    kind?: JobKind;
+    /** Aborted when the worker is shutting down. The segment stops at once and
+     *  the job goes back on the queue without spending an attempt: a shutdown
+     *  is not the run's fault. */
+    signal?: AbortSignal;
 }
 /** 'executed'      — this worker ran the segment (or it was a legitimate no-op).
  *  'lock-conflict' — someone else holds the thread's run lock; nothing ran.
- *  'stale'         — a NEWER run owns the thread; this job must do nothing. */
-export type ExecuteOutcome = 'executed' | 'lock-conflict' | 'stale';
+ *  'stale'         — a NEWER run owns the thread; this job must do nothing.
+ *  'lock-lost'     — this worker held the lock and could not keep it; the
+ *                    segment ended early and the job should come back once
+ *                    the lock is free. Every step it finished is persisted. */
+export type ExecuteOutcome = 'executed' | 'lock-conflict' | 'stale' | 'lock-lost';
 export declare function execute(deps: RuntimePorts, agent: RegisteredAgent, input: ExecuteInput): Promise<ExecuteOutcome>;
 export interface FinalizeInput {
     state: ExecutionState;
-    stopReason: 'completed' | 'token_budget' | 'cost_budget' | 'max_steps' | 'cancelled';
+    /** Why the run ended. 'failed' for a failure; 'replaced', 'orphaned' and
+     *  'deleted' close a record that can never be worked on again. */
+    stopReason: 'completed' | 'token_budget' | 'cost_budget' | 'max_steps' | 'cancelled' | 'failed' | 'timeout' | 'replaced' | 'orphaned' | 'deleted';
     tokensUsed: number;
     attribution: TokenAttribution;
     /** generate-text flavor only: publish the final text as one TEXT_RESULT. */
@@ -71,6 +97,10 @@ export interface FinalizeInput {
  *  A budget break is NOT a user stop: the run completes with stopReason
  *  'token_budget' and the usage it actually spent. */
 export declare function finalize(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, f: FinalizeInput): Promise<void>;
+/** Fail a run the queue gave up on (§2.8), when it is still the thread's
+ *  current run and the thread is still waiting on it. False when the run had
+ *  already moved on. Runs under the run lock like every other terminal write. */
+export declare function failLostRun(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, runId: string | undefined, reason: string): Promise<boolean>;
 /** §2.8 failure policy: transient errors redrive through the queue; exhausted
  *  attempts finalize FAILED (hot cache + durable). A user stop is never
  *  retried, and a successful run resets the attempt counter.

package/dist/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AAG3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAWlD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI9H;;iDAEiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlF;AAED;4EAC4E;AAC5E,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAElE;AA6ND;;;;;;;;;;;;;;gDAcgD;AAChD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;qCACiC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;+EAE+E;AAC/E,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,eAAe,GAAG,OAAO,CAAC;AAEpE,wBAAsB,OAAO,CAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC,CAgRzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;sDACkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;sDAMsD;AACtD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAkCf;AA6CD;;;;yEAIyE;AACzE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,EACnB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,IAAI,GAAE,OAAO,OAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAmDf"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"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"}