@theokit/agents 0.4.0 → 0.6.0

package/dist/decorators.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentOptions, d as MainLoopOptions, c as MainLoopMeta, T as ToolOptions, n as ToolboxOptions, B as BudgetOptions, k as PolicyHandler, a as ApprovalOptions } from './mcp-yyfC5u7t.js';
-export { G as Gateway, b as GatewayOptions, M as MCP, e as McpServerConfig, f as McpServersMap, g as Memory, h as MemoryOptions, i as MemoryProvider, j as MemoryScope, P as PlatformName, S as SessionStrategy, l as Skills, m as SkillsOptions, o as getGatewayConfig, p as getMcpConfig, q as getMemoryConfig, r as getSkillsConfig, s as resolveSessionId } from './mcp-yyfC5u7t.js';
+import { A as AgentOptions, f as MainLoopOptions, M as MainLoopMeta, T as ToolOptions, r as ToolboxOptions, B as BudgetOptions, m as PolicyHandler, a as ApprovalOptions } from './skills-DmN1HGUb.js';
+export { C as ContextCompactionStrategy, b as ContextWindow, c as ContextWindowOptions, G as Gateway, d as GatewayOptions, I as IndexStrategy, e as MCP, g as McpServerConfig, h as McpServersMap, i as Memory, j as MemoryOptions, k as MemoryProvider, l as MemoryScope, P as PlatformName, n as ProjectContext, o as ProjectContextOptions, R as RelevanceStrategy, S as SessionStrategy, p as Skills, q as SkillsOptions, s as getContextWindowConfig, t as getGatewayConfig, u as getMcpConfig, v as getMemoryConfig, w as getProjectContextConfig, x as getSkillsConfig, y as resolveSessionId } from './skills-DmN1HGUb.js';
 import 'zod';
 
 declare function Agent(options?: Partial<AgentOptions>): ClassDecorator;
@@ -71,22 +71,6 @@ interface HumanInTheLoopOptions {
 declare function HumanInTheLoop(options: HumanInTheLoopOptions): MethodDecorator;
 declare function getHumanInTheLoopConfig(target: Function, propertyKey: string | symbol): HumanInTheLoopOptions | undefined;
 
-type ContextCompactionStrategy = 'truncate-oldest' | 'summarize-oldest' | 'sliding-window' | 'priority-based';
-interface ContextWindowOptions {
-    /** Maximum tokens before compaction triggers. */
-    maxTokens?: number;
-    /** How to compact when maxTokens is exceeded. */
-    compactionStrategy?: ContextCompactionStrategy;
-    /** Always preserve the system prompt during compaction (default: true). */
-    preserveSystemPrompt?: boolean;
-    /** Number of recent messages to always keep intact (default: 10). */
-    preserveLastN?: number;
-    /** Keep all tool results even during compaction (default: true). */
-    preserveToolResults?: boolean;
-}
-declare function ContextWindow(options?: ContextWindowOptions): ClassDecorator;
-declare function getContextWindowConfig(target: Function): ContextWindowOptions | undefined;
-
 /** Override the LLM model for an agent class or a specific tool method. */
 declare const Model: (value: string) => MethodDecorator & ClassDecorator;
 
@@ -191,25 +175,6 @@ type EditFormatType = 'search-replace' | 'unified-diff' | 'full-file' | 'line-ra
 /** Declare the edit format a tool produces. */
 declare const EditFormat: (value: EditFormatType) => MethodDecorator & ClassDecorator;
 
-type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
-type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
-interface ProjectContextOptions {
-    /** Files that mark the project root (searched upward from cwd). */
-    rootMarkers?: string[];
-    /** How to index the codebase for structural understanding. */
-    indexStrategy?: IndexStrategy;
-    /** Maximum files to include in context per request. */
-    maxFilesInContext?: number;
-    /** How to rank file relevance when selecting context. */
-    relevanceStrategy?: RelevanceStrategy;
-    /** Glob patterns to exclude from indexing and context. */
-    ignorePatterns?: string[];
-    /** File extensions to include in indexing (default: all text files). */
-    includeExtensions?: string[];
-}
-declare function ProjectContext(options?: ProjectContextOptions): ClassDecorator;
-declare function getProjectContextConfig(target: Function): ProjectContextOptions | undefined;
-
 /**
  * applyDecorators() — compose multiple decorators into a single reusable decorator.
  *
@@ -245,4 +210,4 @@ declare function applyDecorators(...decorators: AnyDecorator[]): ClassDecorator
 declare function Mixin(...mixinClasses: Function[]): ClassDecorator;
 declare function getMixins(target: Function): Function[];
 
-export { Agent, AgentOptions, ApprovalOptions, Artifact, type ArtifactOptions, type ArtifactResult, Audit, Budget, BudgetOptions, Checkpoint, type CheckpointOptions, type CheckpointState, type CheckpointStorage, type CheckpointStrategy, type CommandPermissions, type CompactionStrategy, type ContextCompactionStrategy, ContextWindow, type ContextWindowOptions, Conversation, type ConversationOptions, type ConversationStorage, EditFormat, type EditFormatType, type FilesystemPermissions, Hook, type HookEntry, type HookPoint, HumanInTheLoop, type HumanInTheLoopOptions, type IndexStrategy, MainLoop, MainLoopMeta, MainLoopOptions, Mixin, Model, Observable, type ObservableEntry, Policy, PolicyHandler, ProjectContext, type ProjectContextOptions, type RelevanceStrategy, RequiresApproval, RequiresCapability, Sandbox, type SandboxOptions, SubAgents, type TimeoutAction, Tool, ToolOptions, Toolbox, ToolboxOptions, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getCheckpointConfig, getContextWindowConfig, getConversationConfig, getHooks, getHooksByPoint, getHumanInTheLoopConfig, getMainLoop, getMixins, getObservableByChannel, getObservables, getProjectContextConfig, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed };
+export { Agent, AgentOptions, ApprovalOptions, Artifact, type ArtifactOptions, type ArtifactResult, Audit, Budget, BudgetOptions, Checkpoint, type CheckpointOptions, type CheckpointState, type CheckpointStorage, type CheckpointStrategy, type CommandPermissions, type CompactionStrategy, Conversation, type ConversationOptions, type ConversationStorage, EditFormat, type EditFormatType, type FilesystemPermissions, Hook, type HookEntry, type HookPoint, HumanInTheLoop, type HumanInTheLoopOptions, MainLoop, MainLoopMeta, MainLoopOptions, Mixin, Model, Observable, type ObservableEntry, Policy, PolicyHandler, RequiresApproval, RequiresCapability, Sandbox, type SandboxOptions, SubAgents, type TimeoutAction, Tool, ToolOptions, Toolbox, ToolboxOptions, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getCheckpointConfig, getConversationConfig, getHooks, getHooksByPoint, getHumanInTheLoopConfig, getMainLoop, getMixins, getObservableByChannel, getObservables, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed };

package/dist/decorators.js

@@ -1,7 +1,6 @@
 import {
   Artifact,
   Checkpoint,
-  ContextWindow,
   Conversation,
   EditFormat,
   Hook,
@@ -9,14 +8,12 @@ import {
   MainLoop,
   Model,
   Observable,
-  ProjectContext,
   Sandbox,
   Tool,
   Toolbox,
   applyDecorators,
   getArtifactConfig,
   getCheckpointConfig,
-  getContextWindowConfig,
   getConversationConfig,
   getHooks,
   getHooksByPoint,
@@ -24,37 +21,40 @@ import {
   getMainLoop,
   getObservableByChannel,
   getObservables,
-  getProjectContextConfig,
   getSandboxConfig,
   getToolConfig,
   getToolMethods,
   getToolboxConfig,
   isCommandAllowed,
   isPathAllowed
-} from "./chunk-VKHDADMG.js";
+} from "./chunk-XWVZS2PQ.js";
 import {
   Agent,
   Audit,
   Budget,
+  ContextWindow,
   Gateway,
   MCP,
   Memory,
   Mixin,
   Policy,
+  ProjectContext,
   RequiresApproval,
   RequiresCapability,
   Skills,
   SubAgents,
   Trace,
   getAgentConfig,
+  getContextWindowConfig,
   getGatewayConfig,
   getMcpConfig,
   getMemoryConfig,
   getMixins,
+  getProjectContextConfig,
   getSkillsConfig,
   getSubAgents,
   resolveSessionId
-} from "./chunk-O4UG4RXE.js";
+} from "./chunk-MVEY7HEY.js";
 import "./chunk-7QVYU63E.js";
 export {
   Agent,

package/dist/index.d.ts

@@ -1,5 +1,200 @@
-export { Agent, Artifact, ArtifactOptions, ArtifactResult, Audit, Budget, Checkpoint, CheckpointOptions, CheckpointState, CheckpointStorage, CheckpointStrategy, CommandPermissions, CompactionStrategy, ContextCompactionStrategy, ContextWindow, ContextWindowOptions, Conversation, ConversationOptions, ConversationStorage, EditFormat, EditFormatType, FilesystemPermissions, Hook, HookEntry, HookPoint, HumanInTheLoop, HumanInTheLoopOptions, IndexStrategy, MainLoop, Mixin, Model, Observable, ObservableEntry, Policy, ProjectContext, ProjectContextOptions, RelevanceStrategy, RequiresApproval, RequiresCapability, Sandbox, SandboxOptions, SubAgents, TimeoutAction, Tool, Toolbox, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getCheckpointConfig, getContextWindowConfig, getConversationConfig, getHooks, getHooksByPoint, getHumanInTheLoopConfig, getMainLoop, getMixins, getObservableByChannel, getObservables, getProjectContextConfig, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed } from './decorators.js';
-export { A as AgentOptions, a as ApprovalOptions, B as BudgetOptions, G as Gateway, b as GatewayOptions, M as MCP, c as MainLoopMeta, d as MainLoopOptions, e as McpServerConfig, f as McpServersMap, g as Memory, h as MemoryOptions, i as MemoryProvider, j as MemoryScope, P as PlatformName, k as PolicyHandler, S as SessionStrategy, l as Skills, m as SkillsOptions, T as ToolOptions, n as ToolboxOptions, o as getGatewayConfig, p as getMcpConfig, q as getMemoryConfig, r as getSkillsConfig, s as resolveSessionId } from './mcp-yyfC5u7t.js';
-export { AgentExecutionContext, AgentManifest, AgentManifestEntry, AgentManifestTool, AgentRoute, AgentRouteContext, AgentRunInfo, AgentStreamEvent, AgentWalkResult, AgentWarningCode, AgentsPluginOptions, ApprovalRequiredEvent, ArtifactChunkEvent, ArtifactStartEvent, BudgetExceededError, CheckpointSavedEvent, CompiledAgentOptions, CompiledTool, DelegateOptions, DelegationError, DelegationResult, DoneEvent, ErrorEvent, FileEditEvent, IterationEvent, RunStartedEvent, SdkMessage, StateUpdateEvent, StreamEvent, TextDeltaEvent, ThinkingEvent, ToolCallEvent, ToolResultEvent, ToolWalkResult, ToolboxWalkResult, agentsPlugin, compileAgent, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata } from './bridge.js';
-import 'zod';
+export { Agent, Artifact, ArtifactOptions, ArtifactResult, Audit, Budget, Checkpoint, CheckpointOptions, CheckpointState, CheckpointStorage, CheckpointStrategy, CommandPermissions, CompactionStrategy, Conversation, ConversationOptions, ConversationStorage, EditFormat, EditFormatType, FilesystemPermissions, Hook, HookEntry, HookPoint, HumanInTheLoop, HumanInTheLoopOptions, MainLoop, Mixin, Model, Observable, ObservableEntry, Policy, RequiresApproval, RequiresCapability, Sandbox, SandboxOptions, SubAgents, TimeoutAction, Tool, Toolbox, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getCheckpointConfig, getConversationConfig, getHooks, getHooksByPoint, getHumanInTheLoopConfig, getMainLoop, getMixins, getObservableByChannel, getObservables, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed } from './decorators.js';
+import { M as MainLoopMeta } from './skills-DmN1HGUb.js';
+export { A as AgentOptions, a as ApprovalOptions, B as BudgetOptions, C as ContextCompactionStrategy, b as ContextWindow, c as ContextWindowOptions, G as Gateway, d as GatewayOptions, I as IndexStrategy, e as MCP, f as MainLoopOptions, g as McpServerConfig, h as McpServersMap, i as Memory, j as MemoryOptions, k as MemoryProvider, l as MemoryScope, P as PlatformName, m as PolicyHandler, n as ProjectContext, o as ProjectContextOptions, R as RelevanceStrategy, S as SessionStrategy, p as Skills, q as SkillsOptions, T as ToolOptions, r as ToolboxOptions, s as getContextWindowConfig, t as getGatewayConfig, u as getMcpConfig, v as getMemoryConfig, w as getProjectContextConfig, x as getSkillsConfig, y as resolveSessionId } from './skills-DmN1HGUb.js';
+import { CompiledAgentOptions, DelegationResult } from './bridge.js';
+export { AgentExecutionContext, AgentManifest, AgentManifestEntry, AgentManifestTool, AgentRoute, AgentRouteContext, AgentRunInfo, AgentStreamEvent, AgentWalkResult, AgentWarningCode, AgentsPluginOptions, ApprovalRequiredEvent, ArtifactChunkEvent, ArtifactStartEvent, BudgetExceededError, CheckpointSavedEvent, CompiledContextWindow, CompiledTool, DelegateOptions, DelegationError, DoneEvent, ErrorEvent, FileEditEvent, IterationEvent, RunStartedEvent, SdkMessage, StateUpdateEvent, StreamEvent, TextDeltaEvent, ThinkingEvent, ToolCallEvent, ToolResultEvent, ToolWalkResult, ToolboxWalkResult, agentsPlugin, compileAgent, compileContextWindow, compileProjectContext, compileSkills, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, projectContextMetadataOnlyKnobs, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata } from './bridge.js';
+import { z } from 'zod';
 import '@theokit/http';
+import '@theokit/sdk';
+
+/**
+ * LoopStrategy — the per-round terminal-decision contract that gives runtime to
+ * `@MainLoop({ strategy })`.
+ *
+ * V4-A proved `@MainLoop`'s `strategy` field was metadata-only (declared +
+ * compiled, never executed). This module is the foundation Phase 2's
+ * `runReflectiveLoop` branches on. Modeled on Mastra's `agentic-loop`/`stopWhen`
+ * (inverted) + `maxSteps` ceiling — NOT Spring's per-call Advisor (plan ADR D1).
+ * Config is Zod-validated so an invalid `maxIterations` fails fast at resolve
+ * time, never as a silent infinite loop at runtime (plan ADR D3).
+ *
+ * referencia: knowledge-base/references/mastra agentic-loop/index.ts (stopWhen + maxSteps).
+ */
+
+/** Why a single round ended. Derived in the bridge from the SDK stream events. */
+type LoopFinishReason = 'tool-calls' | 'stop' | 'length' | 'error';
+/** Value object describing one round's result. */
+interface LoopOutcome {
+    /** Why the round ended (the continuation signal). */
+    readonly finishReason: LoopFinishReason;
+    /** 1-indexed round number that just completed. */
+    readonly round: number;
+    /** Tool calls executed during the round. */
+    readonly toolCalls: readonly {
+        name: string;
+        input: unknown;
+        output: string;
+    }[];
+    /** Accumulated assistant text for the round. */
+    readonly responseText: string;
+}
+/** The terminal-decision contract. `shouldContinue` is the inverted `stopWhen`. */
+interface LoopStrategy {
+    /** The originating `@MainLoop` strategy name. */
+    readonly name: MainLoopMeta['strategy'];
+    /** Hard ceiling on rounds — guarantees termination. */
+    readonly maxIterations: number;
+    /** True ⇒ re-enter for another round; false ⇒ terminate. Never true forever. */
+    shouldContinue(outcome: LoopOutcome): boolean;
+}
+/** Default round ceiling when `@MainLoop` declares no `maxIterations` (EC-3: finite, never Infinity). */
+declare const DEFAULT_MAX_ITERATIONS = 8;
+/** Serializable config for a LoopStrategy. SSoT per type-safety.md (ADR D3). */
+declare const loopStrategyConfigSchema: z.ZodObject<{
+    name: z.ZodEnum<{
+        react: "react";
+        "simple-chat": "simple-chat";
+        "plan-act-reflect": "plan-act-reflect";
+    }>;
+    maxIterations: z.ZodNumber;
+}, z.core.$strip>;
+type LoopStrategyConfig = z.infer<typeof loopStrategyConfigSchema>;
+/**
+ * Map a `@MainLoop` strategy + ceiling to a concrete {@link LoopStrategy}.
+ *
+ * - `simple-chat` ⇒ exactly one round (`shouldContinue` always false).
+ * - `plan-act-reflect` / `react` ⇒ continue while the round ended on `tool-calls`
+ *   AND the ceiling has not been reached (`round < maxIterations`).
+ *
+ * Throws (Zod) when `maxIterations < 1` — fail fast, never a silent infinite loop.
+ */
+declare function resolveLoopStrategy(strategy: MainLoopMeta['strategy'], maxIterations?: number): LoopStrategy;
+
+/**
+ * ReflectionStrategy — composes INTO the loop between rounds (the loop calls
+ * `reflect()` then `LoopStrategy.shouldContinue()`).
+ *
+ * `'plan-act-reflect'` resolves to the `'ladder'` default shipped here; a custom
+ * strategy may be supplied (OCP — plan Drawback #2). `reflect()` is pure (no
+ * I/O, no LLM) — it inspects the round's outcome and returns feedback to inject
+ * into the next round's prompt plus a `continue` hint. The hard round ceiling
+ * lives in `LoopStrategy.shouldContinue` (maxIterations), NOT here.
+ *
+ * referencia: knowledge-base/references/mastra agentic-loop/index.ts (onIterationComplete → { feedback, continue }).
+ */
+
+/** Result of reflecting on a completed round. */
+interface ReflectionResult {
+    /** Optional text prepended to the next round's prompt. */
+    readonly feedback?: string;
+    /** Hint: should the loop reflect-and-continue? (the ceiling still bounds it) */
+    readonly continue: boolean;
+}
+/** Pluggable between-round reflection. Pure — never performs I/O. */
+interface ReflectionStrategy {
+    /** Strategy identifier (e.g. `'ladder'`). */
+    readonly name: string;
+    /** Inspect the round outcome; return feedback + continue hint. */
+    reflect(outcome: LoopOutcome): ReflectionResult;
+}
+/** Serializable config for a ReflectionStrategy. SSoT per type-safety.md (ADR D3). */
+declare const reflectionStrategyConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+type ReflectionStrategyConfig = z.infer<typeof reflectionStrategyConfigSchema>;
+/**
+ * The default `'ladder'` reflection (what `'plan-act-reflect'` resolves to).
+ *
+ * Continues with bounded templated feedback while the round ended on
+ * `tool-calls`; terminates on any terminal `finishReason` (`stop`/`error`/
+ * `length`). The feedback is a short fixed template (bounded — EC-5; context
+ * growth is the SDK's responsibility, not the loop's).
+ */
+declare const ladderReflectionStrategy: ReflectionStrategy;
+/**
+ * No-op reflection for `'react'` (multi-round WITHOUT reflection feedback).
+ *
+ * Returns `{ continue: true }` (no feedback) so the round-continuation decision
+ * is delegated entirely to `LoopStrategy.shouldContinue` (i.e. `react` loops
+ * while `finishReason === 'tool-calls'` under the ceiling). NOTE: the plan's
+ * pseudo-code (Files-to-edit) sketched `{ continue: false }`, which would make
+ * `react` single-shot — that contradicts the plan's own Deep Dives ("`react`
+ * still multi-rounds while finishReason==='tool-calls'"); `continue: true` is
+ * the behavior the resolved react LoopStrategy requires.
+ */
+declare const noopReflectionStrategy: ReflectionStrategy;
+
+/**
+ * AgentRunner — the imperative twin of `@MainLoop` (plan ADR D4, V4-B).
+ *
+ * `AgentRunner.builder(AgentClass).reflection().stream().build()` walks +
+ * compiles the agent and resolves the SAME `{ compiled, loopStrategy }` that
+ * `delegate()` resolves for the decorator path (two on-ramps, one runtime).
+ * `build()` is the compile boundary (no I/O, no IoC — standalone, mirrors
+ * Spring's `ChatClient.builder(...).build()`); `run()` does the I/O via
+ * `runReflectiveLoop` (the SAME loop `delegate()` uses — DRY, ADR 0031).
+ *
+ * referencia: knowledge-base/references/spring-ai DefaultChatClientBuilder.java (build() returns standalone).
+ */
+
+/** Options for {@link AgentRunner.run}. */
+interface AgentRunnerRunOptions {
+    /** LLM API key. */
+    readonly apiKey: string;
+    /** Session id override (default: a fresh isolated id). */
+    readonly sessionId?: string;
+    /** Cumulative USD budget across rounds. */
+    readonly budget?: number;
+    /** Cancellation — aborts stop the reflective loop from re-entering. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * A built, runnable agent. Construct via {@link AgentRunner.builder} — the
+ * constructor takes already-resolved state and is an internal detail.
+ */
+declare class AgentRunner {
+    private readonly compiled;
+    private readonly agentName;
+    /** The resolved terminal-decision strategy (parity with `delegate()`). */
+    readonly loopStrategy: LoopStrategy;
+    /** The resolved between-round reflection (default or `.reflection(custom)` override). */
+    readonly reflectionStrategy: 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).
+     */
+    readonly streamEnabled: boolean;
+    constructor(compiled: CompiledAgentOptions, agentName: string, 
+    /** The resolved terminal-decision strategy (parity with `delegate()`). */
+    loopStrategy: LoopStrategy, 
+    /** The resolved between-round reflection (default or `.reflection(custom)` override). */
+    reflectionStrategy: 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: boolean);
+    /** Start a fluent builder for `AgentClass`. */
+    static builder(AgentClass: Function): AgentRunnerBuilder;
+    /** Run the agent to a terminal result via the shared reflective loop. */
+    run(message: string, opts: AgentRunnerRunOptions): Promise<DelegationResult>;
+}
+/** Fluent builder — accumulates config; `build()` is the compile boundary. */
+declare class AgentRunnerBuilder {
+    private readonly AgentClass;
+    private reflectionOverride?;
+    private streamEnabled;
+    constructor(AgentClass: Function);
+    /** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
+    reflection(strategy?: ReflectionStrategy): this;
+    /** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
+    stream(enabled?: boolean): this;
+    /** Walk + compile + resolve strategies — the compile→execute boundary (no I/O). */
+    build(): AgentRunner;
+}
+
+export { AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, CompiledAgentOptions, DEFAULT_MAX_ITERATIONS, DelegationResult, type LoopFinishReason, type LoopOutcome, type LoopStrategy, type LoopStrategyConfig, MainLoopMeta, type ReflectionResult, type ReflectionStrategy, type ReflectionStrategyConfig, ladderReflectionStrategy, loopStrategyConfigSchema, noopReflectionStrategy, reflectionStrategyConfigSchema, resolveLoopStrategy };

package/dist/index.js

@@ -1,7 +1,6 @@
 import {
   Artifact,
   Checkpoint,
-  ContextWindow,
   Conversation,
   EditFormat,
   Hook,
@@ -9,14 +8,12 @@ import {
   MainLoop,
   Model,
   Observable,
-  ProjectContext,
   Sandbox,
   Tool,
   Toolbox,
   applyDecorators,
   getArtifactConfig,
   getCheckpointConfig,
-  getContextWindowConfig,
   getConversationConfig,
   getHooks,
   getHooksByPoint,
@@ -24,20 +21,25 @@ import {
   getMainLoop,
   getObservableByChannel,
   getObservables,
-  getProjectContextConfig,
   getSandboxConfig,
   getToolConfig,
   getToolMethods,
   getToolboxConfig,
   isCommandAllowed,
   isPathAllowed
-} from "./chunk-VKHDADMG.js";
+} from "./chunk-XWVZS2PQ.js";
 import {
+  AgentRunner,
+  AgentRunnerBuilder,
   AgentWarningCode,
   BudgetExceededError,
+  DEFAULT_MAX_ITERATIONS,
   DelegationError,
   agentsPlugin,
   compileAgent,
+  compileContextWindow,
+  compileProjectContext,
+  compileSkills,
   compileTools,
   createAgentExecutionContext,
   createSdkAgentStream,
@@ -51,37 +53,49 @@ import {
   isTextDelta,
   isToolCall,
   isToolResult,
+  ladderReflectionStrategy,
+  loopStrategyConfigSchema,
+  noopReflectionStrategy,
+  projectContextMetadataOnlyKnobs,
+  reflectionStrategyConfigSchema,
+  resolveLoopStrategy,
   streamAgentResponse,
   translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-NC5EE7HN.js";
+} from "./chunk-KTYBQ7HY.js";
 import {
   Agent,
   Audit,
   Budget,
+  ContextWindow,
   Gateway,
   MCP,
   Memory,
   Mixin,
   Policy,
+  ProjectContext,
   RequiresApproval,
   RequiresCapability,
   Skills,
   SubAgents,
   Trace,
   getAgentConfig,
+  getContextWindowConfig,
   getGatewayConfig,
   getMcpConfig,
   getMemoryConfig,
   getMixins,
+  getProjectContextConfig,
   getSkillsConfig,
   getSubAgents,
   resolveSessionId
-} from "./chunk-O4UG4RXE.js";
+} from "./chunk-MVEY7HEY.js";
 import "./chunk-7QVYU63E.js";
 export {
   Agent,
+  AgentRunner,
+  AgentRunnerBuilder,
   AgentWarningCode,
   Artifact,
   Audit,
@@ -90,6 +104,7 @@ export {
   Checkpoint,
   ContextWindow,
   Conversation,
+  DEFAULT_MAX_ITERATIONS,
   DelegationError,
   EditFormat,
   Gateway,
@@ -114,6 +129,9 @@ export {
   agentsPlugin,
   applyDecorators,
   compileAgent,
+  compileContextWindow,
+  compileProjectContext,
+  compileSkills,
   compileTools,
   createAgentExecutionContext,
   createSdkAgentStream,
@@ -151,6 +169,12 @@ export {
   isTextDelta,
   isToolCall,
   isToolResult,
+  ladderReflectionStrategy,
+  loopStrategyConfigSchema,
+  noopReflectionStrategy,
+  projectContextMetadataOnlyKnobs,
+  reflectionStrategyConfigSchema,
+  resolveLoopStrategy,
   resolveSessionId,
   streamAgentResponse,
   translateSdkEvent,

package/dist/{mcp-yyfC5u7t.d.ts → skills-DmN1HGUb.d.ts}

@@ -66,6 +66,22 @@ type PolicyHandler = (user: {
     roles: string[];
 }) => boolean;
 
+type ContextCompactionStrategy = 'truncate-oldest' | 'summarize-oldest' | 'sliding-window' | 'priority-based';
+interface ContextWindowOptions {
+    /** Maximum tokens before compaction triggers. */
+    maxTokens?: number;
+    /** How to compact when maxTokens is exceeded. */
+    compactionStrategy?: ContextCompactionStrategy;
+    /** Always preserve the system prompt during compaction (default: true). */
+    preserveSystemPrompt?: boolean;
+    /** Number of recent messages to always keep intact (default: 10). */
+    preserveLastN?: number;
+    /** Keep all tool results even during compaction (default: true). */
+    preserveToolResults?: boolean;
+}
+declare function ContextWindow(options?: ContextWindowOptions): ClassDecorator;
+declare function getContextWindowConfig(target: Function): ContextWindowOptions | undefined;
+
 type PlatformName = 'telegram' | 'discord' | 'slack' | 'whatsapp' | 'teams' | 'email' | 'sms' | 'mattermost' | 'line' | 'matrix';
 type SessionStrategy = 'per-user' | 'per-channel' | 'per-thread';
 interface GatewayOptions {
@@ -92,6 +108,20 @@ declare function resolveSessionId(strategy: SessionStrategy, platform: string, s
     topicId?: string;
 }): string;
 
+interface McpServerConfig {
+    /** Command to start the MCP server. */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables for the server process. */
+    env?: Record<string, string>;
+    /** Working directory for the server process. */
+    cwd?: string;
+}
+type McpServersMap = Record<string, McpServerConfig>;
+declare function MCP(servers: McpServersMap): ClassDecorator;
+declare function getMcpConfig(target: Function): McpServersMap | undefined;
+
 type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0';
 type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global';
 interface MemoryOptions {
@@ -109,6 +139,25 @@ interface MemoryOptions {
 declare function Memory(options?: MemoryOptions): ClassDecorator;
 declare function getMemoryConfig(target: Function): MemoryOptions | undefined;
 
+type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
+type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
+interface ProjectContextOptions {
+    /** Files that mark the project root (searched upward from cwd). */
+    rootMarkers?: string[];
+    /** How to index the codebase for structural understanding. */
+    indexStrategy?: IndexStrategy;
+    /** Maximum files to include in context per request. */
+    maxFilesInContext?: number;
+    /** How to rank file relevance when selecting context. */
+    relevanceStrategy?: RelevanceStrategy;
+    /** Glob patterns to exclude from indexing and context. */
+    ignorePatterns?: string[];
+    /** File extensions to include in indexing (default: all text files). */
+    includeExtensions?: string[];
+}
+declare function ProjectContext(options?: ProjectContextOptions): ClassDecorator;
+declare function getProjectContextConfig(target: Function): ProjectContextOptions | undefined;
+
 interface SkillsOptions {
     /** Skill names to include (resolved from .theokit/skills/<name>/SKILL.md). */
     include: string[];
@@ -118,18 +167,4 @@ interface SkillsOptions {
 declare function Skills(namesOrOptions: string[] | SkillsOptions): ClassDecorator;
 declare function getSkillsConfig(target: Function): SkillsOptions | undefined;
 
-interface McpServerConfig {
-    /** Command to start the MCP server. */
-    command: string;
-    /** Arguments passed to the command. */
-    args?: string[];
-    /** Environment variables for the server process. */
-    env?: Record<string, string>;
-    /** Working directory for the server process. */
-    cwd?: string;
-}
-type McpServersMap = Record<string, McpServerConfig>;
-declare function MCP(servers: McpServersMap): ClassDecorator;
-declare function getMcpConfig(target: Function): McpServersMap | undefined;
-
-export { type AgentOptions as A, type BudgetOptions as B, Gateway as G, MCP as M, type PlatformName as P, type SessionStrategy as S, type ToolOptions as T, type ApprovalOptions as a, type GatewayOptions as b, type MainLoopMeta as c, type MainLoopOptions as d, type McpServerConfig as e, type McpServersMap as f, Memory as g, type MemoryOptions as h, type MemoryProvider as i, type MemoryScope as j, type PolicyHandler as k, Skills as l, type SkillsOptions as m, type ToolboxOptions as n, getGatewayConfig as o, getMcpConfig as p, getMemoryConfig as q, getSkillsConfig as r, resolveSessionId as s };
+export { type AgentOptions as A, type BudgetOptions as B, type ContextCompactionStrategy as C, Gateway as G, type IndexStrategy as I, type MainLoopMeta as M, type PlatformName as P, type RelevanceStrategy as R, type SessionStrategy as S, type ToolOptions as T, type ApprovalOptions as a, ContextWindow as b, type ContextWindowOptions as c, type GatewayOptions as d, MCP as e, type MainLoopOptions as f, type McpServerConfig as g, type McpServersMap as h, Memory as i, type MemoryOptions as j, type MemoryProvider as k, type MemoryScope as l, type PolicyHandler as m, ProjectContext as n, type ProjectContextOptions as o, Skills as p, type SkillsOptions as q, type ToolboxOptions as r, getContextWindowConfig as s, getGatewayConfig as t, getMcpConfig as u, getMemoryConfig as v, getProjectContextConfig as w, getSkillsConfig as x, resolveSessionId as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Unified decorator runtime — AI agents as first-class citizens of the TheoKit pipeline. @Agent() compiles to SDK Agent.create(), @Tool() compiles to defineTool().",
   "type": "module",
   "sideEffects": false,
@@ -36,16 +36,27 @@
   },
   "peerDependencies": {
     "@theokit/http": ">=0.1.0-alpha.0",
-    "@theokit/sdk": ">=1.5.0",
+    "@theokit/sdk": ">=2.5.0",
+    "@theokit/sdk-tools": ">=0.2.0",
     "reflect-metadata": ">=0.2.0",
     "zod": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@theokit/sdk-tools": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@theokit/http": "workspace:*",
-    "reflect-metadata": "^0.2.0",
-    "zod": "^4.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^3.0.0"
+    "@theokit/sdk": "^2.5.0",
+    "@theokit/sdk-tools": "^0.2.0",
+    "reflect-metadata": "^0.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.12.0"
   }
 }