A lightweight design agent built with libfx. Describe a page and an agent writes it as one HTML file.
TypeScript
import { createHash, randomUUID } from 'node:crypto'
import { createFxAgent, createFxEngine, type FxAgent, type FxAgentHostTool, type FxEffort, type FxHostTool, type FxSession, type FxToolContext } from 'libfx'
import { createTools, type ToolHost } from './tools'
import { gatewayFetch, type GatewayError, type DesignDraftObserver } from './gateway-session'
import { readExecutionFunding } from './turn-credential'
// @ts-expect-error Node strip-types tests require the source extension.
import { AuthError } from './accounts.ts'
import type { SessionData } from './secure-session'
import type { TrialCredential } from './trial'
import { TRIAL_MODEL } from './trial-policy'
import { bindLibfxSession, chatOfLibfxSession, getActiveTurn } from './journal'
import { createDraftContext } from './draft-context'
import { closeDraftCall, storedDraftObserver } from './draft-store'
import { turnBudget } from './turn-budget'
import {
DEFAULT_MODEL,
MAX_TURN_MODEL_STEPS,
effectiveEffort,
effectiveFast,
effectiveModel,
log,
type SessionState,
} from './session'
// What each turn's tool calls receive as libfx `context`: the chat, and the fx0
// message that started the turn, so a tool's transcript items join its turn.
export interface TurnContext {
chatId: string
turnId: number
}
export const STEP_LIMIT = `Turn stopped after ${MAX_TURN_MODEL_STEPS} model steps. Send a message to continue.`
export const SIGN_IN_AGAIN = 'Sign in again to continue this chat, then resend.'
// The chat-specific pieces the agent asks for per call. agent.ts provides them;
// they live there because they read and write the chat's journal state.
export interface ChatRuntime {
toolHost(chatId: string, turnId: number, signal: AbortSignal): Promise<ToolHost>
// Also sees each design as the model writes it (agent.ts prefetches its images).
watchDraft?(observer: DesignDraftObserver | undefined): DesignDraftObserver | undefined
}
// Which model request of a turn this is: who sent it, and the conversation it
// carries. A retry or a crash's resend of a step carries the same conversation, so
// it has the same name; every new step, even after compaction, has a new one.
export function modelStepName(sender: string, body: unknown): string {
const prompt = (body as { prompt?: unknown } | null)?.prompt
// An unreadable conversation counts as a step of its own, never as a resend.
if (!Array.isArray(prompt)) return `${sender}:unread:${randomUUID()}`
return `${sender}:${createHash('sha256').update(JSON.stringify(prompt)).digest('base64url').slice(0, 22)}`
}
// libfx sends the body as bytes (a Buffer), not a string.
function requestJson(body: unknown): unknown {
try {
if (typeof body === 'string') return JSON.parse(body)
if (body instanceof ArrayBuffer) return JSON.parse(new TextDecoder().decode(body))
if (ArrayBuffer.isView(body)) return JSON.parse(new TextDecoder().decode(body))
} catch { /* libfx validates its own body */ }
return null
}
// Model requests of this conversation so far: the assistant messages after the
// last user message, plus this one. It needs no state, so it holds even where the
// turn's shared budget (turn-budget.ts) is unknown or lost.
export function turnModelStep(body: unknown): number {
const prompt = (body as { prompt?: unknown })?.prompt
if (!Array.isArray(prompt)) return 1
let steps = 1
for (let index = prompt.length - 1; index >= 0; index--) {
const role = (prompt[index] as { role?: unknown })?.role
if (role === 'user') break
if (role === 'assistant') steps++
}
return steps
}
function jsonError(status: number, message: string): Response {
return new Response(JSON.stringify({ error: { message } }), { status, headers: { 'content-type': 'application/json' } })
}
function requestHeader(input: RequestInfo | URL, init: RequestInit | undefined, name: string): string | null {
return new Headers(init?.headers).get(name) ?? (input instanceof Request ? input.headers.get(name) : null)
}
// Per chat and process: the stored credential for the request in flight, and
// gatewayFetch's rate-limit streak and Gateway's last scrubbed error.
interface ChatGateway {
gatewaySession: SessionData | TrialCredential | null
rateLimitStreak: number
lastGatewayError: GatewayError | null
}
const chatGateways = new Map<string, ChatGateway>()
// Every model request uses the executing turn's recorded funding. With no usable
// credential the request fails: fx0 never falls back to the deployment's key.
// Public model metadata, which libfx reads without a session, goes out bare.
// `sender` is the parent turn, or one subagent run: all of them share the turn's
// MAX_TURN_MODEL_STEPS, so subagents cannot multiply what one turn spends.
function chatFetch(
chatId: () => Promise<string | null>,
executionTurn: () => number | undefined,
sender = 'parent',
watchDraft?: ChatRuntime['watchDraft'],
): typeof fetch {
return async (input, init) => {
const turn = executionTurn()
const id = await chatId()
const url = new URL(input instanceof Request ? input.url : String(input))
const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
const modelRequest = method === 'POST' && url.pathname.endsWith('/language-model')
const body = modelRequest ? requestJson(init?.body) : null
const limited = () => {
log(id ?? 'unknown', 'turn:step-limit', { steps: MAX_TURN_MODEL_STEPS, sender: sender === 'parent' ? 'parent' : 'subagent' })
return jsonError(400, STEP_LIMIT)
}
// A conversation that already shows the limit stops at once, with no stored state;
// the turn's shared budget below also counts its subagents and survives a crash.
if (modelRequest && turnModelStep(body) > MAX_TURN_MODEL_STEPS) return limited()
const gateway: ChatGateway = (id && chatGateways.get(id)) || { gatewaySession: null, rateLimitStreak: 0, lastGatewayError: null }
let observer: DesignDraftObserver | undefined
if (id) {
chatGateways.set(id, gateway)
// All three use the same executing turn; reserving its preview and its step adds
// no serial round trip to the funding lookup before the model request starts.
const [funding, draft, steps] = await Promise.all([
readExecutionFunding(id, turn),
turn && modelRequest ? storedDraftObserver(id, turn).catch(() => undefined) : undefined,
turn && modelRequest ? turnBudget().reserve(id, turn, modelStepName(sender, body)) : 0,
])
if (steps > MAX_TURN_MODEL_STEPS) return limited()
// The request fails below with "sign in again"; the log says why, with
// the turn and reason only, never a credential.
if (!funding.ok && modelRequest) log(id, 'funding:refused', { turn: turn ?? null, reason: funding.refused })
const credential = funding.ok ? funding.credential : null
gateway.gatewaySession = !credential ? null : 'kind' in credential ? credential : { ...credential, email: '', loginAt: 0, isLoggedIn: true }
observer = modelRequest && watchDraft ? watchDraft(draft) : draft
}
try {
return await gatewayFetch(gateway, fetch, observer)(input, init)
} catch (error) {
// No stored credential, or one too close to expiry to start a request.
if (error instanceof AuthError) return gateway.gatewaySession && 'kind' in gateway.gatewaySession
? jsonError(error.status, error.message) : jsonError(401, SIGN_IN_AGAIN)
throw error
}
}
}
const libfxChats = new Map<string, string>()
async function chatOfRequest(sessionId: string | null): Promise<string | null> {
if (!sessionId) return null
const cached = libfxChats.get(sessionId)
if (cached) return cached
const chatId = await chatOfLibfxSession(sessionId)
if (chatId) libfxChats.set(sessionId, chatId)
return chatId
}
// Reads are safe to run twice after a crash; publishing the same document twice
// is too. Edits, questions and subagents are not, so libfx tells the model a
// call cut off by a crash may have run instead of running it again.
const IDEMPOTENT = new Set(['read_design', 'publish_design', 'screenshot_design', 'web_fetch', 'read_tool_result', 'capability_search'])
// A tool that writes never runs beside another call. A chat has one capture open at a time
// (lib/journal.ts), so two screenshots in one response must take turns too.
const WRITES = new Set(['publish_design', 'edit_design', 'screenshot_design'])
function turnContext(ctx: FxToolContext): TurnContext {
const context = ctx.context as Partial<TurnContext> | undefined
if (typeof context?.chatId !== 'string' || typeof context.turnId !== 'number') {
throw new Error('fx0 tool called without its chat context')
}
return { chatId: context.chatId, turnId: context.turnId }
}
// One set of tool definitions for every chat. Each call builds its own chat's
// host from the context libfx passes, then runs that chat's tool.
function chatTools(runtime: ChatRuntime, allowSubagent: boolean): FxAgentHostTool[] {
const definitions = createTools(templateHost, { allowSubagent })
return definitions.map((definition) => ({
...definition,
idempotent: IDEMPOTENT.has(definition.name),
writes: WRITES.has(definition.name),
async execute(input: unknown, ctx: FxToolContext) {
const { chatId, turnId } = turnContext(ctx)
const host = await runtime.toolHost(chatId, turnId, ctx.signal)
const tool = createTools(host, { allowSubagent }).find((candidate) => candidate.name === definition.name)
if (!tool) throw new Error(`unknown tool ${definition.name}`)
try { return await tool.execute(input, ctx) } finally {
if (definition.name === 'publish_design') await closeDraftCall(chatId, ctx.executionId).catch(() => {})
}
},
}))
}
// Definitions only: createTools reads names, descriptions and schemas from it.
const templateHost = new Proxy({} as ToolHost, {
get() {
return () => { throw new Error('tool definitions do not run') }
},
})
// The durable agent this process runs every chat's turns with. Its own model and
// instructions are defaults; each chat's prompt carries the chat's settings.
export function durableAgent(runtime: ChatRuntime, instructions: string): FxAgent {
const g = globalThis as unknown as { __fx0LibfxAgent?: FxAgent }
if (g.__fx0LibfxAgent) return g.__fx0LibfxAgent
const drafts = createDraftContext()
g.__fx0LibfxAgent = createFxAgent({
// No durability option: libfx picks its default, Vercel's World and Queues
// on Vercel and local files elsewhere. On Vercel a prompt runs its turn in
// the request that sent it, with no queue hop, and Vercel Queues keeps the
// prompt as a backstop until after that request's time limit.
// Placeholder: chatFetch sets each request's credential, and fx0 never uses
// libfx's environment or OIDC fallback.
apiKey: 'session-authenticated',
fetch: (input, init) => {
const id = requestHeader(input, init, 'x-session-id')
return chatFetch(() => chatOfRequest(id), () => drafts.turn(id), 'parent', runtime.watchDraft)(input, init)
},
onEvent: event => drafts.observe(event),
// Hooks run synchronously before a restored engine starts its next request.
hooks: { onEvent: event => drafts.observe(event) },
model: DEFAULT_MODEL,
instructions,
tools: [...chatTools(runtime, true), { name: 'web_search', providerExecuted: true }],
})
return g.__fx0LibfxAgent
}
function chatModel(host: SessionState, sponsored = false) {
if (sponsored) return { id: TRIAL_MODEL, effort: 'low' as FxEffort, fast: true }
return { id: effectiveModel(host), effort: effectiveEffort(host) as FxEffort, fast: effectiveFast(host) }
}
// The chat's settings for the turns its next prompts start.
export function chatSessionOptions(host: SessionState, instructions: string, turnId: number, sponsored = false) {
return {
model: chatModel(host, sponsored),
instructions,
context: { chatId: host.id, turnId } satisfies TurnContext,
}
}
// The chat's libfx session, created on its first prompt.
export async function chatSession(
agent: FxAgent,
host: SessionState,
libfxSessionId: string | null,
instructions: string,
turnId: number,
sponsored = false,
): Promise<{ session: FxSession; libfxSessionId: string }> {
const id = libfxSessionId ?? await bindLibfxSession(host.id, await agent.newSessionId())
libfxChats.set(id, host.id)
return { session: agent.session(id, chatSessionOptions(host, instructions, turnId, sponsored)), libfxSessionId: id }
}
// A subagent is an ordinary in-memory engine inside its tool call, billed to the
// same chat and counted in the parent turn's steps. A crash mid-call is the
// parent's to recover: subagent is not idempotent, so libfx tells the model the
// call may have run; a run the model starts again counts as a new one.
export async function runSubagent(
runtime: ChatRuntime,
host: SessionState,
turnId: number,
instructions: string,
task: string,
signal: AbortSignal,
): Promise<string> {
const chatId = host.id
const [funding, active] = await Promise.all([readExecutionFunding(chatId, turnId), getActiveTurn(chatId)])
// The parent turn's settings, even if the chat's were changed since it started.
const pinned = active?.id === turnId ? active.settings : undefined
const engine = await createFxEngine({
apiKey: 'session-authenticated',
fetch: chatFetch(async () => chatId, () => turnId, `subagent:${crypto.randomUUID()}`, runtime.watchDraft),
model: pinned
? { id: pinned.model, effort: pinned.effort as FxEffort, fast: pinned.fast }
: chatModel(host, funding.ok && 'kind' in funding.credential),
instructions,
tools: [
...createTools(await runtime.toolHost(chatId, turnId, signal), { allowSubagent: false }).map(tool => ({
...tool,
async execute(input: unknown, ctx: FxToolContext) {
try { return await tool.execute(input, ctx) } finally {
if (tool.name === 'publish_design') await closeDraftCall(chatId, ctx.executionId).catch(() => {})
}
},
})),
{ name: 'web_search', providerExecuted: true },
],
})
try {
const turn = engine.prompt(task, { signal })
let text = ''
for await (const event of turn) {
if (event.type === 'text_delta') text += event.delta
}
const result = await turn.result
if (result.stopReason === 'refused') throw new Error('the model refused the task')
return text || '(subagent finished with no text output; check its tool calls above)'
} finally {
await engine.close().catch(() => {})
}
}