eve/dist/src/subagents/handles/transitions.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import { type AgentAddress, type AgentHandleStore, type AgentHandleStoreCommand, type AgentHandleStoreCommandResult, type AgentIdentity, type StartOperation, type TurnOwnedAgentHandle } from "#subagents/handles/store.js";
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import type { AgentTurnOutcome } from "#shared/agent-turn-outcome.js";
/**
 * Records intent to start a fresh child. Must be applied to the step's
 * working snapshot before the start side effect runs, so the returned state
 * owns any child the step may have created.
 *
 * The guarantee is intra-step, not exactly-once: the prepared handle
 * durably commits only when the enclosing dispatch step's result commits.
 * A crash between an accepted start and that commit replays the step from
 * the pre-step snapshot and re-runs the side effect.
 *
 * Throws when the identity or operation already exists: fresh starts mint
 * a new identity, so a collision means corrupted derivation, not a replay.
 */
export declare function prepareAgentStart(session: HarnessSession, input: {
    readonly identity: AgentIdentity;
    readonly operation: StartOperation;
    readonly target: AgentStartTargetInput;
}): HarnessSession;
type AgentStartTargetInput = Extract<TurnOwnedAgentHandle, {
    phase: "starting";
}>["target"];
/**
 * Confirms a started child: `starting` becomes `running` with the child's
 * confirmed address. Throws when no starting handle carries the operation,
 * because confirming an unprepared start means ownership was never
 * committed. Re-confirming an already-running handle with the same
 * operation and address is a replay no-op.
 */
export declare function confirmAgentStarted(session: HarnessSession, input: {
    readonly operationId: string;
    readonly address: AgentAddress;
}): HarnessSession;
/**
 * Resolves a dispatch that definitively failed.
 *
 * - A dead start or dead continuation deletes the handle: there is no
 *   child left to own.
 * - A retryable continuation failure restores `parked` with the status the
 *   handle showed before the delivery, so the model may retry the same
 *   `agentId` later.
 *
 * Unknown operations are a no-op: the failure raced a settlement that
 * already resolved the handle.
 */
export declare function rejectAgentEffect(session: HarnessSession, input: {
    readonly operationId: string;
    readonly disposition: "dead" | "retryable";
}): HarnessSession;
/**
 * Parks every running child when the parent abandons a cancelled turn.
 *
 * Cancellation requests each running descendant's cancellation and then
 * tears down the turn inbox — the only hook a child settlement can
 * resume — so no later settlement can move these handles. Without this
 * transition they would stay `running` forever: invisible to the model,
 * unresumable, and retried by every future cancellation.
 *
 * A cancelled child settles its own turn as a park, so `parked` with
 * `"(cancelled)"` mirrors {@link settleAgentTurn}'s cancelled outcome. If
 * the child instead died, a later continuation attempt discovers the dead
 * session and {@link rejectAgentEffect} deletes the handle.
 */
export declare function abandonRunningAgentTurns(session: HarnessSession): HarnessSession;
/** Result of applying a settled child turn to the store. */
export type SettleAgentTurnResult = {
    readonly kind: "settled";
    readonly session: HarnessSession;
} | {
    readonly kind: "ignored";
    readonly reason: "unknown-operation";
};
/**
 * Applies one settled child turn: `running` becomes `parked` for a parked
 * outcome or is deleted for a terminal outcome.
 *
 * The settlement must carry the operation currently recorded on the
 * running handle; anything else is ignored so a stale delivery can never
 * move a newer turn.
 */
export declare function settleAgentTurn(session: HarnessSession, input: {
    readonly operationId: string;
    readonly outcome: AgentTurnOutcome;
}): SettleAgentTurnResult;
/** Applies one atomic owner lease command to the shared agent handle store. */
export declare function applyAgentHandleStoreCommand(store: AgentHandleStore, command: AgentHandleStoreCommand): {
    readonly result: AgentHandleStoreCommandResult;
    readonly store: AgentHandleStore;
};
/** Parks child turns still owned by workflow runs when their parent turn is cancelled. */
export declare function abandonAgentInvocationOwners<Session extends {
    readonly state?: SessionStateMap;
}>(session: Session, ownerIds: ReadonlySet<string>): Session;
/** Applies one owner-scoped handle transition to a harness session. */
export declare function applyTaskAgentHandleCommand<Session extends {
    readonly state?: SessionStateMap;
}>(session: Session, command: AgentHandleStoreCommand): {
    readonly result: AgentHandleStoreCommandResult;
    readonly session: Session;
};
export {};