@theokit/agents 0.6.0 → 0.8.0

package/dist/{chunk-KTYBQ7HY.js → chunk-BCSRKDP6.js}

@@ -9,6 +9,7 @@ import {
   TOOL_METHODS,
   Trace,
   getAgentConfig,
+  getCompactionConfig,
   getContextWindowConfig,
   getGatewayConfig,
   getMcpConfig,
@@ -18,7 +19,7 @@ import {
   getProjectContextConfig,
   getSkillsConfig,
   getSubAgents
-} from "./chunk-MVEY7HEY.js";
+} from "./chunk-GVPUUKKE.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -205,6 +206,7 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   const contextWindow = getContextWindowConfig(AgentClass);
   const projectContext = getProjectContextConfig(AgentClass);
   warnUnmappedDecoratorKnobs(AgentClass.name, contextWindow, projectContext);
+  const compaction = getCompactionConfig(AgentClass);
   const result = {
     agentConfig,
     mainLoop,
@@ -219,7 +221,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
     skills,
     contextWindow,
     projectContext,
-    mcpServers
+    mcpServers,
+    compaction
   };
   if (toolboxClasses.length === 0) {
     agentWalkCache.set(AgentClass, result);
@@ -694,16 +697,47 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, envModel) {
 }
 __name(createSdkAgentStream, "createSdkAgentStream");
 
-// src/loop/loop-strategy.ts
+// src/loop/compaction-strategy.ts
+import { compactTranscript } from "@theokit/sdk/compaction";
 import { z } from "zod";
+var DEFAULT_KEEP_TOKENS = 8e3;
+var compactionStrategyConfigSchema = z.object({
+  name: z.literal("token-budget"),
+  keepTokens: z.number().int().positive()
+});
+function resolveCompactionStrategy(name, config) {
+  const cfg = compactionStrategyConfigSchema.parse({
+    name,
+    keepTokens: config.keepTokens
+  });
+  return {
+    name: cfg.name,
+    keepTokens: cfg.keepTokens,
+    compact: /* @__PURE__ */ __name((messages, options) => compactTranscript(messages, {
+      keepTokens: options?.keepTokens ?? cfg.keepTokens,
+      summarize: options?.summarize,
+      marker: options?.marker,
+      summaryTemplate: options?.summaryTemplate,
+      // Default-safe: a thrown summarize keeps the transcript (app opts out via failSafe:false).
+      failSafe: options?.failSafe ?? true
+    }), "compact")
+  };
+}
+__name(resolveCompactionStrategy, "resolveCompactionStrategy");
+var tokenBudgetCompactionStrategy = resolveCompactionStrategy("token-budget", {
+  keepTokens: DEFAULT_KEEP_TOKENS
+});
+
+// src/loop/loop-strategy.ts
+import { z as z2 } from "zod";
 var DEFAULT_MAX_ITERATIONS = 8;
-var loopStrategyConfigSchema = z.object({
-  name: z.enum([
+var loopStrategyConfigSchema = z2.object({
+  name: z2.enum([
     "simple-chat",
     "plan-act-reflect",
     "react"
   ]),
-  maxIterations: z.number().int().min(1)
+  maxIterations: z2.number().int().min(1)
 });
 function resolveLoopStrategy(strategy, maxIterations = DEFAULT_MAX_ITERATIONS) {
   const cfg = loopStrategyConfigSchema.parse({
@@ -726,9 +760,9 @@ function resolveLoopStrategy(strategy, maxIterations = DEFAULT_MAX_ITERATIONS) {
 __name(resolveLoopStrategy, "resolveLoopStrategy");
 
 // src/loop/reflection-strategy.ts
-import { z as z2 } from "zod";
-var reflectionStrategyConfigSchema = z2.object({
-  name: z2.string().min(1)
+import { z as z3 } from "zod";
+var reflectionStrategyConfigSchema = z3.object({
+  name: z3.string().min(1)
 });
 var ladderReflectionStrategy = {
   name: "ladder",
@@ -787,14 +821,68 @@ function asNumber(value, fallback) {
   return typeof value === "number" ? value : fallback;
 }
 __name(asNumber, "asNumber");
+var NO_PROGRESS_THRESHOLD = 2;
+var MAINLOOP_METRIC = "[THEO_AGENT_MAINLOOP_RUNTIME_APPLIED]";
+var TOOL_CALLS = "tool-calls";
+var STEP_LIMIT_HINT = "This is your final round \u2014 do not call any more tools; summarize the work done so far and list any remaining tasks.";
+function stableStringify(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const entries = Object.keys(obj).sort((a, b) => a.localeCompare(b)).map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+  return `{${entries.join(",")}}`;
+}
+__name(stableStringify, "stableStringify");
+function roundSignature(toolCalls, text) {
+  const calls = toolCalls.map((tc) => `${tc.name}:${stableStringify(tc.input)}`).sort((a, b) => a.localeCompare(b)).join(",");
+  return `${calls}|${text}`;
+}
+__name(roundSignature, "roundSignature");
+function terminalReason(reflectionContinue, roundReason, round, maxIterations) {
+  if (reflectionContinue && roundReason === TOOL_CALLS && round >= maxIterations) return "step_limit";
+  if (roundReason === TOOL_CALLS) return "stop";
+  return roundReason;
+}
+__name(terminalReason, "terminalReason");
+function buildPrompt(round, maxIterations, message, feedback) {
+  const hint = round === maxIterations ? `${STEP_LIMIT_HINT}
+
+` : "";
+  const body = round === 1 || !feedback ? message : `${message}
+
+[reflection] ${feedback}`;
+  return hint + body;
+}
+__name(buildPrompt, "buildPrompt");
+async function* consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName) {
+  try {
+    return yield* consumeOneRound(factory, prompt, sessionId, signal);
+  } catch (err) {
+    if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
+    throw new DelegationError(agentName, err);
+  }
+}
+__name(consumeRoundOrThrow, "consumeRoundOrThrow");
+function finalize(acc, round, reason, strategyName) {
+  acc.rounds = round;
+  acc.finishReason = reason;
+  console.debug(MAINLOOP_METRIC, {
+    strategy: strategyName,
+    rounds: round,
+    terminal: reason
+  });
+  return acc;
+}
+__name(finalize, "finalize");
 function deriveFinishReason(signals) {
   if (signals.sawError) return "error";
-  if (signals.sawDone && signals.doneFinishReason === "tool-calls") return "tool-calls";
-  if (signals.sawToolResult) return "tool-calls";
+  if (signals.sawDone && signals.doneFinishReason === TOOL_CALLS) return TOOL_CALLS;
+  if (signals.sawToolResult) return TOOL_CALLS;
   return "stop";
 }
 __name(deriveFinishReason, "deriveFinishReason");
-async function consumeOneRound(factory, prompt, sessionId, signal) {
+async function* consumeOneRound(factory, prompt, sessionId, signal) {
   const r = {
     responseText: "",
     toolCalls: [],
@@ -811,6 +899,7 @@ async function consumeOneRound(factory, prompt, sessionId, signal) {
   };
   for await (const event of factory(prompt, sessionId)) {
     if (signal?.aborted) break;
+    yield event;
     if (event.type === "text_delta" && typeof event.content === "string") {
       r.responseText += event.content;
     } else if (event.type === "tool_result") {
@@ -834,7 +923,7 @@ async function consumeOneRound(factory, prompt, sessionId, signal) {
   return r;
 }
 __name(consumeOneRound, "consumeOneRound");
-async function runReflectiveLoop(factory, message, sessionId, config) {
+async function* runReflectiveLoopStream(factory, message, sessionId, config) {
   const { loop, reflection, budget = Number.POSITIVE_INFINITY, signal, agentName = loop.name } = config;
   const acc = {
     response: "",
@@ -845,17 +934,11 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
   };
   let round = 1;
   let feedback;
+  let prevSig;
+  let stuck = 0;
   while (!signal?.aborted) {
-    const prompt = round === 1 || !feedback ? message : `${message}
-
-[reflection] ${feedback}`;
-    let r;
-    try {
-      r = await consumeOneRound(factory, prompt, sessionId, signal);
-    } catch (err) {
-      if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
-      throw new DelegationError(agentName, err);
-    }
+    const prompt = buildPrompt(round, loop.maxIterations, message, feedback);
+    const r = yield* consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName);
     acc.response += r.responseText;
     acc.toolCalls.push(...r.toolCalls);
     acc.cost += r.cost;
@@ -864,6 +947,12 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
     if (Number.isFinite(budget) && acc.cost > budget) {
       throw new BudgetExceededError(agentName, acc.cost, budget);
     }
+    if (r.finishReason === TOOL_CALLS) {
+      const sig = roundSignature(r.toolCalls, r.responseText);
+      stuck = sig === prevSig ? stuck + 1 : 0;
+      if (stuck >= NO_PROGRESS_THRESHOLD) return finalize(acc, round, "no_progress", loop.name);
+      prevSig = sig;
+    }
     const outcome = {
       finishReason: r.finishReason,
       round,
@@ -872,12 +961,8 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
     };
     const reflectionResult = reflection.reflect(outcome);
     if (!(reflectionResult.continue && loop.shouldContinue(outcome))) {
-      acc.rounds = round;
-      console.debug("[THEO_AGENT_MAINLOOP_RUNTIME_APPLIED]", {
-        strategy: loop.name,
-        rounds: round
-      });
-      return acc;
+      const reason = terminalReason(reflectionResult.continue, r.finishReason, round, loop.maxIterations);
+      return finalize(acc, round, reason, loop.name);
     }
     feedback = reflectionResult.feedback;
     round += 1;
@@ -885,6 +970,13 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
   acc.rounds = round - 1;
   return acc;
 }
+__name(runReflectiveLoopStream, "runReflectiveLoopStream");
+async function runReflectiveLoop(factory, message, sessionId, config) {
+  const gen = runReflectiveLoopStream(factory, message, sessionId, config);
+  let res = await gen.next();
+  while (!res.done) res = await gen.next();
+  return res.value;
+}
 __name(runReflectiveLoop, "runReflectiveLoop");
 
 // src/loop/agent-runner.ts
@@ -894,25 +986,47 @@ var AgentRunner = class {
   }
   compiled;
   agentName;
+  /** The resolved terminal-decision strategy (parity with `delegate()`). */
   loopStrategy;
+  /** The resolved between-round reflection (default or `.reflection(custom)` override). */
   reflectionStrategy;
+  /**
+  * Recorded streaming preference. The reflective loop currently always streams via
+  * the SDK `Run.stream()`; a non-streaming collect mode is future work — the flag is
+  * captured + exposed here, not yet branched on (honest per G10: documented, not a
+  * silent no-op).
+  */
   streamEnabled;
-  constructor(compiled, agentName, loopStrategy, reflectionStrategy, streamEnabled) {
-    this.compiled = compiled;
-    this.agentName = agentName;
-    this.loopStrategy = loopStrategy;
-    this.reflectionStrategy = reflectionStrategy;
-    this.streamEnabled = streamEnabled;
+  /**
+  * V4-F: the resolved compaction strategy (from `@Compaction` or `.compaction()`),
+  * or `undefined` when neither is declared — compaction is opt-in (EC-4). CALLABLE
+  * by the app (ADR D1: `runner.compaction?.compact(messages, { summarize })`); the
+  * reflective loop does NOT auto-invoke it (the SDK owns per-turn context).
+  */
+  compaction;
+  constructor(state) {
+    this.compiled = state.compiled;
+    this.agentName = state.agentName;
+    this.loopStrategy = state.loopStrategy;
+    this.reflectionStrategy = state.reflectionStrategy;
+    this.streamEnabled = state.streamEnabled;
+    this.compaction = state.compaction;
   }
   /** Start a fluent builder for `AgentClass`. */
   static builder(AgentClass) {
     return new AgentRunnerBuilder(AgentClass);
   }
-  /** Run the agent to a terminal result via the shared reflective loop. */
-  run(message, opts) {
+  /**
+  * V4-D-stream: stream the agent's events LIVE across the reflective loop, returning
+  * the aggregated {@link DelegationResult} as the generator's return value. This is the
+  * on-ramp for streaming-first apps (SSE) — `runReflectiveLoopStream` yields every
+  * round's events before the loop terminates. `streamEnabled` is honored: when the
+  * builder set `.stream(false)`, callers should use {@link run} instead.
+  */
+  stream(message, opts) {
     const streamFactory = createSdkAgentStream(this.compiled, this.compiled.tools, opts.apiKey, this.compiled.model);
     const sessionId = opts.sessionId ?? `runner-${crypto.randomUUID()}`;
-    return runReflectiveLoop(streamFactory, message, sessionId, {
+    return runReflectiveLoopStream(streamFactory, message, sessionId, {
       loop: this.loopStrategy,
       reflection: this.reflectionStrategy,
       budget: opts.budget,
@@ -920,6 +1034,13 @@ var AgentRunner = class {
       signal: opts.signal
     });
   }
+  /** Run the agent to a terminal result via the shared reflective loop (collect mode). */
+  async run(message, opts) {
+    const gen = this.stream(message, opts);
+    let res = await gen.next();
+    while (!res.done) res = await gen.next();
+    return res.value;
+  }
 };
 var AgentRunnerBuilder = class {
   static {
@@ -928,6 +1049,7 @@ var AgentRunnerBuilder = class {
   AgentClass;
   reflectionOverride;
   streamEnabled = true;
+  compactionOverride;
   constructor(AgentClass) {
     this.AgentClass = AgentClass;
   }
@@ -941,6 +1063,18 @@ var AgentRunnerBuilder = class {
     this.streamEnabled = enabled;
     return this;
   }
+  /**
+  * V4-F: declare the compaction strategy (e.g. `.compaction('token-budget', { keepTokens: 8000 })`).
+  * Resolved + validated at {@link build} (EC-5 — fail-fast there, not here). This builder
+  * call WINS over a `@Compaction` decorator on the same agent (EC-1 — explicit override).
+  */
+  compaction(name, options = {}) {
+    this.compactionOverride = {
+      name,
+      keepTokens: options.keepTokens
+    };
+    return this;
+  }
   /** Walk + compile + resolve strategies — the compile→execute boundary (no I/O). */
   build() {
     const walk = walkAgentMetadata(this.AgentClass, []);
@@ -951,7 +1085,18 @@ var AgentRunnerBuilder = class {
     const compiled = compileAgent(walk, toolboxInstances);
     const loopStrategy = resolveLoopStrategy(walk.mainLoop.strategy, walk.mainLoop.maxIterations);
     const reflectionStrategy = this.reflectionOverride ?? (walk.mainLoop.strategy === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
-    return new AgentRunner(compiled, walk.agentConfig.name, loopStrategy, reflectionStrategy, this.streamEnabled);
+    const compactionDecl = this.compactionOverride ?? walk.compaction;
+    const compaction = compactionDecl ? resolveCompactionStrategy(compactionDecl.name, {
+      keepTokens: compactionDecl.keepTokens
+    }) : void 0;
+    return new AgentRunner({
+      compiled,
+      agentName: walk.agentConfig.name,
+      loopStrategy,
+      reflectionStrategy,
+      streamEnabled: this.streamEnabled,
+      compaction
+    });
   }
 };
 
@@ -1143,6 +1288,10 @@ export {
   generateAgentRoutes,
   translateSdkEvent,
   createSdkAgentStream,
+  DEFAULT_KEEP_TOKENS,
+  compactionStrategyConfigSchema,
+  resolveCompactionStrategy,
+  tokenBudgetCompactionStrategy,
   DEFAULT_MAX_ITERATIONS,
   loopStrategyConfigSchema,
   resolveLoopStrategy,
@@ -1157,4 +1306,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-KTYBQ7HY.js.map
+//# sourceMappingURL=chunk-BCSRKDP6.js.map