@theokit/sdk 2.28.0 → 2.30.0

package/dist/a2a/index.js

@@ -1365,7 +1365,7 @@ function safeFilenameForId(id, options) {
       code: "invalid_filename_id"
     });
   }
-  const maxLen = options?.maxLen;
+  const maxLen = options?.maxLen ?? 128;
   const lower = id.toLowerCase();
   if (lower.length <= maxLen && IDENTIFIER_PATTERN.test(lower)) {
     return lower;
@@ -5112,6 +5112,40 @@ var init_agent_session_store = __esm({
   }
 });
 
+// src/internal/persistence/objective-coerce.ts
+function coerceOptions(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const o = raw;
+  const out = {};
+  if (typeof o.maxRuns === "number") out.maxRuns = o.maxRuns;
+  if (typeof o.judgeModel === "string") out.judgeModel = o.judgeModel;
+  if (typeof o.prompt === "string") out.prompt = o.prompt;
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function coerceObjectiveRecord(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const o = raw;
+  if (o._schemaVersion !== 1) return void 0;
+  if (typeof o.objective !== "string") return void 0;
+  if (typeof o.runsUsed !== "number") return void 0;
+  if (typeof o.status !== "string" || !STATUSES.includes(o.status))
+    return void 0;
+  const options = coerceOptions(o.options);
+  return {
+    _schemaVersion: 1,
+    objective: o.objective,
+    ...options !== void 0 ? { options } : {},
+    status: o.status,
+    runsUsed: o.runsUsed
+  };
+}
+var STATUSES;
+var init_objective_coerce = __esm({
+  "src/internal/persistence/objective-coerce.ts"() {
+    STATUSES = ["active", "done", "paused"];
+  }
+});
+
 // src/internal/persistence/pagination.ts
 function paginate(items, opts) {
   if (opts === void 0 || opts.offset === void 0 && opts.limit === void 0) return items;
@@ -5162,7 +5196,9 @@ var init_conversation_storage_fs = __esm({
   "src/internal/persistence/conversation-storage-fs.ts"() {
     init_agent_session_store();
     init_security();
+    init_path_guard();
     init_file_lock();
+    init_objective_coerce();
     init_pagination();
     init_session_meta();
     FileSystemConversationStorage = class {
@@ -5245,6 +5281,59 @@ var init_conversation_storage_fs = __esm({
           await writeFile(metaPath, redactSecrets(JSON.stringify(next)), "utf8");
         });
       }
+      // SE33 — the durable objective is kept in `objective.json` beside the
+      // transcript (separate from messages.jsonl + session.json). Uses the TOTAL
+      // `safeFilenameForId` (not `sanitizeIdentifier`) so a caller-supplied
+      // `threadId` with exotic characters (e.g. "user@example.com") hashes to a
+      // deterministic dir instead of throwing — honoring the objective methods'
+      // never-throw contract (ADR D6). Conforming ids pass through unchanged, so
+      // the objective still sits beside the transcript for the normal case.
+      #objectivePath(conversationId) {
+        const safe2 = safeFilenameForId(conversationId, { maxLen: 128 });
+        return safePathJoin(this.#root, ".theokit", "agents", safe2, "objective.json");
+      }
+      async getObjectiveRecord(conversationId) {
+        try {
+          const raw = await readFile(this.#objectivePath(conversationId), "utf8");
+          return coerceObjectiveRecord(JSON.parse(raw));
+        } catch (cause) {
+          if (cause.code === "ENOENT") return void 0;
+          throw cause;
+        }
+      }
+      async setObjectiveRecord(conversationId, record) {
+        const path = this.#objectivePath(conversationId);
+        if (record === null) {
+          await rm(path, { force: true });
+          return;
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await withFileLock(path, async () => {
+          await writeFile(path, redactSecrets(JSON.stringify(record)), "utf8");
+        });
+      }
+      // SE33 (HIGH-1 fix) — atomic read-modify-write: the read that feeds `mutate`
+      // happens INSIDE the same file lock as the write, so two concurrent progress
+      // write-backs on one thread cannot both read a stale `runsUsed` and drop turns.
+      async updateObjectiveRecord(conversationId, mutate) {
+        const path = this.#objectivePath(conversationId);
+        await mkdir(dirname(path), { recursive: true });
+        await withFileLock(path, async () => {
+          let current;
+          try {
+            current = coerceObjectiveRecord(JSON.parse(await readFile(path, "utf8")));
+          } catch (cause) {
+            if (cause.code !== "ENOENT") throw cause;
+          }
+          const next = mutate(current);
+          if (next === void 0) return;
+          if (next === null) {
+            await rm(path, { force: true });
+            return;
+          }
+          await writeFile(path, redactSecrets(JSON.stringify(next)), "utf8");
+        });
+      }
       async dispose() {
       }
     };
@@ -13279,6 +13368,151 @@ var init_local_agent_dispatch = __esm({
   }
 });
 
+// src/internal/runtime/objective/objective-store.ts
+function canPersist(a) {
+  return typeof a.getObjectiveRecord === "function" && typeof a.setObjectiveRecord === "function";
+}
+async function mutateObjective(adapter, conversationId, mutate) {
+  if (typeof adapter.updateObjectiveRecord === "function") {
+    await adapter.updateObjectiveRecord(conversationId, mutate);
+    return;
+  }
+  const current = await adapter.getObjectiveRecord(conversationId);
+  const next = mutate(current);
+  if (next === void 0) return;
+  await adapter.setObjectiveRecord(conversationId, next);
+}
+async function getObjective(adapter, conversationId) {
+  if (!canPersist(adapter)) return void 0;
+  return adapter.getObjectiveRecord(conversationId);
+}
+async function setObjective(adapter, conversationId, objective, options) {
+  if (!canPersist(adapter)) return;
+  const record = {
+    _schemaVersion: 1,
+    objective,
+    ...options !== void 0 ? { options } : {},
+    status: "active",
+    runsUsed: 0
+  };
+  await adapter.setObjectiveRecord(conversationId, record);
+}
+async function updateObjectiveOptions(adapter, conversationId, patch) {
+  if (!canPersist(adapter)) return;
+  await mutateObjective(
+    adapter,
+    conversationId,
+    (current) => current === void 0 ? void 0 : { ...current, options: { ...current.options, ...patch } }
+  );
+}
+async function writeObjectiveProgress(adapter, conversationId, progress) {
+  if (!canPersist(adapter)) return;
+  await mutateObjective(
+    adapter,
+    conversationId,
+    (current) => current === void 0 ? void 0 : { ...current, runsUsed: progress.runsUsed, status: progress.status }
+  );
+}
+async function clearObjective(adapter, conversationId) {
+  if (!canPersist(adapter)) return;
+  await adapter.setObjectiveRecord(conversationId, null);
+}
+var init_objective_store = __esm({
+  "src/internal/runtime/objective/objective-store.ts"() {
+  }
+});
+
+// src/internal/runtime/local-agent/local-agent-goal-extensions.ts
+var local_agent_goal_extensions_exports = {};
+__export(local_agent_goal_extensions_exports, {
+  formatObjectiveProjection: () => formatObjectiveProjection,
+  localAgentClearObjective: () => localAgentClearObjective,
+  localAgentGetObjective: () => localAgentGetObjective,
+  localAgentSetObjective: () => localAgentSetObjective,
+  localAgentUpdateObjectiveOptions: () => localAgentUpdateObjectiveOptions,
+  persistDurableProgress: () => persistDurableProgress,
+  resolveCurrentObjectiveText: () => resolveCurrentObjectiveText,
+  resolveDurableRun: () => resolveDurableRun
+});
+function resolveAdapter(handle) {
+  return typeof handle === "string" ? new FileSystemConversationStorage({ root: handle }) : handle;
+}
+function assertValidGoalOptions(options) {
+  if (options.maxRuns !== void 0 && (!Number.isInteger(options.maxRuns) || options.maxRuns <= 0)) {
+    throw new ConfigurationError(`maxRuns must be a positive integer, got ${options.maxRuns}`, {
+      code: "invalid_objective_max_runs"
+    });
+  }
+}
+async function localAgentSetObjective(handle, objective, opts) {
+  const { threadId, ...options } = opts;
+  assertValidGoalOptions(options);
+  await setObjective(
+    resolveAdapter(handle),
+    threadId,
+    objective,
+    Object.keys(options).length > 0 ? options : void 0
+  );
+}
+async function localAgentGetObjective(handle, opts) {
+  return getObjective(resolveAdapter(handle), opts.threadId);
+}
+async function localAgentUpdateObjectiveOptions(handle, opts) {
+  const { threadId, ...patch } = opts;
+  assertValidGoalOptions(patch);
+  await updateObjectiveOptions(resolveAdapter(handle), threadId, patch);
+}
+async function localAgentClearObjective(handle, opts) {
+  await clearObjective(resolveAdapter(handle), opts.threadId);
+}
+async function resolveCurrentObjectiveText(handle, threadId) {
+  const record = await getObjective(resolveAdapter(handle), threadId);
+  return record?.status === "active" ? record.objective : void 0;
+}
+function formatObjectiveProjection(objective, assembled) {
+  const signal = `<current-objective>
+${objective}
+</current-objective>`;
+  return assembled === void 0 || assembled.length === 0 ? signal : `${signal}
+
+${assembled}`;
+}
+async function resolveDurableRun(handle, goalConfig, threadId, callerOptions) {
+  const record = await getObjective(resolveAdapter(handle), threadId);
+  if (record === void 0) return { kind: "none" };
+  const judgeModel = callerOptions?.judgeModel ?? record.options?.judgeModel ?? goalConfig?.judgeModel;
+  if (judgeModel === void 0) return { kind: "inert" };
+  const totalBudget = record.options?.maxRuns ?? goalConfig?.maxRuns ?? DEFAULT_MAX_RUNS;
+  const remaining = Math.max(0, totalBudget - record.runsUsed);
+  if (remaining === 0) return { kind: "exhausted" };
+  const perCall = callerOptions?.maxTurns;
+  const maxTurns = perCall !== void 0 ? Math.min(perCall, remaining) : remaining;
+  return {
+    kind: "run",
+    goal: record.objective,
+    options: { ...callerOptions, maxTurns, judgeModel }
+  };
+}
+async function persistDurableProgress(handle, threadId, result) {
+  const adapter = resolveAdapter(handle);
+  const record = await getObjective(adapter, threadId);
+  if (record === void 0) return;
+  const status = result.status === "completed" ? "done" : result.status === "paused" ? "paused" : "active";
+  await writeObjectiveProgress(adapter, threadId, {
+    runsUsed: record.runsUsed + result.turnsUsed,
+    status
+  });
+}
+var DEFAULT_MAX_RUNS;
+var init_local_agent_goal_extensions = __esm({
+  "src/internal/runtime/local-agent/local-agent-goal-extensions.ts"() {
+    init_errors();
+    init_conversation_storage_fs();
+    init_objective_store();
+    DEFAULT_MAX_RUNS = 20;
+  }
+});
+
 // src/internal/runtime/local-agent/local-agent-invalidate.ts
 async function applyDeferredInvalidation(agentId, pending, refresh) {
   process.stderr.write(
@@ -16281,16 +16515,49 @@ var init_fork_agent = __esm({
 });
 
 // src/internal/runtime/local-agent/local-agent-runtime-extensions.ts
-function localAgentRunUntil(agent, goal, options) {
+function pausedReason(kind, threadId) {
+  switch (kind) {
+    case "none":
+      return `no durable objective set for thread "${threadId}" \u2014 call setObjective() first`;
+    case "inert":
+      return `durable objective for thread "${threadId}" is inert \u2014 no judge resolved (set a judge to activate)`;
+    case "exhausted":
+      return `durable objective for thread "${threadId}" exhausted its run budget \u2014 raise maxRuns to resume`;
+  }
+}
+function localAgentRunUntil(agent, goal, options, durable) {
   async function* wrap() {
     const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
-    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;
-    const deps = {
-      judge: async (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
+    const buildDeps = 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);
+    if (goal !== void 0) {
+      return yield* runUntilImpl2(agent, goal, options, await buildDeps());
+    }
+    const threadId = options?.threadId;
+    if (durable === void 0 || threadId === void 0) {
+      const reason = "runUntil() called with no goal and no threadId \u2014 nothing to resolve a durable objective from";
+      yield { type: "status_change", status: "paused", reason };
+      return { status: "paused", turnsUsed: 0, finalResponse: void 0 };
+    }
+    const { resolveDurableRun: resolveDurableRun2, persistDurableProgress: persistDurableProgress2 } = await Promise.resolve().then(() => (init_local_agent_goal_extensions(), local_agent_goal_extensions_exports));
+    const resolved = await resolveDurableRun2(durable.handle, durable.goalConfig, threadId, options);
+    if (resolved.kind !== "run") {
+      yield {
+        type: "status_change",
+        status: "paused",
+        reason: pausedReason(resolved.kind, threadId)
+      };
+      return { status: "paused", turnsUsed: 0, finalResponse: void 0 };
+    }
+    const result = yield* runUntilImpl2(agent, resolved.goal, resolved.options, await buildDeps());
+    await persistDurableProgress2(durable.handle, threadId, result);
+    return result;
   }
   return wrap();
 }
@@ -16363,6 +16630,49 @@ var init_abort_utils = __esm({
   }
 });
 
+// src/internal/runtime/lifecycle/wrap-completion-check-run.ts
+function wrapRunWithCompletionCheck(args) {
+  const check = args.completionCheck;
+  if (check === void 0) return args.run;
+  const compute = async () => {
+    const result = await args.run.wait();
+    if (result.status !== "finished" || result.result === void 0) return result;
+    const judgeOpts = {};
+    if (check.judgeModel !== void 0) judgeOpts.judgeModel = check.judgeModel;
+    if (check.apiKey !== void 0) judgeOpts.apiKey = check.apiKey;
+    const verdict = await args.deps.judge(
+      { goal: check.criteria, lastResponse: result.result },
+      judgeOpts
+    );
+    const complete = !verdict.parseFailed && verdict.verdict === "done";
+    emitRunEvent(args.onRunEvent, {
+      type: "completion_check",
+      complete,
+      reason: verdict.reason
+    });
+    return {
+      ...result,
+      completionCheck: { complete, reason: verdict.reason, parseFailed: verdict.parseFailed }
+    };
+  };
+  let judged;
+  const wrappedWait = () => {
+    judged ??= compute();
+    return judged;
+  };
+  return new Proxy(args.run, {
+    get(target, prop, receiver) {
+      if (prop === "wait") return wrappedWait;
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+var init_wrap_completion_check_run = __esm({
+  "src/internal/runtime/lifecycle/wrap-completion-check-run.ts"() {
+    init_run_events();
+  }
+});
+
 // src/internal/runtime/processors/run-processors.ts
 function fireViolation(processor, violation) {
   try {
@@ -16639,6 +16949,11 @@ async function executeSendLocked(inputs, message, options) {
     memoryFacts,
     activeMemorySummary
   );
+  const projectedSystemPrompt = await projectCurrentObjective(
+    inputs.storageHandle,
+    options.objectiveThreadId,
+    assembledSystemPrompt
+  );
   const composedOptions = {
     ...options,
     signal: anySignal([options.signal, inputs.lifecycleAbortController.signal])
@@ -16646,7 +16961,7 @@ async function executeSendLocked(inputs, message, options) {
   const run = await inputs.dispatchRun(
     adaptedMessage,
     composedOptions,
-    assembledSystemPrompt,
+    projectedSystemPrompt,
     memoryFacts,
     priorMessages,
     memoryTools,
@@ -16659,23 +16974,49 @@ async function executeSendLocked(inputs, message, options) {
     agentId: inputs.agentId,
     onRunEvent: options.onRunEvent
   }) : run;
-  return wrapRunWithPostReplyHook({
+  const hookedRun = wrapRunWithPostReplyHook({
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
     run: processedRun,
     userText
   });
+  return wrapRunWithCompletionCheck({
+    run: hookedRun,
+    completionCheck: options.completionCheck,
+    onRunEvent: options.onRunEvent,
+    deps: buildCompletionCheckDeps()
+  });
+}
+function buildCompletionCheckDeps() {
+  return {
+    judge: async (ctx, opts) => {
+      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));
+      return judgeCallImpl2(ctx, opts, { create: getAgentFacade2().create });
+    }
+  };
 }
 function readMemoryForSend(workspaceCwd, memoryConfig) {
   if (memoryConfig?.enabled !== true) return Promise.resolve([]);
   return safeCall(() => readMemoryFacts(workspaceCwd, memoryConfig), [], "memory read");
 }
+async function projectCurrentObjective(storageHandle, objectiveThreadId, assembled) {
+  if (objectiveThreadId === void 0) return assembled;
+  const objective = await safeCall(
+    () => resolveCurrentObjectiveText(storageHandle, objectiveThreadId),
+    void 0,
+    "objective projection"
+  );
+  if (objective === void 0) return assembled;
+  return formatObjectiveProjection(objective, assembled);
+}
 var init_local_agent_send = __esm({
   "src/internal/runtime/local-agent/local-agent-send.ts"() {
     init_errors();
     init_run_events();
     init_abort_utils();
+    init_wrap_completion_check_run();
     init_memory_path_selector();
     init_memory_store();
     init_model_selection();
@@ -16684,6 +17025,7 @@ var init_local_agent_send = __esm({
     init_wrap_output_run();
     init_agent_session();
     init_safe_call();
+    init_local_agent_goal_extensions();
     init_local_agent_invalidate();
     init_local_agent_memory_hooks();
     init_local_agent_runtime_extensions();
@@ -17283,6 +17625,7 @@ var init_local_agent = __esm({
     init_validate_agent_options();
     init_local_agent_bootstrap();
     init_local_agent_dispatch();
+    init_local_agent_goal_extensions();
     init_local_agent_invalidate();
     init_local_agent_memory();
     init_local_agent_memory_direct();
@@ -17622,20 +17965,33 @@ var init_local_agent = __esm({
           ...opts !== void 0 ? { opts } : {}
         });
       }
+      // biome-ignore format: G8 budget — artifact stubs (local agents have no artifacts); kept 1-line each.
       listArtifacts() {
         return Promise.resolve([]);
       }
+      // biome-ignore format: G8 budget — see listArtifacts.
       downloadArtifact(_path) {
-        return Promise.reject(
-          new UnsupportedRunOperationError(
-            "Artifacts are not supported for local agents",
-            "downloadArtifact"
-          )
-        );
+        return Promise.reject(new UnsupportedRunOperationError("Artifacts are not supported for local agents", "downloadArtifact"));
       }
       // biome-ignore format: G8 budget — both methods delegate to `local-agent-runtime-extensions.ts`; signatures kept as 1-line each.
       runUntil(goal, options) {
-        return localAgentRunUntil(this, goal, options);
+        return localAgentRunUntil(this, goal, options, { handle: this.storageHandle(), goalConfig: this.options.goal });
+      }
+      // biome-ignore format: SE33 G8 budget — objective methods delegate to `local-agent-goal-extensions.ts`.
+      setObjective(objective, opts) {
+        return localAgentSetObjective(this.storageHandle(), objective, opts);
+      }
+      // biome-ignore format: SE33 G8 budget — see setObjective above.
+      getObjective(opts) {
+        return localAgentGetObjective(this.storageHandle(), opts);
+      }
+      // biome-ignore format: SE33 G8 budget — see setObjective above.
+      updateObjectiveOptions(opts) {
+        return localAgentUpdateObjectiveOptions(this.storageHandle(), opts);
+      }
+      // biome-ignore format: SE33 G8 budget — see setObjective above.
+      clearObjective(opts) {
+        return localAgentClearObjective(this.storageHandle(), opts);
       }
       // biome-ignore format: G8 budget — see runUntil comment above.
       fork(options) {