@theokit/agents 0.7.0 → 0.9.0

package/dist/{bridge-entry-CIwzw_3z.d.ts → bridge-entry-Dt3Fr6md.d.ts}

@@ -1,5 +1,5 @@
 import { ExecutionContext } from '@theokit/http';
-import { A as AgentOptions, T as ToolOptions, e as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, d as GatewayOptions, j as MemoryOptions, q as SkillsOptions, c as ContextWindowOptions, o as ProjectContextOptions, h as McpServersMap } from './skills-DnfvEUSg.js';
+import { A as AgentOptions, T as ToolOptions, g as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, f as GatewayOptions, l as MemoryOptions, s as SkillsOptions, e as ContextWindowOptions, q as ProjectContextOptions, j as McpServersMap, b as CompactionDecoratorConfig } from './skills-BHnHPn7p.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver } from '@theokit/sdk';
 import { z } from 'zod';
 
@@ -63,6 +63,7 @@ interface AgentWalkResult {
     contextWindow?: ContextWindowOptions;
     projectContext?: ProjectContextOptions;
     mcpServers?: McpServersMap;
+    compaction?: CompactionDecoratorConfig;
 }
 interface ToolboxWalkResult {
     class: Function;
@@ -621,4 +622,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { isApprovalRequired as $, type AgentExecutionContext as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type ToolCallEvent as G, type ToolResultEvent as H, type IterationEvent as I, type ToolWalkResult as J, type ToolboxWalkResult as K, type LoopOutcome as L, agentsPlugin as M, compileAgent as N, compileContextWindow as O, compileProjectContext as P, compileSkills as Q, type RunStartedEvent as R, type SdkMessage as S, type TextDeltaEvent as T, compileTools as U, createAgentExecutionContext as V, createSdkAgentStream as W, delegate as X, generateAgentManifest as Y, generateAgentRoutes as Z, isAgentContext as _, type LoopStrategy as a, isDone as a0, isError as a1, isTextDelta as a2, isToolCall as a3, isToolResult as a4, loopStrategyConfigSchema as a5, projectContextMetadataOnlyKnobs as a6, resolveLoopStrategy as a7, streamAgentResponse as a8, translateSdkEvent as a9, validateUniqueRoutes as aa, walkAgentMetadata as ab, type AgentManifest as b, type AgentManifestEntry as c, type AgentManifestTool as d, type AgentRoute as e, type AgentRouteContext as f, type AgentRunInfo as g, type AgentStreamEvent as h, type AgentWalkResult as i, AgentWarningCode as j, type AgentsPluginOptions as k, type ApprovalRequiredEvent as l, type ArtifactChunkEvent as m, type ArtifactStartEvent as n, type CheckpointSavedEvent as o, type CompiledContextWindow as p, type CompiledTool as q, DEFAULT_MAX_ITERATIONS as r, type DelegateOptions as s, DelegationError as t, type DoneEvent as u, type LoopFinishReason as v, type LoopStrategyConfig as w, type StateUpdateEvent as x, type StreamEvent as y, type ThinkingEvent as z };
+export { isApprovalRequired as $, type AgentExecutionContext as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type ToolCallEvent as G, type ToolResultEvent as H, type IterationEvent as I, type ToolWalkResult as J, type ToolboxWalkResult as K, type LoopOutcome as L, agentsPlugin as M, compileAgent as N, compileContextWindow as O, compileProjectContext as P, compileSkills as Q, type RunStartedEvent as R, type StreamEvent as S, type TextDeltaEvent as T, compileTools as U, createAgentExecutionContext as V, createSdkAgentStream as W, delegate as X, generateAgentManifest as Y, generateAgentRoutes as Z, isAgentContext as _, type LoopStrategy as a, isDone as a0, isError as a1, isTextDelta as a2, isToolCall as a3, isToolResult as a4, loopStrategyConfigSchema as a5, projectContextMetadataOnlyKnobs as a6, resolveLoopStrategy as a7, streamAgentResponse as a8, translateSdkEvent as a9, validateUniqueRoutes as aa, walkAgentMetadata as ab, type CompiledTool as b, type AgentManifest as c, type AgentManifestEntry as d, type AgentManifestTool as e, type AgentRoute as f, type AgentRouteContext as g, type AgentRunInfo as h, type AgentStreamEvent as i, type AgentWalkResult as j, AgentWarningCode as k, type AgentsPluginOptions as l, type ApprovalRequiredEvent as m, type ArtifactChunkEvent as n, type ArtifactStartEvent as o, type CheckpointSavedEvent as p, type CompiledContextWindow as q, DEFAULT_MAX_ITERATIONS as r, type DelegateOptions as s, DelegationError as t, type DoneEvent as u, type LoopFinishReason as v, type LoopStrategyConfig as w, type SdkMessage as x, type StateUpdateEvent as y, type ThinkingEvent as z };

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
-export { A as AgentExecutionContext, b as AgentManifest, c as AgentManifestEntry, d as AgentManifestTool, e as AgentRoute, f as AgentRouteContext, g as AgentRunInfo, h as AgentStreamEvent, i as AgentWalkResult, j as AgentWarningCode, k as AgentsPluginOptions, l as ApprovalRequiredEvent, m as ArtifactChunkEvent, n as ArtifactStartEvent, B as BudgetExceededError, o as CheckpointSavedEvent, C as CompiledAgentOptions, p as CompiledContextWindow, q as CompiledTool, s as DelegateOptions, t as DelegationError, D as DelegationResult, u as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, R as RunStartedEvent, S as SdkMessage, x as StateUpdateEvent, y as StreamEvent, T as TextDeltaEvent, z as ThinkingEvent, G as ToolCallEvent, H as ToolResultEvent, J as ToolWalkResult, K as ToolboxWalkResult, M as agentsPlugin, N as compileAgent, O as compileContextWindow, P as compileProjectContext, Q as compileSkills, U as compileTools, V as createAgentExecutionContext, W as createSdkAgentStream, X as delegate, Y as generateAgentManifest, Z as generateAgentRoutes, _ as isAgentContext, $ as isApprovalRequired, a0 as isDone, a1 as isError, a2 as isTextDelta, a3 as isToolCall, a4 as isToolResult, a6 as projectContextMetadataOnlyKnobs, a8 as streamAgentResponse, a9 as translateSdkEvent, aa as validateUniqueRoutes, ab as walkAgentMetadata } from './bridge-entry-CIwzw_3z.js';
+export { A as AgentExecutionContext, c as AgentManifest, d as AgentManifestEntry, e as AgentManifestTool, f as AgentRoute, g as AgentRouteContext, h as AgentRunInfo, i as AgentStreamEvent, j as AgentWalkResult, k as AgentWarningCode, l as AgentsPluginOptions, m as ApprovalRequiredEvent, n as ArtifactChunkEvent, o as ArtifactStartEvent, B as BudgetExceededError, p as CheckpointSavedEvent, C as CompiledAgentOptions, q as CompiledContextWindow, b as CompiledTool, s as DelegateOptions, t as DelegationError, D as DelegationResult, u as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, R as RunStartedEvent, x as SdkMessage, y as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, z as ThinkingEvent, G as ToolCallEvent, H as ToolResultEvent, J as ToolWalkResult, K as ToolboxWalkResult, M as agentsPlugin, N as compileAgent, O as compileContextWindow, P as compileProjectContext, Q as compileSkills, U as compileTools, V as createAgentExecutionContext, W as createSdkAgentStream, X as delegate, Y as generateAgentManifest, Z as generateAgentRoutes, _ as isAgentContext, $ as isApprovalRequired, a0 as isDone, a1 as isError, a2 as isTextDelta, a3 as isToolCall, a4 as isToolResult, a6 as projectContextMetadataOnlyKnobs, a8 as streamAgentResponse, a9 as translateSdkEvent, aa as validateUniqueRoutes, ab as walkAgentMetadata } from './bridge-entry-Dt3Fr6md.js';
 import '@theokit/http';
-import './skills-DnfvEUSg.js';
+import './skills-BHnHPn7p.js';
 import 'zod';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -25,8 +25,8 @@ import {
   translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-2MYIZ4OT.js";
-import "./chunk-MVEY7HEY.js";
+} from "./chunk-5FZVMZPG.js";
+import "./chunk-GVPUUKKE.js";
 import "./chunk-7QVYU63E.js";
 export {
   AgentWarningCode,

package/dist/{chunk-2MYIZ4OT.js → chunk-5FZVMZPG.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",
@@ -821,9 +855,9 @@ function buildPrompt(round, maxIterations, message, feedback) {
   return hint + body;
 }
 __name(buildPrompt, "buildPrompt");
-async function consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName) {
+async function* consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName) {
   try {
-    return await consumeOneRound(factory, prompt, sessionId, signal);
+    return yield* consumeOneRound(factory, prompt, sessionId, signal);
   } catch (err) {
     if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
     throw new DelegationError(agentName, err);
@@ -848,7 +882,7 @@ function deriveFinishReason(signals) {
   return "stop";
 }
 __name(deriveFinishReason, "deriveFinishReason");
-async function consumeOneRound(factory, prompt, sessionId, signal) {
+async function* consumeOneRound(factory, prompt, sessionId, signal) {
   const r = {
     responseText: "",
     toolCalls: [],
@@ -865,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") {
@@ -888,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: "",
@@ -897,13 +932,14 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
     tokens: 0,
     rounds: 0
   };
+  const reflectionContext = {};
   let round = 1;
   let feedback;
   let prevSig;
   let stuck = 0;
   while (!signal?.aborted) {
     const prompt = buildPrompt(round, loop.maxIterations, message, feedback);
-    const r = await consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName);
+    const r = yield* consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName);
     acc.response += r.responseText;
     acc.toolCalls.push(...r.toolCalls);
     acc.cost += r.cost;
@@ -924,7 +960,7 @@ async function runReflectiveLoop(factory, message, sessionId, config) {
       toolCalls: r.toolCalls,
       responseText: r.responseText
     };
-    const reflectionResult = reflection.reflect(outcome);
+    const reflectionResult = reflection.reflect(outcome, reflectionContext);
     if (!(reflectionResult.continue && loop.shouldContinue(outcome))) {
       const reason = terminalReason(reflectionResult.continue, r.finishReason, round, loop.maxIterations);
       return finalize(acc, round, reason, loop.name);
@@ -935,6 +971,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
@@ -944,25 +987,50 @@ 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) {
-    const streamFactory = createSdkAgentStream(this.compiled, this.compiled.tools, opts.apiKey, this.compiled.model);
+  /**
+  * 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 tools = opts.tools ? [
+      ...opts.tools
+    ] : this.compiled.tools;
+    const streamFactory = createSdkAgentStream(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,
@@ -970,6 +1038,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 {
@@ -978,6 +1053,7 @@ var AgentRunnerBuilder = class {
   AgentClass;
   reflectionOverride;
   streamEnabled = true;
+  compactionOverride;
   constructor(AgentClass) {
     this.AgentClass = AgentClass;
   }
@@ -991,6 +1067,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, []);
@@ -1001,7 +1089,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
+    });
   }
 };
 
@@ -1193,6 +1292,10 @@ export {
   generateAgentRoutes,
   translateSdkEvent,
   createSdkAgentStream,
+  DEFAULT_KEEP_TOKENS,
+  compactionStrategyConfigSchema,
+  resolveCompactionStrategy,
+  tokenBudgetCompactionStrategy,
   DEFAULT_MAX_ITERATIONS,
   loopStrategyConfigSchema,
   resolveLoopStrategy,
@@ -1207,4 +1310,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-2MYIZ4OT.js.map
+//# sourceMappingURL=chunk-5FZVMZPG.js.map