@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/core/flow-host.d.ts

@@ -1,6 +1,8 @@
-import type { Action, LiveEvent } from "@nylorun/core/contracts";
+import type { Action, ActionOutcome } from "@nylorun/core/contracts";
 import type { JsonValue, WorkflowManifest } from "@nylorun/core/define";
-import type { EffectResolution, HostEffect } from "@nylorun/harness/run";
+import type { HostEffect } from "@nylorun/harness/run";
+import type { Wake } from "../execution/types.js";
+import type { EffectDoc, Tx } from "../store/types.js";
 import { type FlowLimits } from "./limits.js";
 /** Deterministic agent session id: derive(workflowSessionId, path, …parts). */
 export declare function deriveSessionId(workflowSessionId: string, path: string, ...parts: string[]): string;
@@ -24,12 +26,6 @@ export type FlowLink = {
     readonly effectId: string;
     readonly turnId: string;
 };
-export type FlowHostStore = {
-    get<T = any>(table: string, id: string): T | undefined;
-    put(table: string, id: string, body: unknown): void;
-    all<T = any>(table: string): T[];
-    event(sessionId: string, turnId: string | null, type: string, payload: unknown): LiveEvent;
-};
 export type FlowHostSession = {
     id: string;
     agentId: string;
@@ -45,8 +41,20 @@ export type FlowHostSession = {
     creation?: unknown;
     waits?: unknown;
     lastOutput?: JsonValue;
+    /** The turn `status`, `lastOutput` and `error` describe, once it ended. */
+    lastTurnId?: string;
     error?: string;
 };
+/** How a linked agent turn ended. */
+export type LinkedTurnEnd = {
+    readonly turnId: string;
+} & ({
+    readonly status: "completed";
+    readonly output: JsonValue;
+} | {
+    readonly status: "failed" | "cancelled";
+    readonly error?: string;
+});
 export type FlowWait = {
     readonly sessionId: string;
     readonly path: string;
@@ -67,121 +75,72 @@ export type CascadeCancelPlan = {
     readonly pendingActionIds: string[];
     readonly claimedActionIds: string[];
 };
+/** Wakes a session after commit (`DurableExecution.wake` through the Tenant context). */
+type Schedule = (sessionId: string, wake: Wake) => void | Promise<void>;
+/** Effect documents as the flow host writes them. */
+export type FlowEffect = EffectDoc & {
+    agentSessionId?: string;
+    outcome?: ActionOutcome;
+    error?: string;
+};
+/** Active agent turns + pending/claimed actions for one workflow turn. */
+export declare function countActiveFlowWork(t: Tx, workflowSessionId: string, turnId: string): Promise<number>;
+/** The `commands` document key of a session command's idempotency key (`tenant/commands.ts`). */
+export declare function commandKey(sessionId: string, idempotencyKey: string): string;
+/** The idempotency key of the message a flow `agent` effect sends its linked session. */
+export declare function linkedMessageKey(request: HostEffect): string;
 /**
- * Resolve flow effects: agent (via session contract), tool nodes, fn, verify.
- * Runtime never writes agent session state — only issues commands.
+ * The linked turn an `agent` effect started: the turn its message opened, or undefined until
+ * that message commits.
+ */
+export declare function linkedTurnOf(t: Tx, agentSessionId: string, request: HostEffect): Promise<string | undefined>;
+/**
+ * How the linked turn an `agent` effect started ended, or undefined while it has not: before
+ * its message commits, the linked session's status and `lastOutput` describe an earlier turn.
+ * `agent` is the linked session, read in the caller's transaction.
+ */
+export declare function linkedTurnEnd(t: Tx, effect: Pick<FlowEffect, "request" | "agentSessionId">, agent: FlowHostSession | undefined): Promise<LinkedTurnEnd | undefined>;
+/**
+ * After a linked agent turn ends, settle the `agent` effect that started it and wake the
+ * workflow. `turnId` is the linked session's turn that ended; an effect bound to another turn
+ * (a later iteration whose message has not committed yet) is left alone.
  */
-export declare function resolveFlowEffect(input: {
-    readonly request: HostEffect;
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly limits?: FlowLimits;
-    readonly putLinkedSession: (args: {
-        id: string;
-        agentId: string;
-        ownerUserId: string;
-        vaultIds?: readonly string[];
-        credentialSelections?: readonly unknown[];
-    }) => FlowHostSession;
-    readonly sendMessage: (args: {
-        sessionId: string;
-        content?: string;
-        data?: JsonValue;
-        idempotencyKey: string;
-        requestId: string;
-    }) => {
-        turnId: string | null;
-    };
-    readonly readSession: (id: string) => FlowHostSession | undefined;
-    readonly publish: (event: LiveEvent) => void;
-    readonly notify: () => void;
-    readonly schedule: (sessionId: string) => void;
-}): EffectResolution;
-/** Active agent turns + pending/claimed actions for one workflow turn. */
-export declare function countActiveFlowWork(store: FlowHostStore, workflowSessionId: string, turnId: string): number;
-/** After an agent turn settles, wake the owning workflow if linked. */
 export declare function wakeLinkedWorkflow(input: {
+    readonly t: Tx;
     readonly agentSessionId: string;
-    readonly store: FlowHostStore;
+    readonly turnId: string | null;
     readonly output?: JsonValue;
     readonly failed?: boolean;
     readonly cancelled?: boolean;
     readonly error?: string;
-    readonly schedule: (sessionId: string) => void;
-    readonly publish: (event: LiveEvent) => void;
-}): void;
-/** On Runtime start: settle pending agent effects whose linked turns already finished. */
-export declare function reconcilePendingAgentEffects(input: {
-    readonly store: FlowHostStore;
-    readonly schedule: (sessionId: string) => void;
-    readonly publish: (event: LiveEvent) => void;
-}): void;
-/** Re-offer orphaned fn/verify claims after a process restart (SD-P7 / WF-C9). */
-export declare function reofferOrphanedFnVerifyClaims(store: FlowHostStore): number;
+    readonly schedule: Schedule;
+}): Promise<void>;
+/** Pending workflow `agent` effects with a linked session, for the Tenant sweep. */
+export declare function pendingAgentEffects(t: Tx): Promise<FlowEffect[]>;
 /**
- * On lease expiry: fn/verify → pending again; tool nodes → uncertain (WF-R35, WF-R38).
- * Returns whether any fn/verify was redelivered.
+ * Tenant sweep: settle one pending `agent` effect whose linked turn already finished (the
+ * linked settle normally does this in its own transaction). Runs in its own transaction and
+ * locks the linked agent (child) session before the workflow (parent), per the lock order in
+ * `store/types.ts`. Only the linked turn the effect started settles it (`linkedTurnEnd`): the
+ * linked session may still show an earlier iteration's settled turn while this effect's message
+ * is not committed. A linked session still `running` or `runnable` is left to the sweep's
+ * orphan re-wake; a paused one surfaces on the workflow when the workflow settles. Returns
+ * true when it changed something.
  */
-export declare function applyFlowLeaseExpiry(input: {
-    readonly store: FlowHostStore;
-    readonly action: Action;
-    readonly now?: number;
-}): "reoffer" | "uncertain" | "skip";
-/** Emit loop.verified / loop.decided after fn/verify actions complete. */
-export declare function emitLoopActionEvents(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly action: Action;
-    readonly value: unknown;
-    readonly publish: (event: LiveEvent) => void;
-}): void;
-export declare function emitNodeStarted(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly publish: (event: LiveEvent) => void;
-}, payload: {
-    path: string;
-    kind: string;
-    key: string;
-    iterations?: string;
-}): LiveEvent;
-export declare function emitNodeCompleted(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly publish: (event: LiveEvent) => void;
-}, payload: {
-    path: string;
-    iterations?: string;
-}): LiveEvent;
-export declare function emitNodeFailed(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly publish: (event: LiveEvent) => void;
-}, payload: {
-    path: string;
-    iterations?: string;
-    error: {
-        code: string;
-        message: string;
-        path?: string;
-    };
-}): LiveEvent;
-export declare function emitSwitchSelected(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly publish: (event: LiveEvent) => void;
-}, payload: {
-    path: string;
-    case: string;
-}): LiveEvent;
-export declare function emitMapItems(input: {
-    readonly store: FlowHostStore;
-    readonly session: FlowHostSession;
-    readonly publish: (event: LiveEvent) => void;
-}, payload: {
-    path: string;
-    count: number;
-}): LiveEvent;
+export declare function reconcilePendingAgentEffect(input: {
+    readonly t: Tx;
+    readonly effectId: string;
+    readonly schedule: Schedule;
+}): Promise<boolean>;
+/** Claimed `fn`/`verify` Actions, for the re-offer after a Tenant opens. */
+export declare function claimedFnVerifyActions(t: Tx): Promise<Action[]>;
+/**
+ * Re-offer one claimed `fn`/`verify` Action (SD-P7 / WF-C9): they are pure or repeat-safe, so
+ * a claim left by an executor of an earlier process is offered again at once rather than
+ * after its lease. The next claim bumps the generation, which fences a late result. Locks
+ * only the Action's session. Returns true when it re-offered.
+ */
+export declare function reofferFnVerifyClaim(t: Tx, actionId: string): Promise<boolean>;
 /** Path depth for deepest-first cancel ordering. */
 export declare function pathDepth(path: string): number;
 /**
@@ -189,10 +148,10 @@ export declare function pathDepth(path: string): number;
  * then pending → cancelled and claimed → uncertain actions (SD-P11 / WF-R53).
  */
 export declare function planCancelCascade(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly turnId: string | null;
-}): CascadeCancelPlan;
+}): Promise<CascadeCancelPlan>;
 /**
  * Cancel sibling work under a Parallel/Map parent when one branch fails (PAR-R6).
  * Agent turns listed in `agentSessionIds` are returned for the caller to cancel;
@@ -201,64 +160,66 @@ export declare function planCancelCascade(input: {
  * paths are included in the sibling path set.
  */
 export declare function cancelSiblingWork(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly turnId: string;
     /** Paths of siblings still running (not the failed branch). */
     readonly siblingPaths?: readonly string[];
     /** Effect ids the flow engine marked for fail-fast cancel. */
     readonly cancelEffectIds?: readonly string[];
-}): CancelSiblingResult;
+}): Promise<CancelSiblingResult>;
 /**
  * Apply cancel fencing to workflow-session actions (pending→cancelled, claimed→uncertain).
  */
 export declare function fenceWorkflowActions(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly turnId: string | null;
-}): {
+}): Promise<{
     cancelled: string[];
     uncertain: string[];
-};
+}>;
 /**
  * Aggregate human waits across the workflow session and linked agent sessions (WF-R51).
  */
 export declare function aggregateWaits(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
-}): FlowWait[];
+}): Promise<FlowWait[]>;
 /**
  * Look up which session owns an interaction id. Used for 409 foreign approvals (WF-R52).
  */
 export declare function findInteractionOwner(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly interactionId: string;
-}): {
+}): Promise<{
     sessionId: string;
     path: string;
-} | undefined;
+} | undefined>;
 /**
  * If approve/respond targets an interaction owned by a linked agent session,
  * return a 409 message naming that session (WF-R52 / LOOP-A4).
  */
 export declare function foreignInteractionConflict(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly interactionId: string;
-}): {
+}): Promise<{
     status: 409;
     message: string;
     ownerSessionId: string;
-} | undefined;
+} | undefined>;
 /**
  * When concurrency slots free, re-enter the workflow so queued effects can start
- * (status stays `queued` until `resolveFlowEffect` dispatches them).
+ * (status stays `queued` until the effect resolver dispatches them). Returns
+ * true when a wake was scheduled.
  */
 export declare function wakeForQueuedEffects(input: {
-    readonly store: FlowHostStore;
+    readonly t: Tx;
     readonly workflowSessionId: string;
     readonly turnId: string;
     readonly limits: FlowLimits;
-    readonly schedule: (sessionId: string) => void;
-}): boolean;
+    readonly schedule: Schedule;
+}): Promise<boolean>;
+export {};