@theokit/sdk 2.27.0 → 2.29.0

package/dist/index.js

@@ -2,8 +2,8 @@ import { z, toJSONSchema } from 'zod';
 import { createRequire } from 'module';
 import { createHash, randomUUID, randomBytes } from 'crypto';
 import { existsSync, rmSync, mkdirSync, renameSync, readFileSync, realpathSync, lstatSync, readlinkSync, readdirSync } from 'fs';
-import { join, dirname, relative, resolve, sep, isAbsolute } from 'path';
-import { readFile, stat, rm, readdir, mkdir, appendFile, rename, open, unlink, statfs, access, writeFile } from 'fs/promises';
+import { join, dirname, resolve, sep, relative, isAbsolute } from 'path';
+import { rm, readdir, readFile, mkdir, stat, appendFile, open, rename, unlink, statfs, access, writeFile } from 'fs/promises';
 import { AsyncLocalStorage } from 'async_hooks';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
@@ -913,7 +913,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;
@@ -1110,6 +1110,72 @@ var init_markdown_store = __esm({
   }
 });
 
+// src/internal/persistence/file-lock.ts
+async function getProperLockfile() {
+  if (cached !== void 0) return cached;
+  try {
+    const mod = await import('proper-lockfile');
+    if (!validateLockModule(mod)) {
+      if (!warnedStructural) {
+        warnedStructural = true;
+        process.stderr.write(
+          "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
+        );
+      }
+      cached = null;
+      return cached;
+    }
+    cached = mod;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+function validateLockModule(mod) {
+  if (mod === null || mod === void 0 || typeof mod !== "object") return false;
+  const m = mod;
+  return typeof m.lock === "function" && typeof m.unlock === "function";
+}
+async function withFileLock(path, fn, options) {
+  const lib = await getProperLockfile();
+  if (lib === null) {
+    if (!warnedMissing) {
+      warnedMissing = true;
+      process.stderr.write(
+        "[theokit-sdk] proper-lockfile not installed; cross-process file lock unavailable. Install with: pnpm add proper-lockfile\n"
+      );
+    }
+    return withCwdMutex(`file-lock:${path}`, fn);
+  }
+  return withCwdMutex(`file-lock:${path}`, async () => {
+    const release = await lib.lock(path, {
+      // EC-1: companion lockfile, target path may not exist yet.
+      lockfilePath: `${path}.lock`,
+      realpath: false,
+      stale: 3e4,
+      retries: {
+        retries: 5,
+        factor: 1.5,
+        minTimeout: 100,
+        maxTimeout: 5e3
+      }
+    });
+    try {
+      return await fn();
+    } finally {
+      await release();
+    }
+  });
+}
+var cached, warnedMissing, warnedStructural;
+var init_file_lock = __esm({
+  "src/internal/persistence/file-lock.ts"() {
+    init_cwd_mutex();
+    warnedMissing = false;
+    warnedStructural = false;
+  }
+});
+
 // src/internal/runtime/context/yaml-frontmatter.ts
 function parseSimpleYaml(text) {
   const fields = {};
@@ -1364,94 +1430,459 @@ var init_session_summary_writer = __esm({
     MAX_TURN_CHARS = 2e3;
   }
 });
-async function withToolWhitelist(whitelist, fn) {
-  return toolWhitelistStore.run(whitelist, fn);
-}
-function currentToolWhitelist() {
-  return toolWhitelistStore.getStore();
+function sessionFilePath(cwd, agentId) {
+  const safe2 = sanitizeIdentifier(agentId, { maxLen: 128 });
+  return safePathJoin(cwd, ".theokit", "agents", safe2, "messages.jsonl");
 }
-function checkToolWhitelist(toolName) {
-  const whitelist = currentToolWhitelist();
-  if (whitelist === void 0) return { allowed: true };
-  if (!whitelist.has(toolName)) {
-    return {
-      allowed: false,
-      reason: `Tool "${toolName}" not available in this fork context`
-    };
+async function readJsonlLines(cwd, agentId) {
+  const path = sessionFilePath(cwd, agentId);
+  try {
+    const raw = await readFile(path, "utf8");
+    return raw.split("\n").filter((line) => line.length > 0);
+  } catch {
+    return [];
   }
-  return { allowed: true };
 }
-var toolWhitelistStore;
-var init_async_local_storage = __esm({
-  "src/internal/runtime/concurrency/async-local-storage.ts"() {
-    toolWhitelistStore = new AsyncLocalStorage();
+function warnMalformed(agentId, line) {
+  process.stderr.write(
+    `[theokit-sdk] skipping malformed line in messages.jsonl (${agentId}): ${line.slice(0, 80)}...
+`
+  );
+}
+function hydrateSessionLine(parsed) {
+  if (typeof parsed.text !== "string" || parsed.role === void 0) return void 0;
+  if (parsed.role === "user" || parsed.role === "assistant") {
+    return { role: parsed.role, text: parsed.text };
   }
-});
-
-// src/internal/runtime/concurrency/async-semaphore.ts
-function createSemaphore(permits) {
-  if (!Number.isInteger(permits) || permits < 1) {
-    throw new ConfigurationError(
-      `async-semaphore: permits must be a positive integer, got ${permits}`,
-      { code: "invalid_concurrency" }
-    );
+  if (parsed.role === "tool_call" || parsed.role === "tool_result") {
+    const label = parsed.role === "tool_call" ? "tool call" : "tool result";
+    return { role: "assistant", text: `[${label}] ${parsed.text}` };
   }
-  let active = 0;
-  const queue = [];
-  function tryGrant() {
-    if (active < permits && queue.length > 0) {
-      const resolve3 = queue.shift();
-      if (resolve3 !== void 0) {
-        active += 1;
-        resolve3();
-      }
+  return void 0;
+}
+async function readSessionFile(cwd, agentId) {
+  const lines = await readJsonlLines(cwd, agentId);
+  const messages = [];
+  for (const line of lines) {
+    try {
+      const msg = hydrateSessionLine(JSON.parse(line));
+      if (msg !== void 0) messages.push(msg);
+    } catch {
+      warnMalformed(agentId, line);
     }
   }
-  return {
-    inFlight: () => active,
-    pending: () => queue.length + active,
-    async acquire() {
-      await new Promise((resolve3) => {
-        queue.push(resolve3);
-        tryGrant();
-      });
-      let released = false;
-      return () => {
-        if (released) return;
-        released = true;
-        active -= 1;
-        tryGrant();
-      };
+  return messages;
+}
+async function readAllPersistedMessages(cwd, agentId) {
+  const lines = await readJsonlLines(cwd, agentId);
+  const messages = [];
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.role !== void 0 && VALID_ROLES.has(parsed.role) && typeof parsed.text === "string") {
+        messages.push({
+          role: parsed.role,
+          text: parsed.text,
+          at: typeof parsed.at === "number" ? parsed.at : Date.now()
+        });
+      }
+    } catch {
+      warnMalformed(agentId, line);
     }
+  }
+  return messages;
+}
+async function appendAnyPersistedMessage(cwd, agentId, record) {
+  await appendPersistedMessages(cwd, agentId, [record]);
+}
+async function appendPersistedMessages(cwd, agentId, records) {
+  if (records.length === 0) return;
+  const path = sessionFilePath(cwd, agentId);
+  const payload = records.map((r) => `${redactSecrets(JSON.stringify(r))}
+`).join("");
+  const dir = dirname(path);
+  let written = false;
+  const attempt = async () => {
+    await mkdir(dir, { recursive: true });
+    await withFileLock(path, async () => {
+      await appendFile(path, payload, "utf8");
+      written = true;
+    });
   };
+  try {
+    await attempt();
+  } catch (cause) {
+    if (written || cause.code !== "ENOENT") throw cause;
+    await attempt();
+  }
 }
-var init_async_semaphore = __esm({
-  "src/internal/runtime/concurrency/async-semaphore.ts"() {
-    init_errors();
+async function rewriteLockedSession(path, transform) {
+  await withFileLock(path, async () => {
+    let raw;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch {
+      return;
+    }
+    const lines = raw.split("\n").filter((line) => line.length > 0);
+    const next = transform(lines);
+    if (next === void 0) return;
+    await replaceFileAtomic(path, next);
+  });
+}
+async function compactSessionFile(cwd, agentId, maxTurns) {
+  const path = sessionFilePath(cwd, agentId);
+  if (!existsSync(path)) return;
+  await rewriteLockedSession(
+    path,
+    (lines) => lines.length <= maxTurns * 2 ? void 0 : `${lines.slice(-maxTurns).join("\n")}
+`
+  );
+}
+async function truncateSessionTo(cwd, agentId, keepCount) {
+  const path = sessionFilePath(cwd, agentId);
+  if (!existsSync(path)) return 0;
+  let kept = 0;
+  await rewriteLockedSession(path, (lines) => {
+    const keep = Math.max(0, Math.min(keepCount, lines.length));
+    kept = keep;
+    if (keep === lines.length) return void 0;
+    return keep === 0 ? "" : `${lines.slice(0, keep).join("\n")}
+`;
+  });
+  return kept;
+}
+var VALID_ROLES;
+var init_agent_session_store = __esm({
+  "src/internal/runtime/session/agent-session-store.ts"() {
+    init_atomic_write();
+    init_file_lock();
+    init_security();
+    VALID_ROLES = /* @__PURE__ */ new Set([
+      "user",
+      "assistant",
+      "system",
+      "tool_call",
+      "tool_result"
+    ]);
   }
 });
 
-// src/internal/llm/credential-pool-types.ts
-var COOLDOWN_MS, DEFAULT_COOLDOWN_MS;
-var init_credential_pool_types = __esm({
-  "src/internal/llm/credential-pool-types.ts"() {
-    COOLDOWN_MS = {
-      401: 5 * 60 * 1e3,
-      // 5 minutes — OAuth refresh can recover quickly
-      402: 60 * 60 * 1e3,
-      // 1 hour — billing quota typically hourly+
-      429: 60 * 60 * 1e3
-      // 1 hour — daily-rate-limit windows
-    };
-    DEFAULT_COOLDOWN_MS = 60 * 60 * 1e3;
+// 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/llm/retry.ts
-function computeBackoffMs(opts) {
-  const base = opts.baseMs ?? DEFAULT_BASE_MS;
-  const cap2 = opts.capMs ?? DEFAULT_CAP_MS;
-  const rng = opts.rng ?? Math.random;
+// src/internal/persistence/pagination.ts
+function paginate(items, opts) {
+  if (opts === void 0 || opts.offset === void 0 && opts.limit === void 0) return items;
+  const start = Math.max(0, opts.offset ?? 0);
+  const end = opts.limit === void 0 ? items.length : start + Math.max(0, opts.limit);
+  return items.slice(start, end);
+}
+var init_pagination = __esm({
+  "src/internal/persistence/pagination.ts"() {
+  }
+});
+
+// src/internal/persistence/session-meta.ts
+function applyMetaPatch(current, patch) {
+  const next = {};
+  if (current.title !== void 0) next.title = current.title;
+  if (current.tag !== void 0) next.tag = current.tag;
+  if (patch.title === null) delete next.title;
+  else if (patch.title !== void 0) next.title = patch.title;
+  if (patch.tag === null) delete next.tag;
+  else if (patch.tag !== void 0) next.tag = patch.tag;
+  return next;
+}
+function coerceSessionMeta(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const obj = raw;
+  const meta = {};
+  if (typeof obj.title === "string") meta.title = obj.title;
+  if (typeof obj.tag === "string") meta.tag = obj.tag;
+  return meta.title === void 0 && meta.tag === void 0 ? void 0 : meta;
+}
+var init_session_meta = __esm({
+  "src/internal/persistence/session-meta.ts"() {
+  }
+});
+function toStoredMessage(record) {
+  return {
+    role: record.role,
+    content: record.text,
+    at: record.at
+  };
+}
+function toRecord(message) {
+  return { role: message.role, text: message.content, at: message.at ?? Date.now() };
+}
+var FileSystemConversationStorage;
+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 {
+      #root;
+      constructor(opts = {}) {
+        this.#root = opts.root ?? process.cwd();
+      }
+      /** Exposed for tests + diagnostics. The path is sanitized at use sites. */
+      get root() {
+        return this.#root;
+      }
+      async getMessages(conversationId, opts) {
+        const records = await readAllPersistedMessages(this.#root, conversationId);
+        const all = records.map(toStoredMessage);
+        return paginate(all, opts);
+      }
+      async appendMessage(conversationId, message) {
+        await appendAnyPersistedMessage(this.#root, conversationId, toRecord(message));
+      }
+      async appendMessages(conversationId, messages) {
+        await appendPersistedMessages(this.#root, conversationId, messages.map(toRecord));
+      }
+      async truncateConversation(conversationId, keepCount) {
+        return truncateSessionTo(this.#root, conversationId, keepCount);
+      }
+      async deleteConversation(conversationId) {
+        const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
+        const dirPath = safePathJoin(this.#root, ".theokit", "agents", safe2);
+        await rm(dirPath, { recursive: true, force: true });
+      }
+      async deleteScope(prefix) {
+        const ids = await this.listConversationIds();
+        const matching = ids.filter((id) => id.startsWith(prefix));
+        for (const id of matching) await this.deleteConversation(id);
+        return matching.length;
+      }
+      async listConversationIds(opts = {}) {
+        const agentsRoot = safePathJoin(this.#root, ".theokit", "agents");
+        let entries;
+        try {
+          entries = await readdir(agentsRoot);
+        } catch (cause) {
+          if (cause.code === "ENOENT") return [];
+          throw cause;
+        }
+        if (opts.limit !== void 0) return entries.slice(0, opts.limit);
+        return entries;
+      }
+      async compact(conversationId, maxTurns) {
+        await compactSessionFile(this.#root, conversationId, maxTurns);
+      }
+      // SE4 — session metadata persisted as a per-conversation sidecar
+      // `<root>/.theokit/agents/<safeId>/session.json` (same sanitized perimeter as
+      // the transcript). Kept separate from messages.jsonl so a title/tag write does
+      // not rewrite the append-only log.
+      #metaPath(conversationId) {
+        const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
+        return safePathJoin(this.#root, ".theokit", "agents", safe2, "session.json");
+      }
+      async getSessionMeta(conversationId) {
+        try {
+          const raw = await readFile(this.#metaPath(conversationId), "utf8");
+          return coerceSessionMeta(JSON.parse(raw));
+        } catch (cause) {
+          if (cause.code === "ENOENT") return void 0;
+          throw cause;
+        }
+      }
+      async setSessionMeta(conversationId, patch) {
+        const metaPath = this.#metaPath(conversationId);
+        await mkdir(dirname(metaPath), { recursive: true });
+        await withFileLock(metaPath, async () => {
+          let current = {};
+          try {
+            current = coerceSessionMeta(JSON.parse(await readFile(metaPath, "utf8"))) ?? {};
+          } catch (cause) {
+            if (cause.code !== "ENOENT") throw cause;
+          }
+          const next = applyMetaPatch(current, patch);
+          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() {
+      }
+    };
+  }
+});
+async function withToolWhitelist(whitelist, fn) {
+  return toolWhitelistStore.run(whitelist, fn);
+}
+function currentToolWhitelist() {
+  return toolWhitelistStore.getStore();
+}
+function checkToolWhitelist(toolName) {
+  const whitelist = currentToolWhitelist();
+  if (whitelist === void 0) return { allowed: true };
+  if (!whitelist.has(toolName)) {
+    return {
+      allowed: false,
+      reason: `Tool "${toolName}" not available in this fork context`
+    };
+  }
+  return { allowed: true };
+}
+var toolWhitelistStore;
+var init_async_local_storage = __esm({
+  "src/internal/runtime/concurrency/async-local-storage.ts"() {
+    toolWhitelistStore = new AsyncLocalStorage();
+  }
+});
+
+// src/internal/runtime/concurrency/async-semaphore.ts
+function createSemaphore(permits) {
+  if (!Number.isInteger(permits) || permits < 1) {
+    throw new ConfigurationError(
+      `async-semaphore: permits must be a positive integer, got ${permits}`,
+      { code: "invalid_concurrency" }
+    );
+  }
+  let active = 0;
+  const queue = [];
+  function tryGrant() {
+    if (active < permits && queue.length > 0) {
+      const resolve3 = queue.shift();
+      if (resolve3 !== void 0) {
+        active += 1;
+        resolve3();
+      }
+    }
+  }
+  return {
+    inFlight: () => active,
+    pending: () => queue.length + active,
+    async acquire() {
+      await new Promise((resolve3) => {
+        queue.push(resolve3);
+        tryGrant();
+      });
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        active -= 1;
+        tryGrant();
+      };
+    }
+  };
+}
+var init_async_semaphore = __esm({
+  "src/internal/runtime/concurrency/async-semaphore.ts"() {
+    init_errors();
+  }
+});
+
+// src/internal/llm/credential-pool-types.ts
+var COOLDOWN_MS, DEFAULT_COOLDOWN_MS;
+var init_credential_pool_types = __esm({
+  "src/internal/llm/credential-pool-types.ts"() {
+    COOLDOWN_MS = {
+      401: 5 * 60 * 1e3,
+      // 5 minutes — OAuth refresh can recover quickly
+      402: 60 * 60 * 1e3,
+      // 1 hour — billing quota typically hourly+
+      429: 60 * 60 * 1e3
+      // 1 hour — daily-rate-limit windows
+    };
+    DEFAULT_COOLDOWN_MS = 60 * 60 * 1e3;
+  }
+});
+
+// src/internal/llm/retry.ts
+function computeBackoffMs(opts) {
+  const base = opts.baseMs ?? DEFAULT_BASE_MS;
+  const cap2 = opts.capMs ?? DEFAULT_CAP_MS;
+  const rng = opts.rng ?? Math.random;
   if (opts.retryAfterMs !== void 0 && opts.retryAfterMs >= 0) {
     return Math.max(base, Math.min(cap2, opts.retryAfterMs));
   }
@@ -1737,6 +2168,151 @@ var init_credential_pool_context = __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/memory/embedding-cache.ts
 var LruEmbeddingCache, globalEmbeddingCache;
 var init_embedding_cache = __esm({
@@ -7920,68 +8496,7 @@ init_cwd_mutex();
 
 // src/internal/personality/store.ts
 init_atomic_write();
-
-// src/internal/persistence/file-lock.ts
-init_cwd_mutex();
-var cached;
-var warnedMissing = false;
-var warnedStructural = false;
-async function getProperLockfile() {
-  if (cached !== void 0) return cached;
-  try {
-    const mod = await import('proper-lockfile');
-    if (!validateLockModule(mod)) {
-      if (!warnedStructural) {
-        warnedStructural = true;
-        process.stderr.write(
-          "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
-        );
-      }
-      cached = null;
-      return cached;
-    }
-    cached = mod;
-  } catch {
-    cached = null;
-  }
-  return cached;
-}
-function validateLockModule(mod) {
-  if (mod === null || mod === void 0 || typeof mod !== "object") return false;
-  const m = mod;
-  return typeof m.lock === "function" && typeof m.unlock === "function";
-}
-async function withFileLock(path, fn, options) {
-  const lib = await getProperLockfile();
-  if (lib === null) {
-    if (!warnedMissing) {
-      warnedMissing = true;
-      process.stderr.write(
-        "[theokit-sdk] proper-lockfile not installed; cross-process file lock unavailable. Install with: pnpm add proper-lockfile\n"
-      );
-    }
-    return withCwdMutex(`file-lock:${path}`, fn);
-  }
-  return withCwdMutex(`file-lock:${path}`, async () => {
-    const release = await lib.lock(path, {
-      // EC-1: companion lockfile, target path may not exist yet.
-      lockfilePath: `${path}.lock`,
-      realpath: false,
-      stale: 3e4,
-      retries: {
-        retries: 5,
-        factor: 1.5,
-        minTimeout: 100,
-        maxTimeout: 5e3
-      }
-    });
-    try {
-      return await fn();
-    } finally {
-      await release();
-    }
-  });
-}
+init_file_lock();
 var THEOKIT_DIR_NAME = ".theokit";
 function getTheokitHome(cwd) {
   const override = process.env.THEOKIT_HOME?.trim();
@@ -8856,431 +9371,174 @@ function resolveChildEnv(options = {}) {
     if (value !== void 0 && inheritsUnderPolicy(name, policy)) base[name] = value;
   }
   for (const [name, value] of Object.entries(options.overrides ?? {})) {
-    base[name] = value;
-  }
-  return base;
-}
-
-// src/internal/runtime/lifecycle/spawn-collect.ts
-function spawnAndCollect(options) {
-  return new Promise((resolve3) => {
-    const timeoutMs = options.timeoutMs ?? 3e4;
-    const spawnOptions = {
-      cwd: options.cwd,
-      // #54 — scrub secret-like parent env by default; `options.env` still wins.
-      env: resolveChildEnv({ policy: options.envPolicy, overrides: options.env })
-    };
-    const child = spawn(options.command, options.args ?? [], spawnOptions);
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let settled = false;
-    const settle = (result) => {
-      if (settled) return;
-      settled = true;
-      resolve3(result);
-    };
-    const timer = setTimeout(() => {
-      timedOut = true;
-      try {
-        child.kill("SIGKILL");
-      } catch {
-      }
-      settle({ stdout, stderr, exitCode: null, timedOut: true });
-    }, timeoutMs);
-    child.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString("utf8");
-    });
-    child.on("error", (cause) => {
-      clearTimeout(timer);
-      settle({ stdout, stderr, exitCode: -1, timedOut, spawnError: cause });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      settle({ stdout, stderr, exitCode: code, timedOut });
-    });
-    if (options.stdin !== void 0 && child.stdin !== null) {
-      child.stdin.end(options.stdin);
-    }
-  });
-}
-
-// src/internal/runtime/hooks/hooks-executor.ts
-init_hooks_source();
-var HooksExecutor = class {
-  constructor(cwd) {
-    this.cwd = cwd;
-  }
-  cwd;
-  config = {};
-  async initialize(settingSourcesIncludeProject) {
-    if (!settingSourcesIncludeProject) {
-      this.config = {};
-      return;
-    }
-    this.config = await loadHookConfig(this.cwd);
-  }
-  /** Fire every hook registered for `event` and aggregate the decisions. */
-  async run(payload) {
-    const commands = this.commandsFor(payload.event, payload.tool);
-    if (commands.length === 0) return { decisions: [], blocked: false };
-    const decisions = [];
-    for (const command of commands) {
-      const decision = await this.executeOne(command, payload);
-      decisions.push(decision);
-      if (decision.decision === "deny") {
-        const result = {
-          decisions,
-          blocked: true
-        };
-        if (decision.reason !== void 0) result.reason = decision.reason;
-        return result;
-      }
-    }
-    return { decisions, blocked: false };
-  }
-  commandsFor(event, tool) {
-    const list2 = this.config.hooks?.[event] ?? [];
-    if (tool === void 0) return list2;
-    return list2.filter((entry) => {
-      if (entry.matcher === void 0) return true;
-      try {
-        return new RegExp(entry.matcher).test(tool);
-      } catch {
-        return entry.matcher === tool;
-      }
-    });
-  }
-  async executeOne(command, payload) {
-    const timeoutMs = command.timeoutMs ?? 3e4;
-    const result = await spawnAndCollect({
-      command: "sh",
-      args: ["-c", command.command],
-      cwd: this.cwd,
-      timeoutMs,
-      stdin: JSON.stringify(payload)
-    });
-    if (result.timedOut) {
-      return { decision: "deny", reason: `Hook timed out after ${timeoutMs}ms` };
-    }
-    if (result.spawnError !== void 0) {
-      return { decision: "deny", reason: `Hook spawn failed: ${result.spawnError.message}` };
-    }
-    if (result.exitCode !== 0) {
-      return {
-        decision: "deny",
-        reason: result.stderr.trim().length > 0 ? result.stderr.trim() : `Hook exited with code ${result.exitCode}`
-      };
-    }
-    return parseDecisionFromStdout(result.stdout);
-  }
-};
-function parseDecisionFromStdout(stdout) {
-  const trimmed = stdout.trim();
-  if (trimmed.length === 0) return { decision: "allow" };
-  try {
-    const parsed = JSON.parse(trimmed);
-    if (parsed.decision === "deny" || parsed.decision === "feedback") {
-      const result = { decision: parsed.decision };
-      if (parsed.reason !== void 0) result.reason = parsed.reason;
-      if (parsed.feedback !== void 0) result.feedback = parsed.feedback;
-      return result;
-    }
-    if (parsed.decision === "allow") return { decision: "allow" };
-  } catch {
-    return { decision: "feedback", feedback: trimmed };
-  }
-  return { decision: "allow" };
-}
-
-// src/internal/runtime/lifecycle/post-run-lifecycle.ts
-init_session_summary_writer();
-
-// src/internal/runtime/memory/memory-path-selector.ts
-var PORT_MEMORY_PATH_ENV_VAR = "THEOKIT_PORT_MEMORY_PATH";
-function shouldUsePortMemoryPath() {
-  const env = globalThis.process?.env;
-  if (env === void 0) return false;
-  const val = env[PORT_MEMORY_PATH_ENV_VAR];
-  return val === "1" || val === "true";
-}
-function resolveMemoryProviderForLoop(consumerSupplied, defaultAdapter, portPathEnabled) {
-  if (consumerSupplied !== void 0) return consumerSupplied;
-  if (portPathEnabled) return defaultAdapter;
-  return void 0;
-}
-function resolveMemoryToolsForLoop(legacyTools, portPathEnabled) {
-  if (portPathEnabled) return void 0;
-  return legacyTools;
-}
-function resolveActiveMemorySummaryForSend(legacySummary, portPathEnabled) {
-  if (portPathEnabled) return void 0;
-  return legacySummary;
-}
-
-// src/internal/runtime/session/agent-session-store.ts
-init_atomic_write();
-init_security();
-var VALID_ROLES = /* @__PURE__ */ new Set([
-  "user",
-  "assistant",
-  "system",
-  "tool_call",
-  "tool_result"
-]);
-function sessionFilePath(cwd, agentId) {
-  const safe2 = sanitizeIdentifier(agentId, { maxLen: 128 });
-  return safePathJoin(cwd, ".theokit", "agents", safe2, "messages.jsonl");
-}
-async function readJsonlLines(cwd, agentId) {
-  const path = sessionFilePath(cwd, agentId);
-  try {
-    const raw = await readFile(path, "utf8");
-    return raw.split("\n").filter((line) => line.length > 0);
-  } catch {
-    return [];
-  }
-}
-function warnMalformed(agentId, line) {
-  process.stderr.write(
-    `[theokit-sdk] skipping malformed line in messages.jsonl (${agentId}): ${line.slice(0, 80)}...
-`
-  );
-}
-function hydrateSessionLine(parsed) {
-  if (typeof parsed.text !== "string" || parsed.role === void 0) return void 0;
-  if (parsed.role === "user" || parsed.role === "assistant") {
-    return { role: parsed.role, text: parsed.text };
-  }
-  if (parsed.role === "tool_call" || parsed.role === "tool_result") {
-    const label = parsed.role === "tool_call" ? "tool call" : "tool result";
-    return { role: "assistant", text: `[${label}] ${parsed.text}` };
-  }
-  return void 0;
-}
-async function readSessionFile(cwd, agentId) {
-  const lines = await readJsonlLines(cwd, agentId);
-  const messages = [];
-  for (const line of lines) {
-    try {
-      const msg = hydrateSessionLine(JSON.parse(line));
-      if (msg !== void 0) messages.push(msg);
-    } catch {
-      warnMalformed(agentId, line);
-    }
-  }
-  return messages;
-}
-async function readAllPersistedMessages(cwd, agentId) {
-  const lines = await readJsonlLines(cwd, agentId);
-  const messages = [];
-  for (const line of lines) {
-    try {
-      const parsed = JSON.parse(line);
-      if (parsed.role !== void 0 && VALID_ROLES.has(parsed.role) && typeof parsed.text === "string") {
-        messages.push({
-          role: parsed.role,
-          text: parsed.text,
-          at: typeof parsed.at === "number" ? parsed.at : Date.now()
-        });
-      }
-    } catch {
-      warnMalformed(agentId, line);
-    }
-  }
-  return messages;
-}
-async function appendAnyPersistedMessage(cwd, agentId, record) {
-  await appendPersistedMessages(cwd, agentId, [record]);
-}
-async function appendPersistedMessages(cwd, agentId, records) {
-  if (records.length === 0) return;
-  const path = sessionFilePath(cwd, agentId);
-  const payload = records.map((r) => `${redactSecrets(JSON.stringify(r))}
-`).join("");
-  const dir = dirname(path);
-  let written = false;
-  const attempt = async () => {
-    await mkdir(dir, { recursive: true });
-    await withFileLock(path, async () => {
-      await appendFile(path, payload, "utf8");
-      written = true;
-    });
-  };
-  try {
-    await attempt();
-  } catch (cause) {
-    if (written || cause.code !== "ENOENT") throw cause;
-    await attempt();
-  }
-}
-async function rewriteLockedSession(path, transform) {
-  await withFileLock(path, async () => {
-    let raw;
-    try {
-      raw = await readFile(path, "utf8");
-    } catch {
-      return;
-    }
-    const lines = raw.split("\n").filter((line) => line.length > 0);
-    const next = transform(lines);
-    if (next === void 0) return;
-    await replaceFileAtomic(path, next);
-  });
-}
-async function compactSessionFile(cwd, agentId, maxTurns) {
-  const path = sessionFilePath(cwd, agentId);
-  if (!existsSync(path)) return;
-  await rewriteLockedSession(
-    path,
-    (lines) => lines.length <= maxTurns * 2 ? void 0 : `${lines.slice(-maxTurns).join("\n")}
-`
-  );
-}
-async function truncateSessionTo(cwd, agentId, keepCount) {
-  const path = sessionFilePath(cwd, agentId);
-  if (!existsSync(path)) return 0;
-  let kept = 0;
-  await rewriteLockedSession(path, (lines) => {
-    const keep = Math.max(0, Math.min(keepCount, lines.length));
-    kept = keep;
-    if (keep === lines.length) return void 0;
-    return keep === 0 ? "" : `${lines.slice(0, keep).join("\n")}
-`;
-  });
-  return kept;
-}
-
-// src/internal/persistence/conversation-storage-fs.ts
-init_security();
-
-// src/internal/persistence/pagination.ts
-function paginate(items, opts) {
-  if (opts === void 0 || opts.offset === void 0 && opts.limit === void 0) return items;
-  const start = Math.max(0, opts.offset ?? 0);
-  const end = opts.limit === void 0 ? items.length : start + Math.max(0, opts.limit);
-  return items.slice(start, end);
+    base[name] = value;
+  }
+  return base;
 }
 
-// src/internal/persistence/session-meta.ts
-function applyMetaPatch(current, patch) {
-  const next = {};
-  if (current.title !== void 0) next.title = current.title;
-  if (current.tag !== void 0) next.tag = current.tag;
-  if (patch.title === null) delete next.title;
-  else if (patch.title !== void 0) next.title = patch.title;
-  if (patch.tag === null) delete next.tag;
-  else if (patch.tag !== void 0) next.tag = patch.tag;
-  return next;
-}
-function coerceSessionMeta(raw) {
-  if (typeof raw !== "object" || raw === null) return void 0;
-  const obj = raw;
-  const meta = {};
-  if (typeof obj.title === "string") meta.title = obj.title;
-  if (typeof obj.tag === "string") meta.tag = obj.tag;
-  return meta.title === void 0 && meta.tag === void 0 ? void 0 : meta;
+// src/internal/runtime/lifecycle/spawn-collect.ts
+function spawnAndCollect(options) {
+  return new Promise((resolve3) => {
+    const timeoutMs = options.timeoutMs ?? 3e4;
+    const spawnOptions = {
+      cwd: options.cwd,
+      // #54 — scrub secret-like parent env by default; `options.env` still wins.
+      env: resolveChildEnv({ policy: options.envPolicy, overrides: options.env })
+    };
+    const child = spawn(options.command, options.args ?? [], spawnOptions);
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve3(result);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      settle({ stdout, stderr, exitCode: null, timedOut: true });
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      settle({ stdout, stderr, exitCode: -1, timedOut, spawnError: cause });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      settle({ stdout, stderr, exitCode: code, timedOut });
+    });
+    if (options.stdin !== void 0 && child.stdin !== null) {
+      child.stdin.end(options.stdin);
+    }
+  });
 }
 
-// src/internal/persistence/conversation-storage-fs.ts
-var FileSystemConversationStorage = class {
-  #root;
-  constructor(opts = {}) {
-    this.#root = opts.root ?? process.cwd();
-  }
-  /** Exposed for tests + diagnostics. The path is sanitized at use sites. */
-  get root() {
-    return this.#root;
-  }
-  async getMessages(conversationId, opts) {
-    const records = await readAllPersistedMessages(this.#root, conversationId);
-    const all = records.map(toStoredMessage);
-    return paginate(all, opts);
-  }
-  async appendMessage(conversationId, message) {
-    await appendAnyPersistedMessage(this.#root, conversationId, toRecord(message));
-  }
-  async appendMessages(conversationId, messages) {
-    await appendPersistedMessages(this.#root, conversationId, messages.map(toRecord));
-  }
-  async truncateConversation(conversationId, keepCount) {
-    return truncateSessionTo(this.#root, conversationId, keepCount);
-  }
-  async deleteConversation(conversationId) {
-    const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
-    const dirPath = safePathJoin(this.#root, ".theokit", "agents", safe2);
-    await rm(dirPath, { recursive: true, force: true });
+// src/internal/runtime/hooks/hooks-executor.ts
+init_hooks_source();
+var HooksExecutor = class {
+  constructor(cwd) {
+    this.cwd = cwd;
   }
-  async deleteScope(prefix) {
-    const ids = await this.listConversationIds();
-    const matching = ids.filter((id) => id.startsWith(prefix));
-    for (const id of matching) await this.deleteConversation(id);
-    return matching.length;
-  }
-  async listConversationIds(opts = {}) {
-    const agentsRoot = safePathJoin(this.#root, ".theokit", "agents");
-    let entries;
-    try {
-      entries = await readdir(agentsRoot);
-    } catch (cause) {
-      if (cause.code === "ENOENT") return [];
-      throw cause;
+  cwd;
+  config = {};
+  async initialize(settingSourcesIncludeProject) {
+    if (!settingSourcesIncludeProject) {
+      this.config = {};
+      return;
     }
-    if (opts.limit !== void 0) return entries.slice(0, opts.limit);
-    return entries;
-  }
-  async compact(conversationId, maxTurns) {
-    await compactSessionFile(this.#root, conversationId, maxTurns);
-  }
-  // SE4 — session metadata persisted as a per-conversation sidecar
-  // `<root>/.theokit/agents/<safeId>/session.json` (same sanitized perimeter as
-  // the transcript). Kept separate from messages.jsonl so a title/tag write does
-  // not rewrite the append-only log.
-  #metaPath(conversationId) {
-    const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
-    return safePathJoin(this.#root, ".theokit", "agents", safe2, "session.json");
+    this.config = await loadHookConfig(this.cwd);
   }
-  async getSessionMeta(conversationId) {
-    try {
-      const raw = await readFile(this.#metaPath(conversationId), "utf8");
-      return coerceSessionMeta(JSON.parse(raw));
-    } catch (cause) {
-      if (cause.code === "ENOENT") return void 0;
-      throw cause;
+  /** Fire every hook registered for `event` and aggregate the decisions. */
+  async run(payload) {
+    const commands = this.commandsFor(payload.event, payload.tool);
+    if (commands.length === 0) return { decisions: [], blocked: false };
+    const decisions = [];
+    for (const command of commands) {
+      const decision = await this.executeOne(command, payload);
+      decisions.push(decision);
+      if (decision.decision === "deny") {
+        const result = {
+          decisions,
+          blocked: true
+        };
+        if (decision.reason !== void 0) result.reason = decision.reason;
+        return result;
+      }
     }
+    return { decisions, blocked: false };
   }
-  async setSessionMeta(conversationId, patch) {
-    const metaPath = this.#metaPath(conversationId);
-    await mkdir(dirname(metaPath), { recursive: true });
-    await withFileLock(metaPath, async () => {
-      let current = {};
+  commandsFor(event, tool) {
+    const list2 = this.config.hooks?.[event] ?? [];
+    if (tool === void 0) return list2;
+    return list2.filter((entry) => {
+      if (entry.matcher === void 0) return true;
       try {
-        current = coerceSessionMeta(JSON.parse(await readFile(metaPath, "utf8"))) ?? {};
-      } catch (cause) {
-        if (cause.code !== "ENOENT") throw cause;
+        return new RegExp(entry.matcher).test(tool);
+      } catch {
+        return entry.matcher === tool;
       }
-      const next = applyMetaPatch(current, patch);
-      await writeFile(metaPath, redactSecrets(JSON.stringify(next)), "utf8");
     });
   }
-  async dispose() {
+  async executeOne(command, payload) {
+    const timeoutMs = command.timeoutMs ?? 3e4;
+    const result = await spawnAndCollect({
+      command: "sh",
+      args: ["-c", command.command],
+      cwd: this.cwd,
+      timeoutMs,
+      stdin: JSON.stringify(payload)
+    });
+    if (result.timedOut) {
+      return { decision: "deny", reason: `Hook timed out after ${timeoutMs}ms` };
+    }
+    if (result.spawnError !== void 0) {
+      return { decision: "deny", reason: `Hook spawn failed: ${result.spawnError.message}` };
+    }
+    if (result.exitCode !== 0) {
+      return {
+        decision: "deny",
+        reason: result.stderr.trim().length > 0 ? result.stderr.trim() : `Hook exited with code ${result.exitCode}`
+      };
+    }
+    return parseDecisionFromStdout(result.stdout);
   }
 };
-function toStoredMessage(record) {
-  return {
-    role: record.role,
-    content: record.text,
-    at: record.at
-  };
+function parseDecisionFromStdout(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return { decision: "allow" };
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed.decision === "deny" || parsed.decision === "feedback") {
+      const result = { decision: parsed.decision };
+      if (parsed.reason !== void 0) result.reason = parsed.reason;
+      if (parsed.feedback !== void 0) result.feedback = parsed.feedback;
+      return result;
+    }
+    if (parsed.decision === "allow") return { decision: "allow" };
+  } catch {
+    return { decision: "feedback", feedback: trimmed };
+  }
+  return { decision: "allow" };
 }
-function toRecord(message) {
-  return { role: message.role, text: message.content, at: message.at ?? Date.now() };
+
+// src/internal/runtime/lifecycle/post-run-lifecycle.ts
+init_session_summary_writer();
+
+// src/internal/runtime/memory/memory-path-selector.ts
+var PORT_MEMORY_PATH_ENV_VAR = "THEOKIT_PORT_MEMORY_PATH";
+function shouldUsePortMemoryPath() {
+  const env = globalThis.process?.env;
+  if (env === void 0) return false;
+  const val = env[PORT_MEMORY_PATH_ENV_VAR];
+  return val === "1" || val === "true";
+}
+function resolveMemoryProviderForLoop(consumerSupplied, defaultAdapter, portPathEnabled) {
+  if (consumerSupplied !== void 0) return consumerSupplied;
+  if (portPathEnabled) return defaultAdapter;
+  return void 0;
+}
+function resolveMemoryToolsForLoop(legacyTools, portPathEnabled) {
+  if (portPathEnabled) return void 0;
+  return legacyTools;
+}
+function resolveActiveMemorySummaryForSend(legacySummary, portPathEnabled) {
+  if (portPathEnabled) return void 0;
+  return legacySummary;
 }
 
 // src/internal/runtime/session/agent-session.ts
+init_conversation_storage_fs();
+init_agent_session_store();
 var DEFAULT_MAX_TURNS = 200;
 var COMPACTION_CHECK_INTERVAL = 50;
 var sessions = /* @__PURE__ */ new Map();
@@ -16357,6 +16615,9 @@ async function readProjectMcpServers(cwd) {
   }
 }
 
+// src/internal/runtime/local-agent/local-agent.ts
+init_local_agent_goal_extensions();
+
 // src/internal/runtime/local-agent/local-agent-invalidate.ts
 async function applyDeferredInvalidation(agentId, pending, refresh) {
   process.stderr.write(
@@ -17739,16 +18000,49 @@ async function localAgentUsePersonality(args) {
 init_local_agent_plugins();
 
 // 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();
 }
@@ -17814,6 +18108,44 @@ function ponyfillAny(signals) {
   return ctrl.signal;
 }
 
+// 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);
+    }
+  });
+}
+
 // src/internal/runtime/processors/run-processors.ts
 var ProcessorAbort = class {
   constructor(processorId, reason) {
@@ -17953,6 +18285,9 @@ function wrapRunWithOutputProcessors(args) {
   });
 }
 
+// src/internal/runtime/local-agent/local-agent-send.ts
+init_local_agent_goal_extensions();
+
 // src/internal/runtime/local-agent/local-agent-memory-hooks.ts
 var DEFAULT_MAX_RECALL_BYTES = 16e3;
 async function applyPreUserSendHook(args) {
@@ -18068,6 +18403,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])
@@ -18075,7 +18415,7 @@ async function executeSendLocked(inputs, message, options) {
   const run = await inputs.dispatchRun(
     adaptedMessage,
     composedOptions,
-    assembledSystemPrompt,
+    projectedSystemPrompt,
     memoryFacts,
     priorMessages,
     memoryTools,
@@ -18088,18 +18428,43 @@ 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);
+}
 
 // src/internal/runtime/local-agent/local-agent-task-wrap.ts
 init_registry();
@@ -18462,20 +18827,33 @@ var LocalAgent = class {
       ...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) {
@@ -20059,12 +20437,17 @@ var EventBus = class {
 
 // src/index.ts
 init_generate_object();
+init_conversation_storage_fs();
 
 // src/internal/persistence/conversation-storage-memory.ts
+init_pagination();
+init_session_meta();
 var InMemoryConversationStorage = class {
   #store = /* @__PURE__ */ new Map();
   // SE4 — session-level metadata (title/tag), kept beside the transcript.
   #meta = /* @__PURE__ */ new Map();
+  // SE33 — durable thread-scoped objective, kept beside the transcript.
+  #objectives = /* @__PURE__ */ new Map();
   async getMessages(conversationId, opts) {
     const existing = this.#store.get(conversationId);
     return existing === void 0 ? [] : paginate(existing.slice(), opts);
@@ -20094,18 +20477,21 @@ var InMemoryConversationStorage = class {
   async deleteConversation(conversationId) {
     this.#store.delete(conversationId);
     this.#meta.delete(conversationId);
+    this.#objectives.delete(conversationId);
   }
   async deleteScope(prefix) {
     let n = 0;
-    for (const id of [...this.#store.keys()]) {
-      if (id.startsWith(prefix)) {
-        this.#store.delete(id);
-        this.#meta.delete(id);
-        n += 1;
-      }
-    }
-    for (const id of [...this.#meta.keys()]) {
-      if (id.startsWith(prefix)) this.#meta.delete(id);
+    const ids = /* @__PURE__ */ new Set([
+      ...this.#store.keys(),
+      ...this.#meta.keys(),
+      ...this.#objectives.keys()
+    ]);
+    for (const id of ids) {
+      if (!id.startsWith(prefix)) continue;
+      this.#store.delete(id);
+      this.#meta.delete(id);
+      this.#objectives.delete(id);
+      n += 1;
     }
     return n;
   }
@@ -20122,9 +20508,27 @@ var InMemoryConversationStorage = class {
     const current = this.#meta.get(conversationId) ?? {};
     this.#meta.set(conversationId, applyMetaPatch(current, patch));
   }
+  async getObjectiveRecord(conversationId) {
+    const rec = this.#objectives.get(conversationId);
+    return rec === void 0 ? void 0 : { ...rec };
+  }
+  async setObjectiveRecord(conversationId, record) {
+    if (record === null) this.#objectives.delete(conversationId);
+    else this.#objectives.set(conversationId, { ...record });
+  }
+  // SE33 (HIGH-1 fix) — atomic in the single-threaded runtime: the get→mutate→set
+  // runs synchronously, so there is no interleaving window for a concurrent frame.
+  async updateObjectiveRecord(conversationId, mutate) {
+    const current = this.#objectives.get(conversationId);
+    const next = mutate(current === void 0 ? void 0 : { ...current });
+    if (next === void 0) return;
+    if (next === null) this.#objectives.delete(conversationId);
+    else this.#objectives.set(conversationId, { ...next });
+  }
   async dispose() {
     this.#store.clear();
     this.#meta.clear();
+    this.#objectives.clear();
   }
 };