@principles/pd-cli 1.73.0

package/src/commands/runtime.ts

@@ -0,0 +1,281 @@
+/**
+ * pd runtime probe command — Runtime health and capabilities inspection.
+ *
+ * Usage:
+ *   pd runtime probe --runtime openclaw-cli [--openclaw-local|--openclaw-gateway] [--json]
+ *   pd runtime probe --runtime pi-ai --provider <name> --model <id> --apiKeyEnv <name> [--baseUrl <url>] [--json]
+ *
+ * HG-01 HARD GATE: This command must deliver.
+ */
+import * as path from 'path';
+import { probeRuntime } from '@principles/core/runtime-v2';
+import { PDRuntimeError } from '@principles/core/runtime-v2';
+
+interface RuntimeProbeOptions {
+  runtime: string;
+  openclawLocal?: boolean;
+  openclawGateway?: boolean;
+  agent?: string;
+  provider?: string;
+  model?: string;
+  apiKeyEnv?: string;
+  baseUrl?: string;
+  maxRetries?: number;
+  timeoutMs?: number;
+  workspace?: string;
+  json?: boolean;
+}
+
+/**
+ * Format capabilities as a key-value table for console output.
+ */
+function formatCapabilitiesTable(capabilities: Record<string, unknown>): string {
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(capabilities)) {
+    const displayValue = typeof value === 'boolean' ? (value ? 'yes' : 'no') : String(value);
+    lines.push(`  ${key.padEnd(40)} ${displayValue}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * openclaw-cli probe branch (existing behavior, unchanged).
+ */
+async function handleOpenClawProbe(opts: RuntimeProbeOptions): Promise<void> {
+  // Validate mutually exclusive flags (HG-03)
+  if (opts.openclawLocal && opts.openclawGateway) {
+    console.error('error: --openclaw-local and --openclaw-gateway are mutually exclusive');
+    process.exit(1);
+  }
+
+  // Require explicit runtime mode (HG-03, DPB-09)
+  if (!opts.openclawLocal && !opts.openclawGateway) {
+    console.error('error: --openclaw-local or --openclaw-gateway is required for --runtime openclaw-cli');
+    process.exit(1);
+  }
+
+  const runtimeMode = opts.openclawLocal ? 'local' : 'gateway';
+
+  try {
+    const result = await probeRuntime({
+      runtimeKind: 'openclaw-cli',
+      runtimeMode,
+      agentId: opts.agent,
+    });
+
+    // Per finding #2: status must reflect actual health
+    // healthy=false → status=failed, exit 1
+    // healthy=true + degraded=true → status=degraded
+    // healthy=true + degraded=false → status=succeeded
+    let exitCode = 0;
+    const status = !result.health.healthy ? 'failed'
+      : result.health.degraded ? 'degraded'
+      : 'succeeded';
+    if (!result.health.healthy) exitCode = 1;
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status,
+        runtimeKind: result.runtimeKind,
+        health: result.health,
+        capabilities: result.capabilities,
+      }, null, 2));
+      if (exitCode !== 0) {
+        process.exit(exitCode);
+      }
+      return;
+    }
+
+    // Human-readable output
+    console.log(`\nRuntime: ${result.runtimeKind}`);
+    console.log(`Mode:    ${runtimeMode}`);
+    console.log(`Status:  ${status}`);
+    console.log('');
+    console.log('Health:');
+    console.log(`  healthy:       ${result.health.healthy ? 'yes' : 'no'}`);
+    console.log(`  degraded:      ${result.health.degraded ? 'yes' : 'no'}`);
+    if (result.health.warnings.length > 0) {
+      console.log(`  warnings:`);
+      for (const w of result.health.warnings) {
+        console.log(`    - ${w}`);
+      }
+    }
+    console.log(`  lastCheckedAt: ${result.health.lastCheckedAt}`);
+    console.log('');
+    console.log('Capabilities:');
+    console.log(formatCapabilitiesTable(result.capabilities));
+    console.log('');
+
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    let errorCategory = 'execution_failed';
+    if (error instanceof PDRuntimeError) {
+      errorCategory = error.category;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        errorCategory,
+        message,
+        runtimeKind: 'openclaw-cli',
+      }, null, 2));
+    } else {
+      console.error(`error: ${message} (${errorCategory})`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * pi-ai probe branch — validates flags, calls probeRuntime, formats output.
+ */
+async function handlePiAiProbe(opts: RuntimeProbeOptions): Promise<void> {
+  // D-01: flags are required for pi-ai probe unless --workspace is provided (policy fallback)
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : undefined;
+  let provider = opts.provider ?? '';
+  let model = opts.model ?? '';
+  let apiKeyEnv = opts.apiKeyEnv ?? '';
+  let baseUrl = opts.baseUrl ?? '';
+  let {timeoutMs} = opts;
+
+  // D-01: always load workspace policy; CLI values take priority as override
+  if (workspaceDir) {
+    try {
+      const { resolveRuntimeConfig, isRuntimeConfigError } = await import('@principles/core/runtime-v2');
+      const configResult = resolveRuntimeConfig(path.join(workspaceDir, '.state'));
+      if (isRuntimeConfigError(configResult)) {
+        console.warn(`Warning: could not load workspace runtime config — ${configResult.message}`);
+      } else {
+        const config = configResult;
+        provider = provider || config.provider || '';
+        model = model || config.model || '';
+        apiKeyEnv = apiKeyEnv || config.apiKeyEnv || '';
+        baseUrl = baseUrl || config.baseUrl || '';
+        timeoutMs = timeoutMs ?? config.timeoutMs;
+      }
+    } catch (err) {
+      console.warn(`Warning: could not load workspace runtime config — policy fallback disabled: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (!provider) {
+    console.error("error: --provider is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
+    process.exit(1);
+  }
+  if (!model) {
+    console.error("error: --model is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
+    process.exit(1);
+  }
+  if (!apiKeyEnv) {
+    console.error("error: --apiKeyEnv is required for --runtime pi-ai (or set in --workspace workflows.yaml)");
+    console.error("  e.g.: pd runtime probe --runtime pi-ai --provider openrouter --model anthropic/claude-sonnet-4 --apiKeyEnv OPENROUTER_API_KEY");
+    process.exit(1);
+  }
+
+  // D-09: check env var exists before calling probeRuntime
+  if (!process.env[apiKeyEnv]) {
+    console.error(`error: environment variable '${apiKeyEnv}' is not set`);
+    process.exit(1);
+  }
+
+  try {
+    const result = await probeRuntime({
+      runtimeKind: 'pi-ai',
+      provider,
+      model,
+      apiKeyEnv,
+      baseUrl,
+      maxRetries: opts.maxRetries,
+      timeoutMs: timeoutMs ?? 120_000, // D-04: probe timeout 120s (matches Runtime defaults)
+    });
+
+    // Narrow to pi-ai result (TypeScript can't infer from input args alone)
+    if (result.runtimeKind !== 'pi-ai') {
+      throw new Error('unexpected: probeRuntime returned non-pi-ai result');
+    }
+
+    // Determine status from health
+    let exitCode = 0;
+    const status = !result.health.healthy ? 'failed'
+      : result.health.degraded ? 'degraded'
+      : 'succeeded';
+    if (!result.health.healthy) exitCode = 1;
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status,
+        runtimeKind: result.runtimeKind,
+        provider: result.provider,
+        model: result.model,
+        baseUrlPresent: !!baseUrl,
+        health: result.health,
+        capabilities: result.capabilities,
+      }, null, 2));
+      if (exitCode !== 0) process.exit(exitCode);
+      return;
+    }
+
+    // D-05: human-readable output
+    console.log(`\nRuntime: ${result.runtimeKind}`);
+    console.log(`Provider: ${result.provider}`);
+    console.log(`Model:    ${result.model}`);
+    if (baseUrl) console.log(`BaseUrl:  ${baseUrl}`);
+    console.log(`Status:   ${status}`);
+    console.log('');
+    console.log('Health:');
+    console.log(`  healthy:       ${result.health.healthy ? 'yes' : 'no'}`);
+    console.log(`  degraded:      ${result.health.degraded ? 'yes' : 'no'}`);
+    if (result.health.warnings.length > 0) {
+      console.log('  warnings:');
+      for (const w of result.health.warnings) {
+        console.log(`    - ${w}`);
+      }
+    }
+    console.log(`  lastCheckedAt: ${result.health.lastCheckedAt}`);
+    console.log('');
+    console.log('Capabilities:');
+    console.log(formatCapabilitiesTable(result.capabilities));
+    console.log('');
+
+    if (exitCode !== 0) process.exit(exitCode);
+  } catch (error: unknown) {
+    // D-10: test complete failure → error category + raw error
+    const message = error instanceof Error ? error.message : String(error);
+    let errorCategory = 'execution_failed';
+    if (error instanceof PDRuntimeError) {
+      errorCategory = error.category;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        errorCategory,
+        message,
+        runtimeKind: 'pi-ai',
+      }, null, 2));
+    } else {
+      console.error(`error: ${message} (${errorCategory})`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * pd runtime probe — dispatches to openclaw-cli or pi-ai branch.
+ */
+export async function handleRuntimeProbe(opts: RuntimeProbeOptions): Promise<void> {
+  if (opts.runtime === 'openclaw-cli') {
+    return handleOpenClawProbe(opts);
+  }
+
+  if (opts.runtime === 'pi-ai') {
+    return handlePiAiProbe(opts);
+  }
+
+  console.error(`error: unsupported --runtime '${opts.runtime}' (supported: openclaw-cli, pi-ai)`);
+  process.exit(1);
+}

package/src/commands/samples-list.ts

@@ -0,0 +1,43 @@
+/**
+ * pd samples list command implementation.
+ *
+ * Usage: pd samples list [--status pending|approved|rejected]
+ */
+
+import { listCorrectionSamples } from '@principles/core/trajectory-store';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface SamplesListOptions {
+  status?: 'pending' | 'approved' | 'rejected';
+}
+
+export async function handleSamplesList(opts: SamplesListOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir();
+  const status = opts.status ?? 'pending';
+
+  // eslint-disable-next-line @typescript-eslint/init-declarations
+  let samples;
+  try {
+    samples = listCorrectionSamples(workspaceDir, status);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes('ENOENT') || message.includes('SQLITE_CANTOPEN') || message.includes('SQLITE_NOTADB')) {
+      console.log('No correction samples found.');
+    } else {
+      console.error('Failed to list samples:', message);
+      throw err;
+    }
+    return;
+  }
+
+  if (samples.length === 0) {
+    console.log('No correction samples found.');
+    return;
+  }
+
+  console.log(`Correction Samples (${status}):`);
+  for (const sample of samples) {
+    console.log(`  [${sample.sampleId}] session=${sample.sessionId} score=${sample.qualityScore} created=${sample.createdAt}`);
+  }
+  console.log(`${samples.length} sample(s)`);
+}

package/src/commands/samples-review.ts

@@ -0,0 +1,32 @@
+/**
+ * pd samples review command implementation.
+ *
+ * Usage: pd samples review <sample-id> approve|reject [note]
+ */
+
+import { reviewCorrectionSample } from '@principles/core/trajectory-store';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+type ReviewDecision = 'approved' | 'rejected';
+
+interface SamplesReviewOptions {
+  sampleId: string;
+  decision: ReviewDecision;
+  note?: string;
+}
+
+export async function handleSamplesReview(opts: SamplesReviewOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir();
+
+  try {
+    reviewCorrectionSample(opts.sampleId, opts.decision, opts.note, workspaceDir);
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('Sample not found')) {
+      console.error(`Error: Sample not found: ${opts.sampleId}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  console.log(`Sample ${opts.sampleId} marked as ${opts.decision}`);
+}

package/src/commands/task.ts

@@ -0,0 +1,130 @@
+/**
+ * pd task list/show commands — Runtime v2 task inspection.
+ *
+ * Usage:
+ *   pd task list [--status <status>] [--kind <kind>] [--limit <n>]
+ *   pd task show <taskId>
+ */
+import * as path from 'path';
+import { RuntimeStateManager } from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface TaskListOptions {
+  status?: string;
+  kind?: string;
+  limit?: number;
+}
+
+export async function handleTaskList(opts: TaskListOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+
+  try {
+    const filter: Record<string, string | number> = {};
+    if (opts.status) filter.status = opts.status;
+    if (opts.kind) filter.taskKind = opts.kind;
+    if (opts.limit) filter.limit = opts.limit;
+
+     
+    const tasks = await stateManager.listTasks(Object.keys(filter).length > 0 ? filter : undefined);
+
+    if (tasks.length === 0) {
+      console.log('No tasks found.');
+      return;
+    }
+
+    console.log(`\nTasks (${tasks.length}):\n`);
+    console.log(
+      '%-22s %-12s %-10s %-4s/%-4s %-15s %s',
+      'TASK_ID', 'KIND', 'STATUS', 'ATT', 'MAX', 'LEASE_OWNER', 'LEASE_EXPIRES',
+    );
+    console.log('-'.repeat(90));
+
+    for (const task of tasks) {
+      const expiresAt = task.leaseExpiresAt
+        ? new Date(task.leaseExpiresAt).toLocaleString()
+        : '-';
+      console.log(
+        '%-22s %-12s %-10s %-4s %-4s %-15s %s',
+        task.taskId.substring(0, 22),
+        task.taskKind.substring(0, 12),
+        task.status,
+        task.attemptCount,
+        task.maxAttempts,
+        task.leaseOwner ?? '-',
+        expiresAt.substring(0, 19),
+      );
+    }
+    console.log('');
+  } finally {
+    await stateManager.close();
+  }
+}
+
+interface TaskShowOptions {
+  id: string;
+  json?: boolean;
+  workspace?: string;
+}
+
+export async function handleTaskShow(opts: TaskShowOptions): Promise<void> {
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+
+  try {
+    const task = await stateManager.getTask(opts.id);
+
+    if (!task) {
+      console.error(`Task not found: ${opts.id}`);
+      process.exit(1);
+    }
+
+    const runs = await stateManager.getRunsByTask(opts.id);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ task, runs }, null, 2));
+      return;
+    }
+
+    console.log(`\nTask: ${task.taskId}\n`);
+    console.log(`  Kind:          ${task.taskKind}`);
+    console.log(`  Status:        ${task.status}`);
+    console.log(`  Attempts:      ${task.attemptCount} / ${task.maxAttempts}`);
+    if (task.leaseOwner) {
+      console.log(`  Lease Owner:   ${task.leaseOwner}`);
+      console.log(`  Lease Expires: ${task.leaseExpiresAt ? new Date(task.leaseExpiresAt).toLocaleString() : '-'}`);
+    }
+    if (task.lastError) {
+      console.log(`  Last Error:    ${task.lastError}`);
+    }
+    if (task.inputRef) {
+      console.log(`  Input Ref:     ${task.inputRef}`);
+    }
+    if (task.resultRef) {
+      console.log(`  Result Ref:    ${task.resultRef}`);
+    }
+    console.log(`  Created:       ${new Date(task.createdAt).toLocaleString()}`);
+    console.log(`  Updated:       ${new Date(task.updatedAt).toLocaleString()}`);
+    console.log('');
+
+    if (runs.length > 0) {
+      console.log(`Runs (${runs.length}):`);
+      console.log('  %-22s %-12s %-6s %s', 'RUN_ID', 'STATUS', 'ATT', 'STARTED');
+      console.log('  ' + '-'.repeat(65));
+      for (const run of runs) {
+        console.log(
+          '  %-22s %-12s %-6s %s',
+          run.runId.substring(0, 22),
+          run.executionStatus,
+          run.attemptNumber,
+          new Date(run.startedAt).toLocaleString(),
+        );
+      }
+      console.log('');
+    }
+  } finally {
+    await stateManager.close();
+  }
+}

package/src/commands/trace.ts

@@ -0,0 +1,174 @@
+/**
+ * pd runtime trace show command — full pain-to-ledger chain trace.
+ *
+ * Usage: pd runtime trace show --pain-id <id> [--workspace <path>] [--json]
+ *
+ * Traces the complete pain→task→run→artifact→candidate→ledger chain
+ * and reports consistency, latency, and failure classification.
+ *
+ * PRI-129: Migrated from direct store/ledger usage
+ * to PainChainReadModel (ADR-0001 boundary compliance).
+ */
+
+import * as path from 'path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { PainChainReadModel } from '@principles/core/runtime-v2';
+import type { PainChainTrace, PainChainTraceLatencyMs } from '@principles/core/runtime-v2';
+
+interface TraceResult {
+  painId: string;
+  taskId: string;
+  runId?: string;
+  artifactId?: string;
+  candidateIds: string[];
+  ledgerEntryIds: string[];
+  status: string;
+  latencyMs: PainChainTraceLatencyMs;
+  failureCategory: string | null;
+  checkedAt: string;
+  missingLinks: string[];
+}
+
+interface TraceOptions {
+  painId: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+function formatNoTaskResult(opts: TraceOptions, workspaceDir: string, checkedAt: string) {
+  const taskId = `diagnosis_${opts.painId}`;
+  return {
+    painId: opts.painId,
+    taskId,
+    status: 'not_found' as const,
+    failureCategory: 'runtime_unavailable' as const,
+    message: `No task found for painId: ${opts.painId}`,
+    workspace: workspaceDir,
+    checkedAt,
+    missingLinks: ['task' as const],
+  };
+}
+
+function outputResult(result: TraceResult, opts: TraceOptions): void {
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Pain ID:       ${result.painId}`);
+  console.log(`Task ID:       ${result.taskId}`);
+  console.log(`Status:        ${result.status}`);
+  if (result.runId) console.log(`Run ID:        ${result.runId}`);
+  if (result.artifactId) console.log(`Artifact ID:   ${result.artifactId}`);
+  if (result.candidateIds.length > 0) console.log(`Candidate IDs:  ${result.candidateIds.join(', ')}`);
+  if (result.ledgerEntryIds.length > 0) console.log(`Ledger Entries: ${result.ledgerEntryIds.join(', ')}`);
+  if (result.failureCategory) console.log(`Failure:       ${result.failureCategory}`);
+  console.log(`Checked at:    ${result.checkedAt}`);
+
+  if (Object.keys(result.latencyMs).length > 0) {
+    console.log('\nLatency:');
+    if (result.latencyMs.painToTask) console.log(`  pain→task:          ${result.latencyMs.painToTask}ms`);
+    if (result.latencyMs.taskToRun) console.log(`  task→run:           ${result.latencyMs.taskToRun}ms`);
+    if (result.latencyMs.runToArtifact) console.log(`  run→artifact:       ${result.latencyMs.runToArtifact}ms`);
+    if (result.latencyMs.artifactToCandidate) console.log(`  artifact→candidate: ${result.latencyMs.artifactToCandidate}ms`);
+    if (result.latencyMs.candidateToLedger) console.log(`  candidate→ledger:   ${result.latencyMs.candidateToLedger}ms`);
+  }
+
+  if (result.missingLinks.length > 0) {
+    console.log(`\nMissing links (${result.missingLinks.length}):`);
+    for (const link of result.missingLinks) {
+      console.log(`  - ${link}`);
+    }
+  }
+}
+
+export async function handleTraceShow(opts: TraceOptions): Promise<void> {
+  if (!opts.painId) {
+    console.error('Error: --pain-id <id> is required');
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const readModel = new PainChainReadModel({ workspaceDir });
+
+  try {
+    const trace: PainChainTrace = await readModel.traceByPainId(opts.painId);
+
+    if (trace.status === 'not_found') {
+      const noTaskResult = formatNoTaskResult(opts, workspaceDir, trace.checkedAt);
+      if (opts.json) {
+        console.log(JSON.stringify(noTaskResult, null, 2));
+      } else {
+        console.error(`Error: No task found for painId: ${opts.painId}`);
+        console.error(`  Derived taskId: ${noTaskResult.taskId}`);
+        console.error(`  Workspace: ${workspaceDir}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    if (trace.status === 'error') {
+      const isConfigError = trace.failureCategory === 'config_missing';
+      if (opts.json) {
+        console.log(JSON.stringify({
+          painId: trace.painId,
+          taskId: trace.taskId,
+          status: 'error',
+          failureCategory: trace.failureCategory,
+          message: isConfigError
+            ? 'Failed to initialize state manager'
+            : 'Internal error during trace',
+          checkedAt: trace.checkedAt,
+          missingLinks: trace.missingLinks,
+        }, null, 2));
+      } else {
+        console.error(`Error: ${isConfigError ? 'Failed to open workspace' : 'Internal error during trace'}`);
+        console.error(`  Workspace: ${workspaceDir}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const result: TraceResult = {
+      painId: trace.painId,
+      taskId: trace.taskId,
+      runId: trace.runId,
+      artifactId: trace.artifactId,
+      candidateIds: trace.candidateIds,
+      ledgerEntryIds: trace.ledgerEntryIds,
+      status: trace.status,
+      latencyMs: trace.latencyMs,
+      failureCategory: trace.failureCategory,
+      checkedAt: trace.checkedAt,
+      missingLinks: trace.missingLinks,
+    };
+
+    outputResult(result, opts);
+
+    if (result.status === 'error' || result.status === 'failed' || result.status === 'degraded') {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({
+        painId: opts.painId,
+        taskId: `diagnosis_${opts.painId}`,
+        status: 'error',
+        failureCategory: 'runtime_unavailable',
+        message: msg,
+        checkedAt: new Date().toISOString(),
+        missingLinks: ['internal_error'],
+      }, null, 2));
+    } else {
+      console.error(`Error: ${msg}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    await readModel.close();
+  }
+}