@theokit/agents 0.4.0 → 0.5.0

package/dist/bridge.d.ts

@@ -1,5 +1,6 @@
 import { ExecutionContext } from '@theokit/http';
-import { A as AgentOptions, T as ToolOptions, c as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, b as GatewayOptions, h as MemoryOptions, m as SkillsOptions, f as McpServersMap } from './mcp-yyfC5u7t.js';
+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 { SkillsSettings, ContextSettings, SystemPromptResolver } from '@theokit/sdk';
 import 'zod';
 
 /**
@@ -44,6 +45,8 @@ declare const AgentWarningCode: {
     readonly INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY";
     readonly FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY";
     readonly BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY";
+    readonly CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY";
+    readonly PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY";
 };
 interface AgentWalkResult {
     agentConfig: AgentOptions;
@@ -57,6 +60,8 @@ interface AgentWalkResult {
     subAgentClasses: Function[];
     memory?: MemoryOptions;
     skills?: SkillsOptions;
+    contextWindow?: ContextWindowOptions;
+    projectContext?: ProjectContextOptions;
     mcpServers?: McpServersMap;
 }
 interface ToolboxWalkResult {
@@ -89,6 +94,15 @@ declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Functi
  */
 declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
 
+/**
+ * Agent compiler — transforms decorator metadata into SDK calls.
+ *
+ * Per ADR D1: @Agent is a macro over Agent.create().
+ * Per ADR D3: @Tool compiles to defineTool().
+ *
+ * EC-3: throws if toolbox instance is missing from the instances map.
+ */
+
 /** Minimal interface matching defineTool() result shape. */
 interface CompiledTool {
     name: string;
@@ -115,7 +129,10 @@ interface CompiledAgentOptions {
     tools: CompiledTool[];
     agents: Record<string, CompiledSubAgent>;
     memory?: MemoryOptions;
-    skills?: SkillsOptions;
+    skills?: SkillsSettings;
+    context?: ContextSettings;
+    /** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
+    projectContext?: ProjectContextOptions;
     mcpServers?: McpServersMap;
     maxIterations?: number;
     timeoutMs?: number;
@@ -128,6 +145,69 @@ interface CompiledAgentOptions {
  */
 declare function compileAgent(walkResult: AgentWalkResult, toolboxInstances?: Map<Function, object>): CompiledAgentOptions;
 
+/**
+ * M8-3 — compile `@Skills` metadata into the SDK's `SkillsSettings`.
+ *
+ * Per sdk-runtime.md: the bridge COMPILES decorator metadata into a format the
+ * SDK accepts; the SDK is the runtime. `Agent.create({ skills })` natively
+ * discovers `.theokit/skills/<name>/SKILL.md` files and injects the `<skills>`
+ * block — so giving `@Skills` runtime is a pure shape translation, not a
+ * reimplementation of discovery.
+ *
+ * Mapping (ADR D4):
+ * - `{ include }`            → `{ enabled: include, autoInject: true }`
+ * - `{ autoDiscover: true }` → `{ autoInject: true }` (enabled omitted ⇒ the SDK
+ *                              enables every discovered skill)
+ */
+
+declare function compileSkills(options: SkillsOptions): SkillsSettings;
+
+/**
+ * M8-1 — compile `@ContextWindow` metadata into the SDK's `ContextSettings`.
+ *
+ * Per sdk-runtime.md, the SDK owns session/transcript storage + compaction.
+ * The bridge therefore maps the one knob the SDK natively exposes as a budget —
+ * `maxTokens` → `ContextSettings.maxTokens` — and reports the strategy knobs that
+ * have NO native `AgentOptions` equivalent (`compactionStrategy`, `preserveLastN`,
+ * `preserveToolResults`, `preserveSystemPrompt`). Those are surfaced as
+ * `metadataOnlyKnobs` so the walk can emit an honest `metadata-only` warning
+ * (ADR D2) instead of silently dropping them (G10 — honest enforcement).
+ */
+
+interface CompiledContextWindow {
+    /** SDK-shaped context budget passed to `Agent.create({ context })`. */
+    context: ContextSettings;
+    /** Declared knobs the SDK does not expose — reported, never silently dropped. */
+    metadataOnlyKnobs: string[];
+}
+declare function compileContextWindow(options: ContextWindowOptions): CompiledContextWindow;
+
+/**
+ * M8-2 — compile `@ProjectContext` metadata into an SDK `SystemPromptResolver`.
+ *
+ * There is no native `AgentOptions` field that carries a repo map, so the bridge
+ * composes the documented `systemPrompt` seam (`string | SystemPromptResolver`):
+ * the resolver prepends `buildEnvContext` + `buildRepoMap` (`@theokit/sdk-tools`)
+ * and the nearest `THEO.md` (`@theokit/sdk/project#readProjectInstructions`) to
+ * the agent's base prompt (ADR D3). The SDK primitives are dynamically imported
+ * so `@theokit/sdk-tools` stays an OPTIONAL peer — only loaded when a `@ProjectContext`
+ * agent actually sends.
+ *
+ * Knobs with no primitive mapping (`indexStrategy`, `relevanceStrategy`,
+ * `maxFilesInContext`, `includeExtensions`, `rootMarkers`) are reported via
+ * {@link projectContextMetadataOnlyKnobs} so the walk warns honestly (G10).
+ * Only `ignorePatterns` is forwarded (to `buildRepoMap`).
+ */
+
+declare function projectContextMetadataOnlyKnobs(options: ProjectContextOptions): string[];
+/**
+ * Build a `SystemPromptResolver` that prepends env + repo map + project
+ * instructions to `base`. When the SDK provides no `cwd`, the resolver returns
+ * `base` unchanged (no filesystem guess — keeps `packages/agents/src` free of
+ * direct Node `process` access per G8; the repo map needs a real cwd).
+ */
+declare function compileProjectContext(options: ProjectContextOptions, base?: string): SystemPromptResolver;
+
 /**
  * SSE streaming handler — Web Standard Response with ReadableStream.
  *
@@ -299,22 +379,13 @@ interface AgentRouteContext {
 /** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
 declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
 
-/**
- * SDK Adapter — bridges @theokit/agents decorators → @theokit/sdk runtime.
- *
- * Per rule sdk-runtime.md (INQUEBRÁVEL): @theokit/sdk is the ONLY agent runtime.
- * This adapter replaces llm-runner.ts (which called OpenRouter API directly).
- *
- * Flow: @Agent decorator → compileAgent() → createSdkAgentStream() → SDK Agent.create() → Run.stream()
- */
-
 /**
  * Creates an agent stream factory using @theokit/sdk as the runtime.
  *
  * Returns a function that, given a message + sessionId, yields TheoKit
  * AgentStreamEvent via the SDK's Agent.create() + Run.stream() pipeline.
  */
-declare function createSdkAgentStream(agentWalk: AgentWalkResult, compiledTools: CompiledTool[], apiKey: string, envModel?: string): (message: string, _sessionId: string) => AsyncIterable<StreamEvent>;
+declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string, envModel?: string): (message: string, _sessionId: string) => AsyncIterable<StreamEvent>;
 
 /**
  * Translates @theokit/sdk SDKMessage events → TheoKit AgentStreamEvent.
@@ -469,4 +540,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type AgentExecutionContext, type AgentManifest, type AgentManifestEntry, type AgentManifestTool, type AgentRoute, type AgentRouteContext, type AgentRunInfo, type AgentStreamEvent, type AgentWalkResult, AgentWarningCode, type AgentsPluginOptions, type ApprovalRequiredEvent, type ArtifactChunkEvent, type ArtifactStartEvent, BudgetExceededError, type CheckpointSavedEvent, type CompiledAgentOptions, type CompiledTool, type DelegateOptions, DelegationError, type DelegationResult, type DoneEvent, type ErrorEvent, type FileEditEvent, type IterationEvent, type RunStartedEvent, type SdkMessage, type StateUpdateEvent, type StreamEvent, type TextDeltaEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type ToolWalkResult, type ToolboxWalkResult, agentsPlugin, compileAgent, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata };
+export { type AgentExecutionContext, type AgentManifest, type AgentManifestEntry, type AgentManifestTool, type AgentRoute, type AgentRouteContext, type AgentRunInfo, type AgentStreamEvent, type AgentWalkResult, AgentWarningCode, type AgentsPluginOptions, type ApprovalRequiredEvent, type ArtifactChunkEvent, type ArtifactStartEvent, BudgetExceededError, type CheckpointSavedEvent, type CompiledAgentOptions, type CompiledContextWindow, type CompiledTool, type DelegateOptions, DelegationError, type DelegationResult, type DoneEvent, type ErrorEvent, type FileEditEvent, type IterationEvent, type RunStartedEvent, type SdkMessage, type StateUpdateEvent, type StreamEvent, type TextDeltaEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type ToolWalkResult, type ToolboxWalkResult, agentsPlugin, compileAgent, compileContextWindow, compileProjectContext, compileSkills, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, projectContextMetadataOnlyKnobs, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata };

package/dist/bridge.js

@@ -4,6 +4,9 @@ import {
   DelegationError,
   agentsPlugin,
   compileAgent,
+  compileContextWindow,
+  compileProjectContext,
+  compileSkills,
   compileTools,
   createAgentExecutionContext,
   createSdkAgentStream,
@@ -17,12 +20,13 @@ import {
   isTextDelta,
   isToolCall,
   isToolResult,
+  projectContextMetadataOnlyKnobs,
   streamAgentResponse,
   translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-NC5EE7HN.js";
-import "./chunk-O4UG4RXE.js";
+} from "./chunk-2MI27XCA.js";
+import "./chunk-MVEY7HEY.js";
 import "./chunk-7QVYU63E.js";
 export {
   AgentWarningCode,
@@ -30,6 +34,9 @@ export {
   DelegationError,
   agentsPlugin,
   compileAgent,
+  compileContextWindow,
+  compileProjectContext,
+  compileSkills,
   compileTools,
   createAgentExecutionContext,
   createSdkAgentStream,
@@ -43,6 +50,7 @@ export {
   isTextDelta,
   isToolCall,
   isToolResult,
+  projectContextMetadataOnlyKnobs,
   streamAgentResponse,
   translateSdkEvent,
   validateUniqueRoutes,

package/dist/{chunk-NC5EE7HN.js → chunk-2MI27XCA.js}

@@ -9,14 +9,16 @@ import {
   TOOL_METHODS,
   Trace,
   getAgentConfig,
+  getContextWindowConfig,
   getGatewayConfig,
   getMcpConfig,
   getMemoryConfig,
   getMeta,
   getMixins,
+  getProjectContextConfig,
   getSkillsConfig,
   getSubAgents
-} from "./chunk-O4UG4RXE.js";
+} from "./chunk-MVEY7HEY.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -40,6 +42,68 @@ function isAgentContext(ctx) {
 }
 __name(isAgentContext, "isAgentContext");
 
+// src/bridge/compile-context-window.ts
+var STRATEGY_KNOBS = [
+  "compactionStrategy",
+  "preserveLastN",
+  "preserveToolResults",
+  "preserveSystemPrompt"
+];
+function compileContextWindow(options) {
+  const context = {};
+  if (typeof options.maxTokens === "number") {
+    context.maxTokens = options.maxTokens;
+  }
+  const opts = options;
+  const metadataOnlyKnobs = STRATEGY_KNOBS.filter((knob) => opts[knob] !== void 0);
+  return {
+    context,
+    metadataOnlyKnobs
+  };
+}
+__name(compileContextWindow, "compileContextWindow");
+
+// src/bridge/compile-project-context.ts
+var UNMAPPED_KNOBS = [
+  "indexStrategy",
+  "relevanceStrategy",
+  "maxFilesInContext",
+  "includeExtensions",
+  "rootMarkers"
+];
+function projectContextMetadataOnlyKnobs(options) {
+  const opts = options;
+  return UNMAPPED_KNOBS.filter((knob) => opts[knob] !== void 0);
+}
+__name(projectContextMetadataOnlyKnobs, "projectContextMetadataOnlyKnobs");
+function compileProjectContext(options, base) {
+  return async (promptCtx) => {
+    const cwd = promptCtx.cwd;
+    if (!cwd) {
+      return base ?? "";
+    }
+    const { buildEnvContext, buildRepoMap } = await import("@theokit/sdk-tools");
+    const { readProjectInstructions } = await import("@theokit/sdk/project");
+    const env = buildEnvContext(cwd);
+    const repoMap = buildRepoMap(cwd, {
+      ignore: options.ignorePatterns
+    });
+    let instructions = "";
+    try {
+      instructions = (await readProjectInstructions(cwd)).content ?? "";
+    } catch {
+      instructions = "";
+    }
+    return [
+      env,
+      repoMap,
+      instructions,
+      base
+    ].filter(Boolean).join("\n\n");
+  };
+}
+__name(compileProjectContext, "compileProjectContext");
+
 // src/bridge/walk-agent-metadata.ts
 import "reflect-metadata";
 import { Reflector } from "@theokit/http";
@@ -49,7 +113,9 @@ var USE_FILTERS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-filter
 var AgentWarningCode = {
   INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY",
   FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY",
-  BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY"
+  BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY",
+  CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY",
+  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY"
 };
 var reflectorInstance = new Reflector();
 function walkToolbox(ToolboxClass) {
@@ -88,6 +154,21 @@ function walkToolbox(ToolboxClass) {
   };
 }
 __name(walkToolbox, "walkToolbox");
+function warnUnmappedDecoratorKnobs(agentName, contextWindow, projectContext) {
+  if (contextWindow) {
+    const { metadataOnlyKnobs } = compileContextWindow(contextWindow);
+    if (metadataOnlyKnobs.length > 0) {
+      console.warn(`[${AgentWarningCode.CONTEXT_STRATEGY_METADATA_ONLY}] Agent ${agentName}: @ContextWindow knob(s) ${metadataOnlyKnobs.join(", ")} are metadata-only \u2014 the SDK manages transcript compaction internally. Only maxTokens is forwarded to Agent.create({ context }).`);
+    }
+  }
+  if (projectContext) {
+    const unmapped = projectContextMetadataOnlyKnobs(projectContext);
+    if (unmapped.length > 0) {
+      console.warn(`[${AgentWarningCode.PROJECT_CONTEXT_KNOB_METADATA_ONLY}] Agent ${agentName}: @ProjectContext knob(s) ${unmapped.join(", ")} are metadata-only \u2014 the repo map is composed via buildRepoMap/buildEnvContext/readProjectInstructions; only ignorePatterns is forwarded.`);
+    }
+  }
+}
+__name(warnUnmappedDecoratorKnobs, "warnUnmappedDecoratorKnobs");
 var agentWalkCache = /* @__PURE__ */ new WeakMap();
 function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   if (toolboxClasses.length === 0) {
@@ -121,6 +202,9 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   const memory = getMemoryConfig(AgentClass);
   const skills = getSkillsConfig(AgentClass);
   const mcpServers = getMcpConfig(AgentClass);
+  const contextWindow = getContextWindowConfig(AgentClass);
+  const projectContext = getProjectContextConfig(AgentClass);
+  warnUnmappedDecoratorKnobs(AgentClass.name, contextWindow, projectContext);
   const result = {
     agentConfig,
     mainLoop,
@@ -133,6 +217,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
     subAgentClasses,
     memory,
     skills,
+    contextWindow,
+    projectContext,
     mcpServers
   };
   if (toolboxClasses.length === 0) {
@@ -153,6 +239,20 @@ function validateUniqueRoutes(results) {
 }
 __name(validateUniqueRoutes, "validateUniqueRoutes");
 
+// src/bridge/compile-skills.ts
+function compileSkills(options) {
+  if (options.autoDiscover) {
+    return {
+      autoInject: true
+    };
+  }
+  return {
+    enabled: options.include,
+    autoInject: true
+  };
+}
+__name(compileSkills, "compileSkills");
+
 // src/bridge/agent-compiler.ts
 function compileTools(toolboxes, toolboxInstances) {
   const tools = [];
@@ -200,7 +300,9 @@ function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map())
     tools,
     agents,
     memory: walkResult.memory,
-    skills: walkResult.skills,
+    skills: walkResult.skills ? compileSkills(walkResult.skills) : void 0,
+    context: walkResult.contextWindow ? compileContextWindow(walkResult.contextWindow).context : void 0,
+    projectContext: walkResult.projectContext,
     mcpServers: walkResult.mcpServers,
     maxIterations: walkResult.mainLoop.maxIterations ?? walkResult.agentConfig.maxIterations,
     timeoutMs: walkResult.mainLoop.timeoutMs ?? walkResult.agentConfig.timeoutMs,
@@ -480,8 +582,37 @@ function translateSdkEvent(msg, runId) {
 __name(translateSdkEvent, "translateSdkEvent");
 
 // src/bridge/sdk-adapter.ts
-function createSdkAgentStream(agentWalk, compiledTools, apiKey, envModel) {
-  const model = envModel ?? agentWalk.agentConfig.model ?? "openai/gpt-4o-mini";
+function assembleM8CreateOptions(compiled) {
+  const options = {};
+  const applied = [];
+  const base = compiled.systemPrompt;
+  if (compiled.skills) {
+    options.skills = compiled.skills;
+    options.local = {
+      settingSources: [
+        "project"
+      ]
+    };
+    applied.push("skills");
+  }
+  if (compiled.context) {
+    options.context = compiled.context;
+    applied.push("context");
+  }
+  if (compiled.projectContext) {
+    options.systemPrompt = compileProjectContext(compiled.projectContext, base);
+    applied.push("projectContext");
+  } else if (base !== void 0) {
+    options.systemPrompt = base;
+  }
+  return {
+    options,
+    applied
+  };
+}
+__name(assembleM8CreateOptions, "assembleM8CreateOptions");
+function createSdkAgentStream(compiled, compiledTools, apiKey, envModel) {
+  const model = envModel ?? compiled.model ?? "openai/gpt-4o-mini";
   return (message, _sessionId) => ({
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
@@ -508,13 +639,21 @@ function createSdkAgentStream(agentWalk, compiledTools, apiKey, envModel) {
         handler: t.handler
       }));
       try {
+        const { options: m8, applied } = assembleM8CreateOptions(compiled);
+        if (applied.length > 0) {
+          console.debug("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
+            skills: applied.includes("skills"),
+            context: applied.includes("context"),
+            projectContext: applied.includes("projectContext")
+          });
+        }
         const agent = await Agent.create({
           apiKey,
           model: {
             id: model
           },
           tools: sdkTools,
-          systemPrompt: agentWalk.agentConfig.systemPrompt
+          ...m8
         });
         const run = await agent.send(message);
         for await (const sdkEvent of run.stream()) {
@@ -636,7 +775,7 @@ async function delegate(SubAgentClass, message, opts = {}) {
   const compiled = compileAgent(walk, toolboxInstances);
   const allTools = mergeTools(opts.parentTools ?? [], compiled.tools);
   const budget = Math.min(opts.budget ?? Infinity, opts.parentBudgetRemaining ?? Infinity);
-  const streamFactory = createSdkAgentStream(walk, allTools, apiKey, walk.agentConfig.model);
+  const streamFactory = createSdkAgentStream(compiled, allTools, apiKey, walk.agentConfig.model);
   const sessionId = opts.sessionId ?? `sub-${crypto.randomUUID()}`;
   const acc = {
     response: "",
@@ -786,9 +925,13 @@ __name(matchRoute, "matchRoute");
 export {
   createAgentExecutionContext,
   isAgentContext,
+  compileContextWindow,
+  projectContextMetadataOnlyKnobs,
+  compileProjectContext,
   AgentWarningCode,
   walkAgentMetadata,
   validateUniqueRoutes,
+  compileSkills,
   compileTools,
   compileAgent,
   streamAgentResponse,
@@ -807,4 +950,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-NC5EE7HN.js.map
+//# sourceMappingURL=chunk-2MI27XCA.js.map