abmind 0.2.5 → 0.2.7-alpha.0

package/dist/src/sleep/orchestrator.d.ts

@@ -1,101 +1,35 @@
 #!/usr/bin/env node
 /**
- * abmind sleep orchestrator — library function for overnight memory maintenance.
+ * abmind sleep orchestrator — host-neutral memory-maintenance engine (#1353).
  *
- * Called via runSleepCycle({ runtime, level, ... }). Gathers system state,
- * runs through a pipeline of prompt-driven steps (gc-noise, daily-summary,
- * extract-memories, retrospective, retro-derive, etc.), persists audit log, returns result.
+ * Called via runSleepCycle(options). Gathers system state, runs through a
+ * pipeline of prompt-driven steps (gc-noise, daily-summary, extract-memories,
+ * retrospective, retro-derive, etc.), persists audit log, returns a structured
+ * SleepRunResult.
+ *
+ * abmind owns: step ordering, shared variables/outputs, wired memory
+ * maintenance, essential-step/continuation rules, LLM-call budget, durable
+ * checkpoints/resume/catch-up/watermark, and the final domain result.
+ *
+ * The embedding host owns: scheduling, admission, model/provider transport,
+ * agent/session lifecycle, cancellation on shutdown, and delivery. The host
+ * never reads sleep_*.lock — SleepRunResult is the only supported way to
+ * learn what happened.
  *
  * Library-only — no CLI entry point here. Standalone entry lives in
  * cli/abmind-sleep.ts.
- *
- * Flags (passed via RunOpts.flags):
- *   --dry-run   Gather state + build prompts, print to stdout, skip LLM calls
- *   --verbose   Detailed logging at each orchestration step
- *   --force     Run housekeeping even if no messages since last sleep
  */
-import { LLMUnavailableError } from "../sleep-pipeline.js";
-import type { SleepRuntime } from "./runtime.js";
-import { type Level } from "./levels.js";
+import type { SleepRunOptions, SleepRunResult } from "./contracts.js";
 /** Steps whose failure blocks watermark advance. Public so tests can derive reject targets. */
-export declare const ESSENTIAL_STEPS: ReadonlySet<string>;
+export { ESSENTIAL_STEPS } from "./catchup.js";
 /** Thrown by runSleepCycle when memory layer fails to initialize. */
 export declare class SleepInitError extends Error {
     constructor(message: string);
 }
-/** Thrown by runSleepCycle when the wall-clock timeout expires before completion. */
-export declare class SleepTimeoutError extends Error {
-    constructor(message: string);
-}
-/** Step-lifecycle event fired by the orchestrator at each step boundary (#895).
- *  Best-effort — a throwing handler must never break memory consolidation. */
-export interface SleepStepEvent {
-    /** Step name, e.g. "extract-memories". */
-    name: string;
-    /** Source filename, e.g. "03-extract-memories.md". */
-    filename: string;
-    /** 1-based step index within the run. */
-    index: number;
-    /** Total steps in this run (loaded from loadSleepSteps() at cycle start). */
-    total: number;
-    /** "start" fired before the step runs, "done"/"skipped"/"failed" on resolution. */
-    phase: "start" | "done" | "skipped" | "failed";
-}
-/** Options for runSleepCycle. All optional — defaults preserve current main() behavior. */
-export interface RunOpts {
-    flags?: RawArgs;
-    runtime: SleepRuntime;
-    /** Which prompt set to run. Defaults to SLEEP_QUALITY env or "normal". */
-    level?: Level;
-    /** Discard prior state and start with a clean budget. Used by /sleep now. */
-    fresh?: boolean;
-    /** Inject a deterministic clock for decision sites (today/weekday/startedAt). Observations use real Date.now. */
-    now?: () => number;
-    /** Override the wall-clock timeout in ms. Default from SLEEP_TIMEOUT_MIN env. */
-    timeoutMs?: number;
-    /** Override inter-step backoff. Default: [10,30,60]s on consecutive failures. Tests: () => 0. */
-    backoffMs?: (consecutiveFailures: number) => number;
-    /** Override intra-step retry delay in ms. Default: 6000. Tests: 0. */
-    retryDelayMs?: number;
-    /** Override transport-failure backoff per attempt (ms). Default: capped exp (30s/60s/120s). Tests: () => 0. */
-    transportBackoffMs?: (attempt: number) => number;
-    /** Override transport-failure retry window (ms). Default: 8 minutes. Tests: small value. */
-    transportRetryWindowMs?: number;
-    /** Override memory config (temp dirs in tests). */
-    memoryConfigOverride?: Partial<import("../memory-config.js").MemoryConfig>;
-    /** Step-lifecycle hook (#895) — fired at each step boundary.
-     *  Display-only: a throwing handler never breaks the cycle. */
-    onStep?: (e: SleepStepEvent) => void;
-    /** Hook fired once at the start of a cycle (before any step runs).
-     *  Used by hosts to create a stepped card, reset per-night state, etc. */
-    onCycleStart?: (e: {
-        totalSteps: number;
-    }) => void;
-}
-/** Result of runSleepCycle — thrown errors handled separately. */
-export interface RunResult {
-    ok: boolean;
-    failCount: number;
-}
-export type RawArgs = {
-    dryRun: boolean;
-    verbose: boolean;
-    force: boolean;
-};
-export declare function parseArgs(argv: string[]): RawArgs;
-/** Thrown by sendWithRetry when runtime.complete() throws on every attempt within the retry window.
- *  Extends LLMUnavailableError so buildDailySummary and extractFromDaily rethrow it naturally
- *  (those functions check instanceof LLMUnavailableError to propagate errors up). */
-export declare class ModelUnavailableError extends LLMUnavailableError {
-    constructor(stepName: string);
-}
 /**
- * Run the full sleep cycle. Extracted from main() for testability (#175).
- * - Deterministic time injection via opts.now for decision sites
- * - Throws SleepInitError / SleepTimeoutError instead of process.exit
- * - Returns { ok, failCount } for observable outcomes
- *
- * Default args preserve current main() behavior exactly.
+ * Run the full sleep cycle against a host-injected runtime. Returns a
+ * structured SleepRunResult projected from the authoritative on-disk state —
+ * hosts never need to read the lock file themselves.
  */
-export declare function runSleepCycle(opts: RunOpts): Promise<RunResult>;
+export declare function runSleepCycle(options: SleepRunOptions): Promise<SleepRunResult>;
 //# sourceMappingURL=orchestrator.d.ts.map

package/dist/src/sleep/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/sleep/orchestrator.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAaH,OAAO,EAAqC,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAO9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,KAAK,KAAK,EAA6B,MAAM,aAAa,CAAC;AAgBpE,+FAA+F;AAC/F,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAAmE,CAAC;AAGpH,qEAAqE;AACrE,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAC5B;AAED,qFAAqF;AACrF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAC5B;AAED;8EAC8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;CAChD;AASD,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iHAAiH;IACjH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,SAAS,CAAC,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+GAA+G;IAC/G,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,OAAO,CAAC,OAAO,qBAAqB,EAAE,YAAY,CAAC,CAAC;IAC3E;mEAC+D;IAC/D,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACrC;8EAC0E;IAC1E,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACpD;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,OAAO,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAmBjD;AA4GD;;qFAEqF;AACrF,qBAAa,qBAAsB,SAAQ,mBAAmB;gBAChD,QAAQ,EAAE,MAAM;CAI7B;AA4bD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CA2sBrE"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/sleep/orchestrator.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG;AA2BH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAGf,MAAM,gBAAgB,CAAC;AAIxB,+FAA+F;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,qEAAqE;AACrE,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAC5B;AASD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA4pBrF"}