@theokit/agents 0.39.0 → 0.42.0

package/dist/{bridge-entry-CAY5JP9z.d.ts → bridge-entry-CE3ie8rG.d.ts}

@@ -1,6 +1,6 @@
 import { ExecutionContext } from '@theokit/http';
 import { A as AgentOptions, g as ToolOptions, M as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, H as HumanInTheLoopOptions, t as GatewayOptions, z as MemoryOptions, O as SkillsOptions, r as ContextWindowOptions, K as ProjectContextOptions, x as McpServersMap, G as Guardrail, o as CompactionDecoratorConfig, j as CheckpointOptions, R as ReasoningEffort } from './types-DVA4LQsA.js';
-import { InlineSkill, SystemPromptResolver, ConversationStorageAdapter, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, ModelSelection } from '@theokit/sdk';
+import { InlineSkill, SystemPromptResolver, SettingSource, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, ModelSelection } from '@theokit/sdk';
 import { UIMessageChunk } from 'ai';
 import { z } from 'zod';
 import { RetryOptions } from '@theokit/sdk/retry';
@@ -191,13 +191,11 @@ interface CompiledAgentOptions {
     /** Static prompt OR a per-request {@link SystemPromptResolver} (V4-L.1, Axis-B). */
     systemPrompt?: string | SystemPromptResolver;
     /**
-     * Agent-level conversation memory: the `ConversationStorageAdapter` the SDK persists turns to
-     * (`Agent.getOrCreate({ conversationStorage })`). Populated by `defineAgent({ conversationStorage })`
-     * / `.conversationStorage(adapter)`. A per-run override (`RuntimeOverrides.conversationStorage`)
-     * wins over this; absent ⇒ the SDK default store is chosen lazily. Distinct from `@Checkpoint`,
-     * which only toggles filesystem-vs-memory for the built-in default.
+     * theokit-file-based-config — opt-in `.theokit/` file-based config roots (`"project"`/`"user"`/…).
+     * Projected into `Agent.create({ local: { settingSources } })` by `assembleM8CreateOptions`
+     * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
      */
-    conversationStorage?: ConversationStorageAdapter;
+    settingSources?: readonly SettingSource[];
     tools: CompiledTool[];
     agents: Record<string, CompiledSubAgent>;
     memory?: MemoryOptions;
@@ -563,11 +561,13 @@ interface RuntimeOverrides {
     /** Per-run SDK budget tracker (inner tool-loop cap; distinct from the loop's USD `budget`). */
     budgetTracker?: BudgetTracker;
     /**
-     * V4-M: conversation store shared across the loop's rounds so history persists
-     * (round N+1 sees rounds 1..N). Default `InMemoryConversationStorage` (per-run,
-     * no disk). Pass a `FileSystemConversationStorage`/custom adapter for durable history.
+     * SDK 4.0 (SE40) — root of the native Claude-shaped `.jsonl` session transcript the SDK writes
+     * automatically (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`). The framework threads the
+     * app's project root here (see `mount-agent`) so sessions persist per-app; unset ⇒ SDK default
+     * (`~/.theokit`). Replaces the removed pluggable `conversationStorage` — persistence is now the
+     * SDK's native transcript, not a swappable adapter.
      */
-    conversationStorage?: ConversationStorageAdapter;
+    baseDir?: string;
     /**
      * V4-Q: pre-built SDK `CustomTool[]` forwarded RAW to `Agent.create.tools` (appended after the
      * compiled tools), bypassing `defineTool` (which requires a Zod schema). Lets an app whose tools
@@ -736,12 +736,14 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
      */
     skills?: SkillsSelection;
     /**
-     * Conversation memory: the `ConversationStorageAdapter` the agent persists its turns to. Swap it to
-     * control WHERE memory lives — `InMemoryConversationStorage` (ephemeral, great for tests) vs
-     * `FileSystemConversationStorage` (durable) vs a custom adapter. Absent ⇒ the SDK picks its default
-     * store. A per-run override still wins over this agent-level default.
+     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
+     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
+     * `"project"` = `<cwd>/.theokit/`, `"user"` = `~/.theokit/`. Absent ⇒ inline (code) config only.
+     * SECURITY: enabling `"project"` enables shell-executing hooks from `.theokit/hooks.json` — this
+     * is opt-in because `.theokit/` is the app's own repo (informed consent). The SDK owns discovery
+     * + execution (G2 / ADR-0040); theokit only wires this into `Agent.create({ local.settingSources })`.
      */
-    conversationStorage?: ConversationStorageAdapter;
+    settingSources?: readonly SettingSource[];
 }
 /**
  * A branded agent definition — the value {@link defineAgent} returns.
@@ -873,10 +875,12 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      */
     skills(selection: SkillsSelection): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
-     * Set the agent's conversation memory — the `ConversationStorageAdapter` the SDK persists turns to.
-     * Swap in-memory ⇄ filesystem ⇄ custom without touching the runtime. A per-run override still wins.
+     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
+     * MCP, context, cron), discovered by the SDK from the app root (`"project"` = `<cwd>/.theokit/`,
+     * `"user"` = `~/.theokit/`). Unset ⇒ inline (code) config only. SECURITY: `"project"` enables
+     * shell-executing hooks from `.theokit/hooks.json` — opt-in because `.theokit/` is your own repo.
      */
-    conversationStorage(adapter: ConversationStorageAdapter): AgentBuilder<TInput, TModel, TContext, TTools>;
+    settingSources(sources: readonly SettingSource[]): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * Apply a reusable partial chain (Spring-Boot-style composition). `preset` receives the current
      * builder and returns an advanced one; its accumulated type-state flows through.
@@ -974,8 +978,18 @@ interface StreamAgentOptions {
     sessionId: string;
     /** Enable human-in-the-loop tool approval (M4). Absent ⇒ the M2 non-HITL path, byte-unchanged. */
     hitl?: StreamHitlOptions;
-    /** Durable conversation storage for resume (M4); defaults to the SDK per-run in-memory store. */
-    conversationStorage?: RuntimeOverrides['conversationStorage'];
+    /**
+     * theokit-file-based-config (EC-1) — the app root `cwd` the SDK resolves `.theokit/` against when
+     * `settingSources` is active. The framework boundary (`mountAgent`) threads its resolved
+     * `projectRoot` here so discovery points at the app root, NOT `process.cwd()`. Absent ⇒ no `local.cwd`.
+     */
+    cwd?: RuntimeOverrides['cwd'];
+    /**
+     * SDK 4.0 (SE40) — root of the native `.jsonl` session transcript. The framework boundary
+     * (`mountAgent`) threads the resolved app root here so sessions persist per-app; absent ⇒ the SDK
+     * default (`~/.theokit`).
+     */
+    baseDir?: RuntimeOverrides['baseDir'];
     /**
      * The request's abort signal (M4). On client disconnect, the HITL merge queue is closed so the
      * detached SDK pump stops buffering (bounded memory) and the client stream terminates at once.
@@ -1242,8 +1256,6 @@ interface DelegateOptions {
     agents?: Record<string, AgentDefinition$1>;
     /** Per-run SDK budget tracker (inner tool-loop cap). */
     budgetTracker?: BudgetTracker;
-    /** Per-run conversation store (cross-round history). */
-    conversationStorage?: ConversationStorageAdapter;
     /** Per-run pre-built SDK tools forwarded raw (V4-Q). */
     sdkTools?: readonly CustomTool[];
     /** Per-round transient retry (V4-P). */

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApiErrorContext, s as ApiErrorDecision, t as ApiErrorPolicy, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, C as CompiledAgentOptions, E as CompiledContextWindow, a as CompiledTool, F as ContextualTool, H as DefineAgentConfig, I as DelegateFn, J as DelegateOptions, K as DelegationError, D as DelegationResult, M as DoneEvent, N as ErrorEvent, O as FileEditEvent, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, Z as McpApprovalSpec, _ as McpRegistryConfig, $ as McpRequestContext, a0 as McpSelection, a1 as PartialToolCallEvent, a2 as ProcessInputContext, a6 as RunStartedEvent, a7 as ScoreVerdict, a8 as ScoredDelegation, a9 as Scorer, aa as SdkMessage, ab as Segment, ae as StateUpdateEvent, S as StreamEvent, af as TextDeltaEvent, ag as ThinkingEvent, ah as ToolCallEvent, ai as ToolCallVeto, aj as ToolHooks, ak as ToolHooksPlugin, al as ToolResultEvent, am as ToolWalkResult, an as ToolboxWalkResult, ao as agent, ap as agentsPlugin, aq as buildModelSelection, ar as compileAgent, as as compileAgentDefinition, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as compileTools, ay as contextualTool, az as createAgentExecutionContext, aA as createApiErrorHandler, aB as createSdkAgentStream, aC as createThinkTagExtractor, aD as createToolHooksPlugin, aE as delegate, aF as delegateBackground, aG as delegateWithScoring, aH as extractThinkTagStream, aI as generateAgentManifest, aJ as generateAgentRoutes, aK as isAgentContext, aL as isAgentDefinition, aM as isApprovalRequired, aN as isDone, aO as isError, aP as isPartialToolCall, aQ as isTextDelta, aR as isToolCall, aS as isToolResult, aV as mcpRegistry, aW as mcpToolApprovals, aY as projectContextMetadataOnlyKnobs, b0 as resolveMcpServers, b1 as runWithApiErrorHandling, b2 as streamAgentResponse, b3 as streamAgentUIMessages, b4 as translateSdkEvent, b5 as translateToUIMessageStream, b6 as validateUniqueRoutes, b7 as walkAgentMetadata } from './bridge-entry-CAY5JP9z.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApiErrorContext, s as ApiErrorDecision, t as ApiErrorPolicy, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, C as CompiledAgentOptions, E as CompiledContextWindow, a as CompiledTool, F as ContextualTool, H as DefineAgentConfig, I as DelegateFn, J as DelegateOptions, K as DelegationError, D as DelegationResult, M as DoneEvent, N as ErrorEvent, O as FileEditEvent, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, Z as McpApprovalSpec, _ as McpRegistryConfig, $ as McpRequestContext, a0 as McpSelection, a1 as PartialToolCallEvent, a2 as ProcessInputContext, a6 as RunStartedEvent, a7 as ScoreVerdict, a8 as ScoredDelegation, a9 as Scorer, aa as SdkMessage, ab as Segment, ae as StateUpdateEvent, S as StreamEvent, af as TextDeltaEvent, ag as ThinkingEvent, ah as ToolCallEvent, ai as ToolCallVeto, aj as ToolHooks, ak as ToolHooksPlugin, al as ToolResultEvent, am as ToolWalkResult, an as ToolboxWalkResult, ao as agent, ap as agentsPlugin, aq as buildModelSelection, ar as compileAgent, as as compileAgentDefinition, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as compileTools, ay as contextualTool, az as createAgentExecutionContext, aA as createApiErrorHandler, aB as createSdkAgentStream, aC as createThinkTagExtractor, aD as createToolHooksPlugin, aE as delegate, aF as delegateBackground, aG as delegateWithScoring, aH as extractThinkTagStream, aI as generateAgentManifest, aJ as generateAgentRoutes, aK as isAgentContext, aL as isAgentDefinition, aM as isApprovalRequired, aN as isDone, aO as isError, aP as isPartialToolCall, aQ as isTextDelta, aR as isToolCall, aS as isToolResult, aV as mcpRegistry, aW as mcpToolApprovals, aY as projectContextMetadataOnlyKnobs, b0 as resolveMcpServers, b1 as runWithApiErrorHandling, b2 as streamAgentResponse, b3 as streamAgentUIMessages, b4 as translateSdkEvent, b5 as translateToUIMessageStream, b6 as validateUniqueRoutes, b7 as walkAgentMetadata } from './bridge-entry-CE3ie8rG.js';
 import '@theokit/http';
 import './types-DVA4LQsA.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -46,7 +46,7 @@ import {
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-JID4DOB3.js";
+} from "./chunk-OFPS2N3U.js";
 import "./chunk-NERDIS45.js";
 import "./chunk-7QVYU63E.js";
 export {

package/dist/{chunk-JID4DOB3.js → chunk-OFPS2N3U.js}

@@ -820,12 +820,15 @@ function assembleM8CreateOptions(compiled) {
   const base = compiled.systemPrompt;
   if (compiled.skills) {
     options.skills = compiled.skills;
+    applied.push("skills");
+  }
+  const settingSources = resolveSettingSources(compiled);
+  if (settingSources) {
     options.local = {
-      settingSources: [
-        "project"
-      ]
+      ...options.local,
+      settingSources
     };
-    applied.push("skills");
+    applied.push("settingSources");
   }
   if (compiled.context) {
     options.context = compiled.context;
@@ -847,6 +850,17 @@ function assembleM8CreateOptions(compiled) {
   };
 }
 __name(assembleM8CreateOptions, "assembleM8CreateOptions");
+function resolveSettingSources(compiled) {
+  const explicit = compiled.settingSources;
+  if (explicit && explicit.length > 0) return [
+    ...explicit
+  ];
+  if (compiled.skills) return [
+    "project"
+  ];
+  return void 0;
+}
+__name(resolveSettingSources, "resolveSettingSources");
 function realUsageDone(result, t0) {
   const u = result.usage;
   const inputTokens = u?.inputTokens ?? 0;
@@ -994,15 +1008,12 @@ __name(buildExtraCreateOptions, "buildExtraCreateOptions");
 async function loadSdkRuntime() {
   try {
     const sdk = await import("@theokit/sdk");
-    const InMemory = sdk.InMemoryConversationStorage;
     const skillReadTool = "SkillReadTool" in sdk ? sdk.SkillReadTool : void 0;
     return {
       Agent: sdk.Agent,
       // `.bind` keeps the static factory callable when detached from `sdk.Tool` (it takes no `this`,
       // but binding is explicit + satisfies unbound-method rather than relying on that).
       defineTool: sdk.Tool.create.bind(sdk.Tool),
-      InMemoryConversationStorage: InMemory,
-      FileSystemConversationStorage: "FileSystemConversationStorage" in sdk ? sdk.FileSystemConversationStorage : InMemory,
       ...skillReadTool ? {
         defineSkillReadTool: /* @__PURE__ */ __name((skills) => skillReadTool.create(skills), "defineSkillReadTool")
       } : {}
@@ -1013,10 +1024,6 @@ async function loadSdkRuntime() {
   }
 }
 __name(loadSdkRuntime, "loadSdkRuntime");
-function newConversationStorage(compiled, InMemory, FileSystem) {
-  return compiled.checkpoint?.storage === "filesystem" ? new FileSystem() : new InMemory();
-}
-__name(newConversationStorage, "newConversationStorage");
 function createAsyncQueue() {
   const items = [];
   let wake = null;
@@ -1186,7 +1193,6 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
   const reasoningEffort = overrides.reasoningEffort ?? compiled.reasoningEffort;
   const { parseThinkTags, stripToolDialect } = resolveTextTransformFlags(compiled, overrides);
   const runContext = overrides.runContext ?? compiled.runContext;
-  let storage = overrides.conversationStorage ?? compiled.conversationStorage;
   return (message, sessionId, factoryOpts) => ({
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
@@ -1201,7 +1207,6 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
         return;
       }
-      const { InMemoryConversationStorage, FileSystemConversationStorage } = rt;
       const sdkTools = buildSdkTools(compiledTools, rt.defineTool, overrides.sdkTools, runContext);
       const inlineSkills = compiled.skills?.inline;
       if (inlineSkills !== void 0 && inlineSkills.length > 0 && rt.defineSkillReadTool !== void 0 && !compiledTools.some((t) => t.name === "skill_read")) {
@@ -1219,9 +1224,8 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         source: runContextSource,
         keys: runContext !== void 0 ? Object.keys(runContext) : []
       });
-      storage ??= newConversationStorage(compiled, InMemoryConversationStorage, FileSystemConversationStorage);
       try {
-        yield* streamSdkAgent(rt, compiled, sdkTools, storage, {
+        yield* streamSdkAgent(rt, compiled, sdkTools, {
           apiKey,
           model,
           reasoningEffort,
@@ -1246,7 +1250,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
   });
 }
 __name(createSdkAgentStream, "createSdkAgentStream");
-async function* streamSdkAgent(rt, compiled, sdkTools, storage, opts) {
+async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
   const { Agent } = rt;
   const { apiKey, model, reasoningEffort, overrides, parseThinkTags, stripToolDialect, sessionId, message, factoryOpts, runId, t0 } = opts;
   const { options: m8, applied } = assembleM8CreateOptions(compiled);
@@ -1254,6 +1258,10 @@ async function* streamSdkAgent(rt, compiled, sdkTools, storage, opts) {
     ...m8.local,
     cwd: overrides.cwd
   };
+  if (overrides.baseDir !== void 0) m8.local = {
+    ...m8.local,
+    baseDir: overrides.baseDir
+  };
   const extra = buildExtraCreateOptions(overrides, compiled);
   if (applied.length > 0) {
     debugLog("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
@@ -1267,8 +1275,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, storage, opts) {
     model: buildModelSelection(model, reasoningEffort),
     tools: sdkTools,
     ...m8,
-    ...extra,
-    conversationStorage: storage
+    ...extra
   });
   try {
     const queue = createAsyncQueue();
@@ -1502,10 +1509,10 @@ function compileAgentDefinition(def) {
     } : {},
     // M13 — skills: a static list → SDK skills.enabled; a resolver → carried for the request path.
     ...compileSkillsSelection(def.skills),
-    // Conversation memory: the declared adapter flows to the run path, which hands it to
-    // `Agent.getOrCreate({ conversationStorage })`; absent ⇒ the SDK default is chosen lazily.
-    ...def.conversationStorage !== void 0 ? {
-      conversationStorage: def.conversationStorage
+    // theokit-file-based-config — the declared `.theokit/` sources flow to the run path, which
+    // projects them into `Agent.create({ local.settingSources })`; absent ⇒ inline config only.
+    ...def.settingSources !== void 0 ? {
+      settingSources: def.settingSources
     } : {}
   };
 }
@@ -1607,10 +1614,10 @@ function makeBuilder(config) {
       ...config,
       skills: selection
     }), "skills"),
-    conversationStorage: /* @__PURE__ */ __name((adapter) => makeBuilder({
+    settingSources: /* @__PURE__ */ __name((sources) => makeBuilder({
       ...config,
-      conversationStorage: adapter
-    }), "conversationStorage"),
+      settingSources: sources
+    }), "settingSources"),
     use: /* @__PURE__ */ __name((preset) => preset(runtime), "use"),
     build: /* @__PURE__ */ __name(() => defineAgent(config), "build")
   };
@@ -1762,7 +1769,8 @@ __name(appendCheckpointSaved, "appendCheckpointSaved");
 function streamAgentUIMessages(compiled, apiKey, input) {
   const textId = crypto.randomUUID();
   const overrides = {};
-  if (input.conversationStorage) overrides.conversationStorage = input.conversationStorage;
+  if (input.cwd !== void 0) overrides.cwd = input.cwd;
+  if (input.baseDir !== void 0) overrides.baseDir = input.baseDir;
   let source;
   if (!input.hitl || input.hitl.gated.size === 0) {
     const events2 = createSdkAgentStream(compiled, compiled.tools, apiKey, overrides)(input.message, input.sessionId);
@@ -2447,11 +2455,11 @@ var AgentRunner = class {
       stripToolDialect: opts.stripToolDialect,
       recoverLeakedToolCalls: opts.recoverLeakedToolCalls,
       cwd: opts.cwd,
+      baseDir: opts.baseDir,
       plugins: opts.plugins,
       providers: opts.providers,
       agents: opts.agents,
       budgetTracker: opts.budgetTracker,
-      conversationStorage: opts.conversationStorage,
       sdkTools: opts.sdkTools
     });
     const sessionId = opts.sessionId ?? `runner-${crypto.randomUUID()}`;
@@ -2569,7 +2577,6 @@ async function delegate(SubAgentClass, message, opts = {}) {
     providers: opts.providers,
     agents: opts.agents,
     budgetTracker: opts.budgetTracker,
-    conversationStorage: opts.conversationStorage,
     sdkTools: opts.sdkTools
   });
   const sessionId = opts.sessionId ?? `sub-${crypto.randomUUID()}`;
@@ -2986,4 +2993,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-JID4DOB3.js.map
+//# sourceMappingURL=chunk-OFPS2N3U.js.map