codehere 0.6.2 → 0.7.0

package/dist/application/use-cases/verify-claim.js

@@ -0,0 +1,274 @@
+/**
+ * v0.7 · verify-claim use case
+ *
+ * Pure function that compares what the Final Report TEXT claims against
+ * the structured reality (artifacts + steps) captured during the session.
+ *
+ * Codehere's #1 differentiator (per claim_market_position v4 + landing copy):
+ * agents round to optimism, the verifier catches the rounding.
+ *
+ * Examples this catches today:
+ *   - Report says "18 tests passed" but artifacts.tests.passed = 17 → MISMATCH
+ *   - Report says "all tests green" but artifacts.tests.failed > 0 → MISMATCH
+ *   - Report says "no files changed" but artifacts.files has entries → MISMATCH
+ *   - Report says "5 files modified" but artifacts.files.length === 3 → MISMATCH
+ *
+ * NOT a substitute for human review · this is a tripwire for the easy lies.
+ * The verifier is intentionally conservative: only flag claims it can
+ * compare against structured data. Unverifiable claims (prose-only,
+ * intent-only) pass through silently.
+ *
+ * I/O is deferred to the CLI/UI surface. This file is pure: same input,
+ * same output, no side-effects, no clock, no filesystem.
+ */
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Main verifier                                                             */
+/* ──────────────────────────────────────────────────────────────────────── */
+export function verifyClaim(input) {
+    if (!input.summary || !input.summary.trim()) {
+        return {
+            status: 'no-report',
+            findings: [
+                {
+                    severity: 'warn',
+                    kind: 'no-report',
+                    claim: '(no Final Report generated)',
+                    reality: 'nothing to verify',
+                    message: 'No Final Report available for this session. Nothing to verify against.',
+                },
+            ],
+            summary: 'No Final Report to verify.',
+        };
+    }
+    const findings = [
+        ...verifyTestsClaim(input.summary, input.artifacts),
+        ...verifyFilesClaim(input.summary, input.artifacts),
+    ];
+    const hasFail = findings.some((f) => f.severity === 'fail');
+    const hasNon = findings.length > 0;
+    const status = hasFail ? 'broken' : hasNon ? 'partial' : 'verified';
+    const summary = buildVerdictSummary(status, findings);
+    return { status, findings, summary };
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Tests claim verification                                                  */
+/* ──────────────────────────────────────────────────────────────────────── */
+/**
+ * Detect tests-related claims in the report and cross-check against
+ * artifacts.tests. Catches "X tests passed" exaggeration AND "all tests
+ * green" when failed > 0.
+ */
+export function verifyTestsClaim(summary, artifacts) {
+    const out = [];
+    const lower = summary.toLowerCase();
+    const tests = artifacts?.tests;
+    // Extract numeric "X tests passed" / "X passed" / "X of Y" patterns.
+    // We deliberately keep the regex tight to avoid false positives on prose
+    // like "this is the 5th attempt".
+    const countClaim = matchTestCountClaim(summary);
+    if (countClaim !== null) {
+        if (!tests) {
+            // The agent claimed a test count but the adapter recorded no test
+            // artifact. Suspicious but not necessarily wrong (the adapter may not
+            // capture test results yet). Flag as warn.
+            out.push({
+                severity: 'warn',
+                kind: 'tests',
+                claim: countClaim.quote,
+                reality: 'no test artifact captured',
+                message: `Final Report claims "${countClaim.quote}" but no test results were recorded by the agent.`,
+            });
+        }
+        else {
+            const actualPassed = tests.passed;
+            const actualFailed = tests.failed;
+            const actualTotal = actualPassed + actualFailed;
+            // Per codex Round 1: "X of Y tests passed" must check BOTH numbers.
+            // A claim like "18 of 18 tests passed" with reality {passed: 17, failed: 1}
+            // has matching total (18 ran) but mismatched passed (17 ≠ 18) · we flag.
+            if (countClaim.passedCount !== undefined && countClaim.passedCount !== actualPassed) {
+                out.push({
+                    severity: 'fail',
+                    kind: 'tests',
+                    claim: countClaim.quote,
+                    reality: `${actualPassed} passed, ${actualFailed} failed (${actualTotal} ran)`,
+                    message: `Final Report claims ${countClaim.passedCount} tests passed but reality is ${actualPassed} passed and ${actualFailed} failed.`,
+                });
+            }
+            if (countClaim.totalCount !== undefined && countClaim.totalCount !== actualTotal) {
+                out.push({
+                    severity: 'fail',
+                    kind: 'tests',
+                    claim: countClaim.quote,
+                    reality: `${actualTotal} ran (${actualPassed} passed, ${actualFailed} failed)`,
+                    message: `Final Report claims ${countClaim.totalCount} tests ran but reality is ${actualTotal} (${actualPassed} passed, ${actualFailed} failed).`,
+                });
+            }
+        }
+    }
+    // Universal "all tests pass" / "all green" claims. Requires explicit
+    // universal qualifier ("all", "every", "each", "no failures") so that
+    // count claims like "18 tests passed" don't also match — count
+    // mismatches are caught above by matchTestCountClaim.
+    const claimsAllPass = /\b(?:all|every|each)\s+tests?\s+(?:pass(?:ed|ing)?|green|succeed(?:ed)?)\b/i.test(lower) ||
+        /\btests?\s+all\s+(?:pass(?:ed|ing)?|green)\b/i.test(lower) ||
+        /\ball\s+(?:tests?\s+)?(?:green|passing)\b/i.test(lower) ||
+        /\bno\s+(?:test\s+)?(?:failures|regressions?)\b/i.test(lower);
+    if (claimsAllPass && tests && tests.failed > 0) {
+        out.push({
+            severity: 'fail',
+            kind: 'tests',
+            claim: 'all tests pass / green / no failures',
+            reality: `${tests.failed} test${tests.failed === 1 ? '' : 's'} failed`,
+            message: `Final Report claims all tests pass but ${tests.failed} actually failed.`,
+        });
+    }
+    return out;
+}
+/**
+ * Parse the first explicit test-count claim from the summary.
+ * Returns null if no specific count is mentioned.
+ *
+ * Patterns matched (a single claim can assert BOTH a passed-count AND a total):
+ *   "18 tests passed"          → { passedCount: 18 }
+ *   "18 of 18 tests passed"    → { passedCount: 18, totalCount: 18 }
+ *   "passed 18 tests"          → { passedCount: 18 }
+ *   "ran 25 tests"             → { totalCount: 25 }
+ *
+ * Per codex Round 1 review on commit 8481412: "X of Y tests passed" must
+ * check BOTH numbers, not just total, otherwise "18 of 18 passed" with
+ * reality {passed: 17, failed: 1} slips through (total still equals 18).
+ */
+function matchTestCountClaim(summary) {
+    // "X of Y tests passed/green/succeeded" → X is passed AND Y is total.
+    // Per codex Round 2: require explicit pass-context to populate passedCount
+    // so negative phrasing ("1 of 3 tests failed") doesn't become a false-positive
+    // "1 passed" claim.
+    const ofPassMatch = summary.match(/\b(\d+)\s+(?:of|\/)\s+(\d+)\s+tests?\s+(?:pass(?:ed|ing)?|green|succeed(?:ed)?)\b/i);
+    if (ofPassMatch) {
+        return {
+            quote: ofPassMatch[0],
+            passedCount: parseInt(ofPassMatch[1], 10),
+            totalCount: parseInt(ofPassMatch[2], 10),
+        };
+    }
+    // "X of Y tests" without pass-context → only Y is a total-count claim. X
+    // is ambient (failed / ran / partial / etc) and we don't pretend to know.
+    // Per codex Round 3: this branch preserves total-count detection for
+    // bare X-of-Y phrasing so the verifier still catches mismatched totals.
+    const ofMatch = summary.match(/\b(\d+)\s+(?:of|\/)\s+(\d+)\s+tests?\b/i);
+    if (ofMatch) {
+        return {
+            quote: ofMatch[0],
+            totalCount: parseInt(ofMatch[2], 10),
+        };
+    }
+    // "X tests passed" / "X tests pass"
+    const passedMatch = summary.match(/\b(\d+)\s+tests?\s+(?:pass(?:ed|ing)?|green)\b/i);
+    if (passedMatch) {
+        return { quote: passedMatch[0], passedCount: parseInt(passedMatch[1], 10) };
+    }
+    // "passed X tests" / "ran X tests"
+    const reverseMatch = summary.match(/\b(?:pass(?:ed)?|ran)\s+(\d+)\s+tests?\b/i);
+    if (reverseMatch) {
+        const isPass = /pass/i.test(reverseMatch[0]);
+        return {
+            quote: reverseMatch[0],
+            passedCount: isPass ? parseInt(reverseMatch[1], 10) : undefined,
+            totalCount: isPass ? undefined : parseInt(reverseMatch[1], 10),
+        };
+    }
+    return null;
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Files claim verification                                                  */
+/* ──────────────────────────────────────────────────────────────────────── */
+/**
+ * Detect files-related claims in the report and cross-check against
+ * artifacts.files. Catches "no files changed" when files DID change,
+ * and "X files changed" count mismatches.
+ */
+export function verifyFilesClaim(summary, artifacts) {
+    const out = [];
+    // Claim: "no files were changed" / "no files modified" / similar
+    const claimsNoFiles = /\bno\s+files?\s+(were\s+)?(changed|modified|touched|written|created)\b/i.test(summary) ||
+        /\bsession\s+was\s+read-only\b/i.test(summary) ||
+        /\bnothing\s+(was\s+)?(written|changed|modified)\b/i.test(summary);
+    // Claim: "X files changed" / "modified X files" / "wrote X files"
+    const countClaim = matchFilesCountClaim(summary);
+    // Per codex Round 1: if the adapter didn't capture file artifacts at all,
+    // we can't verify file claims · warn rather than fail. Mirrors the tests
+    // path (missing tests artifact → warn). Distinguishes from `files: []`
+    // which is a valid "explicitly captured zero files" reality.
+    if (artifacts?.files === undefined) {
+        if (claimsNoFiles) {
+            out.push({
+                severity: 'warn',
+                kind: 'files',
+                claim: 'no files changed / read-only',
+                reality: 'no file artifact captured',
+                message: 'Final Report claims no files changed but no file results were recorded by the agent.',
+            });
+        }
+        if (countClaim !== null) {
+            out.push({
+                severity: 'warn',
+                kind: 'files',
+                claim: countClaim.quote,
+                reality: 'no file artifact captured',
+                message: `Final Report claims "${countClaim.quote}" but no file results were recorded by the agent.`,
+            });
+        }
+        return out;
+    }
+    const actualCount = artifacts.files.length;
+    if (claimsNoFiles && actualCount > 0) {
+        out.push({
+            severity: 'fail',
+            kind: 'files',
+            claim: 'no files changed / read-only',
+            reality: `${actualCount} file${actualCount === 1 ? '' : 's'} changed`,
+            message: `Final Report claims no files were changed but ${actualCount} actually were.`,
+        });
+    }
+    if (countClaim !== null && countClaim.value !== actualCount) {
+        out.push({
+            severity: 'fail',
+            kind: 'files',
+            claim: countClaim.quote,
+            reality: `${actualCount} file${actualCount === 1 ? '' : 's'} changed`,
+            message: `Final Report claims ${countClaim.value} file${countClaim.value === 1 ? '' : 's'} were changed but ${actualCount} actually were.`,
+        });
+    }
+    return out;
+}
+function matchFilesCountClaim(summary) {
+    // "X files changed" / "X files modified" / "X files were touched"
+    const m1 = summary.match(/\b(\d+)\s+files?\s+(were\s+)?(?:changed|modified|touched|written|created|added|updated)\b/i);
+    if (m1)
+        return { quote: m1[0], value: parseInt(m1[1], 10) };
+    // "changed X files" / "modified X files"
+    const m2 = summary.match(/\b(?:changed|modified|touched|wrote|created|added|updated)\s+(\d+)\s+files?\b/i);
+    if (m2)
+        return { quote: m2[0], value: parseInt(m2[1], 10) };
+    return null;
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Verdict summary                                                           */
+/* ──────────────────────────────────────────────────────────────────────── */
+function buildVerdictSummary(status, findings) {
+    if (status === 'verified')
+        return 'Claims match the recorded reality. No gaps detected.';
+    if (status === 'no-report')
+        return 'No Final Report to verify.';
+    const failCount = findings.filter((f) => f.severity === 'fail').length;
+    const warnCount = findings.filter((f) => f.severity === 'warn').length;
+    if (failCount > 0 && warnCount > 0) {
+        return `${failCount} claim${failCount === 1 ? '' : 's'} contradict the recorded reality, plus ${warnCount} unverifiable claim${warnCount === 1 ? '' : 's'}.`;
+    }
+    if (failCount > 0) {
+        return `${failCount} claim${failCount === 1 ? '' : 's'} contradict the recorded reality.`;
+    }
+    return `${warnCount} unverifiable claim${warnCount === 1 ? '' : 's'}.`;
+}
+//# sourceMappingURL=verify-claim.js.map

package/dist/application/use-cases/write-pass.js

@@ -0,0 +1,277 @@
+/**
+ * Write-Pass (W-PASS) primitive · v0.9 S6 · the WRITE counterpart to S1's
+ * context-source READ primitive.
+ *
+ * Demo v12 lines 2030-2050. Every time an agent wants to make a stateful
+ * call to a third-party tool (Linear status update, GitHub PR comment,
+ * Notion page edit, etc.) it emits a `WritePassIntent`. Codehere mediates:
+ *
+ *   1. Intent       · agent → codehere · {target, method, payload, reason}
+ *   2. Approval     · user → codehere · approve / edit / cancel
+ *   3. Mediated send · codehere → third-party · captures response
+ *   4. Audit        · chained entry for each step
+ *
+ * Why this primitive exists: AI 2027 forecasts agentic AI doing autonomous
+ * multi-tool writes by mid-2027. Without W-PASS we either (a) hand the
+ * agent raw API keys + tokens — every write is invisible to the human,
+ * audit-impossible — or (b) ban writes entirely and lose half the value.
+ * W-PASS is the middle path: writes happen, but every payload is human-
+ * mediated and chain-recorded.
+ *
+ * This file is PURE LOGIC · no fs, no fetch. CLI + HTTP + UI wrap it.
+ */
+import { randomUUID, createHash } from 'crypto';
+/** Errors raised by W-PASS primitive functions. */
+export class WritePassError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[w-pass] ${code}: ${message}`);
+        this.code = code;
+    }
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Pure helpers                                                              */
+/* ──────────────────────────────────────────────────────────────────────── */
+/** Generate a fresh W-PASS id · stable across the intent → decision → send cycle. */
+export function newPassId() {
+    return randomUUID();
+}
+/** Allowed URL schemes for W-PASS targets · matches context-source's namespace
+ *  (we want symmetry: read via context-source, write via write-pass, same identifiers). */
+const ALLOWED_SCHEMES = new Set(['linear', 'github', 'figma', 'drawio', 'notion']);
+/**
+ * Validate that an intent is well-formed before showing it to the user.
+ * Refuse anything we can't audit (unknown scheme, unsupported method, empty
+ * reason, etc.). Throws WritePassError with a precise code.
+ */
+export function validateIntent(intent) {
+    if (typeof intent !== 'object' || intent === null) {
+        throw new WritePassError('invalid_intent', 'intent must be an object');
+    }
+    const it = intent;
+    if (typeof it.id !== 'string' || it.id.length === 0) {
+        throw new WritePassError('invalid_intent', 'id required');
+    }
+    if (typeof it.sessionId !== 'string' || it.sessionId.length === 0) {
+        throw new WritePassError('invalid_intent', 'sessionId required');
+    }
+    if (typeof it.target !== 'string' || it.target.length === 0) {
+        throw new WritePassError('invalid_intent', 'target required');
+    }
+    const schemeMatch = it.target.match(/^([a-z][a-z0-9+.-]*):\/\//);
+    if (!schemeMatch) {
+        throw new WritePassError('invalid_intent', `target must be a URL with a scheme · got "${it.target}"`);
+    }
+    if (!ALLOWED_SCHEMES.has(schemeMatch[1])) {
+        throw new WritePassError('unsupported_target', `scheme "${schemeMatch[1]}" not allowed · supported: ${[...ALLOWED_SCHEMES].sort().join(', ')}`);
+    }
+    if (typeof it.method !== 'string') {
+        throw new WritePassError('invalid_intent', 'method required');
+    }
+    const m = it.method.toUpperCase();
+    if (m !== 'POST' && m !== 'PUT' && m !== 'PATCH' && m !== 'DELETE') {
+        throw new WritePassError('unsupported_method', `method "${it.method}" not allowed for W-PASS (use context-source for GET)`);
+    }
+    if (typeof it.reason !== 'string' || it.reason.trim().length === 0) {
+        throw new WritePassError('invalid_intent', 'reason required · must be a non-empty one-line "why"');
+    }
+    if (typeof it.emittedAt !== 'number' || !Number.isFinite(it.emittedAt)) {
+        throw new WritePassError('invalid_intent', 'emittedAt required (epoch ms)');
+    }
+    // payload may be any JSON value · we don't constrain shape here · the user
+    // sees it verbatim and decides.
+    return {
+        id: it.id,
+        sessionId: it.sessionId,
+        target: it.target,
+        method: m,
+        payload: it.payload,
+        reason: it.reason,
+        emittedAt: it.emittedAt,
+        emittedBy: typeof it.emittedBy === 'string' ? it.emittedBy : undefined,
+    };
+}
+/** Validate a decision belongs to its intent and carries the fields required for its kind. */
+export function validateDecision(decision, intent) {
+    if (typeof decision !== 'object' || decision === null) {
+        throw new WritePassError('invalid_decision', 'decision must be an object');
+    }
+    const d = decision;
+    if (d.passId !== intent.id) {
+        throw new WritePassError('invalid_decision', `decision.passId "${d.passId}" doesn't match intent.id "${intent.id}"`);
+    }
+    const kind = d.kind;
+    if (kind !== 'approve' && kind !== 'edit' && kind !== 'cancel') {
+        throw new WritePassError('invalid_decision', `kind must be approve | edit | cancel · got "${d.kind}"`);
+    }
+    if (kind === 'edit' && d.editedPayload === undefined) {
+        throw new WritePassError('invalid_decision', 'edit requires editedPayload');
+    }
+    if (typeof d.decidedAt !== 'number' || !Number.isFinite(d.decidedAt)) {
+        throw new WritePassError('invalid_decision', 'decidedAt required (epoch ms)');
+    }
+    return {
+        passId: intent.id,
+        kind,
+        editedPayload: kind === 'edit' ? d.editedPayload : undefined,
+        note: typeof d.note === 'string' ? d.note : undefined,
+        decidedAt: d.decidedAt,
+    };
+}
+/**
+ * Apply a decision to an intent and produce the next status.
+ * Pure · no I/O. The caller (daemon route) does the network call and produces
+ * a `WritePassResponse` which then transitions 'approved'/'edited' → 'sent'.
+ */
+export function applyDecision(intent, decision) {
+    if (decision.kind === 'cancel') {
+        return { kind: 'cancelled', intent, decision };
+    }
+    if (decision.kind === 'edit') {
+        return { kind: 'edited', intent, decision, effectivePayload: decision.editedPayload };
+    }
+    return { kind: 'approved', intent, decision };
+}
+/**
+ * After codehere does the mediated send, record the response and transition
+ * to 'sent' (2xx/3xx) or 'failed' (everything else).
+ */
+export function applyResponse(status, response) {
+    const effectivePayload = status.kind === 'edited' ? status.effectivePayload : status.intent.payload;
+    const ok = response.status >= 200 && response.status < 400;
+    return ok
+        ? { kind: 'sent', intent: status.intent, decision: status.decision, effectivePayload, response }
+        : { kind: 'failed', intent: status.intent, decision: status.decision, effectivePayload, response };
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Audit-line shaping                                                        */
+/* ──────────────────────────────────────────────────────────────────────── */
+/**
+ * Deterministic JSON for hashing into the audit chain. Same canonical-form
+ * rules as thread-export's canonicalize · keys sorted, undefined dropped,
+ * non-finite numbers refused. We want two machines that re-serialize the
+ * same intent to compute the same hash.
+ */
+export function canonicalizeForAudit(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`cannot canonicalize non-finite number: ${value}`);
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalizeForAudit).join(',') + ']';
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const parts = keys
+            .filter((k) => obj[k] !== undefined)
+            .map((k) => JSON.stringify(k) + ':' + canonicalizeForAudit(obj[k]));
+        return '{' + parts.join(',') + '}';
+    }
+    if (value === undefined)
+        return 'null';
+    throw new Error(`cannot canonicalize type: ${typeof value}`);
+}
+/** SHA-256 hash of canonicalize(value) · 16-char hex prefix for inline display. */
+export function shortContentHash(value) {
+    return createHash('sha256').update(canonicalizeForAudit(value)).digest('hex').slice(0, 16);
+}
+/** Render a status transition as an audit-chain entry. Caller appends it. */
+export function statusToAuditLine(s) {
+    const sessionId = s.intent.sessionId;
+    const timestamp = new Date('response' in s ? s.response.receivedAt : 'decision' in s ? s.decision.decidedAt : s.intent.emittedAt).toISOString();
+    const baseSummary = {
+        passId: s.intent.id,
+        target: s.intent.target,
+        method: s.intent.method,
+        reason: s.intent.reason,
+        payloadHash: shortContentHash(s.intent.payload),
+    };
+    switch (s.kind) {
+        case 'pending':
+            return {
+                toolName: 'WritePass.intent',
+                toolInput: canonicalizeForAudit(baseSummary),
+                riskScore: 0,
+                blocked: false,
+                findings: 0,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+        case 'approved':
+            return {
+                toolName: 'WritePass.approved',
+                toolInput: canonicalizeForAudit({ ...baseSummary, note: s.decision.note }),
+                riskScore: 0,
+                blocked: false,
+                findings: 0,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+        case 'edited':
+            return {
+                toolName: 'WritePass.edited',
+                toolInput: canonicalizeForAudit({
+                    ...baseSummary,
+                    editedPayloadHash: shortContentHash(s.effectivePayload),
+                    note: s.decision.note,
+                }),
+                riskScore: 0,
+                blocked: false,
+                findings: 0,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+        case 'cancelled':
+            return {
+                toolName: 'WritePass.cancelled',
+                toolInput: canonicalizeForAudit({ ...baseSummary, note: s.decision.note }),
+                riskScore: 0,
+                blocked: true,
+                findings: 0,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+        case 'sent':
+            return {
+                toolName: 'WritePass.sent',
+                toolInput: canonicalizeForAudit({
+                    ...baseSummary,
+                    effectivePayloadHash: shortContentHash(s.effectivePayload),
+                    responseStatus: s.response.status,
+                }),
+                riskScore: 0,
+                blocked: false,
+                findings: 0,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+        case 'failed':
+            return {
+                toolName: 'WritePass.failed',
+                toolInput: canonicalizeForAudit({
+                    ...baseSummary,
+                    effectivePayloadHash: shortContentHash(s.effectivePayload),
+                    responseStatus: s.response.status,
+                    error: s.response.error,
+                }),
+                riskScore: 0,
+                blocked: false,
+                findings: 1,
+                criticalFindings: 0,
+                sessionId,
+                timestamp,
+            };
+    }
+}
+//# sourceMappingURL=write-pass.js.map