@principles/core 1.73.0

package/dist/runtime-v2/diagnostician-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostician-output.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/diagnostician-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAIxE,eAAO,MAAM,oCAAoC;;;;EAI/C,CAAC;AAEH,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAEjG,eAAO,MAAM,2BAA2B;;;EAGtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAE/E,eAAO,MAAM,wBAAwB,8RAMnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEzE,eAAO,MAAM,iCAAiC;;;IAG5C,sEAAsE;;IAEtE,yEAAyE;;IAEzE;;OAEG;;EAEH,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE3F,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;QAZtC,sEAAsE;;QAEtE,yEAAyE;;QAEzE;;WAEG;;;;;EAgBH,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAI/E;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC;;;;;;EAM7C,CAAC;AAEH,gHAAgH;AAChH,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,OAAO,EAAE,2BAA2B,CAAC;IACrC,8CAA8C;IAC9C,eAAe,EAAE,yBAAyB,CAAC;IAC3C,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/runtime-v2/diagnostician-output.js

@@ -0,0 +1,65 @@
+/**
+ * Canonical diagnostician output schema for PD Runtime v2.
+ *
+ * Source: Diagnostician v2 Detailed Design, Section 11
+ * Source: PD Runtime Protocol SPEC v1, Section 18
+ *
+ * This is the single structured output contract for diagnosis results.
+ * All runtime adapters producing diagnostician output must conform to this schema.
+ */
+import { Type } from '@sinclair/typebox';
+// ── Diagnostician Output V1 ──
+export const DiagnosticianViolatedPrincipleSchema = Type.Object({
+    principleId: Type.Optional(Type.String({ minLength: 1 })),
+    title: Type.Optional(Type.String()),
+    rationale: Type.String({ minLength: 1 }),
+});
+export const DiagnosticianEvidenceSchema = Type.Object({
+    sourceRef: Type.String({ minLength: 1 }),
+    note: Type.String({ minLength: 1 }),
+});
+export const RecommendationKindSchema = Type.Union([
+    Type.Literal('principle'),
+    Type.Literal('rule'),
+    Type.Literal('implementation'),
+    Type.Literal('prompt'),
+    Type.Literal('defer'),
+]);
+export const DiagnosticianRecommendationSchema = Type.Object({
+    kind: RecommendationKindSchema,
+    description: Type.String({ minLength: 1 }),
+    /** Trigger pattern (regex/keywords) — required when kind is 'rule' */
+    triggerPattern: Type.Optional(Type.String()),
+    /** Action to take when pattern matches — required when kind is 'rule' */
+    action: Type.Optional(Type.String()),
+    /** Highly abstracted principle (≤200 chars) — required when kind is 'principle'
+     * @see MAX_ABSTRACTED_PRINCIPLE_CHARS in runner/default-validator.ts
+     */
+    abstractedPrinciple: Type.Optional(Type.String()),
+});
+export const DiagnosticianOutputV1Schema = Type.Object({
+    valid: Type.Boolean(),
+    diagnosisId: Type.String({ minLength: 1 }),
+    summary: Type.String({ minLength: 1 }),
+    rootCause: Type.String({ minLength: 1 }),
+    violatedPrinciples: Type.Array(DiagnosticianViolatedPrincipleSchema),
+    evidence: Type.Array(DiagnosticianEvidenceSchema),
+    recommendations: Type.Array(DiagnosticianRecommendationSchema),
+    confidence: Type.Number({ minimum: 0, maximum: 1 }),
+    ambiguityNotes: Type.Optional(Type.Array(Type.String())),
+});
+// ── Diagnostician Invocation Input ──
+/**
+ * TypeBox schema for diagnostician invocation input.
+ * The `context` field uses Type.Unknown() because cross-file TypeBox schema
+ * references can cause circular dependency issues. The actual type validation
+ * is performed separately via DiagnosticianContextPayloadSchema.
+ */
+export const DiagnosticianInvocationInputSchema = Type.Object({
+    agentId: Type.String({ minLength: 1 }),
+    taskId: Type.String({ minLength: 1 }),
+    context: Type.Unknown(), // Validated separately — DiagnosticianContextPayload
+    outputSchemaRef: Type.Literal('diagnostician-output-v1'),
+    timeoutMs: Type.Number({ minimum: 0 }),
+});
+//# sourceMappingURL=diagnostician-output.js.map

package/dist/runtime-v2/diagnostician-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostician-output.js","sourceRoot":"","sources":["../../src/runtime-v2/diagnostician-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAGtD,gCAAgC;AAEhC,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9D,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;IACzD,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACnC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CAAC;IACrD,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACxC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;CACpC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC,KAAK,CAAC;IACjD,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACpB,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAC9B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;CACtB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,iCAAiC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3D,IAAI,EAAE,wBAAwB;IAC9B,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC1C,sEAAsE;IACtE,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,yEAAyE;IACzE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACpC;;OAEG;IACH,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CAClD,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CAAC;IACrD,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE;IACrB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC1C,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACtC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACxC,kBAAkB,EAAE,IAAI,CAAC,KAAK,CAAC,oCAAoC,CAAC;IACpE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC;IACjD,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,iCAAiC,CAAC;IAC9D,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACnD,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;CACzD,CAAC,CAAC;AAIH,uCAAuC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACtC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACrC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,qDAAqD;IAC9E,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC;IACxD,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;CACvC,CAAC,CAAC"}

package/dist/runtime-v2/diagnostician-prompt-builder.d.ts

@@ -0,0 +1,125 @@
+/**
+ * DiagnosticianPromptBuilder — transforms DiagnosticianContextPayload into PromptInput for OpenClaw agent.
+ *
+ * Phase: m6-03
+ * Requirements: DPB-01, DPB-02, DPB-03, DPB-04, DPB-05
+ *
+ * ## Contract
+ *
+ * buildPrompt() takes DiagnosticianContextPayload and returns a JSON string
+ * to be passed as `openclaw agent --message <json>`.
+ *
+ * ## Output Structure (DPB-06)
+ *
+ * PromptInput has explicit top-level fields (taskId, contextHash, diagnosisTarget,
+ * conversationWindow, sourceRefs) plus nested `context: DiagnosticianContextPayload`.
+ *
+ * ## Diagnostic Instruction (5 Whys / Root Cause Protocol)
+ *
+ * Per SKILL.md (pd-diagnostician): The LLM MUST follow the 5-phase protocol
+ * (Phase 0 context → Phase 1 evidence → Phase 2 causal chain → Phase 3 classification
+ * → Phase 4 principle extraction). The diagnosticInstruction field makes this explicit
+ * so the LLM follows the protocol even if OpenClaw does not load SKILL.md automatically.
+ *
+ * ## Constraints (LOCKED)
+ *
+ * - DPB-02: Output is ONLY JSON — no markdown, no file ops, no tool calls
+ * - DPB-07: NO extraSystemPrompt field — system prompt is agent profile's responsibility
+ * - DPB-05: LLM only analyzes — PD database commits are handled by caller code
+ */
+import type { DiagnosticianContextPayload, HistoryQueryEntry, DiagnosisTarget } from './context-payload.js';
+/**
+ * PromptInput — the JSON message sent to openclaw agent via --message flag.
+ *
+ * Per DPB-06: Explicit top-level fields make LLM's job clearer and easier to validate.
+ * The DiagnosticianContextPayload is nested under `context` for backward compatibility.
+ * The diagnosticInstruction field carries the 5-phase protocol so the LLM follows it.
+ *
+ * @see DEFAULT_LIMITS for size constraints applied during buildPrompt()
+ */
+export interface PromptInput {
+    /** Task being diagnosed */
+    taskId: string;
+    /** Hash of the context for integrity verification */
+    contextHash: string;
+    /** What to diagnose (pain event, failure mode, etc.) */
+    diagnosisTarget: DiagnosisTarget;
+    /**
+     * Conversation window summary (may be truncated if too large).
+     * Full HistoryQueryEntry[] is available in context.conversationWindow;
+     * this field may contain a condensed version for the LLM prompt.
+     */
+    conversationWindow: HistoryQueryEntry[];
+    /** Source references for the diagnosis */
+    sourceRefs: string[];
+    /** Full DiagnosticianContextPayload for backward compatibility */
+    context: DiagnosticianContextPayload;
+    /**
+     * Explicit 5-phase diagnostic protocol instruction.
+     * Tells the LLM to follow Phase 1 (evidence) → Phase 2 (5 Whys causal chain)
+     * → Phase 3 (root cause classification) → Phase 4 (principle extraction),
+     * and to output DiagnosticianOutputV1 JSON.
+     */
+    diagnosticInstruction: string;
+    /** Warnings added during truncation (e.g., conversationWindow entries removed) */
+    truncationWarnings?: string[];
+}
+/** Size limits for buildPrompt() to prevent token overflow. */
+export interface PromptBuilderLimits {
+    /** Maximum number of conversation entries (default: 30) */
+    maxConversationEntries: number;
+    /** Maximum characters per entry text (default: 2000) */
+    maxEntryTextChars: number;
+    /** Maximum total message characters (default: 80000) */
+    maxMessageChars: number;
+}
+export declare const DEFAULT_PROMPT_BUILDER_LIMITS: PromptBuilderLimits;
+/**
+ * Build result — the JSON string to pass as --message argument.
+ *
+ * Per DPB-02: Output is ONLY JSON (no markdown, no file ops, no tool calls).
+ * Per DPB-07: NO extraSystemPrompt field in this result.
+ */
+export interface PromptBuildResult {
+    /** JSON string — the exact value to pass as openclaw agent --message argument */
+    readonly message: string;
+    /** The PromptInput object that was serialized to JSON */
+    readonly promptInput: PromptInput;
+}
+/**
+ * 5-phase diagnostic protocol instruction for the LLM.
+ *
+ * Per DPB-02 (LOCKED): Output is ONLY JSON — no markdown, no file ops, no tool calls.
+ * Per DPB-04: LLM can only analyze the context provided in the prompt; it must NOT
+ *   read files, call tools, or write to databases. All evidence must be drawn from
+ *   the context payload (sourceRefs, conversationWindow, eventSummaries).
+ *
+ * The 5-phase protocol is embedded directly in the prompt so the LLM follows it
+ * regardless of whether OpenClaw loads SKILL.md as the agent system prompt.
+ */
+export declare const DIAGNOSTIC_PROTOCOL_INSTRUCTION = "You are a root cause analysis expert. Follow this protocol:\n\nPHASE 1 \u2014 Evidence Review:\nReview the provided sourceRefs, diagnosisTarget.evidence entries, conversationWindow\nentries, and eventSummaries from the context payload. Do NOT read any files or call any tools.\nRecord all evidence by referencing the sourceRef identifiers and conversation\nentries already present in the context. Each evidence item must cite its source.\nPay special attention to diagnosisTarget.evidence \u2014 these are the primary behavioral\nevidence (owner messages and agent actions) that the root cause analysis must address.\n\nPHASE 2 \u2014 Causal Chain (5 Whys):\nBuild a Why-1 through Why-5 causal chain. Each Why MUST have evidence from Phase 1.\n- Why 1: Surface phenomenon (visible error)\n- Why 2: Direct cause (nearest trigger)\n- Why 3: Process gap (missing check/gate)\n- Why 4: Design flaw (why gap exists)\n- Why 5: Root cause (systemic defect)\nStop early if you find a directly fixable problem.\n\nPHASE 3 \u2014 Root Cause Classification:\nClassify into ONE: People | Design | Assumption | Tooling\n- People: capability blind spots, habit issues\n- Design: architecture defects, missing gates, process gaps\n- Assumption: wrong assumptions about env/versions/deps\n- Tooling: tool misconfiguration, API changes\n\nPHASE 4 \u2014 Recommendation Taxonomy & Distillation:\nAnalyze the root cause and propose actionable recommendations. Classify each recommendation into one of FIVE categories based on the taxonomy below.\n\nTAXONOMY DEFINITIONS:\n1. \"rule\": Deterministic constraints. Use for specific tool blocks or path protections. A \"rule\" MUST have a precise 'triggerPattern' and 'action' for physical interception.\n2. \"principle\": Abstract, reusable wisdom. Use for high-level architectural guidelines. MUST have 'abstractedPrinciple'.\n3. \"implementation\": Code-level candidate. Use for extremely specific code patches.\n4. \"prompt\": Context/Skill injection. Use to influence the agent's workflow habits.\n5. \"defer\": Insufficient evidence. Use for network timeouts or noise.\n\nCRITICAL: Your ENTIRE response must be ONLY the JSON object below. Do NOT include any text before or after the JSON. Do NOT wrap the JSON in markdown code fences. Do NOT add explanatory prose. Output the raw JSON object and nothing else.\n\nCOMPLETE EXAMPLE OUTPUT (follow this exact structure):\n{\"valid\":true,\"diagnosisId\":\"diag-550e8400-e29b-41d4-a716-446655440000\",\"summary\":\"Missing input validation caused null pointer exception in handler\",\"rootCause\":\"Design: No null check on input parameter before processing\",\"violatedPrinciples\":[{\"rationale\":\"The defensive programming principle was violated by not validating inputs at the boundary\"}],\"evidence\":[{\"sourceRef\":\"src:handler.ts:L42\",\"note\":\"Null dereference without guard check\"},{\"sourceRef\":\"log:error-trace\",\"note\":\"NullPointerException at handler.process()\"}],\"recommendations\":[{\"kind\":\"rule\",\"description\":\"Add null check at handler entry point\",\"triggerPattern\":\"function process(\",\"action\":\"Insert null guard returning error response\"},{\"kind\":\"principle\",\"description\":\"Validate all external inputs at system boundaries\",\"abstractedPrinciple\":\"Never trust external data without validation at entry points\"},{\"kind\":\"implementation\",\"description\":\"Add input validation middleware before handler\"},{\"kind\":\"prompt\",\"description\":\"Add defensive validation step to agent workflow\"},{\"kind\":\"defer\",\"description\":\"Upstream caller validation status unclear from available logs\"}],\"confidence\":0.82,\"ambiguityNotes\":[\"Stack trace may indicate upstream caller also missing validation\"]}\n\nIMPORTANT: The example above is ILLUSTRATIVE ONLY. Your recommendations MUST be based on the actual root cause analysis and evidence in this context \u2014 do not copy the example text verbatim.\n\nCONSTRAINTS:\n- Output ONLY valid JSON \u2014 no markdown, no explanatory text, no code fences, no prose before or after\n- Do NOT read files, call tools, or write to any database\n- rootCause MUST include category prefix: \"Design: ...\" or \"People: ...\" etc.\n- confidence MUST be a number between 0.0 and 1.0 (NOT a string, NOT a percentage)\n- kind MUST be one of: \"principle\", \"rule\", \"implementation\", \"prompt\", \"defer\" (lowercase only)\n- \"principle\" kind: MUST include abstractedPrinciple (<=200 chars)\n- \"rule\" kind: MUST include triggerPattern AND action\n- All evidence must reference sourceRef identifiers or conversationWindow entries from the context payload\n- The root cause MUST describe an agent behavior or decision, not a system monitoring or diagnostic mechanism.\n  If the evidence only describes internal metrics (GFI, friction scores, threshold crossings) with no\n  owner message or agent action context, return confidence < 0.3 and kind=\"defer\".\n";
+/**
+ * Summarizes a conversation window for inclusion in the prompt.
+ * DPB-04: Prompt includes conversationWindow summary.
+ *
+ * Default implementation returns entries as-is.
+ * Subclasses or configuration can provide condensation logic.
+ */
+export declare function summarizeConversationWindow(entries: HistoryQueryEntry[]): HistoryQueryEntry[];
+export declare class DiagnosticianPromptBuilder {
+    /**
+     * Transform DiagnosticianContextPayload into a PromptInput object,
+     * then serialize to JSON for the --message argument.
+     *
+     * @param payload — DiagnosticianContextPayload from context assembly (DPB-01)
+     * @param limits — Size limits to prevent token overflow (default: DEFAULT_PROMPT_BUILDER_LIMITS)
+     * @returns PromptBuildResult with JSON string + PromptInput object (DPB-02, DPB-03, DPB-04, DPB-06)
+     *
+     * Per DPB-05: This method only builds the prompt; it does NOT commit to PD database.
+     * The caller (DiagnosticianRunner or CLI layer) handles database commits.
+     *
+     * Per DPB-07: NO extraSystemPrompt is added — agent profile is the source of truth.
+     */
+    buildPrompt(payload: DiagnosticianContextPayload, limits?: PromptBuilderLimits): PromptBuildResult;
+}
+//# sourceMappingURL=diagnostician-prompt-builder.d.ts.map

package/dist/runtime-v2/diagnostician-prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostician-prompt-builder.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/diagnostician-prompt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,2BAA2B,CAAC;IACrC;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBAIlC,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,u1JAuD3C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,EAAE,GAC3B,iBAAiB,EAAE,CAErB;AAED,qBAAa,0BAA0B;IACrC;;;;;;;;;;;;OAYG;IAEH,WAAW,CACT,OAAO,EAAE,2BAA2B,EACpC,MAAM,GAAE,mBAAmD,GAC1D,iBAAiB;CAgErB"}

package/dist/runtime-v2/diagnostician-prompt-builder.js

@@ -0,0 +1,154 @@
+export const DEFAULT_PROMPT_BUILDER_LIMITS = {
+    maxConversationEntries: 30,
+    maxEntryTextChars: 2000,
+    maxMessageChars: 80_000,
+};
+/**
+ * 5-phase diagnostic protocol instruction for the LLM.
+ *
+ * Per DPB-02 (LOCKED): Output is ONLY JSON — no markdown, no file ops, no tool calls.
+ * Per DPB-04: LLM can only analyze the context provided in the prompt; it must NOT
+ *   read files, call tools, or write to databases. All evidence must be drawn from
+ *   the context payload (sourceRefs, conversationWindow, eventSummaries).
+ *
+ * The 5-phase protocol is embedded directly in the prompt so the LLM follows it
+ * regardless of whether OpenClaw loads SKILL.md as the agent system prompt.
+ */
+export const DIAGNOSTIC_PROTOCOL_INSTRUCTION = `You are a root cause analysis expert. Follow this protocol:
+
+PHASE 1 — Evidence Review:
+Review the provided sourceRefs, diagnosisTarget.evidence entries, conversationWindow
+entries, and eventSummaries from the context payload. Do NOT read any files or call any tools.
+Record all evidence by referencing the sourceRef identifiers and conversation
+entries already present in the context. Each evidence item must cite its source.
+Pay special attention to diagnosisTarget.evidence — these are the primary behavioral
+evidence (owner messages and agent actions) that the root cause analysis must address.
+
+PHASE 2 — Causal Chain (5 Whys):
+Build a Why-1 through Why-5 causal chain. Each Why MUST have evidence from Phase 1.
+- Why 1: Surface phenomenon (visible error)
+- Why 2: Direct cause (nearest trigger)
+- Why 3: Process gap (missing check/gate)
+- Why 4: Design flaw (why gap exists)
+- Why 5: Root cause (systemic defect)
+Stop early if you find a directly fixable problem.
+
+PHASE 3 — Root Cause Classification:
+Classify into ONE: People | Design | Assumption | Tooling
+- People: capability blind spots, habit issues
+- Design: architecture defects, missing gates, process gaps
+- Assumption: wrong assumptions about env/versions/deps
+- Tooling: tool misconfiguration, API changes
+
+PHASE 4 — Recommendation Taxonomy & Distillation:
+Analyze the root cause and propose actionable recommendations. Classify each recommendation into one of FIVE categories based on the taxonomy below.
+
+TAXONOMY DEFINITIONS:
+1. "rule": Deterministic constraints. Use for specific tool blocks or path protections. A "rule" MUST have a precise 'triggerPattern' and 'action' for physical interception.
+2. "principle": Abstract, reusable wisdom. Use for high-level architectural guidelines. MUST have 'abstractedPrinciple'.
+3. "implementation": Code-level candidate. Use for extremely specific code patches.
+4. "prompt": Context/Skill injection. Use to influence the agent's workflow habits.
+5. "defer": Insufficient evidence. Use for network timeouts or noise.
+
+CRITICAL: Your ENTIRE response must be ONLY the JSON object below. Do NOT include any text before or after the JSON. Do NOT wrap the JSON in markdown code fences. Do NOT add explanatory prose. Output the raw JSON object and nothing else.
+
+COMPLETE EXAMPLE OUTPUT (follow this exact structure):
+{"valid":true,"diagnosisId":"diag-550e8400-e29b-41d4-a716-446655440000","summary":"Missing input validation caused null pointer exception in handler","rootCause":"Design: No null check on input parameter before processing","violatedPrinciples":[{"rationale":"The defensive programming principle was violated by not validating inputs at the boundary"}],"evidence":[{"sourceRef":"src:handler.ts:L42","note":"Null dereference without guard check"},{"sourceRef":"log:error-trace","note":"NullPointerException at handler.process()"}],"recommendations":[{"kind":"rule","description":"Add null check at handler entry point","triggerPattern":"function process(","action":"Insert null guard returning error response"},{"kind":"principle","description":"Validate all external inputs at system boundaries","abstractedPrinciple":"Never trust external data without validation at entry points"},{"kind":"implementation","description":"Add input validation middleware before handler"},{"kind":"prompt","description":"Add defensive validation step to agent workflow"},{"kind":"defer","description":"Upstream caller validation status unclear from available logs"}],"confidence":0.82,"ambiguityNotes":["Stack trace may indicate upstream caller also missing validation"]}
+
+IMPORTANT: The example above is ILLUSTRATIVE ONLY. Your recommendations MUST be based on the actual root cause analysis and evidence in this context — do not copy the example text verbatim.
+
+CONSTRAINTS:
+- Output ONLY valid JSON — no markdown, no explanatory text, no code fences, no prose before or after
+- Do NOT read files, call tools, or write to any database
+- rootCause MUST include category prefix: "Design: ..." or "People: ..." etc.
+- confidence MUST be a number between 0.0 and 1.0 (NOT a string, NOT a percentage)
+- kind MUST be one of: "principle", "rule", "implementation", "prompt", "defer" (lowercase only)
+- "principle" kind: MUST include abstractedPrinciple (<=200 chars)
+- "rule" kind: MUST include triggerPattern AND action
+- All evidence must reference sourceRef identifiers or conversationWindow entries from the context payload
+- The root cause MUST describe an agent behavior or decision, not a system monitoring or diagnostic mechanism.
+  If the evidence only describes internal metrics (GFI, friction scores, threshold crossings) with no
+  owner message or agent action context, return confidence < 0.3 and kind="defer".
+`;
+/**
+ * Summarizes a conversation window for inclusion in the prompt.
+ * DPB-04: Prompt includes conversationWindow summary.
+ *
+ * Default implementation returns entries as-is.
+ * Subclasses or configuration can provide condensation logic.
+ */
+export function summarizeConversationWindow(entries) {
+    return entries;
+}
+export class DiagnosticianPromptBuilder {
+    /**
+     * Transform DiagnosticianContextPayload into a PromptInput object,
+     * then serialize to JSON for the --message argument.
+     *
+     * @param payload — DiagnosticianContextPayload from context assembly (DPB-01)
+     * @param limits — Size limits to prevent token overflow (default: DEFAULT_PROMPT_BUILDER_LIMITS)
+     * @returns PromptBuildResult with JSON string + PromptInput object (DPB-02, DPB-03, DPB-04, DPB-06)
+     *
+     * Per DPB-05: This method only builds the prompt; it does NOT commit to PD database.
+     * The caller (DiagnosticianRunner or CLI layer) handles database commits.
+     *
+     * Per DPB-07: NO extraSystemPrompt is added — agent profile is the source of truth.
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    buildPrompt(payload, limits = DEFAULT_PROMPT_BUILDER_LIMITS) {
+        const truncationWarnings = [];
+        // DPB-04: Apply truncation to conversationWindow to prevent token overflow
+        const rawWindow = summarizeConversationWindow(payload.conversationWindow);
+        const windowEntries = rawWindow.slice(0, limits.maxConversationEntries);
+        if (rawWindow.length > limits.maxConversationEntries) {
+            truncationWarnings.push(`conversationWindow truncated from ${rawWindow.length} to ${limits.maxConversationEntries} entries`);
+        }
+        // Truncate individual entry text
+        const conversationWindow = windowEntries.map((entry) => {
+            if (entry.text && entry.text.length > limits.maxEntryTextChars) {
+                return {
+                    ...entry,
+                    text: entry.text.slice(0, limits.maxEntryTextChars) + '...[truncated]',
+                };
+            }
+            return entry;
+        });
+        // Build compact context — replace conversationWindow with truncated version
+        // to avoid duplicating full content at top-level AND in context
+        const compactContext = {
+            ...payload,
+            conversationWindow,
+        };
+        // DPB-04: Explicit top-level fields at the prompt level
+        const promptInput = {
+            taskId: payload.taskId,
+            contextHash: payload.contextHash,
+            diagnosisTarget: payload.diagnosisTarget,
+            conversationWindow,
+            sourceRefs: payload.sourceRefs,
+            context: compactContext,
+            diagnosticInstruction: DIAGNOSTIC_PROTOCOL_INSTRUCTION,
+            ...(truncationWarnings.length > 0 ? { truncationWarnings } : {}),
+        };
+        // DPB-02: Output is ONLY JSON — no markdown, no file ops, no tool calls
+        // DPB-03: JSON must conform to what DiagnosticianOutputV1 expects (caller validates)
+        let message = JSON.stringify(promptInput);
+        // If message exceeds maxMessageChars, truncate the diagnostic instruction
+        if (message.length > limits.maxMessageChars) {
+            const surplus = message.length - limits.maxMessageChars;
+            const instruction = DIAGNOSTIC_PROTOCOL_INSTRUCTION;
+            // Keep at least the first 200 chars of the instruction + a note
+            const keepLength = Math.max(200, instruction.length - surplus - 100);
+            const truncatedInstruction = instruction.slice(0, keepLength) +
+                '\n\n[OUTPUT FORMAT section is REQUIRED; other sections may be summarized if needed]';
+            promptInput.diagnosticInstruction = truncatedInstruction;
+            promptInput.truncationWarnings = [
+                ...truncationWarnings,
+                `diagnosticInstruction truncated due to size (${message.length} > ${limits.maxMessageChars})`,
+            ];
+            message = JSON.stringify(promptInput);
+        }
+        return { message, promptInput };
+    }
+}
+//# sourceMappingURL=diagnostician-prompt-builder.js.map

package/dist/runtime-v2/diagnostician-prompt-builder.js.map

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

package/dist/runtime-v2/error-categories.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Canonical error categories for PD Runtime v2.
+ *
+ * Unified from:
+ *   - PD Runtime Protocol SPEC v1, Section 19
+ *   - Diagnostician v2 Detailed Design, Section 20
+ *   - History Retrieval and Context Assembly SPEC, Section 14
+ *
+ * All PD components, adapters, CLI commands, and events MUST use these
+ * categories instead of inventing local error codes.
+ *
+ * MIGRATION NOTE:
+ *   - openclaw-plugin's TrinityRuntimeFailureCode → superseded
+ *   - openclaw-plugin's TaskResolution → superseded (legacy marker-file values kept as legacy-only)
+ *   - openclaw-plugin's PdError class hierarchy → may wrap these categories
+ */
+import { type Static } from '@sinclair/typebox';
+export declare const PDErrorCategorySchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"runtime_unavailable">, import("@sinclair/typebox").TLiteral<"capability_missing">, import("@sinclair/typebox").TLiteral<"input_invalid">, import("@sinclair/typebox").TLiteral<"lease_conflict">, import("@sinclair/typebox").TLiteral<"lease_expired">, import("@sinclair/typebox").TLiteral<"execution_failed">, import("@sinclair/typebox").TLiteral<"timeout">, import("@sinclair/typebox").TLiteral<"cancelled">, import("@sinclair/typebox").TLiteral<"output_invalid">, import("@sinclair/typebox").TLiteral<"artifact_commit_failed">, import("@sinclair/typebox").TLiteral<"max_attempts_exceeded">, import("@sinclair/typebox").TLiteral<"context_assembly_failed">, import("@sinclair/typebox").TLiteral<"history_not_found">, import("@sinclair/typebox").TLiteral<"trajectory_ambiguous">, import("@sinclair/typebox").TLiteral<"storage_unavailable">, import("@sinclair/typebox").TLiteral<"workspace_invalid">, import("@sinclair/typebox").TLiteral<"workspace_dirty">, import("@sinclair/typebox").TLiteral<"query_invalid">]>;
+export type PDErrorCategory = Static<typeof PDErrorCategorySchema>;
+/** All valid error category values. Useful for validation. */
+export declare const PD_ERROR_CATEGORIES: readonly PDErrorCategory[];
+/** Type guard for PDErrorCategory — uses TypeBox Value.Check for runtime validation. */
+export declare function isPDErrorCategory(value: string): value is PDErrorCategory;
+/**
+ * Maps PDErrorCategory (17 internal codes) to 9 user-facing failure categories.
+ *
+ * Used by pd-cli trace + pain-record commands for consistent classification.
+ */
+export declare const FAILURE_CATEGORY_MAP: Record<PDErrorCategory, string>;
+export declare function mapFailureCategory(errorCategory?: string | null): string | null;
+/**
+ * Structured PD error carrying a normalized category.
+ *
+ * Adapters and services should throw or return PDRuntimeError
+ * instead of generic Error when operating within runtime-v2 paths.
+ */
+export declare class PDRuntimeError extends Error {
+    readonly category: PDErrorCategory;
+    readonly details?: Record<string, unknown>;
+    constructor(category: PDErrorCategory, message: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=error-categories.d.ts.map

package/dist/runtime-v2/error-categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-categories.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/error-categories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAKtD,eAAO,MAAM,qBAAqB,4jCAmBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,EAAE,SAAS,eAAe,EAmBhD,CAAC;AAEX,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAmBhE,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAI/E;AASD;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAM1F"}

package/dist/runtime-v2/error-categories.js

@@ -0,0 +1,119 @@
+/**
+ * Canonical error categories for PD Runtime v2.
+ *
+ * Unified from:
+ *   - PD Runtime Protocol SPEC v1, Section 19
+ *   - Diagnostician v2 Detailed Design, Section 20
+ *   - History Retrieval and Context Assembly SPEC, Section 14
+ *
+ * All PD components, adapters, CLI commands, and events MUST use these
+ * categories instead of inventing local error codes.
+ *
+ * MIGRATION NOTE:
+ *   - openclaw-plugin's TrinityRuntimeFailureCode → superseded
+ *   - openclaw-plugin's TaskResolution → superseded (legacy marker-file values kept as legacy-only)
+ *   - openclaw-plugin's PdError class hierarchy → may wrap these categories
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+// ── TypeBox schema for PDErrorCategory ──
+export const PDErrorCategorySchema = Type.Union([
+    Type.Literal('runtime_unavailable'),
+    Type.Literal('capability_missing'),
+    Type.Literal('input_invalid'),
+    Type.Literal('lease_conflict'),
+    Type.Literal('lease_expired'),
+    Type.Literal('execution_failed'),
+    Type.Literal('timeout'),
+    Type.Literal('cancelled'),
+    Type.Literal('output_invalid'),
+    Type.Literal('artifact_commit_failed'),
+    Type.Literal('max_attempts_exceeded'),
+    Type.Literal('context_assembly_failed'),
+    Type.Literal('history_not_found'),
+    Type.Literal('trajectory_ambiguous'),
+    Type.Literal('storage_unavailable'),
+    Type.Literal('workspace_invalid'),
+    Type.Literal('workspace_dirty'),
+    Type.Literal('query_invalid'),
+]);
+/** All valid error category values. Useful for validation. */
+export const PD_ERROR_CATEGORIES = [
+    'runtime_unavailable',
+    'capability_missing',
+    'input_invalid',
+    'lease_conflict',
+    'lease_expired',
+    'execution_failed',
+    'timeout',
+    'cancelled',
+    'output_invalid',
+    'artifact_commit_failed',
+    'max_attempts_exceeded',
+    'context_assembly_failed',
+    'history_not_found',
+    'trajectory_ambiguous',
+    'storage_unavailable',
+    'workspace_invalid',
+    'workspace_dirty',
+    'query_invalid',
+];
+/** Type guard for PDErrorCategory — uses TypeBox Value.Check for runtime validation. */
+export function isPDErrorCategory(value) {
+    return Value.Check(PDErrorCategorySchema, value);
+}
+/**
+ * Maps PDErrorCategory (17 internal codes) to 9 user-facing failure categories.
+ *
+ * Used by pd-cli trace + pain-record commands for consistent classification.
+ */
+export const FAILURE_CATEGORY_MAP = {
+    runtime_unavailable: 'runtime_unavailable',
+    capability_missing: 'config_missing',
+    input_invalid: 'config_missing',
+    lease_conflict: 'runtime_unavailable',
+    lease_expired: 'runtime_unavailable',
+    execution_failed: 'runtime_unavailable',
+    timeout: 'runtime_timeout',
+    cancelled: 'runtime_timeout',
+    output_invalid: 'output_invalid',
+    artifact_commit_failed: 'artifact_missing',
+    max_attempts_exceeded: 'runtime_timeout',
+    context_assembly_failed: 'runtime_unavailable',
+    history_not_found: 'runtime_unavailable',
+    trajectory_ambiguous: 'runtime_unavailable',
+    storage_unavailable: 'ledger_write_failed',
+    workspace_invalid: 'config_missing',
+    workspace_dirty: 'artifact_missing',
+    query_invalid: 'runtime_unavailable',
+};
+export function mapFailureCategory(errorCategory) {
+    if (!errorCategory)
+        return null;
+    if (!isPDErrorCategory(errorCategory))
+        return 'runtime_unavailable';
+    return FAILURE_CATEGORY_MAP[errorCategory];
+}
+// Runtime exhaustiveness assertion — verify every PDErrorCategory has a mapping
+for (const cat of PD_ERROR_CATEGORIES) {
+    if (!(cat in FAILURE_CATEGORY_MAP)) {
+        throw new Error(`FAILURE_CATEGORY_MAP is missing mapping for PDErrorCategory: ${cat}`);
+    }
+}
+/**
+ * Structured PD error carrying a normalized category.
+ *
+ * Adapters and services should throw or return PDRuntimeError
+ * instead of generic Error when operating within runtime-v2 paths.
+ */
+export class PDRuntimeError extends Error {
+    category;
+    details;
+    constructor(category, message, details) {
+        super(`[${category}] ${message}`);
+        this.name = 'PDRuntimeError';
+        this.category = category;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=error-categories.js.map

package/dist/runtime-v2/error-categories.js.map

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