zidane 5.10.0 → 5.10.2

package/dist/restate.d.ts

@@ -1,14 +1,6 @@
-import { Gt as AgentBehavior, Kt as AgentClock, L as SessionStore, b as ToolDef, bn as ToolBatchExecutor, pt as StreamOptions, ut as Provider } from "./agent-AnumGPWj.js";
+import { Cn as ToolResultContent, Gt as AgentBehavior, Kt as AgentClock, L as SessionStore, b as ToolDef, bn as ToolBatchExecutor, pt as StreamOptions, ut as Provider, y as ToolContext } from "./agent-Bt123Fdy.js";
+import { a as DetachedTasksCapability } from "./types-BMwiYRIJ.js";
 
-//#region src/restate/behavior.d.ts
-/**
- * Conservative behavior defaults for agents running inside Restate.
- *
- * The helper is opt-in and returns a plain AgentBehavior object, so callers can
- * spread or override it without changing non-Restate harness defaults.
- */
-declare function restateBehavior(overrides?: AgentBehavior): AgentBehavior;
-//#endregion
 //#region src/restate/types.d.ts
 /**
  * Minimal structural types mirroring the subset of `@restatedev/restate-sdk`
@@ -82,6 +74,19 @@ interface RestateContextLike {
     uuidv4: () => string;
   };
   awakeable: <T>() => RestateAwakeable<T>;
+  /**
+   * Durable timer — suspends the invocation for `millis` and survives
+   * process death (replay resumes the same timer). Mirrors the SDK's
+   * `Context.sleep(duration)`; we narrow the parameter to plain millis
+   * (the SDK also accepts a `Duration`, which a wider implementation
+   * signature satisfies structurally).
+   *
+   * What it's for in this adapter: durable timeouts. Racing
+   * `awakeable.promise` against `sleep(timeoutMs)` is the canonical
+   * "wait with a deadline" shape — see {@link awakeableWithTimeout},
+   * which packages exactly that race for `waitBackground`-style parks.
+   */
+  sleep: (millis: number) => Promise<void>;
 }
 /**
  * Structural subset of `restate.ObjectContext` — adds keyed K/V state
@@ -97,6 +102,114 @@ interface RestateObjectContextLike extends RestateContextLike {
   clear: (name: string) => void;
 }
 //#endregion
+//#region src/restate/awakeable.d.ts
+/**
+ * Structural subset of the SDK's `RestatePromise` static surface used by
+ * {@link awakeableWithTimeout} — mirrors `RestatePromiseAllLike` from
+ * `./parallel`. Pass `RestatePromise` from `@restatedev/restate-sdk` so
+ * the race goes through the journaled combinator; native `Promise.race`
+ * over two durable promises leaves the winner to the runtime's replay
+ * ordering instead of an explicit journal entry.
+ */
+interface RestatePromiseRaceLike<TPromise extends Promise<unknown> = Promise<unknown>> {
+  race: (values: readonly TPromise[]) => Promise<unknown>;
+}
+interface AwakeableWithTimeoutOptions<TPromise extends Promise<unknown> = Promise<unknown>> {
+  /**
+   * Durable deadline in milliseconds. Unset / non-positive = no timeout
+   * (the returned awakeable is the plain `ctx.awakeable()` passthrough).
+   */
+  timeoutMs?: number;
+  /**
+   * Durable race combinator — pass `RestatePromise` from the SDK. When
+   * omitted, native `Promise.race` is used: correct at runtime and
+   * replay-safe for THIS pattern (both branches are journaled
+   * primitives), but the SDK combinator is the recommended belt-and-
+   * braces choice for deterministic replay.
+   */
+  promises?: RestatePromiseRaceLike<TPromise>;
+}
+/**
+ * Mint an awakeable that resolves with the resumer's payload, or `null`
+ * when `timeoutMs` elapses first. The id is journal-stable (send it
+ * out-of-band as usual); the timeout is a durable `ctx.sleep`, so a
+ * parked invocation suspends instead of holding a worker.
+ *
+ * Timeout surfaces as `null` — a resumer that resolves `undefined` is
+ * indistinguishable from a timeout, so resolve a concrete payload.
+ *
+ * ```ts
+ * // waitBackground for a durable host, in three lines:
+ * const { id, promise } = awakeableWithTimeout<TaskExitInfo>(ctx, { timeoutMs, promises: RestatePromise })
+ * await registerExitResumer(taskId, id) // runner → ctx.resolveAwakeable(id, info)
+ * return await promise                  // TaskExitInfo, or null on timeout
+ * ```
+ */
+declare function awakeableWithTimeout<T, TPromise extends Promise<unknown> = Promise<unknown>>(ctx: RestateContextLike, options?: AwakeableWithTimeoutOptions<TPromise>): RestateAwakeable<T | null>;
+//#endregion
+//#region src/restate/awakeable-tool.d.ts
+interface RestateAwakeableToolOptions<T = unknown> {
+  /** Canonical tool name (what the model calls). */
+  name: string;
+  /** Model-facing tool description. */
+  description: string;
+  /** JSON schema for the tool input. */
+  inputSchema: Record<string, unknown>;
+  /** The Restate context the awakeable + journal entries bind to. */
+  ctx: RestateContextLike;
+  /**
+   * Send the awakeable id (plus the call's input) out-of-band so a
+   * resumer can later call `ctx.resolveAwakeable(awakeableId, value)`.
+   * Runs inside `ctx.run` — fires exactly once across replays.
+   */
+  notify: (info: {
+    awakeableId: string;
+    input: Record<string, unknown>;
+    toolCtx: ToolContext;
+  }) => void | Promise<void>;
+  /**
+   * Map the resolved awakeable payload to the tool result. Default:
+   * strings pass through, everything else is JSON-stringified.
+   */
+  toResult?: (value: T, input: Record<string, unknown>) => string | ToolResultContent[];
+  /**
+   * `ctx.run` options for the notify entry. Defaults to
+   * `{ maxRetryAttempts: 1 }`, matching `restateTool`'s rationale.
+   */
+  runOptions?: RestateRunOptions;
+  /**
+   * Concurrency-safety flag passed through to the `ToolDef`. Defaults to
+   * `false` — a parked wait holding a scheduler slot should barrier.
+   */
+  isConcurrencySafe?: boolean;
+}
+/**
+ * Build a `ToolDef` that parks on a Restate awakeable until an external
+ * resumer resolves it. See the module doc for the replay contract.
+ *
+ * Do NOT additionally wrap the returned tool in `restateTool` — the
+ * journal discipline is already internal, and an outer `ctx.run` would
+ * illegally nest the suspension point inside a journaled closure.
+ */
+declare function restateAwakeableTool<T = unknown>(options: RestateAwakeableToolOptions<T>): ToolDef;
+//#endregion
+//#region src/restate/behavior.d.ts
+/**
+ * Conservative behavior defaults for agents running inside Restate.
+ *
+ * The helper is opt-in and returns a plain AgentBehavior object, so callers can
+ * spread or override it without changing non-Restate harness defaults.
+ *
+ * `disableBackgroundTasks: 'non-durable'` is capability-aware: background
+ * tasks stay enabled for execution contexts whose
+ * `capabilities.detachedTasks` is `'durable'` (tasks live on a remote
+ * runner and survive worker crashes) and are disabled for everything
+ * else (host-local processes don't survive process death). Hosts on
+ * plain `ProcessContext` see the same effective behavior as the old
+ * blanket `true`.
+ */
+declare function restateBehavior(overrides?: AgentBehavior): AgentBehavior;
+//#endregion
 //#region src/restate/clock.d.ts
 /**
  * Wrap a Restate context's `date.now()` + `rand.uuidv4()` into the
@@ -202,7 +315,50 @@ declare function restateProvider(inner: Provider, ctx: RestateContextLike, optio
 declare function restateSessionStore(ctx: RestateObjectContextLike): SessionStore;
 //#endregion
 //#region src/restate/tool.d.ts
-interface RestateToolOptions {
+/**
+ * Opt-in two-phase journaling for long-running, re-attachable tools.
+ *
+ * The default `restateTool` wrapping journals only the COMPLETED result —
+ * a crash mid-execute re-runs the tool on replay, which is unacceptable
+ * for builds / migrations / deploys. `durableStart` splits the execution:
+ *
+ *   1. `start` runs inside its own `ctx.run` entry, journaled BEFORE the
+ *      body — it kicks off the side effect and returns a re-attach token
+ *      (a background task id, a job handle, an idempotency key).
+ *   2. `attach` runs inside the result entry with the journaled token —
+ *      on replay it receives the SAME token and re-attaches to the
+ *      already-running work instead of starting it again.
+ *
+ * The wrapped tool's own `execute` is bypassed; the start/attach pair IS
+ * the execution.
+ */
+interface RestateDurableStart<Token = unknown> {
+  /** Kick off the side effect; journaled before `attach`. Must be cheap + idempotent-safe up to journal persistence. */
+  start: (input: Record<string, unknown>, toolCtx: ToolContext) => Promise<Token> | Token;
+  /** Await / re-attach to the work identified by `token` and produce the tool result. */
+  attach: (token: Token, input: Record<string, unknown>, toolCtx: ToolContext) => Promise<string | ToolResultContent[]>;
+  /**
+   * Best-effort cleanup when the per-call abort signal fires before
+   * `attach` settles (run abort, `agent.cancelTool`, sibling-cascade
+   * cancel, `agent.destroy()` mid-run). Without it, the journaled token
+   * identifies a remote job that keeps running with nobody attached —
+   * a leak for hosts whose jobs outlive the session.
+   *
+   * Contract:
+   *   - Fires at most once per call, outside the journal (an aborting
+   *     invocation can't open new `ctx.run` entries reliably) — journal
+   *     your own cleanup on the host side if it must be durable.
+   *   - May run concurrently with a still-unwinding `attach`; make it
+   *     idempotent against "job already gone".
+   *   - NOT called on process death — that's not termination: the
+   *     journaled token re-attaches on replay instead. This seam is for
+   *     deliberate aborts, where no replay is coming.
+   *   - Errors are swallowed (surfaced under `ZIDANE_DEBUG`) — cleanup
+   *     failure must not mask the abort itself.
+   */
+  onAbort?: (token: Token, input: Record<string, unknown>, toolCtx: ToolContext) => Promise<void> | void;
+}
+interface RestateToolOptions<Token = unknown> {
   /**
    * `ctx.run` options forwarded on every wrapped tool call. Defaults to
    * `{ maxRetryAttempts: 1 }` — tool errors are typically deterministic
@@ -221,16 +377,36 @@ interface RestateToolOptions {
    */
   entryName?: (seq: number, name: string, input: Record<string, unknown>) => string;
   /**
-   * Hide and reject the built-in shell tool's background mode. Defaults to
-   * `true` because Restate cannot recover host-local background processes.
+   * Hide and reject the built-in shell tool's background mode.
+   *
+   * Default: derived from {@link RestateToolOptions.detachedTasks} —
+   * disabled unless the execution context declares `'durable'` detached
+   * tasks. An explicit boolean always wins.
    */
   disableShellBackground?: boolean;
+  /**
+   * `detachedTasks` capability of the execution context the agent will
+   * run with (see `ContextCapabilities.detachedTasks` /
+   * `resolveDetachedTasksCapability`). Drives the
+   * `disableShellBackground` default: a `'durable'` context keeps its
+   * background tasks across worker crashes, so the wrapper leaves the
+   * shell tool's background mode intact.
+   *
+   * Default: `undefined`, treated as non-durable (background disabled).
+   */
+  detachedTasks?: DetachedTasksCapability;
+  /**
+   * Two-phase start/attach journaling for crash-safe long tools — see
+   * {@link RestateDurableStart}. Per-tool by nature; not accepted by
+   * `wrapAgentTools` (a single start/attach pair can't fit a whole map).
+   */
+  durableStart?: RestateDurableStart<Token>;
 }
 /**
  * Wrap a single `ToolDef` so its `execute` runs inside `ctx.run`. The
  * tool's `spec` and `isConcurrencySafe` pass through unchanged.
  */
-declare function restateTool(inner: ToolDef, ctx: RestateContextLike, options?: RestateToolOptions): ToolDef;
+declare function restateTool<Token = unknown>(inner: ToolDef, ctx: RestateContextLike, options?: RestateToolOptions<Token>): ToolDef;
 /**
  * Wrap an entire tool map at once — convenience for the common case of
  * "journal every tool the agent has". Pass-through for tools whose
@@ -239,9 +415,9 @@ declare function restateTool(inner: ToolDef, ctx: RestateContextLike, options?:
  *
  * The returned map is a fresh object; the input is untouched.
  */
-declare function wrapAgentTools(tools: Record<string, ToolDef>, ctx: RestateContextLike, opts?: RestateToolOptions & {
+declare function wrapAgentTools(tools: Record<string, ToolDef>, ctx: RestateContextLike, opts?: Omit<RestateToolOptions, 'durableStart'> & {
   exclude?: readonly string[];
 }): Record<string, ToolDef>;
 //#endregion
-export { type RestateAwakeable, type RestateContextLike, type RestateObjectContextLike, type RestatePromiseAllLike, type RestatePromiseLike, type RestateProviderOptions, type RestateRunOptions, type RestateToolBatchExecutorOptions, type RestateToolOptions, restateBehavior, restateClock, restateProvider, restateSessionStore, restateTool, restateToolBatchExecutor, shouldRethrowRestateControlError, wrapAgentTools };
+export { type AwakeableWithTimeoutOptions, type RestateAwakeable, type RestateAwakeableToolOptions, type RestateContextLike, type RestateDurableStart, type RestateObjectContextLike, type RestatePromiseAllLike, type RestatePromiseLike, type RestatePromiseRaceLike, type RestateProviderOptions, type RestateRunOptions, type RestateToolBatchExecutorOptions, type RestateToolOptions, awakeableWithTimeout, restateAwakeableTool, restateBehavior, restateClock, restateProvider, restateSessionStore, restateTool, restateToolBatchExecutor, shouldRethrowRestateControlError, wrapAgentTools };
 //# sourceMappingURL=restate.d.ts.map

package/dist/restate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"restate.d.ts","names":[],"sources":["../src/restate/behavior.ts","../src/restate/types.ts","../src/restate/clock.ts","../src/restate/errors.ts","../src/restate/parallel.ts","../src/restate/provider.ts","../src/restate/session.ts","../src/restate/tool.ts"],"mappings":";;;;;AASA;;;;iBAAgB,eAAA,CAAgB,SAAA,GAAW,aAAA,GAAqB,aAAa;;;;;;AAA7E;;;;;;;;AAA6E;;;;ACU7E;;;UAAiB,iBAAA;EAEf;EAAA,gBAAA;EAIA;EAFA,gBAAA;EAMA;EAJA,oBAAA;EAMK;EAJL,gBAAA;EAce;EAZf,mBAAA;EAY+B;EAV/B,KAAA;AAAA;;;;;;AAYkB;AAuBpB;UAzBiB,gBAAA;EACf,EAAA;EACA,OAAA,EAAS,OAAO,CAAC,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;;UAuBF,kBAAA;EACf,GAAA,MACE,IAAA,UACA,EAAA,QAAU,OAAA,CAAQ,CAAA,IAAK,CAAA,EACvB,OAAA,GAAU,iBAAA,KACP,OAAA,CAAQ,CAAA;EACb,IAAA;IAAQ,GAAA,QAAW,OAAA;EAAA;EACnB,IAAA;IAAQ,MAAA;EAAA;EACR,SAAA,WAAoB,gBAAA,CAAiB,CAAA;AAAA;AAAC;AAUxC;;;;;;AAVwC,UAUvB,wBAAA,SAAiC,kBAAA;EAChD,GAAA;EACA,GAAA,MAAS,IAAA,aAAiB,OAAA,CAAQ,CAAA;EAClC,GAAA,MAAS,IAAA,UAAc,KAAA,EAAO,CAAA;EAC9B,KAAA,GAAQ,IAAA;AAAA;;;;;;AArEV;;;;;iBCGgB,YAAA,CAAa,GAAA,EAAK,kBAAA,GAAqB,UAAU;;;;;;AFbjE;;;;iBGFgB,gCAAA,CAAiC,KAAc;;;UCJ9C,qBAAA,kBAAuC,OAAA,YAAmB,kBAAA;EACzE,GAAA,GAAM,MAAA,WAAiB,QAAA,OAAe,OAAA;AAAA;AAAA,KAG5B,kBAAA,MAAwB,OAAA,CAAQ,CAAA;EAC1C,GAAA,MAAS,MAAA,GAAS,KAAA,GAAQ,CAAA,EAAG,OAAA,eAAsB,CAAA,KAAM,OAAA,CAAQ,CAAA;AAAA;AAAA,UAGlD,+BAAA,kBAAiD,OAAA,YAAmB,kBAAA;EJFrD;;;AAA6C;EIO3E,QAAA,EAAU,qBAAA,CAAsB,QAAA;AAAA;;AHGlC;;;;;;iBGOgB,wBAAA,kBAA0C,OAAA,YAAmB,kBAAA,UAAA,CAC3E,OAAA,EAAS,+BAAA,CAAgC,QAAA,IACxC,iBAAA;;;UCHc,sBAAA;EJMf;;AAAK;AAUP;;;;;;;;;;AAEoB;AAuBpB;;;;;;;EInBE,UAAA,GAAa,iBAAA;EJwBR;;;;;;;EIhBL,SAAA,IAAa,GAAA,UAAa,IAAA,EAAM,aAAa;EJa3C;;;;;;;EILF,eAAA;AAAA;;;;;;;iBASc,eAAA,CACd,KAAA,EAAO,QAAA,EACP,GAAA,EAAK,kBAAA,EACL,OAAA,GAAS,sBAAA,GACR,QAAA;;;;;;;;;;;iBChBa,mBAAA,CAAoB,GAAA,EAAK,wBAAA,GAA2B,YAAY;;;UC/B/D,kBAAA;ENEV;AAUP;;;;;;EMJE,UAAA,GAAa,iBAAA;ENMJ;;;AAAS;AAuBpB;;;;EMpBE,SAAA,IAAa,GAAA,UAAa,IAAA,UAAc,KAAA,EAAO,MAAM;ENuB5B;;;;EMlBzB,sBAAA;AAAA;;;;;iBAUc,WAAA,CACd,KAAA,EAAO,OAAA,EACP,GAAA,EAAK,kBAAA,EACL,OAAA,GAAS,kBAAA,GACR,OAAA;;;;;;;;;iBA2Fa,cAAA,CACd,KAAA,EAAO,MAAA,SAAe,OAAA,GACtB,GAAA,EAAK,kBAAA,EACL,IAAA,GAAM,kBAAA;EAAuB,OAAA;AAAA,IAC5B,MAAA,SAAe,OAAA"}
+{"version":3,"file":"restate.d.ts","names":[],"sources":["../src/restate/types.ts","../src/restate/awakeable.ts","../src/restate/awakeable-tool.ts","../src/restate/behavior.ts","../src/restate/clock.ts","../src/restate/errors.ts","../src/restate/parallel.ts","../src/restate/provider.ts","../src/restate/session.ts","../src/restate/tool.ts"],"mappings":";;;;;;;;AAmBA;;;;;;;;;;;AAYO;AAUP;;UAtBiB,iBAAA;EAwBC;EAtBhB,gBAAA;EAqBA;EAnBA,gBAAA;EAoBS;EAlBT,oBAAA;EAkBkB;EAhBlB,gBAAA;EAuCe;EArCf,mBAAA;EAqCiC;EAnCjC,KAAA;AAAA;;;;;;;;UAUe,gBAAA;EACf,EAAA;EACA,OAAA,EAAS,OAAO,CAAC,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;;UAuBF,kBAAA;EACf,GAAA,MACE,IAAA,UACA,EAAA,QAAU,OAAA,CAAQ,CAAA,IAAK,CAAA,EACvB,OAAA,GAAU,iBAAA,KACP,OAAA,CAAQ,CAAA;EACb,IAAA;IAAQ,GAAA,QAAW,OAAA;EAAA;EACnB,IAAA;IAAQ,MAAA;EAAA;EACR,SAAA,WAAoB,gBAAA,CAAiB,CAAA;EA0BP;;;;;;;;;;;;EAb9B,KAAA,GAAQ,MAAA,aAAmB,OAAA;AAAA;;;;;;AAcP;;UAJL,wBAAA,SAAiC,kBAAA;EAChD,GAAA;EACA,GAAA,MAAS,IAAA,aAAiB,OAAA,CAAQ,CAAA;EAClC,GAAA,MAAS,IAAA,UAAc,KAAA,EAAO,CAAA;EAC9B,KAAA,GAAQ,IAAA;AAAA;;;;;AAtEH;AAUP;;;;;UClBiB,sBAAA,kBAAwC,OAAA,YAAmB,OAAA;EAC1E,IAAA,GAAO,MAAA,WAAiB,QAAA,OAAe,OAAA;AAAA;AAAA,UAGxB,2BAAA,kBAA6C,OAAA,YAAmB,OAAA;EDgB7D;AAAA;AAuBpB;;EClCE,SAAA;EDqCoB;;;;;;;EC7BpB,QAAA,GAAW,sBAAA,CAAuB,QAAA;AAAA;;;;;;;;;;;;;;;;;iBAmBpB,oBAAA,qBAAyC,OAAA,YAAmB,OAAA,UAAA,CAC1E,GAAA,EAAK,kBAAA,EACL,OAAA,GAAS,2BAAA,CAA4B,QAAA,IACpC,gBAAA,CAAiB,CAAA;;;UC5BH,2BAAA;EFgCA;EE9Bf,IAAA;EF8BiC;EE5BjC,WAAA;EF+BY;EE7BZ,WAAA,EAAa,MAAA;EF8BD;EE5BZ,GAAA,EAAK,kBAAA;EF6BA;;;;;EEvBL,MAAA,GAAS,IAAA;IACP,WAAA;IACA,KAAA,EAAO,MAAA;IACP,OAAA,EAAS,WAAA;EAAA,aACE,OAAA;EFiBD;;;;EEZZ,QAAA,IAAY,KAAA,EAAO,CAAA,EAAG,KAAA,EAAO,MAAA,+BAAqC,iBAAA;EFahE;;;;EERF,UAAA,GAAa,iBAAA;EFUM;;;;EELnB,iBAAA;AAAA;;;;;;AFoBkC;AAUpC;;iBEnBgB,oBAAA,aAAA,CACd,OAAA,EAAS,2BAAA,CAA4B,CAAA,IACpC,OAAA;;;;;;AF7DH;;;;;;;;;;;iBGFgB,eAAA,CAAgB,SAAA,GAAW,aAAA,GAAqB,aAAa;;;;;;AHctE;AAUP;;;;iBInBgB,YAAA,CAAa,GAAA,EAAK,kBAAA,GAAqB,UAAU;;;;;;;AJHjE;;;iBKZgB,gCAAA,CAAiC,KAAc;;;UCJ9C,qBAAA,kBAAuC,OAAA,YAAmB,kBAAA;EACzE,GAAA,GAAM,MAAA,WAAiB,QAAA,OAAe,OAAA;AAAA;AAAA,KAG5B,kBAAA,MAAwB,OAAA,CAAQ,CAAA;EAC1C,GAAA,MAAS,MAAA,GAAS,KAAA,GAAQ,CAAA,EAAG,OAAA,eAAsB,CAAA,KAAM,OAAA,CAAQ,CAAA;AAAA;AAAA,UAGlD,+BAAA,kBAAiD,OAAA,YAAmB,kBAAA;ENUnF;;;;EMLA,QAAA,EAAU,qBAAA,CAAsB,QAAA;AAAA;;ANe3B;AAUP;;;;;iBMfgB,wBAAA,kBAA0C,OAAA,YAAmB,kBAAA,UAAA,CAC3E,OAAA,EAAS,+BAAA,CAAgC,QAAA,IACxC,iBAAA;;;UCHc,sBAAA;EPkBE;;AAAC;AAuBpB;;;;;;;;;;;;;;;;;;EOnBE,UAAA,GAAa,iBAAA;EPsBO;;;;;;;EOdpB,SAAA,IAAa,GAAA,UAAa,IAAA,EAAM,aAAa;EPiBrC;;;;;;;EOTR,eAAA;AAAA;;;;APwBkC;AAUpC;;iBOzBgB,eAAA,CACd,KAAA,EAAO,QAAA,EACP,GAAA,EAAK,kBAAA,EACL,OAAA,GAAS,sBAAA,GACR,QAAA;;;;;;;;;;;iBChBa,mBAAA,CAAoB,GAAA,EAAK,wBAAA,GAA2B,YAAY;;;ARMhF;;;;;;;;;;;;;;;;;AAAA,USlBiB,mBAAA;ETqBH;ESnBZ,KAAA,GAAQ,KAAA,EAAO,MAAA,mBAAyB,OAAA,EAAS,WAAA,KAAgB,OAAA,CAAQ,KAAA,IAAS,KAAA;ETmBzD;ESjBzB,MAAA,GAAS,KAAA,EAAO,KAAA,EAAO,KAAA,EAAO,MAAA,mBAAyB,OAAA,EAAS,WAAA,KAAgB,OAAA,UAAiB,iBAAA;ETkBrF;;;;;;;;;;;;;;;;;AAiBsB;AAUpC;ESzBE,OAAA,IAAW,KAAA,EAAO,KAAA,EAAO,KAAA,EAAO,MAAA,mBAAyB,OAAA,EAAS,WAAA,KAAgB,OAAA;AAAA;AAAA,UAGnE,kBAAA;ETwBW;;;;;;;EShB1B,UAAA,GAAa,iBAAA;ETgBP;;;;;;;;ESPN,SAAA,IAAa,GAAA,UAAa,IAAA,UAAc,KAAA,EAAO,MAAA;ETS/C;;;AAAoB;;;;ESDpB,sBAAA;ER7EqC;;;;;;;;;;EQwFrC,aAAA,GAAgB,uBAAA;ERvFhB;;;;;EQ6FA,YAAA,GAAe,mBAAA,CAAoB,KAAA;AAAA;;;;;iBAUrB,WAAA,iBAAA,CACd,KAAA,EAAO,OAAA,EACP,GAAA,EAAK,kBAAA,EACL,OAAA,GAAS,kBAAA,CAAmB,KAAA,IAC3B,OAAA;;;;;;;;;iBAsKa,cAAA,CACd,KAAA,EAAO,MAAA,SAAe,OAAA,GACtB,GAAA,EAAK,kBAAA,EACL,IAAA,GAAM,IAAA,CAAK,kBAAA;EAAwC,OAAA;AAAA,IAClD,MAAA,SAAe,OAAA"}

package/dist/restate.js

@@ -1,4 +1,77 @@
 import { i as hydrateReadStateFromSessionAsync } from "./read-state-CDVYj7q-.js";
+//#region src/restate/awakeable.ts
+/**
+* Mint an awakeable that resolves with the resumer's payload, or `null`
+* when `timeoutMs` elapses first. The id is journal-stable (send it
+* out-of-band as usual); the timeout is a durable `ctx.sleep`, so a
+* parked invocation suspends instead of holding a worker.
+*
+* Timeout surfaces as `null` — a resumer that resolves `undefined` is
+* indistinguishable from a timeout, so resolve a concrete payload.
+*
+* ```ts
+* // waitBackground for a durable host, in three lines:
+* const { id, promise } = awakeableWithTimeout<TaskExitInfo>(ctx, { timeoutMs, promises: RestatePromise })
+* await registerExitResumer(taskId, id) // runner → ctx.resolveAwakeable(id, info)
+* return await promise                  // TaskExitInfo, or null on timeout
+* ```
+*/
+function awakeableWithTimeout(ctx, options = {}) {
+	const awakeable = ctx.awakeable();
+	const timeoutMs = options.timeoutMs;
+	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return awakeable;
+	const timer = ctx.sleep(timeoutMs);
+	const raced = options.promises ? options.promises.race([awakeable.promise, timer]) : Promise.race([awakeable.promise, timer]);
+	return {
+		id: awakeable.id,
+		promise: raced.then((value) => value === void 0 ? null : value)
+	};
+}
+//#endregion
+//#region src/restate/awakeable-tool.ts
+/**
+* Build a `ToolDef` that parks on a Restate awakeable until an external
+* resumer resolves it. See the module doc for the replay contract.
+*
+* Do NOT additionally wrap the returned tool in `restateTool` — the
+* journal discipline is already internal, and an outer `ctx.run` would
+* illegally nest the suspension point inside a journaled closure.
+*/
+function restateAwakeableTool(options) {
+	const { name, description, inputSchema, ctx, notify, toResult } = options;
+	const runOpts = options.runOptions ?? { maxRetryAttempts: 1 };
+	let seq = 0;
+	const execute = async (input, toolCtx) => {
+		seq += 1;
+		const awakeable = ctx.awakeable();
+		const marker = await ctx.run(`awakeable-${name}-${seq}-notify`, async () => {
+			await notify({
+				awakeableId: awakeable.id,
+				input,
+				toolCtx
+			});
+			return {
+				notified: true,
+				awakeableId: awakeable.id
+			};
+		}, runOpts);
+		if (marker.awakeableId !== awakeable.id) throw new Error(`restateAwakeableTool(${name}): journal drift — broadcast marker carries awakeable "${marker.awakeableId}" but this replay minted "${awakeable.id}". The journal and the code path no longer line up; refusing to park on an unreachable awakeable.`);
+		const value = await awakeable.promise;
+		if (toResult) return toResult(value, input);
+		return typeof value === "string" ? value : JSON.stringify(value);
+	};
+	return {
+		spec: {
+			name,
+			description,
+			inputSchema
+		},
+		...options.isConcurrencySafe !== void 0 ? { isConcurrencySafe: options.isConcurrencySafe } : {},
+		execute,
+		durableExecute: execute
+	};
+}
+//#endregion
 //#region src/restate/errors.ts
 /**
 * Restate control-flow errors must escape the agent loop. If they are turned
@@ -26,11 +99,19 @@ function shouldRethrowRestateControlError(error) {
 *
 * The helper is opt-in and returns a plain AgentBehavior object, so callers can
 * spread or override it without changing non-Restate harness defaults.
+*
+* `disableBackgroundTasks: 'non-durable'` is capability-aware: background
+* tasks stay enabled for execution contexts whose
+* `capabilities.detachedTasks` is `'durable'` (tasks live on a remote
+* runner and survive worker crashes) and are disabled for everything
+* else (host-local processes don't survive process death). Hosts on
+* plain `ProcessContext` see the same effective behavior as the old
+* blanket `true`.
 */
 function restateBehavior(overrides = {}) {
 	return {
 		maxConcurrentTools: 1,
-		disableBackgroundTasks: true,
+		disableBackgroundTasks: "non-durable",
 		cache: true,
 		shouldRethrowToolError: shouldRethrowRestateControlError,
 		...overrides
@@ -188,7 +269,13 @@ function restateSessionStore(ctx) {
 		},
 		async save(session) {
 			const { turns, runs, ...header } = session;
-			ctx.set(KEY_DATA, header);
+			const prior = await ctx.get(KEY_DATA);
+			const now = await ctx.date.now();
+			ctx.set(KEY_DATA, {
+				...header,
+				createdAt: prior?.createdAt ?? now,
+				updatedAt: now
+			});
 			ctx.set(KEY_TURNS, sanitizeTurnsForState(turns));
 			ctx.set(KEY_RUNS, sanitizeRunsForState(runs));
 		},
@@ -297,7 +384,8 @@ function restateTool(inner, ctx, options = {}) {
 	const runOpts = options.runOptions ?? { maxRetryAttempts: 1 };
 	const nameFor = options.entryName ?? ((seq, name) => `tool-${name}-${seq}`);
 	const canonicalName = inner.spec.name;
-	const shellBackgroundDisabled = (options.disableShellBackground ?? true) && canonicalName === "shell";
+	const shellBackgroundDisabled = (options.disableShellBackground ?? options.detachedTasks !== "durable") && canonicalName === "shell";
+	const durableStart = options.durableStart;
 	let seq = 0;
 	const hydrateOnce = async (toolCtx) => {
 		if (toolCtx.session && !HYDRATED_READ_STATE_SESSIONS.has(toolCtx.session)) {
@@ -322,6 +410,45 @@ function restateTool(inner, ctx, options = {}) {
 			return inner.execute(input, toolCtx);
 		}, runOpts);
 	};
+	const executeTwoPhase = async (input, toolCtx) => {
+		const start = durableStart;
+		seq += 1;
+		const entry = nameFor(seq, canonicalName, input);
+		const token = await ctx.run(`${entry}-start`, async () => {
+			await hydrateOnce(toolCtx);
+			return start.start(input, toolCtx);
+		}, runOpts);
+		const attach = () => ctx.run(entry, () => start.attach(token, input, toolCtx), runOpts);
+		const onAbort = start.onAbort;
+		const signal = toolCtx.signal;
+		if (!onAbort || !signal) return attach();
+		let fired = false;
+		const fireAbortCleanup = () => {
+			if (fired) return;
+			fired = true;
+			Promise.resolve(onAbort(token, input, toolCtx)).catch((err) => {
+				if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/restate] durableStart onAbort threw: ${err instanceof Error ? err.message : String(err)}\n`);
+			});
+		};
+		if (signal.aborted) {
+			fireAbortCleanup();
+			return attach();
+		}
+		signal.addEventListener("abort", fireAbortCleanup, { once: true });
+		try {
+			return await attach();
+		} finally {
+			signal.removeEventListener("abort", fireAbortCleanup);
+		}
+	};
+	if (durableStart) {
+		const { durableExecute: _dropped, ...rest } = inner;
+		return {
+			...rest,
+			spec: shellBackgroundDisabled ? withoutShellBackgroundInput(inner.spec) : inner.spec,
+			execute: executeTwoPhase
+		};
+	}
 	return {
 		...inner,
 		spec: shellBackgroundDisabled ? withoutShellBackgroundInput(inner.spec) : inner.spec,
@@ -361,11 +488,12 @@ function isRecord(value) {
 */
 function wrapAgentTools(tools, ctx, opts = {}) {
 	const excludeSet = new Set(opts.exclude ?? []);
+	const skipWaitTask = opts.detachedTasks === "durable";
 	const wrapped = {};
-	for (const [name, def] of Object.entries(tools)) wrapped[name] = excludeSet.has(name) ? def : restateTool(def, ctx, opts);
+	for (const [name, def] of Object.entries(tools)) wrapped[name] = excludeSet.has(name) || skipWaitTask && def.spec.name === "wait_task" ? def : restateTool(def, ctx, opts);
 	return wrapped;
 }
 //#endregion
-export { restateBehavior, restateClock, restateProvider, restateSessionStore, restateTool, restateToolBatchExecutor, shouldRethrowRestateControlError, wrapAgentTools };
+export { awakeableWithTimeout, restateAwakeableTool, restateBehavior, restateClock, restateProvider, restateSessionStore, restateTool, restateToolBatchExecutor, shouldRethrowRestateControlError, wrapAgentTools };
 
 //# sourceMappingURL=restate.js.map