@principles/pd-cli 1.73.0

package/src/legacy/legacy-import.ts

@@ -0,0 +1,179 @@
+/**
+ * Legacy Compatibility Import — OpenClaw → PD Runtime v2
+ *
+ * ## Purpose
+ *
+ * This module is a **compatibility import path only**.
+ * It is NOT the authoritative retrieval path for M3 queries.
+ *
+ * It syncs diagnostician task data from OpenClaw's legacy JSON-based stores
+ * into the PD Runtime v2 SQLite store so that `pd trajectory`, `pd history`,
+ * and `pd context` commands have data to query against.
+ *
+ * **Authoritative path**: `workspace/.pd/state.db` (PD-owned SQLite)
+ * **This module's role**: migrate legacy `.state/diagnostician_tasks.json` →
+ * `workspace/.pd/state.db` (one-way sync, idempotent)
+ *
+ * ## Sync Sources
+ *
+ *   - `.state/diagnostician_tasks.json`  →  tasks + runs tables
+ *
+ * ## Non-Goals
+ *
+ * This module does NOT:
+ * - Query raw OpenClaw `.state/` files for primary retrieval
+ * - Serve as the main path for trajectory/history/context commands
+ * - Own any PD task semantics
+ *
+ * ## Usage
+ *
+ * Call `syncOpenClawWorkspace(workspaceDir, connection)` once to import,
+ * then use `pd trajectory locate`, `pd history query`, `pd context build`
+ * which read from `workspace/.pd/state.db` directly.
+ *
+ * Idempotent: safe to call multiple times. Re-syncs latest state on every call.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { SqliteConnection } from '@principles/core';
+
+interface OpenClawDiagnosticianTask {
+  prompt: string;
+  createdAt: string;
+  status: 'pending' | 'completed';
+  reportMissingRetries?: number;
+}
+
+interface OpenClawDiagnosticianStore {
+  tasks: Record<string, OpenClawDiagnosticianTask>;
+}
+
+interface ParsedTaskFields {
+  sessionId: string;
+  painScore: number;
+  painSource: string;
+  painReason: string;
+}
+
+function readDiagnosticianStore(stateDir: string): OpenClawDiagnosticianStore {
+  const filePath = path.join(stateDir, 'diagnostician_tasks.json');
+  if (!fs.existsSync(filePath)) {
+    return { tasks: {} };
+  }
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.tasks === 'object' && parsed.tasks !== null && !Array.isArray(parsed.tasks)) {
+      return parsed as OpenClawDiagnosticianStore;
+    }
+    return { tasks: {} };
+  } catch {
+    return { tasks: {} };
+  }
+}
+
+function parsePrompt(taskId: string, prompt: string): ParsedTaskFields {
+  const sessionId =
+    /\*\*Session ID\*\*:\s*([^\n*]+)/.exec(prompt)?.[1]?.trim() ?? taskId;
+  const painScore =
+    parseInt(/\*\*Pain Score\*\*:\s*(\d+)/.exec(prompt)?.[1] ?? '0', 10);
+  const painSource =
+    /\*\*Source\*\*:\s*([^\n*]+)/.exec(prompt)?.[1]?.trim() ?? 'unknown';
+  const painReason =
+    /\*\*Reason\*\*:\s*([^\n*]+)/.exec(prompt)?.[1]?.trim() ?? '';
+
+  return { sessionId, painScore, painSource, painReason };
+}
+
+function painScoreToSeverity(score: number): string {
+  if (score >= 80) return 'critical';
+  if (score >= 60) return 'high';
+  if (score >= 40) return 'medium';
+  return 'low';
+}
+
+/**
+ * Sync all openclaw diagnostician tasks into the PD Runtime v2 SQLite store.
+ *
+ * For each task in diagnostician_tasks.json:
+ *   - Upsert into tasks table (base fields + diagnostic_json blob)
+ *   - Upsert a corresponding synthetic run into runs table
+ *
+ * Idempotent: existing records are updated, not duplicated.
+ */
+export async function syncOpenClawWorkspace(
+  workspaceDir: string,
+  connection: SqliteConnection,
+): Promise<{ tasksSynced: number; runsSynced: number }> {
+  const stateDir = path.join(workspaceDir, '.state');
+  const store = readDiagnosticianStore(stateDir);
+
+  const db = connection.getDb();
+  let tasksSynced = 0;
+  let runsSynced = 0;
+
+  const upsertTask = db.prepare(`
+    INSERT INTO tasks (task_id, task_kind, status, created_at, updated_at, attempt_count, max_attempts, diagnostic_json)
+    VALUES (@taskId, 'diagnostician', @status, @createdAt, @updatedAt, 0, 3, @diagnosticJson)
+    ON CONFLICT(task_id) DO UPDATE SET
+      status = @status,
+      updated_at = @updatedAt,
+      diagnostic_json = @diagnosticJson
+  `);
+
+  const upsertRun = db.prepare(`
+    INSERT INTO runs (run_id, task_id, runtime_kind, execution_status, started_at, ended_at, attempt_number, created_at, updated_at)
+    VALUES (@runId, @taskId, 'openclaw', @executionStatus, @startedAt, @endedAt, 1, @createdAt, @updatedAt)
+    ON CONFLICT(run_id) DO UPDATE SET
+      execution_status = @executionStatus,
+      ended_at = @endedAt,
+      updated_at = @updatedAt
+  `);
+
+  const now = new Date().toISOString();
+
+  for (const [taskId, task] of Object.entries(store.tasks)) {
+    const { sessionId, painScore, painSource, painReason } = parsePrompt(taskId, task.prompt);
+
+    const status =
+      task.status === 'pending'
+        ? 'pending'
+        : task.status === 'completed'
+          ? 'succeeded'
+          : 'failed';
+
+    const severity = painScoreToSeverity(painScore);
+    const reasonSummary = painReason.length > 200 ? painReason.substring(0, 197) + '...' : painReason;
+
+    const diagnosticJson = JSON.stringify({
+      workspaceDir,
+      reasonSummary,
+      source: painSource,
+      severity,
+      sessionIdHint: sessionId !== taskId ? sessionId : null,
+    });
+
+    upsertTask.run({
+      taskId,
+      status,
+      createdAt: task.createdAt,
+      updatedAt: now,
+      diagnosticJson,
+    });
+    tasksSynced++;
+
+    const runId = `run_${taskId}_1`;
+    upsertRun.run({
+      runId,
+      taskId,
+      executionStatus: status === 'pending' ? 'queued' : 'succeeded',
+      startedAt: task.createdAt,
+      endedAt: status !== 'pending' ? now : null,
+      createdAt: task.createdAt,
+      updatedAt: now,
+    });
+    runsSynced++;
+  }
+
+  return { tasksSynced, runsSynced };
+}

package/src/legacy/session-history-import.ts

@@ -0,0 +1,231 @@
+/**
+ * Session History Import — OpenClaw trajectory.db → PD Runtime v2
+ *
+ * Reads real conversation history from OpenClaw's trajectory.db and imports
+ * assistant_turns, user_turns, and tool_calls into PD-owned runtime-v2 runs table
+ * so that `pd history query` and `pd context build` return non-empty results.
+ *
+ * This is a COMPATIBILITY IMPORT — not authoritative retrieval.
+ * Primary retrieval always goes through `.pd/state.db` only.
+ */
+import Database from 'better-sqlite3';
+import * as path from 'path';
+
+interface OpenClawTrajectoryDb {
+  getAssistantTurns(sessionId: string): AssistantTurn[];
+  getUserTurns(sessionId: string): UserTurn[];
+  getToolCalls(sessionId: string): ToolCall[];
+  getSessionIds(): string[];
+}
+
+interface AssistantTurn {
+  id: number;
+  session_id: string;
+  run_id: string;
+  provider: string;
+  model: string;
+  sanitized_text: string;
+  created_at: string;
+}
+
+interface UserTurn {
+  id: number;
+  session_id: string;
+  turn_index: number;
+  raw_text: string;
+  created_at: string;
+}
+
+interface ToolCall {
+  id: number;
+  session_id: string;
+  tool_name: string;
+  outcome: string;
+  duration_ms: number | null;
+  exit_code: number | null;
+  error_type: string | null;
+  error_message: string | null;
+  created_at: string;
+}
+
+function openTrajectoryDb(dbPath: string): OpenClawTrajectoryDb {
+  const db = new Database(dbPath, { readonly: true });
+
+  return {
+    getAssistantTurns(sessionId: string): AssistantTurn[] {
+      return db
+        .prepare(
+          'SELECT id, session_id, run_id, provider, model, sanitized_text, created_at ' +
+            'FROM assistant_turns WHERE session_id = ? ORDER BY id ASC',
+        )
+        .all(sessionId) as AssistantTurn[];
+    },
+
+    getUserTurns(sessionId: string): UserTurn[] {
+      return db
+        .prepare(
+          'SELECT id, session_id, turn_index, raw_text, created_at ' +
+            'FROM user_turns WHERE session_id = ? ORDER BY id ASC',
+        )
+        .all(sessionId) as UserTurn[];
+    },
+
+    getToolCalls(sessionId: string): ToolCall[] {
+      return db
+        .prepare(
+          'SELECT id, session_id, tool_name, outcome, duration_ms, exit_code, ' +
+            'error_type, error_message, created_at ' +
+            'FROM tool_calls WHERE session_id = ? ORDER BY id ASC',
+        )
+        .all(sessionId) as ToolCall[];
+    },
+
+    getSessionIds(): string[] {
+      return (
+        db.prepare('SELECT session_id FROM sessions ORDER BY started_at DESC').all() as {
+          session_id: string;
+        }[]
+      ).map((r) => r.session_id);
+    },
+  };
+}
+
+/**
+ * Import session history from OpenClaw trajectory.db into PD runtime-v2 runs table.
+ *
+ * For each task that has a sessionIdHint in its diagnostic_json:
+ *   1. Look up the session in trajectory.db
+ *   2. Import assistant_turns, user_turns, tool_calls as entries
+ *   3. Upsert into runs table with full payload (JSON string)
+ *
+ * Idempotent: updates existing run records, does not duplicate.
+ */
+export async function importSessionHistory(
+  openclawWorkspaceDir: string,
+  pdWorkspaceDir: string,
+  getDb: () => Database.Database,
+): Promise<{ sessionsProcessed: number; entriesImported: number }> {
+  const trajectoryPath = path.join(openclawWorkspaceDir, '.state', 'trajectory.db');
+  const trajectoryDb = openTrajectoryDb(trajectoryPath);
+  const db = getDb();
+
+  // Find all tasks with a sessionIdHint
+  const tasksWithSession = db
+    .prepare(
+      `SELECT task_id, json_extract(diagnostic_json, '$.sessionIdHint') as session_id
+       FROM tasks
+       WHERE json_extract(diagnostic_json, '$.sessionIdHint') IS NOT NULL
+         AND json_extract(diagnostic_json, '$.sessionIdHint') != ''`,
+    )
+    .all() as { task_id: string; session_id: string }[];
+
+  let sessionsProcessed = 0;
+  let entriesImported = 0;
+
+  const upsertRun = db.prepare(`
+    INSERT INTO runs (run_id, task_id, runtime_kind, execution_status, started_at, ended_at,
+      attempt_number, created_at, updated_at, input_payload, output_payload)
+    VALUES (@runId, @taskId, 'openclaw-history', @executionStatus, @startedAt, @endedAt,
+      1, @createdAt, @updatedAt, @inputPayload, @outputPayload)
+    ON CONFLICT(run_id) DO UPDATE SET
+      input_payload = @inputPayload,
+      output_payload = @outputPayload,
+      ended_at = @endedAt,
+      updated_at = @updatedAt
+  `);
+
+  const now = new Date().toISOString();
+
+  for (const { task_id, session_id } of tasksWithSession) {
+    // Verify session exists in trajectory.db
+    const assistantTurns = trajectoryDb.getAssistantTurns(session_id);
+    if (assistantTurns.length === 0) continue;
+
+    const userTurns = trajectoryDb.getUserTurns(session_id);
+    const toolCalls = trajectoryDb.getToolCalls(session_id);
+
+    // Use the latest timestamp from the session as ended_at
+    const lastTimestamp =
+      assistantTurns.length > 0
+        ? assistantTurns[assistantTurns.length - 1].created_at
+        : now;
+
+    // Build input (user turns + tool calls) and output (assistant turns) payloads
+    const inputPayload = JSON.stringify({
+      type: 'session_history',
+      sessionId: session_id,
+      userTurns: userTurns.map((t) => ({
+        turnIndex: t.turn_index,
+        text: t.raw_text,
+        ts: t.created_at,
+      })),
+      toolCalls: toolCalls.map((t) => ({
+        toolName: t.tool_name,
+        outcome: t.outcome,
+        durationMs: t.duration_ms,
+        exitCode: t.exit_code,
+        errorType: t.error_type,
+        errorMessage: t.error_message,
+        ts: t.created_at,
+      })),
+    });
+
+    const outputPayload = JSON.stringify({
+      type: 'assistant_turns',
+      sessionId: session_id,
+      turns: assistantTurns.map((t) => ({
+        provider: t.provider,
+        model: t.model,
+        text: t.sanitized_text,
+        ts: t.created_at,
+      })),
+    });
+
+    const runId = `run_${task_id}_history_1`;
+
+    upsertRun.run({
+      runId,
+      taskId: task_id,
+      executionStatus: 'succeeded',
+      startedAt: assistantTurns[0].created_at,
+      endedAt: lastTimestamp,
+      createdAt: assistantTurns[0].created_at,
+      updatedAt: now,
+      inputPayload,
+      outputPayload,
+    });
+
+    entriesImported += assistantTurns.length + userTurns.length + toolCalls.length;
+    sessionsProcessed++;
+  }
+
+  return { sessionsProcessed, entriesImported };
+}
+
+function _buildConversationEntries(
+  assistantTurns: AssistantTurn[],
+  userTurns: UserTurn[],
+  toolCalls: ToolCall[],
+): string {
+  // Interleave and sort by timestamp for a unified view
+  type Entry = { ts: string; role: string; text: string; toolName?: string };
+  const entries: Entry[] = [];
+
+  for (const t of assistantTurns) {
+    entries.push({ ts: t.created_at, role: 'assistant', text: t.sanitized_text });
+  }
+  for (const t of userTurns) {
+    entries.push({ ts: t.created_at, role: 'user', text: t.raw_text ?? '' });
+  }
+  for (const t of toolCalls) {
+    entries.push({
+      ts: t.created_at,
+      role: 'tool',
+      text: `${t.tool_name}: ${t.outcome}${t.error_message ? ` — ${t.error_message}` : ''}`,
+      toolName: t.tool_name,
+    });
+  }
+
+  entries.sort((a, b) => a.ts.localeCompare(b.ts));
+  return JSON.stringify(entries, null, 2);
+}

package/src/principle-tree-ledger-adapter.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-exports the canonical PrincipleTreeLedgerAdapter from @principles/core/runtime-v2.
+ *
+ * This adapter uses @principles/core's addPrincipleToLedger/loadLedger, which write to
+ * <stateDir>/principle_training_state.json (HybridLedgerStore format), matching the ledger
+ * format used by the OpenClaw plugin's pain-signal-bridge.
+ *
+ * audit/repair commands use this adapter — it ensures consistency between
+ * what intake writes and what audit/repair read back.
+ */
+export {
+  PrincipleTreeLedgerAdapter,
+} from '@principles/core/runtime-v2';

package/src/resolve-workspace.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the active workspace directory.
+ *
+ * Requires explicit input — no silent cwd fallback.
+ * In openclaw-plugin, this will resolve via plugin config/env vars.
+ *
+ * @throws Error if no workspace directory can be determined.
+ */
+export function resolveWorkspaceDir(workspaceDir?: string): string {
+  if (workspaceDir) return workspaceDir;
+  const envWorkspace = process.env.PD_WORKSPACE_DIR;
+  if (envWorkspace) return envWorkspace;
+  throw new Error(
+    'No workspace directory configured. Set --workspace <path>, ' +
+    'PD_WORKSPACE_DIR environment variable, or run from within an initialized workspace.',
+  );
+}
+
+/** Environment variable name for workspace directory. */
+export const WORKSPACE_ENV = 'PD_WORKSPACE_DIR';