import type { PromptFragment, StreamTransformer } from "@b4run/core"; import type { ApprovalGrantMinter, B4Agent, B4Principal, ClientToolRecorder, RetryConfig } from "@b4run/sdk"; import { type BaseMessageLike } from "@langchain/core/messages"; import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint"; import { type JsonSchemaResponseFormat } from "./chat-model-factory.js"; import { type ResolvedStateField } from "./state-adapter.js"; import { type SubagentResolver } from "./subagent-tool-bridge.js"; import type { ResolvedSummarizationConfig } from "./summarization/index.js"; import { type OffloadFn } from "./tool-converter.js"; export interface B4ToolDefinition { readonly description?: string; readonly name: string; readonly run: (input: unknown, context: { readonly middleware?: Readonly>; readonly principal?: import("@b4run/sdk").B4Principal; readonly signal: AbortSignal; /** * The provider's id for this call, stable across LangGraph's re-execution * of an interrupted tool node. Absent when the tool is invoked outside a * model tool call. */ readonly toolCallId?: string; }) => Promise | unknown; readonly schema?: unknown; /** End the run on this tool's successful result; see the core `B4ToolDefinition`. */ readonly returnDirect?: boolean; } /** * Test-only escape hatch: reset the materialized-agents cache so the next * harness run creates a fresh LLM instance (e.g. pointing at a new aimock * port). Exported (and re-exported via `@b4run/cli/runtime`) so the * `@b4run/testing` harness can clear the cache on teardown. Not for * production use; the `__`/`ForTests` name marks it internal-by-convention. */ export declare function __resetMaterializedAgentsForTests(): void; export declare function composePromptMessages(systemPrompt: string, promptFragments: readonly PromptFragment[], state: Record): Promise; export declare function materializeAgentGraph(options: { /** Bypass the compiled-graph cache when tools close over invocation-local state. */ readonly bypassCache?: boolean; readonly checkpointer?: BaseCheckpointSaver; readonly descriptor: B4Agent; readonly middlewareContext?: Readonly>; /** Who started the run; tools read it as `ctx.principal`. Per-request, so it bypasses the graph cache. */ readonly principal?: B4Principal; readonly offload?: OffloadFn; readonly routeParamNames?: readonly string[]; readonly tools?: readonly B4ToolDefinition[]; readonly stateFields?: readonly ResolvedStateField[]; readonly streamTransformers?: readonly StreamTransformer[]; readonly promptFragments?: readonly PromptFragment[]; readonly summarization?: ResolvedSummarizationConfig; /** Bind the root model's final message to a JSON schema; see `createChatModel`. */ readonly responseFormat?: JsonSchemaResponseFormat; readonly subagentResolver?: SubagentResolver; /** * Set when the caller's tools are bound to a per-thread sandbox (workspace * fs/exec backends). Bypasses the per-descriptor cache so one thread's * sandbox closures never leak into another thread's agent. */ readonly sandboxed?: boolean; }): Promise; /** An agent event; text tokens may identify their originating model invocation. */ export interface AgentStreamChunk { readonly type: "token" | "tool_call" | "tool_call_args" | "tool_result" | "interrupt" | "done" | (string & {}); readonly data: unknown; /** Model invocation identity for text tokens, scoped to this stream. */ readonly messageId?: string; } export interface AgentOptions { /** Bypass the compiled-graph cache when tools close over invocation-local state. */ readonly bypassCache?: boolean; /** * Checkpointer used by LangGraph to park interrupted graph state and replay * from it on resume. Required — the CLI runtime supplies a SQLite-backed * instance by default. If you call agent-adapter directly (e.g. in tests), * pass `new MemorySaver()` from `@langchain/langgraph`. */ readonly checkpointer: BaseCheckpointSaver; readonly entry: unknown; /** * The agent input. For a normal invocation, this is a record like * `{messages: [...]}`. For a resume invocation (after a parked interrupt), * pass a `Command({resume: decision})` instance directly — the adapter will * forward it verbatim to `streamEvents` instead of wrapping it in messages. */ readonly input: unknown; readonly middlewareContext?: Readonly>; /** Who started the run; tools read it as `ctx.principal`. Per-request, so it bypasses the graph cache. */ readonly principal?: B4Principal; readonly offload?: OffloadFn; /** * Run-level retry for a legacy raw runnable that has no `streamEvents`: the * `withRetry` fallback re-invokes the whole runnable. Nothing else reads * it. An `agent()` descriptor route ignores this field and takes its retry * from the descriptor's own `retry`, applied per model call (see * `model-call-retry`); a raw runnable that streams is never retried. */ readonly retry?: RetryConfig; readonly routeParamNames: readonly string[]; readonly signal: AbortSignal; readonly stateFields?: readonly ResolvedStateField[]; readonly tools: readonly B4ToolDefinition[]; readonly promptFragments?: readonly PromptFragment[]; readonly streamTransformers?: readonly StreamTransformer[]; /** Resolves guarded task requests to lazily materialized child graphs. */ readonly subagentResolver?: SubagentResolver; /** * Stable per-conversation identifier used as LangGraph's `thread_id`. When * set, the agent-adapter wires it into `config.configurable.thread_id` so * the checkpointer can park interrupted state. Required for resume to work * — without a thread_id, an interrupt ends the stream with no way to * replay. */ readonly threadId?: string; /** * Per-run approval-grant minter, forwarded into * `config.configurable[APPROVAL_GRANT_MINTER_KEY]` so the park site in * `@b4run/core` can read it from the ambient run config with `getConfig()`. * * Same channel and same optionality as `threadId`: an invoker that omits it * is a legacy invoker, and the park site — not this adapter — decides * whether that absence is tolerable. Do NOT default it to a no-op minter * here; a silent no-op is exactly the failure the fail-closed rule exists to * prevent. */ readonly approvalGrantMinter?: ApprovalGrantMinter; /** * Per-run tool-call recorder, forwarded into * `config.configurable[CLIENT_TOOL_RECORDER_KEY]` so a client tool stub in * `@b4run/core` can record the call it parks and the tool converter and * subagent bridge can issue and settle a server row around every other tool * call (when the recorder carries `issue`/`settle`). Same channel and * optionality as the minter: the stub refuses to park without one, and * without one the writers record nothing, so do NOT default it. */ readonly clientToolRecorder?: ClientToolRecorder; readonly summarization?: ResolvedSummarizationConfig; /** * A JSON schema the ROOT model's final message must match, bound as the * provider's native schema-constrained output alongside the route's tools * (see `createChatModel`). Per request, so it forces a fresh graph compile. * Unsupported providers throw before any model call. */ readonly responseFormat?: JsonSchemaResponseFormat; /** * Set by the CLI runtime when a per-thread sandbox is active for this turn * (the workspace tools close over the thread's sandbox filesystem/exec * backend). Forces `bypassCache` in materializeAgent so a cached agent * compiled with one thread's sandbox tools is never reused for another * thread — the one leak a sandbox must never allow. */ readonly sandboxed?: boolean; } /** The settled shape of one non-streaming agent turn. */ export interface AgentTurnResult { /** Payload of the turn's `done` chunk — the graph's final state. */ readonly output: unknown; /** * True when the turn PARKED on a HITL interrupt instead of completing. A * parked turn ran no further model work: the human's decision arrives on a * later resume invocation, which settles the run. */ readonly parked: boolean; } /** * Run an agent turn to settlement and report BOTH its final output and whether * it parked. * * `streamAgent` yields `done` unconditionally at the end of its event stream — * including for a parked turn — so `done` alone is not completion. On this * path a pending interrupt surfaces ONLY as an `interrupt` chunk: LangGraph's * `streamEvents` final output carries no `__interrupt__` key (that key appears * only on the `invoke`/`stream` return value), so a caller that keeps just the * `done` payload cannot tell a parked turn from a finished one. Callers that * must distinguish them — the episode recorder, thread status — use this * instead of `executeAgent`. */ export declare function executeAgentTurn(options: AgentOptions): Promise; export declare function executeAgent(options: AgentOptions): Promise; export declare function streamAgent(options: AgentOptions): AsyncGenerator; //# sourceMappingURL=agent-adapter.d.ts.map