eve/dist/src/execution/tasks/parent/tool-execution.d.ts

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

import type { ContextContainer } from "#context/container.js";
import type { FrameworkContextProvider } from "#context/provider.js";
import type { HarnessSession, StepResult } from "#harness/types.js";
import { type BackgroundToolExecutor } from "#harness/background-tools.js";
interface BackgroundToolStepResult {
    readonly backgroundTaskSession: HarnessSession;
    readonly backgroundTasks: NonNullable<StepResult["backgroundTasks"]>;
}
export declare function runBackgroundStep(ctx: ContextContainer, session: HarnessSession, callback: (session: HarnessSession) => Promise<StepResult>): Promise<StepResult>;
/**
 * Makes background tool work transactional with the harness step.
 *
 * Concretely: when the model calls a background tool,
 * the tool does real external work mid-step — it creates a task run and
 * delivers commands to its inbox — while the step itself can still fail. This
 * provider scopes that work to the step so it either lands with the step or
 * is compensated with it.
 *
 * Lifetime: one {@link BackgroundToolExecutionScope} per step. `create` runs
 * before the authored callback; exactly one of `commit` or `rollback` settles
 * the scope afterwards; `decorateStepResult` runs last, only after a
 * successful commit. Nothing survives the step except retained tasks (below).
 *
 * - `commit` — step succeeded. Compensates executions that never settled
 *   (the tool neither delegated nor completed its task), then records the
 *   task entries onto the session being persisted.
 * - `rollback` — step failed. Compensates incomplete executions, and settled
 *   ones too — unless the cause is turn cancellation: those tasks are already
 *   running, so they are retained for {@link readRetainedBackgroundToolResult}
 *   instead of killed.
 * - `decorateStepResult` — attaches `backgroundTasks` and
 *   `backgroundTaskSession` to the {@link StepResult} so the turn loop keeps
 *   tracking the spawned tasks after the step returns.
 */
export declare const backgroundToolExecutionProvider: FrameworkContextProvider<BackgroundToolExecutor>;
/**
 * Returns what a successful commit would have produced (session with task
 * entries and executor session writes applied) when turn cancellation raced
 * a successfully delegated task. `rollback` deliberately does not compensate
 * settled records on cancellation — that would kill already-running tasks —
 * so the cancellation epilogue reads this instead to keep those tasks tracked
 * in durable state rather than orphaned. `undefined` when nothing was retained.
 */
export declare function readRetainedBackgroundToolResult(ctx: ContextContainer): BackgroundToolStepResult | undefined;
export {};