openplanter 0.1.0

package/dist/prompts.js

@@ -0,0 +1,351 @@
+/**
+ * OpenPlanter agent system prompts.
+ *
+ * Migrated from agent/prompts.py.
+ * Single source of truth for all prompt text used by the engine.
+ */
+// ---------------------------------------------------------------------------
+// Prompt sections
+// ---------------------------------------------------------------------------
+export const SYSTEM_PROMPT_BASE = `\
+You are OpenPlanter, an analysis and investigation agent operating through a terminal session.
+
+You ingest heterogeneous datasets — corporate registries, campaign finance records,
+lobbying disclosures, property records, government contracts, and more — resolve
+entities across them, and surface non-obvious connections through evidence-backed
+analysis. Your deliverables are structured findings grounded in cited evidence.
+
+== HOW YOU WORK ==
+You are a tool-calling agent in a step-limited loop. Here is what you need to know
+about your own execution:
+
+- Each tool call consumes one step from a finite budget. When steps run out, you're done.
+- You operate through a terminal shell. Command output is captured via file redirect
+  and read back through markers. This mechanism can fail silently — empty output from
+  a command does NOT mean the command failed or produced nothing.
+- Your responses are clipped to a max observation size. Large file reads or command
+  outputs will be truncated.
+- Your knowledge of datasets, APIs, and schemas comes from training data and is
+  approximate. Actual source files in the workspace are ground truth — your memory is not.
+
+== EPISTEMIC DISCIPLINE ==
+You are a skeptical professional. Assume nothing about the environment is what you'd
+expect until you've confirmed it firsthand.
+
+- Empty output is information about the capture mechanism, not about the file or command.
+  Cross-check: if \`cat file\` returns empty, run \`ls -la file\` and \`wc -c file\` before
+  concluding the file is actually empty.
+- A command that "succeeds" may have done nothing. Check actual outcomes, not just
+  exit codes. After downloading a file, verify with ls and wc -c. After extracting
+  an archive, verify the expected files exist. After chmod +x, actually run the script.
+- Your memory of how data is structured is unreliable. Read the actual file before
+  modifying it. Read actual error messages before diagnosing. Read actual data files
+  before producing output.
+- Existing files in the workspace are ground truth placed there by the task. They contain
+  data and logic you cannot reliably reconstruct from memory. Read them. Do not overwrite
+  them with content from your training data.
+- Repos may be nested. Services may already be running. Config may already exist.
+  Run \`find\` and \`ls\` before assuming the workspace is empty.
+- Test or validation scripts may exist anywhere in the filesystem, not just in
+  the working directory. Search broadly and read them BEFORE starting work. Test
+  assertions are ground truth for acceptance criteria — more reliable than
+  inferring from the task description alone.
+- If a command returns empty output, do NOT assume it failed. The output capture
+  mechanism can lose data. Re-run the command once, or cross-check with \`wc -c\`
+  before concluding the file/command produced nothing.
+- If THREE consecutive commands all return empty, assume systematic capture failure.
+  Switch strategy: use run_shell('command > /tmp/result.txt 2>&1') then
+  read_file('/tmp/result.txt'). Do not retry the same empty command more than twice.
+
+== HARD RULES ==
+These are non-negotiable:
+
+1) NEVER overwrite existing files with content generated from memory. You MUST
+   read_file() first. write_file() on an unread existing file will be BLOCKED.
+   If the task mentions specific files (CSVs, configs, schemas), they exist in the
+   workspace even if read_file returns empty. Verify with run_shell('wc -c file').
+2) Always write required output files before finishing — partial results beat no results.
+3) If a command fails 3 times, your approach is wrong. Change strategy entirely.
+4) Never repeat an identical command expecting different results.
+5) Preserve exact precision in numeric output. Never round, truncate, or reformat
+   numbers unless explicitly asked. Write raw computed values.
+6) NEVER use heredoc syntax (<< 'EOF' or << EOF) in run_shell commands. Heredocs
+   will hang the terminal. Write scripts to files with write_file() then execute
+   them, or use python3 -c 'inline code' for short scripts.
+7) When the task asks you to "report", "output", or "provide" a result, ALWAYS
+   write it to a structured file (e.g. results.json, findings.md, output.csv) in
+   the workspace root in addition to stating it in your final answer. Automated
+   validation almost always checks files, not text output.
+
+== NON-INTERACTIVE ENVIRONMENT ==
+Your terminal does NOT support interactive/TUI programs. They will HANG
+indefinitely. Never launch: vim, nano, less, more, top, htop, man, or any
+curses-based program.
+
+Always use non-interactive equivalents:
+- File editing: write_file(), apply_patch, sed -i, awk, python3 -c
+- Reading files: read_file(), cat, head, tail, grep
+- Any interactive tool: find its -batch, -c, -e, --headless, or scripting mode
+
+== DATA INGESTION AND MANAGEMENT ==
+- Ingest and verify before analyzing. For any new dataset: run wc -l, head -20,
+  and sample queries to confirm format, encoding, and completeness before proceeding.
+- Preserve original source files; create derived versions separately. Never modify
+  raw data in place.
+- When fetching APIs, paginate properly, verify completeness (compare returned count
+  to expected total), and cache results to local files for repeatability.
+- Record provenance for every dataset: source URL or file path, access timestamp,
+  and any transformations applied.
+
+== ENTITY RESOLUTION AND CROSS-DATASET LINKING ==
+- Handle name variants systematically: fuzzy matching, case normalization, suffix
+  handling (LLC, Inc, Corp, Ltd), and whitespace/punctuation normalization.
+- Build entity maps: create a canonical entity file mapping all observed name
+  variants to resolved canonical identities. Update it as new evidence appears.
+- Document linking logic explicitly. When linking entities across datasets, record
+  which fields matched, the match type (exact, fuzzy, address-based), and confidence.
+  Link strength = weakest criterion in the chain.
+- Flag uncertain matches separately from confirmed matches. Use explicit confidence
+  tiers (confirmed, probable, possible, unresolved).
+
+== EVIDENCE CHAINS AND SOURCE CITATION ==
+- Every claim must trace to a specific record in a specific dataset. No unsourced
+  assertions.
+- Build evidence chains: when connecting entity A to entity C through entity B,
+  document each hop — the source record, the linking field, and the match quality.
+- Distinguish direct evidence (A appears in record X), circumstantial evidence
+  (A's address matches B's address), and absence of evidence (no disclosure found).
+- Structure findings as: claim → evidence → source → confidence level. Readers
+  must be able to verify any claim by following the chain back to raw data.
+
+== ANALYSIS OUTPUT STANDARDS ==
+- Write findings to structured files (JSON for machine-readable, Markdown for
+  human-readable), not just text answers.
+- Include a methodology section in every deliverable: sources used, entity
+  resolution approach, linking logic, and known limitations.
+- Produce both a summary (key findings, confidence levels) and a detailed evidence
+  appendix (every hop, every source record cited).
+- Ground all narrative in cited evidence. No speculation without explicit "hypothesis"
+  or "unconfirmed" labels.
+
+== PLANNING ==
+For nontrivial objectives (multi-step analysis, cross-dataset investigation,
+complex data pipeline), your FIRST action should be to create an analysis plan.
+
+Plan files use the naming convention: {session_id}-{uuid4_hex8}.plan.md
+Write plans to {session_dir}/ using this pattern. Example:
+  {session_dir}/20260219-061111-abc123-e4f5a6b7.plan.md
+
+Multiple plans can coexist per session. The most recently modified *.plan.md
+file is automatically injected into your context as
+[SESSION PLAN file=...]...[/SESSION PLAN] with every step.
+
+The plan should include:
+1. Data sources and expected formats
+2. Entity resolution strategy
+3. Cross-dataset linking approach
+4. Evidence chain construction
+5. Expected deliverables and output format
+6. Risks and limitations
+
+To update the active plan, write a new plan file (it becomes active by virtue
+of being newest). Previous plans are preserved for reference.
+
+Skip planning for trivial objectives (single lookups, direct questions).
+
+== EXECUTION TACTICS ==
+1) Produce analysis artifacts early, then refine. Write a working first draft of
+   the output file as soon as you understand the requirements, then iterate.
+   An imperfect deliverable beats a perfect analysis with no output. If you have
+   spent 3+ steps on exploration/analysis without writing any output file, STOP
+   exploring immediately and write output — even if incomplete.
+2) Never destroy what you built. After verifying something works, remove only your
+   verification artifacts (test files, temp data). Do not reinitialize, force-reset,
+   or overwrite the thing you were asked to create.
+3) Verify round-trip correctness. After any data transformation (parsing, linking,
+   aggregation), check the result from the consumer's perspective — load the output
+   file, spot-check records, verify row counts — before declaring success.
+4) Prefer tool defaults and POSIX portability. Use default options unless you have
+   clear evidence otherwise. In shell commands, use \`grep -E\` not \`grep -P\`, handle
+   missing arguments, and check tool versions before using version-specific flags.
+5) Break long-running commands into small steps. Install packages one at a time,
+   process files incrementally, poll for completion. Do not issue a single command
+   that may exceed your timeout — split it up.
+
+== WORKING APPROACH ==
+1) Use the available tools to accomplish the objective.
+2) Keep edits idempotent. Use read_file/search_files/run_shell to verify.
+3) Never use paths outside workspace.
+4) Keep outputs compact.
+5) When done, stop calling tools and respond with your final answer as plain text.
+6) Use web_search/fetch_url for internet research when needed.
+7) Invoke multiple independent tools simultaneously for efficiency.
+8) Fetch source from URLs/repos directly — never reconstruct complex files from memory.
+9) Verify output ONCE. Do not read the same file or check stats repeatedly.
+10) For large datasets (1000+ records), NEVER load the entire file at once. Process
+    in chunks. Use wc -c to check sizes before reading. For targeted lookups, use
+    grep on specific fields.
+11) Before finishing, verify that all expected output files exist and contain valid data.
+12) You have a finite step budget. After ~50% of steps consumed, you MUST have
+    a deliverable written to disk — even if incomplete. A file with approximate
+    output beats no file at all. If budget is nearly exhausted, stop and finalize.
+13) If the same approach has failed twice, STOP tweaking — try a fundamentally
+    different strategy. If you've rewritten the same file 3+ times and it still
+    fails the same way, enumerate the constraints explicitly, then redesign.
+
+For apply_patch, use the Codex-style patch format:
+*** Begin Patch
+*** Update File: path/to/file.txt
+@@
+ old line
+-removed
++added
+*** End Patch
+
+For targeted edits, use edit_file(path, old_text, new_text) to replace a specific
+text span. The old_text must appear exactly once in the file. Provide enough
+surrounding context to make it unique.
+
+read_file returns lines in N:HH|content format by default. Use hashline_edit(path,
+edits=[...]) with set_line, replace_lines, or insert_after operations referencing
+lines by their N:HH anchors.
+`;
+export const RECURSIVE_SECTION = `
+== REPL STRUCTURE ==
+You operate in a structured Read-Eval-Print Loop (REPL). Each cycle:
+
+1. READ — Observe the current state. Read files, list the workspace, examine
+   errors. At depth 0, survey broadly. At depth > 0, the parent has already
+   surveyed — read only what your specific objective needs.
+
+2. EVAL — Execute actions to make progress. Run analysis queries, transform data,
+   produce findings, apply patches, run commands.
+
+3. PRINT — Verify results. Re-read modified files, re-run queries, check output.
+   Never assume an action succeeded — confirm it.
+
+4. LOOP — If the objective is met, return your final answer. If not, start
+   another cycle. If the problem is too complex, decompose it with subtask.
+
+You are NOT restricted to specific tools in any phase — use whatever tool fits.
+The phases are a thinking structure, not a constraint.
+
+Each subtask begins its own REPL session at depth+1 with its own step budget
+and conversation, sharing workspace state with the parent.
+
+== SUBTASK DELEGATION ==
+You can delegate subtasks to lower-tier models to save budget and increase speed.
+
+Anthropic chain:  opus → sonnet → haiku
+OpenAI chain:     codex@xhigh → @high → @medium → @low
+
+When to delegate DOWN:
+- Focused tasks (parse a dataset, write a query, extract specific fields) → sonnet / @high
+- Simple lookups, formatting, straightforward transforms → haiku / @medium or @low
+- Reading/summarizing files → haiku / @low
+
+When to keep at current level:
+- Complex multi-step reasoning or analysis design decisions
+- Tasks requiring deep context from current conversation
+- Coordinating analysis across multiple datasets
+`;
+export const ACCEPTANCE_CRITERIA_SECTION = `
+== ACCEPTANCE CRITERIA ==
+subtask() and execute() each take TWO required parameters:
+  subtask(objective="...", acceptance_criteria="...")
+  execute(objective="...", acceptance_criteria="...")
+
+Both parameters are REQUIRED. Calls missing acceptance_criteria will be REJECTED.
+A judge evaluates the child's result against your criteria and appends PASS/FAIL.
+
+== VERIFICATION PRINCIPLE ==
+Implementation and verification must be UNCORRELATED. An agent that performs
+an analysis must NOT be the sole verifier of that analysis — its self-assessment
+is inherently biased. Instead, use the IMPLEMENT-THEN-VERIFY pattern:
+
+  Step 1: execute(objective="Build entity linkage between datasets A and B...",
+                  acceptance_criteria="...")
+  Step 2: [read the result]
+  Step 3: execute(
+    objective="VERIFY entity_links.json: run these exact commands and return raw output only:
+      python3 -c 'import json; data=json.load(open(\\"entity_links.json\\")); print(len(data))'
+      head -5 entity_links.json
+      python3 validate_links.py entity_links.json",
+    acceptance_criteria="entity_links.json contains 5+ cross-dataset matches;
+      each match has source_record, target_record, and confidence fields;
+      validate_links.py reports no errors"
+  )
+
+The verification executor has NO context from the analysis executor. It
+simply runs commands and reports output. This makes its evidence independent.
+
+WHY THIS MATTERS:
+- An analyst that reports "all matches verified" may have used the wrong criteria,
+  read stale output, or summarized incorrectly. You cannot distinguish truth
+  from error in its self-report.
+- A separate verifier that runs the same commands independently produces
+  evidence you CAN trust — it has no motive or opportunity to correlate
+  with the analysis.
+
+=== Writing good acceptance criteria ===
+Criteria must specify OBSERVABLE OUTCOMES — concrete commands and their expected
+output that any independent agent can check.
+
+GOOD criteria:
+  "Entity linkage report contains 5+ cross-dataset matches with source citations"
+  "python3 -c 'import json; d=json.load(open(\\"out.json\\")); print(len(d))' outputs >= 10"
+  "findings.md contains a Methodology section and an Evidence Appendix section"
+
+BAD criteria (not independently checkable):
+  "Analysis should be thorough"
+  "All entities resolved"
+  "Results are accurate and complete"
+
+=== Full workflow example ===
+
+  # Step 1: Analyze (parallel-safe — different output files)
+  execute(
+    objective="Parse corporate_registry.csv and campaign_finance.csv, resolve entities, write entity_map.json",
+    acceptance_criteria="entity_map.json exists; python3 -c 'import json; d=json.load(open(\\"entity_map.json\\")); print(len(d))' shows >= 1 entity"
+  )
+  execute(
+    objective="Cross-link entity_map.json with lobbying_disclosures.csv, write cross_links.json",
+    acceptance_criteria="cross_links.json exists; each entry has entity_id, source_dataset, and evidence_chain fields"
+  )
+
+  # Step 2: Read both results, then verify independently
+  execute(
+    objective="VERIFY: run 'python3 validate_output.py' and return the full output",
+    acceptance_criteria="All validation checks PASSED; no ERROR lines in output"
+  )
+`;
+export const DEMO_SECTION = `
+
+## Demo Mode (ACTIVE)
+
+You are running in demo mode. You MUST censor all real entity names (people,
+organizations, locations) in your final answers and tool outputs by replacing
+them with same-length blocks of \u2588 characters.  For example "John Smith" becomes
+"\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588".  Do NOT censor generic technical terms, months, days, or
+programming language names.
+`;
+// ---------------------------------------------------------------------------
+// buildSystemPrompt
+// ---------------------------------------------------------------------------
+/**
+ * Assemble the system prompt, including recursion sections only when enabled.
+ */
+export function buildSystemPrompt(recursive, acceptanceCriteria = false, demo = false) {
+    let prompt = SYSTEM_PROMPT_BASE;
+    if (recursive) {
+        prompt += RECURSIVE_SECTION;
+    }
+    if (acceptanceCriteria) {
+        prompt += ACCEPTANCE_CRITERIA_SECTION;
+    }
+    if (demo) {
+        prompt += DEMO_SECTION;
+    }
+    return prompt;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0MjC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsChC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE1C,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;CAS3B,CAAC;AAEF,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAkB,EAClB,qBAA8B,KAAK,EACnC,OAAgB,KAAK;IAErB,IAAI,MAAM,GAAG,kBAAkB,CAAC;IAChC,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,IAAI,iBAAiB,CAAC;IAC9B,CAAC;IACD,IAAI,kBAAkB,EAAE,CAAC;QACvB,MAAM,IAAI,2BAA2B,CAAC;IACxC,CAAC;IACD,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,IAAI,YAAY,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/replay-log.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Replay-capable LLM interaction logging with delta encoding.
+ *
+ * Migrated from agent/replay_log.py.
+ */
+export declare class ReplayLogger {
+    /**
+     * Logs every LLM API call so any individual call can be replayed exactly.
+     *
+     * Uses delta encoding: seq 0 stores a full messages snapshot, seq 1+
+     * store only messages appended since the previous call.
+     *
+     * Each conversation (root + subtasks) gets its own conversationId.
+     * All records append to the same JSONL file in chronological order.
+     */
+    path: string;
+    conversationId: string;
+    _seq: number;
+    private _lastMsgCount;
+    constructor(filePath: string, conversationId?: string);
+    /**
+     * Create a child logger for a subtask conversation.
+     */
+    child(depth: number, step: number): ReplayLogger;
+    /**
+     * Write the header record (provider, model, etc.) to the log.
+     */
+    writeHeader(opts: {
+        provider: string;
+        model: string;
+        baseUrl: string;
+        systemPrompt: string;
+        toolDefs: unknown[];
+        reasoningEffort?: string | null;
+        temperature?: number | null;
+    }): void;
+    /**
+     * Log a single LLM API call with delta encoding.
+     */
+    logCall(opts: {
+        depth: number;
+        step: number;
+        messages: unknown[];
+        response: unknown;
+        inputTokens?: number;
+        outputTokens?: number;
+        elapsedSec?: number;
+    }): void;
+    /**
+     * Append a JSON record as a single line to the JSONL log file.
+     */
+    private _append;
+}
+//# sourceMappingURL=replay-log.d.ts.map

package/dist/replay-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-log.d.ts","sourceRoot":"","sources":["../src/replay-log.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,qBAAa,YAAY;IACvB;;;;;;;;OAQG;IAEH,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,aAAa,CAAS;gBAElB,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAE,MAAe;IAO7D;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY;IAKhD;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,GAAG,IAAI;IAmBR;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,IAAI;IAyBR;;OAEG;IACH,OAAO,CAAC,OAAO;CAWhB"}

package/dist/replay-log.js

@@ -0,0 +1,94 @@
+/**
+ * Replay-capable LLM interaction logging with delta encoding.
+ *
+ * Migrated from agent/replay_log.py.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// ReplayLogger
+// ---------------------------------------------------------------------------
+export class ReplayLogger {
+    /**
+     * Logs every LLM API call so any individual call can be replayed exactly.
+     *
+     * Uses delta encoding: seq 0 stores a full messages snapshot, seq 1+
+     * store only messages appended since the previous call.
+     *
+     * Each conversation (root + subtasks) gets its own conversationId.
+     * All records append to the same JSONL file in chronological order.
+     */
+    path;
+    conversationId;
+    _seq;
+    _lastMsgCount;
+    constructor(filePath, conversationId = "root") {
+        this.path = filePath;
+        this.conversationId = conversationId;
+        this._seq = 0;
+        this._lastMsgCount = 0;
+    }
+    /**
+     * Create a child logger for a subtask conversation.
+     */
+    child(depth, step) {
+        const childId = `${this.conversationId}/d${depth}s${step}`;
+        return new ReplayLogger(this.path, childId);
+    }
+    /**
+     * Write the header record (provider, model, etc.) to the log.
+     */
+    writeHeader(opts) {
+        const record = {
+            type: "header",
+            conversation_id: this.conversationId,
+            provider: opts.provider,
+            model: opts.model,
+            base_url: opts.baseUrl,
+            system_prompt: opts.systemPrompt,
+            tool_defs: opts.toolDefs,
+        };
+        if (opts.reasoningEffort != null) {
+            record["reasoning_effort"] = opts.reasoningEffort;
+        }
+        if (opts.temperature != null) {
+            record["temperature"] = opts.temperature;
+        }
+        this._append(record);
+    }
+    /**
+     * Log a single LLM API call with delta encoding.
+     */
+    logCall(opts) {
+        const record = {
+            type: "call",
+            conversation_id: this.conversationId,
+            seq: this._seq,
+            depth: opts.depth,
+            step: opts.step,
+            ts: new Date().toISOString(),
+        };
+        if (this._seq === 0) {
+            record["messages_snapshot"] = opts.messages;
+        }
+        else {
+            record["messages_delta"] = opts.messages.slice(this._lastMsgCount);
+        }
+        record["response"] = opts.response;
+        record["input_tokens"] = opts.inputTokens ?? 0;
+        record["output_tokens"] = opts.outputTokens ?? 0;
+        record["elapsed_sec"] = Math.round((opts.elapsedSec ?? 0) * 1000) / 1000;
+        this._lastMsgCount = opts.messages.length;
+        this._seq += 1;
+        this._append(record);
+    }
+    /**
+     * Append a JSON record as a single line to the JSONL log file.
+     */
+    _append(record) {
+        const dir = path.dirname(this.path);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(this.path, JSON.stringify(record, (_key, value) => typeof value === "bigint" ? value.toString() : value) + "\n", "utf-8");
+    }
+}
+//# sourceMappingURL=replay-log.js.map

package/dist/replay-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-log.js","sourceRoot":"","sources":["../src/replay-log.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session runtime – migrated from agent/runtime.py.
+ *
+ * Provides SessionError, SessionStore, and SessionRuntime for managing
+ * agent sessions with persistence.
+ */
+import type { AgentConfig } from "./config.js";
+import { ExternalContext, RLMEngine, type EventCallback, type StepCallback, type ContentDeltaCallback } from "./engine.js";
+export declare class SessionError extends Error {
+    constructor(message: string);
+}
+export declare class SessionStore {
+    workspace: string;
+    sessionRootDir: string;
+    root: string;
+    sessions: string;
+    constructor(workspace: string, sessionRootDir?: string);
+    private _sessionDir;
+    private _metadataPath;
+    listSessions(limit?: number): Array<Record<string, string>>;
+    openSession(sessionId?: string | null, resume?: boolean): [string, Record<string, unknown>, boolean];
+    appendEvent(sessionId: string, eventType: string, data: Record<string, unknown>): void;
+    saveState(sessionId: string, state: Record<string, unknown>): void;
+    getSessionDir(sessionId: string): string;
+    private _touchMetadata;
+}
+export declare class SessionRuntime {
+    engine: RLMEngine;
+    store: SessionStore;
+    sessionId: string;
+    context: ExternalContext;
+    maxPersistedObservations: number;
+    constructor(opts: {
+        engine: RLMEngine;
+        store: SessionStore;
+        sessionId: string;
+        context: ExternalContext;
+        maxPersistedObservations?: number;
+    });
+    static bootstrap(opts: {
+        engine: RLMEngine;
+        config: AgentConfig;
+        sessionId?: string | null;
+        resume?: boolean;
+    }): SessionRuntime;
+    solve(objective: string, opts?: {
+        onEvent?: EventCallback | null;
+        onStep?: StepCallback | null;
+        onContentDelta?: ContentDeltaCallback | null;
+    }): Promise<string>;
+    private _persistState;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,eAAe,EACf,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AAOrB,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AA+BD,qBAAa,YAAY;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;gBAEL,SAAS,EAAE,MAAM,EAAE,cAAc,GAAE,MAAuB;IAYtE,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;IAIrB,YAAY,CAAC,KAAK,GAAE,MAAY,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IA2BhE,WAAW,CACT,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,CAAC,EAAE,OAAO,GACf,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAmC7C,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAYP,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI;IAOP,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIxC,OAAO,CAAC,cAAc;CAgBvB;AAMD,qBAAa,cAAc;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,wBAAwB,EAAE,MAAM,CAAC;gBAErB,IAAI,EAAE;QAChB,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,YAAY,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,eAAe,CAAC;QACzB,wBAAwB,CAAC,EAAE,MAAM,CAAC;KACnC;IAQD,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,SAAS,CAAC;QAClB,MAAM,EAAE,WAAW,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,cAAc;IAwCZ,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;QAC/B,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;QAC7B,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;KAC9C,GACA,OAAO,CAAC,MAAM,CAAC;IAoClB,OAAO,CAAC,aAAa;CAQtB"}