/** * "Where does this run?" — `backend=`, `runOn=` and `toolsRunOn=` * (Python parity: `agent/placement.py`, `agent/tools_placement.py`, * `agent/execution_mixin.py::_delegate_to_backend`). * * Two different questions, deliberately kept apart: * * - `runOn` / `backend` place the **whole agent** — model calls, loop and * tools — on a managed runtime. `runOn: "anthropic"` is shorthand for * `backend: `. * - `toolsRunOn` places **only the tools**. Thinking stays here; the shell, * the file writes and the code execution move. * * Because the two answer sets are disjoint, a wrong pairing is a typo worth * catching rather than a preference worth honouring: `runOn: "docker"` cannot * mean anything, and gets an error naming the parameter the caller wanted. * That validation is ported verbatim from `resolve_placement`. * * Neither a hosted runtime nor a remote sandbox ships in this package (they * are provider integrations), so both are resolved through registries a host * fills in — {@link registerManagedRuntime} and {@link registerToolPlace}. * An unregistered name fails loudly at construction with the same * "install the integration" shape Python uses, instead of running the agent * on the wrong machine. */ /** A managed runtime that can host an entire agent loop (Python `ManagedBackendProtocol`). */ export interface ManagedBackendLike { /** Run one prompt on managed infrastructure and return the whole response. */ execute(prompt: unknown, options?: Record): Promise | unknown; /** Optional streaming form, used when the turn is streaming. */ stream?(prompt: unknown, options?: Record): AsyncIterable; /** Optional id of the managed session, linked into the agent's session store. */ managedSessionId?: string; } /** * A place that can run a tool call (Python's `ToolPlace` / `SharedCompute` * adapters). `runTool` receives the tool name, its parsed arguments and the * local implementation, and returns the result — a local place just calls it. */ export interface ToolPlaceLike { readonly placeName: string; runTool(toolName: string, args: Record, localImplementation: () => Promise): Promise; } /** The `local` place: the tool runs in this process, unchanged (Python's default). */ export declare const LOCAL_TOOL_PLACE: ToolPlaceLike; /** * Register a runtime that `runOn: ""` may name (Python's backend * entry-point registry, which the wrapper package fills in). */ export declare function registerManagedRuntime(name: string, factory: () => ManagedBackendLike): void; /** Forget a managed runtime registration. Returns whether one was removed. */ export declare function unregisterManagedRuntime(name: string): boolean; /** Every runtime name `runOn=` accepts right now. */ export declare function managedRuntimeNames(): string[]; /** Register a place that `toolsRunOn: ""` may name (Python's compute bridge). */ export declare function registerToolPlace(name: string, factory: () => ToolPlaceLike): void; /** Forget a tool place registration. `local` cannot be removed. */ export declare function unregisterToolPlace(name: string): boolean; export declare function toolPlaceNames(): string[]; /** Anything with an `execute()` is a backend (Python: `hasattr(backend, 'execute')`). */ export declare function isManagedBackendLike(value: unknown): value is ManagedBackendLike; /** The resolved answer to "where does this run?" (Python `Placement`). */ export interface Placement { /** The managed backend running the whole agent, or `undefined`. */ backend?: ManagedBackendLike; /** The place this agent's tools run, or `undefined` for in-process. */ toolPlace?: ToolPlaceLike; } export interface ResolvePlacementInput { /** Class name, used only so errors read naturally (Python's `owner`). */ owner?: string; runOn?: unknown; toolsRunOn?: unknown; backend?: unknown; } /** * Validate the three placement options against each other and resolve them * (Python `resolve_placement` plus `Agent._hosted_backend_for`). * * Throws when two options name two different places for the same thing, or * when a place is asked to do a job it cannot do. */ export declare function resolvePlacement(input: ResolvePlacementInput): Placement; /** Everything Python forwards to a managed backend's `execute()`. */ export interface BackendDelegationOptions { temperature?: number; tools?: unknown; outputJson?: unknown; outputPydantic?: unknown; reasoningSteps?: boolean; stream?: boolean; taskName?: string; taskDescription?: string; taskId?: string; /** Python's `config` keyword: forwarded verbatim, never interpreted here. */ config?: Record; forceRetrieval?: boolean; skipRetrieval?: boolean; attachments?: readonly string[]; toolChoice?: string; } /** * Hand the whole turn to the managed backend (Python * `_delegate_to_backend`). Streams through `backend.stream()` when the turn is * streaming and the backend offers one, so tokens still reach `onToken`. */ export declare function delegateToBackend(backend: ManagedBackendLike, prompt: string, options: BackendDelegationOptions, onToken?: (token: string) => void): Promise;