@agentex/agent 0.0.27 → 0.0.29

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentex/agent",
-  "version": "0.0.27",
-  "description": "Programmatic execution of AI coding agents (Claude Code, Codex, OpenClaw)",
+  "version": "0.0.29",
+  "description": "Programmatic execution of AI coding agents including Claude Code, Codex, Cursor, and OpenCode",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dynamismlabs/agentex.git",
@@ -38,6 +38,11 @@
       "import": "./dist/goals/index.js",
       "default": "./dist/goals/index.js"
     },
+    "./history": {
+      "types": "./dist/history/index.d.ts",
+      "import": "./dist/history/index.js",
+      "default": "./dist/history/index.js"
+    },
     "./sessions": {
       "types": "./dist/sessions/index.d.ts",
       "import": "./dist/sessions/index.js",
@@ -84,6 +89,8 @@
     "agent",
     "claude",
     "codex",
+    "cursor",
+    "opencode",
     "openclaw",
     "provider",
     "execution"
@@ -114,6 +121,7 @@
     "smoke:mock": "tsx scripts/smoke.ts --mock",
     "smoke:concurrent": "tsx scripts/concurrent-smoke.ts",
     "demo:durable": "tsx scripts/durable-session-demo.ts",
+    "diagnose:history": "tsx scripts/local-history-diagnostic.ts",
     "list-models": "tsx scripts/list-models.ts"
   }
 }

package/src/derived.ts

@@ -1,11 +1,18 @@
 import type {
+  AgentSession,
+  AttachOptions,
+  HistoryAttachment,
   ProviderCapabilities,
   ProviderConfig,
   ProviderModel,
   ProviderModule,
+  ProviderRuntimeContext,
+  SessionAttachment,
+  SessionRecord,
 } from "./types.js";
 import { getProvider, registerProvider } from "./registry.js";
 import { acpProvider } from "./providers/acp/index.js";
+import { MalformedSessionRecordError } from "./sessions/record.js";
 
 /**
  * Declarative configuration for a *derived* provider — a new provider id that
@@ -76,6 +83,38 @@ export function getAcpFactory(): AcpFactory | null {
   return acpFactory;
 }
 
+function withProviderType(record: SessionRecord | null, providerType: string): SessionRecord | null {
+  return record ? { ...record, providerType } : null;
+}
+
+function wrapDerivedSession(session: AgentSession, providerType: string): AgentSession {
+  return new Proxy(session, {
+    get(target, property) {
+      if (property === "describe") {
+        return target.describe
+          ? () => withProviderType(target.describe!(), providerType)
+          : undefined;
+      }
+      if (property === "describeHistory") {
+        return target.describeHistory
+          ? () => withProviderType(target.describeHistory!(), providerType)
+          : undefined;
+      }
+      const value = Reflect.get(target, property, target) as unknown;
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+function assertDerivedRecord(record: SessionRecord, providerType: string): void {
+  if (record.providerType !== providerType) {
+    throw new MalformedSessionRecordError(
+      `${providerType} attach requires providerType ${JSON.stringify(providerType)}; got ${JSON.stringify(record.providerType)}`,
+      "providerType",
+    );
+  }
+}
+
 /**
  * Build a derived `ProviderModule` from a base provider plus an overlay. The
  * returned module is NOT auto-registered — pass it to `registerProvider`, or
@@ -124,15 +163,21 @@ export function defineDerivedProvider(cfg: DerivedProviderConfig): ProviderModul
 
   if (base.createSession) {
     const baseCreate = base.createSession.bind(base);
-    derived.createSession = (ctx) =>
-      baseCreate({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) });
+    derived.createSession = async (ctx) => wrapDerivedSession(
+      await baseCreate({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) }),
+      cfg.id,
+    );
   }
   if (cfg.models) {
     const models = cfg.models;
     derived.listModels = async () => models;
   } else if (base.listModels) {
     const baseList = base.listModels.bind(base);
-    derived.listModels = (opts) => baseList(opts);
+    derived.listModels = (opts) => baseList({
+      ...opts,
+      env: overlayEnv(opts?.env),
+      config: overlayConfig(opts?.config),
+    });
   }
   if (base.listModes) {
     const baseModes = base.listModes.bind(base);
@@ -144,10 +189,88 @@ export function defineDerivedProvider(cfg: DerivedProviderConfig): ProviderModul
     derived.checkQuota = (qctx) =>
       baseQuota({ ...qctx, env: overlayEnv(qctx?.env), config: overlayConfig(qctx?.config) });
   }
+  if (base.probeCapabilities) {
+    const baseProbe = base.probeCapabilities.bind(base);
+    derived.probeCapabilities = (ctx) => baseProbe({
+      ...ctx,
+      env: overlayEnv(ctx?.env),
+      config: overlayConfig(ctx?.config),
+    });
+  }
+  if (base.upstreamProviders) {
+    const manager = base.upstreamProviders;
+    const runtime = (ctx?: ProviderRuntimeContext): ProviderRuntimeContext => ({
+      ...ctx,
+      env: overlayEnv(ctx?.env),
+      config: overlayConfig(ctx?.config),
+    });
+    derived.upstreamProviders = {
+      list: (ctx) => manager.list(runtime(ctx)),
+      authMethods: (providerId, ctx) => manager.authMethods(providerId, runtime(ctx)),
+      setApiKey: (providerId, key, ctx) => manager.setApiKey(providerId, key, runtime(ctx)),
+      beginOAuth: (providerId, methodId, inputs, ctx) =>
+        manager.beginOAuth(providerId, methodId, inputs, runtime(ctx)),
+      completeOAuth: (flowId, code, ctx) => manager.completeOAuth(flowId, code, runtime(ctx)),
+      canDisconnect: (providerId, ctx) => manager.canDisconnect(providerId, runtime(ctx)),
+      disconnect: (providerId, ctx) => manager.disconnect(providerId, runtime(ctx)),
+    };
+  }
+  if (base.attachSession && derived.createSession) {
+    const baseAttach = base.attachSession.bind(base);
+    derived.attachSession = async (record, opts): Promise<SessionAttachment> => {
+      assertDerivedRecord(record, cfg.id);
+      const attachment = await baseAttach(
+        { ...record, providerType: base.type },
+        overlayAttachOptions(opts, overlayEnv, overlayConfig),
+      );
+      const derivedRecord = withProviderType(attachment.record, cfg.id)!;
+      return {
+        ...attachment,
+        record: derivedRecord,
+        resume: (ctx) => derived.createSession!({
+          ...ctx,
+          cwd: ctx?.cwd ?? derivedRecord.cwd ?? undefined,
+          sessionParams: derivedRecord.params,
+        }),
+      };
+    };
+  }
+  if (base.attachHistory && derived.createSession) {
+    const baseAttachHistory = base.attachHistory.bind(base);
+    derived.attachHistory = async (record, opts): Promise<HistoryAttachment> => {
+      assertDerivedRecord(record, cfg.id);
+      const attachment = await baseAttachHistory(
+        { ...record, providerType: base.type },
+        overlayAttachOptions(opts, overlayEnv, overlayConfig),
+      );
+      const derivedRecord = withProviderType(attachment.record, cfg.id)!;
+      return {
+        ...attachment,
+        record: derivedRecord,
+        resume: (ctx) => derived.createSession!({
+          ...ctx,
+          cwd: ctx?.cwd ?? derivedRecord.cwd ?? undefined,
+          sessionParams: derivedRecord.params,
+        }),
+      };
+    };
+  }
 
   return derived;
 }
 
+function overlayAttachOptions(
+  opts: AttachOptions | undefined,
+  overlayEnv: (env?: Record<string, string>) => Record<string, string>,
+  overlayConfig: (config?: ProviderConfig) => ProviderConfig,
+): AttachOptions {
+  return {
+    ...opts,
+    env: overlayEnv(opts?.env),
+    config: overlayConfig(opts?.config),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Config-file loader
 // ---------------------------------------------------------------------------

package/src/goals/controller.ts

@@ -139,6 +139,9 @@ export class GoalController {
    * sentinel/loop), call `setGoal` again; hydrate does not restart the loop.
    */
   hydrate(state: GoalState): void {
+    // Hydration is historical initialization, never an overwrite. A live
+    // parser event or caller-set goal that won the race remains authoritative.
+    if (this.state !== null) return;
     this.state = state;
     this.mode = "idle";
   }
@@ -387,6 +390,19 @@ export class GoalController {
       // re-enters onTurnSettled and continues the loop.
       const nudge = verdict.nudge ?? defaultNudge(objective, this.iterations);
       void this.deps.send(nudge).catch(() => {});
+    } catch (error) {
+      if (gen !== this.generation) return;
+      this.transition({
+        objective,
+        status: "blocked",
+        met: false,
+        enforced: true,
+        source: "agentex",
+        blockedReason: "sentinel_error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+      this.mode = "idle";
+      this.sentinel = null;
     } finally {
       this.evaluating = false;
     }
@@ -433,6 +449,7 @@ export class GoalController {
       raw: { synthetic: "goal", ...fields },
     };
     if (fields.blockedReason !== undefined) event.blockedReason = fields.blockedReason;
+    if (fields.errorMessage !== undefined) event.errorMessage = fields.errorMessage;
     if (fields.tokensUsed !== undefined) event.tokensUsed = fields.tokensUsed;
     if (fields.timeUsedSeconds !== undefined) event.timeUsedSeconds = fields.timeUsedSeconds;
     if (fields.tokenBudget !== undefined) event.tokenBudget = fields.tokenBudget;

package/src/goals/normalize.ts

@@ -33,6 +33,7 @@ export interface NormalizedGoalFields {
   enforced: boolean;
   source: GoalSource;
   blockedReason?: GoalBlockedReason;
+  errorMessage?: string;
   tokensUsed?: number;
   timeUsedSeconds?: number;
   tokenBudget?: number;
@@ -90,6 +91,9 @@ export function normalizeCodexGoalStatus(raw: string | null | undefined): {
     case "budget-limited":
     case "budget_limited":
     case "budgetlimited": // camelCase `budgetLimited`, lowercased
+    case "usage-limited":
+    case "usage_limited":
+    case "usagelimited": // camelCase `usageLimited`, lowercased
       return { status: "blocked", met: false, blockedReason: "budget" };
     case "blocked":
       return { status: "blocked", met: false, blockedReason: "needs_input" };
@@ -165,6 +169,7 @@ export function goalStateFromEvent(event: GoalStatusEvent): GoalState {
     updatedAt: event.timestamp,
   };
   if (event.blockedReason !== undefined) state.blockedReason = event.blockedReason;
+  if (event.errorMessage !== undefined) state.errorMessage = event.errorMessage;
   if (event.tokensUsed !== undefined) state.tokensUsed = event.tokensUsed;
   if (event.timeUsedSeconds !== undefined) state.timeUsedSeconds = event.timeUsedSeconds;
   if (event.tokenBudget !== undefined) state.tokenBudget = event.tokenBudget;

package/src/history/fs.ts

@@ -0,0 +1,307 @@
+import { createHash } from "node:crypto";
+import { readdir, stat, open as openFile, type FileHandle } from "node:fs/promises";
+import * as path from "node:path";
+import * as readline from "node:readline";
+
+import {
+  LocalHistoryError,
+  type LocalHistorySourceFingerprint,
+} from "./types.js";
+
+export const UUID_JSONL_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;
+export const ROLLOUT_UUID_RE = /-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+export interface JsonlRecord {
+  raw: Record<string, unknown>;
+  text: string;
+  lineStartOffset: number;
+  nextOffset: number;
+}
+
+interface StableReadOptions {
+  /** Reject a completed read when the opened source changed while streaming. */
+  rejectChanges?: boolean;
+  /** Internal deterministic test hook. Not part of the public history API. */
+  afterInitialStat?: () => void | Promise<void>;
+}
+
+interface FileIdentity {
+  size: bigint;
+  modifiedAtNs: bigint;
+  device: bigint;
+  inode: bigint;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+export function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+export function isoDate(value: unknown, fallback: string | null = null): string | null {
+  if (typeof value !== "string") return fallback;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? fallback : parsed.toISOString();
+}
+
+export function cleanTitle(value: string | null): string | null {
+  const cleaned = value
+    ?.replace(/<[^>]+>/g, " ")
+    .replace(/\[\[[^\]]+\]\]/g, " ")
+    .replace(/^[#>*_`\s-]+/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!cleaned) return null;
+  return cleaned.length > 120 ? `${cleaned.slice(0, 117).trimEnd()}...` : cleaned;
+}
+
+export async function isDirectory(filePath: string): Promise<boolean> {
+  try {
+    return (await stat(filePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function listJsonlFiles(
+  root: string,
+  options: { maxDepth: number; limit?: number; accept?: (name: string) => boolean },
+): Promise<string[]> {
+  const files: string[] = [];
+  const limit = Math.max(1, options.limit ?? Number.MAX_SAFE_INTEGER);
+
+  async function visit(dir: string, depth: number): Promise<void> {
+    if (depth > options.maxDepth || files.length >= limit) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (files.length >= limit) break;
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) await visit(child, depth + 1);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl") && (options.accept?.(entry.name) ?? true)) {
+        files.push(child);
+      }
+    }
+  }
+
+  await visit(root, 0);
+  return files;
+}
+
+export async function mapLimited<T, U>(
+  values: readonly T[],
+  concurrency: number,
+  mapper: (value: T) => Promise<U>,
+): Promise<U[]> {
+  const output = new Array<U>(values.length);
+  let cursor = 0;
+  async function worker(): Promise<void> {
+    while (cursor < values.length) {
+      const index = cursor++;
+      output[index] = await mapper(values[index]!);
+    }
+  }
+  await Promise.all(Array.from(
+    { length: Math.min(Math.max(1, concurrency), values.length) },
+    () => worker(),
+  ));
+  return output;
+}
+
+async function fileIdentity(handle: FileHandle): Promise<FileIdentity> {
+  const info = await handle.stat({ bigint: true });
+  if (!info.isFile()) throw new LocalHistoryError("invalid_session", "Local history source is not a file");
+  return {
+    size: info.size,
+    modifiedAtNs: info.mtimeNs,
+    device: info.dev,
+    inode: info.ino,
+  };
+}
+
+function sameFileIdentity(left: FileIdentity, right: FileIdentity): boolean {
+  return left.size === right.size
+    && left.modifiedAtNs === right.modifiedAtNs
+    && left.device === right.device
+    && left.inode === right.inode;
+}
+
+function sourceChangedError(): LocalHistoryError {
+  return new LocalHistoryError(
+    "source_changed_during_read",
+    "Local history source changed during the read",
+  );
+}
+
+function wrapFileError(error: unknown, action: "inspect" | "read" | "hash"): LocalHistoryError {
+  if (error instanceof LocalHistoryError) return error;
+  const code = (error as NodeJS.ErrnoException).code;
+  return new LocalHistoryError(
+    code === "ENOENT" ? "source_missing" : code === "EACCES" ? "permission_denied" : "io_error",
+    code === "ENOENT"
+      ? "Local history source is missing"
+      : `Unable to ${action} local history source`,
+    { cause: error },
+  );
+}
+
+export async function recentEligible<T>(
+  filePaths: readonly string[],
+  options: { limit?: number; concurrency?: number },
+  inspect: (filePath: string) => Promise<T | null>,
+): Promise<T[]> {
+  const limit = options.limit === undefined
+    ? Number.MAX_SAFE_INTEGER
+    : Math.max(0, options.limit);
+  if (limit === 0 || filePaths.length === 0) return [];
+
+  const metadata = await mapLimited(filePaths, 32, async (filePath) => {
+    try {
+      const info = await stat(filePath, { bigint: true });
+      return info.isFile() ? { filePath, modifiedAtNs: info.mtimeNs } : null;
+    } catch {
+      return null;
+    }
+  });
+  const ordered = metadata
+    .filter((value): value is { filePath: string; modifiedAtNs: bigint } => value !== null)
+    .sort((a, b) => a.modifiedAtNs === b.modifiedAtNs
+      ? a.filePath.localeCompare(b.filePath)
+      : a.modifiedAtNs > b.modifiedAtNs ? -1 : 1);
+
+  const output: T[] = [];
+  const concurrency = Math.max(1, options.concurrency ?? 16);
+  let cursor = 0;
+  while (cursor < ordered.length && output.length < limit) {
+    // Never inspect more files than the number of results still requested in
+    // one batch. Excluded files cause another bounded batch to be pulled.
+    const batchSize = Math.min(concurrency, limit - output.length, ordered.length - cursor);
+    const batch = ordered.slice(cursor, cursor + batchSize);
+    cursor += batch.length;
+    const inspected = await mapLimited(batch, concurrency, ({ filePath }) => inspect(filePath));
+    for (const value of inspected) {
+      if (value !== null) output.push(value);
+      if (output.length >= limit) break;
+    }
+  }
+  return output;
+}
+
+export async function sourceFingerprint(
+  filePath: string,
+  includeSha256 = false,
+  internalOptions: StableReadOptions = {},
+): Promise<LocalHistorySourceFingerprint> {
+  let handle: FileHandle | null = null;
+  try {
+    handle = await openFile(filePath, "r");
+    const before = await fileIdentity(handle);
+    const fingerprint: LocalHistorySourceFingerprint = {
+      size: Number(before.size),
+      modifiedAtNs: before.modifiedAtNs.toString(),
+    };
+    if (!includeSha256) return fingerprint;
+
+    await internalOptions.afterInitialStat?.();
+    const hash = createHash("sha256");
+    const stream = handle.createReadStream({ autoClose: false });
+    let after: FileIdentity;
+    try {
+      for await (const chunk of stream) hash.update(chunk as Buffer);
+      after = await fileIdentity(handle);
+    } finally {
+      stream.destroy();
+    }
+    if (!sameFileIdentity(before, after)) throw sourceChangedError();
+    fingerprint.sha256 = hash.digest("hex");
+    return fingerprint;
+  } catch (error) {
+    throw wrapFileError(error, includeSha256 ? "hash" : "inspect");
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function* readJsonlRecords(
+  filePath: string,
+  fromOffset = 0,
+  options: StableReadOptions = {},
+): AsyncIterable<JsonlRecord> {
+  let handle: FileHandle | null = null;
+  let stream: ReturnType<FileHandle["createReadStream"]> | null = null;
+  let rl: readline.Interface | null = null;
+  let offset = fromOffset;
+  try {
+    handle = await openFile(filePath, "r");
+    const before = await fileIdentity(handle);
+    await options.afterInitialStat?.();
+    stream = handle.createReadStream({ start: fromOffset, encoding: "utf8", autoClose: false });
+    stream.on("error", () => {});
+    rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+      const lineStartOffset = offset;
+      offset += Buffer.byteLength(line, "utf8") + 1;
+      if (!line.trim()) continue;
+      try {
+        const raw = asRecord(JSON.parse(line));
+        if (raw) yield { raw, text: line, lineStartOffset, nextOffset: offset };
+      } catch {
+        // A damaged historical record must not hide later valid records.
+      }
+    }
+    if (options.rejectChanges) {
+      const after = await fileIdentity(handle);
+      if (!sameFileIdentity(before, after)) throw sourceChangedError();
+      let pathInfo;
+      try {
+        pathInfo = await stat(filePath, { bigint: true });
+      } catch (error) {
+        throw wrapFileError(error, "inspect");
+      }
+      if (pathInfo.dev !== after.device || pathInfo.ino !== after.inode) throw sourceChangedError();
+    }
+  } catch (error) {
+    throw wrapFileError(error, "read");
+  } finally {
+    rl?.close();
+    stream?.destroy();
+    await handle?.close();
+  }
+}
+
+export function textFromContent(content: unknown, acceptedTypes: ReadonlySet<string>): string | null {
+  if (typeof content === "string") return content.trim() || null;
+  if (!Array.isArray(content)) return null;
+  const parts: string[] = [];
+  for (const value of content) {
+    const block = asRecord(value);
+    if (!block) continue;
+    const type = asString(block["type"]);
+    if (type && !acceptedTypes.has(type)) continue;
+    const text = asString(block["text"]) ?? asString(block["content"]);
+    if (text) parts.push(text);
+  }
+  return parts.join("\n\n").trim() || null;
+}
+
+export function meaningfulHumanText(text: string | null): string | null {
+  if (!text) return null;
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  if (/^<(?:environment_context|user_instructions|developer_instructions|system-reminder)[\s>]/i.test(trimmed)) {
+    return null;
+  }
+  if (/^<(?:local-command-caveat|command-name|command-message|command-args)[\s>]/i.test(trimmed)) {
+    return null;
+  }
+  return trimmed;
+}

package/src/history/index.ts

@@ -0,0 +1,18 @@
+export {
+  LocalHistoryError,
+} from "./types.js";
+export type {
+  LocalHistoryArchiveState,
+  LocalHistoryDiscoverOptions,
+  LocalHistoryErrorCode,
+  LocalHistoryEvent,
+  LocalHistoryFingerprintOptions,
+  LocalHistoryOps,
+  LocalHistoryProbeOptions,
+  LocalHistoryProbeResult,
+  LocalHistoryReadOptions,
+  LocalHistorySession,
+  LocalHistorySourceFingerprint,
+  LocalHistoryUserEvent,
+  LocalHistoryYield,
+} from "./types.js";