@theokit/sdk 4.19.0 → 4.19.2

package/dist/goal-loop.d.ts

@@ -0,0 +1,35 @@
+/**
+ * M56 (agent-builder goal transparency) — PUBLIC goal-loop driver for CUSTOM agent surfaces.
+ *
+ * `LocalAgent.runUntil` binds the goal loop to a registered local agent. Surfaces that route turns
+ * through their OWN transport (e.g. a TUI store facade, so every goal turn renders in the same
+ * timeline as a manual turn) need the SAME loop over a minimal `send → wait` shape. This export
+ * gives them exactly that: the canonical `runUntilImpl` (judge + continuation + token budget +
+ * Codex states) with the default judge wired from the DI registry.
+ *
+ * @public
+ */
+import type { RunUntilDeps } from "./internal/runtime/lifecycle/run-until.js";
+/**
+ * Stable marker on the FIRST LINE of every goal-continuation prompt. Surfaces detect it to render the
+ * turn collapsed, exclude it from backtrack windows, and skip it in compaction preservation.
+ */
+export declare const GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+import type { GoalEvent, GoalOptions, GoalResult } from "./types/goal-events.js";
+/** The minimal surface the goal loop drives — anything that can send a prompt and wait for it. */
+export interface GoalLoopAgent {
+    send(prompt: string): Promise<{
+        wait(): Promise<{
+            result?: string;
+            usage?: {
+                totalTokens?: number;
+            };
+        }>;
+    }>;
+}
+/**
+ * Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.
+ * Identical semantics to `Agent.runUntil` (ADRs D115-D121 + M55 token budget / states).
+ * `depsOverride` is a test seam for injecting a fake judge.
+ */
+export declare function runGoalLoop(agent: GoalLoopAgent, goal: string, options?: GoalOptions, depsOverride?: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;

package/dist/index.cjs

@@ -6174,12 +6174,14 @@ __export(compact_session_exports, {
   shouldAutoCompact: () => shouldAutoCompact
 });
 function isCompactSummary(content) {
-  return content.startsWith(COMPACT_SUMMARY_MARKER);
+  return content.startsWith(COMPACT_SUMMARY_MARKER) || content.startsWith("[[theokit:goal-continuation]]");
 }
 function plainText(content) {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return void 0;
-  const texts = content.filter((p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string").map((p) => p.text);
+  const texts = content.filter(
+    (p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string"
+  ).map((p) => p.text);
   return texts.length > 0 ? texts.join("\n") : void 0;
 }
 async function compactSessionTranscript(opts) {
@@ -6300,8 +6302,10 @@ async function autoCompactIfNeeded(opts) {
     return true;
   } catch (cause) {
     const msg = cause instanceof Error ? cause.message : String(cause);
-    process.stderr.write(`[theokit-sdk] auto-compaction failed (left transcript untouched): ${msg}
-`);
+    process.stderr.write(
+      `[theokit-sdk] auto-compaction failed (left transcript untouched): ${msg}
+`
+    );
     return false;
   }
 }
@@ -6311,11 +6315,11 @@ var init_compact_session = __esm({
     init_compaction();
     init_router();
     init_real_local_run_provider();
+    init_session_transcript();
     init_providers();
     init_compression_model_registry();
     init_compression_summarizer();
     init_agent_session();
-    init_session_transcript();
     COMPACT_SUMMARY_MARKER = "[[theokit:compact-summary]]";
     COMPACT_USER_MESSAGE_MAX_TOKENS = 2e4;
     autoCompactAttempts = (() => {
@@ -6537,7 +6541,9 @@ async function loadDriver(filePath) {
   }
   try {
     const mod = await (driverLoaderOverrides?.nodeSqlite?.() ?? Promise.resolve(
-      process.getBuiltinModule?.("node:sqlite") ?? (() => {
+      process.getBuiltinModule?.(
+        "node:sqlite"
+      ) ?? (() => {
         throw new Error("node:sqlite built-in unavailable (Node < 22.3)");
       })()
     ));
@@ -7504,6 +7510,133 @@ var init_context = __esm({
   }
 });
 
+// src/internal/judge/parse-verdict.ts
+function parseVerdict(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith(DONE_PREFIX)) {
+    return {
+      verdict: "done",
+      reason: trimmed.slice(DONE_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  if (trimmed.startsWith(CONTINUE_PREFIX)) {
+    return {
+      verdict: "continue",
+      reason: trimmed.slice(CONTINUE_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  if (trimmed.startsWith(SKIPPED_PREFIX)) {
+    return {
+      verdict: "skipped",
+      reason: trimmed.slice(SKIPPED_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  return {
+    verdict: "continue",
+    reason: `judge response malformed: "${trimmed.slice(0, 100)}"`,
+    parseFailed: true
+  };
+}
+var DONE_PREFIX, CONTINUE_PREFIX, SKIPPED_PREFIX;
+var init_parse_verdict = __esm({
+  "src/internal/judge/parse-verdict.ts"() {
+    DONE_PREFIX = "DONE:";
+    CONTINUE_PREFIX = "CONTINUE:";
+    SKIPPED_PREFIX = "SKIPPED:";
+  }
+});
+
+// src/internal/judge/judge-call.ts
+var judge_call_exports = {};
+__export(judge_call_exports, {
+  composeJudgePrompt: () => composeJudgePrompt,
+  judgeCallImpl: () => judgeCallImpl
+});
+async function judgeCallImpl(ctx, options, deps) {
+  const prompt = composeJudgePrompt(ctx);
+  const apiKey = options?.apiKey ?? process.env.OPENROUTER_API_KEY;
+  if (apiKey === void 0) {
+    return {
+      verdict: "continue",
+      reason: "judge unavailable: OPENROUTER_API_KEY missing and no override passed via options.apiKey",
+      parseFailed: true
+    };
+  }
+  const judgeModel = options?.judgeModel ?? "openai/gpt-4o-mini";
+  let auxAgent;
+  try {
+    auxAgent = await deps.create({
+      apiKey,
+      model: { id: judgeModel },
+      tools: [],
+      local: {},
+      metadata: { forkOrigin: "judge" }
+    });
+    const run = await auxAgent.send(prompt);
+    const result = await run.wait();
+    return parseVerdict(result.result ?? "");
+  } catch (err) {
+    return {
+      verdict: "continue",
+      reason: `judge call failed: ${err instanceof Error ? err.message : String(err)}`,
+      parseFailed: true
+    };
+  } finally {
+    if (auxAgent !== void 0) {
+      try {
+        await auxAgent.dispose();
+      } catch {
+      }
+    }
+  }
+}
+function composeJudgePrompt(ctx) {
+  const subgoals = ctx.subgoals !== void 0 && ctx.subgoals.length > 0 ? ctx.subgoals.join(", ") : "(none)";
+  return `You are a goal judge. Determine if this goal is satisfied.
+
+Goal: ${ctx.goal}
+Subgoals: ${subgoals}
+Last agent response: ${ctx.lastResponse}
+
+Respond with EXACTLY one of:
+- DONE: <reason>
+- CONTINUE: <what's left>
+- SKIPPED: <why not applicable>
+
+Be strict. If unclear, prefer CONTINUE.`;
+}
+var init_judge_call = __esm({
+  "src/internal/judge/judge-call.ts"() {
+    init_parse_verdict();
+  }
+});
+
+// src/goal-loop.ts
+function runGoalLoop(agent, goal, options, depsOverride) {
+  async function* wrap() {
+    const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
+    const deps = depsOverride ?? await (async () => {
+      const { judgeCallImpl: judgeCallImpl2 } = await Promise.resolve().then(() => (init_judge_call(), judge_call_exports));
+      const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
+      const create = getAgentFacade2().create;
+      return {
+        judge: (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
+      };
+    })();
+    return yield* runUntilImpl2(agent, goal, options, deps);
+  }
+  return wrap();
+}
+exports.GOAL_CONTINUATION_MARKER = void 0;
+var init_goal_loop = __esm({
+  "src/goal-loop.ts"() {
+    exports.GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+  }
+});
+
 // src/internal/runtime/lifecycle/run-until.ts
 var run_until_exports = {};
 __export(run_until_exports, {
@@ -7647,6 +7780,7 @@ async function* runUntilImpl(agent, goal, options, deps) {
 }
 function composeContinuation(goal, lastResponse) {
   return [
+    exports.GOAL_CONTINUATION_MARKER,
     "Continue working toward the active goal.",
     "",
     `<objective>
@@ -7667,115 +7801,12 @@ ${goal}
     "  current state, requirement by requirement. Treat uncertain or indirect evidence as not achieved.",
     "",
     `Your last response was:
-${lastResponse.slice(0, 1e3)}`
+${lastResponse.slice(-1e3)}`
   ].join("\n");
 }
 var init_run_until = __esm({
   "src/internal/runtime/lifecycle/run-until.ts"() {
-  }
-});
-
-// src/internal/judge/parse-verdict.ts
-function parseVerdict(text) {
-  const trimmed = text.trim();
-  if (trimmed.startsWith(DONE_PREFIX)) {
-    return {
-      verdict: "done",
-      reason: trimmed.slice(DONE_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  if (trimmed.startsWith(CONTINUE_PREFIX)) {
-    return {
-      verdict: "continue",
-      reason: trimmed.slice(CONTINUE_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  if (trimmed.startsWith(SKIPPED_PREFIX)) {
-    return {
-      verdict: "skipped",
-      reason: trimmed.slice(SKIPPED_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  return {
-    verdict: "continue",
-    reason: `judge response malformed: "${trimmed.slice(0, 100)}"`,
-    parseFailed: true
-  };
-}
-var DONE_PREFIX, CONTINUE_PREFIX, SKIPPED_PREFIX;
-var init_parse_verdict = __esm({
-  "src/internal/judge/parse-verdict.ts"() {
-    DONE_PREFIX = "DONE:";
-    CONTINUE_PREFIX = "CONTINUE:";
-    SKIPPED_PREFIX = "SKIPPED:";
-  }
-});
-
-// src/internal/judge/judge-call.ts
-var judge_call_exports = {};
-__export(judge_call_exports, {
-  composeJudgePrompt: () => composeJudgePrompt,
-  judgeCallImpl: () => judgeCallImpl
-});
-async function judgeCallImpl(ctx, options, deps) {
-  const prompt = composeJudgePrompt(ctx);
-  const apiKey = options?.apiKey ?? process.env.OPENROUTER_API_KEY;
-  if (apiKey === void 0) {
-    return {
-      verdict: "continue",
-      reason: "judge unavailable: OPENROUTER_API_KEY missing and no override passed via options.apiKey",
-      parseFailed: true
-    };
-  }
-  const judgeModel = options?.judgeModel ?? "openai/gpt-4o-mini";
-  let auxAgent;
-  try {
-    auxAgent = await deps.create({
-      apiKey,
-      model: { id: judgeModel },
-      tools: [],
-      local: {},
-      metadata: { forkOrigin: "judge" }
-    });
-    const run = await auxAgent.send(prompt);
-    const result = await run.wait();
-    return parseVerdict(result.result ?? "");
-  } catch (err) {
-    return {
-      verdict: "continue",
-      reason: `judge call failed: ${err instanceof Error ? err.message : String(err)}`,
-      parseFailed: true
-    };
-  } finally {
-    if (auxAgent !== void 0) {
-      try {
-        await auxAgent.dispose();
-      } catch {
-      }
-    }
-  }
-}
-function composeJudgePrompt(ctx) {
-  const subgoals = ctx.subgoals !== void 0 && ctx.subgoals.length > 0 ? ctx.subgoals.join(", ") : "(none)";
-  return `You are a goal judge. Determine if this goal is satisfied.
-
-Goal: ${ctx.goal}
-Subgoals: ${subgoals}
-Last agent response: ${ctx.lastResponse}
-
-Respond with EXACTLY one of:
-- DONE: <reason>
-- CONTINUE: <what's left>
-- SKIPPED: <why not applicable>
-
-Be strict. If unclear, prefer CONTINUE.`;
-}
-var init_judge_call = __esm({
-  "src/internal/judge/judge-call.ts"() {
-    init_parse_verdict();
+    init_goal_loop();
   }
 });
 
@@ -21315,8 +21346,8 @@ async function getRegisteredAgentOrThrow(agentId) {
 // src/agent.ts
 init_errors();
 init_discovery();
-init_agent_session();
 init_agent_factory_registry();
+init_agent_session();
 var streamObjectImport;
 var Agent = class _Agent {
   constructor() {
@@ -21608,7 +21639,9 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new exports.UnknownAgentError(`No local agent "${agentId}" registered \u2014 compact targets local sessions.`);
+      throw new exports.UnknownAgentError(
+        `No local agent "${agentId}" registered \u2014 compact targets local sessions.`
+      );
     }
     const cwd = reg.cwd ?? process.cwd();
     const optModel = reg.options.model;
@@ -21618,16 +21651,20 @@ var Agent = class _Agent {
     const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await Promise.resolve().then(() => (init_session_transcript(), session_transcript_exports));
     const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
     const store = new FsSessionStore2({ baseDir, cwd });
-    return enqueueSessionWrite(cwd, agentId, () => compactSessionTranscript2({
-      store,
-      loc: { cwd, agentId, model },
-      sessionId: agentId,
-      trigger: options.trigger ?? "manual",
-      summarize: options.summarize ?? buildDefaultSummarizer2({
-        agentModel: model,
-        ...reg.options.apiKey !== void 0 ? { apiKey: reg.options.apiKey } : {}
+    return enqueueSessionWrite(
+      cwd,
+      agentId,
+      () => compactSessionTranscript2({
+        store,
+        loc: { cwd, agentId, model },
+        sessionId: agentId,
+        trigger: options.trigger ?? "manual",
+        summarize: options.summarize ?? buildDefaultSummarizer2({
+          agentModel: model,
+          ...reg.options.apiKey !== void 0 ? { apiKey: reg.options.apiKey } : {}
+        })
       })
-    }));
+    );
   }
   /**
    * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
@@ -21644,7 +21681,9 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new exports.UnknownAgentError(`No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`);
+      throw new exports.UnknownAgentError(
+        `No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`
+      );
     }
     const cwd = reg.cwd ?? process.cwd();
     const optModel = reg.options.model;
@@ -22670,23 +22709,6 @@ async function updateJobStatus(jobId, enabled) {
   return updated;
 }
 
-// src/goal-loop.ts
-function runGoalLoop(agent, goal, options, depsOverride) {
-  async function* wrap() {
-    const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
-    const deps = depsOverride ?? await (async () => {
-      const { judgeCallImpl: judgeCallImpl2 } = await Promise.resolve().then(() => (init_judge_call(), judge_call_exports));
-      const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
-      const create = getAgentFacade2().create;
-      return {
-        judge: (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
-      };
-    })();
-    return yield* runUntilImpl2(agent, goal, options, deps);
-  }
-  return wrap();
-}
-
 // src/define-provider.ts
 init_builtin();
 init_registry();
@@ -22826,6 +22848,7 @@ var EventBus = class {
 
 // src/index.ts
 init_generate_object();
+init_goal_loop();
 
 // src/internal/budget/tracker/budget-tracker-counter.ts
 function createCounterBudgetTracker(options = {}) {