@itaila/archetype 0.3.30

package/dist/observability/render-run-markdown.js

@@ -0,0 +1,231 @@
+/**
+ * Render a benchmark run as a single turn-by-turn TURNS.md-style report.
+ *
+ * Purpose: the bug is almost always in the prompt the model received.
+ * Reading turn-by-turn should take ≤30 seconds and surface:
+ *   - the system prompt (deduped — appears once if constant across turns)
+ *   - per-turn input (as the model saw it)
+ *   - per-turn assistant emission (message verbatim + action summary)
+ *   - any errors (unknown action, schema fail) flagged inline
+ *   - a fingerprint header (turn count, action mix, errors)
+ *
+ * This module is pure: it takes structured data and returns a string.
+ * Path discovery (where traces live, where errors.jsonl sits, how to
+ * read a score) belongs to the host CLI — archetype/observability ships
+ * a renderer, not a file-system reader. See `parseTracePacket` if you
+ * want a quick way to hydrate traces from JSON files.
+ *
+ * Works in browsers and Node (no fs use here).
+ */
+/**
+ * Render the final markdown. Returns the full TURNS.md body as a string.
+ * Host writes it wherever it wants.
+ */
+export function renderRunMarkdown(input) {
+    const traces = input.traces;
+    if (traces.length === 0) {
+        return `# Turn review — ${input.runId}\n\n(no turn traces)\n`;
+    }
+    const inputCharBudget = input.inputCharBudget ?? 1200;
+    const errors = input.errors ?? [];
+    const score = input.score ?? null;
+    // System prompt dedup — if identical across all turns, show once.
+    const systemPrompts = new Set(traces.map((t) => t.systemPrompt ?? ''));
+    const systemPromptConstant = systemPrompts.size === 1;
+    // Action fingerprint from the last trace's history (has the most data).
+    const lastHistory = traces[traces.length - 1].history ?? [];
+    const fingerprint = computeFingerprint(lastHistory);
+    const out = [];
+    out.push(`# Turn review — ${input.runId}`);
+    out.push('');
+    out.push(`- benchmark: ${input.metadata?.benchmarkId ?? '?'}`);
+    out.push(`- artifactName: ${input.metadata?.artifactName ?? '?'}`);
+    out.push(`- status: ${input.metadata?.status ?? '?'}`);
+    out.push(`- turn traces: ${traces.length}`);
+    out.push(`- assistant turns (from history): ${fingerprint.assistantTurns}`);
+    out.push(`- single-action turns: ${fingerprint.singleActionTurns}`);
+    out.push(`- multi-action turns: ${fingerprint.multiActionTurns}`);
+    out.push(`- zero-action turns: ${fingerprint.zeroActionTurns}`);
+    out.push(`- editFile shape: single=${fingerprint.singleEditCalls}, multi=${fingerprint.multiEditCalls}`);
+    out.push(`- action mix: ${JSON.stringify(fingerprint.actionCounts)}`);
+    if (score) {
+        out.push(`- customer score: **${score.score ?? '?'}** (${score.verdict ?? '?'}, ${score.ship ?? '?'})`);
+    }
+    const errorNotes = errors
+        .filter((e) => !!e)
+        .map((e) => `turn ${e.turn ?? '?'}: ${e.reason ?? ''}`);
+    if (errorNotes.length > 0) {
+        out.push('');
+        out.push(`## ⚠️ Errors (${errorNotes.length})`);
+        for (const n of errorNotes)
+            out.push(`- ${n}`);
+    }
+    out.push('');
+    if (systemPromptConstant) {
+        out.push('## System prompt (constant across turns)');
+    }
+    else {
+        out.push(`## System prompt — changed ${systemPrompts.size} times across turns (first shown below; see prompt-traces/ for each variant)`);
+    }
+    out.push('');
+    out.push('```');
+    out.push(traces[0].systemPrompt ?? '(empty)');
+    out.push('```');
+    out.push('');
+    // Per-turn — walk the latest trace's history (contains the full run).
+    out.push('## Turn-by-turn');
+    out.push('');
+    let turnNum = 0;
+    for (const h of lastHistory) {
+        const content = typeof h.content === 'string' ? h.content : JSON.stringify(h.content);
+        if (h.role === 'user') {
+            turnNum += 1;
+            out.push(`### Turn ${turnNum} input`);
+            out.push('');
+            out.push('```');
+            out.push(clip(content, inputCharBudget));
+            out.push('```');
+            out.push('');
+        }
+        else if (h.role === 'assistant') {
+            renderAssistantTurn(out, turnNum, content);
+        }
+    }
+    // Capture the latest trace's `message` as the next turn's input (not
+    // yet in history) — gives visibility into whatever the loop is about
+    // to send when it stopped.
+    const latestInput = traces[traces.length - 1].message;
+    if (latestInput) {
+        turnNum += 1;
+        out.push(`### Turn ${turnNum} input (latest — model may have responded after this was captured)`);
+        out.push('');
+        out.push('```');
+        out.push(clip(latestInput, inputCharBudget));
+        out.push('```');
+        out.push('');
+    }
+    return out.join('\n');
+}
+function computeFingerprint(history) {
+    const actionCounts = {};
+    let assistantTurns = 0;
+    let multiActionTurns = 0;
+    let zeroActionTurns = 0;
+    let multiEditCalls = 0;
+    let singleEditCalls = 0;
+    for (const h of history) {
+        if (h.role !== 'assistant')
+            continue;
+        const payload = tryParseAssistantPayload(typeof h.content === 'string' ? h.content : '');
+        if (!payload)
+            continue;
+        assistantTurns += 1;
+        const actions = payload.actions ?? [];
+        if (actions.length === 0)
+            zeroActionTurns += 1;
+        else if (actions.length > 1)
+            multiActionTurns += 1;
+        for (const a of actions) {
+            const nm = a.name ?? '?';
+            actionCounts[nm] = (actionCounts[nm] ?? 0) + 1;
+            if (nm === 'editFile') {
+                const edits = (a.params ?? {}).edits;
+                if (Array.isArray(edits)) {
+                    if (edits.length > 1)
+                        multiEditCalls += 1;
+                    else
+                        singleEditCalls += 1;
+                }
+            }
+        }
+    }
+    const singleActionTurns = assistantTurns - multiActionTurns - zeroActionTurns;
+    return {
+        assistantTurns,
+        singleActionTurns,
+        multiActionTurns,
+        zeroActionTurns,
+        multiEditCalls,
+        singleEditCalls,
+        actionCounts,
+    };
+}
+function renderAssistantTurn(out, turnNum, content) {
+    const payload = tryParseAssistantPayload(content);
+    if (payload) {
+        out.push(`**Turn ${turnNum} assistant** — ${(payload.actions ?? []).length} action(s)`);
+        if (payload.message && payload.message.trim()) {
+            out.push('');
+            out.push('> ' + payload.message.replace(/\n/g, '\n> '));
+        }
+        if (payload.actions && payload.actions.length > 0) {
+            out.push('');
+            for (const a of payload.actions) {
+                out.push(`- \`${summarizeAction(a)}\``);
+            }
+        }
+        if (payload.diagnostics && payload.diagnostics.length > 0) {
+            out.push('');
+            out.push('_diagnostics:_');
+            for (const d of payload.diagnostics)
+                out.push(`- ⚠️ ${d}`);
+        }
+        out.push('');
+    }
+    else {
+        out.push(`**Turn ${turnNum} assistant** — (unparseable)`);
+        out.push('```');
+        out.push(content.slice(0, 600));
+        out.push('```');
+        out.push('');
+    }
+}
+/**
+ * Extract an AssistantPayload from a raw assistant-message string.
+ * Handles the common case of prose before a JSON object — everything
+ * before the first `{` is ignored.
+ */
+export function tryParseAssistantPayload(content) {
+    if (typeof content !== 'string')
+        return null;
+    const i = content.indexOf('{');
+    if (i < 0)
+        return null;
+    try {
+        return JSON.parse(content.slice(i));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compact one-line summary of an action: keeps reference keys (path,
+ * pattern, id, name, outcome, …) visible, drops bodies (content, stdout,
+ * image payloads). Used in the per-turn action list for fast scanning.
+ */
+export function summarizeAction(a) {
+    const name = a.name ?? '?';
+    const params = a.params ?? {};
+    const keep = {};
+    for (const refKey of ['path', 'pattern', 'pathGlob', 'id', 'entity', 'name', 'outcome', 'summary', 'label']) {
+        if (refKey in params && params[refKey] !== undefined)
+            keep[refKey] = params[refKey];
+    }
+    if (name === 'editFile') {
+        const edits = params.edits;
+        keep.editCount = Array.isArray(edits) ? edits.length : (params.oldText !== undefined ? 1 : 0);
+    }
+    if (name === 'writeFile') {
+        const content = params.content;
+        if (typeof content === 'string')
+            keep.bytes = Buffer.byteLength(content, 'utf8');
+    }
+    const kvs = Object.entries(keep)
+        .map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 80)}`)
+        .join(', ');
+    return kvs ? `${name}  {${kvs}}` : name;
+}
+function clip(s, limit) {
+    return s.length > limit ? s.slice(0, limit) + `\n… [+${s.length - limit} chars]` : s;
+}
+//# sourceMappingURL=render-run-markdown.js.map

package/dist/observability/render-run-markdown.js.map

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

package/dist/observability/turn-reporter.d.ts

@@ -0,0 +1,20 @@
+import type { LoopTurnRecord } from '../managed/autonomous-loop.js';
+export interface TurnReporterOptions {
+    /** Directory to write errors.jsonl + diagnostics.md into. */
+    runRoot: string;
+    /**
+     * Whether to print stderr callouts alongside file writes. Default true.
+     * Set false for batch jobs where stderr is not human-watched.
+     */
+    emitStderr?: boolean;
+}
+export interface TurnReporterHook {
+    /** Wire this into `runAutonomousLoop({ hooks: { onTurn } })`. */
+    onTurn: (record: LoopTurnRecord) => void;
+}
+/**
+ * Build an onTurn reporter hook. One instance per benchmark run; safe
+ * to share across peers/delegates (writes append).
+ */
+export declare function createTurnReporter(options: TurnReporterOptions): TurnReporterHook;
+//# sourceMappingURL=turn-reporter.d.ts.map

package/dist/observability/turn-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-reporter.d.ts","sourceRoot":"","sources":["../../src/observability/turn-reporter.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEnE,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAA;CACzC;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAejF"}

package/dist/observability/turn-reporter.js

@@ -0,0 +1,106 @@
+/**
+ * Turn reporter — persists per-turn errors + builder diagnostics so
+ * every autonomous-loop consumer gets the same observability pattern
+ * without inlining the hook logic.
+ *
+ * What it writes (per turn, when there's something to report):
+ *   runRoot/errors.jsonl       one JSON-per-line entry for each
+ *                              validation error or provider error
+ *   runRoot/diagnostics.md     one markdown line per diagnostic the
+ *                              builder emitted through its
+ *                              `diagnostics[]` response field
+ *
+ * What it prints (stderr, one line per event, with ANSI prefix):
+ *   [ARCHETYPE ERROR] turn N: unknown_action "doesNotExist" — ...
+ *   [BUILDER DIAGNOSTIC] turn N: <diagnostic>
+ *
+ * The "fail loudly" policy lives here: silent failures mask broken
+ * prompt/contract/context bugs. Every call-site error surfaces in both
+ * the durable jsonl + a visible stderr callout. Retries continue
+ * regardless — this module is telemetry, not flow control.
+ *
+ * Node-only (writes to local filesystem).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Build an onTurn reporter hook. One instance per benchmark run; safe
+ * to share across peers/delegates (writes append).
+ */
+export function createTurnReporter(options) {
+    const { runRoot } = options;
+    const emitStderr = options.emitStderr ?? true;
+    const errFile = path.join(runRoot, 'errors.jsonl');
+    const diagFile = path.join(runRoot, 'diagnostics.md');
+    fs.mkdirSync(runRoot, { recursive: true });
+    return {
+        onTurn: (record) => {
+            persistErrors(record, errFile, emitStderr);
+            persistDiagnostics(record, diagFile, emitStderr);
+        },
+    };
+}
+function persistErrors(record, errFile, emitStderr) {
+    const lines = [];
+    for (const ve of record.validationErrors ?? []) {
+        lines.push({
+            turn: record.turn,
+            kind: ve.status,
+            action: ve.name,
+            reason: ve.error ?? `action "${ve.name}" rejected by contract (${ve.status})`,
+        });
+    }
+    if (record.providerError) {
+        lines.push({
+            turn: record.turn,
+            kind: 'provider_error',
+            action: null,
+            reason: record.providerError,
+        });
+    }
+    if (lines.length === 0)
+        return;
+    try {
+        fs.appendFileSync(errFile, lines.map(l => JSON.stringify(l)).join('\n') + '\n');
+    }
+    catch (err) {
+        console.error(`[errors.jsonl] write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (emitStderr) {
+        for (const rec of lines) {
+            const actionSuffix = rec.action ? ` "${rec.action}"` : '';
+            console.error(`\x1b[31m[ARCHETYPE ERROR]\x1b[0m turn ${rec.turn}: ${rec.kind}${actionSuffix} — ${rec.reason}`);
+        }
+    }
+}
+function persistDiagnostics(record, diagFile, emitStderr) {
+    if (!record.rawAssistantResponse)
+        return;
+    const i = record.rawAssistantResponse.indexOf('{');
+    if (i < 0)
+        return;
+    let parsed = null;
+    try {
+        parsed = JSON.parse(record.rawAssistantResponse.slice(i));
+    }
+    catch {
+        return; // diagnostics are optional — parse failures are not errors
+    }
+    const raw = Array.isArray(parsed?.diagnostics) ? parsed.diagnostics : [];
+    const diags = raw.filter((d) => typeof d === 'string' && d.trim().length > 0);
+    if (diags.length === 0)
+        return;
+    try {
+        const entries = diags.map((d) => `- turn ${record.turn}: ${d}`).join('\n') + '\n';
+        fs.appendFileSync(diagFile, entries);
+    }
+    catch (err) {
+        console.error(`[diagnostics.md] write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (emitStderr) {
+        for (const d of diags) {
+            console.error(`\x1b[33m[BUILDER DIAGNOSTIC]\x1b[0m turn ${record.turn}: ${d}`);
+        }
+    }
+}
+//# sourceMappingURL=turn-reporter.js.map

package/dist/observability/turn-reporter.js.map

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

package/dist/persona.d.ts

@@ -0,0 +1,49 @@
+import type { PersonaConfig, ChatInput, ChatResult, GreetingInput, PromptedTurnInput, RetrospectInput, RetrospectResult } from './types.js';
+import type { AuditInput, AuditResult } from './audit/types.js';
+/**
+ * PersonaEngine — the main SDK entry point.
+ * Wraps a PersonaConfig and provides the chat interface.
+ */
+export declare class PersonaEngine {
+    readonly config: PersonaConfig;
+    constructor(config: PersonaConfig);
+    /**
+     * Stateless chat — app manages history + persistence.
+     * Build prompt → call LLM → parse response.
+     */
+    chat(input: ChatInput): Promise<ChatResult>;
+    /**
+     * Stateless app-initiated turn — delegates to chat() with the intent
+     * framed as a system section, not a user message.
+     * The message slot gets a neutral directive so the AI understands
+     * this is system-initiated, not user-initiated.
+     */
+    promptedTurn(input: PromptedTurnInput): Promise<ChatResult>;
+    /**
+     * Stateless retrospective memory pass — infer durable memory updates silently.
+     * Returns memory CRUD actions only; no user-facing message.
+     */
+    retrospect(input: RetrospectInput): Promise<RetrospectResult>;
+    /**
+     * Stateless greeting — build greeting prompt, call LLM, return plain text.
+     * No response schema, no actions — just a warm check-in message.
+     */
+    greet(input: GreetingInput): Promise<{
+        greeting: string;
+    }>;
+    /**
+     * Check if a greeting is appropriate given the last message time.
+     */
+    shouldGreet(lastMessageAt: Date | null | undefined, timezone?: string): boolean;
+    /** The persona's display name */
+    get name(): string;
+    /** The LLM provider name */
+    get providerName(): string;
+    /**
+     * Audit the persona for keystone principle violations.
+     * Reviews the assembled prompt and optionally the conversation history.
+     * Returns explicit, actionable failure lists for developers/coding agents.
+     */
+    audit(input: AuditInput): Promise<AuditResult>;
+}
+//# sourceMappingURL=persona.d.ts.map

package/dist/persona.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../src/persona.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAc,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAgB,MAAM,YAAY,CAAA;AAUrK,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAoJ/D;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;gBAElB,MAAM,EAAE,aAAa;IAIjC;;;OAGG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAIjD;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAyCjE;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqCnE;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBhE;;OAEG;IACH,WAAW,CAAC,aAAa,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAI/E,iCAAiC;IACjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,4BAA4B;IAC5B,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;CAsBrD"}