@theokit/sdk 4.27.0 → 4.29.0

package/dist/persistence.js

@@ -1,11 +1,113 @@
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds } from './chunk-DUK5WMKJ.js';
+export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds } from './chunk-R6ZP6KNB.js';
 export { PersistenceSchema } from './chunk-CAH3G4IS.js';
-export { applyWalWithFallback, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from './chunk-77FOZCOT.js';
 export { withFileLock } from './chunk-HZQEDNF6.js';
+export { applyWalWithFallback, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from './chunk-77FOZCOT.js';
 export { withCwdMutex } from './chunk-2XLKLVVR.js';
 export { encodeProjectDir, transcriptPath } from './chunk-ZZWTY3RX.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from './chunk-S2BBRVQX.js';
-import './chunk-WLKFWQSJ.js';
+import { TheokitAgentError } from './chunk-WLKFWQSJ.js';
 import './chunk-JTFYYKDT.js';
+import { openSync, closeSync, rmSync, readFileSync, writeSync, statSync, readSync } from 'fs';
+
+var SessionBusyError = class extends TheokitAgentError {
+  constructor(sessionPath) {
+    super(
+      `another process is already writing this session: ${sessionPath}. Fork it to a new id instead of appending \u2014 two writers interleave lines into a sequence that parses but is not what either process wrote.`,
+      { code: "session_busy", isRetryable: false }
+    );
+    this.sessionPath = sessionPath;
+  }
+  sessionPath;
+  name = "SessionBusyError";
+};
+async function acquireSessionWriter(sessionPath) {
+  const lockPath = `${sessionPath}.lock`;
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx");
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new SessionBusyError(sessionPath);
+    }
+    throw err;
+  }
+  closeSync(fd);
+  let released = false;
+  return {
+    sessionPath,
+    release: async () => {
+      if (released) return;
+      released = true;
+      rmSync(lockPath, { force: true });
+    }
+  };
+}
+var LiveSessionError = class extends TheokitAgentError {
+  constructor(path) {
+    super(
+      `refusing to write over a live session transcript: ${path}. Fork to a new id instead \u2014 the live pointer, the most recent transcript and any active registry entry are never overwritten (audit-trail rotation, M60).`,
+      { code: "live_session_protected", isRetryable: false }
+    );
+    this.path = path;
+  }
+  path;
+  name = "LiveSessionError";
+};
+function forkTranscript(src, dst, options = {}) {
+  for (const live of options.liveSessionPaths ?? []) {
+    if (live === dst) throw new LiveSessionError(dst);
+  }
+  const lines = readFileSync(src, "utf8").split("\n").filter((l) => l.trim().length > 0);
+  const kept = options.beforeRecordIndex === void 0 ? lines : lines.slice(0, options.beforeRecordIndex);
+  const body = kept.length > 0 ? `${kept.join("\n")}
+` : "";
+  const fd = openSync(dst, "wx");
+  try {
+    writeSync(fd, body);
+  } finally {
+    closeSync(fd);
+  }
+}
+var TAIL_CHUNK = 64 * 1024;
+function lerCaudaBruta(path, want) {
+  const size = statSync(path).size;
+  const fd = openSync(path, "r");
+  let bytesRead = 0;
+  let tail = "";
+  let pos = size;
+  try {
+    while (pos > 0) {
+      const len = Math.min(TAIL_CHUNK, pos);
+      pos -= len;
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, pos);
+      bytesRead += len;
+      tail = buf.toString("utf8") + tail;
+      if (naoVazias(tail).length > want) break;
+    }
+  } finally {
+    closeSync(fd);
+  }
+  const linhas = naoVazias(tail);
+  return { linhas: pos > 0 ? linhas.slice(1) : linhas, bytesRead };
+}
+function naoVazias(texto) {
+  return texto.split("\n").filter((l) => l.trim().length > 0);
+}
+function readJsonlTail(path, options = {}) {
+  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;
+  const { linhas, bytesRead } = lerCaudaBruta(path, want);
+  let sel = linhas;
+  if (options.sinceMarker !== void 0) {
+    const marcador = options.sinceMarker;
+    const idx = sel.findLastIndex((l) => l.includes(marcador));
+    if (idx >= 0) sel = sel.slice(idx + 1);
+  }
+  if (Number.isFinite(want)) sel = sel.slice(-want);
+  const out = sel.map((l) => JSON.parse(l));
+  return options._stats === true ? Object.assign(out, { bytesRead }) : out;
+}
+
+export { LiveSessionError, SessionBusyError, acquireSessionWriter, forkTranscript, readJsonlTail };
 //# sourceMappingURL=persistence.js.map
 //# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"persistence.js"}
+{"version":3,"sources":["../src/internal/persistence/session-writer.ts","../src/internal/persistence/transcript-ops.ts"],"names":["openSync","closeSync"],"mappings":"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","file":"persistence.js","sourcesContent":["/**\n * M81 — single-writer lease for a session transcript.\n *\n * ## The problem\n *\n * Nothing stops two processes appending to the same JSONL transcript. The concrete case: `exec\n * resume --last` can write into the TUI's live session. Two interleaved appends to an append-only\n * file produce lines that are each individually valid and whose SEQUENCE is fiction — and nothing\n * reports it, because every line parses.\n *\n * ## Why an exclusive lockfile rather than `withFileLock`\n *\n * The plan's ADR D2 said to compose `withFileLock`, and that was the right instinct — do not build a\n * second lock mechanism. It turned out not to fit the SHAPE: `withFileLock(path, fn)` is\n * scope-based — it holds the lock for the duration of a callback. A session lease is **held across\n * turns**, for as long as the process owns the session, with an explicit `release()`. Wrapping the\n * whole session lifetime in a callback would invert control of the entire agent loop.\n *\n * So this uses the same underlying primitive `withFileLock` uses (an exclusive-create lockfile,\n * `wx`) with lease semantics on top. That keeps the mechanism single — the file-existence lock —\n * while giving it the lifetime the caller needs. The deviation from D2 is recorded here because the\n * plan's rationale (no second mechanism) still holds; only its shape assumption did not.\n *\n * ## Fail fast, never wait\n *\n * A second writer that WAITED would block `exec` behind a TUI session that can last hours. The typed\n * error lets the caller choose: fork to a new id, or give up with a real diagnosis.\n *\n * @internal\n */\n\nimport { closeSync, openSync, rmSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — another process already holds the writer lease for this session.\n *\n * Carries `sessionPath` because knowing WHICH session is busy is what lets the caller decide between\n * forking and waiting for the user to close the TUI (`rules/error-handling.md § 2` — context enough\n * to act on).\n */\nexport class SessionBusyError extends TheokitAgentError {\n  override readonly name = \"SessionBusyError\";\n\n  constructor(readonly sessionPath: string) {\n    super(\n      `another process is already writing this session: ${sessionPath}. ` +\n        \"Fork it to a new id instead of appending — two writers interleave lines into a sequence \" +\n        \"that parses but is not what either process wrote.\",\n      { code: \"session_busy\", isRetryable: false },\n    );\n  }\n}\n\n/** A held writer lease. `release()` is idempotent. */\nexport interface SessionWriterLease {\n  readonly sessionPath: string;\n  release(): Promise<void>;\n}\n\n/**\n * Take the exclusive writer lease for `sessionPath`, or reject with {@link SessionBusyError}.\n *\n * The lock is a sibling `.lock` file created with `wx` — the same file-existence primitive the\n * SDK's `withFileLock` builds on. Exclusivity comes from the filesystem, so it holds across\n * processes, not just across async tasks in one process.\n */\nexport async function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease> {\n  const lockPath = `${sessionPath}.lock`;\n  let fd: number;\n  try {\n    fd = openSync(lockPath, \"wx\");\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      throw new SessionBusyError(sessionPath);\n    }\n    throw err;\n  }\n  closeSync(fd);\n\n  let released = false;\n  return {\n    sessionPath,\n    release: async (): Promise<void> => {\n      if (released) return;\n      released = true;\n      rmSync(lockPath, { force: true });\n    },\n  };\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, openSync, readFileSync, readSync, statSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee.\n  const fd = openSync(dst, \"wx\");\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /** Stop once a line contains this marker (exclusive). */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Lê chunks de trás para frente até acumular linhas completas suficientes.\n *\n * Extraído de `readJsonlTail` porque o laço de leitura e a seleção de registros são duas\n * responsabilidades — e juntas passavam do teto de complexidade. A primeira linha do buffer pode\n * estar cortada ao meio quando a leitura parou antes do início do arquivo; por isso ela é descartada.\n */\nfunction lerCaudaBruta(path: string, want: number): { linhas: string[]; bytesRead: number } {\n  const size = statSync(path).size;\n  const fd = openSync(path, \"r\");\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (naoVazias(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const linhas = naoVazias(tail);\n  return { linhas: pos > 0 ? linhas.slice(1) : linhas, bytesRead };\n}\n\n/** Linhas com conteúdo, na ordem do arquivo. */\nfunction naoVazias(texto: string): string[] {\n  return texto.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { linhas, bytesRead } = lerCaudaBruta(path, want);\n\n  let sel = linhas;\n  if (options.sinceMarker !== undefined) {\n    const marcador = options.sinceMarker;\n    const idx = sel.findLastIndex((l) => l.includes(marcador));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}

package/dist/{run-until-K7IO7ZPQ.js → run-until-YZ2ODWOF.js}

@@ -59,6 +59,7 @@ async function* runUntilImpl(agent, goal, options, deps) {
     const judgeOpts = {};
     if (options?.judgeModel !== void 0) judgeOpts.judgeModel = options.judgeModel;
     if (options?.judgeApiKey !== void 0) judgeOpts.apiKey = options.judgeApiKey;
+    if (options?.agentModel !== void 0) judgeOpts.agentModel = options.agentModel;
     const judgeCtx = { goal, lastResponse };
     if (options?.subgoals !== void 0) judgeCtx.subgoals = options.subgoals;
     const judgment = await deps.judge(judgeCtx, judgeOpts);
@@ -173,5 +174,5 @@ ${lastResponse.slice(-1e3)}`
 }
 
 export { composeContinuation, runUntilImpl };
-//# sourceMappingURL=run-until-K7IO7ZPQ.js.map
-//# sourceMappingURL=run-until-K7IO7ZPQ.js.map
+//# sourceMappingURL=run-until-YZ2ODWOF.js.map
+//# sourceMappingURL=run-until-YZ2ODWOF.js.map

package/dist/run-until-YZ2ODWOF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/run-until.ts"],"names":[],"mappings":"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","file":"run-until-YZ2ODWOF.js","sourcesContent":["/**\n * Goal-driven Ralph loop (T3.2, ADRs D115-D121).\n *\n * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:\n * yields events as the loop progresses, returns the final result when\n * the goal completes, fails, or is paused. The auxiliary judge model is\n * injected via `deps.judge` so the generator stays free of the `Agent`\n * façade import.\n *\n * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.\n * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).\n *\n * @internal\n */\n\nimport type { SDKAgent } from \"../../../types/agent.js\";\nimport type {\n  GoalEvent,\n  GoalOptions,\n  GoalResult,\n  JudgeResult,\n} from \"../../../types/goal-events.js\";\nimport type { JudgeContext, JudgeOptions } from \"../../judge/judge-call.js\";\nimport { GOAL_CONTINUATION_MARKER } from \"./goal-marker.js\";\n\n/** DI contract: the judge is the only external touchpoint. */\nexport interface RunUntilDeps {\n  judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the goal-loop interleaves turn-start, send, judge, continuation, abort-check, and failure-bail — extracting helpers harms the linear narrative.\nexport async function* runUntilImpl(\n  agent: SDKAgent,\n  goal: string,\n  options: GoalOptions | undefined,\n  deps: RunUntilDeps,\n): AsyncGenerator<GoalEvent, GoalResult, void> {\n  const maxTurns = options?.maxTurns ?? 20;\n  const maxFails = options?.maxConsecutiveJudgeFailures ?? 3;\n  const tokenBudget = options?.tokenBudget; // M55 — undefined ⇒ ilimitado\n  const signal = options?.signal;\n  // Use a function (not direct property access) so TS does not narrow\n  // `signal.aborted` to `false | undefined` after the initial check.\n  // AbortSignal.aborted is a getter that can flip true between calls.\n  // biome-ignore lint/complexity/useOptionalChain: optional-chain would re-narrow signal?.aborted to `false | undefined` after the first check, defeating the purpose of this helper.\n  const isAborted = (): boolean => signal !== undefined && signal.aborted;\n  let turn = 0;\n  let consecutiveFailures = 0;\n  let tokensUsed = 0; // M55 — soma observada (0 se usage ausente — fail-open)\n  let lastResponse = \"\";\n\n  // EC-C: signal already aborted BEFORE first event → emit only [paused].\n  if (isAborted()) {\n    yield {\n      type: \"status_change\",\n      status: \"paused\",\n      reason: \"aborted via AbortSignal before first turn\",\n    };\n    return { status: \"paused\", turnsUsed: 0, tokensUsed, finalResponse: undefined };\n  }\n\n  yield { type: \"status_change\", status: \"active\", reason: \"Goal started\" };\n\n  while (turn < maxTurns) {\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    turn += 1;\n    yield { type: \"turn_start\", turn, goal };\n\n    const continuationPrompt = turn === 1 ? goal : composeContinuation(goal, lastResponse);\n\n    const run = await agent.send(continuationPrompt);\n    // M55 review HIGH — thread the abort INTO the in-flight run: without this, Esc mid-turn is\n    // cosmetic (the turn keeps mutating the workspace until it finishes on its own). `run.cancel()`\n    // aborts the stream + in-flight tool calls (types/run.ts contract).\n    const cancelOnAbort = (): void => {\n      void (run as { cancel?: () => Promise<void> }).cancel?.();\n    };\n    if (signal !== undefined) {\n      if (signal.aborted) cancelOnAbort();\n      else signal.addEventListener(\"abort\", cancelOnAbort, { once: true });\n    }\n    const result = await run.wait();\n    if (signal !== undefined) signal.removeEventListener(\"abort\", cancelOnAbort);\n    lastResponse = result.result ?? \"\";\n    // M55 — token accounting fail-open: só soma quando o run reporta usage.\n    const turnTokens = (result as { usage?: { totalTokens?: number } }).usage?.totalTokens;\n    if (typeof turnTokens === \"number\") tokensUsed += turnTokens;\n    // Re-check aborted right after the turn lands: a cancelled turn must NOT spend a judge call.\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    yield { type: \"agent_response\", turn, content: lastResponse };\n\n    const judgeOpts: JudgeOptions = {};\n    if (options?.judgeModel !== undefined) judgeOpts.judgeModel = options.judgeModel;\n    if (options?.judgeApiKey !== undefined) judgeOpts.apiKey = options.judgeApiKey;\n    // M80 — encaminha o modelo do agente conduzido para o judge derivar quando `judgeModel` é omitido.\n    if (options?.agentModel !== undefined) judgeOpts.agentModel = options.agentModel;\n    const judgeCtx: JudgeContext = { goal, lastResponse };\n    if (options?.subgoals !== undefined) judgeCtx.subgoals = options.subgoals;\n    const judgment = await deps.judge(judgeCtx, judgeOpts);\n    yield {\n      type: \"judge_verdict\",\n      turn,\n      verdict: judgment.verdict,\n      reason: judgment.reason,\n      parseFailed: judgment.parseFailed,\n    };\n\n    if (judgment.parseFailed) {\n      consecutiveFailures += 1;\n      if (consecutiveFailures >= maxFails) {\n        yield {\n          type: \"status_change\",\n          status: \"failed\",\n          reason: `judge model too unreliable (${consecutiveFailures} parse failures in a row)`,\n        };\n        return {\n          status: \"failed\",\n          turnsUsed: turn,\n          tokensUsed,\n          finalResponse: lastResponse || undefined,\n        };\n      }\n    } else {\n      consecutiveFailures = 0;\n    }\n\n    if (judgment.verdict === \"done\") {\n      yield { type: \"status_change\", status: \"completed\", reason: judgment.reason };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    // M80 — o braço que faltava. Sem ele, um judge que reconhecesse impossibilidade só podia dizer\n    // \"continue\", e o loop repetia o mesmo turno até estourar o orçamento — reportando `failed` por\n    // limite em vez de `blocked` por impossibilidade. Duas causas distintas com o mesmo desfecho\n    // visível, e o consumidor precisava reconciliar depois do loop para distingui-las.\n    if (judgment.verdict === \"blocked\") {\n      yield { type: \"status_change\", status: \"blocked\", reason: judgment.reason };\n      return {\n        status: \"blocked\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    if (judgment.verdict === \"skipped\") {\n      yield {\n        type: \"status_change\",\n        status: \"completed\",\n        reason: `skipped: ${judgment.reason}`,\n      };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    // M55 — checagem de token budget APÓS o turno (Codex: wind-down suave, para o loop).\n    if (tokenBudget !== undefined && tokensUsed >= tokenBudget) {\n      yield {\n        type: \"status_change\",\n        status: \"budget_limited\",\n        reason: `token budget (${tokenBudget}) reached: ${tokensUsed} used`,\n      };\n      return {\n        status: \"budget_limited\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    yield { type: \"continuation\", turn, prompt: continuationPrompt };\n  }\n\n  yield {\n    type: \"status_change\",\n    status: \"failed\",\n    reason: `max turns (${maxTurns}) exhausted`,\n  };\n  return {\n    status: \"failed\",\n    turnsUsed: turn,\n    tokensUsed,\n    finalResponse: lastResponse || undefined,\n  };\n}\n\n/**\n * Build the continuation user message for turns 2+. Keeps last response\n * preview short so we don't bloat the prompt cache.\n *\n * @internal\n */\n\nexport function composeContinuation(goal: string, lastResponse: string): string {\n  // M55 — Codex-faithful continuation (ext/goal templates/goals/continuation.md): keep the FULL\n  // objective intact, work from current-state evidence, and audit completion requirement-by-requirement\n  // before declaring done. Improves the quality of what the judge then evaluates.\n  return [\n    GOAL_CONTINUATION_MARKER,\n    \"Continue working toward the active goal.\",\n    \"\",\n    `<objective>\\n${goal}\\n</objective>`,\n    \"\",\n    \"Continuation behavior:\",\n    \"- This goal persists across turns. Keep the full objective intact; if it cannot be finished now,\",\n    \"  make concrete progress toward the real requested end state and do not redefine success around a\",\n    \"  smaller or easier task.\",\n    \"\",\n    \"Work from evidence:\",\n    \"- Use the current worktree and external state as authoritative. Inspect the current state before\",\n    \"  relying on it. Improve, replace, or remove existing work as needed to satisfy the actual objective.\",\n    \"\",\n    \"Completion audit:\",\n    \"- Before deciding the goal is achieved, treat completion as unproven and verify it against the actual\",\n    \"  current state, requirement by requirement. Treat uncertain or indirect evidence as not achieved.\",\n    \"\",\n    `Your last response was:\\n${lastResponse.slice(-1000)}`,\n  ].join(\"\\n\");\n}\n"]}

package/dist/{run-until-ZD4PRLNJ.cjs → run-until-ZZ2JLPJM.cjs}

@@ -61,6 +61,7 @@ async function* runUntilImpl(agent, goal, options, deps) {
     const judgeOpts = {};
     if (options?.judgeModel !== void 0) judgeOpts.judgeModel = options.judgeModel;
     if (options?.judgeApiKey !== void 0) judgeOpts.apiKey = options.judgeApiKey;
+    if (options?.agentModel !== void 0) judgeOpts.agentModel = options.agentModel;
     const judgeCtx = { goal, lastResponse };
     if (options?.subgoals !== void 0) judgeCtx.subgoals = options.subgoals;
     const judgment = await deps.judge(judgeCtx, judgeOpts);
@@ -176,5 +177,5 @@ ${lastResponse.slice(-1e3)}`
 
 exports.composeContinuation = composeContinuation;
 exports.runUntilImpl = runUntilImpl;
-//# sourceMappingURL=run-until-ZD4PRLNJ.cjs.map
-//# sourceMappingURL=run-until-ZD4PRLNJ.cjs.map
+//# sourceMappingURL=run-until-ZZ2JLPJM.cjs.map
+//# sourceMappingURL=run-until-ZZ2JLPJM.cjs.map

package/dist/run-until-ZZ2JLPJM.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/run-until.ts"],"names":["GOAL_CONTINUATION_MARKER"],"mappings":"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","file":"run-until-ZZ2JLPJM.cjs","sourcesContent":["/**\n * Goal-driven Ralph loop (T3.2, ADRs D115-D121).\n *\n * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:\n * yields events as the loop progresses, returns the final result when\n * the goal completes, fails, or is paused. The auxiliary judge model is\n * injected via `deps.judge` so the generator stays free of the `Agent`\n * façade import.\n *\n * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.\n * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).\n *\n * @internal\n */\n\nimport type { SDKAgent } from \"../../../types/agent.js\";\nimport type {\n  GoalEvent,\n  GoalOptions,\n  GoalResult,\n  JudgeResult,\n} from \"../../../types/goal-events.js\";\nimport type { JudgeContext, JudgeOptions } from \"../../judge/judge-call.js\";\nimport { GOAL_CONTINUATION_MARKER } from \"./goal-marker.js\";\n\n/** DI contract: the judge is the only external touchpoint. */\nexport interface RunUntilDeps {\n  judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the goal-loop interleaves turn-start, send, judge, continuation, abort-check, and failure-bail — extracting helpers harms the linear narrative.\nexport async function* runUntilImpl(\n  agent: SDKAgent,\n  goal: string,\n  options: GoalOptions | undefined,\n  deps: RunUntilDeps,\n): AsyncGenerator<GoalEvent, GoalResult, void> {\n  const maxTurns = options?.maxTurns ?? 20;\n  const maxFails = options?.maxConsecutiveJudgeFailures ?? 3;\n  const tokenBudget = options?.tokenBudget; // M55 — undefined ⇒ ilimitado\n  const signal = options?.signal;\n  // Use a function (not direct property access) so TS does not narrow\n  // `signal.aborted` to `false | undefined` after the initial check.\n  // AbortSignal.aborted is a getter that can flip true between calls.\n  // biome-ignore lint/complexity/useOptionalChain: optional-chain would re-narrow signal?.aborted to `false | undefined` after the first check, defeating the purpose of this helper.\n  const isAborted = (): boolean => signal !== undefined && signal.aborted;\n  let turn = 0;\n  let consecutiveFailures = 0;\n  let tokensUsed = 0; // M55 — soma observada (0 se usage ausente — fail-open)\n  let lastResponse = \"\";\n\n  // EC-C: signal already aborted BEFORE first event → emit only [paused].\n  if (isAborted()) {\n    yield {\n      type: \"status_change\",\n      status: \"paused\",\n      reason: \"aborted via AbortSignal before first turn\",\n    };\n    return { status: \"paused\", turnsUsed: 0, tokensUsed, finalResponse: undefined };\n  }\n\n  yield { type: \"status_change\", status: \"active\", reason: \"Goal started\" };\n\n  while (turn < maxTurns) {\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    turn += 1;\n    yield { type: \"turn_start\", turn, goal };\n\n    const continuationPrompt = turn === 1 ? goal : composeContinuation(goal, lastResponse);\n\n    const run = await agent.send(continuationPrompt);\n    // M55 review HIGH — thread the abort INTO the in-flight run: without this, Esc mid-turn is\n    // cosmetic (the turn keeps mutating the workspace until it finishes on its own). `run.cancel()`\n    // aborts the stream + in-flight tool calls (types/run.ts contract).\n    const cancelOnAbort = (): void => {\n      void (run as { cancel?: () => Promise<void> }).cancel?.();\n    };\n    if (signal !== undefined) {\n      if (signal.aborted) cancelOnAbort();\n      else signal.addEventListener(\"abort\", cancelOnAbort, { once: true });\n    }\n    const result = await run.wait();\n    if (signal !== undefined) signal.removeEventListener(\"abort\", cancelOnAbort);\n    lastResponse = result.result ?? \"\";\n    // M55 — token accounting fail-open: só soma quando o run reporta usage.\n    const turnTokens = (result as { usage?: { totalTokens?: number } }).usage?.totalTokens;\n    if (typeof turnTokens === \"number\") tokensUsed += turnTokens;\n    // Re-check aborted right after the turn lands: a cancelled turn must NOT spend a judge call.\n    if (isAborted()) {\n      yield { type: \"status_change\", status: \"paused\", reason: \"aborted via AbortSignal\" };\n      return {\n        status: \"paused\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    yield { type: \"agent_response\", turn, content: lastResponse };\n\n    const judgeOpts: JudgeOptions = {};\n    if (options?.judgeModel !== undefined) judgeOpts.judgeModel = options.judgeModel;\n    if (options?.judgeApiKey !== undefined) judgeOpts.apiKey = options.judgeApiKey;\n    // M80 — encaminha o modelo do agente conduzido para o judge derivar quando `judgeModel` é omitido.\n    if (options?.agentModel !== undefined) judgeOpts.agentModel = options.agentModel;\n    const judgeCtx: JudgeContext = { goal, lastResponse };\n    if (options?.subgoals !== undefined) judgeCtx.subgoals = options.subgoals;\n    const judgment = await deps.judge(judgeCtx, judgeOpts);\n    yield {\n      type: \"judge_verdict\",\n      turn,\n      verdict: judgment.verdict,\n      reason: judgment.reason,\n      parseFailed: judgment.parseFailed,\n    };\n\n    if (judgment.parseFailed) {\n      consecutiveFailures += 1;\n      if (consecutiveFailures >= maxFails) {\n        yield {\n          type: \"status_change\",\n          status: \"failed\",\n          reason: `judge model too unreliable (${consecutiveFailures} parse failures in a row)`,\n        };\n        return {\n          status: \"failed\",\n          turnsUsed: turn,\n          tokensUsed,\n          finalResponse: lastResponse || undefined,\n        };\n      }\n    } else {\n      consecutiveFailures = 0;\n    }\n\n    if (judgment.verdict === \"done\") {\n      yield { type: \"status_change\", status: \"completed\", reason: judgment.reason };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    // M80 — o braço que faltava. Sem ele, um judge que reconhecesse impossibilidade só podia dizer\n    // \"continue\", e o loop repetia o mesmo turno até estourar o orçamento — reportando `failed` por\n    // limite em vez de `blocked` por impossibilidade. Duas causas distintas com o mesmo desfecho\n    // visível, e o consumidor precisava reconciliar depois do loop para distingui-las.\n    if (judgment.verdict === \"blocked\") {\n      yield { type: \"status_change\", status: \"blocked\", reason: judgment.reason };\n      return {\n        status: \"blocked\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n    if (judgment.verdict === \"skipped\") {\n      yield {\n        type: \"status_change\",\n        status: \"completed\",\n        reason: `skipped: ${judgment.reason}`,\n      };\n      return {\n        status: \"completed\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    // M55 — checagem de token budget APÓS o turno (Codex: wind-down suave, para o loop).\n    if (tokenBudget !== undefined && tokensUsed >= tokenBudget) {\n      yield {\n        type: \"status_change\",\n        status: \"budget_limited\",\n        reason: `token budget (${tokenBudget}) reached: ${tokensUsed} used`,\n      };\n      return {\n        status: \"budget_limited\",\n        turnsUsed: turn,\n        tokensUsed,\n        finalResponse: lastResponse || undefined,\n      };\n    }\n\n    yield { type: \"continuation\", turn, prompt: continuationPrompt };\n  }\n\n  yield {\n    type: \"status_change\",\n    status: \"failed\",\n    reason: `max turns (${maxTurns}) exhausted`,\n  };\n  return {\n    status: \"failed\",\n    turnsUsed: turn,\n    tokensUsed,\n    finalResponse: lastResponse || undefined,\n  };\n}\n\n/**\n * Build the continuation user message for turns 2+. Keeps last response\n * preview short so we don't bloat the prompt cache.\n *\n * @internal\n */\n\nexport function composeContinuation(goal: string, lastResponse: string): string {\n  // M55 — Codex-faithful continuation (ext/goal templates/goals/continuation.md): keep the FULL\n  // objective intact, work from current-state evidence, and audit completion requirement-by-requirement\n  // before declaring done. Improves the quality of what the judge then evaluates.\n  return [\n    GOAL_CONTINUATION_MARKER,\n    \"Continue working toward the active goal.\",\n    \"\",\n    `<objective>\\n${goal}\\n</objective>`,\n    \"\",\n    \"Continuation behavior:\",\n    \"- This goal persists across turns. Keep the full objective intact; if it cannot be finished now,\",\n    \"  make concrete progress toward the real requested end state and do not redefine success around a\",\n    \"  smaller or easier task.\",\n    \"\",\n    \"Work from evidence:\",\n    \"- Use the current worktree and external state as authoritative. Inspect the current state before\",\n    \"  relying on it. Improve, replace, or remove existing work as needed to satisfy the actual objective.\",\n    \"\",\n    \"Completion audit:\",\n    \"- Before deciding the goal is achieved, treat completion as unproven and verify it against the actual\",\n    \"  current state, requirement by requirement. Treat uncertain or indirect evidence as not achieved.\",\n    \"\",\n    `Your last response was:\\n${lastResponse.slice(-1000)}`,\n  ].join(\"\\n\");\n}\n"]}

package/dist/server/auth/index.d.cts

@@ -1,15 +1,211 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
 /**
- * @theokit/sdk/server/auth — public barrel
+ * @theokit/sdk/server/auth — typed error classes
  *
- * Per ADR D6 (sub-path export) — consumers import via `@theokit/sdk/server/auth`
- * NOT main `@theokit/sdk` barrel. Tree-shaking + allows breaking changes in
- * auth surface without affecting Agent runtime consumers.
+ * Plan T1.2 + v1.1 EC-1 (AuthCancelledError for OAuth provider error response RFC 6749 §4.1.2.1).
+ */
+/**
+ * Thrown at `defineAuth()` time when configuration is invalid
+ * (e.g., duplicate provider name, invalid email shape per EC-V1-12).
+ */
+declare class AuthConfigError extends Error {
+    readonly name = "AuthConfigError";
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
+ * when the named provider is not registered in `providers[]`.
+ */
+declare class AuthProviderNotFoundError extends Error {
+    readonly name = "AuthProviderNotFoundError";
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/**
+ * Thrown during OAuth callback handling for state mismatches, expired
+ * transactions, missing query params, or provider 4xx/5xx errors.
+ *
+ * Typed `code` field lets consumers branch on cause:
+ *   - 'oauth_transaction_expired' — cookie tx > 10min old (per ADR D5)
+ *   - 'oauth_state_mismatch' — query state ≠ cookie state (CSRF defense per RFC 6749 §10.12)
+ *   - 'oauth_provider_error' — non-access_denied error in callback URL
+ *   - 'oauth_token_exchange_failed' — provider rejected code-for-tokens swap
+ *   - 'oauth_userinfo_failed' — userinfo endpoint returned error
+ *   - 'oauth_missing_code_or_state' — required query params absent
+ */
+declare class AuthCallbackError extends Error {
+    readonly name: string;
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/**
+ * Per v1.1 EC-1 MUST FIX — typed subclass of AuthCallbackError for the
+ * specific case where user declined consent at provider screen.
+ *
+ * OAuth 2.0 RFC 6749 §4.1.2.1: provider redirects with `?error=access_denied`.
+ * Apps can catch this distinctly from network/server errors to render
+ * "Login cancelled — try again" UX instead of opaque "callback failed".
+ */
+declare class AuthCancelledError extends AuthCallbackError {
+    readonly name: string;
+    readonly errorDescription?: string;
+    constructor(errorDescription?: string);
+}
+
+/**
+ * @theokit/sdk/server/auth — orchestrator types (Caminho C Hybrid per G11)
+ *
+ * Plan: g11-auth-architecture-implementation v1.4 (sha256 4d381020...)
+ * Blueprint: g11-auth-architecture-decision v1.1 (SHIPPABLE 97.9)
+ * AUTH-DELEGATION lock (theokit/CLAUDE.md:217-225) — these types are the
+ * orchestrator contract; concrete OAuth/email providers ship in opt-in
+ * @theokit/auth-* packages (adapters layer per ADR D11).
+ */
+
+/**
+ * SessionManager contract (matches theokit/packages/theo/src/server/auth/session.ts:49).
+ * Imported as type-only — runtime depends via peerDep `theokit@>=0.2.4`.
+ */
+interface SessionManager<TSession> {
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+    createSession(res: ServerResponse, data: TSession): Promise<void>;
+    destroySession(res: ServerResponse): void;
+    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+}
+/**
+ * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
+ * (cookie-state pattern). Expires within 10 minutes per invariant.
+ */
+interface OAuthTransaction {
+    state: string;
+    pkceVerifier?: string;
+    returnTo?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Per ADR D9 — provider profile types are provider-specific (not unified).
+ * Each @theokit/auth-* package exports its own profile shape.
+ * Generic param TProfile lets consumers narrow via discriminated unions on providerName.
+ */
+interface AuthResult<TProfile, TName extends string = string> {
+    profile: TProfile;
+    providerName: TName;
+    rawTokens?: {
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Provider contract — each @theokit/auth-* package implements this.
+ * Per blueprint Q5 + ADR D11 (adapters layer).
+ */
+interface AuthProvider<TProfile, TName extends string = string> {
+    name: TName;
+    createAuthorizationURL(tx: OAuthTransaction): URL | Promise<URL>;
+    handleCallback(req: IncomingMessage, tx: OAuthTransaction): Promise<AuthResult<TProfile, TName>>;
+}
+/**
+ * `defineAuth(opts)` configuration shape — Caminho C (Hybrid).
+ * `providers` optional: empty = Caminho A escape hatch (manual signIn only).
+ * `onSignIn` invoked after provider callback success; returns TSession to persist.
+ */
+interface DefineAuthOptions<TSession> {
+    session: SessionManager<TSession>;
+    providers?: AuthProvider<unknown, string>[];
+    onSignIn?: <TProfile>(args: {
+        profile: TProfile;
+        provider: string;
+    }) => Promise<TSession>;
+    onSignOut?: (session: TSession | null) => Promise<void> | void;
+}
+/**
+ * Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.
+ *
+ * - startSignIn: returns Response.redirect to provider authorization URL with state cookie
+ * - finishSignIn: handles provider callback; verifies state; calls onSignIn; rotates session ID
+ *   (OWASP A07:2021 per EC-10); creates session cookie; clears transaction cookie
+ * - signIn: Caminho A escape hatch — skip OAuth flow; directly persist session from external profile
+ * - signOut: destroys session cookie + invokes onSignOut callback
+ * - getSession: read-only passthrough to session.getSession
+ */
+interface AuthOrchestrator<TSession> {
+    startSignIn(providerName: string, req: IncomingMessage, opts?: {
+        returnTo?: string;
+    }): Promise<Response>;
+    finishSignIn(providerName: string, req: IncomingMessage, res: ServerResponse): Promise<{
+        session: TSession;
+        returnTo?: string;
+    }>;
+    signIn<TProfile>(profile: TProfile, providerName: string, req: IncomingMessage, res: ServerResponse): Promise<TSession>;
+    signOut(res: ServerResponse): void | Promise<void>;
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+}
+
+/**
+ * @theokit/sdk/server/auth — encrypted OAuth transaction cookie store
+ *
+ * Per ADR D5 — cookie-state pattern (no Redis/db dependency in core).
+ *
+ * Stores OAuthTransaction (state + pkceVerifier + returnTo + expiry) in a
+ * single signed+encrypted HttpOnly cookie. Stateless, works in edge/serverless.
+ *
+ * Cookie name: `__Host-theo_oauth_tx` (T5.3 — RFC 6265bis prefix)
+ * Lifetime: 10 minutes (per D5 invariant)
+ * Encryption: AES-256-GCM via Node's webcrypto subtle API
+ *
+ * Note: this is a minimal in-package implementation. Production deployments
+ * may prefer using `theokit/server/auth/crypto`'s encrypt/decrypt helpers
+ * via the SessionManager's existing secret rotation chain. For T1.2 we keep
+ * it self-contained to avoid cross-package peer-dep complexity; T2+ may
+ * refactor to share SessionManager's encrypt path.
+ */
+
+/**
+ * T5.1 — Typed error thrown when an OAuth tx-cookie secret has < 32
+ * bytes of entropy. Surfaces the actual byte length so operators can
+ * diagnose mis-configured env vars without leaking the secret itself.
+ *
+ * @public
+ */
+declare class AuthSecretTooShortError extends Error {
+    readonly name = "AuthSecretTooShortError";
+    constructor(actualBytes: number);
+}
+
+/**
+ * @theokit/sdk/server/auth — defineAuth orchestrator runtime (Caminho C Hybrid)
+ *
+ * Plan T1.2 implementation per blueprint Q5 § Caminho C signatures.
+ * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
+ */
+
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+declare class Auth {
+    private constructor();
+    static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;
+}
+
+/**
+ * @theokit/sdk/server/auth — same-origin returnTo validator
+ *
+ * Per v1.1 EC-2 MUST FIX — OWASP A01:2021 open-redirect mitigation.
+ *
+ * Without this check, attacker craft `/login?returnTo=https://evil.com` would
+ * cause post-login redirect to attacker domain with authenticated session cookie.
  *
- * T1.1 shipped types-only.
- * T1.2 adds runtime: defineAuth() + 4 typed error classes + validateReturnTo helper.
+ * Rules:
+ *   - undefined/empty returnTo → default '/'
+ *   - protocol-relative `//evil.com` → default '/' (URL parser would resolve to baseUrl protocol)
+ *   - absolute URL with origin ≠ baseUrl.origin → default '/' (cross-origin redirect)
+ *   - absolute URL with origin === baseUrl.origin → keep (same-origin allowed)
+ *   - relative path starting with '/' → keep (same-app navigation)
+ *   - relative path not starting with '/' → default '/' (defensive)
  */
-export { AuthCallbackError, AuthCancelledError, AuthConfigError, AuthProviderNotFoundError, } from "./errors.js";
-export { AuthSecretTooShortError } from "./oauth-transaction-store.js";
-export { Auth } from "./orchestrator.js";
-export type { AuthOrchestrator, AuthProvider, AuthResult, DefineAuthOptions, OAuthTransaction, SessionManager, } from "./types.js";
-export { validateReturnTo } from "./validate-return-to.js";
+declare function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string;
+
+export { Auth, AuthCallbackError, AuthCancelledError, AuthConfigError, type AuthOrchestrator, type AuthProvider, AuthProviderNotFoundError, type AuthResult, AuthSecretTooShortError, type DefineAuthOptions, type OAuthTransaction, type SessionManager, validateReturnTo };