@theokit/sdk 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.8.0
+
+### Minor Changes
+
+- f2203ed: V3-3 — add a **token-budget mode** + **configurable marker** + **template-driven summarizer** + **opt-in fail-safe** to `@theokit/sdk/compaction`, reaching behavioral parity with theocode's compaction so it can adopt the SDK helper. All additive and default-preserving — no existing `keepRecent` caller, persisted `[[theokit:checkpoint]]` marker, or propagate-on-throw contract changes.
+
+  - `compactTranscript(messages, { keepTokens?, marker?, summaryTemplate?, failSafe?, … })`:
+    - `keepTokens` selects the recent window by accumulated `estimateTokens` (theocode `splitTranscript` semantics; always keeps ≥ 1 turn). Takes precedence over `keepRecent`; in this mode leading system prompts are not specially preserved.
+    - `marker` (default `CHECKPOINT_MARKER`, must be non-empty) lets a consumer use a custom checkpoint sentinel such as a persisted `<conversation-checkpoint>`.
+    - `summarize(older, template)` now receives the summary `template`; `SUMMARY_TEMPLATE` (a 7-section template — Goal/Constraints/Progress/Decisions/Next/Critical/Files) is exported and overridable via `summaryTemplate`.
+    - `failSafe: true` returns the ORIGINAL transcript + a structured warn when the summarizer throws (default still propagates).
+  - `filterFromLatestCheckpoint(messages, { marker?, include? })` — `include: "from"` returns the turns from the latest checkpoint inclusive (default `"after"` unchanged).
+  - `buildCheckpoint(label?, marker?)` — accepts a custom marker (empty marker throws).
+
+  Zero new dependency (token-budget reuses the in-module `estimateTokens`).
+
+## 2.7.0
+
+### Minor Changes
+
+- 96a507f: V3-4 — add `agent.streamToCompletion(message, options?)`, the STREAMING twin of `runToCompletion`. It returns an `AsyncGenerator<SDKMessage, StreamToCompletionResult>` that yields each continuation round's messages LIVE (so a UI can render tool calls + text as they happen across rounds), reusing the exact same terminal policy as the M1 driver — `classifyRound` (`done`/`step_limit`/`no_progress`) + bounded re-prompt + usage aggregation (no new policy; the only difference from `runToCompletion` is surfacing events over `Run.stream()` instead of `Run.wait()`). Local agents only; cloud agents throw `UnsupportedRunOperationError`. Stateful like `runToCompletion`; the STATELESS+streaming combination reconstructs history with `buildReplayHistory` into a fresh session first. The `StreamToCompletionResult` is the generator's return value (read via a manual `next()` loop — a plain `for await...of` discards it). Closes the V3-4 (a) streaming gap; (b) stateless and (c) terminals were already covered by `buildReplayHistory` + `runToCompletion`. Zero new dependency.
+
 ## 2.6.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -3015,6 +3015,18 @@ var init_cloud_agent = __esm({
           "runToCompletion"
         );
       }
+      /**
+       * Cloud agents do not expose the streaming continuation driver (V3-4);
+       * the cloud runtime manages continuation server-side.
+       *
+       * @public
+       */
+      streamToCompletion() {
+        throw new UnsupportedRunOperationError(
+          "Agent.streamToCompletion() is not supported on cloud agents. Cloud runtime manages continuation server-side. Use a local agent.",
+          "streamToCompletion"
+        );
+      }
       /**
        * Personality presets require consistent server-side enforcement that
        * the cloud runtime (pre-release) does not yet provide. Reject explicitly
@@ -14260,7 +14272,15 @@ var init_agent_factory_registry = __esm({
 // src/internal/runtime/lifecycle/run-to-completion.ts
 var run_to_completion_exports = {};
 __export(run_to_completion_exports, {
+  DEFAULT_CONTINUATION_PROMPT: () => DEFAULT_CONTINUATION_PROMPT,
+  DEFAULT_MAX_ROUNDS: () => DEFAULT_MAX_ROUNDS,
+  addUsage: () => addUsage,
+  buildResult: () => buildResult,
   classifyRound: () => classifyRound,
+  continuationTail: () => continuationTail,
+  isEmptyRound: () => isEmptyRound,
+  promptForRound: () => promptForRound,
+  resolveContinuation: () => resolveContinuation,
   runToCompletionImpl: () => runToCompletionImpl
 });
 function isEmptyRound(result) {
@@ -14289,6 +14309,23 @@ function addUsage(acc, u) {
 function buildResult(terminal, rounds, lastResult, usage) {
   return { terminal, rounds, lastResult, ...usage !== void 0 ? { usage } : {} };
 }
+async function continuationTail(round, lastResult, usage, onTruncated, signal) {
+  await onTruncated?.({ round });
+  return signal?.aborted === true ? buildResult("step_limit", round, lastResult, usage) : void 0;
+}
+function resolveContinuation(options) {
+  return {
+    maxRounds: options?.maxRounds ?? DEFAULT_MAX_ROUNDS,
+    continuationPrompt: options?.continuationPrompt ?? DEFAULT_CONTINUATION_PROMPT,
+    onTruncated: options?.onTruncated,
+    signal: options?.signal,
+    sendOptions: options?.sendOptions,
+    state: { usage: void 0, emptyStreak: 0 }
+  };
+}
+function promptForRound(round, message, continuationPrompt) {
+  return round === 0 ? message : continuationPrompt;
+}
 async function stepRound(agent, prompt, sendOptions, round, maxRounds, state2) {
   const run = await agent.send(prompt, sendOptions);
   const result = await run.wait();
@@ -14299,19 +14336,21 @@ async function stepRound(agent, prompt, sendOptions, round, maxRounds, state2) {
   return { next: { usage, emptyStreak }, lastResult: result };
 }
 async function runToCompletionImpl(agent, message, options) {
-  const maxRounds = options?.maxRounds ?? DEFAULT_MAX_ROUNDS;
-  const continuationPrompt = options?.continuationPrompt ?? DEFAULT_CONTINUATION_PROMPT;
-  const { onTruncated, signal, sendOptions } = options ?? {};
-  let state2 = { usage: void 0, emptyStreak: 0 };
+  const cfg = resolveContinuation(options);
+  let state2 = cfg.state;
   for (let round = 0; ; round += 1) {
-    const prompt = round === 0 ? message : continuationPrompt;
-    const outcome = await stepRound(agent, prompt, sendOptions, round, maxRounds, state2);
+    const prompt = promptForRound(round, message, cfg.continuationPrompt);
+    const outcome = await stepRound(agent, prompt, cfg.sendOptions, round, cfg.maxRounds, state2);
     if ("terminal" in outcome) return outcome.terminal;
     state2 = outcome.next;
-    await onTruncated?.({ round });
-    if (signal?.aborted === true) {
-      return buildResult("step_limit", round, outcome.lastResult, state2.usage);
-    }
+    const aborted = await continuationTail(
+      round,
+      outcome.lastResult,
+      state2.usage,
+      cfg.onTruncated,
+      cfg.signal
+    );
+    if (aborted !== void 0) return aborted;
   }
 }
 var DEFAULT_MAX_ROUNDS, DEFAULT_CONTINUATION_PROMPT;
@@ -14322,6 +14361,39 @@ var init_run_to_completion = __esm({
   }
 });
 
+// src/internal/runtime/lifecycle/stream-to-completion.ts
+var stream_to_completion_exports = {};
+__export(stream_to_completion_exports, {
+  streamToCompletionImpl: () => streamToCompletionImpl
+});
+function decideRound(result, round, maxRounds, state2) {
+  const usage = addUsage(state2.usage, result.usage);
+  const decision = classifyRound(result, round, maxRounds, state2.emptyStreak);
+  if (decision !== "continue") return { terminal: buildResult(decision, round, result, usage) };
+  const emptyStreak = isEmptyRound(result) ? state2.emptyStreak + 1 : 0;
+  return { next: { usage, emptyStreak } };
+}
+async function* streamToCompletionImpl(agent, message, options) {
+  const cfg = resolveContinuation(options);
+  let state2 = cfg.state;
+  for (let round = 0; ; round += 1) {
+    const prompt = promptForRound(round, message, cfg.continuationPrompt);
+    const run = await agent.send(prompt, cfg.sendOptions);
+    yield* run.stream();
+    const result = await run.wait();
+    const decision = decideRound(result, round, cfg.maxRounds, state2);
+    if ("terminal" in decision) return decision.terminal;
+    state2 = decision.next;
+    const aborted = await continuationTail(round, result, state2.usage, cfg.onTruncated, cfg.signal);
+    if (aborted !== void 0) return aborted;
+  }
+}
+var init_stream_to_completion = __esm({
+  "src/internal/runtime/lifecycle/stream-to-completion.ts"() {
+    init_run_to_completion();
+  }
+});
+
 // src/internal/runtime/lifecycle/fork-agent.ts
 var fork_agent_exports = {};
 __export(fork_agent_exports, {
@@ -14409,6 +14481,10 @@ function localAgentRunToCompletion(agent, message, options) {
   }
   return run();
 }
+async function* localAgentStreamToCompletion(agent, message, options) {
+  const { streamToCompletionImpl: streamToCompletionImpl2 } = await Promise.resolve().then(() => (init_stream_to_completion(), stream_to_completion_exports));
+  return yield* streamToCompletionImpl2({ send: (m, o) => agent.send(m, o) }, message, options);
+}
 async function localAgentFork(parent, options) {
   const { forkAgentImpl: forkAgentImpl2 } = await Promise.resolve().then(() => (init_fork_agent(), fork_agent_exports));
   const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
@@ -15547,6 +15623,10 @@ var init_local_agent = __esm({
       runToCompletion(message, options) {
         return localAgentRunToCompletion(this, message, options);
       }
+      // biome-ignore format: G8 budget — see runUntil comment above.
+      streamToCompletion(message, options) {
+        return localAgentStreamToCompletion(this, message, options);
+      }
     };
   }
 });