@getopencrawl/cli 0.0.0-stage → 0.1.1

package/src/answer-contract.mjs

@@ -0,0 +1,112 @@
+// Validation body compiled from sdk/src/answerContract.ts; parity is checked in tests.
+// This optional reader never mutates a run or certifies whole-goal completion.
+// Keep the validation/formatter body identical across the SDK, CLI and web.
+const obj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const int = (v, min = 0, max = Number.MAX_SAFE_INTEGER) => typeof v === 'number' && Number.isSafeInteger(v) && v >= min && v <= max;
+const text = (v, max, min = 1) => typeof v === 'string' && Array.from(v).length >= min && Array.from(v).length <= max && !/[\uD800-\uDFFF]/u.test(v) && !v.includes('\0');
+const digest = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const requireValue = (ok) => { if (!ok)
+    throw new Error('Invalid optional answer assessment'); };
+const unknownNotice = (c) => `Research assessment for “${c.text}”: the saved source text used for this run does not establish an answer or its contradiction. Scope: ${c.evidence_ids.join(', ')}.`;
+const undeliveredNotice = (c) => `Research assessment for “${c.text}”: answer material was found in the saved source text, but a complete answer was not retained in this result. Scope: ${c.evidence_ids.join(', ')}.`;
+const unassessedNotice = 'Requested-answer coverage was not assessed for this run. The findings and coverage notes remain available.';
+const invalidNotice = 'Requested-answer assessment could not be validated for this run. The findings and coverage notes remain available.';
+const reasons = [null, 'component_contract_invalid', 'component_review_empty', 'goal_representation_bound', 'optional_input_bound', 'optional_output_bound', 'input_binding_invalid', 'review_skipped', 'no_evidence', 'legacy_receipt'];
+function notice(c) { return c.status === 'source_scoped_unknown_assessment' ? unknownNotice(c) : c.status === 'available_but_not_delivered' ? undeliveredNotice(c) : null; }
+export function readAnswerContract(run, hash) {
+    if (!Object.hasOwn(run.usage, 'answer_contract'))
+        return { state: 'absent', contract: null, notices: [] };
+    try {
+        const value = run.usage.answer_contract;
+        requireValue(new TextEncoder().encode(JSON.stringify(run.usage)).length <= 16384);
+        requireValue(obj(value));
+        const v = value;
+        requireValue(v.version === 1 && v.inventory === 'nonexhaustive' && v.whole_request_completeness === 'not_certified');
+        if (keys(v, ['version', 'state', 'reason', 'inventory', 'whole_request_completeness', 'components_omitted'])) {
+            requireValue(v.state === 'unassessed' && v.reason === 'optional_output_bound' && int(v.components_omitted, 0, 8));
+            return { state: 'unassessed', contract: structuredClone(v), notices: [{ id: 'unassessed', text: unassessedNotice }] };
+        }
+        requireValue(keys(v, ['version', 'state', 'reason', 'scope', 'source_scope', 'inventory', 'whole_request_completeness', 'goal_sha256', 'components', 'notice_components_omitted', 'gap_notice']));
+        requireValue(['assessed_nonexhaustive', 'unassessed'].includes(v.state) && reasons.includes(v.reason) && v.scope === 'admitted_retained_windows_only' && digest(v.goal_sha256));
+        requireValue(Array.isArray(v.source_scope) && v.source_scope.length <= 20 && Array.isArray(v.components) && v.components.length <= 8);
+        const scopes = new Map();
+        for (const s of v.source_scope) {
+            requireValue(obj(s) && keys(s, ['evidence_id', 'source_sha256', 'window_text_sha256', 'window_chars', 'source_kind', ...(s.source_kind === 'web_page' ? ['page'] : [])]));
+            requireValue(text(s.evidence_id, 80) && s.evidence_id.trim() === s.evidence_id && !/[\u0000-\u0020\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(s.evidence_id) && !scopes.has(s.evidence_id) && digest(s.source_sha256) && digest(s.window_text_sha256) && int(s.window_chars, 1, 16000) && ['indexed', 'web_page'].includes(s.source_kind));
+            if (s.source_kind === 'web_page') {
+                const p = s.page;
+                requireValue(obj(p) && keys(p, ['body_sha256', 'start', 'end', 'total_chars']) && digest(p.body_sha256) && int(p.start, 0, 131071) && int(p.end, 1, 131072) && int(p.total_chars, 1, 131072) && p.start < p.end && p.end <= p.total_chars && p.end - p.start === s.window_chars);
+            }
+            scopes.set(s.evidence_id, s);
+        }
+        // Available citations must agree, but uncited scope is retained too. No new
+        // source fetch or mutable agent.goal is substituted for the original run.
+        for (const f of run.findings)
+            for (const cite of f.citations) {
+                const s = scopes.get(cite.id);
+                requireValue(s && s.window_text_sha256 === cite.body_sha256 && s.source_kind === cite.source_kind);
+                if (s?.source_kind === 'web_page')
+                    requireValue(cite.page && ['body_sha256', 'start', 'end', 'total_chars'].every(k => s.page[k] === cite.page[k]));
+            }
+        requireValue(v.state === 'unassessed' ? (v.components.length === 0 && v.reason !== null) : (v.components.length > 0 && v.reason === null));
+        const ids = new Set(), spans = [], eligible = [];
+        const allIds = [...scopes.keys()];
+        for (const c of v.components) {
+            requireValue(obj(c) && keys(c, ['component_id', 'start', 'end', 'text', 'status', 'reason', 'fact_refs', 'evidence_ids', 'source_state']));
+            requireValue(typeof c.component_id === 'string' && /^[CM][1-8]$/.test(c.component_id) && !ids.has(c.component_id));
+            ids.add(c.component_id);
+            requireValue(int(c.start, 0, 3999) && int(c.end, 1, 4000) && text(c.text, 256) && c.text.trim() && c.end - c.start === Array.from(c.text).length);
+            requireValue(['literal_answer', 'literal_negative_answer', 'source_scoped_unknown_assessment', 'available_but_not_delivered', 'unassessed'].includes(c.status));
+            requireValue([null, 'linked_finding_rejected', 'request_anchor_not_meaningful', 'review_unassessed'].includes(c.reason) && ['supported', 'explicitly_contradicted', 'not_established', 'unassessed'].includes(c.source_state));
+            requireValue(Array.isArray(c.evidence_ids) && c.evidence_ids.length <= 20 && same(c.evidence_ids, allIds.filter(id => c.evidence_ids.includes(id))) && Array.isArray(c.fact_refs) && c.fact_refs.length <= 10);
+            const refIds = new Set(), ownIds = new Set();
+            for (const r of c.fact_refs) {
+                requireValue(obj(r) && keys(r, ['finding_id', 'field', 'qualifier_ordinal', 'literal_text_sha256']) && digest(r.literal_text_sha256));
+                const f = run.findings.find(f => f.id === r.finding_id), key = JSON.stringify([r.finding_id, r.field, r.qualifier_ordinal]);
+                requireValue(f && !refIds.has(key) && ['claim', 'qualifier'].includes(r.field) && int(r.qualifier_ordinal, r.field === 'claim' ? 0 : 1, r.field === 'claim' ? 0 : f?.qualifiers.length));
+                refIds.add(key);
+                const literal = r.field === 'claim' ? f.claim : f.qualifiers[r.qualifier_ordinal - 1];
+                requireValue(hash(literal) === r.literal_text_sha256);
+                f.citations.forEach(cite => ownIds.add(cite.id));
+            }
+            if (c.status === 'unassessed')
+                requireValue(c.source_state === 'unassessed' && ['request_anchor_not_meaningful', 'review_unassessed'].includes(c.reason) && !c.fact_refs.length && !c.evidence_ids.length);
+            else if (c.status === 'source_scoped_unknown_assessment')
+                requireValue(c.source_state === 'not_established' && c.reason === null && !c.fact_refs.length && allIds.length > 0 && same(c.evidence_ids, allIds));
+            else {
+                requireValue(['supported', 'explicitly_contradicted'].includes(c.source_state) && c.evidence_ids.length > 0);
+                if (c.status === 'available_but_not_delivered')
+                    requireValue(c.reason === null || c.reason === 'linked_finding_rejected');
+                else
+                    requireValue(c.reason === null && c.fact_refs.length > 0 && c.status === (c.source_state === 'supported' ? 'literal_answer' : 'literal_negative_answer') && same(c.evidence_ids, allIds.filter(id => ownIds.has(id))));
+            }
+            if (c.reason !== 'request_anchor_not_meaningful') {
+                requireValue(spans.every(p => p.text !== c.text && (p.end <= c.start || p.start >= c.end)));
+                spans.push(c);
+            }
+            if (notice(c))
+                eligible.push(c);
+        }
+        requireValue(int(v.notice_components_omitted, 0, eligible.length));
+        let delivered = [];
+        if (v.gap_notice !== null) {
+            const g = v.gap_notice;
+            requireValue(obj(g) && keys(g, ['index', 'sha256', 'component_ids']) && int(g.index, 0, run.gaps.length - 1) && g.index === run.gaps.length - 1 && digest(g.sha256) && hash(run.gaps[g.index]) === g.sha256);
+            requireValue(Array.isArray(g.component_ids) && g.component_ids.length > 0 && same(g.component_ids, eligible.filter(c => g.component_ids.includes(c.component_id)).map(c => c.component_id)));
+            const suffix = ' ' + eligible.filter(c => g.component_ids.includes(c.component_id)).map(c => notice(c)).join(' ');
+            requireValue(run.gaps[g.index].endsWith(suffix));
+            delivered = g.component_ids;
+        }
+        requireValue(v.notice_components_omitted === eligible.length - delivered.length);
+        const notices = v.state === 'unassessed' ? [{ id: 'unassessed', text: unassessedNotice }] : v.components.flatMap((c) => {
+            const n = notice(c);
+            return n && !delivered.includes(c.component_id) ? [{ id: c.component_id, text: n }] : c.status === 'unassessed' ? [{ id: c.component_id, text: `Research assessment for “${c.text}”: requested-answer coverage was not assessed.` }] : [];
+        });
+        return { state: v.state, contract: structuredClone(v), notices };
+    }
+    catch {
+        return { state: 'invalid', contract: null, notices: [{ id: 'invalid', text: invalidNotice }] };
+    }
+}

package/src/answer-view.mjs

@@ -0,0 +1,118 @@
+// Validation body compiled from sdk/src/answerView.ts; parity is checked in tests.
+const obj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const need = (ok) => { if (!ok)
+    throw new Error('Invalid optional concise answer'); };
+const digest = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const refKey = (r) => JSON.stringify([r.finding_id, r.field, r.qualifier_ordinal, r.literal_text_sha256]);
+const empty = (state) => ({ state, view: null, sections: [] });
+const byteLength = (text) => new TextEncoder().encode(text).length;
+/** Python's sorted-key, compact, ensure_ascii=False JSON for bounded public data.
+ * Literal strings are not normalized. Reject lossy JSON values and lone surrogates.
+ */
+export function canonicalAnswerJson(value) {
+    let nodes = 0;
+    const scalar = (text) => { need(!/[\uD800-\uDFFF]/u.test(text)); return JSON.stringify(text); };
+    const compare = (a, b) => { const x = Array.from(a), y = Array.from(b); for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (d)
+            return d;
+    } return x.length - y.length; };
+    const encode = (v, depth) => {
+        need(++nodes <= 8192 && depth <= 24);
+        if (v === null)
+            return 'null';
+        if (typeof v === 'string')
+            return scalar(v);
+        if (typeof v === 'boolean')
+            return v ? 'true' : 'false';
+        if (typeof v === 'number') {
+            need(Number.isSafeInteger(v) && !Object.is(v, -0));
+            return String(v);
+        }
+        if (Array.isArray(v))
+            return '[' + Array.from(v, item => encode(item, depth + 1)).join(',') + ']';
+        need(obj(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+        return '{' + Object.keys(v).sort(compare).map(k => scalar(k) + ':' + encode(v[k], depth + 1)).join(',') + '}';
+    };
+    const result = encode(value, 0);
+    need(byteLength(result) <= 65536);
+    return result;
+}
+function omission(c, reason) {
+    if (reason === 'source_scoped_unknown')
+        return 'Not established in the saved sources for this part.';
+    if (reason === 'answer_not_delivered')
+        return 'Answer material was found in the saved source text, but a complete answer was not retained in this result.';
+    return c.status === 'unassessed' ? 'Review the exact evidence for this part. Requested-answer coverage was not assessed.' : 'Review the exact evidence for this part. Concise prose was not retained.';
+}
+/** The wrappers supply the existing validated contract. Optional failure never
+ * changes a run, its findings/gaps, or the original contract's coverage notices.
+ */
+export function readAnswerView(run, contractView, hash) {
+    if (!Object.hasOwn(run.usage, 'answer_view'))
+        return empty('absent');
+    try {
+        need(contractView.state === 'assessed_nonexhaustive' && contractView.contract !== null);
+        const contract = contractView.contract, value = run.usage.answer_view;
+        need(obj(value));
+        const v = value;
+        need(keys(v, ['version', 'goal_sha256', 'answer_contract_sha256', 'findings_sha256', 'sections', 'omitted']) && v.version === 1);
+        need(byteLength(canonicalAnswerJson(v)) <= 8192 && byteLength(canonicalAnswerJson(run.usage)) <= 16384);
+        need(run.findings.length <= 5 && run.findings.every(f => f.qualifiers.length <= 5 && [f.claim, ...f.qualifiers].every(t => typeof t === 'string' && Array.from(t).length <= 1500)));
+        need(digest(v.goal_sha256) && v.goal_sha256 === contract.goal_sha256 && digest(v.answer_contract_sha256) && digest(v.findings_sha256));
+        need(hash(canonicalAnswerJson(run.usage.answer_contract)) === v.answer_contract_sha256 && hash(canonicalAnswerJson(run.findings)) === v.findings_sha256);
+        need(Array.isArray(v.sections) && v.sections.length <= 8 && Array.isArray(v.omitted) && v.omitted.length <= 8);
+        const ordered = [...contract.components].sort((a, b) => a.start - b.start || a.end - b.end), byId = new Map(ordered.map(c => [c.component_id, c]));
+        const sections = new Map(), omitted = new Map();
+        let total = 0;
+        for (const s of v.sections) {
+            need(obj(s) && keys(s, ['component_id', 'assertions']) && !sections.has(s.component_id));
+            const c = byId.get(s.component_id);
+            need(c && ['literal_answer', 'literal_negative_answer'].includes(c.status));
+            need(Array.isArray(s.assertions) && s.assertions.length >= 1 && s.assertions.length <= 2);
+            const expected = new Set(c.fact_refs.map(refKey)), actual = new Set();
+            for (const a of s.assertions) {
+                need(obj(a) && keys(a, ['text', 'fact_refs']) && typeof a.text === 'string' && a.text === a.text.trim() && a.text.length > 0 && !/\p{C}/u.test(a.text));
+                total += Array.from(a.text).length;
+                need(total <= 1800);
+                need(Array.isArray(a.fact_refs) && a.fact_refs.length >= 1 && a.fact_refs.length <= 10);
+                const own = new Set();
+                for (const r of a.fact_refs) {
+                    need(obj(r) && keys(r, ['finding_id', 'field', 'qualifier_ordinal', 'literal_text_sha256']));
+                    const finding = run.findings.find(f => f.id === r.finding_id);
+                    need(finding && ['claim', 'qualifier'].includes(r.field) && Number.isSafeInteger(r.qualifier_ordinal) && digest(r.literal_text_sha256));
+                    need(r.field === 'claim' ? r.qualifier_ordinal === 0 : r.qualifier_ordinal >= 1 && r.qualifier_ordinal <= finding.qualifiers.length);
+                    const literal = r.field === 'claim' ? finding.claim : finding.qualifiers[r.qualifier_ordinal - 1];
+                    need(typeof literal === 'string' && hash(literal) === r.literal_text_sha256);
+                    const key = refKey(r);
+                    need(!own.has(key));
+                    own.add(key);
+                    actual.add(key);
+                }
+            }
+            // Extra reviewed, retained fields may carry necessary context. They never
+            // substitute for a required component field or a missing qualification.
+            need([...expected].every(key => actual.has(key)));
+            sections.set(s.component_id, s.assertions);
+        }
+        for (const o of v.omitted) {
+            need(obj(o) && keys(o, ['component_id', 'reason']) && !sections.has(o.component_id) && !omitted.has(o.component_id));
+            const c = byId.get(o.component_id);
+            need(c);
+            const allowed = c.status === 'source_scoped_unknown_assessment' ? ['source_scoped_unknown'] : c.status === 'available_but_not_delivered' ? ['answer_not_delivered'] : c.status === 'unassessed' ? ['unassessed'] : ['prose_not_supplied', 'prose_review_failed', 'fact_binding_failed'];
+            need(allowed.includes(o.reason));
+            omitted.set(o.component_id, o.reason);
+        }
+        need(sections.size + omitted.size === ordered.length);
+        need(JSON.stringify([...sections.keys()]) === JSON.stringify(ordered.filter(c => sections.has(c.component_id)).map(c => c.component_id)));
+        need(JSON.stringify([...omitted.keys()]) === JSON.stringify(ordered.filter(c => omitted.has(c.component_id)).map(c => c.component_id)));
+        return { state: 'valid', view: structuredClone(v), sections: structuredClone(ordered.map(component => {
+                const reason = omitted.get(component.component_id) ?? null;
+                return { component, assertions: sections.get(component.component_id) ?? [], omission_reason: reason, notice: reason === null ? null : omission(component, reason) };
+            })) };
+    }
+    catch {
+        return empty('invalid');
+    }
+}

package/src/browser.test.mjs

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { validateCaptureUrl, isReadOnlyRequest, browserCommand } from '../browser.mjs';
+
+test('browser scope rejects executable schemes and action links', () => {
+  for (const url of ['file:///etc/passwd', 'javascript:alert(1)', 'https://x.test/logout', 'https://x.test/%64elete/123', 'https://x.test/?action=delete', 'https://user:password@x.test']) {
+    assert.throws(() => validateCaptureUrl(url));
+  }
+  assert.equal(validateCaptureUrl('https://crm.example/contacts#top').href, 'https://crm.example/contacts');
+});
+test('only read HTTP methods and GraphQL queries are accepted', () => {
+  assert.equal(isReadOnlyRequest('GET'), true);
+  assert.equal(isReadOnlyRequest('DELETE'), false);
+  assert.equal(isReadOnlyRequest('POST', '{"name":"Change me"}'), false);
+  assert.equal(isReadOnlyRequest('POST', JSON.stringify({ query: 'query Contacts { contacts { name } }' })), true);
+  assert.equal(isReadOnlyRequest('POST', JSON.stringify({ query: 'mutation DeleteContact { deleteContact(id: 1) }' })), false);
+});
+
+function browserFixture() {
+  const observations = { urls: [], closed: false, documents: [], routes: [] };
+  const frame = {};
+  let current = 'about:blank';
+  const page = {
+    goto: async url => { current = url; observations.urls.push(url); return { status: () => 200 }; },
+    url: () => current, mainFrame: () => frame,
+    waitForLoadState: async () => {},
+    evaluate: async () => ({ title: 'Customer account', text: 'Acme customer account. Renewal is on November 15. Owner is Jamie.', links: [
+      'https://crm.example/accounts/next', 'https://crm.example/logout', 'https://unrelated.example/private',
+    ], headings: ['Acme'] }),
+    locator: () => ({}), screenshot: async ({ path: output }) => fs.writeFile(output, 'test screenshot'),
+  };
+  const context = {
+    pages: () => [page], newPage: async () => page, route: async (match, callback) => observations.routes.push(callback),
+    on: () => {}, close: async () => { observations.closed = true; },
+  };
+  const playwright = { chromium: { launchPersistentContext: async (dir, options) => { observations.profile = dir; observations.options = options; return context; } } };
+  const client = { configured: true, request: async (route, { body }) => { observations.documents.push(body); return { id: 'document-' + observations.documents.length }; } };
+  return { observations, playwright, client };
+}
+
+test('capture imports provenance using isolated profile and blocks mutations', async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'opencrawl-browser-test-'));
+  const prior = process.env.OPENCRAWL_CONFIG_DIR; process.env.OPENCRAWL_CONFIG_DIR = directory;
+  try {
+    const { observations, playwright, client } = browserFixture();
+    const result = await browserCommand('capture', 'https://crm.example/accounts/123', { headless: true }, client, { playwright });
+    assert.equal(result.imported, 1);
+    assert.equal(observations.documents[0].visibility, 'private');
+    assert.equal(observations.documents[0].url, 'https://crm.example/accounts/123');
+    assert.ok(observations.profile.startsWith(path.join(directory, 'browser-profiles')));
+    assert.equal(observations.options.serviceWorkers, 'block');
+    assert.equal(observations.closed, true);
+    let aborted = false;
+    await observations.routes[0]({ request: () => ({ method: () => 'DELETE', postData: () => null }), abort: async () => { aborted = true; } });
+    assert.equal(aborted, true);
+    await assert.rejects(browserCommand('capture', 'https://other.example/page', {}, client, { playwright }), /scoped to/);
+  } finally { if (prior === undefined) delete process.env.OPENCRAWL_CONFIG_DIR; else process.env.OPENCRAWL_CONFIG_DIR = prior; await fs.rm(directory, { recursive: true, force: true }); }
+});
+
+test('bounded crawl excludes other origins and action links', async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'opencrawl-crawl-test-'));
+  const prior = process.env.OPENCRAWL_CONFIG_DIR; process.env.OPENCRAWL_CONFIG_DIR = directory;
+  try {
+    const { observations, playwright, client } = browserFixture();
+    const result = await browserCommand('crawl', 'https://crm.example/accounts/123', { 'max-pages': '2', 'path-prefix': '/accounts/' }, client, { playwright });
+    assert.equal(result.imported, 2);
+    assert.deepEqual(observations.urls, ['https://crm.example/accounts/123', 'https://crm.example/accounts/next']);
+  } finally { if (prior === undefined) delete process.env.OPENCRAWL_CONFIG_DIR; else process.env.OPENCRAWL_CONFIG_DIR = prior; await fs.rm(directory, { recursive: true, force: true }); }
+});

package/src/capture.mjs

@@ -0,0 +1,273 @@
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { configDir, createClient } from './client.mjs';
+import { allowedOptions, decimal } from './jobs.mjs';
+import { displayLine } from './display.mjs';
+
+export const CAPTURE_HELP = `OpenCrawl · capture new project conversations
+
+  opencrawl install claude-code|codex --capture
+  opencrawl capture status --provider claude-code|codex [--json]
+  opencrawl capture flush --provider claude-code|codex [--timeout 10] [--json]
+  opencrawl capture pause|resume --provider claude-code|codex
+
+The current project is the default; --project DIRECTORY selects an installed
+project explicitly. New user prompts and final assistant messages are private.
+No transcript files, old chats, tools, reasoning, or other projects are read.
+Status reads saved receipts and current server readiness. Flush explicitly
+replays only immutable queued events using server idempotence, for 1–60 seconds.
+Unknown delivery is never called indexed. Conflicts/deleted sessions stay blocked.
+Pause stops new local capture; resume captures future events, not missed history.
+Persist the owner-only OpenCrawl configuration directory in disposable sandboxes.
+Global options: --account PROFILE_ID --server URL --config-dir DIRECTORY --json
+Environment-key install: --credential-env NAME (name only; key never in settings).
+`;
+export const AGENT_OPTIONS = ['credential-env','expect-user','expect-workspace'];
+const PROVIDERS = ['claude-code','codex'];
+const MAX_STORE = 8 * 1024 * 1024, MAX_CONTENT = 64 * 1024, MAX_SESSIONS = 100, MAX_EVENTS = 20000;
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const fail = message => { throw new Error(message); };
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\u0000-\u0020\u007f]/.test(value);
+const user = value => /^usr_[a-f0-9]{32}$/.test(value || '');
+const workspace = value => /^ws_[a-f0-9]{32}$/.test(value || '');
+const same = (a,b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Explicit environment credentials require a destination and durable identity pins. */
+export async function agentClient(options, { installing = false } = {}) {
+  if (options['credential-env'] === undefined) {
+    if (options['expect-user'] !== undefined || options['expect-workspace'] !== undefined) fail('Identity pins require --credential-env.');
+    return createClient(options);
+  }
+  const name = options['credential-env'];
+  if (!/^[A-Z][A-Z0-9_]{1,79}$/.test(name) || !options.server || options.account) fail('Environment-key setup requires an explicit --server, a variable name, and no saved --account.');
+  if (!installing && (!user(options['expect-user']) || !workspace(options['expect-workspace']))) fail('Environment-key agent setup needs verified identity pins. Rerun the installer in this runtime.');
+  const token = process.env[name];
+  if (!token) fail('The configured credential environment variable is missing. No saved key was substituted.');
+  const client = await createClient({ server: options.server, token });
+  client.expectedIdentity = installing ? null : { user_id: options['expect-user'], workspace_id: options['expect-workspace'] };
+  return client;
+}
+export function bindingIdentity(client) {
+  const value = client.expectedIdentity || (client.profile && { user_id: client.profile.userId, workspace_id: client.profile.workspaceId });
+  if (!client.configured || !value || !user(value.user_id) || !workspace(value.workspace_id)) fail('Capture requires a verified saved account or an installed environment-key identity.');
+  return { server: client.baseUrl, ...value };
+}
+export async function verifyAgentIdentity(client, timeout = 2000) {
+  const result = await client.request('/api/auth/me', { timeout, maxResponseBytes: 128 * 1024 });
+  const actual = { user_id: result?.user?.id, workspace_id: result?.workspace?.id };
+  if (!user(actual.user_id) || !workspace(actual.workspace_id)) fail('The server did not return a valid account identity.');
+  const expected = client.expectedIdentity || (client.profile && { user_id: client.profile.userId, workspace_id: client.profile.workspaceId });
+  if (expected && !same(actual, expected)) fail('The credential does not match the installed user and workspace. Nothing was sent.');
+  return { server: client.baseUrl, ...actual };
+}
+async function privateDirectory(directory) {
+  await fs.mkdir(directory,{recursive:true,mode:0o700});
+  const stat=await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || typeof process.getuid==='function' && stat.uid!==process.getuid()) fail('Capture state must be in a directory owned by this user, without symbolic links.');
+  await fs.chmod(directory,0o700);
+}
+async function projectScope(client, provider, project) {
+  if (!PROVIDERS.includes(provider)) fail('Choose --provider claude-code or codex.');
+  const root=await fs.realpath(project || process.cwd());
+  if (!(await fs.stat(root)).isDirectory()) fail('Capture project must be a directory.');
+  return { ...bindingIdentity(client), provider, project: root };
+}
+async function storage(scope, action, { initialize=false }={}) {
+  const root=path.resolve(configDir());await privateDirectory(root);
+  const directory=path.join(root,'capture');await privateDirectory(directory);
+  const name=hash(JSON.stringify(scope)),file=path.join(directory,name+'.json'),lockfile=path.join(directory,name+'.lock');
+  let lock;
+  const until=Date.now()+700;
+  while (!lock) {
+    try { lock=await fs.open(lockfile,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);await lock.writeFile(String(process.pid)); }
+    catch (error) { if(error.code!=='EEXIST')throw error;if(Date.now()>=until)fail('Capture is busy or has a stale lock. Inspect capture status; remove its lock only after confirming the previous process stopped.');await new Promise(resolve=>setTimeout(resolve,25)); }
+  }
+  try {
+    let state,handle;
+    try {
+      handle=await fs.open(file,constants.O_RDONLY|constants.O_NOFOLLOW);const stat=await handle.stat();
+      if(!stat.isFile()||stat.size>MAX_STORE||stat.mode&0o077||typeof process.getuid==='function'&&stat.uid!==process.getuid())fail('Capture state must be an owner-only bounded regular file.');
+      try { state=JSON.parse(await handle.readFile('utf8')); } catch { fail('Capture state is invalid. Preserve it before repair; no events were sent.'); }
+    } catch(error) {
+      if(error.code!=='ENOENT')throw error;
+      if(!initialize)fail('Capture is not configured for this project and account. Run install TARGET --capture here.');
+      if((await fs.readdir(directory)).filter(value=>/^[a-f0-9]{64}\.json$/.test(value)).length>=64)fail('Capture is limited to 64 project/account configurations. Preserve existing state before starting another.');
+      state={version:1,scope,paused:false,sessions:[],configured_at:new Date().toISOString()};
+    } finally { await handle?.close(); }
+    validateState(state,scope);
+    const save=async()=>{
+      const encoded=JSON.stringify(state);if(Buffer.byteLength(encoded)>MAX_STORE)fail('Capture spool reached its 8 MiB limit. Flush or review queued events; no content was silently dropped.');
+      const temp=file+'.'+crypto.randomUUID()+'.tmp';let output;
+      try { output=await fs.open(temp,'wx',0o600);await output.writeFile(encoded);await output.sync();await output.close();output=null;await fs.rename(temp,file);
+        if(process.platform!=='win32'){const dir=await fs.open(directory,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);try{await dir.sync();}finally{await dir.close();}} }
+      finally {await output?.close();await fs.unlink(temp).catch(error=>{if(error.code!=='ENOENT')throw error;});}
+    };
+    return await action(state,save);
+  } finally {await lock.close();await fs.unlink(lockfile);}
+}
+function validateState(state,scope) {
+  if(state?.version!==1||!same(state.scope,scope)||typeof state.paused!=='boolean'||!Array.isArray(state.sessions)||state.sessions.length>MAX_SESSIONS)fail('Capture binding or state is invalid. No events were sent.');
+  let count=0;
+  for(const session of state.sessions) {
+    if(!identifier(session.id)||!identifier(session.remote_id)||!Array.isArray(session.events)||!Number.isSafeInteger(session.next)||session.next<0||!Array.isArray(session.turns))fail('Capture session state is invalid.');
+    const ids=new Set(),sequences=new Set();
+    for(const event of session.events) {
+      if(!identifier(event.id)||ids.has(event.id)||!Number.isSafeInteger(event.sequence)||event.sequence<0||event.sequence>=session.next||sequences.has(event.sequence)||!['user','assistant'].includes(event.role)||!['queued','acknowledged'].includes(event.state)||!/^[a-f0-9]{64}$/.test(event.hash)||!Number.isInteger(event.attempts)||event.attempts<0)fail('Capture event state is invalid.');
+      if(event.state==='queued'&&(typeof event.content!=='string'||!event.content.trim()||Buffer.byteLength(event.content)>MAX_CONTENT||hash(event.content)!==event.hash))fail('Queued capture content is invalid.');
+      ids.add(event.id);sequences.add(event.sequence);count++;
+    }
+  }
+  if(count>MAX_EVENTS)fail('Capture state exceeds its event limit.');
+}
+export async function configureCapture(client,provider,project) {
+  const scope=await projectScope(client,provider,project);
+  await storage(scope,async(state,save)=>{await save();},{initialize:true});return scope;
+}
+function safeIssue(error) {
+  const status=error?.status;
+  return ({401:'authorization_required',403:'authorization_required',409:'event_conflict',410:'session_deleted',413:'capacity_exceeded',422:'invalid_event',429:'temporarily_unavailable',507:'storage_unavailable'})[status] || 'delivery_unconfirmed';
+}
+const permanent = issue => ['event_conflict','session_deleted','invalid_event','capacity_exceeded'].includes(issue);
+export function validateCaptureReceipt(value,batchCount=null) {
+  if(!value||typeof value.document_id!=='string'||!/^doc_[a-f0-9]{32}$/.test(value.document_id)||value.lexical_ready!==true||typeof value.semantic_ready!=='boolean'||!Number.isSafeInteger(value.event_count)||value.event_count<1||!['ready','pending','unavailable'].includes(value.semantic?.status)||!Number.isSafeInteger(value.semantic?.indexed_chunks)||!Number.isSafeInteger(value.semantic?.total_chunks)||value.semantic.indexed_chunks<0||value.semantic.total_chunks<value.semantic.indexed_chunks)fail('Capture acknowledgement is invalid; queued events were preserved.');
+  if(batchCount!==null&&(!Number.isSafeInteger(value.accepted_events)||!Number.isSafeInteger(value.replayed_events)||value.accepted_events<0||value.replayed_events<0||value.accepted_events+value.replayed_events!==batchCount))fail('Capture acknowledgement did not account for this exact event batch.');
+  return {document_id:value.document_id,lexical_ready:true,semantic_ready:value.semantic_ready,semantic:{status:value.semantic.status,indexed_chunks:value.semantic.indexed_chunks,total_chunks:value.semantic.total_chunks},event_count:value.event_count,observed_at:new Date().toISOString()};
+}
+function enqueue(state,input) {
+  if(state.paused)return null;
+  const role=input.hook_event_name==='UserPromptSubmit'?'user':input.hook_event_name==='Stop'?'assistant':null;
+  if(!role||!identifier(input.session_id))fail('Unsupported capture hook or session identifier.');
+  const content=role==='user'?input.prompt:input.last_assistant_message;
+  if(typeof content!=='string'||!content.trim())return null;
+  if(Buffer.byteLength(content)>MAX_CONTENT)fail('This message exceeds the 64 KiB capture limit; it was not truncated or uploaded.');
+  if(Buffer.byteLength(JSON.stringify(content))>230*1024)fail('This message exceeds the encoded capture request limit; it was not truncated or uploaded.');
+  let session=state.sessions.find(value=>value.id===input.session_id);
+  if(!session) {
+    if(role==='assistant')return null; // Never attach an orphan Stop to a guessed turn.
+    if(state.sessions.length>=MAX_SESSIONS)fail('This capture scope reached 100 sessions. Preserve its state before starting another.');
+    session={id:input.session_id,remote_id:'occap_'+hash(state.scope.project+'\0'+input.session_id),events:[],turns:[],next:0};state.sessions.push(session);
+  }
+  if(permanent(session.issue))return session;
+  let turn;
+  if(state.scope.provider==='codex') {
+    if(!identifier(input.turn_id))fail('This Codex version did not provide a turn ID. Capture skipped; update the client and inspect /hooks.');
+    turn=session.turns.find(value=>value.id===input.turn_id);
+    if(!turn) {if(role==='assistant')return null;turn={id:input.turn_id,token:hash(input.turn_id)};session.turns.push(turn);}
+  } else if(role==='user') {
+    // prompt_id is optional in Claude versions. Without it, an unfinished
+    // identical prompt is treated as a hook replay; completed turns are new.
+    const last=session.turns.at(-1), native=identifier(input.prompt_id)?input.prompt_id:null;
+    if(native)turn=session.turns.find(value=>value.id===native);
+    else if(last&&!last.closed&&last.user_hash===hash(content))turn=last;
+    if(!turn){turn={id:native||crypto.randomUUID(),token:crypto.randomUUID(),user_hash:hash(content)};session.turns.push(turn);}
+  } else turn=session.turns.at(-1);
+  if(!turn)return null;
+  const id=hash(turn.token+'\0'+role),prior=session.events.find(value=>value.id===id);
+  if(prior) {
+    if(prior.hash!==hash(content)){session.issue='event_conflict';return session;}
+    return session;
+  }
+  if(state.sessions.reduce((count,item)=>count+item.events.length,0)>=MAX_EVENTS)fail('This capture scope reached 20,000 events. No queued event was discarded.');
+  session.events.push({id,sequence:session.next++,role,content,hash:hash(content),state:'queued',attempts:0,next_attempt_at:0});
+  if(role==='assistant')turn.closed=true;
+  return session;
+}
+async function flushOne(client,scope,sessionId,{explicit=false,timeout=1200}={}) {
+  const batch=await storage(scope,async(state,save)=>{
+    const session=state.sessions.find(value=>value.id===sessionId);
+    if(!session||state.paused||permanent(session.issue))return null;
+    let events=[];
+    for(const event of session.events.filter(event=>event.state==='queued')) {
+      if(!explicit&&(event.attempts>=3||event.next_attempt_at>Date.now()))break;
+      const next=[...events,{id:event.id,sequence:event.sequence,role:event.role,content:event.content}];
+      if(next.length>100||Buffer.byteLength(JSON.stringify({provider:scope.provider,session_id:session.remote_id,events:next}))>240*1024)break;
+      events=next;
+    }
+    if(!events.length)return null;
+    for(const item of events){const event=session.events.find(value=>value.id===item.id);event.attempts++;event.next_attempt_at=Date.now()+Math.min(60000,1000*2**Math.min(event.attempts,6));}
+    await save();
+    return {provider:scope.provider,session_id:session.remote_id,events};
+  });
+  if(!batch)return;
+  let receipt,issue;
+  try {receipt=validateCaptureReceipt(await client.request('/api/v1/sessions/events',{method:'POST',body:batch,timeout,maxResponseBytes:64*1024}),batch.events.length);}
+  catch(error){issue=safeIssue(error);}
+  await storage(scope,async(state,save)=>{
+    const session=state.sessions.find(value=>value.id===sessionId);
+    if(!session)return;
+    const events=batch.events.map(item=>session.events.find(value=>value.id===item.id&&value.sequence===item.sequence&&value.role===item.role&&value.hash===hash(item.content)));
+    if(events.some(event=>!event))fail('The queued capture changed while its request was in flight. Preserve the spool.');
+    if(receipt) {
+      if(!session.receipt||session.receipt.event_count<=receipt.event_count)session.receipt=receipt;
+      if(!permanent(session.issue))delete session.issue;
+      delete session.status_issue;session.status_verified_at=receipt.observed_at;
+      for(const event of events){event.state='acknowledged';delete event.content;}
+    } else if(events.some(event=>event.state==='queued')&&!permanent(session.issue))session.issue=issue;
+    await save();
+  });
+}
+
+function summary(state) {
+  return {configured:true,paused:state.paused,provider:state.scope.provider,project:state.scope.project,server:state.scope.server,
+    sessions:state.sessions.map(session=>({session_id:session.id,state:permanent(session.issue)?'blocked':session.events.some(event=>event.state==='queued')?'queued':session.status_issue?'verification_unavailable':session.receipt?'lexical_ready':'configured',queued_events:session.events.filter(event=>event.state==='queued').length,acknowledged_events:session.events.filter(event=>event.state==='acknowledged').length,issue:session.issue||null,current_verification:session.status_issue?{state:'unavailable',issue:session.status_issue}:session.status_verified_at?{state:'verified',observed_at:session.status_verified_at}:{state:'not_checked'},...(session.receipt?{last_acknowledgement:session.receipt}:{})}))};
+}
+export async function captureHook(input,options,client) {
+  const scope=await assertCaptureHook(input,options,client);
+  const sessionId=await storage(scope,async(state,save)=>{
+    const session=enqueue(state,input);await save();return session?.id;
+  });
+  if(sessionId) {
+    try {await verifyAgentIdentity(client,1200);await flushOne(client,scope,sessionId,{timeout:1200});}
+    catch(error){await storage(scope,async(state,save)=>{const session=state.sessions.find(value=>value.id===sessionId);if(session&&!permanent(session.issue)){session.issue=safeIssue(error);await save();}});}
+  }
+  return storage(scope,async state=>summary(state));
+}
+export async function assertCaptureHook(input,options,client) {
+  const scope=await projectScope(client,options.provider,options.project);
+  // Both the host's event cwd and executing hook must belong to this exact
+  // installed project. Never infer scope from transcript paths or file contents.
+  if(typeof input?.cwd!=='string'||await fs.realpath(input.cwd)!==scope.project||await fs.realpath(process.cwd())!==scope.project)fail('Hook project does not match the installed capture scope.');
+  await storage(scope,async()=>{}); // Require the explicit installed capture registration.
+  return scope;
+}
+export async function captureCommand(rest,options,client,{stdout=text=>process.stdout.write(text)}={}) {
+  const [command,...extra]=rest;
+  if(extra.length||!['status','flush','pause','resume'].includes(command))fail('Choose capture status, flush, pause, or resume.');
+  allowedOptions(options,['provider','project','timeout',...AGENT_OPTIONS],'capture');
+  if(options.timeout!==undefined&&command!=='flush')fail('--timeout is only supported by capture flush.');
+  const timeout=decimal(options.timeout,'timeout',1,60,10),scope=await projectScope(client,options.provider,options.project),deadline=Date.now()+timeout*1000;
+  if(command==='pause'||command==='resume') {
+    await storage(scope,async(state,save)=>{state.paused=command==='pause';await save();});
+  } else {
+    const snapshot=await storage(scope,async state=>({paused:state.paused,sessions:state.sessions.map(session=>({id:session.id,remote_id:session.remote_id,pending:session.events.some(event=>event.state==='queued'),blocked:permanent(session.issue)}))}));
+    try {await verifyAgentIdentity(client,Math.min(2000,timeout*1000));}
+    catch(error){
+      await storage(scope,async(state,save)=>{for(const session of state.sessions)session.status_issue=safeIssue(error);await save();});
+      if(command==='flush')throw error;
+      const value=await storage(scope,async state=>summary(state));
+      stdout(options.json?JSON.stringify(value,null,2)+'\n':'Current capture verification is unavailable. Previous acknowledgements are historical; check account access.\n');return 1;
+    }
+    if(command==='flush') {
+      if(snapshot.paused)fail('Capture is paused. Resume explicitly before flushing queued messages.');
+      let operations=0;
+      for(const session of snapshot.sessions) {
+        if(Date.now()>=deadline||operations>=10)break;
+        if(session.pending&&!session.blocked){await flushOne(client,scope,session.id,{explicit:true,timeout:Math.max(1,Math.min(2000,deadline-Date.now()))});operations++;}
+      }
+    } else {
+      // Only query known captured sessions, with a shared finite deadline.
+      for(const session of snapshot.sessions.slice(-20)) {
+        if(Date.now()>=deadline)break;
+        let receipt,issue;
+        try {receipt=validateCaptureReceipt(await client.request('/api/v1/sessions/events/status?'+new URLSearchParams({provider:scope.provider,session_id:session.remote_id}),{timeout:Math.max(1,Math.min(1500,deadline-Date.now())),maxResponseBytes:64*1024}));}
+        catch(error){issue=error.status===410?'session_deleted':error.status===404?'not_received':safeIssue(error);}
+        await storage(scope,async(state,save)=>{const current=state.sessions.find(value=>value.id===session.id);if(current){if(receipt){if(!current.receipt||current.receipt.event_count<=receipt.event_count)current.receipt=receipt;current.status_verified_at=receipt.observed_at;delete current.status_issue;}else{current.status_issue=issue;if(issue==='session_deleted')current.issue=issue;}await save();}});
+      }
+    }
+  }
+  const result=await storage(scope,async state=>summary(state));
+  stdout(options.json?JSON.stringify(result,null,2)+'\n':`Capture ${result.paused?'paused':'configured'}: ${displayLine(result.provider)} in ${displayLine(result.project)}\n`+result.sessions.map(session=>`${displayLine(session.session_id)}: ${session.state}; ${session.queued_events} queued, ${session.acknowledged_events} acknowledged${session.issue?' ('+session.issue+')':''}${session.current_verification.issue?' (current verification: '+session.current_verification.issue+')':''}\n`).join(''));
+  return result.sessions.some(session=>session.state==='blocked'||session.current_verification.state==='unavailable'||command==='flush'&&session.queued_events)?1:0;
+}