@nylorun/runtime 0.9.0-beta → 0.11.0-beta

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

@@ -0,0 +1,225 @@
+import type { Action, ActionOutcome } from "@nylorun/core/contracts";
+import type { JsonValue, WorkflowManifest } from "@nylorun/core/define";
+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;
+/**
+ * Linked agent session id for a flow agent effect.
+ * Verifier agents (`context.role === "verify-agent"`) get a unique session per
+ * (path, turnId, iterations) so prior verdicts cannot leak across Loop iterations.
+ */
+export declare function deriveAgentEffectSessionId(workflowSessionId: string, path: string, request: {
+    readonly turnId: string;
+    readonly iterations?: string;
+    readonly context?: Record<string, unknown>;
+}): string;
+export declare function isWorkflowManifest(manifest: unknown): manifest is WorkflowManifest;
+/** Flow tool-node effect: `tool` with path/key and no agent capabilityId. */
+export declare function isFlowToolEffect(request: HostEffect): boolean;
+export declare function isFlowEffect(request: HostEffect): boolean;
+export type FlowLink = {
+    readonly workflowSessionId: string;
+    readonly path: string;
+    readonly effectId: string;
+    readonly turnId: string;
+};
+export type FlowHostSession = {
+    id: string;
+    agentId: string;
+    ownerUserId: string;
+    manifest: any;
+    manifestHash: string;
+    implementationVersion: string;
+    status: string;
+    activeTurnId: string | null;
+    info?: any;
+    vaultIds?: readonly string[];
+    credentialSelections?: readonly unknown[];
+    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;
+    readonly interactionId: string;
+    readonly kind: string;
+    readonly invocationId?: string;
+    readonly wait?: unknown;
+    readonly status?: string;
+};
+export type CancelSiblingResult = {
+    readonly cancelledActions: string[];
+    readonly uncertainActions: string[];
+    readonly agentSessionIds: string[];
+};
+export type CascadeCancelPlan = {
+    /** Linked agent sessions to cancel, deepest path first. */
+    readonly agentSessionIds: string[];
+    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;
+/**
+ * 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 wakeLinkedWorkflow(input: {
+    readonly t: Tx;
+    readonly agentSessionId: string;
+    readonly turnId: string | null;
+    readonly output?: JsonValue;
+    readonly failed?: boolean;
+    readonly cancelled?: boolean;
+    readonly error?: string;
+    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[]>;
+/**
+ * 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 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;
+/**
+ * Plan a cancel cascade for a workflow session: linked agents deepest first,
+ * then pending → cancelled and claimed → uncertain actions (SD-P11 / WF-R53).
+ */
+export declare function planCancelCascade(input: {
+    readonly t: Tx;
+    readonly workflowSessionId: string;
+    readonly turnId: string | null;
+}): 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;
+ * pending actions → cancelled, claimed tool actions → uncertain.
+ * When `cancelEffectIds` is provided, those effects are marked cancelled and their
+ * paths are included in the sibling path set.
+ */
+export declare function cancelSiblingWork(input: {
+    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[];
+}): Promise<CancelSiblingResult>;
+/**
+ * Apply cancel fencing to workflow-session actions (pending→cancelled, claimed→uncertain).
+ */
+export declare function fenceWorkflowActions(input: {
+    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 t: Tx;
+    readonly workflowSessionId: string;
+}): Promise<FlowWait[]>;
+/**
+ * Look up which session owns an interaction id. Used for 409 foreign approvals (WF-R52).
+ */
+export declare function findInteractionOwner(input: {
+    readonly t: Tx;
+    readonly workflowSessionId: string;
+    readonly interactionId: string;
+}): Promise<{
+    sessionId: string;
+    path: string;
+} | 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 t: Tx;
+    readonly workflowSessionId: string;
+    readonly interactionId: string;
+}): Promise<{
+    status: 409;
+    message: string;
+    ownerSessionId: string;
+} | undefined>;
+/**
+ * When concurrency slots free, re-enter the workflow so queued effects can start
+ * (status stays `queued` until the effect resolver dispatches them). Returns
+ * true when a wake was scheduled.
+ */
+export declare function wakeForQueuedEffects(input: {
+    readonly t: Tx;
+    readonly workflowSessionId: string;
+    readonly turnId: string;
+    readonly limits: FlowLimits;
+    readonly schedule: Schedule;
+}): Promise<boolean>;
+export {};