@itaila/archetype 0.3.30

package/dist/audit/conversation-audit.js

@@ -0,0 +1,76 @@
+/**
+ * Conversation Audit — reviews actual AI behavior for keystone violations.
+ *
+ * The prompt audit checks what the AI was told.
+ * The conversation audit checks what the AI actually did.
+ *
+ * Output: explicit failure list with evidence. The developer decides
+ * whether to build regression tests from the failures.
+ */
+import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
+import { configVersion } from './version.js';
+const CONVERSATION_AUDIT_SYSTEM = `You are the Archetype meta judge — an expert in AI persona behavioral quality.
+
+You are reviewing a conversation between an AI persona and a user.
+
+THE KEYSTONE PRINCIPLE:
+The AI persona is a domain expert. It has rich context — the user's data, history, memories, and the current situation. A great expert uses what it knows about THIS specific person to lead the conversation. The prompt paints the scenario; the expert decides how to show up.
+
+WHAT GREAT LOOKS LIKE:
+A well-functioning persona sounds like a professional who has been working with this client for months. It leads with expertise, grounds its advice in the specific data it has, and sounds like itself — not like a textbook or a generic assistant.
+
+You are an expert in evaluating AI persona behavior. Review this conversation and identify where the AI fails the keystone standard. For each failure, quote specific evidence from the transcript.
+
+Return valid JSON.`;
+const RESPONSE_SCHEMA = {
+    type: SchemaType.OBJECT,
+    properties: {
+        failures: {
+            type: SchemaType.ARRAY,
+            items: {
+                type: SchemaType.OBJECT,
+                properties: {
+                    principle: { type: SchemaType.STRING, description: 'Which keystone principle the behavior violates' },
+                    turn: { type: SchemaType.NUMBER, description: 'Which assistant turn (0-indexed) contains the violation' },
+                    issue: { type: SchemaType.STRING, description: 'What went wrong, concretely' },
+                    evidence: { type: SchemaType.STRING, description: 'Direct quote from the assistant response as evidence' },
+                },
+                required: ['principle', 'turn', 'issue', 'evidence'],
+            },
+        },
+        summary: { type: SchemaType.STRING, description: 'One-paragraph summary of behavioral quality' },
+    },
+    required: ['failures', 'summary'],
+};
+export async function auditConversation(input) {
+    const { apiKey, config, history, context } = input;
+    const transcript = history.map(msg => `${msg.role.toUpperCase()}: ${msg.content}`).join('\n\n');
+    const personaContext = [
+        `PERSONA: ${config.identity.name}`,
+        `EXPERTISE: ${config.identity.expertise.join(', ')}`,
+        `RELATIONSHIP: ${config.identity.relationship}`,
+        `NORTH STAR: ${config.identity.northStar}`,
+        config.methodology ? `METHODOLOGY:\n${config.methodology}` : '',
+    ].filter(Boolean).join('\n');
+    const contextStr = context
+        ? `\nCONTEXT DATA AVAILABLE TO THE AI:\n${JSON.stringify(context, null, 2)}`
+        : '';
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const model = genAI.getGenerativeModel({
+        model: 'gemini-3.5-flash',
+        systemInstruction: CONVERSATION_AUDIT_SYSTEM,
+        generationConfig: {
+            temperature: 0.2,
+            responseMimeType: 'application/json',
+            responseSchema: RESPONSE_SCHEMA,
+        },
+    });
+    const result = await model.generateContent(`${personaContext}${contextStr}\n\nCONVERSATION TO AUDIT:\n${transcript}`);
+    const parsed = JSON.parse(result.response.text());
+    return {
+        configVersion: configVersion(config),
+        failures: parsed.failures ?? [],
+        summary: parsed.summary ?? '',
+    };
+}
+//# sourceMappingURL=conversation-audit.js.map

package/dist/audit/conversation-audit.js.map

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

package/dist/audit/prompt-audit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Prompt Audit — Archetype's meta judge for keystone principle violations.
+ *
+ * The persona is the domain expert. Archetype is the prompt-engineering expert.
+ * This judge reviews the assembled prompt for anti-patterns that constrain
+ * the AI's expert judgment instead of empowering it.
+ */
+import type { PromptAuditInput, PromptAuditResult } from './types.js';
+export declare function auditPrompt(input: PromptAuditInput): Promise<PromptAuditResult>;
+//# sourceMappingURL=prompt-audit.d.ts.map

package/dist/audit/prompt-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-audit.d.ts","sourceRoot":"","sources":["../../src/audit/prompt-audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAsB,MAAM,YAAY,CAAA;AAuEzF,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiFrF"}

package/dist/audit/prompt-audit.js

@@ -0,0 +1,153 @@
+/**
+ * Prompt Audit — Archetype's meta judge for keystone principle violations.
+ *
+ * The persona is the domain expert. Archetype is the prompt-engineering expert.
+ * This judge reviews the assembled prompt for anti-patterns that constrain
+ * the AI's expert judgment instead of empowering it.
+ */
+import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
+import { buildSystemPrompt } from '../core/prompt-builder.js';
+import { resolveActions } from '../core/effective-config.js';
+import { configVersion } from './version.js';
+/**
+ * The keystone audit criteria — derived from PLAYBOOK_ESSENTIALS.md and the
+ * design principles in eq.ts, identity.ts, and defaults.ts.
+ *
+ * These judge the SHAPE of the prompt, not the domain content.
+ */
+const PROMPT_AUDIT_SYSTEM = `You are the Archetype meta judge — an expert reviewer of AI persona configs written by other engineers (often with AI coding agents).
+
+The most common failure you catch is the reviewer's instinct to assume the AI is "stupid" and box it with rules, instead of realizing the AI is as capable as the engineer and failed because the context, scenario, or contract was unclear. When you see a rule that looks like it's correcting a mediocre employee, the real fix is almost always in the adjacent layer (entity description, schema field, context label, EQ config) — not more brain prose.
+
+THE KEYSTONE PRINCIPLE:
+The AI persona is a domain expert. The prompt's job is to paint the scenario — context, memories, history, timing, constraints — and explain the intent. Describe the standard. Then trust the expert. Hard rules are ONLY for mechanical correctness (JSON format, unit conversion, schema compliance, dedup logic). Everything else must be a thinking nudge.
+
+THE SMELL TEST:
+If a line reads like correcting a mediocre employee instead of briefing a strong collaborator, it's a violation.
+
+WHAT GREAT LOOKS LIKE:
+A well-shaped methodology describes the world the expert operates in and what a great practitioner notices. It reads like a briefing, not a rulebook.
+
+FAILURE MODES TO WATCH FOR (use judgment; these are lenses, not a checklist):
+
+- prescriptive — rules that tell the AI what to do in specific situations instead of describing a standard.
+- trigger-response-mapping — any "when X → do Y" pattern, at any level of abstraction. Even abstracted coaching wisdom like "respond to frustration by validating" is boxing.
+- doing-experts-thinking — enumerating what to check, attend to, or reason about, instead of trusting the expert to know what matters.
+- negative-identity — "you are NOT a calorie tracker" etc. Defines the persona by what it isn't.
+- throttling — "limit yourself to 2 suggestions", "don't always ask a question" — arbitrary caps on the expert's judgment.
+- announce-actions — instructions to narrate what the AI is doing or about to do.
+- rule-density — so many rules stacked that the expert has no room to reason.
+- duplicate-across-layers — prose in the brain that restates content already carried by entity descriptions, entity field describe() annotations, EQ flags, context labels, or memory config. The brain shouldn't carry what adjacent layers already say — duplicates compete for attention and crowd out taste.
+- signal-dilution — the same semantic signal stated three or more times in different wordings across the assembled prompt (across SDK defaults, brain sections, EQ nudges, memory block intros, etc.). Different from duplicate-across-layers: that's brain restating adjacent-layer content; this is the SAME idea phrased multiple ways inside the same prompt. The AI sees a cloud of soft reminders instead of one canonical rule, and the cloud dilutes rather than reinforces. Name the concept being repeated, quote two or three of the offending phrasings, and suggest consolidating to the single strongest statement.
+- self-documenting-overdocumented — an action or entity name that's already self-explanatory (like sendEmail, logMeal, createTask) paired with multi-line prose that restates what the name already says. Tell: deleting the description loses nothing a reader couldn't infer.
+- ambiguous-action-contract — action or entity contracts where the name/schema/description fight each other, use generic words (data, handle, process), have vague types (any, stringified objects), or lack the semantic clues the AI needs to emit correct calls. When you see "AI emits malformed actions", the problem is usually here — not AI capability.
+- not-visible-in-context — the ENTITIES block advertises update and delete for an entity, but the assembled prompt contains no surface that carries a record with an id for it (no CURRENT/OPEN/… block listing rows with ids under the entity name or its {name}Record(s) variants). The AI is asked to target records it can't see — it falls back to creating duplicates or writing memories instead. Fix by declaring a contextInput that surfaces records with ids, or by scoping the entity to createOnly.
+- conflicting-instructions — two parts of the config contradict each other (e.g., identity says "respect informed choices", action protocol says "always push toward healthier").
+- underspecified — instructions vague to the point of forcing guessing (e.g., "handle correction turns appropriately" — what's "appropriately"?). Different from terseness: good terse prose is unambiguous; underspecified prose leaves the AI to invent the meaning.
+
+For each violation, quote the exact text, name the principle, explain concretely why it's a problem, and suggest a scenario-first rewrite OR point to the adjacent layer where the content should live (e.g., "move to profile entity description", "already carried by EQ qualitativeFirst flag").
+
+Return valid JSON.`;
+const RESPONSE_SCHEMA = {
+    type: SchemaType.OBJECT,
+    properties: {
+        failures: {
+            type: SchemaType.ARRAY,
+            items: {
+                type: SchemaType.OBJECT,
+                properties: {
+                    principle: { type: SchemaType.STRING, description: 'Which keystone principle is violated (e.g., "prescriptive", "behavioral-rule", "doing-experts-thinking", "negative-identity", "throttling", "rule-density")' },
+                    text: { type: SchemaType.STRING, description: 'The exact problematic text from the prompt' },
+                    issue: { type: SchemaType.STRING, description: 'Why this is a problem, concretely' },
+                    suggestion: { type: SchemaType.STRING, description: 'A scenario-first rewrite that preserves the intent' },
+                },
+                required: ['principle', 'text', 'issue', 'suggestion'],
+            },
+        },
+        summary: { type: SchemaType.STRING, description: 'One-paragraph summary of the prompt health and key issues' },
+    },
+    required: ['failures', 'summary'],
+};
+const DEFAULT_AUDIT_FALLBACKS = ['gemini-3.1-pro-preview', 'gemini-3.1-flash-lite'];
+const AUDIT_MAX_RETRIES = 2;
+function isRetryableAuditError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return /\b(429|5\d\d|timeout|timed out|overloaded|unavailable|resource exhausted)\b/i.test(msg);
+}
+export async function auditPrompt(input) {
+    const { apiKey, config, context, memories } = input;
+    const primary = input.model ?? 'gemini-3.5-flash';
+    const fallbacks = input.fallbackModels ?? DEFAULT_AUDIT_FALLBACKS;
+    const seen = new Set();
+    const modelChain = [primary, ...fallbacks].filter((m) => {
+        if (seen.has(m))
+            return false;
+        seen.add(m);
+        return true;
+    });
+    // Resolve effective actions (merges memory/craft actions) to get the full prompt
+    const effectiveActions = resolveActions(config);
+    const effectiveConfig = effectiveActions !== config.actions
+        ? { ...config, actions: effectiveActions }
+        : config;
+    // Assemble the full prompt that the AI would actually see. When the
+    // consumer passes `promptMode`, honor it — otherwise the audit reports
+    // findings against a prompt variant the runtime never sends (chat-mode
+    // default), missing latent contradictions in focus / operational modes.
+    const fullPrompt = buildSystemPrompt({
+        config: effectiveConfig,
+        input: {
+            message: '(audit)',
+            context: context ?? {},
+            memories: memories ?? [],
+            timezone: 'UTC',
+            ...(input.promptMode ? { promptMode: input.promptMode } : {}),
+        },
+    });
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const makeModel = (modelName) => genAI.getGenerativeModel({
+        model: modelName,
+        systemInstruction: PROMPT_AUDIT_SYSTEM,
+        generationConfig: {
+            temperature: 0.2,
+            responseMimeType: 'application/json',
+            responseSchema: RESPONSE_SCHEMA,
+        },
+    });
+    const auditInput = `Review this assembled system prompt for keystone principle violations:\n\n---\n${fullPrompt}\n---`;
+    // Try each model in chain with retries
+    let lastError;
+    let result;
+    outer: for (let m = 0; m < modelChain.length; m++) {
+        const current = modelChain[m];
+        if (m > 0) {
+            console.warn(`[archetype:audit] ${modelChain[m - 1]} exhausted — falling back to ${current}`);
+        }
+        const model = makeModel(current);
+        for (let attempt = 0; attempt <= AUDIT_MAX_RETRIES; attempt++) {
+            try {
+                result = await model.generateContent(auditInput);
+                break outer;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (!isRetryableAuditError(lastError))
+                    throw lastError;
+                if (attempt < AUDIT_MAX_RETRIES) {
+                    const delayMs = Math.min(500 * Math.pow(2, attempt), 4000);
+                    console.warn(`[archetype:audit] ${current} attempt ${attempt + 1} failed: ${lastError.message} — retrying in ${delayMs}ms`);
+                    await new Promise((r) => setTimeout(r, delayMs));
+                }
+            }
+        }
+    }
+    if (!result)
+        throw lastError ?? new Error('[archetype:audit] all models exhausted');
+    const parsed = JSON.parse(result.response.text());
+    return {
+        configVersion: configVersion(config),
+        failures: parsed.failures ?? [],
+        summary: parsed.summary ?? '',
+    };
+}
+//# sourceMappingURL=prompt-audit.js.map

package/dist/audit/prompt-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-audit.js","sourceRoot":"","sources":["../../src/audit/prompt-audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAe,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAG5C;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAgCT,CAAA;AAEnB,MAAM,eAAe,GAAG;IACtB,IAAI,EAAE,UAAU,CAAC,MAAM;IACvB,UAAU,EAAE;QACV,QAAQ,EAAE;YACR,IAAI,EAAE,UAAU,CAAC,KAAK;YACtB,KAAK,EAAE;gBACL,IAAI,EAAE,UAAU,CAAC,MAAM;gBACvB,UAAU,EAAE;oBACV,SAAS,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,6JAA6J,EAAE;oBAClN,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,4CAA4C,EAAE;oBAC5F,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,mCAAmC,EAAE;oBACpF,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,oDAAoD,EAAE;iBAC3G;gBACD,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC;aACvD;SACF;QACD,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,2DAA2D,EAAE;KAC/G;IACD,QAAQ,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;CAClC,CAAA;AAED,MAAM,uBAAuB,GAAG,CAAC,wBAAwB,EAAE,uBAAuB,CAAC,CAAA;AACnF,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAE3B,SAAS,qBAAqB,CAAC,KAAc;IAC3C,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClE,OAAO,8EAA8E,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAuB;IACvD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,kBAAkB,CAAA;IACjD,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,IAAI,uBAAuB,CAAA;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACtD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAA;QAC7B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QACX,OAAO,IAAI,CAAA;IACb,CAAC,CAAC,CAAA;IAEF,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;IAC/C,MAAM,eAAe,GAAG,gBAAgB,KAAK,MAAM,CAAC,OAAO;QACzD,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE;QAC1C,CAAC,CAAC,MAAM,CAAA;IAEV,oEAAoE;IACpE,uEAAuE;IACvE,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,UAAU,GAAG,iBAAiB,CAAC;QACnC,MAAM,EAAE,eAAe;QACvB,KAAK,EAAE;YACL,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE,OAAO,IAAI,EAAE;YACtB,QAAQ,EAAE,QAAQ,IAAI,EAAE;YACxB,QAAQ,EAAE,KAAK;YACf,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D;KACF,CAAC,CAAA;IAEF,MAAM,KAAK,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAE,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC;QAChE,KAAK,EAAE,SAAS;QAChB,iBAAiB,EAAE,mBAAmB;QACtC,gBAAgB,EAAE;YAChB,WAAW,EAAE,GAAG;YAChB,gBAAgB,EAAE,kBAAkB;YACpC,cAAc,EAAE,eAAoC;SACrD;KACF,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,kFAAkF,UAAU,OAAO,CAAA;IAEtH,uCAAuC;IACvC,IAAI,SAA4B,CAAA;IAChC,IAAI,MAAwD,CAAA;IAC5D,KAAK,EAAE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;QAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,qBAAqB,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAA;QAC/F,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;QAChC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,iBAAiB,EAAE,OAAO,EAAE,EAAE,CAAC;YAC9D,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC,UAAU,CAAC,CAAA;gBAChD,MAAM,KAAK,CAAA;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,SAAS,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;gBAC/D,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC;oBAAE,MAAM,SAAS,CAAA;gBACtD,IAAI,OAAO,GAAG,iBAAiB,EAAE,CAAC;oBAChC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAA;oBAC1D,OAAO,CAAC,IAAI,CAAC,qBAAqB,OAAO,YAAY,OAAO,GAAG,CAAC,YAAY,SAAS,CAAC,OAAO,kBAAkB,OAAO,IAAI,CAAC,CAAA;oBAC3H,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAA;gBAClD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM;QAAE,MAAM,SAAS,IAAI,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAEnF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAG/C,CAAA;IAED,OAAO;QACL,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC;QACpC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;KAC9B,CAAA;AACH,CAAC"}

package/dist/audit/prompt-dump.d.ts

@@ -0,0 +1,137 @@
+import type { PersonaConfig, ChatInput, PromptedTurnInput, ChatAttachment, PromptMode, PromptOrigin } from '../types.js';
+export interface DumpedPrompt {
+    /** The assembled system prompt — exactly what the LLM sees as its system role. */
+    systemPrompt: string;
+    /** The user/assistant history in order. */
+    history: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /** The current user message (or the intent/guidelines for prompted turns). */
+    message: string;
+    /** Image attachments, when present. */
+    attachments?: ChatAttachment[];
+    /** Response schema passed to the LLM, when relevant. */
+    responseSchema?: Record<string, unknown>;
+    /** Which mode produced this prompt ('chat' | 'prompted-turn' | 'retrospect'). */
+    mode: DumpMode;
+    /** Which prompt scaffold the model actually received. */
+    promptMode: PromptMode;
+    /** Whether the current message originated with a person/user or the app/runtime. */
+    promptOrigin: PromptOrigin;
+    /**
+     * A single-string artifact ready for pasting into an AI reviewer,
+     * attaching to a bug report, diffing across runs, etc. Includes
+     * clearly-labeled section headers.
+     */
+    artifact: string;
+}
+export type DumpMode = 'chat' | 'prompted-turn' | 'retrospect';
+export interface DumpPromptOptions {
+    /**
+     * Which assembly path to use. Default 'chat' — matches engine.chat().
+     * Use 'prompted-turn' for AI-initiated turns (greetings, proactive).
+     */
+    mode?: DumpMode;
+}
+/**
+ * Assemble the exact prompt this persona would send for one input, and
+ * return it in a shape friendly for human or AI review.
+ *
+ * Use this during the debugging loop when auditPersona findings need
+ * context, or when you want a second opinion from another AI on the
+ * actual packet.
+ */
+export declare function dumpPromptForReview(config: PersonaConfig, input: ChatInput | PromptedTurnInput, options?: DumpPromptOptions): DumpedPrompt;
+export interface PromptTraceRecorderOptions {
+    /** Directory to write per-turn trace JSONs into. Created if missing. */
+    outDir: string;
+    /**
+     * Optional namespace/subgroup within outDir — useful when running
+     * multiple harnesses against one persona in parallel. Falls under
+     * `<outDir>/<traceGroup>/` when set.
+     */
+    traceGroup?: string;
+    /**
+     * Optional tag written into each trace record. Pass e.g. the
+     * transport/provider name so downstream review tooling can filter.
+     */
+    tag?: string;
+    /**
+     * Format written per turn. Default 'json' for programmatic analysis.
+     * 'artifact' writes the human-readable single-string version instead.
+     * 'both' writes two files per turn (.json + .txt).
+     */
+    format?: 'json' | 'artifact' | 'both';
+}
+export interface PromptTraceRecorder {
+    /**
+     * Attach to `runAutonomousLoop`'s `hooks.onBeforeChat` — the recorder
+     * receives the assembled request and writes a per-turn file.
+     */
+    onBeforeChat: (info: {
+        request: {
+            systemPrompt: string;
+            message: string;
+            history: Array<{
+                role: 'user' | 'assistant';
+                content: string;
+            }>;
+            responseSchema?: Record<string, unknown>;
+            attachments?: ChatAttachment[];
+            promptMode?: PromptMode;
+        };
+        turn: number;
+        attempt: number;
+    }) => void;
+    /**
+     * Record a standalone dump without going through autonomous-loop.
+     * Useful when a benchmark harness is hand-rolled.
+     */
+    record: (input: {
+        turn: number;
+        attempt?: number;
+        phase?: 'initial' | 'followup';
+        dumped: DumpedPrompt;
+    }) => void;
+    /**
+     * Append post-model/post-action evidence to the existing turn JSON.
+     * This is intentionally developer-facing audit data: it records the raw
+     * response, parsed actions, execution outcomes, and resulting history so a
+     * failed action can be debugged from artifacts alone.
+     */
+    recordTurnResult: (input: PromptTraceResultInput) => void;
+    /** Directory where traces are being written. */
+    outDir: string;
+}
+export interface PromptTraceResultInput {
+    turn: number;
+    attempt?: number;
+    phase?: 'initial' | 'followup';
+    rawResponse?: string | null;
+    message?: string;
+    trace?: unknown;
+    actions?: unknown[];
+    actionResults?: unknown[];
+    historyAfterTurn?: Array<{
+        role: string;
+        content: string;
+    }>;
+    nextMessage?: string | null;
+    notes?: string[];
+}
+export declare function createPromptTraceRecorder(options: PromptTraceRecorderOptions): PromptTraceRecorder;
+declare function formatAsArtifact(input: {
+    systemPrompt: string;
+    history: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    message: string;
+    mode: DumpMode;
+    promptMode?: PromptMode;
+    promptOrigin?: PromptOrigin;
+    attachments?: ChatAttachment[];
+}): string;
+export { formatAsArtifact };
+//# sourceMappingURL=prompt-dump.d.ts.map

package/dist/audit/prompt-dump.d.ts.map

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