@empyria/restate 0.1.23 → 0.2.0

package/AGENTS.md

@@ -24,6 +24,18 @@ is not the right default here.
 - Relative imports must include explicit `.js` extensions — Bun tolerates missing ones, Node's
   ESM resolver doesn't.
 
+## Agent entry point (`lib/agent/`)
+
+`lib/agent/` (merged in from the former `@empyria/restate-llm`) is exported only through
+`@empyria/restate/agent` ([agent.js](./agent.js)), never from [index.js](./index.js). The AI
+SDK packages (`ai`, `@ai-sdk/*`) are **optional** peer dependencies (and devDependencies for
+the tests): a consumer that only uses Admin/Cron/Pubsub must be able to import the package
+root without them installed. Never import `lib/agent/` from a root-exported module.
+
+Agent tests use `test/agent/fakes.js`'s `fakeCtx`, which mimics the journal's JSON round trip
+and a bounded `ctx.run` turning an exhausted retry into a `TerminalError` — keep it in step
+with the real SDK behaviour when touching either.
+
 ## No official Admin API client
 
 Verified directly against the published `@restatedev/restate-sdk`/`-clients` package

package/README.md

@@ -51,6 +51,66 @@ import { checkServiceHandler } from '@empyria/restate/lib/Admin.js'
 | [lib/Pubsub.js](./lib/Pubsub.js)         | `definePubsub` (register a pubsub Virtual Object on your endpoint), `pubsubPublisher` (publish into it from inside a handler, in-process), `pubsubClient` (publish/pull/subscribe to it from anywhere else, over the network) — thin wrappers around `@restatedev/pubsub`/`@restatedev/pubsub-client`. |
 | [lib/Validation.js](./lib/Validation.js) | `withValidation` — wraps a workflow handler with input/output JSON schema validation via `@empyria/common`.                                                                                                                                                                                            |
 
+## Agents: `@empyria/restate/agent`
+
+LLM agents as Restate building blocks (formerly `@empyria/restate-llm`). A separate entry
+point, so the root import never loads the AI SDK. It needs the optional peer dependencies:
+
+```bash
+bun add ai @ai-sdk/openai-compatible @ai-sdk/provider
+```
+
+```js
+import { defineAgent } from '@empyria/restate/agent'
+
+export const triage = defineAgent({
+	name: 'CorporateActionTriage',
+	env: { LLM_BASE_URL: 'https://agent-bureau.vip/v1', MODEL_ID: 'vllm/ornith-1.5' },
+	system: 'You triage corporate action notices.',
+	tools: {
+		// a Restate call to another building block
+		lookupIssuer: {
+			description: 'Look up an issuer by ISIN',
+			inputSchema: {
+				type: 'object',
+				properties: { isin: { type: 'string' } },
+				required: ['isin'],
+			},
+			block: 'IssuerService',
+			handler: 'get',
+		},
+		// a direct side effect in its own bounded ctx.run, gated by approval
+		notifyDesk: {
+			description: 'Notify the operations desk',
+			inputSchema: { type: 'object', properties: { message: { type: 'string' } } },
+			execute: async ({ message }, { idempotencyKey }) => sendToDesk(message, idempotencyKey),
+			approval: {
+				timeout: 4 * 3600_000,
+				notify: { block: 'ApprovalInbox', handler: 'request' },
+			},
+		},
+	},
+	output: TriageResultSchema, // the model answers through a final_answer tool
+	memory: 'none', // or 'session': a virtual object keyed by session, plus a reset handler
+	limits: { maxSteps: 8, maxTokens: 50_000 },
+})
+// register `triage` on your endpoint, then: POST /CorporateActionTriage/ask {"prompt": "…"}
+```
+
+| Module                                       | Purpose                                                                                                                                                                                                                                                                                                     |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [lib/agent/Agent.js](./lib/agent/Agent.js)   | `defineAgent` — builds the service/object and its `ask` handler: validated I/O, `loadContext` that journals only the skill index, session memory (object state or an external `historyStore`), step/token budgets, invocation retry policy. `createAgentService` is the deprecated `AgentService` shortcut. |
+| [lib/agent/Loop.js](./lib/agent/Loop.js)     | `runAgentLoop` — one round at a time; every LLM call and tool call is its own durable step. Journals model responses, never prompts or prior history.                                                                                                                                                       |
+| [lib/agent/Tools.js](./lib/agent/Tools.js)   | Tool specs and execution: block tools (`ctx.genericCall`), execute tools (bounded `ctx.run` with an idempotency key), approval through an awakeable with a timeout, `load_skill`, `final_answer`.                                                                                                           |
+| [lib/agent/Skills.js](./lib/agent/Skills.js) | Skill bodies stay out of the journal: `load_skill` records `{name, sha256}`, and `expandSkillRefs` puts the body back inside each LLM step. A hash mismatch within one invocation is terminal; across session turns the current body is used.                                                               |
+| [lib/agent/Errors.js](./lib/agent/Errors.js) | `toRestateLLMError` (AI SDK error → terminal / `RetryableError` / transient) and the default retry policies for LLM steps, tool steps and the agent invocation.                                                                                                                                             |
+| [lib/agent/Model.js](./lib/agent/Model.js)   | `createModel` — AI SDK model for an OpenAI-compatible endpoint (e.g. Bifrost).                                                                                                                                                                                                                              |
+
+Error policy: a tool that fails terminally (rejected or timed-out approval, a callee's
+`TerminalError`, an execute tool out of retries) goes back to the model as an error result,
+so the agent can adapt. Transient errors are left to Restate to retry, and cancellation
+always propagates.
+
 There is no official Restate Admin API client (verified directly against the published
 `@restatedev/restate-sdk`/`-clients` packages) — `lib/Admin.js` is a hand-written wrapper kept
 in sync with the live Admin API's OpenAPI spec (`<admin-url>/openapi`) by hand.

package/agent.js

@@ -0,0 +1,11 @@
+export * from './lib/agent/Agent.js'
+
+export * from './lib/agent/Loop.js'
+
+export * from './lib/agent/Tools.js'
+
+export * from './lib/agent/Model.js'
+
+export * from './lib/agent/Errors.js'
+
+export * from './lib/agent/Skills.js'

package/lib/agent/Agent.js

@@ -0,0 +1,246 @@
+import { TerminalError } from '@restatedev/restate-sdk'
+import { defineObject, defineService } from '../Admin.js'
+import { withValidation } from '../Validation.js'
+import { DEFAULT_AGENT_RETRY_POLICY } from './Errors.js'
+import { runAgentLoop } from './Loop.js'
+import { createModel } from './Model.js'
+import { assertToolSpecs } from './Tools.js'
+
+const HISTORY = 'history'
+const HISTORY_REF = 'historyRef'
+
+export const AskInputSchema = {
+	type: 'object',
+	properties: {
+		prompt: { type: 'string', minLength: 1 },
+		skillsFolder: { type: 'string' },
+		department: { type: 'string' },
+		threadId: { type: 'string' },
+		resourceId: { type: 'string' },
+	},
+	required: ['prompt'],
+	additionalProperties: false,
+}
+
+export const AskOutputSchema = {
+	type: 'object',
+	properties: {
+		text: { type: 'string' },
+		steps: { type: 'number' },
+	},
+	required: ['text', 'steps'],
+	additionalProperties: false,
+}
+
+/**
+ * @typedef {Object} HistoryStore External storage for a session agent's conversation, so
+ *   the journal and object state only ever hold a reference to it.
+ * @property {(ref: string) => Promise<Array<object>>} load Returns the messages saved under
+ *   `ref`. Must return the same messages for the same `ref` every time: refs are immutable
+ *   snapshots, e.g. a content hash or a versioned object key.
+ * @property {(sessionKey: string, messages: Array<object>) => Promise<string>} save Stores
+ *   the full conversation as a new snapshot and returns its ref.
+ *
+ * @typedef {Object} AgentSpec
+ * @property {string} name Restate service / object name. Required: each agent is its own
+ *   building block.
+ * @property {{LLM_BASE_URL: string, LLM_API_KEY?: string, MODEL_ID: string}} [env] Builds the
+ *   model via {@link createModel}, unless `model` is given.
+ * @property {import('@ai-sdk/provider').LanguageModelV4} [model]
+ * @property {string} [system] Static system prompt, prepended to `loadContext`'s.
+ * @property {(input: any) => Promise<{systemPrompt?: string, skills?: Array<{name: string, description: string, body?: string}>}>} [loadContext]
+ *   Resolves this request's system prompt and skills. Runs in its own `ctx.run`, which
+ *   records only the system prompt and the skill index — never the skill bodies.
+ * @property {(name: string, input: any) => Promise<string|undefined>} [loadSkill] Fetches one
+ *   skill body when the model asks for it. Defaults to re-running `loadContext` and
+ *   picking the body by name. The journal records only the skill's name and hash; the
+ *   body is fetched again before every model call. So it must return the same content
+ *   for the whole invocation (skills shipped with the deployment do), or the invocation
+ *   fails terminally rather than send the model changed instructions.
+ * @property {Record<string, import('./Tools.js').ToolSpec>} [tools]
+ * @property {object} [input] Input JSON Schema. Defaults to {@link AskInputSchema}.
+ * @property {(input: any) => string} [prompt] Builds the user prompt from the validated
+ *   input. Defaults to `input.prompt`.
+ * @property {object} [output] Output JSON Schema. When given, the model must answer through
+ *   the `final_answer` tool and `ask` returns its arguments. Defaults to
+ *   {@link AskOutputSchema} (`{text, steps}`).
+ * @property {'none'|'session'} [memory] `none` (default): a stateless service. `session`: a
+ *   virtual object keyed by session ID, so turns of one session run one at a time and see
+ *   the conversation so far.
+ * @property {HistoryStore} [historyStore] Session memory only. Without it, the conversation
+ *   is kept in object state, trimmed to `limits.maxHistoryTurns` — fine for short
+ *   sessions; long ones should use a store.
+ * @property {{maxSteps?: number, maxTokens?: number, maxHistoryTurns?: number}} [limits]
+ * @property {import('@restatedev/restate-sdk').RunOptions<any>} [llmRetry] Retry policy of
+ *   each LLM call step. Defaults to `DEFAULT_LLM_RETRY`.
+ * @property {import('@restatedev/restate-sdk').RetryPolicy} [retryPolicy] Invocation-level
+ *   retry policy. Defaults to {@link DEFAULT_AGENT_RETRY_POLICY}.
+ */
+
+/**
+ * Defines an LLM agent as a Restate building block. Restate itself has no agent
+ * primitive: this generates a regular service (`memory: 'none'`) or virtual object
+ * (`memory: 'session'`) with an `ask` handler that runs {@link runAgentLoop}, and enforces
+ * what a hand-written agent service tends to get wrong:
+ *
+ * - every LLM call and tool call is its own bounded, durable step;
+ * - tools are Restate calls to other building blocks, or bounded `ctx.run` side effects
+ *   that get an idempotency key;
+ * - tools can require approval through an awakeable, with a timeout;
+ * - input and output are validated, and failures are terminal;
+ * - step and token budgets, and an explicit invocation retry policy;
+ * - the journal holds only small values: the skill index, never skill bodies; a session
+ *   store's reference, never the conversation.
+ *
+ * Session agents also get a `reset` handler that forgets the conversation.
+ * @param {AgentSpec} spec
+ * @returns {import('@restatedev/restate-sdk').ServiceDefinition<string, unknown> | import('@restatedev/restate-sdk').VirtualObjectDefinition<string, unknown>}
+ * @throws {TypeError} If the spec is invalid.
+ */
+export function defineAgent(spec) {
+	const {
+		name,
+		env,
+		model = env ? createModel(env) : undefined,
+		system = '',
+		loadContext,
+		loadSkill,
+		tools = {},
+		input = AskInputSchema,
+		prompt = (validatedInput) => validatedInput.prompt,
+		output,
+		memory = 'none',
+		historyStore,
+		limits = {},
+		llmRetry,
+		retryPolicy = DEFAULT_AGENT_RETRY_POLICY,
+	} = spec
+
+	if (typeof name !== 'string' || name === '') {
+		throw new TypeError('defineAgent needs a name')
+	}
+	if (!model) throw new TypeError(`Agent '${name}' needs a model or an env to build one from`)
+	if (memory !== 'none' && memory !== 'session') {
+		throw new TypeError(`Agent '${name}': memory must be 'none' or 'session'`)
+	}
+	if (historyStore && memory !== 'session') {
+		throw new TypeError(`Agent '${name}': historyStore needs memory: 'session'`)
+	}
+	assertToolSpecs(tools)
+
+	const { maxSteps, maxTokens, maxHistoryTurns = 20 } = limits
+
+	const ask = withValidation(input, output ?? AskOutputSchema, async (ctx, validatedInput) => {
+		const userPrompt = prompt(validatedInput)
+		if (typeof userPrompt !== 'string' || userPrompt === '') {
+			throw new TerminalError(`Agent '${name}': the input produced no prompt`, {
+				errorCode: 400,
+			})
+		}
+
+		const context = loadContext
+			? await ctx.run('load-context', async () => {
+					const { systemPrompt = '', skills = [] } =
+						(await loadContext(validatedInput)) ?? {}
+					return {
+						systemPrompt,
+						skills: skills.map((skill) => ({
+							name: skill.name,
+							description: skill.description,
+						})),
+					}
+				})
+			: { systemPrompt: '', skills: [] }
+
+		const session = memory === 'session' ? await openSession(ctx, historyStore) : undefined
+
+		const result = await runAgentLoop(ctx, {
+			model,
+			system: [system, context.systemPrompt].filter(Boolean).join('\n\n'),
+			prompt: userPrompt,
+			tools,
+			skills: context.skills,
+			loadSkill: skillLoader({ loadSkill, loadContext, input: validatedInput }),
+			loadHistory: session?.load,
+			outputSchema: output,
+			maxSteps,
+			maxTokens,
+			retry: llmRetry,
+		})
+
+		if (session) await session.save(result.messages, maxHistoryTurns)
+
+		return output ? result.output : { text: result.text, steps: result.steps }
+	})
+
+	const options = { retryPolicy }
+
+	if (memory === 'none') {
+		return defineService({ name, handlers: { ask }, options })
+	}
+
+	return defineObject({
+		name,
+		handlers: {
+			ask,
+			reset: async (ctx) => {
+				ctx.clear(HISTORY)
+				ctx.clear(HISTORY_REF)
+			},
+		},
+		options,
+	})
+}
+
+/**
+ * The session's conversation: `load` returns the previous turns' messages (memoised for
+ * this execution; called inside each LLM step, so never journaled), `save` appends this
+ * turn's messages.
+ * @param {import('@restatedev/restate-sdk').ObjectContext} ctx
+ * @param {HistoryStore} [store]
+ */
+async function openSession(ctx, store) {
+	if (store) {
+		const ref = await ctx.get(HISTORY_REF)
+		let cached
+		const load = async () => (cached ??= ref ? await store.load(ref) : [])
+		return {
+			load,
+			save: async (messages) => {
+				const newRef = await ctx.run('save-history', async () =>
+					store.save(ctx.key, [...(await load()), ...messages]),
+				)
+				ctx.set(HISTORY_REF, newRef)
+			},
+		}
+	}
+
+	// Without a store, history lives in object state as a list of turns, so trimming never
+	// separates a tool call from its result.
+	const turns = (await ctx.get(HISTORY)) ?? []
+	return {
+		load: async () => turns.flat(),
+		save: async (messages, maxHistoryTurns) => {
+			ctx.set(HISTORY, [...turns, messages].slice(-maxHistoryTurns))
+		},
+	}
+}
+
+function skillLoader({ loadSkill, loadContext, input }) {
+	if (loadSkill) return (skillName) => loadSkill(skillName, input)
+	if (!loadContext) return undefined
+	return async (skillName) => {
+		const { skills = [] } = (await loadContext(input)) ?? {}
+		return skills.find((skill) => skill.name === skillName)?.body
+	}
+}
+
+/**
+ * @deprecated Use {@link defineAgent} with an explicit `name`. Kept so callers migrating
+ *   from `@empyria/restate-llm` only change their import: defines a stateless agent named
+ *   `AgentService` with the default `ask` input/output.
+ * @param {Omit<AgentSpec, 'name'>} spec
+ */
+export function createAgentService(spec) {
+	return defineAgent({ name: 'AgentService', ...spec })
+}

package/lib/agent/Errors.js

@@ -0,0 +1,86 @@
+import { TerminalError, RetryableError } from '@restatedev/restate-sdk'
+import { APICallError } from '@ai-sdk/provider'
+
+/**
+ * Default bounded retry policy for an LLM call's durable `ctx.run` step.
+ *
+ * `ctx.run`'s own SDK-wide defaults (`initialRetryInterval: 50ms`, unbounded attempts)
+ * are tuned for cheap, fast-failing side effects, not a rate-limited LLM gateway — a
+ * 50ms-then-double backoff burns through a 429's typical multi-second cooldown in a
+ * handful of attempts, and with no `maxRetryAttempts` it never gives up on a
+ * genuinely-broken endpoint. `maxRetryAttempts` also matters independently of the
+ * interval tuning: without it, any error this module fails to classify as
+ * {@link TerminalError} (see {@link toRestateLLMError}) retries forever.
+ */
+export const DEFAULT_LLM_RETRY = {
+	maxRetryAttempts: 5,
+	initialRetryInterval: 1_000,
+	maxRetryInterval: 30_000,
+	retryIntervalFactor: 2,
+}
+
+/**
+ * Default bounded retry policy for an `execute` tool's durable `ctx.run` step. Once it's
+ * exhausted, `ctx.run` throws a `TerminalError`, which the agent loop hands back to the
+ * model as a tool error instead of failing the whole invocation — see `Tools.js`.
+ */
+export const DEFAULT_TOOL_RETRY = {
+	maxRetryAttempts: 3,
+	initialRetryInterval: 500,
+	maxRetryInterval: 10_000,
+	retryIntervalFactor: 2,
+}
+
+/**
+ * Default invocation-level retry policy for an agent service/object. Applies to failures
+ * outside any bounded `ctx.run` (e.g. a bug in the handler itself): after `maxAttempts`
+ * the invocation is paused for an operator to fix and resume, never retried forever and
+ * never silently killed.
+ */
+export const DEFAULT_AGENT_RETRY_POLICY = {
+	maxAttempts: 10,
+	onMaxAttempts: 'pause',
+}
+
+/**
+ * Maps an error thrown by an AI SDK Core call (`generateText`/`streamText`/...) to the
+ * error a `ctx.run(name, fn, RunOptions)` closure should throw, so Restate retries
+ * exactly the failures worth retrying and stops immediately on the ones that aren't.
+ *
+ * `@ai-sdk/provider`'s `APICallError` already carries an `isRetryable` flag the AI SDK
+ * itself derives from the HTTP status code (true for 408/409/429/5xx, false for
+ * 400/401/403/404/422/...) — this reuses that classification instead of re-deriving it
+ * from status codes by hand, and layers Restate's two escape hatches on top of it:
+ *
+ * - Not retryable → {@link TerminalError}, so Restate fails the invocation immediately
+ *   instead of retrying an auth/config/bad-request error forever.
+ * - Retryable AND the response carried a `Retry-After` header → {@link RetryableError},
+ *   so Restate honors the gateway's own requested cooldown instead of guessing one.
+ * - Retryable with no such header → the original error, unchanged, so `ctx.run`'s own
+ *   `RunOptions` backoff (see {@link DEFAULT_LLM_RETRY}) applies.
+ * - Anything that isn't an `APICallError` at all (a thrown `TypeError`, a network-layer
+ *   error `fetch` itself throws, ...) is returned unchanged — Restate's default is to
+ *   treat any non-`TerminalError` throw as retryable, which is the right default for an
+ *   error shape this module doesn't recognize.
+ *
+ * Call sites re-throw the result — this function never throws itself, only classifies:
+ * `catch (error) { throw toRestateLLMError(error) }`.
+ * @param {unknown} error
+ * @returns {Error}
+ */
+export function toRestateLLMError(error) {
+	if (!APICallError.isInstance(error)) return error
+
+	if (!error.isRetryable) {
+		return new TerminalError(error.message, { errorCode: error.statusCode })
+	}
+
+	const retryAfterHeader = error.responseHeaders?.['retry-after']
+	const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : undefined
+
+	if (retryAfterSeconds !== undefined && Number.isFinite(retryAfterSeconds)) {
+		return RetryableError.from(error, { retryAfter: { seconds: retryAfterSeconds } })
+	}
+
+	return error
+}

package/lib/agent/Loop.js

@@ -0,0 +1,157 @@
+import { generateText } from 'ai'
+import { TerminalError } from '@restatedev/restate-sdk'
+import { DEFAULT_LLM_RETRY, toRestateLLMError } from './Errors.js'
+import { cachedSkillFetcher, expandSkillRefs } from './Skills.js'
+import { FINAL_ANSWER_TOOL, buildToolDefs, executeTool } from './Tools.js'
+
+const FINAL_ANSWER_NUDGE = `Respond by calling the ${FINAL_ANSWER_TOOL} tool with your answer.`
+
+/**
+ * Drives an AI SDK Core tool-calling loop ONE round at a time, from inside a Restate
+ * handler — deliberately NOT `generateText`'s own multi-step loop wrapped in a single
+ * `ctx.run()`. That would make the whole loop atomic to Restate: a crash mid-loop would
+ * replay it from scratch, re-billing finished LLM calls and re-executing tools that
+ * already ran. Here every LLM call and every tool call is its own durable step, so a
+ * crash resumes exactly where it left off, and each step shows up by name in Restate's
+ * invocation UI.
+ *
+ * Journal discipline: an LLM step records only the model's response (text, tool calls,
+ * token usage), never the prompt it was sent. Prior conversation comes from
+ * `loadHistory`, which is called inside each LLM step — so it must return the same
+ * messages every time it's called during one invocation (e.g. load an immutable
+ * snapshot by reference). Loaded skills work the same way: the journal holds a
+ * reference and hash, and the body is fetched again inside each LLM step (see Skills.js).
+ * @param {import('@restatedev/restate-sdk').Context} ctx
+ * @param {{
+ *   model: import('@ai-sdk/provider').LanguageModelV4,
+ *   system: string,
+ *   prompt: string,
+ *   tools?: Record<string, import('./Tools.js').ToolSpec>,
+ *   skills?: Array<{name: string, description: string}>,
+ *   loadSkill?: (name: string) => Promise<string|undefined>,
+ *   loadHistory?: () => Promise<Array<object>>,
+ *   outputSchema?: object,
+ *   maxSteps?: number,
+ *   maxTokens?: number,
+ *   retry?: import('@restatedev/restate-sdk').RunOptions<any>,
+ * }} params `skills` is the index only (name + description); `loadSkill` fetches a body
+ *   when the model asks for it. With `outputSchema`, the model must answer through the
+ *   `final_answer` tool and the loop returns that tool's input as `output`.
+ * @returns {Promise<{text: string, output?: unknown, steps: number, totalTokens: number, messages: Array<object>}>}
+ *   `messages` are the new messages of this turn only (prompt, responses, tool results).
+ */
+export async function runAgentLoop(
+	ctx,
+	{
+		model,
+		system,
+		prompt,
+		tools = {},
+		skills = [],
+		loadSkill,
+		loadHistory = async () => [],
+		outputSchema,
+		maxSteps = 8,
+		maxTokens,
+		retry = DEFAULT_LLM_RETRY,
+	},
+) {
+	const fullSystem = buildSystemPrompt(system, skills)
+	const toolDefs = buildToolDefs({ tools, hasSkills: skills.length > 0, outputSchema })
+	const messages = [{ role: 'user', content: prompt }]
+	let totalTokens = 0
+	const fetchSkill = cachedSkillFetcher(loadSkill)
+
+	for (let step = 0; step < maxSteps; step++) {
+		// `ctx.run` JSON-serialises the callback's result for the journal and hands back that
+		// copy. AI SDK's `response` is a non-enumerable getter `JSON.stringify` drops, so the
+		// plain fields the loop needs are extracted inside the callback.
+		const result = await ctx.run(
+			`llm-step-${step}`,
+			async () => {
+				try {
+					// `maxRetries: 0`: `ctx.run`'s RunOptions are the single retry authority,
+					// instead of AI SDK's own retries stacking invisibly underneath them.
+					const r = await generateText({
+						model,
+						system: fullSystem,
+						messages: [
+							...(await expandSkillRefs(await loadHistory(), {
+								fetchSkill,
+								strict: false,
+							})),
+							...(await expandSkillRefs(messages, { fetchSkill, strict: true })),
+						],
+						tools: toolDefs,
+						maxRetries: 0,
+					})
+					return {
+						text: r.text,
+						toolCalls: r.toolCalls.map(({ toolCallId, toolName, input }) => ({
+							toolCallId,
+							toolName,
+							input,
+						})),
+						responseMessages: r.response.messages,
+						totalTokens: r.usage?.totalTokens ?? 0,
+					}
+				} catch (error) {
+					throw toRestateLLMError(error)
+				}
+			},
+			retry,
+		)
+
+		messages.push(...result.responseMessages)
+		totalTokens += result.totalTokens
+		if (maxTokens !== undefined && totalTokens > maxTokens) {
+			throw new TerminalError(
+				`Agent exceeded its token budget (${totalTokens} > ${maxTokens})`,
+				{ errorCode: 429 },
+			)
+		}
+
+		if (result.toolCalls.length === 0) {
+			if (!outputSchema) {
+				return { text: result.text, steps: step + 1, totalTokens, messages }
+			}
+			messages.push({ role: 'user', content: FINAL_ANSWER_NUDGE })
+			continue
+		}
+
+		for (const [index, call] of result.toolCalls.entries()) {
+			if (outputSchema && call.toolName === FINAL_ANSWER_TOOL) {
+				return {
+					text: result.text,
+					output: call.input,
+					steps: step + 1,
+					totalTokens,
+					messages,
+				}
+			}
+			const output = await executeTool(ctx, call, { tools, loadSkill, step, index })
+			messages.push({
+				role: 'tool',
+				content: [
+					{
+						type: 'tool-result',
+						toolCallId: call.toolCallId,
+						toolName: call.toolName,
+						output,
+					},
+				],
+			})
+		}
+	}
+
+	// Exceeding maxSteps isn't a transient fault a retry could fix.
+	throw new TerminalError(`Agent loop exceeded maxSteps (${maxSteps}) without a final answer`)
+}
+
+function buildSystemPrompt(system, skills) {
+	if (skills.length === 0) return system
+
+	const index = skills.map((skill) => `- ${skill.name}: ${skill.description}`).join('\n')
+	const instructions = `Available skills — call load_skill with a skill's name to read its full instructions before following them:\n${index}`
+	return [system, instructions].filter(Boolean).join('\n\n')
+}

package/lib/agent/Model.js

@@ -0,0 +1,19 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
+
+/**
+ * AI SDK Core model, pointed at an OpenAI-compatible endpoint — Bifrost
+ * (llm-system's gateway) by default, fully overridable via env. `LLM_BASE_URL`
+ * already includes the `/v1` suffix Bifrost's own docs use (`https://agent-bureau.vip/v1`);
+ * `MODEL_ID` defaults to `vllm/ornith-1.5`, the currently-live routed model ID on that
+ * gateway (see llm-system's README, "Verifying").
+ * @param {{LLM_BASE_URL: string, LLM_API_KEY?: string, MODEL_ID: string}} env
+ * @returns {import('@ai-sdk/provider').LanguageModelV4}
+ */
+export function createModel(env) {
+	const provider = createOpenAICompatible({
+		name: 'bifrost',
+		baseURL: env.LLM_BASE_URL,
+		apiKey: env.LLM_API_KEY,
+	})
+	return provider(env.MODEL_ID)
+}