create-principles-disciple 1.0.0 → 1.74.0

package/core/dist/runtime-v2/candidate-intake.js

@@ -0,0 +1,178 @@
+/**
+ * Candidate Intake Contract — M7 schema and interface definitions.
+ *
+ * Defines the intake boundary: input/output schemas, the ledger entry
+ * contract, the LedgerAdapter interface, and intake error codes.
+ *
+ * Implementation logic (CandidateIntakeService) lives in m7-03.
+ *
+ * Non-goals (M7):
+ * - No pain signal auto-trigger (M8)
+ * - No legacy evolution-worker deletion (M9)
+ * - No promote to active principle
+ * - No direct ledger write from SqliteDiagnosticianCommitter
+ *
+ * =============================================================================
+ * FIELD PROVENANCE MAP
+ * =============================================================================
+ *
+ * Every field in LedgerPrincipleEntry flows from exactly one origin:
+ *
+ * │ Field             │ Origin                          │ Reliability │
+ * │-------------------|----------------------------------|-------------│
+ * │ id                │ Service-generated (UUID v4)      │ Always      │
+ * │ title             │ Extracted from artifact          │ Always      │
+ * │ text              │ Extracted from artifact          │ Always      │
+ * │ triggerPattern    │ Extracted from artifact          │ Optional    │
+ * │ action            │ Extracted from artifact          │ Optional    │
+ * │ status            │ Fixed: 'probation'              │ Always      │
+ * │ evaluability      │ Fixed: 'weak_heuristic'          │ Always      │
+ * │ sourceRef         │ Constructed: candidate://<id>   │ Always      │
+ * │ artifactRef       │ Constructed: artifact://<id>    │ Optional    │
+ * │ taskRef           │ Constructed: task://<id>        │ Optional    │
+ * │ createdAt         │ Service-generated (ISO 8601)   │ Always      │
+ *
+ * =============================================================================
+ * LEDGER PRINCIPLE ENTRY — 18 FIELD DEFAULT VALUES
+ * =============================================================================
+ *
+ * When the intake service expands a LedgerPrincipleEntry into a full
+ * LedgerPrinciple, it applies these defaults (m7-03):
+ *
+ *   id:               Generated UUID v4
+ *   title:            From artifact extraction
+ *   text:             From artifact extraction
+ *   triggerPattern:   null (absent if not extracted)
+ *   action:           null (absent if not extracted)
+ *   status:           'probation'
+ *   evaluability:     'weak_heuristic'
+ *   sourceRef:        'candidate://<candidateId>'
+ *   artifactRef:      'artifact://<artifactId>' (if artifactId known)
+ *   taskRef:          null (absent in M7; M8+ may populate)
+ *   createdAt:        new Date().toISOString()
+ *
+ *   -- M7 does NOT set (M8/M9 concerns):
+ *   promotedAt:       undefined
+ *   promotedBy:       undefined
+ *   archivedAt:       undefined
+ *   archivedBy:       undefined
+ *   archivedReason:   undefined
+ *   experimentTags:   undefined
+ *   principleNotes:   undefined
+ *   reviewCycle:      undefined
+ */
+import { Type } from '@sinclair/typebox';
+// ── Schema ────────────────────────────────────────────────────────────────
+export const CandidateIntakeInputSchema = Type.Object({
+    candidateId: Type.String({ minLength: 1 }),
+    workspaceDir: Type.String({ minLength: 1 }),
+});
+export const CandidateIntakeOutputSchema = Type.Object({
+    candidateId: Type.String(),
+    artifactId: Type.String(),
+    ledgerRef: Type.String(),
+    status: Type.Literal('consumed'),
+});
+/**
+ * Ledger principle entry written during candidate intake.
+ *
+ * Provenance annotations (@provenance):
+ *
+ * @provenance id               — Service-generated UUID v4. Never from artifact.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *
+ * @provenance title            — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle text/title.
+ *
+ * @provenance text             — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle body content.
+ *
+ * @provenance triggerPattern    — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no trigger.
+ *
+ * @provenance action            — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no action.
+ *
+ * @provenance status            — Fixed value. Always 'probation' on intake.
+ *                               Never from artifact. Governed by promotion gate (M8).
+ *
+ * @provenance evaluability      — Fixed value. Always 'weak_heuristic' on intake.
+ *                               Never from artifact. Governed by evaluation strategy (M8).
+ *
+ * @provenance sourceRef         — Constructed by service. Idempotency key.
+ *                               Format: `candidate://<candidateId>`
+ *                               @provenance Always constructed from input candidateId.
+ *                               NOT derived from artifact artifactId (D-11).
+ *
+ * @provenance artifactRef       — Constructed by service, only if artifactId known.
+ *                               Format: `artifact://<artifactId>`
+ *                               @provenance Derived from artifactId in intake input.
+ *                               @nullable Omit from entry when artifactId is not available.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance taskRef           — Constructed by service (optional, M7 not populated).
+ *                               Format: `task://<taskId>`
+ *                               @provenance Reserved for M8+ task linking.
+ *                               @nullable Omit from entry in M7.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance createdAt         — Service-generated ISO 8601 timestamp.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *                               NOT from artifact.
+ */
+export const LedgerPrincipleEntrySchema = Type.Object({
+    id: Type.String(),
+    title: Type.String(),
+    text: Type.String(),
+    triggerPattern: Type.Optional(Type.String()),
+    action: Type.Optional(Type.String()),
+    status: Type.Literal('probation'),
+    evaluability: Type.Literal('weak_heuristic'),
+    sourceRef: Type.String(), // candidate://<candidateId> — idempotency key
+    artifactRef: Type.Optional(Type.String()), // artifact://<artifactId> — traceability only
+    taskRef: Type.Optional(Type.String()), // task://<taskId> — traceability only
+    createdAt: Type.String(),
+});
+// ── Errors ───────────────────────────────────────────────────────────────
+/**
+ * Error codes for candidate intake operations.
+ *
+ * @error INPUT_INVALID           — Input validation failed (missing/invalid fields).
+ * @error CANDIDATE_NOT_FOUND    — Candidate ID does not exist in workspace.
+ * @error ARTIFACT_NOT_FOUND     — Artifact ID does not exist in workspace.
+ * @error CANDIDATE_ALREADY_CONSUMED — Ledger entry exists for this candidate;
+ *                                  returned as idempotent success (D-10),
+ *                                  NOT an error. This code is reserved for
+ *                                  data-corruption detection: DB claims
+ *                                  consumed but no ledger entry found.
+ * @error LEDGER_WRITE_FAILED     — Ledger write operation failed.
+ */
+export const INTAKE_ERROR_CODES = {
+    CANDIDATE_NOT_FOUND: 'candidate_not_found',
+    CANDIDATE_ALREADY_CONSUMED: 'candidate_already_consumed',
+    ARTIFACT_NOT_FOUND: 'artifact_not_found',
+    LEDGER_WRITE_FAILED: 'ledger_write_failed',
+    INPUT_INVALID: 'input_invalid',
+};
+/**
+ * Candidate intake error with structured code and optional context.
+ *
+ * Use INTAKE_ERROR_CODES for the code value.
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.CANDIDATE_NOT_FOUND, 'Candidate cand-1 not found');
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.LEDGER_WRITE_FAILED, 'Ledger write failed', { cause: err });
+ */
+export class CandidateIntakeError extends Error {
+    code;
+    context;
+    constructor(code, message, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'CandidateIntakeError';
+    }
+}
+//# sourceMappingURL=candidate-intake.js.map

package/core/dist/runtime-v2/candidate-intake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-intake.js","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAEtD,6EAA6E;AAE7E,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC1C,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;CAC5C,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CAAC;IACrD,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;IAC1B,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE;IACzB,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;IACxB,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;CACjC,CAAC,CAAC;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;IACpB,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;IACnB,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACpC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACjC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAC5C,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAA2B,8CAA8C;IACjG,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAY,8CAA8C;IACnG,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAe,sCAAsC;IAC1F,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC;AAIH,4EAA4E;AAE5E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,mBAAmB,EAAE,qBAAqB;IAC1C,0BAA0B,EAAE,4BAA4B;IACxD,kBAAkB,EAAE,oBAAoB;IACxC,mBAAmB,EAAE,qBAAqB;IAC1C,aAAa,EAAE,eAAe;CACtB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAE3B;IAEA;IAHlB,YACkB,IAAkE,EAClF,OAAe,EACC,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAA8D;QAElE,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/core/dist/runtime-v2/cli/diagnose.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CLI surface for diagnostician execution.
+ *
+ * Per D-02: Library function exports, no bin scripts, no CLI framework dependency.
+ * External code (e.g., OpenClaw plugin) imports and calls these functions.
+ *
+ * Per D-03: status() returns TaskRecord key fields only (taskId, status, attemptCount, maxAttempts, lastError).
+ * No Run history.
+ */
+import type { RuntimeStateManager, CandidateRecord } from '../store/runtime-state-manager.js';
+import type { DiagnosticianRunner } from '../runner/diagnostician-runner.js';
+import type { RunnerResult } from '../runner/runner-result.js';
+import type { TaskRecord } from '../task-status.js';
+import type { LedgerAdapter } from '../candidate-intake.js';
+/** Options for pd candidate list */
+export interface CandidateListOptions {
+    taskId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd candidate list */
+export interface CandidateListResult {
+    readonly taskId: string;
+    readonly candidates: readonly CandidateRecord[];
+}
+/** Options for pd candidate show */
+export interface CandidateShowOptions {
+    candidateId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd candidate show */
+export interface CandidateShowResult {
+    readonly candidateId: string;
+    readonly artifactId: string;
+    readonly taskId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly confidence: number | null;
+    readonly sourceRunId: string;
+    readonly status: 'pending' | 'consumed' | 'expired';
+    readonly createdAt: string;
+    readonly ledgerEntryId: string | null;
+}
+/** Options for pd artifact show */
+export interface ArtifactShowOptions {
+    artifactId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd artifact show */
+export interface ArtifactShowResult {
+    readonly artifactId: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly artifactKind: string;
+    readonly contentJson: string;
+    readonly createdAt: string;
+    readonly candidates: readonly CandidateRecord[];
+}
+/** Options for the run() CLI function. */
+export interface DiagnoseRunOptions {
+    /** Task ID to execute diagnostician for. */
+    taskId: string;
+    /** Initialized RuntimeStateManager instance. */
+    stateManager: RuntimeStateManager;
+    /** DiagnosticianRunner instance (already configured with deps). */
+    runner: DiagnosticianRunner;
+}
+/** Options for the status() CLI function. */
+export interface DiagnoseStatusOptions {
+    /** Task ID to inspect. */
+    taskId: string;
+    /** Initialized RuntimeStateManager instance. */
+    stateManager: RuntimeStateManager;
+}
+/** Structured status result per D-03, extended per CLIV-04 for commit/candidate info. */
+export interface DiagnoseStatusResult {
+    readonly taskId: string;
+    readonly status: TaskRecord['status'];
+    readonly attemptCount: number;
+    readonly maxAttempts: number;
+    readonly lastError: TaskRecord['lastError'];
+    /** Populated only when status is 'succeeded' — the committed commit ID */
+    readonly commitId: string | null;
+    /** Populated only when status is 'succeeded' — the committed artifact ID */
+    readonly artifactId: string | null;
+    /** Populated only when status is 'succeeded' — number of candidates registered */
+    readonly candidateCount: number | null;
+}
+/**
+ * Execute the diagnostician runner for a task.
+ *
+ * Thin wrapper over DiagnosticianRunner.run().
+ * Returns the raw RunnerResult for full visibility.
+ */
+export declare function run(options: DiagnoseRunOptions): Promise<RunnerResult>;
+/**
+ * Inspect diagnostician task status.
+ *
+ * Per D-03: Returns key TaskRecord fields only.
+ * Returns null if the task does not exist.
+ */
+export declare function status(options: DiagnoseStatusOptions): Promise<DiagnoseStatusResult | null>;
+/**
+ * List principle candidates for a task.
+ *
+ * Per CLIV-01: pd candidate list --task-id <taskId>
+ * Per D-05: joins through tasks→runs→commits→principle_candidates
+ */
+export declare function candidateList(options: CandidateListOptions): Promise<CandidateListResult>;
+/**
+ * Show detail for a single candidate.
+ *
+ * Per CLIV-02: pd candidate show <candidateId>
+ * Returns title, description, confidence, source (runId), status
+ * Returns null if candidate not found.
+ */
+export declare function candidateShow(options: CandidateShowOptions & {
+    ledgerAdapter?: LedgerAdapter;
+}): Promise<CandidateShowResult | null>;
+/**
+ * Show artifact content and its associated candidates.
+ *
+ * Per CLIV-03: pd artifact show <artifactId>
+ * Per D-06: single query with JOIN, returns artifact + inline candidates array
+ * Returns null if artifact not found.
+ */
+export declare function artifactShow(options: ArtifactShowOptions): Promise<ArtifactShowResult | null>;
+//# sourceMappingURL=diagnose.d.ts.map

package/core/dist/runtime-v2/cli/diagnose.d.ts.map

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

package/core/dist/runtime-v2/cli/diagnose.js

@@ -0,0 +1,113 @@
+/**
+ * Execute the diagnostician runner for a task.
+ *
+ * Thin wrapper over DiagnosticianRunner.run().
+ * Returns the raw RunnerResult for full visibility.
+ */
+export async function run(options) {
+    return options.runner.run(options.taskId);
+}
+/**
+ * Inspect diagnostician task status.
+ *
+ * Per D-03: Returns key TaskRecord fields only.
+ * Returns null if the task does not exist.
+ */
+export async function status(options) {
+    const task = await options.stateManager.getTask(options.taskId);
+    if (!task) {
+        return null;
+    }
+    // Per CLIV-04: populate commit fields only for succeeded tasks
+    let commitId = null;
+    let artifactId = null;
+    let candidateCount = null;
+    if (task.status === 'succeeded') {
+        const commit = await options.stateManager.getCommitByTaskId(options.taskId);
+        if (commit) {
+            const { commitId: cid, artifactId: aid } = commit;
+            commitId = cid;
+            artifactId = aid;
+            const candidates = await options.stateManager.getCandidatesByTaskId(options.taskId);
+            candidateCount = candidates.length;
+        }
+    }
+    return {
+        taskId: task.taskId,
+        status: task.status,
+        attemptCount: task.attemptCount,
+        maxAttempts: task.maxAttempts,
+        lastError: task.lastError,
+        commitId,
+        artifactId,
+        candidateCount,
+    };
+}
+/**
+ * List principle candidates for a task.
+ *
+ * Per CLIV-01: pd candidate list --task-id <taskId>
+ * Per D-05: joins through tasks→runs→commits→principle_candidates
+ */
+export async function candidateList(options) {
+    const candidates = await options.stateManager.getCandidatesByTaskId(options.taskId);
+    return {
+        taskId: options.taskId,
+        candidates,
+    };
+}
+/**
+ * Show detail for a single candidate.
+ *
+ * Per CLIV-02: pd candidate show <candidateId>
+ * Returns title, description, confidence, source (runId), status
+ * Returns null if candidate not found.
+ */
+export async function candidateShow(options) {
+    const candidate = await options.stateManager.getCandidate(options.candidateId);
+    if (!candidate) {
+        return null;
+    }
+    let ledgerEntryId = null;
+    if (options.ledgerAdapter) {
+        const entry = options.ledgerAdapter.existsForCandidate(options.candidateId);
+        if (entry) {
+            ledgerEntryId = entry.id;
+        }
+    }
+    return {
+        candidateId: candidate.candidateId,
+        artifactId: candidate.artifactId,
+        taskId: candidate.taskId,
+        title: candidate.title,
+        description: candidate.description,
+        confidence: candidate.confidence,
+        sourceRunId: candidate.sourceRunId,
+        status: candidate.status,
+        createdAt: candidate.createdAt,
+        ledgerEntryId,
+    };
+}
+/**
+ * Show artifact content and its associated candidates.
+ *
+ * Per CLIV-03: pd artifact show <artifactId>
+ * Per D-06: single query with JOIN, returns artifact + inline candidates array
+ * Returns null if artifact not found.
+ */
+export async function artifactShow(options) {
+    const result = await options.stateManager.getArtifactWithCandidates(options.artifactId);
+    if (!result) {
+        return null;
+    }
+    return {
+        artifactId: result.artifact.artifactId,
+        runId: result.artifact.runId,
+        taskId: result.artifact.taskId,
+        artifactKind: result.artifact.artifactKind,
+        contentJson: result.artifact.contentJson,
+        createdAt: result.artifact.createdAt,
+        candidates: result.candidates,
+    };
+}
+//# sourceMappingURL=diagnose.js.map

package/core/dist/runtime-v2/cli/diagnose.js.map

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

package/core/dist/runtime-v2/cli/index.d.ts

@@ -0,0 +1,5 @@
+export { run, status, candidateList, candidateShow, artifactShow } from './diagnose.js';
+export type { DiagnoseRunOptions, DiagnoseStatusOptions, DiagnoseStatusResult, CandidateListOptions, CandidateShowOptions, ArtifactShowOptions } from './diagnose.js';
+export { probeRuntime } from './probe.js';
+export type { ProbeOptions, ProbeResult } from './probe.js';
+//# sourceMappingURL=index.d.ts.map

package/core/dist/runtime-v2/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACxF,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEtK,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/core/dist/runtime-v2/cli/index.js

@@ -0,0 +1,3 @@
+export { run, status, candidateList, candidateShow, artifactShow } from './diagnose.js';
+export { probeRuntime } from './probe.js';
+//# sourceMappingURL=index.js.map

package/core/dist/runtime-v2/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime-v2/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGxF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/core/dist/runtime-v2/cli/probe.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeHealth, RuntimeCapabilities } from '../runtime-protocol.js';
+export type ProbeOptions = {
+    runtimeKind: 'openclaw-cli';
+    /** 'local' or 'gateway' — required, no silent fallback (HG-03, DPB-09) */
+    runtimeMode: 'local' | 'gateway';
+    workspaceDir?: string;
+    /** Agent ID to verify availability (default: 'diagnostician') */
+    agentId?: string;
+} | {
+    runtimeKind: 'pi-ai';
+    provider: string;
+    model: string;
+    apiKeyEnv: string;
+    /** Custom base URL for OpenAI-compatible providers not in pi-ai's built-in registry. */
+    baseUrl?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+};
+export type ProbeResult = {
+    runtimeKind: 'openclaw-cli';
+    health: RuntimeHealth;
+    capabilities: RuntimeCapabilities;
+} | {
+    runtimeKind: 'pi-ai';
+    health: RuntimeHealth;
+    capabilities: RuntimeCapabilities;
+    provider: string;
+    model: string;
+};
+export declare function probeRuntime(options: ProbeOptions): Promise<ProbeResult>;
+//# sourceMappingURL=probe.d.ts.map

package/core/dist/runtime-v2/cli/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/cli/probe.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEjF,MAAM,MAAM,YAAY,GACpB;IACE,WAAW,EAAE,cAAc,CAAC;IAC5B,0EAA0E;IAC1E,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,MAAM,MAAM,WAAW,GACnB;IACE,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,mBAAmB,CAAC;CACnC,GACD;IACE,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,mBAAmB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAgD9E"}

package/core/dist/runtime-v2/cli/probe.js

@@ -0,0 +1,58 @@
+/**
+ * probeRuntime — Library function for probing a runtime's health and capabilities.
+ *
+ * Can be called from CLI or other code.
+ *
+ * Discriminated union on runtimeKind:
+ *   'openclaw-cli' — uses OpenClawCliRuntimeAdapter
+ *   'pi-ai'       — uses PiAiRuntimeAdapter (requires provider/model/apiKeyEnv/baseUrl)
+ *
+ * @throws Error if runtimeKind is unsupported
+ * @throws PDRuntimeError if probe fails
+ */
+import { OpenClawCliRuntimeAdapter } from '../adapter/openclaw-cli-runtime-adapter.js';
+import { PiAiRuntimeAdapter } from '../adapter/pi-ai-runtime-adapter.js';
+export async function probeRuntime(options) {
+    if (options.runtimeKind === 'openclaw-cli') {
+        // HG-03 (HARD GATE): runtimeMode is always explicitly provided by CLI layer.
+        // probeRuntime itself requires runtimeMode to be set (no silent fallback).
+        // P1 #3 fix: Pass agentId so healthCheck can verify the specific agent is available.
+        const adapter = new OpenClawCliRuntimeAdapter({
+            runtimeMode: options.runtimeMode,
+            workspaceDir: options.workspaceDir,
+            agentId: options.agentId,
+        });
+        const [health, capabilities] = await Promise.all([
+            adapter.healthCheck(),
+            adapter.getCapabilities(),
+        ]);
+        return {
+            runtimeKind: 'openclaw-cli',
+            health,
+            capabilities,
+        };
+    }
+    if (options.runtimeKind === 'pi-ai') {
+        const adapter = new PiAiRuntimeAdapter({
+            provider: options.provider,
+            model: options.model,
+            apiKeyEnv: options.apiKeyEnv,
+            baseUrl: options.baseUrl,
+            maxRetries: options.maxRetries,
+            timeoutMs: options.timeoutMs,
+        });
+        const [health, capabilities] = await Promise.all([
+            adapter.healthCheck(),
+            adapter.getCapabilities(),
+        ]);
+        return {
+            runtimeKind: 'pi-ai',
+            health,
+            capabilities,
+            provider: options.provider,
+            model: options.model,
+        };
+    }
+    throw new Error(`Unsupported runtime kind: ${options.runtimeKind}`);
+}
+//# sourceMappingURL=probe.js.map

package/core/dist/runtime-v2/cli/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../src/runtime-v2/cli/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAqCzE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAqB;IACtD,IAAI,OAAO,CAAC,WAAW,KAAK,cAAc,EAAE,CAAC;QAC3C,6EAA6E;QAC7E,2EAA2E;QAC3E,qFAAqF;QACrF,MAAM,OAAO,GAAG,IAAI,yBAAyB,CAAC;YAC5C,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC/C,OAAO,CAAC,WAAW,EAAE;YACrB,OAAO,CAAC,eAAe,EAAE;SAC1B,CAAC,CAAC;QAEH,OAAO;YACL,WAAW,EAAE,cAAc;YAC3B,MAAM;YACN,YAAY;SACb,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC;YACrC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC/C,OAAO,CAAC,WAAW,EAAE;YACrB,OAAO,CAAC,eAAe,EAAE;SAC1B,CAAC,CAAC;QAEH,OAAO;YACL,WAAW,EAAE,OAAO;YACpB,MAAM;YACN,YAAY;YACZ,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6BAA8B,OAAmC,CAAC,WAAW,EAAE,CAAC,CAAC;AACnG,CAAC"}