@openclawbrain/openclaw 0.2.2 → 0.3.0

package/dist/src/index.d.ts

@@ -1,7 +1,10 @@
-import { CONTRACT_IDS, type ArtifactManifestV1, type ActivationPointerRecordV1, type ActivationPointerSlot, type RuntimeTurnBrainAttachmentPolicyV1, type ContextCompactionMode, type ContextContributionEvidenceStateV1, type CurrentProfileBrainStatusAnswerV1, type CurrentProfileStructuralDecisionV1, type FeedbackEventKind, type PackGraphEvolutionV1, type FeedbackEventV1, type KernelSurfaceValidationResultV1, type LearningBootProfile, type LearningScanPolicy, type InteractionEventV1, type NormalizedEventExportV1, type NormalizedEventV1, type PrincipalPriorityClassV1, type PrincipalRoleV1, type RouteMode, type RuntimeCompileResponseV1, type RuntimeCompileStructuralSignalsV1, type RuntimeCompileTargetV1, type RuntimeGraphPlasticityStateV1, type RuntimePlasticitySourceV1, type SparseFeedbackPolicyV1, type TeacherAuthorityV1, type TeacherSupervisionArtifactV1, type WorkspaceInjectionSurfaceV1 } from "@openclawbrain/contracts";
+import { type CompileSelectionMode } from "@openclawbrain/compiler";
+import { CONTRACT_IDS, type ArtifactManifestV1, type ActivationPointerRecordV1, type ActivationPointerSlot, type RuntimeTurnBrainAttachmentPolicyV1, type ContextCompactionMode, type ContextContributionEvidenceStateV1, type CurrentProfileBrainStatusAnswerV1, type CurrentProfileActivationStateV1, type CurrentProfileStructuralDecisionV1, type FeedbackEventKind, type PackGraphEvolutionV1, type FeedbackEventV1, type KernelSurfaceValidationResultV1, type LearningBootProfile, type LearningCadence, type LearningScanPolicy, type InteractionEventV1, type NormalizedEventExportV1, type NormalizedEventV1, type PrincipalPriorityClassV1, type PrincipalRoleV1, type RouteMode, type RuntimeCompileResponseV1, type RuntimeCompileStructuralSignalsV1, type RuntimeCompileTargetV1, type RuntimeGraphPlasticityStateV1, type RuntimePlasticitySourceV1, type SparseFeedbackPolicyV1, type TeacherAuthorityV1, type TeacherSupervisionArtifactV1, type WorkspaceInjectionSurfaceV1 } from "@openclawbrain/contracts";
 import { type EventExportLaneV1 } from "@openclawbrain/event-export";
-import { type AdvanceAlwaysOnLearningRuntimeInput, type AlwaysOnLearningCadenceV1, type AlwaysOnLearningMaterializationJobV1, type AlwaysOnLearningRuntimePlanV1, type AlwaysOnLearningRuntimeStateV1, type PendingPrincipalEventV1, type PrincipalLearningCheckpointV1 } from "@openclawbrain/learner";
-import { type ActivationInspection, type ActivationObservabilityReport, type GraphEvolutionLogV1, type ActivationSlotInspection, type InitHandoffState } from "@openclawbrain/pack-format";
+import { type AdvanceAlwaysOnLearningRuntimeInput, type AlwaysOnLearningCadenceV1, type AlwaysOnLearningMaterializationJobV1, type AlwaysOnLearningRuntimePlanV1, type AlwaysOnLearningRuntimeStateV1, type BaselineStateV1, type PendingPrincipalEventV1, type PrincipalLearningCheckpointV1 } from "@openclawbrain/learner";
+import { type ActivationInspection, type ActivationObservabilityReport, type GraphEvolutionLogV1, type LearningSpineServeRouteBreadcrumbsV1, type ActivationSlotInspection, type InitHandoffState, type LearningSpineServeRouteDecisionLogEntryV1 } from "@openclawbrain/pack-format";
+import { type AsyncTeacherLabelerConfigV1 } from "./teacher-labeler.js";
+export { createHttpOllamaTeacherLabelerClient, createOllamaTeacherLabeler, createTeacherLabeler, type AsyncTeacherLabelerConfigV1, type AsyncTeacherNoopLabelerConfigV1, type AsyncTeacherOllamaLabelerConfigV1, type OllamaTeacherLabelerClient, type TeacherLabeler, type TeacherLabelerResultV1, type TeacherLabelerRunInputV1 } from "./teacher-labeler.js";
 export declare const DEFAULT_ASYNC_TEACHER_QUEUE_CAPACITY = 8;
 declare const RECORDED_SESSION_TRACE_CONTRACT: "recorded_session_trace.v1";
 declare const RECORDED_SESSION_FIXTURE_CONTRACT: "recorded_session_replay_fixture.v1";
@@ -11,6 +14,11 @@ export declare const RUNTIME_EVENT_EXPORT_BUNDLE_LAYOUT: {
     readonly manifest: "manifest.json";
     readonly payload: "normalized-event-export.json";
 };
+export interface CompileServeRouteBreadcrumbInput {
+    invocationSurface: LearningSpineServeRouteBreadcrumbsV1["invocationSurface"];
+    hostEvent: LearningSpineServeRouteBreadcrumbsV1["hostEvent"];
+    installedEntryPath?: string | null;
+}
 export interface RuntimeEventExportBundleSummaryV1 {
     runtimeOwner: "openclaw";
     sessionId: string | null;
@@ -78,8 +86,17 @@ export interface CompileRuntimeContextInput {
     budgetStrategy?: CompileRuntimeBudgetStrategy;
     maxContextChars?: number;
     mode?: RouteMode;
+    selectionMode?: CompileSelectionMode;
     compactionMode?: ContextCompactionMode;
     runtimeHints?: readonly string[];
+    /** Optional session ID for serve-time route decision logging (extension callers). */
+    sessionId?: string;
+    /** Optional channel identifier for serve-time route decision logging (extension callers). */
+    channel?: string;
+    /** @internal Suppress serve-time logging inside compileRuntimeContext when called from runRuntimeTurn (which logs separately). */
+    _suppressServeLog?: boolean;
+    /** @internal Preserve explicit serve-route breadcrumbs for installed/runtime hook paths. */
+    _serveRouteBreadcrumbs?: CompileServeRouteBreadcrumbInput;
 }
 export interface ActiveCompileTarget {
     activationRoot: string;
@@ -305,6 +322,7 @@ export interface OpenClawRuntimeTurnInput {
     maxContextBlocks?: number;
     budgetStrategy?: CompileRuntimeBudgetStrategy;
     mode?: RouteMode;
+    selectionMode?: CompileSelectionMode;
     runtimeHints?: readonly string[];
     brainAttachmentPolicy?: RuntimeTurnBrainAttachmentPolicyV1 | null;
     contextFingerprint?: RuntimeTurnContextFingerprintInputV1 | null;
@@ -345,6 +363,14 @@ export type TeacherLoopNoOpReason = "none" | "duplicate_export" | "queue_full" |
 export interface AsyncTeacherLiveLoopInput extends Pick<AdvanceAlwaysOnLearningRuntimeInput, "packLabel" | "workspace" | "learnedRouting" | "builtAt" | "offlineArtifacts" | "structuralOps" | "sparseFeedback" | "liveSliceSize" | "backfillSliceSize" | "cadence"> {
     maxQueuedExports?: number;
     staleAfterMs?: number;
+    resumeFromSnapshot?: AsyncTeacherLiveLoopSnapshotV1 | null;
+    resolveLearnedRoutingState?: () => {
+        pgVersion?: AdvanceAlwaysOnLearningRuntimeInput["pgVersion"];
+        serveTimeDecisions?: LearningSpineServeRouteDecisionLogEntryV1[];
+        baselineState?: BaselineStateV1;
+    };
+    persistUpdatedBaseline?: (state: BaselineStateV1) => void;
+    teacherLabeler?: AsyncTeacherLabelerConfigV1 | null;
 }
 export interface AsyncTeacherQueuedExportJobV1 {
     jobId: string;
@@ -381,6 +407,18 @@ export interface AsyncTeacherLiveLoopSnapshotV1 {
         lastMaterialization: AlwaysOnLearningMaterializationJobV1 | null;
     };
     diagnostics: AsyncTeacherLiveLoopDiagnosticsV1;
+    state?: {
+        interactionEvents: InteractionEventV1[];
+        feedbackEvents: FeedbackEventV1[];
+        seenExportDigests: string[];
+    };
+    runtime?: {
+        startedAt: string | null;
+        lastHeartbeatAt: string | null;
+        lastScanAt: string | null;
+        scanRoot: string | null;
+        lastAppliedMaterializationJobId: string | null;
+    };
 }
 export interface AsyncTeacherEnqueueResultV1 {
     accepted: boolean;
@@ -536,6 +574,7 @@ export declare class AsyncTeacherLiveLoop {
     private readonly input;
     private readonly queueCapacity;
     private readonly staleAfterMs;
+    private readonly teacherLabeler;
     private readonly queuedExportDigests;
     private readonly seenExportDigests;
     private queue;
@@ -545,6 +584,7 @@ export declare class AsyncTeacherLiveLoop {
     private teacherArtifacts;
     private learnerState;
     private lastMaterialization;
+    private lastTeacherLabelerResult;
     private diagnostics;
     constructor(input: AsyncTeacherLiveLoopInput);
     enqueueNormalizedEventExport(normalizedEventExport: NormalizedEventExportV1, options?: {
@@ -602,9 +642,125 @@ export interface ScanLiveEventExportResultV1 {
     packLabel: string;
     supervision: CanonicalSupervisionV1;
     snapshot: AsyncTeacherLiveLoopSnapshotV1;
+    labelFlow: OperatorLabelFlowSummary;
+    learningPath: OperatorLearningPathSummary;
 }
 export declare function scanRecordedSession(input: ScanRecordedSessionInputV1): ScanRecordedSessionResultV1;
 export declare function scanLiveEventExport(input: ScanLiveEventExportInputV1): ScanLiveEventExportResultV1;
+export declare function resolveAsyncTeacherLiveLoopSnapshotPath(activationRoot: string): string;
+export declare const WATCH_STATE_DIRNAME = "watch";
+export declare const WATCH_SESSION_TAIL_CURSOR_BASENAME = "session-tail-cursor.json";
+export declare const WATCH_TEACHER_SNAPSHOT_BASENAME = "teacher-snapshot.json";
+export interface WatchTeacherSnapshotFailureV1 {
+    mode: "materialization_failed" | "teacher_fail_open";
+    detail: string;
+    at: string;
+}
+export interface WatchTeacherSnapshotTeacherSummaryV1 {
+    artifactCount: number;
+    latestFreshness: AsyncTeacherLiveLoopDiagnosticsV1["latestFreshness"] | "unavailable";
+    acceptedExportCount: number;
+    processedExportCount: number;
+    duplicateExportCount: number;
+    droppedExportCount: number;
+    emittedArtifactCount: number;
+    dedupedArtifactCount: number;
+    lastProcessedAt: string | null;
+    lastNoOpReason: TeacherLoopNoOpReason;
+    queueDepth: number;
+    queueCapacity: number;
+    running: boolean;
+    lastAppliedMaterializationJobId: string | null;
+    lastMaterializedPackId: string | null;
+}
+export interface WatchTeacherSnapshotLearningSummaryV1 {
+    bootstrapped: boolean;
+    mode: AlwaysOnLearningRuntimePlanV1["mode"];
+    nextPriorityLane: AlwaysOnLearningRuntimePlanV1["nextPriorityLane"];
+    nextPriorityBucket: AlwaysOnLearningRuntimePlanV1["nextPriorityBucket"];
+    pendingLive: number;
+    pendingBackfill: number;
+    pendingTotal: number;
+    pendingByBucket: AlwaysOnLearningRuntimePlanV1["pending"]["byBucket"];
+    materializationCount: number;
+    lastMaterializedAt: string | null;
+    lastMaterializationReason: AlwaysOnLearningMaterializationJobV1["reason"] | null;
+    lastMaterializationLane: AlwaysOnLearningMaterializationJobV1["lane"] | null;
+    lastMaterializedPackId: string | null;
+    lastHandledMaterializationPackId: string | null;
+}
+export interface WatchTeacherSnapshotLabelingSummaryV1 {
+    learningCadence: LearningCadence;
+    scanPolicy: LearningScanPolicy;
+    liveSlicesPerCycle: number;
+    backfillSlicesPerCycle: number;
+    teacherBudget: number;
+    teacherDelayMs: number;
+    backgroundLabelAmplification: number;
+}
+export interface WatchTeacherSnapshotFileV1 {
+    contract: "openclaw_watch_teacher_snapshot.v1";
+    runtimeOwner: "openclaw";
+    updatedAt: string;
+    lastRunAt: string;
+    scanRoot: string;
+    sessionTailCursorPath: string;
+    sessionTailCursorUpdatedAt: string;
+    sessionTailSessionsTracked: number;
+    sessionTailBridgedEventCount: number;
+    scannerCheckpointPath: string;
+    scannerCheckpoint: RuntimeEventExportScannerCheckpointV1;
+    replayedBundleCount: number;
+    replayedEventCount: number;
+    exportedBundleCount: number;
+    exportedEventCount: number;
+    startupWarnings: string[];
+    lastTeacherError: string | null;
+    localSessionTailNoopReason: string | null;
+    lastHandledMaterializationPackId: string | null;
+    teacher: WatchTeacherSnapshotTeacherSummaryV1;
+    learning: WatchTeacherSnapshotLearningSummaryV1;
+    labeling: WatchTeacherSnapshotLabelingSummaryV1;
+    failure: WatchTeacherSnapshotFailureV1 | null;
+    snapshot: AsyncTeacherLiveLoopSnapshotV1;
+}
+export interface LoadedTeacherSurfaceV1 {
+    sourcePath: string;
+    sourceKind: "watch_snapshot" | "async_snapshot";
+    snapshot: AsyncTeacherLiveLoopSnapshotV1;
+    watchSnapshot: WatchTeacherSnapshotFileV1 | null;
+}
+export declare function resolveWatchStateRoot(activationRoot: string): string;
+export declare function resolveWatchSessionTailCursorPath(activationRoot: string): string;
+export declare function resolveWatchTeacherSnapshotPath(activationRoot: string): string;
+export declare function resolveOperatorTeacherSnapshotPath(activationRoot: string, explicitPath: string | null | undefined): string | null;
+export declare function loadTeacherSurface(snapshotPath: string): LoadedTeacherSurfaceV1 | null;
+export declare function loadWatchTeacherSnapshotState(snapshotPath: string): {
+    lastHandledMaterializationPackId: string | null;
+    snapshot: AsyncTeacherLiveLoopSnapshotV1 | null;
+    error: string | null;
+};
+export declare function persistWatchTeacherSnapshot(snapshotPath: string, input: {
+    lastRunAt: string;
+    scanRoot: string;
+    sessionTailCursorPath: string;
+    sessionTailCursorUpdatedAt: string;
+    sessionTailSessionsTracked: number;
+    sessionTailBridgedEventCount: number;
+    scannerCheckpointPath: string;
+    scannerCheckpoint: RuntimeEventExportScannerCheckpointV1;
+    replayedBundleCount: number;
+    replayedEventCount: number;
+    exportedBundleCount: number;
+    exportedEventCount: number;
+    startupWarnings: readonly string[];
+    lastTeacherError: string | null;
+    localSessionTailNoopReason: string | null;
+    lastHandledMaterializationPackId: string | null;
+    failure: WatchTeacherSnapshotFailureV1 | null;
+    snapshot: AsyncTeacherLiveLoopSnapshotV1;
+}): WatchTeacherSnapshotFileV1;
+export declare function loadAsyncTeacherLiveLoopSnapshot(snapshotPath: string): AsyncTeacherLiveLoopSnapshotV1;
 export declare function buildRuntimeEventExportBundleManifest(input: {
     exportName: string;
     exportedAt: string;
@@ -758,6 +914,7 @@ export declare class RuntimeEventExportScanner {
     private checkpoint;
     constructor(input: RuntimeEventExportScannerInput);
     snapshot(): RuntimeEventExportScannerCheckpointV1;
+    restoreCheckpoint(checkpoint: RuntimeEventExportScannerCheckpointV1): void;
     scanOnce(options?: {
         scannedAt?: string;
     }): RuntimeEventExportScannerScanResultV1;
@@ -1142,6 +1299,11 @@ export interface OperatorBrainStateSummary {
     activeEventExportDigest: string | null;
     detail: string;
 }
+export interface OperatorActivationStateSummary {
+    state: CurrentProfileActivationStateV1;
+    detail: string;
+    inspectionError: string | null;
+}
 export interface OperatorGraphSummary {
     available: boolean;
     runtimePlasticitySource: RuntimePlasticitySourceV1 | null;
@@ -1155,6 +1317,27 @@ export interface OperatorGraphSummary {
     operatorSummary: string | null;
     detail: string;
 }
+export type OperatorObservabilitySource = "active_pack" | "event_export" | "materialized_candidate" | "missing";
+export type OperatorPolicyGradientVersion = "v1" | "v2" | "unavailable";
+export interface OperatorLabelFlowSummary {
+    source: OperatorObservabilitySource;
+    humanLabelCount: number | null;
+    selfLabelCount: number | null;
+    asyncTeacherArtifactCount: number | null;
+    implicitPositiveCount: number | null;
+    detail: string;
+}
+export interface OperatorLearningPathSummary {
+    available: boolean;
+    source: OperatorObservabilitySource;
+    policyGradientVersion: OperatorPolicyGradientVersion;
+    policyGradientMethod: string | null;
+    objective: string | null;
+    targetConstruction: string | null;
+    connectOpsFired: number | null;
+    reconstructedTrajectoryCount: number | null;
+    detail: string;
+}
 export interface OperatorServePathSummary {
     state: OperatorServePathState;
     fallbackToStaticContext: boolean;
@@ -1206,12 +1389,32 @@ export interface OperatorSupervisionSummary {
 export interface OperatorTeacherLoopSummary {
     available: boolean;
     sourcePath: string | null;
+    sourceKind: "watch_snapshot" | "async_snapshot" | "missing";
+    lastRunAt: string | null;
     lastNoOpReason: TeacherLoopNoOpReason | "unavailable";
     latestFreshness: AsyncTeacherLiveLoopDiagnosticsV1["latestFreshness"] | "unavailable";
+    startedAt: string | null;
+    lastHeartbeatAt: string | null;
+    lastScanAt: string | null;
     lastProcessedAt: string | null;
+    artifactCount: number | null;
     queueDepth: number | null;
     queueCapacity: number | null;
     running: boolean | null;
+    replayedBundleCount: number | null;
+    replayedEventCount: number | null;
+    exportedBundleCount: number | null;
+    exportedEventCount: number | null;
+    sessionTailSessionsTracked: number | null;
+    sessionTailBridgedEventCount: number | null;
+    localSessionTailNoopReason: string | null;
+    learningCadence: LearningCadence | "unavailable";
+    scanPolicy: LearningScanPolicy | "unavailable";
+    liveSlicesPerCycle: number | null;
+    backfillSlicesPerCycle: number | null;
+    failureMode: WatchTeacherSnapshotFailureV1["mode"] | "none" | "unavailable";
+    failureDetail: string | null;
+    lastAppliedMaterializationJobId: string | null;
     lastMaterializedPackId: string | null;
     notes: string[];
     detail: string;
@@ -1303,6 +1506,7 @@ interface OperatorSurfaceReport {
     generatedAt: string;
     activationRoot: string;
     status: OperatorSurfaceStatus;
+    activation: OperatorActivationStateSummary;
     active: OperatorSurfaceSlotSummary | null;
     candidate: OperatorSurfaceSlotSummary | null;
     previous: OperatorSurfaceSlotSummary | null;
@@ -1312,6 +1516,8 @@ interface OperatorSurfaceReport {
     };
     brain: OperatorBrainStateSummary;
     graph: OperatorGraphSummary;
+    labelFlow: OperatorLabelFlowSummary;
+    learningPath: OperatorLearningPathSummary;
     learnedRouting: {
         required: boolean;
         available: boolean;
@@ -1360,6 +1566,8 @@ export interface CurrentProfileBrainStatusInput extends OperatorSurfaceInput {
     profileId?: string | null;
 }
 export type CurrentProfileBrainStatusV1 = CurrentProfileBrainStatusAnswerV1;
+export declare function summarizeNormalizedEventExportLabelFlow(normalizedEventExport: NormalizedEventExportV1, asyncTeacherArtifactCount?: number): OperatorLabelFlowSummary;
+export declare function summarizeLearningPathFromMaterialization(materialization: AlwaysOnLearningMaterializationJobV1 | null): OperatorLearningPathSummary;
 export declare function buildOperatorSurfaceReport(input: OperatorSurfaceInput): OperatorSurfaceReport;
 export declare function describeCurrentProfileBrainStatus(input: CurrentProfileBrainStatusInput): CurrentProfileBrainStatusV1;
 export declare function formatOperatorRollbackReport(result: RollbackRuntimeAttachResult): string;
@@ -1420,7 +1628,8 @@ export { describeNormalizedEventExportObservability } from "@openclawbrain/event
 export { describeCompileFallbackUsage } from "@openclawbrain/compiler";
 export { describeActivationObservability, inspectActivationState, rollbackActivePack } from "@openclawbrain/pack-format";
 export { createOpenClawLocalSessionTail, OpenClawLocalSessionTail, type OpenClawLocalSessionTailChangeKindV1, type OpenClawLocalSessionTailChangeV1, type OpenClawLocalSessionTailCursorV1, type OpenClawLocalSessionTailInput, type OpenClawLocalSessionTailLoopOptionsV1, type OpenClawLocalSessionTailLoopResultV1, type OpenClawLocalSessionTailNoopReasonV1, type OpenClawLocalSessionTailPollResultV1 } from "./session-tail.js";
-export { discoverOpenClawMainSessionStores, loadOpenClawSessionIndex, readOpenClawAcpStreamFile, readOpenClawSessionFile, type OpenClawMainSessionStoreV1, type OpenClawAcpStreamRecord, type OpenClawInjectedWorkspaceFile, type OpenClawSessionContentPart, type OpenClawSessionCustomRecord, type OpenClawSessionHeaderRecord, type OpenClawSessionIndex, type OpenClawSessionIndexEntry, type OpenClawSessionMessagePayload, type OpenClawSessionMessageRecord, type OpenClawSessionModelChangeRecord, type OpenClawSessionRecord, type OpenClawSessionTextPart, type OpenClawSessionThinkingLevelChangeRecord, type OpenClawSessionThinkingPart, type OpenClawSessionToolCallPart, type OpenClawSystemPromptReport, type OpenClawToolSurfaceEntry } from "./session-store.js";
+export { discoverOpenClawMainSessionStores, discoverOpenClawSessionStores, loadOpenClawSessionIndex, readOpenClawAcpStreamFile, readOpenClawSessionFile, type OpenClawMainSessionStoreV1, type OpenClawSessionStoreV1, type OpenClawAcpStreamRecord, type OpenClawInjectedWorkspaceFile, type OpenClawSessionContentPart, type OpenClawSessionCustomRecord, type OpenClawSessionHeaderRecord, type OpenClawSessionIndex, type OpenClawSessionIndexEntry, type OpenClawSessionMessagePayload, type OpenClawSessionMessageRecord, type OpenClawSessionModelChangeRecord, type OpenClawSessionRecord, type OpenClawSessionTextPart, type OpenClawSessionThinkingLevelChangeRecord, type OpenClawSessionThinkingPart, type OpenClawSessionToolCallPart, type OpenClawSystemPromptReport, type OpenClawToolSurfaceEntry } from "./session-store.js";
 export { buildPassiveLearningSessionExportFromOpenClawSessionStore, buildPassiveLearningStoreExportFromOpenClawSessionIndex, type OpenClawPassiveLearningPrivacySummaryV1, type OpenClawPassiveLearningSessionEvidenceV1, type OpenClawPassiveLearningSessionExportV1, type OpenClawPassiveLearningStoreExportV1 } from "./local-session-passive-learning.js";
+export { DEFAULT_OLLAMA_BASE_URL, DEFAULT_OLLAMA_TIMEOUT_MS, OllamaClient, OllamaClientError, createOllamaClient, type OllamaChatMessage, type OllamaClientOptions, type OllamaFetch, type OllamaFetchRequestInit, type OllamaFetchResponse, type OllamaRequestOptions } from "./ollama-client.js";
 export { resolveActivationRoot, type ResolveActivationRootOptions } from "./resolve-activation-root.js";
 export { runDaemonCommand, type DaemonCliArgs, type DaemonSubcommand, parseDaemonArgs } from "./daemon.js";