@earendil-works/pi-durable 1.3.0 → 1.4.0

package/dist/harness/scheduler.d.ts

@@ -3,9 +3,21 @@ import type { Models } from "@earendil-works/pi-ai";
 import type { ExecutionEnv } from "../env/index.ts";
 import type { SessionImpl } from "../session/session.ts";
 import type { Transaction } from "../session/transaction.ts";
-import type { ConversationId, Storage, TaskId, TaskOutcome, TaskRecord } from "../types.ts";
-import type { Agent, ConversationHandle, HarnessInspection, RegistryReader, RegistrySnapshot, Settings, SettledTask, TaskInspection } from "./types.ts";
+import type { Timers } from "../timers.ts";
+import type { ConversationId, ReportInfo, Storage, StorageWrite, TaskId, TaskOutcome, TaskRecord, TaskState } from "../types.ts";
+import type { Agent, ConversationHandle, HarnessInspection, HarnessOptions, RegistryReader, RegistrySnapshot, Settings, SettledTask, TaskInspection, Wake } from "./types.ts";
 type AnyTaskRecord = TaskRecord<JsonValue, JsonValue, JsonValue>;
+/** What `blockedReason()` reads of a task: the task graph keeps only this of each record. */
+export type BlockedSubject = Pick<AnyTaskRecord, "id" | "kind" | "version" | "abortRequested" | "abortReason" | "restarts"> & {
+    readonly status: TaskState<JsonValue, JsonValue>["status"];
+};
+/** The part of a record `blockedReason()` reads. */
+export declare function blockedSubject(record: AnyTaskRecord): BlockedSubject;
+/**
+ * Why a task cannot be reserved: no registered definition can take it, or it was cut off `restartLimit` times in a row.
+ * Derived from the registry, the settings, and the record's `restarts`.
+ */
+export type BlockedReason = "missing_task" | "task_too_old" | "migration_failed" | "restart_limit";
 /** Terminal outcomes the scheduler writes without running task code. */
 export type SchedulerOutcome = Extract<TaskOutcome<JsonValue>, {
     readonly status: "faulted" | "orphaned";
@@ -16,10 +28,12 @@ export type InvocationBinding = {
     check(): void;
 };
 export type TaskSchedulerOptions = {
+    readonly telemetry?: HarnessOptions["telemetry"];
     readonly session: SessionImpl;
     readonly storage: Storage;
     readonly registry: RegistryReader;
-    readonly models: Models;
+    /** The host's current model access (`HarnessOptions.models`); read at each access. */
+    readonly models: () => Models;
     /** Resolve a conversation's agent against a snapshot; the runtime calls it at most once per phase. */
     readonly agent: (conversationId: ConversationId, snapshot: RegistrySnapshot, context: Context) => Promise<Agent>;
     /** Resolve the settings; read at each access. */
@@ -27,7 +41,13 @@ export type TaskSchedulerOptions = {
     /** Build a conversation's environment with `HarnessOptions.env`. */
     readonly env: (conversationId: ConversationId, context: Context) => Promise<ExecutionEnv | undefined>;
     readonly now: () => number;
-    readonly report: (error: unknown) => void;
+    /** `HarnessOptions.onWake`: replaces the timer for sleeping tasks. */
+    readonly onWake: ((wake: Wake) => void) | undefined;
+    /** The host's timers (`HarnessOptions.setTimer`). */
+    readonly timers: Timers;
+    /** While closing, on the line after admitted commits settle, write what the callback returns straight to Storage. */
+    readonly writeAtClose: (writes: () => readonly StorageWrite[]) => Promise<void>;
+    readonly report: (error: unknown, info: ReportInfo, context?: Context) => void;
     /** Harness cleanup staged in the commit that makes an outcome the scheduler wrote itself terminal. */
     readonly settleOutcome: (tx: Transaction, record: AnyTaskRecord, outcome: SchedulerOutcome) => Promise<void>;
     /** Withdraw a conversation's queued inputs, for conversation abort and abort cascades. */
@@ -40,8 +60,9 @@ export type TaskSchedulerOptions = {
 /**
  * Durable task scheduler of one Harness.
  *
- * `#live` mirrors every committed non-terminal task record: pending, running, waiting, and completing. The synchronous
- * commit listener updates it on the Session line, so code running on the line reads exactly the committed state from it.
+ * `#live` mirrors every committed non-terminal task record: pending, running, waiting, sleeping, and completing. The
+ * synchronous commit listener updates it on the Session line, so code running on the line reads exactly the committed
+ * state from it.
  *
  * Tasks and conversations form one ownership tree (spec §5.5): a task's parent is its owner task, or its conversation;
  * a conversation's parent is its owner task, if any. Walks up that tree decide what reaches one task: a cancelling
@@ -61,13 +82,37 @@ export type TaskSchedulerOptions = {
 export declare class TaskScheduler {
     #private;
     constructor(options: TaskSchedulerOptions);
-    /** Load live tasks and change surviving `running` tasks back to `pending`. Dispatches nothing. */
+    /**
+     * Load live tasks and change surviving `running` tasks back to `pending`, counting the restart. Dispatches nothing. A
+     * task that reaches the restart limit this way is parked and reported.
+     */
     open(context: Context): Promise<void>;
-    /** Enable scheduling. Idempotent; the kick does nothing once closing. */
+    /**
+     * Enable scheduling, and make sleeping tasks that are due runnable: a host wakeup, such as an alarm, calls this.
+     * Idempotent; the kick does nothing once closing.
+     */
     resume(): void;
     /**
-     * Signal every invocation and wait for them; writes nothing. Close calls this after every close listener has run, so
-     * waits, watches, and streams a task holds end with the Session's reason, not as cancelled by its signal.
+     * Run a task parked by the restart limit again: clears its restart count and enables scheduling. Does nothing for a
+     * task that is not parked; rejects for an unknown one.
+     */
+    retry(id: TaskId, context: Context): Promise<void>;
+    /**
+     * Why a live task cannot run here, if it cannot: its definition (missing, too old, failed migration) or the restart
+     * limit. A running task, an abort-marked one, and one holding its outcome are never blocked.
+     */
+    blockedReason(record: BlockedSubject): BlockedReason | undefined;
+    /** Call `listener` when blocked reasons may have changed without a commit: a registry change or a failed migration. */
+    subscribeBlocked(listener: () => void): () => void;
+    /**
+     * When the Session next needs a process: `active` while some task can run now or is running, `at` for the earliest
+     * sleep not yet due. Synchronous, from memory; a task whose chain is not loaded yet counts as it would alone.
+     */
+    wake(): Wake;
+    /**
+     * Signal every invocation and wait for them, then write the tasks they ran back as `pending` (`writeAtClose`), as a
+     * close is not a crash. Close calls this after every close listener has run, so waits, watches, and streams a task
+     * holds end with the Session's reason, not as cancelled by its signal.
      */
     join(): Promise<void>;
     /**

package/dist/harness/scheduler.d.ts.map

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