eve/dist/src/harness/coordination.d.ts

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

import type { ModelMessage, ToolSet, TypedToolCall } from "ai";
import type { RuntimeActionRequest, RuntimeToolCallActionRequest, RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
import { type JsonObject } from "#shared/json.js";
import type { HarnessEmitFn, HarnessSession, HarnessToolMap, SessionStateMap, StepInput } from "#harness/types.js";
/**
 * Serializable event coordinates for one pending coordination batch.
 *
 * Runtime action results are projected back onto the parent stream using the
 * same turn and step identity as the originating `actions.requested` batch.
 */
interface PendingCoordinationEventMetadata {
    readonly sequence: number;
    readonly stepIndex: number;
    readonly turnId: string;
}
/**
 * Serializable pending coordination batch stored on `session.state`.
 *
 * Child ownership does not live here: the agent handle store records every
 * dispatched child (from before its start side effect) and is the sole
 * authority for continuing, settling, and cancelling children.
 */
export interface PendingCoordinationBatch {
    /** Framework task controls deferred to the turn owner. */
    readonly runtimeActions: readonly RuntimeToolCallActionRequest[];
    /** Authored-tool and subagent workflow tasks pending coordination. */
    readonly tasks: readonly RuntimeWorkflowTaskRequest[];
    readonly event: PendingCoordinationEventMetadata;
    readonly localFanoutSize?: number;
    readonly responseMessages: readonly ModelMessage[];
}
/**
 * Outcome of resolving a pending coordination batch.
 */
interface ResolvePendingCoordinationResult {
    readonly messages: ModelMessage[];
    readonly outcome: "continue" | "resolved" | "unresolved";
    readonly session: HarnessSession;
}
/** Returns the pending coordination batch stored on the session, if any. */
export declare function getPendingCoordinationBatch(state: SessionStateMap | undefined): PendingCoordinationBatch | undefined;
/**
 * Returns true when the session is parked on pending task/control coordination.
 */
export declare function hasPendingCoordinationBatch(state: SessionStateMap | undefined): boolean;
export declare function clearPendingCoordinationBatch(session: HarnessSession): HarnessSession;
/**
 * Stores one pending coordination batch on the session.
 */
export declare function setPendingCoordinationBatch(input: {
    readonly runtimeActions: readonly RuntimeToolCallActionRequest[];
    readonly tasks: readonly RuntimeWorkflowTaskRequest[];
    readonly event: PendingCoordinationEventMetadata;
    readonly localFanoutSize?: number;
    readonly responseMessages: readonly ModelMessage[];
    readonly session: HarnessSession;
}): HarnessSession;
/** Rejects a batch before any result or side effect can bind ambiguously by call id. */
export declare function assertUniqueCoordinationCallIds(requests: readonly {
    readonly callId: string;
}[]): void;
/**
 * Resolves one pending coordination batch back into model history.
 *
 * When all expected runtime action results are present, this appends the
 * stored assistant tool-call messages plus synthesized tool-result messages to
 * history, clears the pending batch, and emits `subagent.completed` and
 * `action.result` events back onto the parent stream.
 */
export declare function resolvePendingCoordination(input: {
    readonly emit?: HarnessEmitFn;
    readonly session: HarnessSession;
    readonly stepInput?: StepInput;
    /** Definitions whose `toModelOutput` projects a workflow tool's result for the model. */
    readonly tools?: HarnessToolMap;
}): Promise<ResolvePendingCoordinationResult>;
/**
 * Projects one AI SDK tool call into the eve runtime-action contract.
 */
export declare function createRuntimeActionRequestFromToolCall(input: {
    readonly toolCall: TypedToolCall<ToolSet>;
    readonly tools: HarnessToolMap;
}): RuntimeActionRequest;
/** Projects one deferred harness tool call into task/control coordination. */
export declare function createCoordinationRequestFromToolCall(input: {
    readonly toolCall: TypedToolCall<ToolSet>;
    readonly tools: HarnessToolMap;
}): {
    readonly kind: "runtime-action";
    readonly request: RuntimeToolCallActionRequest;
} | {
    readonly kind: "task";
    readonly request: RuntimeWorkflowTaskRequest;
};
/**
 * Coerces an AI SDK tool-call `input` into the runtime-action `JsonObject`
 * contract, throwing a `TypeError` (with the original as `cause`) that names
 * the offending tool when the payload is not a JSON object.
 *
 * String inputs are parsed as JSON first: the model protocol carries tool
 * arguments as text, and provider-executed tool calls can surface that raw
 * string — or an empty string when the model sends no arguments.
 */
export declare function resolveToolCallInputObject(value: unknown, context: {
    readonly callId: string;
    readonly toolName: string;
}): JsonObject;
export {};