abmind 0.2.6 → 0.2.7-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/SUPPORTED-SURFACE.md +20 -2
  2. package/dist/cli/abmind-hook-recall.js +17 -40
  3. package/dist/cli/abmind-hook-recall.js.map +1 -1
  4. package/dist/cli/abmind-hook-store.js +10 -31
  5. package/dist/cli/abmind-hook-store.js.map +1 -1
  6. package/dist/cli/abmind-hook-wakeup.js +17 -3
  7. package/dist/cli/abmind-hook-wakeup.js.map +1 -1
  8. package/dist/cli/abmind-install.js +19 -19
  9. package/dist/cli/abmind-install.js.map +1 -1
  10. package/dist/cli/abmind-restore.js +10 -0
  11. package/dist/cli/abmind-restore.js.map +1 -1
  12. package/dist/cli/abmind-sleep.d.ts +9 -5
  13. package/dist/cli/abmind-sleep.d.ts.map +1 -1
  14. package/dist/cli/abmind-sleep.js +61 -14
  15. package/dist/cli/abmind-sleep.js.map +1 -1
  16. package/dist/cli/hook-lifecycle-adapter.d.ts +11 -0
  17. package/dist/cli/hook-lifecycle-adapter.d.ts.map +1 -0
  18. package/dist/cli/hook-lifecycle-adapter.js +33 -0
  19. package/dist/cli/hook-lifecycle-adapter.js.map +1 -0
  20. package/dist/src/context-engine.d.ts +13 -3
  21. package/dist/src/context-engine.d.ts.map +1 -1
  22. package/dist/src/context-engine.js +22 -5
  23. package/dist/src/context-engine.js.map +1 -1
  24. package/dist/src/context-orchestrator.d.ts +20 -2
  25. package/dist/src/context-orchestrator.d.ts.map +1 -1
  26. package/dist/src/context-orchestrator.js +11 -3
  27. package/dist/src/context-orchestrator.js.map +1 -1
  28. package/dist/src/context-tier-renderer.d.ts +8 -1
  29. package/dist/src/context-tier-renderer.d.ts.map +1 -1
  30. package/dist/src/context-tier-renderer.js +7 -2
  31. package/dist/src/context-tier-renderer.js.map +1 -1
  32. package/dist/src/ensure-initialized.d.ts +5 -0
  33. package/dist/src/ensure-initialized.d.ts.map +1 -1
  34. package/dist/src/ensure-initialized.js +19 -28
  35. package/dist/src/ensure-initialized.js.map +1 -1
  36. package/dist/src/host-integration/identity.d.ts +10 -0
  37. package/dist/src/host-integration/identity.d.ts.map +1 -0
  38. package/dist/src/host-integration/identity.js +66 -0
  39. package/dist/src/host-integration/identity.js.map +1 -0
  40. package/dist/src/host-integration/index.d.ts +5 -0
  41. package/dist/src/host-integration/index.d.ts.map +1 -0
  42. package/dist/src/host-integration/index.js +4 -0
  43. package/dist/src/host-integration/index.js.map +1 -0
  44. package/dist/src/host-integration/lifecycle.d.ts +14 -0
  45. package/dist/src/host-integration/lifecycle.d.ts.map +1 -0
  46. package/dist/src/host-integration/lifecycle.js +192 -0
  47. package/dist/src/host-integration/lifecycle.js.map +1 -0
  48. package/dist/src/host-integration/render.d.ts +5 -0
  49. package/dist/src/host-integration/render.d.ts.map +1 -0
  50. package/dist/src/host-integration/render.js +20 -0
  51. package/dist/src/host-integration/render.js.map +1 -0
  52. package/dist/src/host-integration/types.d.ts +107 -0
  53. package/dist/src/host-integration/types.d.ts.map +1 -0
  54. package/dist/src/host-integration/types.js +2 -0
  55. package/dist/src/host-integration/types.js.map +1 -0
  56. package/dist/src/imemory-system.d.ts +1 -1
  57. package/dist/src/imemory-system.d.ts.map +1 -1
  58. package/dist/src/index.d.ts +6 -4
  59. package/dist/src/index.d.ts.map +1 -1
  60. package/dist/src/index.js +3 -1
  61. package/dist/src/index.js.map +1 -1
  62. package/dist/src/maintenance-service.d.ts +11 -0
  63. package/dist/src/maintenance-service.d.ts.map +1 -1
  64. package/dist/src/maintenance-service.js +43 -0
  65. package/dist/src/maintenance-service.js.map +1 -1
  66. package/dist/src/memory-manager.d.ts +6 -2
  67. package/dist/src/memory-manager.d.ts.map +1 -1
  68. package/dist/src/memory-manager.js +9 -5
  69. package/dist/src/memory-manager.js.map +1 -1
  70. package/dist/src/message-store.d.ts +15 -3
  71. package/dist/src/message-store.d.ts.map +1 -1
  72. package/dist/src/message-store.js +28 -9
  73. package/dist/src/message-store.js.map +1 -1
  74. package/dist/src/openclaw-plugin/index.d.ts.map +1 -1
  75. package/dist/src/openclaw-plugin/index.js +3 -2
  76. package/dist/src/openclaw-plugin/index.js.map +1 -1
  77. package/dist/src/pi-plugin/abtars-client.d.ts +22 -0
  78. package/dist/src/pi-plugin/abtars-client.d.ts.map +1 -0
  79. package/dist/src/pi-plugin/abtars-client.js +153 -0
  80. package/dist/src/pi-plugin/abtars-client.js.map +1 -0
  81. package/dist/src/pi-plugin/abtars-tools.d.ts +8 -0
  82. package/dist/src/pi-plugin/abtars-tools.d.ts.map +1 -0
  83. package/dist/src/pi-plugin/abtars-tools.js +317 -0
  84. package/dist/src/pi-plugin/abtars-tools.js.map +1 -0
  85. package/dist/src/pi-plugin/identity.d.ts +8 -0
  86. package/dist/src/pi-plugin/identity.d.ts.map +1 -0
  87. package/dist/src/pi-plugin/identity.js +37 -0
  88. package/dist/src/pi-plugin/identity.js.map +1 -0
  89. package/dist/src/pi-plugin/index.d.ts +3 -0
  90. package/dist/src/pi-plugin/index.d.ts.map +1 -0
  91. package/dist/src/pi-plugin/index.js +139 -0
  92. package/dist/src/pi-plugin/index.js.map +1 -0
  93. package/dist/src/pi-plugin/messages.d.ts +4 -0
  94. package/dist/src/pi-plugin/messages.d.ts.map +1 -0
  95. package/dist/src/pi-plugin/messages.js +36 -0
  96. package/dist/src/pi-plugin/messages.js.map +1 -0
  97. package/dist/src/pi-plugin/pi-types.d.ts +126 -0
  98. package/dist/src/pi-plugin/pi-types.d.ts.map +1 -0
  99. package/dist/src/pi-plugin/pi-types.js +15 -0
  100. package/dist/src/pi-plugin/pi-types.js.map +1 -0
  101. package/dist/src/pi-plugin/runtime.d.ts +21 -0
  102. package/dist/src/pi-plugin/runtime.d.ts.map +1 -0
  103. package/dist/src/pi-plugin/runtime.js +60 -0
  104. package/dist/src/pi-plugin/runtime.js.map +1 -0
  105. package/dist/src/pi-plugin/tools.d.ts +11 -0
  106. package/dist/src/pi-plugin/tools.d.ts.map +1 -0
  107. package/dist/src/pi-plugin/tools.js +136 -0
  108. package/dist/src/pi-plugin/tools.js.map +1 -0
  109. package/dist/src/reconcile.d.ts +2 -0
  110. package/dist/src/reconcile.d.ts.map +1 -1
  111. package/dist/src/reconcile.js +21 -4
  112. package/dist/src/reconcile.js.map +1 -1
  113. package/dist/src/session-context.d.ts +1 -0
  114. package/dist/src/session-context.d.ts.map +1 -1
  115. package/dist/src/session-context.js +42 -23
  116. package/dist/src/session-context.js.map +1 -1
  117. package/dist/src/sleep/basic.d.ts +1 -1
  118. package/dist/src/sleep/basic.d.ts.map +1 -1
  119. package/dist/src/sleep/basic.js +5 -2
  120. package/dist/src/sleep/basic.js.map +1 -1
  121. package/dist/src/sleep/catchup.d.ts +3 -5
  122. package/dist/src/sleep/catchup.d.ts.map +1 -1
  123. package/dist/src/sleep/catchup.js +37 -55
  124. package/dist/src/sleep/catchup.js.map +1 -1
  125. package/dist/src/sleep/contracts.d.ts +112 -0
  126. package/dist/src/sleep/contracts.d.ts.map +1 -0
  127. package/dist/src/sleep/contracts.js +25 -0
  128. package/dist/src/sleep/contracts.js.map +1 -0
  129. package/dist/src/sleep/llm-budget.d.ts +34 -14
  130. package/dist/src/sleep/llm-budget.d.ts.map +1 -1
  131. package/dist/src/sleep/llm-budget.js +66 -52
  132. package/dist/src/sleep/llm-budget.js.map +1 -1
  133. package/dist/src/sleep/orchestrator.d.ts +19 -69
  134. package/dist/src/sleep/orchestrator.d.ts.map +1 -1
  135. package/dist/src/sleep/orchestrator.js +286 -270
  136. package/dist/src/sleep/orchestrator.js.map +1 -1
  137. package/dist/src/sleep/state.d.ts +7 -19
  138. package/dist/src/sleep/state.d.ts.map +1 -1
  139. package/dist/src/sleep/state.js +5 -38
  140. package/dist/src/sleep/state.js.map +1 -1
  141. package/dist/src/sleep/test-harness.d.ts +3 -1
  142. package/dist/src/sleep/test-harness.d.ts.map +1 -1
  143. package/dist/src/sleep/test-harness.js +3 -2
  144. package/dist/src/sleep/test-harness.js.map +1 -1
  145. package/dist/src/soul-seeder.d.ts +36 -0
  146. package/dist/src/soul-seeder.d.ts.map +1 -0
  147. package/dist/src/soul-seeder.js +69 -0
  148. package/dist/src/soul-seeder.js.map +1 -0
  149. package/dist/src/wake-up-builder.d.ts +3 -1
  150. package/dist/src/wake-up-builder.d.ts.map +1 -1
  151. package/dist/src/wake-up-builder.js +29 -5
  152. package/dist/src/wake-up-builder.js.map +1 -1
  153. package/package.json +20 -2
  154. package/dist/cli/abmind-rollback.d.ts +0 -8
  155. package/dist/cli/abmind-rollback.d.ts.map +0 -1
  156. package/dist/cli/abmind-rollback.js +0 -78
  157. package/dist/cli/abmind-rollback.js.map +0 -1
  158. package/dist/src/native-loader.d.ts +0 -7
  159. package/dist/src/native-loader.d.ts.map +0 -1
  160. package/dist/src/native-loader.js +0 -21
  161. package/dist/src/native-loader.js.map +0 -1
  162. package/dist/src/recall-benchmark.d.ts +0 -13
  163. package/dist/src/recall-benchmark.d.ts.map +0 -1
  164. package/dist/src/recall-benchmark.js +0 -260
  165. package/dist/src/recall-benchmark.js.map +0 -1
  166. package/dist/src/sleep/runtime.d.ts +0 -15
  167. package/dist/src/sleep/runtime.d.ts.map +0 -1
  168. package/dist/src/sleep/runtime.js +0 -2
  169. package/dist/src/sleep/runtime.js.map +0 -1
  170. package/dist/src/wake-up-renderer.d.ts +0 -24
  171. package/dist/src/wake-up-renderer.d.ts.map +0 -1
  172. package/dist/src/wake-up-renderer.js +0 -148
  173. package/dist/src/wake-up-renderer.js.map +0 -1
@@ -0,0 +1,112 @@
1
+ /**
2
+ * sleep/contracts.ts — host-neutral public contract for the abmind sleep
3
+ * engine (#1353).
4
+ *
5
+ * abmind owns memory-domain maintenance: step ordering, shared variables,
6
+ * budget, checkpoints, resume/catch-up, watermark, and the final domain
7
+ * result. An embedding host (abtars, OpenClaw, Hermes, the standalone CLI)
8
+ * owns scheduling, authenticated/manual admission, model/provider transport,
9
+ * agent/session lifecycle, and delivery. This file is the seam between them.
10
+ *
11
+ * These types are exported from the package root and listed in
12
+ * SUPPORTED-SURFACE.md. Internal state-file shapes (SleepState, StepResult,
13
+ * lock-file JSON) remain private — a host must never read them directly.
14
+ */
15
+ import type { Level } from "./levels.js";
16
+ import type { MemoryConfig } from "../memory-config.js";
17
+ /** One model-completion request for a single sleep step.
18
+ * `signal` combines the caller's cancellation with the configured wall-clock
19
+ * timeout — hosts must pass it through to their own transport/abort logic. */
20
+ export interface SleepCompletionRequest {
21
+ prompt: string;
22
+ stepId: string;
23
+ runId: string;
24
+ signal: AbortSignal;
25
+ }
26
+ /** Host-injected model runtime. One method: send a prompt, get text back.
27
+ * Reject on transport failure — abmind does not operate a provider retry
28
+ * loop; a rejection maps directly to abmind's own essential-step/suspend
29
+ * policy. Hosts own their own provider retry/fallback before rejecting. */
30
+ export interface SleepRuntime {
31
+ complete(request: SleepCompletionRequest): Promise<string>;
32
+ }
33
+ /** "manual" runs (e.g. an explicit "/sleep now") still run housekeeping even
34
+ * with zero new messages since the last cycle — matching the historical
35
+ * --force behavior. "scheduled" and "resume" respect the no-work guard. */
36
+ export type SleepRunMode = "scheduled" | "manual" | "resume";
37
+ export interface SleepRunOptions {
38
+ runtime: SleepRuntime;
39
+ mode?: SleepRunMode;
40
+ level?: Level;
41
+ /** Caller-supplied cancellation — combined internally with the wall-clock timeout. */
42
+ signal?: AbortSignal;
43
+ /** Discard prior state and start with a clean budget. Used by manual "now" runs. */
44
+ fresh?: boolean;
45
+ /** Best-effort lifecycle observer. A throwing handler never alters the run. */
46
+ onEvent?: (event: SleepEvent) => void;
47
+ now?: () => number;
48
+ timeoutMs?: number;
49
+ memoryConfigOverride?: Partial<MemoryConfig>;
50
+ /** Internal test seam — delay between bounded domain retries (empty/invalid
51
+ * response). Not part of the documented public contract; defaults to 6000ms. */
52
+ domainRetryDelayMs?: number;
53
+ /** Internal test seam — inter-step backoff after a non-essential step
54
+ * failure, keyed by consecutive-failure count. Not part of the documented
55
+ * public contract; defaults to [10,30,60]s capped. */
56
+ betweenStepBackoffMs?: (consecutiveFailures: number) => number;
57
+ }
58
+ export type SleepTerminalStatus = "completed" | "no_work" | "partial" | "failed" | "cancelled" | "already_running";
59
+ export interface SleepStepSummary {
60
+ id: string;
61
+ status: "completed" | "skipped" | "failed" | "timeout";
62
+ essential: boolean;
63
+ attempts: number;
64
+ durationMs?: number;
65
+ }
66
+ export interface SleepRunResult {
67
+ runId: string;
68
+ status: SleepTerminalStatus;
69
+ startedAt: number;
70
+ finishedAt: number;
71
+ llmCalls: number;
72
+ steps: readonly SleepStepSummary[];
73
+ essentialFailures: readonly string[];
74
+ resumable: boolean;
75
+ watermarkAdvanced: boolean;
76
+ report: string;
77
+ }
78
+ /** Neutral lifecycle events. Bounded metadata only — never prompts or raw
79
+ * model responses. Exactly one `cycle_finished` is attempted for every run
80
+ * that emitted `cycle_started`. */
81
+ export type SleepEvent = {
82
+ type: "cycle_started";
83
+ runId: string;
84
+ totalSteps: number;
85
+ resumed: boolean;
86
+ } | {
87
+ type: "step_started";
88
+ runId: string;
89
+ stepId: string;
90
+ index: number;
91
+ total: number;
92
+ } | {
93
+ type: "step_completed";
94
+ runId: string;
95
+ step: SleepStepSummary;
96
+ } | {
97
+ type: "step_skipped";
98
+ runId: string;
99
+ step: SleepStepSummary;
100
+ } | {
101
+ type: "step_failed";
102
+ runId: string;
103
+ step: SleepStepSummary;
104
+ } | {
105
+ type: "cycle_finished";
106
+ runId: string;
107
+ result: SleepRunResult;
108
+ };
109
+ /** Best-effort event dispatch — an observer that throws must never alter the
110
+ * memory transaction, ordering, or final result (#1353 constraint 5). */
111
+ export declare function emitSleepEvent(handler: ((event: SleepEvent) => void) | undefined, event: SleepEvent): void;
112
+ //# sourceMappingURL=contracts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/sleep/contracts.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,25 @@
1
+ /**
2
+ * sleep/contracts.ts — host-neutral public contract for the abmind sleep
3
+ * engine (#1353).
4
+ *
5
+ * abmind owns memory-domain maintenance: step ordering, shared variables,
6
+ * budget, checkpoints, resume/catch-up, watermark, and the final domain
7
+ * result. An embedding host (abtars, OpenClaw, Hermes, the standalone CLI)
8
+ * owns scheduling, authenticated/manual admission, model/provider transport,
9
+ * agent/session lifecycle, and delivery. This file is the seam between them.
10
+ *
11
+ * These types are exported from the package root and listed in
12
+ * SUPPORTED-SURFACE.md. Internal state-file shapes (SleepState, StepResult,
13
+ * lock-file JSON) remain private — a host must never read them directly.
14
+ */
15
+ /** Best-effort event dispatch — an observer that throws must never alter the
16
+ * memory transaction, ordering, or final result (#1353 constraint 5). */
17
+ export function emitSleepEvent(handler, event) {
18
+ if (!handler)
19
+ return;
20
+ try {
21
+ handler(event);
22
+ }
23
+ catch { /* host display only — never fail the cycle */ }
24
+ }
25
+ //# sourceMappingURL=contracts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/sleep/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4FH;0EAC0E;AAC1E,MAAM,UAAU,cAAc,CAAC,OAAkD,EAAE,KAAiB;IAClG,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,IAAI,CAAC;QAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,8CAA8C,CAAC,CAAC;AAClF,CAAC"}
@@ -1,21 +1,32 @@
1
1
  /**
2
- * sleep/llm-budget.ts — LLM call budget tracking and retry-with-transport-backoff.
3
- * Extracted from orchestrator.ts (#1229). Carries the full transport-aware
4
- * sendWithRetry from #1279.
2
+ * sleep/llm-budget.ts — LLM call budget tracking and bounded domain retry.
3
+ *
4
+ * #1353: transport retry/backoff is a host responsibility, not abmind's.
5
+ * `SleepRuntime.complete()` is one host-supervised model operation — if it
6
+ * rejects, the host has already exhausted its own provider retry/fallback
7
+ * policy. Abmind records a transport-unavailable step outcome and follows
8
+ * its existing essential-step stop/suspend rules; it does not sleep and
9
+ * retry the provider itself.
10
+ *
11
+ * The bounded retry that remains here is a DOMAIN retry: a structurally
12
+ * empty or invalid *successful* response is retried a small number of times
13
+ * because another model call is semantically meaningful (the model may
14
+ * simply produce a better answer next time). Every model-reaching attempt —
15
+ * retried or not — is charged to the LLM budget.
5
16
  */
6
17
  import { LLMUnavailableError } from "../sleep-pipeline.js";
7
- import type { SleepRuntime } from "./runtime.js";
18
+ import type { SleepRuntime } from "./contracts.js";
8
19
  import type { SleepState } from "./state.js";
9
- export declare const MAX_RETRIES = 3;
10
- export declare const TRANSPORT_MAX_RETRIES = 6;
11
- export declare const DEFAULT_TRANSPORT_RETRY_WINDOW_MS: number;
12
- /** Thrown by sendWithRetry when runtime.complete() throws on every attempt within the retry window.
13
- * Extends LLMUnavailableError so buildDailySummary and extractFromDaily rethrow it naturally
14
- * (those functions check instanceof LLMUnavailableError to propagate errors up). */
15
- export declare class ModelUnavailableError extends LLMUnavailableError {
16
- constructor(stepName: string);
20
+ /** Bounded retries for an empty/invalid domain response. Not a transport retry. */
21
+ export declare const MAX_DOMAIN_RETRIES = 3;
22
+ /** Thrown when the host's `runtime.complete()` rejects — a transport failure,
23
+ * not a domain one. Extends LLMUnavailableError so buildDailySummary/
24
+ * extractFromDaily propagate it naturally (they check instanceof
25
+ * LLMUnavailableError to bubble errors up to the orchestrator). */
26
+ export declare class TransportUnavailableError extends LLMUnavailableError {
27
+ constructor(stepId: string, cause?: unknown);
17
28
  }
18
- /** Budget tracker — shared across all sendWithRetry calls in a sleep cycle. */
29
+ /** Budget tracker — shared across all completion calls in a sleep cycle. */
19
30
  export declare class LlmBudget {
20
31
  private state;
21
32
  private readonly statePath;
@@ -25,5 +36,14 @@ export declare class LlmBudget {
25
36
  consume(): boolean;
26
37
  get calls(): number;
27
38
  }
28
- export declare function sendWithRetry(runtime: SleepRuntime, prompt: string, stepName: string, _verbose: boolean, budget?: LlmBudget, delayMs?: number, transportBackoffMs?: (attempt: number) => number, transportRetryWindowMs?: number, nowFn?: () => number): Promise<string | null>;
39
+ /**
40
+ * Send one prompt through the host runtime with bounded domain retry for
41
+ * empty/invalid responses. A runtime rejection is NOT retried here — it
42
+ * propagates immediately as TransportUnavailableError so the orchestrator
43
+ * can apply its own essential-step stop/suspend policy.
44
+ *
45
+ * Returns null if the budget is already exhausted, or after MAX_DOMAIN_RETRIES
46
+ * consecutive empty responses.
47
+ */
48
+ export declare function sendToRuntime(runtime: SleepRuntime, prompt: string, stepId: string, runId: string, signal: AbortSignal, budget?: LlmBudget, delayMs?: number): Promise<string | null>;
29
49
  //# sourceMappingURL=llm-budget.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"llm-budget.d.ts","sourceRoot":"","sources":["../../../src/sleep/llm-budget.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,eAAO,MAAM,iCAAiC,QAAa,CAAC;AAE5D;;qFAEqF;AACrF,qBAAa,qBAAsB,SAAQ,mBAAmB;gBAChD,QAAQ,EAAE,MAAM;CAI7B;AAED,+EAA+E;AAC/E,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,SAAS,UAAS;gBAEN,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM;IAKhD,2DAA2D;IAC3D,OAAO,IAAI,OAAO;IAUlB,IAAI,KAAK,IAAI,MAAM,CAAqC;CACzD;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,SAAO,EACd,kBAAkB,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAA8D,EACvG,sBAAsB,SAAoC,EAC1D,KAAK,GAAE,MAAM,MAAiB,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmDxB"}
1
+ {"version":3,"file":"llm-budget.d.ts","sourceRoot":"","sources":["../../../src/sleep/llm-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAA0B,MAAM,gBAAgB,CAAC;AAE3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;oEAGoE;AACpE,qBAAa,yBAA0B,SAAQ,mBAAmB;gBACpD,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK5C;AAED,4EAA4E;AAC5E,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,SAAS,UAAS;gBAEN,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM;IAKhD,2DAA2D;IAC3D,OAAO,IAAI,OAAO;IAUlB,IAAI,KAAK,IAAI,MAAM,CAAqC;CACzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,SAAO,GACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyCxB"}
@@ -1,26 +1,38 @@
1
1
  /**
2
- * sleep/llm-budget.ts — LLM call budget tracking and retry-with-transport-backoff.
3
- * Extracted from orchestrator.ts (#1229). Carries the full transport-aware
4
- * sendWithRetry from #1279.
2
+ * sleep/llm-budget.ts — LLM call budget tracking and bounded domain retry.
3
+ *
4
+ * #1353: transport retry/backoff is a host responsibility, not abmind's.
5
+ * `SleepRuntime.complete()` is one host-supervised model operation — if it
6
+ * rejects, the host has already exhausted its own provider retry/fallback
7
+ * policy. Abmind records a transport-unavailable step outcome and follows
8
+ * its existing essential-step stop/suspend rules; it does not sleep and
9
+ * retry the provider itself.
10
+ *
11
+ * The bounded retry that remains here is a DOMAIN retry: a structurally
12
+ * empty or invalid *successful* response is retried a small number of times
13
+ * because another model call is semantically meaningful (the model may
14
+ * simply produce a better answer next time). Every model-reaching attempt —
15
+ * retried or not — is charged to the LLM budget.
5
16
  */
6
17
  import { getAbmindEnv } from "../env-schema.js";
7
- import { logWarn, logError, logInfo } from "../mem-logger.js";
18
+ import { logWarn, logError } from "../mem-logger.js";
8
19
  import { LLMUnavailableError } from "../sleep-pipeline.js";
9
20
  import { writeStateFile } from "./state.js";
10
21
  const TAG = "abmind-sleep";
11
- export const MAX_RETRIES = 3;
12
- export const TRANSPORT_MAX_RETRIES = 6;
13
- export const DEFAULT_TRANSPORT_RETRY_WINDOW_MS = 8 * 60_000; // 8 minutes
14
- /** Thrown by sendWithRetry when runtime.complete() throws on every attempt within the retry window.
15
- * Extends LLMUnavailableError so buildDailySummary and extractFromDaily rethrow it naturally
16
- * (those functions check instanceof LLMUnavailableError to propagate errors up). */
17
- export class ModelUnavailableError extends LLMUnavailableError {
18
- constructor(stepName) {
19
- super(`Model unavailable for step "${stepName}" after retry window`);
20
- this.name = "ModelUnavailableError";
22
+ /** Bounded retries for an empty/invalid domain response. Not a transport retry. */
23
+ export const MAX_DOMAIN_RETRIES = 3;
24
+ /** Thrown when the host's `runtime.complete()` rejects a transport failure,
25
+ * not a domain one. Extends LLMUnavailableError so buildDailySummary/
26
+ * extractFromDaily propagate it naturally (they check instanceof
27
+ * LLMUnavailableError to bubble errors up to the orchestrator). */
28
+ export class TransportUnavailableError extends LLMUnavailableError {
29
+ constructor(stepId, cause) {
30
+ const msg = cause instanceof Error ? cause.message : String(cause);
31
+ super(`Runtime rejected for step "${stepId}": ${msg}`);
32
+ this.name = "TransportUnavailableError";
21
33
  }
22
34
  }
23
- /** Budget tracker — shared across all sendWithRetry calls in a sleep cycle. */
35
+ /** Budget tracker — shared across all completion calls in a sleep cycle. */
24
36
  export class LlmBudget {
25
37
  state;
26
38
  statePath;
@@ -41,52 +53,54 @@ export class LlmBudget {
41
53
  }
42
54
  get calls() { return this.state.llmCalls ?? 0; }
43
55
  }
44
- export async function sendWithRetry(runtime, prompt, stepName, _verbose, budget, delayMs = 6000, transportBackoffMs = (n) => Math.min(30_000 * Math.pow(2, n - 1), 120_000), transportRetryWindowMs = DEFAULT_TRANSPORT_RETRY_WINDOW_MS, nowFn = Date.now) {
45
- const deadline = nowFn() + transportRetryWindowMs;
46
- let emptyAttempts = 0;
47
- let transportAttempts = 0;
48
- // Budget-exhaustion pre-check: if we are already over the cap, bail immediately.
49
- // This mirrors the old pre-loop consume() guard without burning a call.
56
+ /**
57
+ * Send one prompt through the host runtime with bounded domain retry for
58
+ * empty/invalid responses. A runtime rejection is NOT retried here — it
59
+ * propagates immediately as TransportUnavailableError so the orchestrator
60
+ * can apply its own essential-step stop/suspend policy.
61
+ *
62
+ * Returns null if the budget is already exhausted, or after MAX_DOMAIN_RETRIES
63
+ * consecutive empty responses.
64
+ */
65
+ export async function sendToRuntime(runtime, prompt, stepId, runId, signal, budget, delayMs = 6000) {
50
66
  if (budget?.exhausted) {
51
- logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepName} — suspending`);
67
+ logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepId} — suspending`);
52
68
  return null;
53
69
  }
70
+ let emptyAttempts = 0;
54
71
  while (true) {
72
+ if (signal.aborted)
73
+ return null;
74
+ const request = { prompt, stepId, runId, signal };
75
+ let result;
55
76
  try {
56
- const result = await runtime.complete(prompt);
57
- // Real call reached the model — count it now (success OR empty, never a throw).
58
- if (budget && !budget.consume()) {
59
- logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepName} — suspending`);
60
- return null;
61
- }
62
- if (!result || !result.trim()) {
63
- emptyAttempts++;
64
- logWarn(TAG, `Step ${stepName} attempt ${emptyAttempts}/${MAX_RETRIES} returned empty response`);
65
- if (emptyAttempts >= MAX_RETRIES) {
66
- logError(TAG, `Step ${stepName} failed after ${MAX_RETRIES} attempts (empty), skipping`);
67
- return null;
68
- }
69
- if (delayMs > 0)
70
- await new Promise(r => setTimeout(r, delayMs));
71
- continue;
72
- }
73
- return result;
77
+ result = await runtime.complete(request);
74
78
  }
75
79
  catch (err) {
76
- // Transport failure — model unreachable. Do NOT consume budget (no tokens used).
77
- transportAttempts++;
78
- const msg = err instanceof Error ? err.message : String(err);
79
- const backoff = transportBackoffMs(transportAttempts);
80
- const timeRemaining = deadline - nowFn();
81
- logWarn(TAG, `Step ${stepName} transport fail (${transportAttempts}/${TRANSPORT_MAX_RETRIES}): ${msg}`);
82
- if (transportAttempts >= TRANSPORT_MAX_RETRIES || timeRemaining <= backoff) {
83
- logError(TAG, `Step ${stepName} model unavailable after ${transportAttempts} attempt(s), ${Math.round(transportRetryWindowMs / 60_000)}min window exhausted`);
84
- throw new ModelUnavailableError(stepName);
80
+ // Transport failure — model unreachable via the host's own transport.
81
+ // No abmind-side backoff/retry window: the host has already exhausted
82
+ // its provider policy. Surface immediately.
83
+ throw new TransportUnavailableError(stepId, err);
84
+ }
85
+ // Real call reached the model — count it now (success OR empty, never a throw).
86
+ if (budget && !budget.consume()) {
87
+ logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepId} suspending`);
88
+ return null;
89
+ }
90
+ if (!result || !result.trim()) {
91
+ emptyAttempts++;
92
+ logWarn(TAG, `Step ${stepId} attempt ${emptyAttempts}/${MAX_DOMAIN_RETRIES} returned empty response`);
93
+ if (emptyAttempts >= MAX_DOMAIN_RETRIES) {
94
+ logError(TAG, `Step ${stepId} failed after ${MAX_DOMAIN_RETRIES} attempts (empty), skipping`);
95
+ return null;
85
96
  }
86
- logInfo(TAG, `[SLEEP] Model unreachable — waiting ${Math.round(backoff / 1000)}s before retry (step ${stepName})`);
87
- if (backoff > 0)
88
- await new Promise(r => setTimeout(r, backoff));
97
+ if (signal.aborted)
98
+ return null;
99
+ if (delayMs > 0)
100
+ await new Promise(r => setTimeout(r, delayMs));
101
+ continue;
89
102
  }
103
+ return result;
90
104
  }
91
105
  }
92
106
  //# sourceMappingURL=llm-budget.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"llm-budget.js","sourceRoot":"","sources":["../../../src/sleep/llm-budget.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"llm-budget.js","sourceRoot":"","sources":["../../../src/sleep/llm-budget.ts"],"names":[],"mappings":"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"}
@@ -1,85 +1,35 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * abmind sleep orchestrator — library function for overnight memory maintenance.
3
+ * abmind sleep orchestrator — host-neutral memory-maintenance engine (#1353).
4
4
  *
5
- * Called via runSleepCycle({ runtime, level, ... }). Gathers system state,
6
- * runs through a pipeline of prompt-driven steps (gc-noise, daily-summary,
7
- * extract-memories, retrospective, retro-derive, etc.), persists audit log, returns result.
5
+ * Called via runSleepCycle(options). Gathers system state, runs through a
6
+ * pipeline of prompt-driven steps (gc-noise, daily-summary, extract-memories,
7
+ * retrospective, retro-derive, etc.), persists audit log, returns a structured
8
+ * SleepRunResult.
9
+ *
10
+ * abmind owns: step ordering, shared variables/outputs, wired memory
11
+ * maintenance, essential-step/continuation rules, LLM-call budget, durable
12
+ * checkpoints/resume/catch-up/watermark, and the final domain result.
13
+ *
14
+ * The embedding host owns: scheduling, admission, model/provider transport,
15
+ * agent/session lifecycle, cancellation on shutdown, and delivery. The host
16
+ * never reads sleep_*.lock — SleepRunResult is the only supported way to
17
+ * learn what happened.
8
18
  *
9
19
  * Library-only — no CLI entry point here. Standalone entry lives in
10
20
  * cli/abmind-sleep.ts.
11
- *
12
- * Flags (passed via RunOpts.flags):
13
- * --dry-run Gather state + build prompts, print to stdout, skip LLM calls
14
- * --verbose Detailed logging at each orchestration step
15
- * --force Run housekeeping even if no messages since last sleep
16
21
  */
17
- import type { SleepRuntime } from "./runtime.js";
18
- import { type Level } from "./levels.js";
19
- import type { SleepStepEvent } from "./state.js";
22
+ import type { SleepRunOptions, SleepRunResult } from "./contracts.js";
20
23
  /** Steps whose failure blocks watermark advance. Public so tests can derive reject targets. */
21
24
  export { ESSENTIAL_STEPS } from "./catchup.js";
22
25
  /** Thrown by runSleepCycle when memory layer fails to initialize. */
23
26
  export declare class SleepInitError extends Error {
24
27
  constructor(message: string);
25
28
  }
26
- /** Thrown by runSleepCycle when the wall-clock timeout expires before completion. */
27
- export declare class SleepTimeoutError extends Error {
28
- constructor(message: string);
29
- }
30
- /** Step-lifecycle event fired by the orchestrator at each step boundary (#895).
31
- * Best-effort — a throwing handler must never break memory consolidation. */
32
- export type { SleepStepEvent } from "./state.js";
33
- /** Options for runSleepCycle. All optional — defaults preserve current main() behavior. */
34
- export interface RunOpts {
35
- flags?: RawArgs;
36
- runtime: SleepRuntime;
37
- /** Which prompt set to run. Defaults to SLEEP_QUALITY env or "normal". */
38
- level?: Level;
39
- /** Discard prior state and start with a clean budget. Used by /sleep now. */
40
- fresh?: boolean;
41
- /** Inject a deterministic clock for decision sites (today/weekday/startedAt). Observations use real Date.now. */
42
- now?: () => number;
43
- /** Override the wall-clock timeout in ms. Default from SLEEP_TIMEOUT_MIN env. */
44
- timeoutMs?: number;
45
- /** Override inter-step backoff. Default: [10,30,60]s on consecutive failures. Tests: () => 0. */
46
- backoffMs?: (consecutiveFailures: number) => number;
47
- /** Override intra-step retry delay in ms. Default: 6000. Tests: 0. */
48
- retryDelayMs?: number;
49
- /** Override transport-failure backoff per attempt (ms). Default: capped exp (30s/60s/120s). Tests: () => 0. */
50
- transportBackoffMs?: (attempt: number) => number;
51
- /** Override transport-failure retry window (ms). Default: 8 minutes. Tests: small value. */
52
- transportRetryWindowMs?: number;
53
- /** Override memory config (temp dirs in tests). */
54
- memoryConfigOverride?: Partial<import("../memory-config.js").MemoryConfig>;
55
- /** Step-lifecycle hook (#895) — fired at each step boundary.
56
- * Display-only: a throwing handler never breaks the cycle. */
57
- onStep?: (e: SleepStepEvent) => void;
58
- /** Hook fired once at the start of a cycle (before any step runs).
59
- * Used by hosts to create a stepped card, reset per-night state, etc. */
60
- onCycleStart?: (e: {
61
- totalSteps: number;
62
- }) => void;
63
- }
64
- /** Result of runSleepCycle — thrown errors handled separately. */
65
- export interface RunResult {
66
- ok: boolean;
67
- failCount: number;
68
- }
69
- export type RawArgs = {
70
- dryRun: boolean;
71
- verbose: boolean;
72
- force: boolean;
73
- };
74
- export declare function parseArgs(argv: string[]): RawArgs;
75
- /** LLM call entry for sleep steps — caller provides the runtime via RunOpts. */
76
29
  /**
77
- * Run the full sleep cycle. Extracted from main() for testability (#175).
78
- * - Deterministic time injection via opts.now for decision sites
79
- * - Throws SleepInitError / SleepTimeoutError instead of process.exit
80
- * - Returns { ok, failCount } for observable outcomes
81
- *
82
- * Default args preserve current main() behavior exactly.
30
+ * Run the full sleep cycle against a host-injected runtime. Returns a
31
+ * structured SleepRunResult projected from the authoritative on-disk state
32
+ * hosts never need to read the lock file themselves.
83
33
  */
84
- export declare function runSleepCycle(opts: RunOpts): Promise<RunResult>;
34
+ export declare function runSleepCycle(options: SleepRunOptions): Promise<SleepRunResult>;
85
35
  //# sourceMappingURL=orchestrator.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/sleep/orchestrator.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAiBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,KAAK,KAAK,EAA6B,MAAM,aAAa,CAAC;AAEpE,OAAO,KAAK,EAAiE,cAAc,EAAE,MAAM,YAAY,CAAC;AAWhH,+FAA+F;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,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,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,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;AAID,gFAAgF;AAMhF;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CA2sBrE"}
1
+ {"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"}