Skip to main content

[Unreleased]

  • The npm packages ship unscoped: lousho (SDK), lousho-studio (Studio) and create-lousho (scaffold). The @linuxdevil/* scoped names from alpha.118/119 are dropped — they were never published to npm, so npm install lousho continues the existing package line.

[1.0.0-alpha.119] - 2026-11-14

[1.0.0-alpha.118] - 2026-11-14

  • Breaking: the npm package is published unscoped as lousho (the @linuxdevil/lousho scoped name from this cycle was never published and is dropped). Studio ships separately as lousho-studio. Update dependencies from "@linuxdevil/lousho" to "lousho" and "@linuxdevil/studio" to "lousho-studio". The lousho binary name is unchanged, so npx lousho … and lousho … commands keep working.
  • Docs: docs/agent-forge.md is retitled Lousho Studio and now documents installing the separate lousho-studio package, workspaces, which SDK runs a workspace’s agents (with each banner), the collector, and reporting deployed agents via LOUSHO_OBSERVE_PROJECT.
  • Breaking: Studio is now the separate package lousho-studio; the SDK tarball no longer contains apps/agent-forge. lousho studio finds an installed lousho-studio (local, next to the SDK, or global) and opens the current folder as a workspace, or prints Studio is a separate install: npx lousho-studio when it is missing. Inside the SDK checkout it keeps its dev/prod modes (--prod/--dev). Install Studio with npm i -g lousho-studio (or npx lousho-studio).
  • Studio: the Code tab gains “Eject to project” (POST /agents/:id/eject), which writes the agent-directory form (specToAgentDir) to agents/<id>/ in the workspace after a confirm dialog, with an explicit overwrite step when the folder already exists.
  • New lousho/observe subpath: startObserveDaemon, probeHealth, isObserveDaemon, defaultDbPath, OBSERVE_DEFAULT_PORT and the daemon option/retention defaults, so a host process (Studio) can run and probe the collector through public exports.
  • Install docs use the public npm packages again (npm install lousho, npm create lousho).
  • lousho/improve (experimental): improveAgent() proposes tested edits to an agent’s instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See Improving an agent.
  • lousho bridge: a new command that speaks Studio’s bridge protocol (NDJSON on stdin/stdout, protocol 1) so Lousho Studio can build and run a project’s agents with that project’s own SDK and dependencies. It answers hello, catalog, compile and shutdown, and runs agents: run/chat start a run or chat turn, steer/abort control it, resolveApproval/answerQuestion resume a paused run, and every AgentEvent, trace span, steer join and run settle arrives as a pushed event (flows are refused with LOUSHO_HOST_UNSUPPORTED).
  • Model strings resolve any official AI SDK provider: mistral/..., groq/..., xai/..., bedrock/..., vertex/..., azure/... and 13 more load @ai-sdk/<vendor> on the first call, and ai-sdk/<vendor>/<model> loads any other @ai-sdk/* package. The package reads its own credentials. See Providers.

[1.0.0-alpha.117] - 2026-11-09

[1.0.0-alpha.116] - 2026-11-09

[1.0.0-alpha.115] - 2026-11-09

[1.0.0-alpha.114] - 2026-11-09

[1.0.0-alpha.113] - 2026-11-09

[1.0.0-alpha.112] - 2026-11-09

[1.0.0-alpha.111] - 2026-11-09

[1.0.0-alpha.110] - 2026-11-09

[1.0.0-alpha.109] - 2026-11-09

[1.0.0-alpha.108] - 2026-11-09

[1.0.0-alpha.107] - 2026-11-09

[1.0.0-alpha.106] - 2026-11-09

[1.0.0-alpha.105] - 2026-11-09

[1.0.0-alpha.104] - 2026-11-09

[1.0.0-alpha.103] - 2026-11-08

[1.0.0-alpha.102] - 2026-11-08

[1.0.0-alpha.101] - 2026-11-08

[1.0.0-alpha.100] - 2026-11-08

[1.0.0-alpha.99] - 2026-11-08

[1.0.0-alpha.98] - 2026-11-08

[1.0.0-alpha.97] - 2026-11-08

[1.0.0-alpha.96] - 2026-11-08

[1.0.0-alpha.95] - 2026-11-08

[1.0.0-alpha.94] - 2026-11-08

[1.0.0-alpha.93] - 2026-11-08

[1.0.0-alpha.92] - 2026-11-08

[1.0.0-alpha.91] - 2026-11-08

[1.0.0-alpha.90] - 2026-11-08

[1.0.0-alpha.89] - 2026-11-08

[1.0.0-alpha.88] - 2026-11-08

[1.0.0-alpha.87] - 2026-11-08

[1.0.0-alpha.86] - 2026-11-08

[1.0.0-alpha.85] - 2026-11-08

[1.0.0-alpha.84] - 2026-11-08

[1.0.0-alpha.83] - 2026-11-08

[1.0.0-alpha.82] - 2026-11-08

[1.0.0-alpha.81] - 2026-11-08

[1.0.0-alpha.80] - 2026-11-08

[1.0.0-alpha.79] - 2026-11-08

[1.0.0-alpha.78] - 2026-11-08

[1.0.0-alpha.77] - 2026-11-08

[1.0.0-alpha.76] - 2026-11-08

[1.0.0-alpha.75] - 2026-11-08

[1.0.0-alpha.74] - 2026-11-08

[1.0.0-alpha.73] - 2026-11-08

[1.0.0-alpha.72] - 2026-11-08

[1.0.0-alpha.71] - 2026-11-08

[1.0.0-alpha.70] - 2026-11-08

[1.0.0-alpha.69] - 2026-11-08

[1.0.0-alpha.68] - 2026-11-08

[1.0.0-alpha.67] - 2026-11-08

[1.0.0-alpha.66] - 2026-11-08

[1.0.0-alpha.65] - 2026-11-08

[1.0.0-alpha.64] - 2026-11-08

[1.0.0-alpha.63] - 2026-11-08

[1.0.0-alpha.62] - 2026-11-08

[1.0.0-alpha.61] - 2026-11-08

[1.0.0-alpha.60] - 2026-11-08

[1.0.0-alpha.59] - 2026-11-08

[1.0.0-alpha.58] - 2026-11-08

[1.0.0-alpha.57] - 2026-11-08

[1.0.0-alpha.56] - 2026-11-08

[1.0.0-alpha.55] - 2026-11-08

[1.0.0-alpha.54] - 2026-11-08

[1.0.0-alpha.53] - 2026-11-07

[1.0.0-alpha.52] - 2026-11-07

[1.0.0-alpha.51] - 2026-11-07

[1.0.0-alpha.50] - 2026-11-07

[1.0.0-alpha.49] - 2026-11-07

[1.0.0-alpha.48] - 2026-11-07

[1.0.0-alpha.47] - 2026-11-07

[1.0.0-alpha.46] - 2026-11-07

[1.0.0-alpha.45] - 2026-11-07

[1.0.0-alpha.44] - 2026-11-07

[1.0.0-alpha.43] - 2026-11-07

[1.0.0-alpha.42] - 2026-11-07

[1.0.0-alpha.41] - 2026-11-07

[1.0.0-alpha.40] - 2026-11-07

[1.0.0-alpha.39] - 2026-11-07

[1.0.0-alpha.38] - 2026-11-07

[1.0.0-alpha.37] - 2026-11-07

[1.0.0-alpha.36] - 2026-11-07

[1.0.0-alpha.35] - 2026-11-07

[1.0.0-alpha.34] - 2026-11-07

[1.0.0-alpha.33] - 2026-11-07

[1.0.0-alpha.32] - 2026-11-07

  • Install docs use the public npm packages again (npm install lousho, npm create lousho).
  • lousho/improve (experimental): improveAgent() proposes tested edits to an agent’s instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See Improving an agent.
  • agent.recover({ retryWithDiagnosis: true }) gives a run that reached maxAttempts one fork told why it failed, before quarantining it. createOutputCheck() is a new hook that runs your check after a tool succeeds and tells the model what it found. A fork no longer inherits lastError and attempts from its source.
  • Behavior change: agent.recover() no longer resumes a failing run forever. It backs off exponentially from the last failure (up to 15 minutes) and stops after maxAttempts failures in a row (default 10), calling the new onQuarantined(run) once. agent.resume() still runs a quarantined run. Pass a larger maxAttempts to keep retrying longer.
  • lousho observe failures also lists runs whose process died and scores below --min-score (default 0.5).
  • agent.recover() pauses during a provider outage instead of using up each run’s attempts: after 3 provider failures in a row it stops resuming, probes with one run at growing intervals, and reports through the new onOutage(paused).
  • createProgressGuard() gains maxSameResults (default 5), which denies a tool that keeps returning the same result even when its arguments differ. Run spans record lousho.run.finish_reason, and lousho observe failures lists runs that ended without an answer and names rate limits.
  • lousho observe failures lists recurring tool and model failures by agent, from the observe database or from trace files (--traces), each with a class and trace ids. See Observability.
  • createProgressGuard(): an opt-in hook that adds advice to repeated tool failures, denies calls that keep returning the same result and tools that keep failing the same way, and stops the run with LOUSHO_RUN_NO_PROGRESS if denials continue. Actions stream as the new heal.action event; tool hooks get ctx.emit, and tool spans record lousho.tool.replaced_by_hook. See Hooks.

[1.0.0-alpha.31] - 2026-11-01

  • Behavior change: the package is renamed from @lousho/build-ai-agent to lousho, and the scaffolder from create-lousho-agent to create-lousho (npm create lousho). Update imports from @lousho/build-ai-agent to lousho (subpaths such as lousho/testing keep their names). Install with npm install lousho or npm create lousho (no token needed). The packages are also mirrored to GitHub Packages as lousho and create-lousho for the repository’s Packages tab.

[1.0.0-alpha.30] - 2026-10-31

What is on main and not yet on npm. Entries marked Behavior change can break working code; Upgrading lists each one with its opt-out.

Added

  • The lousho observe daemon: a local collector (loopback, http://127.0.0.1:7777, SQLite at ~/.lousho/observe.db) that gathers every agent’s traces, heartbeats and eval scores when LOUSHO_OBSERVE is set — no per-agent code changes. lousho observe start|status|stop|rebuild-rollups|token create; a second start on a busy port attaches when it is already the observe daemon. See Observability.
  • Agent Forge is rebuilt around a left navigation grouped Build (Agents, Playground), Observe (Traces, Threads, Monitoring), Evaluate (Evaluations: Scores, Datasets, Evaluators, Annotation queues) and Assets (Prompts, Context Hub), plus Settings. It replaces the Build/Observe toggle and the old Observe tabs, and the Build toolbar shows only on Agents. See Agent Forge.
  • Every Studio screen has a hash route with its filters in the query string (#/traces?agent=…&status=error, #/traces/<id>?obs=<step>), so a reload, a bookmark, a pasted link or back/forward lands on the same view. See Routes and deep links.
  • Studio keyboard: Ctrl+K / Cmd+K opens a command palette (go to a screen, open an agent, open a pasted trace id, toggle the light/dark theme), ? lists the shortcuts, and j/k/Enter move through and open table rows. See Keyboard.
  • The last Studio nav item shows whether the collector answers. While the daemon is down, each daemon screen shows the command to start it and fills in once it is back. Daemon screens read it through the token-gated /observe/** proxy on the studio server, which forwards reads plus only the writes the screens make. See The collector.
  • Studio Traces and Trace screens: the list filters by search (name, input, output), agent, status, model, project, prompt and time range (15m to 30d or custom, default 24 h), sorts by duration, tokens or cost, and shows input/output previews, the error message and the model. A trace opens in one viewer (tree or waterfall, the failed step selected by default) whose inspector shows the error, input and output as chat bubbles with tool-call chips (Rendered, Raw or JSON), thumbs up/down feedback, usage and attributes; the header links the agent and thread and has Copy link, Add to dataset and Add to queue. Model-call steps carry Open in Playground. See Traces.
  • Studio Threads (#/threads, one row per session, a session’s turns oldest first), Monitoring (#/monitoring: the fleet table with status, last heartbeat, runs today, error rate, p95 latency and dropped events, plus Runs, Latency p95, Error rate, Cost and Tokens charts over 1h to 30d whose buckets open the matching traces) and Scores (#/evals/scores: one row per eval with pass rate, trend, per-check pass rates and latest failures, filtered by eval, agent, source and range). See Monitoring.
  • Studio Playground (#/playground): system, user and assistant messages with {name} variables, a provider and model (mock with no key), tools borrowed from a saved agent, a streamed run with Stop, Open trace when it finishes, and Save as new prompt version. See Playground.
  • Playground deep links: #/playground?trace=<id>&fromObs=<obs> loads a model call from a trace, and #/playground?prompt=<name>[@<ref>] loads a registry prompt.
  • POST /playground/run on the studio server runs a playground request and streams SSE delta, tool_call, done and error events; runs report to the daemon as agent playground. See Playground run endpoint.
  • Studio Prompts (#/prompts: versions, labels, runs that used each version, a side-by-side diff, Move <label> here, Open in Playground) and Context Hub (#/hub: namespaces viewed as one agent, private or fleet scope, and editing a fleet entry). See Prompts.
  • The Agents builder: node cards show the model, tool count and status; an empty canvas offers templates; Inspector sections collapse and the bottom drawer resizes (both remembered); and a run’s status pill links Open trace. Builder runs report to the observe daemon under their agent id, with captured content kept out of the project’s trace files. See Agents.
  • Datasets: the daemon stores named datasets of { input, expected? } examples (GET/POST /api/v1/datasets, GET /api/v1/datasets/:name, POST /api/v1/datasets/:name/examples with an example or { from_trace_id }, which copies a trace’s root input and output, and DELETE …/examples/:id). defineEval({ dataset: 'name' }) in place of cases runs one test per example (c is { input, expected, label, example_id, source_trace_id }) and fails with LOUSHO_DATASET_UNAVAILABLE when the daemon cannot serve it. Studio’s #/evals/datasets lists, creates and browses datasets and deletes examples, and a trace’s Add to dataset copies it into one. See Datasets and Evals.
  • Online evaluator rules: /api/v1/evaluators holds rules with a filter on agent, status and name, a sample_rate and an enabled switch. Each enabled rule scores new traces as their root ends, as source: online scores named after the rule. See Online evaluator rules.
  • Code evaluators: a code rule is a function (trace) => number | { value, comment } the daemon runs in the isolate sandbox. It needs isolated-vm, plus NODE_OPTIONS=--no-node-snapshot on Node 20+; without them code rules are skipped with one warning. POST /api/v1/evaluators/:id/test dry-runs a rule on one trace without writing a score. See Online evaluators.
  • Judge evaluators: a judge rule is a model and a rubric. The daemon queues a job per matching trace, and Agent Forge runs the judge with its provider keys (a key saved in Settings, or the provider’s env var; the saved key wins), so judges run only while Studio is running. LOUSHO_STUDIO_JUDGE=0 turns Studio’s judge loop off. Studio’s /observe/api/v1/evaluators/:id/test dry-runs judge rules too. See Judge rules.
  • Studio Evaluators screen (#/evals/evaluators): lists the rules with their last run and runs in the last 24 hours, and creates, edits, enables, disables and deletes them. Test on trace dry-runs a rule on one trace id. The judge kind stays disabled until Studio has a provider key, saved in Settings or set in the provider’s env var. See Evaluators.
  • Annotation queues: /api/v1/queues holds named lists of traces with an optional rubric (name, description, min, max per score); GET /api/v1/queues/:id/next returns the oldest pending item and POST …/items/:item/complete writes its scores as human scores (or skips it). Studio’s #/evals/queues creates queues and reviews them one trace at a time beside the rubric (Enter submits, S skips), and a trace’s Add to queue adds it. See Annotation queues.
  • Human feedback scores: POST /api/v1/scores { trace_id, obs_id?, name, value, comment? } adds a source: human score (201 { score_id }; unknown trace or step 404). Each eval case also records one <evalName> score: 1 when no gate check failed and the case did not throw, else 0 with the failed gates in the comment. See The observe daemon.
  • Prompt labels: a label (prod, staging) points at one version; lousho prompt label <name> <label> <version> (or PUT /api/v1/prompts/:name/labels/:label) moves it, push --labels sets it on the pushed version, and createAgent({ prompt: 'name@prod' }), lousho prompt get name@prod and GET /api/v1/prompts/:name/:ref resolve it. A push whose text and variables equal the latest version’s mints nothing (unchanged: true). See lousho prompt.
  • Trace list API: GET /api/v1/traces takes from/to (half-open ms), q (substring of name, input or output), min_duration_ms, model, prompt (<name>[@<version>]), sort (start, duration, tokens, cost) and order, and rows add agent_name, model, error_message and input/output previews. See Trace list API.
  • Sessions API: GET /api/v1/sessions (filter by agent, status and start window, paged) and GET /api/v1/sessions/:id (the session and its traces, oldest first) with per-session trace counts, tokens, cost and last input. See Sessions API.
  • Retention: once a day the daemon deletes finished traces whose last observation ended more than lousho observe start --retention-days N ago (default 30, 0 keeps everything), with their scores and prompt-use links, plus older scores whose trace is gone and sessions that are not active and no run references. A trace with a run still open and an active session are kept. Rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. lousho observe prune --older-than <N>d prunes now and runs VACUUM. See Retention.
  • lousho observe export [--since 7d] [--agent X] [--out file] writes traces as JSONL ({ trace, observations, scores } per line) straight from the db, without a running daemon. See Export.
  • Insights series carry p95_latency_ms and error_rate per agent and bucket. A db written by an older daemon lacks them for past buckets: run lousho observe rebuild-rollups once to backfill. See The observe daemon.
  • Heartbeats carry the reporter’s dropped-event count, and each /api/v1/agents row shows it as dropped (null for older SDKs); Studio’s Monitoring fleet table shows it. See The observe daemon and Monitoring.
  • Prompt registry: createAgent({ prompt: 'name@version' }) or LOUSHO_PROMPT resolves versioned instructions from the daemon at build; every run records the version used. lousho prompt push|list|get manages it. When the daemon is unreachable, embedded instructions are used; with no instructions the agent fails closed: every run rejects with LOUSHO_PROMPT_UNRESOLVED instead of running without a system prompt. A failed fetch is not cached for good: runs in the next 30 seconds resolve at once, then the next run fetches again (waiting up to 2.5 seconds).
  • Context hub: hub() / hubTools() publish and query namespaced shared memory scoped private (the writing agent) or fleet (every agent on the daemon).
  • Fleet monitoring: heartbeat-derived agent status, agent.deregister on graceful exit, a crashed agent’s open sessions and unfinished observations flip to interrupted, and webhook alerts (--webhook, alerts.json) on down transitions and error-rate thresholds.
  • Eval scores report to the daemon: every AssertionResult lands as a score row on the exercised run’s trace (source: eval or judge); lousho eval --observe forces emission. Each case’s eval span and score rows are flushed when the case finishes, each wait capped at 1 second; the scores share the reporter’s queue, so they go out after the span and are retried while the daemon is down. A wait that runs out skips the waits of the next 30 seconds of cases.
  • Reporting to the daemon: spans that finished without an error report status ok. A down daemon’s batches are requeued and retried with exponential backoff (1 s up to 30 s); batches are capped at 1000 events and 4 MB, and a batch the daemon refuses (400/413) is dropped and counted in dropped. The queue holds at most 5000 events or 32 MB, oldest evicted first. A process dying of an uncaught exception or unhandled rejection sends the newest 16 MB it holds, blocking for at most 1 second; a graceful exit makes one final attempt capped at about 2 seconds. A run’s root span is reported when the run starts, so a run whose process is killed is still listed and turns interrupted.
  • LOUSHO_OBSERVE accepts 1/true/on/yes, an http(s):// URL, or 0/false/off/no/none/disabled/empty (any case). Any other value warns once naming LOUSHO_OBSERVE and disables reporting, instead of being posted to as a URL.
  • With LOUSHO_OBSERVE pointing at a loopback daemon, createAgent captures message and tool content for the daemon by default (captureContent: false turns it off). Only the daemon gets it: the agent’s own exporter (trace files, OTLP or vendor exporters, the built server’s OTel export) still records no content unless the agent sets captureContent: true. Captured content goes through redactContent first (see the scrubber entry under Changed). See Observability.
  • Each observe daemon writes its own pidfile beside its db (foo.db gives foo.pid), so two dbs in one folder never share one. lousho observe start exits 1 when the port already serves another db, and stop refuses to signal when the daemon on the pidfile’s port reports another db or answers as a different service. /health names the db it serves only to callers on the same machine. A daemon started with --db foo.db by an earlier build of this feature wrote the shared pidfile and is not found by the new stop: stop it before updating.
  • lousho observe start and Studio print the LOUSHO_OBSERVE value for the port and host the daemon really uses (LOUSHO_OBSERVE=http://127.0.0.1:7788 on a non-default port), and the Studio proxy answers /observe/__target with the daemon URL reporters should use.
  • sandbox({ driver: 'isolate' }) runs tool code in an isolated-vm V8 isolate (optional peer isolated-vm); defineTool({ sandbox }) opts a tool in, timeouts and OOM map to sandbox.error on the tool span. 'docker' and 'e2b' driver names are reserved for later drivers.

Changed

  • Behavior change: content captured for traces is scrubbed for secrets by default. redactContent is boolean | ((text) => string): unset or true runs a built-in scrubber over message text, system instructions, tool-call arguments and tool results that replaces API-key shapes (sk-…, lsv2_…, GitHub tokens, AWS access key ids, the token after Bearer) with [redacted]; a function replaces the scrubber (text it throws on is recorded as [redacted]); false records content as is. It catches common key formats, not every secret, so set captureContent: false if content must never reach the db. See Secrets in captured content.
  • Behavior change: sessions end. The daemon marks a session ended once none of its runs is open and nothing in it has started or finished for lousho observe start --session-idle-minutes N (default 30, 0 turns it off); ended_at is the last activity, and a new run makes it active again. Sessions in an existing db close on the first sweep that finds them idle, and ended sessions then age out with retention. See Idle sessions.
  • Behavior change: the daemon keeps 30 days of runs by default. On its first sweep after start, and daily after that, it deletes traces whose observations all finished more than --retention-days ago, with their scores; a trace with a run still open, and a session still active, is kept. Start it with --retention-days 0 to keep an existing db’s history. See Retention.
  • Studio redesign: a new look in light and dark (Settings > Appearance picks Light, Dark or System, plus Compact or Comfortable table density), a left nav that collapses to an icon rail, and a Settings screen in sections (among them Appearance, Provider keys with Set / From environment / Not set, Collector, Keyboard shortcuts). Traces gains Refresh and a Live toggle that refreshes every 5 seconds, the trace viewer switches between Tree and Waterfall, Evaluations moves between Scores, Datasets, Evaluators and Annotation queues with tabs, Ctrl/Cmd+Enter runs the Playground, and the Agents canvas opens with the whole graph fitted and the Inspector folded until you select a node. See Agent Forge.

Fixed

  • Studio filter bar: the search box keeps what you type — a trailing space (tool ) no longer gets reset when the URL echoes the trimmed query; clearing filters or navigating still updates it.
  • Insights runs/day averages over the days an agent was active in the window, so an agent first seen today with 12 runs reports 12/day instead of 12/7.
  • Studio threads: each turn now shows its full input and output (chat messages render as bubbles) instead of the 200-char previews; a turn fetches its trace as it scrolls near the viewport, shows the preview labelled “Preview (truncated)” while loading or if the trace can’t be read, and says so when the recorder truncated the turn’s I/O.
  • An open run’s root start is kept when the reporter’s buffer trims or a crash flush cuts to its newest 16 MB, so a run whose child spans overflow the buffer is still listed.
  • Studio Scores and GET /api/v1/scores?aggregate=eval: human and online scores now pass only on a value of exactly 1, so a thumbs-down or an online rule returning 0 (or 0.9) without a comment counts as a failure instead of a pass; eval and judge scores keep their rule (no failure comment, or a perfect 1), and the table and the eval detail agree.
  • Studio: the command palette and ? shortcuts sheet now keep every keydown to themselves, so S no longer skips the annotation-queue item behind them; Traces, Threads, a Thread, Prompts and the Context Hub recover in place after the daemon restarts instead of staying on “daemon down”; and the queue review’s trace tree no longer wraps a row name one letter per line at 1280px.
  • The run inspector shows error, not running, for a failed step that has no end time.
  • Studio trace viewer: an observation the crash sweep marked interrupted (or an open error one) now shows as terminal instead of “running” forever; its duration and the waterfall stop at the latest known end and the header clock stops ticking.
  • The observe daemon refuses cross-site browser writes and DNS rebinding on /api/*: a loopback-bound daemon answers only loopback Host names (403), writes carrying a non-loopback Origin (including null) or Sec-Fetch-Site: cross-site get 403, and a write with a body must be Content-Type: application/json (415) — curl -d needs -H "Content-Type: application/json". The SDK reporter, CLI and Studio already comply. See Observability.
  • Observe retention (lousho observe start --retention-days, lousho observe prune) also deletes old traces the sweep marked interrupted (a crashed run whose end never arrived); their age counts from when they were interrupted.
  • The observe daemon’s online evaluator worker no longer blocks the daemon: it yields between traces, checks each rule’s filter against the root row before loading anything else, hands code rules at most 200 observations (attrs over 8192 characters become { truncated: true }) and no scores, and judge jobs claimed by Agent Forge carry the root fields only (observations: []).
  • Error text recorded on spans (error attributes and the span status message, on runs, LLM calls, tools, resumed runs and flows) goes through the same redactContent choice as captured content, so tokens in an error no longer reach traces, exports, evaluators or judge prompts; the built-in scrubber also catches case-insensitive Bearer, Stripe sk_/rk_ live and test keys, Slack xox[abprs]- tokens, Google AIza keys and JWTs. recordSpanError and withSpan take an optional redactor (default: the built-in scrubber).

Documentation

  • Agent Forge documents the left navigation, every screen, the deep-link routes and the keyboard shortcuts, with screenshots in docs/images; Observability, CLI and Evals link to the screens. The screenshots come from an opt-in Playwright spec: LOUSHO_DOC_SHOTS=1 npx playwright test -c apps/agent-forge/playwright.config.ts docShots. See Keyboard and Routes and deep links.

Security

  • Agent Forge’s studio server requires its per-launch token on every API route regardless of path case or encoding: /PLAYGROUND/run, /Observe/api/v1/scores, //settings/... or /%70layground/run no longer skip the check. Routing is case-sensitive, and every request except a GET/HEAD of /health or the built client needs the token.
  • Agent Forge’s /observe/** proxy only ever forwards to the LOUSHO_OBSERVE_URL daemon: the upstream URL is built from the request’s path and query alone, so an absolute-form request line (GET http://a@evil.example/observe/...) can no longer point it at another host, and a path that URL parsing would rewrite (.., %2e, a literal \) is refused with 400 instead of reaching a write route the allowlist does not name. The proxy sends LOUSHO_OBSERVE_TOKEN as the bearer to a daemon that requires one, and the Playground’s “Save as new prompt version” (POST /api/v1/prompts) is forwarded instead of answering 405.

[1.0.0-alpha.29] - 2026-10-21

Changed

  • Behavior change: the built node-server and Docker image refuse to start on a non-loopback host when no auth is configured (no LOUSHO_API_TOKEN, build token or auth.ts), with LOUSHO_SERVER_UNPROTECTED. Set a token, add auth.ts, bind to 127.0.0.1, or set LOUSHO_ALLOW_PUBLIC=1 to serve an open agent on purpose. lousho build --target=docker prints the run command with -e LOUSHO_API_TOKEN=<token>.
  • The limits.maxCostUsd warning for a model with no known price names the model, says the limit is not enforced for it, and shows the registerModel() call that fixes it. It is printed once per model instead of on every step.
  • Scaffolded READMEs link to the docs site (https://lousho.com/quickstart) instead of the GitHub file on main.
  • Sessions has one statement on sharing a SQLite store, used across the docs: several processes on one host and a local disk are fine; network filesystems and multiple hosts are not.
  • Behavior change: the built node-server and Docker image resume runs a crash left in progress when they start (agent.recover()), and check again every 30 seconds until shutdown. Runs paused on an approval or a question are left alone, and a run another replica holds is skipped. LOUSHO_RECOVER_ON_START=0 turns it off. See Crash recovery.
  • Behavior change: createAgent() and defineTool() reject an option key they don’t know with LOUSHO_CONFIG_INVALID and a suggestion (requireApproval → needsApproval, maxOutputTokens → modelSettings.maxTokens) instead of ignoring it. A mistyped needsApproval used to run the tool unapproved. Keys set to undefined are ignored.
  • Behavior change: the workspace file tools deny .env and .env.* by default as well as .git. .env.example, .env.sample and .env.template stay readable. A deny list you pass still replaces the defaults.
  • POST /chat answers 409 with Retry-After: 2 and code: LOUSHO_SESSION_BUSY when another process or replica is running the session, instead of a 200 stream holding only the error. An Idempotency-Key resend that hits a running turn gets the same 409.
  • Scaffolded agents (lousho init, create-lousho-agent) set modelSettings: { maxTokens: 4096 }, so a first run on a low-credit OpenRouter key no longer fails with “requires more credits, or fewer max_tokens”. The generated README explains the error.
  • Error docs links point to https://lousho.com/errors#<code> instead of the GitHub file on main.
  • The Docker image creates /app/data owned by node and declares it a VOLUME, so a fresh named volume works with LOUSHO_STORE=sqlite:/app/data/lousho.db.
  • The Authentication examples read secrets from the environment and fail at startup when they are missing, instead of falling back to a literal secret.
  • Behavior change: the built node-server (and the Docker image) now guards POST /channels/<name> and its approvals route for a channel without verify with LOUSHO_API_TOKEN / auth.ts, the same as /chat. Before, such a channel answered anyone even with a token set. Channels that verify their own requests (Slack, Discord, Telegram, GitHub, Teams, webhookChannel with a secret, any channel with verify) are unchanged, and the start-up log lists each channel route’s guard (self-verified, server-auth or open).
  • Behavior change: webhookChannel replies with { sessionId, text, finishReason, approval? } (plus approvalPrompt on a pause), as httpChannel does, instead of the full ExecutionResult. The full result echoed the system prompt and the whole transcript to the caller. fullResult: true restores the old body.
  • Channels answer a turn on a session that another process or replica is running (LOUSHO_SESSION_BUSY) with 409 and Retry-After: 2 instead of a 500, and report a turn that fails before the request is acknowledged to onError with stage 'turn' (it said 'parse').
  • README and Comparison no longer list ACP and MCP as differentiators, and describe Agent Forge as a local visual console.
  • CI is one workflow with two jobs: ci (type checks, lint, build, tests with coverage, docs, API and fallow gates, pack-smoke, size check, and a zod 4 type check) and compat (the newest peers, ai 7 with zod 4, plus the real-Docker sandbox tests). The separate Docker Engine, Agent Forge E2E and weekly registry-smoke workflows and the ai 6 / zod 3 matrix entries are gone; npm run registry-smoke and npm run test:e2e:studio still run locally. When the fallow gate fails, CI now prints its full health and duplication reports.

Added

  • GET /ready on the built node-server and Docker image: 200 {"status":"ready"} while serving, 503 {"status":"draining"} once shutdown starts. /health is unchanged. See Deployment.
  • The built server exports OpenTelemetry traces over OTLP/HTTP when OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) is set, next to any exporter the agent already has. It loads @opentelemetry/sdk-trace-node, @opentelemetry/resources and @opentelemetry/exporter-trace-otlp-http only then, says how to install them when missing, and honours OTEL_SERVICE_NAME. See Observability.
  • createAgent({ toolErrorMessage }) replaces the text of a thrown tool error (kind: 'execution') before it reaches the model, tool.error events and hooks; a sanitizer that throws gives “The tool failed.”. See Tools.
  • lousho init and create-lousho-agent generate an AGENTS.md for coding agents (the project’s real scripts, conventions and docs links) and a CLAUDE.md that imports it.
  • lousho add falls back to the registry bundled in the npm package (registry/dist) when registry.lousho.com and its GitHub fallbacks are unreachable, with a notice that the bundled copy may be older.
  • Pause, restart and resume: one tutorial for an approval that waits across a restart, crash recovery, and resending over HTTP.
  • SECURITY.md: supported versions, private reporting through GitHub, and the disclosure policy.
  • httpChannel() created without verify logs one warning that the channel is unauthenticated and its sessionKey values are guessable. Channels shows verify in the quick start, and Deployment says which routes LOUSHO_API_TOKEN guards.
  • POST /chat accepts an Idempotency-Key header: a resend with the same key replays the finished turn’s reply (Idempotent-Replayed: true, nothing runs), resumes a turn a crash interrupted instead of appending the message again, and is a 409 (LOUSHO_SESSION_BUSY) while that turn still runs. The key is stored on the turn’s user message (metadata.idempotencyKey), so it survives restarts; session.pending() reports it as idempotencyKey. See Resending a turn.
  • fromAiSdkTools(record) converts Vercel AI SDK tools (tool({ ... }) or plain { description, inputSchema | parameters, execute, needsApproval? } objects) into Lousho tools, keyed by name: zod and Standard Schemas are kept, jsonSchema() wrappers and plain JSON Schemas are converted (their own validate still runs), needsApproval (boolean or function) pauses the run for approval, and execute gets the call id and the run’s abort signal. It imports nothing from ai, so tools built on ai 4 to 7 work with any installed version. New guide: Migrating from the AI SDK.
  • lousho eval without vitest installed now says it runs *.eval.ts files through vitest, the directory it searched from, and the install command; Evals states the requirement up front.
  • result.usage.delegated.toolErrors: the tool calls that failed inside a run’s sub-agents (and theirs), which the lead’s own result.toolErrors does not count. ToolCallContext.onDelegatedUsage takes the child’s toolErrors as an optional second argument.
  • The session HTTP API (createRouteHandler(), the deployed node server, the Worker, lousho dev) writes an SSE comment (: ping) after 15 seconds without an event, so proxies and client idle timeouts no longer drop a turn whose model or tool is slow; heartbeatMs changes the interval (0 turns it off). See HTTP API.
  • google/<model> model strings (e.g. createAgent({ model: 'google/gemini-2.5-flash' })) and a GoogleProvider, backed by the optional peer @ai-sdk/google (^1.2.0 with ai 4, ^3.0.0 with ai 6, ^4.0.0 with ai 7) and reading GOOGLE_GENERATIVE_AI_API_KEY. lousho init --provider google, lousho doctor (package pairing, key, --ping) and the missing-peer install hint cover it. See Providers.
  • An unknown model prefix (mistral/..., xai/...) now says how to reach the vendor anyway: openrouter/<vendor>/<model>, pi/<vendor>/<model> when pi serves it, or fromAiSdk() with the vendor’s AI SDK package. See Vendors without a prefix.
  • lousho doctor fails an installed ai 5 (AI SDK v5 is not supported) with an upgrade hint to ai 6 or 7 and the matching @ai-sdk/* majors.

Fixed

  • lousho build works again in a project without the optional @opentelemetry/* packages (every fresh scaffold): the OTel exporter added for the built server is loaded only when OTEL_EXPORTER_OTLP_ENDPOINT is set, and the build leaves those packages unresolved instead of failing with Could not resolve "@opentelemetry/api". The scaffold end-to-end test now builds the server and checks /health.
  • The httpChannel() “no verify” warning no longer says the channel is unauthenticated when the built server guards it with LOUSHO_API_TOKEN or auth.ts, and Channels shows webhookChannel’s trimmed reply.
  • lousho add works again when registry.lousho.com is unreachable: the fallback now tries the release tag as the repository names it (1.0.0-alpha.24), then the v-prefixed tag, then main. It asked only for v<version>, which 404’d.
  • The file tools’ deny list (.git by default) is now also checked where a path really leads: a symlink or Windows junction inside the workspace pointing at .git or into it (gitj -> .git) let edit_file gitj/config rewrite .git/config (for example core.hooksPath, which runs code on the next git command) and write_file gitj/PWNED create files in .git. Reads, writes, edits, list_dir, and glob/grep given such a link as path are now refused. Providers with links can implement the new optional FsProvider.realPath(path); NodeWorkspace does. See Workspace tools.
  • NodeWorkspace.writeFile (and so write_file / edit_file) writes a temp file in the same directory and renames it into place, so a process killed mid-write no longer leaves a truncated file. A replaced file keeps its permission bits; a read-only file is still refused.
  • WorkspaceCheckpoints stores a file’s backup before write_file / edit_file writes it, not after. A process killed between the write and the backup lost the original: on resume the re-run call backed up the agent’s own content, so rewind() reported restored but put back the agent’s version (or, for edit_file, recorded nothing). A re-run now keeps the turn’s first backup, and rewind treats a file still holding its backed-up content as nothing to undo. track() also accepts a PreparedWorkspaceWrite ({ prepare, write }), which the built-in tools use.
  • edit_file re-run after a crash (the edit already in the file: old_string gone, a non-empty new_string present, also with replace_all) now succeeds with “the edit was already applied” and writes nothing, instead of failing with old_string was not found and sending the model into a loop. A write_file / edit_file that leaves the file unchanged no longer records a checkpoint backup.
  • Sessions no longer says to call resume() before resolving an approval after a restart: agent.approvals.resolve() / streamResolve() from a fresh process finds the session itself. It and Build a coding agent now say how to show a resumed turn’s progress (session.on(), onEvent), and the guide points long coding turns at compaction.
  • MCP tool schemas with OpenAPI’s nullable: true (any type) now accept null; the model’s valid null was rejected with ToolArgumentsValidationError.
  • A failed MCP tool call (server exited, timeout, protocol error) now rejects with LOUSHO_MCP_CALL_FAILED, naming <server>__<tool> with the MCP error as cause, instead of a bare MCP error -32000: Connection closed. MCP now says stdio env is merged onto the MCP SDK’s default allow-list, not process.env.
  • Flows (consumer harness): a {{variable}} holding an object (a toolCall result, an MCP result) no longer reaches a prompt as [object Object]: an object whose only field is text (an MCP tool result) is that text, a raw MCP { content } result its text parts, and any other object or array its JSON. Placeholders take dotted paths ({{res.user.name}}, {{list.0}}, own properties only), also as whole tool-argument values. An evaluator step stores its result in outputVariable. See Template values.
  • Flows: a durable run is saved before its first step, so a run whose first step failed can be resume()d instead of failing with LOUSHO_CHECKPOINT_NOT_FOUND, whose hint for a flow run now points at FlowExecutor.execute() rather than forking session history. A step’s checkpoint is saved before its step-complete event, so a crash in between no longer re-runs a step reported complete.
  • Flows: an llmCall whose model request fails rejects with the same compacted CompactedLLMProviderError as an agent run (LOUSHO_PROVIDER_* code, compacted.category), not the provider SDK’s raw APICallError, and its retry no longer retries a failure marked retryable: false (a 401, an exhausted quota, a too-long prompt).
  • A provider answering a streaming request with HTTP 200 and a body that is neither an event stream nor valid JSON (for example a truncated {"choices": [ {"oops) no longer ends as a silent empty reply. It now fails as a retryable 502, so withRetry retries it and an exhausted retry surfaces as a provider error.
  • A sub-agent with an output schema that ran out of steps and gave a valid object in its forced final call is now a task result (the object, with a line saying the steps ran out), not a failure telling the lead it gave no final answer - which made leads re-run the task.
  • Sub-agents are held to their lead’s token, cost and duration limits while they run, counted with what the lead and its other running sub-agents have spent, so parallel sub-agents no longer each spend the lead’s whole budget (a lead with maxCostUsd could end at several times it). A sub-agent stopped this way reports the limit to the lead. A spend limit stays a hard stop with no forced output answer; the finished tool results stay in result.messages (Budgets).
  • Behavior change: POST /chat to a session paused on an approval is a 409 JSON body (LOUSHO_SESSION_AWAITING_APPROVAL, with approvalId and approvalIds) instead of a 200 stream ending in a generic error.
  • A decision on an approval whose winning decision is still streaming is a 409 (LOUSHO_APPROVAL_CONFLICT), as docs/auth.md says, instead of a 404.
  • The session routes’ 400 bodies carry a code: LOUSHO_REQUEST_INVALID (invalid JSON, missing or empty fields), LOUSHO_APPROVAL_DECISION_INVALID (an approval body with neither approved nor answer), LOUSHO_SESSION_ID_INVALID.
  • lousho chat prints a failed turn with its error code, the provider’s failure category and HTTP status, and the fix (error: User not found. (auth-failure, HTTP 401) then [LOUSHO_PROVIDER_REQUEST_FAILED] ...), as docs/cli.md says, instead of the bare provider message. The terminal chat of a project scaffolded by lousho init / create-lousho-agent does the same.
  • A .env saved with a UTF-8 byte order mark (PowerShell 5.1’s Set-Content -Encoding utf8) no longer loses its first variable: the lousho commands and the scaffolded src/index.ts drop the mark before parsing. Variables already set in the environment still win.
  • lousho doctor src/agent.ts loads a .ts/.js agent module the way lousho dev does instead of failing with LOUSHO_SPEC_UNSUPPORTED_FORMAT, and a missing key for the module’s provider is a failure. A scaffolded project’s npm run doctor now runs lousho doctor src/agent.ts, so it fails when the agent’s key is missing.
  • lousho doctor --ping checks OpenRouter at /api/v1/key, which needs the key (its /models answers without one, so a wrong key passed); a key the provider rejects is now a failure, and a ping of a custom OPENAI_BASE_URL says it shows reachability only.
  • lousho doctor fix lines use PowerShell syntax ($env:NAME="<your key>") on Windows.
  • The lousho eval table shows the scores of passing scored gates (such as t.check('words', n, atLeast(3))), not only in --json.
  • Behavior change. An agent with output and tools no longer sends the strict responseFormat schema on calls that offer tools: openai/gpt-4o-mini via OpenRouter then called tools on every step until maxSteps and never answered. responseFormat now goes only on calls without tools (an agent without tools, the “answer now” call at maxSteps, the repair step); tool-offering calls answer from the schema in the prompt, with the existing parse and repair. output: { schema, responseFormat: 'always' } restores the old behavior, and is the default with promptSchema: false. object.delta events still stream on every step of an output run. See Structured output.
  • An agent directory built with lousho build --target=node-server (or docker) can now change who may decide an approval and who may use a session: auth.ts may export functions named authorizeApproval and authorizeSession next to its default auth list, resolveAgentDir() returns them, and the built server applies them. Before, the built server always used the defaults, so a manager could not approve another user’s paused call while that user could approve their own. See Who may decide an approval.

Documentation

  • Tool idempotency: toolCallId and ctx.approval.id identify one call; after a crash the model may retry with a new call, so side effects that must happen once need a key from your own data. New guidance for ending a run after a rejected approval, and for extract-then-approve-then-act with structured output.
  • Durable execution: agent.resume() resolves with a result, not a stream (stream a resumed run with agent.stream([], { sessionId })), and agent.pending() also lists runs still active in another process. Installation: TypeScript 6+ projects need "types": ["node"] for the SDK’s declarations.

[1.0.0-alpha.24] - 2026-10-17

Two fixes on top of 1.0.0-alpha.23, published from the release branch.

Added

  • model-unloaded provider error category: “model is not loaded/unloaded” replies from a local server (LM Studio, Ollama) classify as retryable, so withRetry() rides out the server evicting or still loading a model.
  • A run ended by maxSteps or a budget without a final answer now returns explanatory text instead of an empty string.

Changed

  • MCP: a warning is logged when a server’s tool schemas exceed about 16K tokens (deferred tools excluded). A server marked optional: true connects in the background, so a slow or failing optional server no longer blocks the first send().

Fixed

  • Compaction: when the provider rejects a request for context size and the configured contextWindow is larger than the model’s real one, the error is marked on the transcript and folded into it for a retry when a compaction hook exists; the hook compacts under the server’s observed window (or the rejected request size when unnamed) for the rest of the run.
  • toolCalls of a run continued from a transcript (approval resolve, resume) are collected from its messages, so they no longer disappear from the result.
  • recall_<slot> with a query that matches nothing now says the slot is not empty, instead of returning a bare [] that contradicted the injected <memory> block.
  • The guardrail starter set’s ignore-instructions signal also catches “ignore these/those/her/his/their/our instructions” and “ignore your instructions”, without a qualifier such as “previous”.

[1.0.0-alpha.23] - 2026-10-16

The same tree as 1.0.0-alpha.21; no code changes. create-lousho-agent 0.1.2-alpha.7.

[1.0.0-alpha.22]

Never published to npm (the registry goes from 1.0.0-alpha.21 to 1.0.0-alpha.23); no changes.

[1.0.0-alpha.21] - 2026-10-16

Everything merged to main after 1.0.0-alpha.20. create-lousho-agent 0.1.2-alpha.6.

Breaking

  • Removed the deprecated trigger adapters and their types from @lousho/build-ai-agent/triggers. TriggerAdapter, TriggerRegistry, the WebhookAuth helpers, verifySlackSignature() and parseCronExpression() stay. Migration (see Migrating from triggers):
    • WebhookTriggerAdapter, WebhookTriggerAdapterOptions, WebhookTriggerHandle -> webhookChannel() with mountChannels() (same auth option)
    • SlackTriggerAdapter, SlackTriggerAdapterOptions -> slackChannel() with mountChannels()
    • CronTriggerAdapter, CronTriggerAdapterOptions, CronIntervalOptions, CronExpressionOptions -> defineSchedule() with startSchedules() (no intervalMs: use a cron expression such as */5 * * * *)

Added

  • agent.recover({ intervalMs?, signal?, onError?, onRecovered? }) finishes interrupted durable runs in the background: it polls agent.pending() and resumes each 'in-progress' run once its crashed holder’s run lease is free, leaving approval and question pauses (and non-retryable failures) alone; returns { done, stop() } (Durable execution).
  • An agent directory’s config accepts retry (agent.json: maxRetries, timeoutMs, backoff, …) and, in an agent.ts code config, output (a Standard Schema), so lousho dev/chat/build ./agent keep structured output and per-attempt timeouts. loadAgentDir(dir, { output }) now returns SimpleAgent<Infer<output>>, so result.object is typed.
  • result.toolErrors counts a run’s tool calls that ended in an error result, so an answer the model gave after its tools failed (finishReason: 'stop') is no longer indistinguishable from a good one; limits.maxToolErrors stops the run ('budget-exceeded', budget.limit: 'maxToolErrors') once that many failed. See Failed calls in the result.
  • An error a run rejects with carries what the run spent as error.usage (also on PropagatingToolError and your own errors). A sub-agent’s spend is saved on its lead’s checkpoint as it runs, so a lead resumed after a crash mid-sub-agent counts the interrupted sub-agent’s model calls.
  • A send(msg, { sessionId }) or agent.resume() run that rejects records lastError and attempts on its checkpoint, and agent.pending() lists them (attempts is new for session turns too), so a restart loop can tell a failing run from a crashed one.
  • Docs: a webhook-redelivery recipe (run a job once by checking the checkpoint before send()), a note on structured-output schemas that mirror a side-effect tool, and the fetch option for proxies and fault injection on every provider class.

Changed

  • Behavior change: the fallback default model for the OpenAI, OpenRouter and Pi providers (what lousho init scaffolds and what runs when no model is configured) is now gpt-4.1-mini instead of gpt-4o-mini; set model or LOUSHO_MODEL to keep the old one. README and Quick Start use it. Added docs/comparison.md; CI also runs on pushes to main; README no longer claims unverifiable live validation.
  • createAgent({ prompt }) is deprecated: instructions is the one documented name (prompt still works as an alias, marked @deprecated). Docs, README and examples now use instructions, and npm run docs:verify-snippets fails a docs snippet that passes prompt to createAgent.
  • The published package no longer ships source maps (dist/**/*.map, ~3.7 MB; tsup no longer emits them). The tarball goes from 965 files / 18.9 MB unpacked / 5.0 MB packed to 774 files / 15.1 MB / 4.3 MB. src/ still ships because lousho build bundles the SDK from it. npm run size-check now guards the tarball size and a hello-world bundle against scripts/size-budget.json.
  • docs/comparison.md is now a dated (October 2026) per-competitor table covering the AI SDK 7, Mastra, LangGraph.js, OpenAI Agents SDK, Claude Agent SDK, eve, VoltAgent and open-harness, and the README’s differentiator list keeps only claims still true against them.

Fixed

  • Behavior change: a session without a checkpointStore that pauses on an approval now keeps an in-process pause marker, so a second send() / stream() / compact() on it throws SessionAwaitingApprovalError (LOUSHO_SESSION_AWAITING_APPROVAL) — before, the new turn ran over the truncated transcript and the later approvals.resolve() silently overwrote the committed turn. The marker covers send, stream, compact, clear, pending and discardPending, and is dropped when the turn resolves, aborts, fails or is discarded. Across processes there is still no durable marker: a session that may pause needs a checkpointStore.
  • Session turn checkpoints no longer reuse a <id>.turn-<n> id after compact() shortened the transcript: the n now comes from a persisted high-water mark (<id>.turn-counter), so fork() can no longer resolve a stale checkpoint of a different turn, and prune() keeps the counter while its session’s paused run needs it.
  • Memory: two parallel remember_<slot> calls with an itemKey no longer store duplicate items — the check-and-replace is serialized per memory key. A remembered item is capped at 20,000 characters and the injected <memory> block at 20,000 (each line 4,000), so one item can no longer outgrow the context window of every later run.
  • lousho add <kit> --dir <new-dir> no longer creates the target directory before the install is decided: a non-interactive refusal, a manifest refusal or a ‘no’ at the prompt now truly leaves “nothing was written” — before, an empty directory stayed behind.
  • A malformed or truncated provider response before any output (the AI SDK JSONParseError/TypeValidationError on a garbage first SSE chunk, or a stream cut by UND_ERR_SOCKET / “terminated” / “other side closed”, also inside a cause) is now retried by withRetry() like other network errors, with a provider.retry event, instead of ending the turn with LOUSHO_PROVIDER_REQUEST_FAILED. Nothing is retried once text or a tool call was emitted.
  • lousho build --target=node-server now lists the provider package in the build’s package.json when the agent module (or a code agent.ts) uses an SDK provider class such as new OpenRouterProvider(...), not only a literal model: '<provider>/...', and warns when it detects no provider. docs/deployment.md no longer tells readers to call the internal createDeployedServer(); it shows a graceful shutdown for a self-served agent.
  • Errors and cost (consumer harness): a session turn that fails outside its run (e.g. LOUSHO_SESSION_BUSY) now sends the error’s stable code on the error event, with the message still sanitized; provider.fallback events carry fromModel / toModel, so two providers of the same name (both OpenRouter) can be told apart; and one step with no known price no longer discards the run’s cost: usage.costUsd keeps the priced steps’ sum and usage.costPartial: true flags it (also on byModel entries, delegated and step.done / run.done usage), and limits.maxCostUsd is enforced on that partial total.
  • grep no longer times out on a cheap pattern over a slow disk: the 10 s budget now counts only the time spent matching, not reading files. The timeout error says whether the pattern is slow or the many files used the budget, and how many files were scanned. New createFsTools({ grepTimeoutMs }).
  • Permissions: a permissions rule naming a tool the agent does not have (a typo such as write_flie, so a deny silently guarded nothing) now logs a [lousho] warning at createAgent() with a “did you mean”, and lousho doctor <agent-dir> reports it as a warning. Wildcards, globs, patterns and agents whose tools may arrive later (MCP, tool search, sub-agents) are only checked for near-miss typos.
  • lousho init / create-lousho-agent template: npm run dev with piped input (printf 'hi\n' | npm run dev) no longer exits before the reply; it streams the reply and exits when the turn is done.
  • lousho eval: the “with soft failures” total (softFailed in the JSON summary) also counts cases that failed a gate or threw; the JUnit report keeps their soft failures as <system-out> notes.
  • Sessions: a checkpointed turn whose first model call fails (a 5xx after retries, an exhausted 429, a malformed response) no longer loses the user’s message. The turn is kept as an in-progress pending turn (new Checkpoint.unstarted), so pending() and the route’s GET show it, and the next send() / resume() runs it again with the message in the transcript once. Over the session routes, that stored turn claims the session for its caller.
  • lousho eval --replay / --record skip a mockModel() provider: a scripted mock needs no network, so a mock eval no longer fails with no cassette ... [LOUSHO_CASSETTE_INVALID].
  • limits.maxCostUsd no longer logs “cost limit is not enforced” on runs that use mockModel(), which has no price.
  • lousho doctor lists optional packages the agent does not use as one info line instead of a warning each.
  • Docs: fileMemory({ dir }) in an agent directory’s memory/*.ts resolves against the working directory (anchor it to the module); lousho mcp takes an agent directory; running create-lousho-agent from a local tarball; lousho dev/chat cannot pass run metadata.
  • Flows: a durable run (checkpointStore and runId) holds a run lease, like an agent run: a concurrent FlowExecutor.execute() or resume() of the same runId (in this process, another process or through another store object) is refused with LOUSHO_SESSION_BUSY and runs nothing, instead of running the remaining steps twice. A lease left by a crashed process expires, so the run can still be resumed. See Durable runs.
  • Flows: a toolCall argument that is exactly '{{name}}' or '$name' passes the variable’s value (a number, an object) instead of its text, so { n: '{{n}}' } works with a z.number() tool. Mixed strings are still interpolated as text. See Argument values.
  • Flows: a step node (StepNode) fails with a message naming the supported way to run a createAgent() agent in a flow (a tool that calls agent.send()). See Running an agent in a flow.
  • Sub-agents: a sub-agent’s own memory works when the lead’s task tool runs it (recall in its system prompt, its remember_<name> / recall_<name> tools), scoped by the lead run’s sessionId, metadata and principal; before, its slots were silently ignored there. New subagentOptions: { continuation: false } leaves taskId and mode out of the task tool, and the error for another sub-agent’s taskId tells the model to omit it for a new task. See Sub-agents.

Security

  • Behavior change: the file tools from createFsTools() (read_file, list_dir, glob, grep, write_file, edit_file) refuse any path with a .git segment (.git/config, ./.git, a/../.git, .GIT, a worktree’s .git file; on Windows also 8.3 names such as GIT~1) with a WorkspaceError, and glob, grep and list_dir leave .git out of their results. .git/config can hold a CI checkout token (http.<url>.extraheader) and a worktree’s .git names a host path. The new deny option sets the names (default ['.git']; [] turns it off). The shell tool is not path-filtered. See Security model.
  • lousho build <dir> --target=node-server|docker no longer copies an agent directory’s .env files or its .lousho/ session store (real user transcripts) into dist/ and the Docker image. Only the files the server reads are copied: instructions.md, instructions/, skills/ and a JSON/YAML config, in the directory and each sub-agent; .env*, .lousho, a JSON/YAML config’s store.dir, .git and node_modules are skipped at any depth. dist/ is emptied before each build so sessions a previous build’s server wrote there are not resurrected, and the generated .dockerignore also lists **/.env, **/.env.* and **/.lousho. Rebuild and redeploy images built from an agent directory with an earlier version. See Deployment.
  • createRouteHandler()’s UI stream (POST <base>/ui) and framework hook route (POST <base>) now enforce the documented 1 MB body cap (413) like POST /chat does; they previously buffered the full body via request.json().
  • A channel approval decision now binds to the session recorded in the approval’s own durable snapshot, not the sessionKey the caller sends, so a request carrying a foreign session key can no longer resolve another conversation’s pending approval.
  • POST /chat/:sessionId/approvals/:id checks the approval’s kind after authorization: answer only decides question approvals and approved/note only tool approvals; a mismatched body is 400 LOUSHO_APPROVAL_KIND_MISMATCH instead of silently approving a tool.
  • POST /chat message arrays may carry role: 'user' only; client-supplied system, assistant and tool messages are dropped before the turn (content-part arrays without roles are unaffected).
  • Behavior change: crossSiteRequest no longer trusts X-Forwarded-Host or Forwarded: host= as same-site evidence — those headers are client-controllable. A request is same-site when its Origin matches the server’s actual Host (or an allowedOrigins entry); behind a trusted proxy, set allowedOrigins to the public origin.
  • Session-owner bookkeeping adds a per-principal cap (1024 claimed sessions per caller) under the global 100,000 LRU, so one caller flooding new session ids can no longer evict everyone else’s ownership claims.
  • webhookChannel() only defines verify when an auth option is configured; an unauthenticated webhook is treated as an open channel and its cross-site requests are refused like httpChannel()’s. The deprecated WebhookTriggerAdapter treats a missing verify as success.
  • Malformed percent-encoding in route parameters (%zz, truncated UTF-8) answers 400 instead of a URIError 500 on /chat/:sessionId/... and channel approval routes.

[1.0.0-alpha.20] - 2026-10-16

create-lousho-agent 0.1.2-alpha.5.

Security

  • Behavior change: with route auth and no authorizeSession, a session belongs to the first principal that sends it a turn (reading claims nothing); any other principal gets 403 LOUSHO_SESSION_FORBIDDEN. Owners are kept in memory per agent for the 100,000 most recently used sessions, so a stored session whose owner is not on record (after a restart, on another replica, past the cap) is refused to everyone: pass authorizeSession for multi-instance deployments and durable stores, or authorizeSession: () => true for the old behavior. A route behind one bearer token has a single caller and checks no owner. POST /chat with an empty input (and POST <base>/ui without a user message) is a 400 that claims nothing, and a turn that stores nothing drops its claim, so an owner can no longer be evicted by flooding. See Who may use a session.
  • Behavior change: POST /chat/:sessionId/approvals/:id answers 404 unless the approval belongs to that session, and by default only the caller the paused run acts for may decide it; allow others (a supervisor) with authorizeApproval.
  • Behavior change: the session routes (createRouteHandler(), createDeployedServer(), the Worker, lousho dev) refuse cross-site requests: a POST whose Origin is neither the server’s own (Host, X-Forwarded-Host or Forwarded: host=) nor in the new allowedOrigins, or that the browser marked Sec-Fetch-Site: cross-site, is 403 LOUSHO_REQUEST_FORBIDDEN, and a POST body must be Content-Type: application/json (415 LOUSHO_UNSUPPORTED_MEDIA_TYPE). Requests without Origin are unaffected. Opt out with allowedOrigins: ['*'] and requireJsonBody: false; allowedHosts refuses unlisted Host headers. Built servers read LOUSHO_ALLOWED_ORIGINS, LOUSHO_ALLOWED_HOSTS and LOUSHO_REQUIRE_JSON_BODY=false. The React/Vue/Svelte bindings no longer send Content-Type twice and accept a Headers instance. See Cross-site requests.
  • Behavior change: lousho dev answers 403 to a non-loopback Host (off loopback: an IP address or the --host name; new --allowed-hosts a,b), so a web page cannot reach it through DNS rebinding, and warns when bound off loopback. A channel without verify refuses a cross-site browser request (403), and httpChannel() without verify requires a JSON body (415).
  • Behavior change: the Cloudflare Worker refuses every /chat route (403 LOUSHO_REQUEST_FORBIDDEN) when no LOUSHO_API_TOKEN secret is set; set the var LOUSHO_ALLOW_OPEN_SESSIONS (or the earlier LOUSHO_ALLOW_OPEN_TRANSCRIPTS) to "true" to allow it. /health, the OAuth callback and channels stay open, and lousho build --target=cloudflare-worker warns about the secret.
  • Behavior change: WebhookTriggerAdapter binds 127.0.0.1 by default (was 0.0.0.0), refuses a non-loopback host without auth unless allowUnauthenticated: true (LOUSHO_TRIGGER_INVALID), refuses a foreign Host or an Origin on loopback without auth, caps bodies at 1 MB (413) before auth, and no longer echoes handler errors. See Webhook.
  • Behavior change: MCP tools ask for approval by default (approval: 'always'); a server’s readOnlyHint / destructiveHint count only with approval: 'annotations'. An MCP tool named like a local tool is refused with LOUSHO_CONFIG_INVALID instead of replacing it. See MCP.
  • Flows: a toolCall step passes the same gate as an agent’s tool call (permissions, permissionMode, onPermissionDecision and a new approve option on FlowExecutionContext); a call that needs approval and is not approved fails with LOUSHO_FLOW_TOOL_DENIED without running. Step arguments are validated against the tool’s schema (LOUSHO_TOOL_ARGS_INVALID) and a flow’s declared inputs are enforced (LOUSHO_VALIDATION_FAILED). See Flows.
  • Registry: the approval an install receipt requires for an exec, needsApproval or unattested item can no longer be waived from inside the agent directory (an allow rule, acceptEdits or the directory’s own approve file); only a person or an approve passed in code decides it. Receipts now also cover a kit’s subagents/<name>/ tools. coding-kit / coding-pi refuse writes to their own config, tools and .git/, drop git diff from the shell allowlist and accept node --test only with test file paths (reinstall with lousho add coding-kit --overwrite). See Registry.
  • Shell tool: an allow string pattern refuses arguments that escape the workspace (.. segments, also in --flag=../x, ~, absolute paths, quoted or escaped forms such as cat "../x", globs that can expand to .., and $, {, }), and under cmd.exe % and ^ count as shell operators. Use a CommandRule or an anchored RegExp to allow such arguments.
  • Agent Forge (lousho studio) no longer answers any origin: it sends no CORS headers, refuses a foreign Origin or a non-loopback Host, and every API and WebSocket call needs the per-launch token printed in its URL. See Agent Forge.
  • Tracing: redactContent defaults to true, so prompts, instructions and tool output are no longer written to span attributes or .lousho/traces unless you pass redactContent: false (or captureContent: true for gen_ai.* content).
  • The session routes no longer send raw error text to clients: error events, 500s and provider.retry / provider.fallback events carry the error’s name and code with a generic message, and the full error is logged. Pass exposeErrors: true for the old behavior (lousho dev does). Channel 500s no longer echo internal errors either.
  • fromUIMessages() (and POST <base>/ui) keeps only user and assistant messages from the client; a client-sent system message is dropped.
  • OAuth: a principal without an issuer gets tokens namespaced by its authenticator, so the same id from Slack and GitHub no longer shares a token (docs/oauth.md has the one-time move); telegramChannel and teamsChannel send a sign-in link only in a 1:1 chat; the [REDACTED] net for ctx.getToken() tokens also covers thrown errors, object keys, URLs, class instances and base64 forms of the token.
  • serveMcp over HTTP validates Host and Origin against DNS rebinding (new allowedHosts / allowedOrigins), and loopback checks there and in WebhookTriggerAdapter accept exactly localhost, 127.x.x.x and ::1 (127.attacker.example passed).
  • The openrouter provider without apiKey reads OPENROUTER_API_KEY and no longer sends OPENAI_API_KEY to openrouter.ai.
  • Slack and Discord signatures accept a timestamp at most a minute ahead (was five minutes either way), read in seconds; discordChannel refuses timestamps more than five minutes old. githubChannel({ deliveries }) takes a shared DeliveryStore for X-GitHub-Delivery replay protection.
  • The @modelcontextprotocol/sdk peer range is ^1.31.0 (was ^1.30.1): 1.30.x is affected by GHSA-6qxp-vccf-f47h, which MCP OAuth relies on.
  • SubprocessSandbox: writeFile() stays under the new root option (LOUSHO_SANDBOX_PATH_DENIED, also through symlinks), and containers run as 1000:1000 with all capabilities dropped, no-new-privileges and default limits (512 MiB, 256 pids, 1 CPU); pass user: 'root' for the old user. See Guardrails.

Changed

  • Behavior change: session turns keep the checkpoint history of the latest 10 committed turns (agent.session({ id, turnHistoryLimit }); 0 keeps none); storage used to grow with the square of the conversation. Excess history already in a store is deleted over the next commits, also when each turn uses a new process or store object. New fileStore(dir).prune({ olderThanMs }) returns checkpointHistory too; fileStore() returns the new FileStore type.
  • Behavior change: a checkpointed run holds a run lease while it executes (new optional CheckpointStore.acquireLease(), releaseLease(), renewLease(), saveIfLeased(); file, SQLite, memory and best-effort KV stores). A second process, replica or store object that sends to the same session, resumes it or resolves its approval gets LOUSHO_SESSION_BUSY instead of running its tool calls again, and a stalled holder can no longer overwrite the run that took over. A dead holder on the same host is taken over at once; on another machine 30-60 s after its last heartbeat. Schedule fires are claimed the same way, so replicas fire a tick once. See Run leases.
  • Behavior change: approvals run at most once: deciding one re-saves the turn as 'in-progress' with the call in Checkpoint.startedToolCallIds, and resuming after a crash mid-call gives it a kind: 'interrupted' tool error instead of running it again. Resolving an approval whose run was deleted or replaced fails with LOUSHO_APPROVAL_ORPHANED and withdraws it.
  • Behavior change: a session turn paused for approval locks the session id: a new turn on it throws SessionAwaitingApprovalError (LOUSHO_SESSION_AWAITING_APPROVAL) until the approval is decided or discardPending() drops the turn.
  • Behavior change: a deterministic provider error records lastError on the turn’s checkpoint, and later calls on that session fail fast with LOUSHO_SESSION_TURN_FAILED instead of replaying the failing turn; resume() retries it.
  • Behavior change: run ids (send({ sessionId }), a fork’s newSessionId) are 1-200 characters of A-Za-z0-9_.- on every store and may not end in .turn-<n>, .paused or .fire; '' is refused. Session ids (agent.session({ id }), the routes) stay 1-128 characters of A-Za-z0-9_-. The error messages now say which of the two rules applies.
  • Behavior change: with a store, tools, needsApproval, permission rules and hooks get the session id as ctx.sessionId, not the checkpoint key <id>.turn-<n> (new ExecuteOptions.contextSessionId).
  • Behavior change: a model step with several calls that need approval pauses once, on all of them (result.approvalIds, agent.approvals.resolveAll()); calls that need no approval run before the pause. See Several calls in one step.
  • Behavior change: once() no longer remembers a yes from a createAgent({ approve }) callback, and 'defer' is reserved: an approval note that is exactly 'defer' defers.
  • Behavior change: approvalTtlMs and an ask rule’s ttlMs above 100 years throw LOUSHO_CONFIG_INVALID (they meant “never expires”).
  • Behavior change: memory items are keyed <slot name>#<scope key>, so two slots on one scope no longer share items. Run migrateMemoryKeys(slot) once to copy items stored under the old bare key. See Memory.
  • Behavior change: a prompt schedule runs every fire in its own session schedule-<name>-<fire time> (defineSchedule({ sharedSession: true }) keeps one shared session), and a fire that does not finish 'stop' reports the new LOUSHO_SCHEDULE_RUN_INCOMPLETE.
  • Behavior change: channels without a store keep transcripts in the agent’s createAgent({ store }) when it has sessions.
  • Behavior change: the routes let a session turn run to its end and save it when the client disconnects (onDisconnect: 'abort' for the old behavior; waitUntil keeps a serverless function alive). An aborted turn keeps the user’s input, the tool calls that ran and the partial reply (metadata: { interrupted: true }), and its usage counts.
  • Behavior change: tool results are capped at maxToolResultChars (default 50_000, Infinity for none) for every tool; MCP image/audio/blob data reaches the model as a placeholder and MCP tool descriptions are cut at 2,000 characters.
  • Behavior change: a user file part the provider cannot send rejects the call with LOUSHO_UNSUPPORTED_CONTENT (under fallback the next provider gets it) instead of a text note; unsupportedFiles: 'text-note' keeps the note. See Multimodal input.
  • Behavior change: createAgent({ provider }) with a built-in or fromAiSdk() provider and no retry wraps it in withRetry() (provider’s maxRetries, default 2), and withRetry() is the only retry layer: the built-in providers turn the ai SDK’s own retries off (retry: false used to send 3 requests, maxRetries: 3 sent 12).
  • Behavior change: a rate-limited call has the code LOUSHO_PROVIDER_RATE_LIMITED, and an out-of-credit account (insufficient_quota, 402) is the new non-retryable category quota-exceeded.
  • Behavior change: OpenAIProvider sends store: false on the Responses API unless store: true is set.
  • Behavior change (types): LLMProviderConfig has no index signature, so a misspelled option is a type error; LLMProviderRegistry.register() / create() take the provider’s own config type (new BuiltinProviderConfigs). ExecutionFinishReason is a closed union, and an unknown provider finish reason is reported as 'other'.
  • Behavior change: agent.stream() rethrows the run’s error after the error and run.done events ({ throwOnError: false } for the old behavior).
  • Behavior change (CLI): every usage error exits 2 and 1 means a command ran and failed. lousho eval, build, dev, chat, acp, mcp and doctor load ./.env. The fallback registry URL points at the installed version’s release tag.
  • Behavior change: connectMcp() rethrows a server’s start failure as McpStartError (LOUSHO_MCP_START_FAILED, with exit code and the last stderr lines) instead of wrapping it.
  • Evals: t.maxCostUsd(n) fails when a run reports no cost ({ unknownCost: 'skip' } for the old, now warning, behavior); judge.model and llmJudge() / llmCritique()’s model are optional.
  • Pruned tool results leave a stub naming the call and its arguments ([pruned: search({"query":"deploy"}) result, 18234 chars; already read]).
  • Agent Forge: a run on a real provider without an API key fails with LOUSHO_PROVIDER_MISSING_API_KEY (HTTP 422) instead of silently using the mock provider, and the provider pill shows what actually ran.
  • The examples import @lousho/build-ai-agent and its public subpaths instead of the repository’s src/, so they can be copied into an app as they are.
  • The package.json that lousho build --target=node-server|docker writes lists only the optional peers the bundled server loads (the provider package, @modelcontextprotocol/sdk with mcpServers), no longer @lousho/build-ai-agent: dist/server.js bundles the SDK, ai and zod, so the image’s install is smaller.
  • The npm package no longer ships the CommonJS build of the CLI (dist/cli/*.js and maps) or the CLI’s type declarations: bin/lousho.js loads only dist/cli/*.mjs.

Added

  • Providers: a timeout option (default 10 minutes until the response starts and between chunks; 0 or Infinity turns it off) and a fetch option on every built-in provider. OpenAIProvider({ api: 'chat' }) and LOUSHO_OPENAI_API=chat use Chat Completions for OpenAI-compatible servers (LM Studio, Ollama, vLLM, llama.cpp; the built-in hosted tools are then refused with LOUSHO_HOSTED_TOOL_UNSUPPORTED); see Local and OpenAI-compatible servers. withRateLimit() / createRateLimiter() and createAgent({ rateLimit }) queue model calls client-side. promptCaching: 'auto' (the default) marks Anthropic cache breakpoints for Claude on anthropic and openrouter. withRetry({ idleTimeoutMs }) fails a stream that stalls between chunks (timeoutMs now bounds only the wait for the first chunk). withFallback() results carry servedBy.
  • Model settings: createAgent({ modelSettings }) and per-call modelSettings (maxTokens, temperature, topP, penalties, stop, seed, toolChoice), range-checked up front, also in agent.json. Per-call maxSteps and instructions on send() / stream(). See Configuration.
  • Cost: built-in prices for more default models (Ollama llama3 window, OpenRouter variants), cache read/write prices (cachedInputCostPerMTok, cacheWriteCostPerMTok, cacheWriteTokens) and OpenRouter’s reported usage.cost for costUsd and limits.maxCostUsd.
  • Approvals: remember: 'session' and edited args on a decision, 'defer' from an approve callback, approvalTtlMs / ttlMs deadlines (expiresAt on events and UI state), agent.approvals.list() across processes (new optional ApprovalStore.list()), agent.pending() for unfinished runs (new optional CheckpointStore.list()), and resumedAfterApproval on tool-call hook contexts. See Approvals and Recovering after a crash.
  • Routes: authorizeSession and authorizeApproval on createRouteHandler() / createDeployedServer(); approvals report their sessionId and error events their code. Built node and Docker servers drain on SIGTERM (shutdown({ timeoutMs }), LOUSHO_SHUTDOWN_TIMEOUT_MS). Channel routes decide each call of a multi-call pause and accept a sessionKey after a restart.
  • Flows: durable runs (checkpointStore + runId, FlowExecutor.resume()), pausing for approval (status: 'awaiting-approval'), per-node retry and timeoutMs, cancellation through signal, and usage on the result. See Flows.
  • Structured output: partial-object streaming (object.delta, partialObject in the UI bindings), result.outputRepaired, { schema, promptSchema: false }, a forced no-tools answer when maxSteps or limits.maxSteps runs out, and outputError.kind: 'truncated'. Unions, records, tuples and optional fields now work on strict endpoints. See Structured output.
  • Memory: expose: { forget: true }, itemSchema / itemKey upserts (new optional MemoryProvider.upsert()), memoryKey(), de-duplicated add(), and migrateMemoryKeys(). See Memory.
  • MCP: optional: true, cwd, stderr, connectTimeoutMs, timeoutMs, tools: { include, exclude }, per-call approval({ args }), onToolsChanged and McpConnections.reconnect(). See MCP.
  • Observability: invoke_agent spans carry the request model and token totals (agentUsageTotals: false leaves them off), legacyAttributes: false, parentSpanId on send() / stream(), retry attributes on chat spans, sub-agent names on their spans, and compaction calls as counted chat spans. See Observability.
  • Tools and sub-agents: defineTool({ timeoutMs }), subagentOptions: { background: false }, read_skill_file for skill folders, ToolDescriptor.transient, CommandRule objects for the shell tool’s allow / deny, and an optional ShellProvider.shell that tells the model which shell runs its commands.
  • Compaction: reserveOutputTokens and onCompaction on the object form; GenerateHookContext.generate() for counted side calls.
  • Evals: sub-agent tool calls in trajectory evals, SendOptions.onEvent, repeat / passAt, { agent } for setProviderInterceptor callbacks, lousho eval --timeout and defineEval({ timeoutMs }), and recordReplay({ rerecordHint }). See Evals.
  • Channels and schedules: githubChannel({ pullRequestOpened: true }), webhookChannel({ principal }), exported fireSchedule(), startSchedules({ keepAlive: true }) and an awaitable stop(), and mountFetchChannels({ waitUntil }).
  • CLI: lousho doctor --ping and base URLs in its output, and lousho --version.
  • lousho build --target=node-server|docker builds a .ts/.js agent module (the file lousho dev src/agent.ts serves: a default or agent export holding createAgent() options or a built agent). The cloudflare-worker target says it builds only a spec or an agent directory. The minimal and tools scaffolds export their options as src/agent.ts’s default export, so lousho dev|chat|mcp|acp|build src/agent.ts work on a new project, and every scaffold has a build script (and tsup); the minimal and tools ones also have dev:ui (lousho dev src/agent.ts).
  • The Docker image lousho build --target=docker writes has a HEALTHCHECK on GET /health, and its .dockerignore keeps .env, .env.* and *.tgz out of the image.
  • lousho add, studio, eval and traces --help describe every flag; lousho help <command> prints that command’s help.

Fixed

  • Durability: concurrent commits on one session no longer lose a turn (new optional SessionStore.saveIf() compare-and-swap; KVStore stays best effort), and session objects re-read the store instead of caching the transcript. Concurrent send({ sessionId }) calls in one process run in order. Parallel tool calls are checkpointed as each settles, so a crash no longer re-runs finished calls. A restarted process that resolves a session’s approval commits the turn instead of dropping it. session.clear() deletes every turn’s checkpoints and history, finished turns stay forkable, session.fork() works for 122-128 character ids, and sub-agent task ids are never reused.
  • Stores: fileStore file names are case-safe on Windows and macOS (Alice and alice no longer share a file), long ids and device names are hashed, older long names are still read, writes are fsynced and Windows EPERM / EBUSY is retried. A corrupt checkpoint fails with LOUSHO_CHECKPOINT_CORRUPT and can be discarded. SqliteStore waits 50 ms instead of freezing the event loop, retries locked writes without blocking (LOUSHO_STORAGE_BUSY) and prune() keeps paused turns. KVStore approval claims run a tool once in the common case (ctx.approval.id serves as an idempotency key). Image and file bytes survive every store. Taking over a stale file lock is serialized, and KVCheckpointStore.list() throws without a list binding instead of returning []. agent.approvals.get() returns undefined for an id that cannot name an approval. fileMemory and sqliteMemory keep every item with several writers.
  • OAuth: concurrent ctx.getToken() calls share one refresh, and a refused refresh no longer deletes a newer token.
  • Approvals and memory: a run resumed after an approval or a crash keeps its memory tools and the scope it paused with; memory stays on after a handoff; recall errors skip the slot with a warning; invalid scopes fail with LOUSHO_MEMORY_INVALID; keyword recall matches whole words; <memory tags in item text are escaped; recall_<name> returns scores and metadata.
  • Providers on ai 4, 6 and 7: tool errors are no longer wrapped twice on ai 7, malformed or truncated tool-call JSON reaches the model as a repairable LOUSHO_TOOL_ARGS_INVALID error (light repairs are tried first; tool.start has rawArgs), prefixed tool names (functions.read_file) resolve, unknown tools suggest the closest name, duplicate tool-call ids both run, a completion sent to a streaming request is replayed, mid-stream and finish_reason: "error" failures become retryable 502s, a stream that fails before any output is retried, and unset temperature / maxTokens are left out. withFallback() keeps its state per call, so concurrent calls no longer misreport fallbacks or book cost under the wrong model, and withRateLimit() over withRetry() streams reports the final attempt and holds its slot until the retried stream ends.
  • Provider errors: local runtimes’ context overflows are context-length-exceeded, refused connections name the URL, status and message are read together, nested OpenRouter reasons are shown, a long Retry-After fails at once instead of sleeping, negative hints are ignored, and compacted errors keep their category through createAgent(). A missing provider package fails with LOUSHO_PEER_MISSING, and the routes send its npm install command to the client.
  • Provider features: reasoning reaches more models and warns once when it is dropped; image MIME types are sniffed; OpenRouterProvider honours baseURL and OllamaProvider sends headers and apiKey; supportsTools() knows current models; registered providers work in model strings; retired fallback models are replaced; price lookup handles OpenRouter spellings; the forced answer at maxSteps works on Claude.
  • Runs: abort no longer waits on a provider or tool that ignores the signal (finishReason: 'aborted', result.abortReason; mockModel honours signal), aborted streams keep their text, a throwing event listener or trace exporter no longer fails the run, tool results with cycles, BigInts, Maps or Sets serialize, send(result.messages) does not repeat the system prompt, send([]) throws LOUSHO_CONFIG_INVALID, a finish_reason: tool_calls reply without calls ends 'stop', a load_skill tool that clashes with skills throws, maxSteps must be a whole number >= 1, and handoffs work on local models and Anthropic (no mid-conversation system message).
  • Structured output: the repair and forced-answer prompts stay out of transcripts, near-miss replies (prose, <think> blocks, fenced JSON) are accepted without a repair call, a reply that repeats the schema gets a clearer repair message, and unsupported root unions or zod 4 z.date() fields throw a ConfigurationError naming the fix. defineTool() rejects inputs no model can satisfy and accepts z.preprocess dates on zod 4.1+.
  • Compaction: summarizing splits oversized histories, counts tool definitions and the output schema, warns when it falls back to a 128,000-token window for an unknown model, caps protectedTokens at half the threshold, retries the summarizer after a rejection, counts its call in usage and budgets, and reports appliedStrategy.
  • Sub-agents and handoffs: dynamic sub-agent config functions get the lead’s sessionId, metadata and principal; a failed sub-agent’s spend counts; truncated answers say so; agent-directory and Worker subagents/ run as native sub-agents; a handoff target’s toolSearch applies.
  • Schedules: a fixed-hour cron job in a spring-forward gap runs once after the gap instead of being skipped.
  • Flows: a failed parallel branch aborts its siblings, forEach variables are per iteration, unnamed steps get unique ids, and resume() refuses a changed flow (LOUSHO_FLOW_CHANGED).
  • MCP: Not connected counts as a dropped connection and reconnects, tools/list follows every page, dropped servers report 'failed' with their stderr, calls honour abort, text-only results are sent once, tool names are made valid for every provider, object schemas with a sibling oneOf keep their shape, agent.ready() reconnects after close(), and serveMcp() over HTTP cancels the run a client cancels or abandons (matched by its new Mcp-Session-Id) and rejects its pending approvals. serveAcp keeps serving after a malformed JSON line.
  • Channels: redelivered webhooks run once (Telegram, GitHub, Slack), concurrent decisions on one approval decide it once (409 LOUSHO_APPROVAL_CONFLICT, also on the routes), webhookChannel authenticates on Fetch hosts and its pause replies carry the prompt, githubChannel ignores /approve for unknown approvals, and channel metadata reaches the run. POST <base>/ui answers 400 for an invalid id, and auth: '' is LOUSHO_AUTH_CONFIG_INVALID on createRouteHandler() and serveFetch().
  • UI bindings (React, Vue, Svelte): remote mode keeps one session across turns, a stream that ends early becomes an error, each step starts a new paragraph, abnormal endings set status: 'error', React gains reset(), server error messages are kept, Svelte no longer aborts on a transient subscribe, formatUsage() shows small costs, and parseEventStream() joins multi-line data: fields.
  • Tracing and OpenTelemetry: open spans are bounded without losing parents, queued background sub-agents stay in the lead’s trace, background sub-agent cost rolls up, and execute_tool spans carry the error message.
  • Evals: replay matches calls by request, sub-agent cassettes are named after the agent, cassette names include a hash of the case label, re-recording unchanged exchanges leaves no diff, tool order no longer breaks replay, reasoning and full usage are recorded, judge scores parse more formats (the last SCORE: wins) and judges see the user’s input at temperature 0, lousho eval gives live cases 10 minutes and its reports are never empty when vitest fails.
  • CLI: lousho dev reloads CommonJS tool files and recreated folders, tool files no longer print MODULE_TYPELESS_PACKAGE_JSON, TypeScript syntax that type stripping cannot erase gets an error suggesting --experimental-transform-types, every agent command loads tools/*.ts of an installed project (one ESM build, shared brands, instanceof across ESM and CJS copies), lousho build reports bundling failures as LOUSHO_DEPLOY_FAILED, warns about missing provider packages, merges an existing wrangler.toml (new default compatibility_date 2026-09-01), no longer needs unused provider packages for a Worker and prints where it wrote, Docker images run as node, lousho doctor and lousho mcp accept agent directories, lousho add checks flags and target directories up front and falls back to GitHub when the default registry is down, lousho init templates and Windows instructions are fixed, init says when the provider’s API key is missing and git-ignores an --sdk-path tarball, and help texts and messages are clearer.
  • Agent directories: every createAgent() override passed to loadAgentDir() is forwarded, mock/<name> models work from every entry point, and import failures throw LOUSHO_AGENT_DIR_INVALID with an install hint. loadSkills() skips a loose README.md.
  • Workspace tools: grep refuses catastrophic regexes and runs with a time budget, edit_file refuses non-UTF-8 files instead of corrupting them, and tool_search ranks synonyms and word families.
  • Agent Forge: agents are read from and written to .lousho/agents/, narrow screens and keyboard and screen-reader use work, invalid names and imports show errors instead of a blank page, finished runs report done, and several drawing and status glitches are fixed.
  • Packaging and types: ESM consumers get .d.mts declarations (plus typesVersions for node10), declarations type-check with skipLibCheck: false on zod 3 and 4, the pi peers are caret ranges, llms-full.txt no longer ships and the Worker entry has no source maps.
  • Docs: corrections throughout (sessions vs runs under one id, schedules, nextjs approvals, memory, engines.node), the snippet check now also runs every snippet that builds its own mock provider and checks fences indented in lists, and the ops-pipeline example works as described.
  • A checkpointed session turn that stalled past its run lease and then failed for good no longer stamps its lastError (retryable: false) on the checkpoint of the process that took the turn over, which bricked that turn forever with LOUSHO_SESSION_TURN_FAILED: the session now holds the turn’s run lease itself (handed to the run as HELD_RUN_LEASE) and recordFailure() writes through RunLease.save, whose fenced save writes nothing once the lease is lost.
  • agent.send(msg, { sessionId }) and a fresh agent.session({ id }) no longer run beside a session turn that waits on an approval when its <id>.paused marker was never written (a crash or a send between the executor’s awaiting-approval checkpoint and markPaused()): pausedSessionTurn now also scans the store’s <id>.turn-* checkpoints for status: 'awaiting-approval' when the marker is absent, on stores that implement list().
  • A streamed tool call whose deltas repeat its id while omitting index (the OpenAI-compatible / Gemini-proxy servers the tool-call id rewrite exists for) stays one call: each repeat no longer mints a call_1_2, call_1_3, … id that split the arguments JSON across phantom calls none of which parses; the call’s slot in the delta’s tool_calls stands in for the missing index.
  • A non-streamed request whose body carries a nested "stream": true (a providerOptions passthrough, tool arguments, gateway metadata) no longer has its JSON reply rewritten into an SSE stream the consumer cannot parse: whether a request asked for streaming is read from the parsed top-level stream field instead of a regex over the raw body.
  • Session routes: two concurrent first-touch turns on one unowned session no longer both pass the owner check - the claim is atomic now, so the loser is refused (403 LOUSHO_SESSION_FORBIDDEN) instead of streaming a turn inside the winner’s session; a claim lost while a turn ran clears what it stored and ends the stream on the same coded error.
  • Approve-with-edits on a sub-agent’s grouped approval validates the edited args against the tool’s schema like a top-level or single sub-agent decision does: before, snapshot.subagent stored decision.args raw, so an invalid edit (e.g. a string where z.number() wants a number) ran the tool with garbage args; it now throws LOUSHO_TOOL_ARGS_INVALID and leaves the approval pending.
  • Aborting a run during a tool call no longer hangs send() / stream() / approvals.resolve() forever on a tool that ignores its abortSignal: the tool batch and the approved-tool wait of resumeAfterApproval() are raced against the run’s signal the way the model call already was, the run ends finishReason: 'aborted' with a ‘cancelled’ result for calls still running past a short grace window (a result that lands within it is still kept), and the tool keeps running in the background.
  • A run that re-pauses on several approvals after a resume persists every pending approval id in its checkpoint: markAwaitingApproval() wrote only approvalId, so durable discovery (pausedApprovalIds, agent.approvals.list()) named 1 of N approvals; it now carries the group’s approvalIds like markGroupPending() does.
  • The inbox-triage registry kit loads under lousho dev, chat, acp, mcp and doctor: its relative imports carry the .ts extension Node’s type stripping needs (only bundlers resolved them). A test now installs every registry kit and loads it in a plain node process, as the CLI does. An extensionless relative import in an agent directory gets a hint naming the specifier to write ('./lib/store.ts'), and on a Node without built-in type stripping (before 22.18) the .ts load error says Node 22.19+ is required.
  • OPENAI_BASE_URL (and ANTHROPIC_BASE_URL) is used with @ai-sdk/openai 1.x (@ai-sdk/anthropic 1.x), the line that pairs with ai 4: the provider passes it when no baseURL is configured. Before, model: 'openai/...' called api.openai.com while lousho doctor --ping reported the custom endpoint.
  • PropagatingToolError, McpToolError and WorkspaceError pass instanceof across the ESM and CJS copies of the SDK, so a .cjs tool’s “do not retry” error stops the run under the ESM lousho CLI instead of being handed to the model (and retried).
  • lousho dev re-evaluates the local helper files an edited tool or agent module imports (the ?t= cache-bust is passed on to relative imports), instead of logging “reloaded” while serving the stale helper; editor temp files no longer show in the “changed:” list.
  • lousho eval: a case that vitest fails after the case finished (it ran past its time limit) is reported as that case failing, not as a pass plus an extra vitest row; a run that records no case at all (a mistyped --tag) exits 1 like a glob that matches nothing.
  • The yarn scaffold’s yarn test works: the templates list vite, vitest’s peer, which yarn 1 does not install. The README’s “Next 3 commands” lists three, and the tools template’s README counts its three tools.
  • CLI messages: a module that exports no agent names the command that loaded it (lousho chat:, not lousho dev:); lousho mcp without a path says a spec, directory or module is accepted, and --port/--host without --http are a usage error instead of ignored; lousho version <arg> and init --sdk-path <missing> exit 2; the unknown-provider error lists mock.

[1.0.0-alpha.19] - 2026-10-08

Everything published from 1.0.0-alpha.15 (2026-10-06) through 1.0.0-alpha.19 (alpha.17 on 2026-10-07, alpha.18 and alpha.19 on 2026-10-08). Most of it was prepared on main under the version number 1.0.0-rc.0, which was never published. Upgrading from an earlier 1.0.0-alpha.* release? Read the upgrade guide: imports moved to subpaths, dead and superseded APIs were removed, and the patch guardrails are now patch checks. What 1.0 considers public is defined there (every exports entry and the checked-in api/ reports).

Breaking

  • Flows, the Jira / GitHub / Slack / email tools, encryption, StorageService and the validators moved out of the package root. Import them from their subpath: FlowBuilder, FlowExecutor, validateFlow and every flow type (AgentFlow, EditorStep, FlowExecutionEvent,…) from @lousho/build-ai-agent/flows; createJiraTools, createGitHubTools, createSlackTool, slackTool, postSlackAlert, createEmailTool and their types from @lousho/build-ai-agent/integrations; EncryptionUtils, DTOEncryptionFilter, DecryptionError, sha256, generatePassword, StorageService, StorageServiceApprovalStore, LocalStorageCheckpointStore and the validators (validateWithSchema, safeValidate, isValidEmail,…) from @lousho/build-ai-agent/utils. The integrations are no longer in @lousho/build-ai-agent/tools and the flow types are no longer in @lousho/build-ai-agent/types. Nothing else changed: the classes and functions are the same. For file-backed stores with createAgent(), prefer fileStore(dir).
  • Removed AgentType, AgentTypeDescriptor, AgentConfig.agentType, AgentBuilder.setType() and the agent-type registry (agentTypesRegistry, getAgentTypeDescriptor, getAllAgentTypeDescriptors, isValidAgentType, validateAgentConfig, validateAgentTools). They had no runtime effect since 1.0.0-alpha: delete the setType(...) call and the agentType field. Also removed, because nothing implemented or used them: the repository interfaces (IRepository, IAgentRepository, ISessionRepository, IResultRepository, SessionData, ResultData, SDKRepositories), DataLoadingStatus, PaginationParams, PaginatedResponse, DeepPartial, Timestamped, IdEntity, AgentExecutionOptions, AgentExecutionResult, AgentDefinition and ToolSetting. If your code used one of these types, copy its declaration into your project. A checkpoint saved with agentType still loads; the field is ignored.
  • Removed ExecuteOptions.onEvent and the ExecutionEvent / ExecutionEventType types, deprecated in an earlier alpha. Pass onAgentEvent to AgentExecutor.execute() / stream() / resumeAfterApproval() instead (with createAgent(), onEvent already receives AgentEvents and is unchanged). The mapping from the old event names to AgentEvent types is in docs/streaming.md#listening-without-iterating (“Migrating from onEvent / ExecutionEvent”). The one-time “onEvent is deprecated” warning is gone with it.
  • Removed createDelegateTool(), DelegateAgentOptions, DelegateAgentResult and DelegationDepthExceededError. Use the subagents option instead, on createAgent() or AgentExecutor.execute(): create the child with createAgent({ provider, instructions, description }) and pass subagents: { billing }. The model gets one task tool for every sub-agent, with the same inheritance (hooks, permissions, abort, usage roll-up) and a depth limit (maxSubagentDepth, default 1). A run at the depth limit is not offered the task tool, so a delegation cycle can no longer start; DelegationDepthExceededError is gone. See docs/sub-agents.md.
  • The executor API moved out of the package root to @lousho/build-ai-agent/executor: AgentExecutor, AgentBuilder, ExecuteOptions, resumeAfterApproval, streamResumeAfterApproval, resumeRequest, ResumeExecuteOptions, ResumeRequest, ToolRegistry and globalToolRegistry. Change import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent' to import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent/executor'. ToolRegistry is also still in @lousho/build-ai-agent/tools. The @lousho/build-ai-agent/core subpath is removed: import AgentBuilder from @lousho/build-ai-agent/executor. createAgent(), ExecutionResult and every type createAgent() uses stay in the root. To move off the executor API entirely, see docs/migrating-to-create-agent.md.
  • The patch guardrails are now called patch checks, so “guardrail” only means the input/output/tool guardrails of createAgent({ guardrails }). Rename: runGuardrails to runPatchChecks, Guardrail to PatchCheck, GuardrailResult to PatchCheckResult, ProposedAction to ProposedPatch, RunGuardrailsResult to RunPatchChecksResult, runGuardrailSafely to runPatchCheckSafely, secretScanGuardrail to secretScanCheck, createDiffSizeGuardrail to createDiffSizeCheck, createCommandGuardrail to createCommandCheck (options type CommandCheckOptions), createTestRunGuardrail to createTestRunCheck, createLintGuardrail to createLintCheck. Arguments, results and behavior are unchanged. SECRET_PATTERNS keeps its name.

Security

  • Behavior change: MCP tools now ask for approval by default (approval: 'always'). A server’s own readOnlyHint / destructiveHint no longer switch approval off or let a tool run in plan mode unless its entry opts in with approval: 'annotations' (loaded descriptors then carry metadata.mcp.annotationsTrusted: false). An MCP tool whose <server>__<tool> name equals a local tool’s is refused with LOUSHO_CONFIG_INVALID instead of silently replacing it and its approval gate. Set approval: 'annotations' on servers you trust to keep the old behavior. See MCP.
  • openApiTools() can refuse private destinations: with the new option privateAddresses: 'refuse' (default 'allow', unchanged), every operation request and the document fetch, each redirect hop included, fails when its host is or resolves to a loopback, link-local, private or reserved address. Host names go through the pinned DNS lookup http_request and web_fetch use (one resolution per connection, every address checked, the socket connects to the checked address), so DNS rebinding cannot reach a private address; IP literals in every form URL normalizes (decimal, octal, hex, IPv4-mapped IPv6) and localhost / *.localhost are refused when the tools are made. allowPrivate lists hosts that may be private. 'refuse' cannot be combined with a custom fetch (it throws a ConfigurationError: a custom fetch’s connections cannot be pinned) and needs Node.js (undici, node:dns); where undici cannot load, making the tools throws a ConfigurationError. See docs/openapi-tools.md#security-rules.
  • The registry permission manifest is now enforced when an agent directory loads and runs. loadAgentDir re-hashes every file the lousho-registry.json receipt lists; an item with edited or missing files is reported unattested (a warning naming the item and files, and manifest.registry on resolveAgentDir(), which also gains the new Attestation, RegistryItemStatus and RegistryStatus types) without refusing the load. Every tool a receipt item owns then runs inside the manifest accepted at install: an exec: true or needsApproval: true item’s tools - and any unattested item’s tools - always wait for approval (a tool’s own deny still denies); fetch while the tool runs is limited to the declared network hosts; process.env shows only the declared env names; and a requiresSandbox tool gets a narrowed adapter (run() refused without exec, writeFile() without filesystem: "write", a command env of the non-secret base plus the declared variables only). The envelope stays as narrow as the last accepted manifest until lousho add <name> --overwrite attests the current files. Limits, unchanged: the guards intercept fetch and process.env, not http/net/axios, the filesystem, module-scope captures or a container’s own network policy; the manifest is still not a sandbox. See docs/registry.md#permission-manifest.

Changed

  • The published package is smaller: ~873 files / ~13.5 MiB unpacked / ~3.65 MiB packed, down from ~902 / ~20.8 MiB / ~5.6 MiB. Test-only files that still shipped (*.test-d.ts type tests, *.testkit.ts helpers, __snapshots__/ and the test-replay __cassettes__/ directories) and the Agent Forge server source map no longer ship, and the SDK’s own source maps no longer embed sourcesContent — their sources still resolve to the shipped src/, so --enable-source-maps stack traces keep working. pack-smoke now also runs build:studio, so it measures the tarball that is actually published, and it fails when a file lousho build or lousho studio needs is missing.
  • Test files are type-checked (npm run typecheck:tests, in CI); pack-smoke also checks the published declarations with skipLibCheck: false.

Added

  • Agent directories: new agent.* config keys permissionMode, permissions (a serializable rule form: tool is a name, a list or - in a code config - a RegExp; when narrows the rule with a record of argument names to matchers - a regular expression string or an operator object (eq/ne, lt/lte/gt/gte on Number(arg), matches), or a predicate in a code config; action is allow / ask / deny), compaction, limits, plus hooks and approve, each a path (relative to the directory) to a file default-exporting the hook(s) / the approver function, or the value inline in a code config. instructions/<family>.md appends to instructions.md when the resolved model id contains <family> (e.g. openai, anthropic). lousho build --target=node-server (and --target=docker) bundles a root hooks.* / approve.* file next to the config and resolves the compiled .js sibling; the Cloudflare Worker target carries permissionMode, permissions, compaction and limits over and accepts hooks / approve from a code config (a file path is refused, a Worker cannot import it). See Agent directories.
  • Registry: a new item type kit is a whole agent directory - its files may sit at any (still safe) relative path - so lousho add <kit> --dir <target> installs agent.*, instructions.md, tools, skills and sub-agents in one item, under one permission manifest, and records it in lousho-registry.json like any other item. The default registry’s first kit is coding-kit, a port of the examples/coding-harness baseline: workspace tools with checkpoint rewind, an allow-listed shell, permission rules, a loop guard and output cap as hooks, a compaction setting, a fix-failing-test skill and a read-only explorer sub-agent (manifest: exec, fs-write; install with lousho add coding-kit --dir <dir> --yes --allow exec,fs-write). See Registry.
  • The pi provider: createAgent({ model: 'pi/<pi-provider>/<model>' }) routes calls through @earendil-works/pi-ai (1.0.3, a new optional peer - npm install @earendil-works/pi-ai@1.0.3), the engine pi-coding-agent runs on, so pi’s whole catalog (OpenRouter, Anthropic, OpenAI, Google,…) is usable natively; e.g. pi/openrouter/openai/gpt-4o-mini is OpenRouter’s openai/gpt-4o-mini (nested slashes are kept: the segment after pi/ is the pi provider, the rest the model id). Messages (including reasoning blocks, tool calls/results and image parts), tool parameters (raw JSON Schema, zod 3/4 or Standard Schema), streamed chunks and usage/cost map to the same surface the ai-SDK providers expose, and pi’s own retries are pinned off so retry/fallbackModels stay the only retry layer. Credentials are per nested provider: pi reads each one’s own env var (pi/openrouter/... reads OPENROUTER_API_KEY), and a missing one fails the call with LOUSHO_PROVIDER_MISSING_API_KEY naming it; a missing package fails with MissingPeerDependencyError naming npm install @earendil-works/pi-ai@1.0.3. New export PiProvider (+ PiProviderConfig, whose models injects custom/faux catalog entries). pi is Node-only: the cloudflare-worker target refuses pi/... specs. See docs/providers.md#the-pi-provider.
  • piAgent() (“pi-coder”): a Pi coding-agent session (@earendil-works/pi-coding-agent, a new optional peer) usable in-process as a createAgent({ subagents }) entry - subagents: { coder: piAgent({ cwd, model, description, permissions }) }. Each task call is one Pi session under the task’s sessionId, so taskId resumes and approval resumes reopen the same JSONL transcript even across a restart. permissions (the same PermissionRules as createAgent()) gate every Pi tool call through a tool_call extension handler: deny refuses it, ask pauses the lead run durably for approval when the caller can pause and refuses it otherwise; approving re-issues that exact call once (Pi has no run-blocked-call API, so a decision prompt asks the model to repeat it and the gate lets that one call through), rejecting sends the note as the next turn. Pi usage rolls into the lead’s result.usage, and aborts propagate to the Pi session. Node-only: the package is loaded lazily, so a consumer without it still typechecks and run() fails with LOUSHO_PEER_MISSING. Also new: defineRemoteSubagent(impl) wraps any RemoteSubagent implementation (same contract as remoteAgent()), and SubagentApprovalPause is exported for such adapters.
  • Agent directories: three more agent.* config keys wire the approval surface. approvalTtlMs is createAgent’s run-level default for how long a pause for approval stays decidable (milliseconds); a permissions ask rule may set ttlMs, bounding that rule’s pauses and winning over approvalTtlMs (both positive finite numbers, rejected otherwise). store declares a durable store so paused approvals survive restarts (“draft today, approve tomorrow”): { "dir": "./.lousho" } (resolved against the agent directory, staying inside it) becomes a fileStore() - sessions, checkpoints and approvals as JSON files, with historyLimit / tokenKey also declarable; a code config may set an AgentStore instance instead. store is Node-only: the Cloudflare Worker target rejects it. loadAgentDir(dir, { approve: null }) / { hooks: null } strip the directory’s wiring (the file the config names is not even imported), where undefined keeps it. The generated node-server / docker server keeps a config-declared store unless LOUSHO_STORE is set. See Agent directories.
  • Agent directories: "engine": "pi" in a subagents/<name>/ config makes that directory a piAgent() coding sub-agent instead of a nested createAgent() one - it lands in the parent’s subagents map (the task tool) and its sessions run in the parent’s directory, the workspace both share. Its model is the usual pi/<provider>/<model> id and its permissions gate the Pi session’s own tool calls; the remaining config keys are ignored (Pi carries its own prompt and tools). loadAgentDir()’s new piAgent override injects PiAgentOptions into every such sub-agent (a faux modelRuntime in tests, a sessionDir for durable approvals); the directory always wins cwd, name and description. Cloudflare Worker targets reject engine - Pi needs the Node runtime. The default registry’s second kit, coding-pi, is coding-kit on the full Pi stack: pi-provider lead, dir-declared pi coder, same safety rails (install --allow exec,fs-write,network,env). See Agent directories.
  • The approve callback may return 'defer' to abstain: the call stays pending (listed by agent.approvals.list(), resolvable by agent.approvals.resolve() / streamResolve() / answer()) and the run surfaces the pause - send() resolves with finishReason: 'awaiting-approval', as if the callback had never been asked - so an approver can decide the calls it trusts and hand the rest to a human. Note: 'defer' is now reserved; an approval note that is exactly 'defer' defers instead of approving. See Deciding in code.
  • Tool-call hook contexts carry resumedAfterApproval: true only when preToolCall / postToolCall fire for the post-approval re-run of a call the run paused on (agent.approvals.resolve(), resumeAfterApproval()). Stateful hooks (loop guards, audit counters) can skip the re-fire with if (ctx.resumedAfterApproval) return;. See Hooks.
  • New ToolDescriptor.transient marks a tool bound per run (a memory slot’s remember_* / recall_* tools, bound to the run’s scope keys): it is left out of the agent fingerprint, so an approval-resumed run - whose registry intentionally does not rebind them - no longer reports tools removed agent drift on every resolve.
  • Approvals can expire. createAgent({ approvalTtlMs }) (validated: positive finite) sets a default deadline for every pause, send()/stream() take a per-call override, a permissions ask rule may set ttlMs (wins over the run default), and ExecuteOptions.approvalTtlMs covers AgentExecutor.execute(); sub-agents inherit the lead’s TTL unless they set their own. A pending approval past expiresAt resolves as denied with 'approval expired' - enforced at decision time, so a durable-store resume (a restart, another process) can never approve a stale pause - and list() keeps expired entries (marked by expiresAt) so resolve() still continues the run. approval.requested events and UIPendingApproval carry expiresAt for UI countdowns; expiry writes an audited deny decision to onPermissionDecision. See Approvals.
  • llmCritique(config): like llmJudge but returns { score, feedback } - one judge call, a SCORE:/FEEDBACK: prompt, graceful degradation on malformed output - so evaluator-optimizer loops get actionable revision guidance, not just a number. See Evals.
  • Testing helpers: testToolContext(overrides?) (@lousho/build-ai-agent/testing) builds a valid ToolExecutionContext for direct tool.execute() calls - getToken/requireAuth fail loudly unless stubbed - and toolResultText(message) (root export) unwraps a tool message’s JSON-encoded content to its result text.
  • Channels: ChannelInbound.metadata now reaches the run as SendOptions.metadata (memory scopes and when contexts can key on channel-supplied data; it is unauthenticated, unlike principal), and webhookChannel({ principal: (body, req) =>... }) can derive the caller principal from a verified body/header - so a webhook intake (PagerDuty, Grafana) attributes the run to the alerting system. See Channels.
  • New registry kits and examples replicating the most-built agent archetypes: inbox-triage (channel intake → classify → draft → approval-gated send, per-sender memory, @hourly sweep; install lousho add inbox-triage --allow env,fs-write) and incident-response (webhook alert → diagnose → risk-tiered approvals → remediate → verify → audit timeline; install --allow env,fs-write); examples deep-research (orchestrator-workers fan-out with cited synthesis), support-desk (triage → handoff() to specialist agents), evaluator-loop (writer ↔ llmCritique revision loop) and data-analyst (text-to-SQL with read-only enforcement). Each runs offline on mock models and accepts OPENROUTER_API_KEY for a live pass.
  • claudeProject(dir): loads a repository’s Claude-Code-conventional context into options that spread into createAgent() — CLAUDE.md/AGENTS.md + .claude/rules/*.md become instructions, .claude/skills/*/SKILL.md load through loadSkills() unchanged, .claude/agents/*.md frontmatter becomes subagents (frontmatter model selects the sub-agent’s model; provider/model options are the fallback), and .claude/scratchpad/ gets a scratchpad note tool (name-validated *.md writes). Nothing in the directory executes: markdown is read as data, and .claude/commands, settings*.json and mcp.json are listed on manifest.ignored rather than loaded. See Claude Code projects.
  • decide(): typed answers from the OpenAI Decisions API (POST /v1/decisions, public beta — gpt-6-luna only) — predicate questions return a probability, choice returns a value plus per-option probabilities and confidence, score returns a rubric’s probability-weighted level index, and any question may come back a refusal. Input is a string or messages with input_text/input_image (inline base64) parts; apiKey (default OPENAI_API_KEY), baseURL, timeoutMs, signal and fetch are overridable. It is the fast path for typed decisions (route/gate/score) — no agent turn and no generated prose — and does not go through providers or OpenRouter. See Decisions.
  • Four new examples covering the agentic-patterns catalog: waves (Workers · Aggregate · Verify · Extend — bounded parallel workers, deterministic merge, a typed { verdict, gaps } verifier, extension waves seeded by its gaps), phase-pipeline (discuss → spec → plan → implement → proof gate → report on FlowBuilder/FlowExecutor, with the implement↔check retry ladder as a oneOf chain), coding-agent-workflows (a coding agent routed by a typed decision — output schema { route, confidence, reason }, a confidence floor escalating low-confidence calls to the careful path), and connectors (MCP connectors à la Claude — runs fully offline against a mock serveMcp stdio server exposing docs_*/slack_* tools; README maps Google Docs, Slack, GitHub and Notion). Plus hostinger-deploy: build an agent with lousho build --target=docker, ship it to a Hostinger VPS over SSH and smoke-test /health + bearer auth + approval pause/resume. See Prompting and context techniques, Connectors and Hostinger VPS.
  • lousho add has a default registry: without --registry or LOUSHO_REGISTRY it reads https://registry.lousho.com/index.json - the registry/dist/ folder of this repository served as static JSON - instead of failing with “no registry configured; there is no hosted registry yet”, so lousho add --list works out of the box. It carries five starter items: the tools open-meteo-weather (current weather by city through Open-Meteo, no API key) and github-issues (list and create issues through api.github.com; creating asks for approval), the skills changelog and code-review, and the generic-webhook channel (HMAC-SHA256 signature verification from WEBHOOK_SECRET). --registry and LOUSHO_REGISTRY still override it, and the new value none (in either place) disables the registry entirely with the old LOUSHO_CONFIG_INVALID “no registry configured” error, for offline or locked-down use. The items live in registry/ as an item.json plus their files per folder; npm run registry:build validates each against the registry schemas, the path rules and the M7a code/manifest check, and writes the committed registry/dist/ (npm run registry:check fails when it is stale and runs in CI). See docs/registry.md.

Fixed

  • A channel button click (Slack, Discord), inline-keyboard tap (Telegram), Adaptive Card press (Teams) or /approve command (GitHub) after a restart is now bound to the conversation’s session before the approval is resolved, so its continuation is appended to the session transcript again. The decision names the conversation it came from (inbound); with checkpointed sessions (mountChannels store with checkpoints, e.g. a SqliteStore) it is accepted only when that session’s pending turn waits on exactly that approval id and kind - a decision for another conversation, a replay of a decided one and a decision of the wrong kind are refused (LOUSHO_APPROVAL_NOT_FOUND) before the approval is touched, and onDecision audits only decisions that pass, so a replayed click cannot run the tool twice and the thread’s next message continues the same session. Without a checkpoint store nothing can be checked, so the approval store alone decides, as before.
  • A channel’s function approvers works after a restart: ctx.approval(id) asked only this process’s agent.approvals.list(), so a pause the restarted process did not make looked the same as a denial and the function failed closed. ApprovalStore gains an optional load(id) - resolve() without removing the record; every shipped store implements it, and a custom store without it keeps compiling and behaves as before - and the new agent.approvals.get(id) reads through it. ctx.approval falls back to that, so the function sees the same request (toolName, input, sessionId, principal) it saw before the restart and fails closed only when no store knows the id (a process-local approval store still forgets its pauses at a restart).
  • A hand-written Cloudflare Worker can now bundle createAgent. The package root also exports file stores, the agent-directory loader, MCP over stdio and sandboxes, so bundling it for platform: 'browser' failed with Could not resolve "async_hooks" (and crypto, fs/promises, http, net, stream) - only the generated Worker ever bundled, because lousho build --target=cloudflare-worker redirects those imports to shims itself. @lousho/build-ai-agent/worker is a new subpath exporting createAgent (and its config types), memoryStore, the KV stores (KVStore, KVCheckpointStore, CHECKPOINT_KV_BINDING), the schedule helpers (defineSchedule, handleScheduled), serveFetch (the /chat API as a fetch handler), the providers a Worker can run and the whole Worker-safe subset agent-directory code may import. The SDK’s own build produces it through the same Node-builtin/sandbox/QuickJS shims the adapter applies (plus new ollama-ai-provider and @modelcontextprotocol/sdk ones, which an external specifier would leave unresolvable and mcpServers therefore fails on first connect - use lousho build for MCP on Workers), so the published entry carries no node: import for a user’s own bundler to fail on; ai, zod, @opentelemetry/api and the @ai-sdk/* provider packages stay external specifiers resolved from the user’s install. Guarded by src/deploy/worker.test.ts; see docs/cloudflare-workers.md#writing-your-own-worker.
  • The published .d.ts files no longer import the types of optional peers: SubprocessSandboxOptions.dockerOptions is now the structural DockerConnectionOptions (same fields as dockerode’s DockerOptions, passed through unchanged) and McpClientLike is the structural subset of the MCP SDK’s Client it already was (listTools / callTool). Before, dist/index.d.ts imported dockerode and the shared schema chunk imported @modelcontextprotocol/sdk, so a consumer compiling with skipLibCheck: false without those optional peers installed got TS2307 inside the SDK’s own declarations. A dockerode DockerOptions or MCP Client value still satisfies both types.

[1.0.0-alpha.18] - 2026-10-08

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

[1.0.0-alpha.17] - 2026-10-07

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

[1.0.0-alpha.15] - 2026-10-06

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

[1.0.0-alpha.9] - 2026-10-04

Security

  • http_request is no longer open to DNS rebinding. It resolved a host name once to check it against the private-address list and then let fetch resolve it again to connect, so a name that answered a public address to the check and 127.0.0.1 (or a cloud metadata or intranet address) to the connection reached the private address; the docs and a comment in the Worker runtime described the check as rebinding-safe. Now the one resolution is the check: the in-process path connects through an undici Agent whose connect.lookup checks every address and hands the socket the address it checked (each redirect hop included), and the sandboxed path (sandboxExecute, which agents use) resolves and checks the host in the agent’s process and has the sandboxed process connect to that address (node:http/https with a fixed lookup; the host name still goes in Host and TLS SNI). The private-address list is now the shared one (below), which adds 0.0.0.0/8, 100.64.0.0/10, 192.0.0.0/24, 198.18.0.0/15, multicast and reserved 224.0.0.0/3, ::, ff00::/8, NAT64 64:ff9b::/96 and 6to4 2002::/16 to what http_request refused. Behavior changes: a host name that cannot be resolved now fails with the resolver’s error instead of being passed to fetch; undici is loaded on the first http_request request (not only with validateSSL: false). New option createHttpTool({ allowPrivate }) for hosts that may resolve to private addresses. Cloudflare Workers have no DNS hook, so neither tool exists in the Worker build; docs/deployment.md now says what a Worker can and cannot check.
  • A run’s principal is fixed for the whole run: an approval resolved by another caller, a restart, agent.resume() or a session’s pending turn continue as the caller that started the run, and the decider is recorded as the approver (ctx.approval.by), never swapped in as the run’s principal, so a later caller cannot use an earlier caller’s grant by approving their pending call. The principal comes only from route auth or a channel’s verified sender; the approvals route and channels never read it from a body field. It is frozen before a tool, a policy or a hook sees it. Remote sub-agents are not told who the caller is.

Changed

  • Behaviour and types: a tool whose execute returns an async iterator that is also async iterable (what an async function* returns) is now iterated: its last yielded value is the result, instead of the iterator object itself (which used to reach the model as {}). AgentEvent gains tool.partial (ToolPartialEvent), isToolEvent() narrows to it too, UIToolCall gains partial?, the tool-output-available UI chunk type gains preliminary?: true, and DefinedTool gains a third, defaulted type parameter (what execute resolves to). Migration: a switch over event.type meant to be exhaustive needs a 'tool.partial' case; code using the result of isToolEvent() as start/done/error only should check event.type; a tool that means to return an async generator as a value should wrap it ({ items: generator }) - a value that is only async iterable, such as a ReadableStream, is still returned as it is.
  • Types only: AgentEvent gains the handoff event (HandoffEvent) and ExecutionResult the optional agentName (set on every result the executor returns: the agent of the final reply). Migration: a switch over event.type meant to be exhaustive needs a handoff case; a test comparing a whole ExecutionResult with toEqual() now sees agentName. Nothing changes at runtime for an agent without handoffs.
  • BREAKING (types only): McpServerStatus gains 'needs-auth', and AgentOAuth (the type of agent.oauth) gains mcpSignInUrl(server). Migration: an exhaustive switch over connectMcp(...).status() values needs a 'needs-auth' case (only servers with oauth ever report it); an object written by hand to satisfy AgentOAuth (a test double, say) needs an mcpSignInUrl method. Runtime behaviour without oauth is unchanged.
  • BREAKING (types only): ToolExecutionContext gains the methods getToken(provider) and requireAuth(provider), and ApprovalKind gains 'sign-in'. Migration: code that builds a tool’s execute context by hand (for example to call tool.execute(args, { toolCallId, messages }) in a unit test) must add the two methods or cast (as ToolExecutionContext); a switch over PendingApproval.kind / approval.requested’s kind that is meant to be exhaustive needs a 'sign-in' case. Contexts the SDK builds have them already; nothing changes at runtime.
  • BREAKING: send() and AgentExecutor.execute() with a listener (createAgent({ onEvent }), onAgentEvent, or the deprecated onEvent option) now stream model calls: a step’s text arrives as several text.delta events, as in stream(), instead of one text.delta per step after the step finished. What a listener receives otherwise does not change: the same event types in the same order, exactly one text.done per step with the step’s whole text, the same step.done usage and run.done, the same ExecutionResult (text, tool calls, usage, steps). A provider without stream(), or whose supportsStreaming(model) is false, still gives one text.delta per step. Output guardrails on send() still check only the final reply (a stream() you iterate checks every step’s text, as before). send() without a listener still calls provider.generate(). Hooks’ ctx.emit is set whenever the run has listeners (it was already; the docs said “only when streamed”). Migration: concatenate text.delta, or listen to text.done for whole steps; execute({ streamModelCalls: false }) (new option, default true) restores whole steps.
  • MockLLMProvider / createMockProvider(): stream() now streams the same step generate() returns: the same tool calls (it streamed none, so a streamed mock run never called a tool), finish reason and usage, and text chunks that add up to exactly the generated text (the old chunks ended with an extra space: 'This is a mock response. '). Runs on the mock provider with a listener (Agent Forge’s, for one) therefore give the same results as before, and stream() runs on it now call tools as send() does.
  • Agent Forge: runs now stream their model calls, so the run WebSocket (WS /agents/:id/stream) carries several text.delta events per step; the chat, logs and trace views are unchanged (they use text.done and the reconciled messages). Stop is checked between streamed chunks and after the last one, as it was after each generate() call.
  • CI peer matrix: the typecheck-ai7 and typecheck-zod4 jobs are replaced by one peers job with five entries, each installed for real on top of the default install and run through tsc, test:types, both builds and npx vitest run: ai4-zod4, ai6-zod3, ai6-zod4, ai7-zod3, ai7-zod4. The two zod 4 entries on ai 6/7 also install ollama-ai-provider-v2 (3.x / 4.x), and the new src/providers/ollamaV2.contract.test.ts runs OllamaProvider against the real package and a local fake Ollama server (generate(), stream(), a tool-call turn through createAgent().send() and .stream()). The ai-v6 dev alias replaces the hand-made ai 6 stand-in in aiMajorPeers.test.ts.
  • lousho init --provider ollama now scaffolds ai@^7.0.0 with ollama-ai-provider-v2@^4.0.0 and zod@^4.0.0 (it was ai@^4.3.19 with ollama-ai-provider@^1.2.0 and zod 3). Existing projects are not touched; to stay on the old pairing keep ai@^4.3.19 and ollama-ai-provider@^1.2.0.
  • A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead’s onAgentDrift. Behaviour change: with onAgentDrift: 'error', agent.approvals.resolve() (and resumeAfterApproval()) now also rejects with LOUSHO_AGENT_DRIFT when a paused sub-agent’s instructions, model or tools changed; before, only tool and provider default-model changes of a sub-agent were seen, and always as a warning. This holds at any depth (a sub-agent of a sub-agent uses the lead’s mode). With 'warn' (still the default) the agent.drift event carries subagent. A rejected resume puts the lead’s approval record and its 'awaiting-approval' checkpoint back, so fixing the sub-agent and resolving again finishes the run; before, a sub-agent’s missing-tool error became an error result of the task call and the run continued. Migration: none for 'warn' / 'ignore'; with 'error', resolve approvals paused before a sub-agent changed with the old definition, or use 'warn'. See docs/durable-execution.md#resuming-with-a-changed-agent.
  • lousho add enforces the permission manifest at install. Behaviour change: an item whose code does not match its manifest is now refused with the new code LOUSHO_REGISTRY_MANIFEST_MISMATCH, and nothing is written. Before writing, every JavaScript / TypeScript file of the item is scanned (comments stripped) for child_process / execa / shelljs / createShellTool / SubprocessSandbox (needs exec: true), fs imports and createFsTools (needs filesystem: "read"), file-writing calls (needs "write"), fetch( and network modules (needs a non-empty network), http(s):// hosts in strings (each must match a network entry) and process.env.NAME reads (each must be in env); eval(, new Function(, a computed process.env[...] and a non-literal import() / require() are always refused. Each finding is listed as <file>:<line>: <what> (<fix>). network entries must now be host patterns and env entries variable names (LOUSHO_REGISTRY_INVALID otherwise). With --yes, an item asking for exec: true, filesystem: "write", a network or an env is refused unless each is named in the new --allow exec,fs-write,network,env flag; the interactive prompt lists them, and the printed manifest marks them [elevated:...]. After writing, lousho add records the item (type, registry, time, permissions, each file’s sha256) in <agent-dir>/lousho-registry.json. Migration: registry authors declare what their code uses; scripts that run lousho add --yes add --allow with the permissions they accept. It is a static check, not a sandbox; see docs/registry.md#permission-manifest. The example item in docs/registry.md now uses input (not inputSchema).
  • Behaviour change: continuing an unfinished checkpointed run (send(message, { sessionId, principal }), AgentExecutor.execute({ sessionId, checkpointStore, principal })) with a principal other than the one it was saved with now throws LOUSHO_CONFIG_INVALID instead of running the new input; without a principal (agent.resume(), a session’s pending turn) the run continues as the saved caller. Migration: resume such a run without principal, or start a new session. onPermissionDecision is called with a second argument, { principal } (callbacks that take one argument are unaffected). Checkpoints, approval snapshots and pending approvals now store the run’s principal (claims included): treat those stores as personal data. Checkpoints and snapshots written before this release resume with no principal; no migration.

Added

  • lousho dev and lousho chat take --traces (or --traces=<dir>) to write local traces with fileTraceExporter(): .lousho/traces by default, the directory lousho traces reads, for spec files, agent directories and modules (specToAgent() now also accepts an exporter option). It is opt-in because trace files hold prompt and tool content even with captureContent: false (only redactContent: true removes it); the command prints where it writes. lousho init projects already ignore .lousho/.
  • Code mode: createAgent({ codeMode: true | CodeModeOptions }) adds a run_code tool. The model writes the body of an async JavaScript function that calls the agent’s tools as await tools.<name>(args), loops and combines their results, and returns one JSON value; run_code returns { result, logs, toolCalls } and only that enters the transcript. Scripts run in a QuickJS WebAssembly isolate from the new optional peer quickjs-emscripten (^0.32.0, listed by lousho doctor; without it the first run of a codeMode agent fails with MissingPeerDependencyError): a fresh runtime per script, no require, import, process, fetch, timers or host objects, values passed as JSON copies, and the limits timeoutMs (30,000, whole script including awaited tool calls), memoryLimitBytes (64 MiB), maxToolCalls (50) and maxOutputChars (20,000, return value plus logs). tools picks the callable tools (default: all but run_code, ask_question, sub-agent tools, tool_search, load_skill and deferred tools); exclusive: true takes them off the model’s tool list. Every inner call (id <run_code id>:<n>) goes through the same gate as a direct call: validation, hooks, permission rules and modes (plan mode refuses non-read-only inner calls; run_code itself is read-only), tool guardrails (a block stops the run), needsApproval, sandbox routing and the principal. A call that would pause the run (approval, sign-in, a sub-agent’s approval) throws inside the script instead and the run does not pause; run_code itself can be paused for approval by a rule and runs after the decision. A failed script’s error lists its first five tool calls with their (clipped) results. New export: type CodeModeOptions. Types: parentToolCallId? on the tool.start, tool.partial, tool.done and tool.error events (set on inner calls; their tool.done / tool.error comes before run_code’s); inner calls get execute_tool spans under the run_code span with the attribute lousho.tool.parent_call_id. No migration needed: nothing changes without codeMode. See docs/code-mode.md.
  • Streaming partial tool results: a tool’s execute may be an async function*. Every yield is a complete snapshot of its output, streamed as the new tool.partial event ({ toolCallId, toolName, output, index }, index from 0) between the call’s tool.start and tool.done; the last yield is the result the model gets (and tool.done’s result), a return value is ignored and a generator that yields nothing has the result undefined. Snapshots are not sent to the model, not added to the transcript, not checkpointed and not recorded in trace spans; hooks see only the result; tokens from ctx.getToken() are redacted in snapshots like in the result. The main loop, a streamed resume after an approval (agent.approvals.streamResolve()) and a flow’s tool-call node iterate the generator; aborting the run stops reading it and calls its return(); toolConcurrency counts the whole generator run. A call that pauses for a sign-in mid-stream runs again from the start (index from 0); partial output is lost on a crash. defineTool types it: ToolOutput<typeof tool> is the yielded type (new helper type ToolResultOf<R>). The UI reducer (useLoushoAgent() and the Vue / Svelte bindings) keeps the latest snapshot as toolCalls[i].partial, and toUIMessageStream() sends snapshots as the AI SDK’s preliminary tool output (tool-output-available with preliminary: true). See docs/tools.md#streaming-partial-results.
  • Tool search: tools marked deferLoading (defineTool({ deferLoading: true }), or every tool of an MCP server with mcpServers.<name>.deferLoading: true, also in spec files and agent directories) are withheld from the model, which finds them with a built-in tool_search tool ({ query } -> { loaded: [{ name, description }], more }); the tools it finds are sent from the next step on, and tool_search stops being offered once everything is loaded. New option toolSearch on createAgent() and AgentExecutor.execute(): { thresholdPercent? (default 0.1 of the context window; 0 always defers), maxResults? (5), contextWindow?, search? }, or false to send every tool upfront. Below the threshold nothing is deferred and no tool_search exists. Which tools are loaded is read from the transcript at each model call, so loading survives crash resume, approvals, forks and session turns; compaction that prunes a tool_search result unloads its tools; a handoff target or a sub-agent never inherits the lead’s loaded tools. Skills, memory, task, ask_question and handoff tools are never deferred. New exports: ToolSearchOptions, ToolSearchResult, rankToolsByKeywords(). Types: ToolDescriptor.deferLoading, DefineToolOptions.deferLoading, McpStdioServerSpec / McpHttpServerSpec.deferLoading, LoadMcpToolsOptions.deferLoading, SubagentSpec.toolSearch, ToolMetadata.mcp.server. Behaviour change: tools loaded by loadMcpTools() / connectMcp() now carry their server name in metadata.mcp.server; a test comparing an MCP tool’s whole metadata with toEqual() needs that key. A user tool named tool_search is refused (LOUSHO_CONFIG_INVALID) only when deferral is active. See docs/tool-search.md.
  • Handoffs: createAgent({ handoffs: [billing, handoff(refunds, options)] }) lets an agent hand the whole conversation to another createAgent() agent (with a name and a description), offered to the model as one transfer_to_<name> tool each. The handoff call is not run as a tool: once the other calls of its step are done, the run goes on in the same send() / stream() as the target, with its instructions (replacing the system prompt), model, tools, skills, sub-agents, reasoning and own handoffs, the lead’s guardrails and permission rules before its own, on the transcript the handoff’s inputFilter returns (handoffFilters.removeToolCalls, handoffFilters.lastUserMessage, or your own). Hooks, limits and spend, maxSteps (counted across agents), the signal, the approval, checkpoint and token stores, listeners, output, the permission mode and the principal stay the run’s. handoff() options: toolName, description, input (validated; bad arguments get a tool error and no handoff), inputFilter, onHandoff, isEnabled (a PerRun<boolean>). Only the first handoff call of a turn is honored; maxHandoffs (default 5) caps one run. The transcript marks each handoff with metadata.handoff = { from, to }; a session’s next turn, agent.resume(), session.resume() and agent.approvals.resolve() continue as the agent it last handed off to (agent.send() without a session starts at the lead), and the resume drift check compares with that agent. Approvals remembered with once() are dropped at a handoff. A transfer_to_* call passes the run’s gate like a tool call: permissions rules apply to it (deny gives the model a kind: 'denied' tool error and no handoff happens; ask pauses the run for approval and the decided call then hands off or reports the rejection), pre/post tool hooks may deny it or rewrite its arguments, and its decision is audited to onPermissionDecision / permission.decision. Each handoff appends a routing system note (metadata.handoff) carrying the validated call arguments to the transcript the target reads; handoffFilters.removeToolCalls keeps it and a custom inputFilter may drop or replace it. createAgent() warns once when a reachable handoff target was created with run-level options (approve, approvalStore, permissionMode, approvalTtlMs, store) - a run keeps the entry agent’s. New handoff event (from, to, toolCallId) and ExecutionResult.agentName; ExecuteOptions.handoffs / maxHandoffs for the executor API. Remote agents cannot be handoff targets. See docs/handoffs.md.
  • OAuth for HTTP MCP servers, per the MCP authorization spec: an mcpServers HTTP entry takes oauth: { redirectUri, clientId?, clientSecret?, scopes?, clientName? } (new type McpOAuthOptions; refused on stdio entries by the spec schema). The MCP SDK’s client does discovery (RFC 9728 protected resource metadata, RFC 8414 authorization server metadata), dynamic client registration (RFC 7591) when no clientId is given, PKCE and resource indicators (RFC 8707), and refreshes an expired token; tokens are kept in the agent’s encrypted token store as provider mcp-<server>, owned by the app. An operator signs the agent in once with the new agent.oauth.mcpSignInUrl(server); N9b’s agent.oauth.complete() and GET /oauth/callback finish it. Without a usable token the server’s status is the new 'needs-auth' and connecting fails with the new error code LOUSHO_MCP_AUTH_REQUIRED (a tool call refused mid-run is a tool error with that code; nothing pauses). connectMcp(servers, { tokens }) takes the token store. Security: oauth needs an https url (http only for localhost, 127.0.0.1 and [::1]); an Authorization header together with oauth is refused; with oauth, headers go only to the MCP server’s origin, never to the authorization server; a stored grant is only used for the url it was obtained for (a changed url needs a new sign-in); no token, code, verifier or client secret appears in errors, logs, status(), events or results. Out of scope for now: per-user MCP grants, a lousho mcp login command, OAuth over stdio. See docs/oauth.md, “MCP servers with OAuth”.
  • Parallel input guardrails: IoGuardrail.runInParallel (default false) makes an input guardrail run while the first model call is already in flight, so a slow, model-backed check no longer delays the answer by its whole latency; promptInjectionGuardrail({ runInParallel }) and moderationGuardrail({ runInParallel }) take it as an option. The blocking input guardrails run first as before (rewrites included), then the parallel ones start together on that input. Until all have passed, the call’s text.delta, reasoning.* and provider-run tool events are held in order (on the iterator and onAgentEvent alike), its tool calls do not run, and onLLMResponse, post-generate hooks, output guardrails, text.done and the checkpoint after the response wait. A trip aborts the call (its signal only, not the run’s), drops the held events and ends the run with finishReason: 'guardrail', result.guardrail and guardrail.tripped (or GuardrailError under onTripped: 'throw'), with nothing of the call in the transcript or a checkpoint; the call’s usage counts in result.usage only when the provider reported it. A parallel check cannot rewrite (action: 'rewrite' blocks, the reason prefixed runInParallel guardrails cannot rewrite: ), and a check that throws fails the run. Ignored on output and tools guardrails. No change for guardrails without the flag. See docs/guardrails.md#input-and-output-guardrails.
  • OAuth sign-in for tools: defineOAuthProvider({ name, displayName?, credentialOwner?, authorizationUrl, tokenUrl, clientId, clientSecret?, clientAuth?, scopes?, redirectUri, authorizationParams?, fetch? }), and in a tool ctx.getToken(provider) and ctx.requireAuth(provider). Without a usable token the run pauses durably like an approval (finishReason: 'awaiting-approval', kind: 'sign-in', signIn: { provider, displayName?, url } on the pending approval and the approval.requested event); the authorization URL uses PKCE S256 and a single-use 256-bit state that expires after 10 minutes, and the verifier is kept only in the encrypted pending record. The new route GET /oauth/callback (lousho dev, the node server, the Worker) and GET <basePath>/oauth/callback (createRouteHandler) is not behind route auth (a browser redirect carries no API token): it calls the new agent.oauth.complete({ state, code?, error? }), which stores the token for the paused run’s principal and answers a small HTML page (400 for an unknown, used or expired state). Approving the pause (agent.approvals.resolve({ id, approved: true }), or the approvals route) runs the tool call again; before the callback it throws LOUSHO_SIGNIN_PENDING (HTTP 409) and the run stays paused. Tokens within 60 s of expiry are refreshed; requireAuth() deletes a refused token and pauses. A user credential needs a principal (LOUSHO_OAUTH_PRINCIPAL_REQUIRED); an app credential (credentialOwner: 'app') is never asked of a chat user (LOUSHO_OAUTH_APP_SIGNIN_REQUIRED) and is connected by the operator with agent.oauth.signInUrl(provider). The approve callback is never asked about a sign-in. Slack sends the link with chat.postEphemeral and Discord as an ephemeral follow-up, both without buttons; GitHub never posts it in a public thread; behind createDeployedServer() and lousho dev the callback continues the paused channel turn. The UI state (pendingApproval.signIn), the data-lousho-approval part, lousho dev’s page, lousho chat and lousho acp show the link. A tool result that contains a token handed out during that call is redacted to [REDACTED] with a warning. New error codes LOUSHO_OAUTH_PRINCIPAL_REQUIRED, LOUSHO_OAUTH_APP_SIGNIN_REQUIRED, LOUSHO_OAUTH_STORE_MISSING, LOUSHO_OAUTH_STATE_INVALID, LOUSHO_SIGNIN_PENDING, LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED. See OAuth.
  • Hosted tools on Anthropic and OpenRouter: webSearch() and codeInterpreter() now also run on the Anthropic provider (ai 6 with @ai-sdk/anthropic 3, ai 7 with @ai-sdk/anthropic 4): webSearch() is the newest tools.webSearch_*() the installed package exports (options maxUses, allowedDomains, blockedDomains, userLocation), codeInterpreter() the newest tools.codeExecution_*(); events and usage.hostedToolCalls keep the neutral name code_interpreter. fileSearch() on Anthropic, and codeInterpreter() / fileSearch() on OpenRouter, are LOUSHO_HOSTED_TOOL_UNSUPPORTED. webSearch() works with every openrouter/... model on any ai major: the provider adds OpenRouter’s openrouter:web_search server tool to the request body (after the function tools, composing with the reasoning field; maxUses, allowedDomains, blockedDomains and searchContextSize map to its parameters) and reports one hosted call per step that searched, read from the response: the cited urls from url_citation annotations as sources, and result: { requests } when OpenRouter reports usage.server_tool_use.web_search_requests. OpenRouter bills each search on top of tokens (not in costUsd). supportsHostedTool() on both providers reflects this. The per-provider table in docs/hosted-tools.md is complete, and a replayable cassette from a live OpenRouter search is in the test suite (npm run test:live re-records it with OPENROUTER_API_KEY).
  • Hosted provider tools: webSearch(), codeInterpreter(), fileSearch() and hostedTool(name, aiSdkTool) go in createAgent({ tools }) next to local tools (array or record form; in the record form the key must be the tool’s name), and the provider runs them inside the model request. OpenAI maps them to openai.tools.webSearch() / .codeInterpreter() / .fileSearch() on ai 6 with @ai-sdk/openai 3 and ai 7 with @ai-sdk/openai 4 (options it does not take, such as maxUses, are dropped with one warning); hostedTool() passes any AI SDK provider tool through on ai 6 or 7, including on fromAiSdk() models. Provider-executed calls are never handed to the executor as local tool calls (on ai 6/7 they used to come back as calls of an unknown tool): they are reported as tool.start / tool.done / tool.error with the new optional field executedBy: 'provider' (as they stream in, or after a non-streamed call in call order; results capped at 20,000 characters of JSON), kept on the step’s assistant message as metadata.hostedToolCalls (with url sources; not sent back to the model), counted in usage.hostedToolCalls and run.done usage per tool name (fees not in costUsd), and named on the chat span as lousho.hosted_tool_calls. A step whose only calls the provider ran ends the run even when the provider reports tool-calls. No permission rule, guardrail, approval or hook runs for them; instead, in permission mode 'plan' only the read-only webSearch() and fileSearch() are sent to the provider (codeInterpreter() and hostedTool() are left out of the request, read before every model call), and every other mode sends them all. New: ExecuteOptions.hostedTools, GenerateOptions.hostedTools, GenerateResult.hostedToolCalls, HostedToolCall, stream chunks hosted-tool-call / hosted-tool-result, optional LLMProvider.supportsHostedTool(type), mockModel turns with hostedToolCalls, cassettes that keep hosted calls, error code LOUSHO_HOSTED_TOOL_UNSUPPORTED (ai 4, Ollama, a provider without supportsHostedTool(), or an @ai-sdk/openai without the tool). Sub-agents do not inherit the lead’s hosted tools; the agent fingerprint includes them. Anthropic and OpenRouter mappings follow in N1b (below). See docs/hosted-tools.md.
  • session.history() and session.fork({ fromStep, id?, patch? }) on agent.session() sessions. history() lists the steps of the committed transcript (one per model response: step numbered from 1 across the session, turn, messageIndex, text, and toolCalls with args and result). fork() saves the transcript up to and including a step (0 keeps nothing), optionally with one tool result replaced (patch.toolResult), under a new id in the same store (default <id>-fork-<n>) and returns a session of the same agent and options (with the permission mode the session has at that moment); the original is not changed. The spend recorded for limits up to that point carries over. A turn waiting on an approval or a question, or an interrupted checkpointed turn, stays with the source session, so it is resolved once; workspace files are not rewound. Works on every shipped store (memory, fileStore(), SqliteStore, KVStore), with one contract suite run against each. New types SessionHistoryStep, SessionForkOptions and SessionSpawner; new error codes LOUSHO_SESSION_STEP_NOT_FOUND, LOUSHO_SESSION_EXISTS and LOUSHO_SESSION_FORK_UNSUPPORTED; AgentSession’s constructor takes an optional fourth argument, the function that creates its forks. See Forking a session.
  • Permission modes: createAgent({ permissionMode }), send() / stream() { permissionMode }, agent.session({ permissionMode }) and session.setPermissionMode() put an agent in 'plan' (only read-only tools run; everything else is refused with kind: 'denied', also when an allow rule matched, and a run that starts in plan mode gets one system-prompt paragraph saying so), 'acceptEdits' (file edits that would ask run without asking) or 'dontAsk' (a call that would ask is refused; nothing pauses). The modes are presets applied after hooks, permission rules, tool guardrails and needsApproval, so no mode turns a deny into a run. A function mode, and a session’s mode, are read at every tool call, so a switch applies from the next call, also mid-turn and in a paused turn continued by agent.approvals.resolve(). Sub-agents run under the lead’s mode unless it is 'default'; a remote sub-agent is refused in plan mode. Audit: under a mode other than 'default' every call is audited, PermissionDecisionEntry.mode says when the mode changed the outcome, and the new onPermissionModeChange records each switch. New: PermissionMode and PermissionModeChange types, defineTool({ editsFiles }) (metadata.editsFiles, set on write_file and edit_file), readOnlyHint: true on load_skill, recall_<name>, agent_status and agent_await. The mode is not saved in checkpoints. Example: examples/plan-mode. See Permission modes.
  • Semantic recall: a memory slot can recall by meaning. New EmbeddingProvider ({ id, embed(texts) }) and aiSdkEmbedder(model, { id?, maxBatch? }), which wraps any AI SDK embedding model through embedMany from the installed ai (4, 6 or 7; ai is loaded on first use, no new dependency), and two providers that rank by cosine similarity: inMemoryVectorMemory({ embedder, maxItems?, minScore? }) from the root and sqliteVectorMemory(store, options) from @lousho/build-ai-agent/sqlite (a new memory_vectors table, added to an existing database file on open; memory_items and sqliteMemory() are unchanged). With a query, list() returns the scope key’s items by score (floor minScore, default 0.2; score in metadata.score); without one it lists the newest first. Items embedded by another embedder id are skipped when ranking until provider.reindex(scopeKey?) re-embeds them. A MemoryProvider may set ranking: 'relevance', which makes the recall_<name> tool say “by meaning, most relevant first”. hashEmbedder({ dimensions? }) from @lousho/build-ai-agent/testing is a deterministic offline embedder for tests. describeMemoryProviderContract takes { query: 'filter' | 'rank' }. docs/memory.md has a new ## Semantic recall section at the end.
  • teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? }): an agent behind an Azure Bot in Microsoft Teams, mounted like the other channels (POST <basePath>/teams). The inbound Bot Framework token is verified with the auth module (oidc(): RS256, the key set of the fixed Bot Framework OpenID metadata, issuer https://api.botframework.com, audience appId, 5-minute tolerance) before the body is parsed, and its serviceurl claim must equal the activity’s serviceUrl; replies go only to that service URL (https). Personal chats always reach the agent, group chats and channels only on an @mention (stripped from the text); one session per conversation; Markdown replies split at 25,000 characters; tool approvals are Adaptive Cards with Approve and Deny buttons (approvers as on the other channels; the card updates to “Approved by…” and names its conversation, so a copied or replayed reference decides nothing); ask_question is answered by the next message, also after a restart with durable stores. No node:* import. Telegram and GitHub now set the sender as the run’s principal too (authenticator: 'telegram' with the user id, 'github' with the login), as Slack and Discord do. See docs/channels.md#microsoft-teams.
  • Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): npx lousho build./my-agent --target=cloudflare-worker. The build reads the directory on Node and generates agent.module.ts (static imports of tools/* and of an agent.ts config; instructions.md, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of resolveAgentDir() (the config check and the tool-export rules now live in Node-free modules both use). The config’s model must name a Worker provider, or agent.ts sets a provider instance. subagents/, schedules/, channels/, memory/, projectInstructions and an unsupported provider are rejected with LOUSHO_DEPLOY_FAILED, naming what to remove. In a Worker build, an agent file’s @lousho/build-ai-agent import resolves to a Worker-safe subset (defineTool, defineSkill, the Worker providers, fromAiSdk, errors,…); another name fails the build with the list. The leak check now names the file that imported a Node builtin ("node:fs" imported by my-agent/tools/files.ts) instead of failing with esbuild’s “Could not resolve”. Tools run in the Worker’s isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
  • Workspace rewind: createFsTools(fs, { checkpoints }) with a new WorkspaceCheckpoints backs up every file write_file and edit_file change (content and, where the provider has the new optional FsProvider.getMode / chmod, permission bits), grouped by session and turn. checkpoints.list({ sessionId }) shows the changed paths per turn; checkpoints.rewind(toTurn, { sessionId, dryRun, force }) restores every file changed in that turn or later, deletes files the agent created, and skips files changed since by something else ('changed-since'), files over maxFileBytes ('too-large') and paths that are no longer files. Every path is checked before anything is written, and restores go through the provider, so NodeWorkspace keeps them inside its root. Retention: the newest maxTurns turns per session (default 20), the old content only for a turn’s first write of a path, rewound turns dropped, clear({ sessionId }). Stores: MemoryWorkspaceCheckpointStore (default) and FileWorkspaceCheckpointStore(dir) (one JSON file per session, atomic writes). NodeWorkspace gains getMode() and chmod(). Without checkpoints the tools behave as before. See Workspace tools.
  • Route auth and principals: a new subpath, @lousho/build-ai-agent/auth, with jwt(), oidc(), basic(), apiToken(), anonymous() and routeAuth(). A route takes an ordered list of entries: the first one that returns a Principal accepts the request, null skips to the next, AuthError(401 | 403) stops; when every entry skips the answer is a generic 401 with one WWW-Authenticate header per challenge (Bearer, Basic realm="..."), and the body never says which check failed. JWTs are verified with Web Crypto only (no new dependency, no node: import, so the helpers run on Workers and edge routes): alg: none, algorithms outside the configured list, a crit header and algorithm confusion (an HS token checked against a public key) are refused; exp is required, nbf / iat honored, iss / aud checked, with a clock tolerance of 60 s (at most 300); JWKS key sets are cached for 10 minutes and refetched at most once per 30 s, and a key-set URL is never taken from a token. oidc() uses the configured issuer’s discovery document and requires it to name the same issuer. basic() and apiToken() compare in constant time. createRouteHandler({ auth }) and createDeployedServer(agent, { auth }) take the list (a token string and a boolean function work as before); the node server appends apiToken(LOUSHO_API_TOKEN) when that variable is set; an agent directory’s auth.ts is bundled by lousho build --target=node-server / docker and guards the built server (resolveAgentDir() returns it as auth, the manifest has auth: true). The accepted principal reaches the run: send() / stream() / session turns take principal, and RunConfigContext (the model / instructions / tools functions) and MemoryScopeContext (memory scopes) carry it; Slack and Discord channels set the sender as the principal. Principal is also exported from the root. Bad helper options throw the new error code LOUSHO_AUTH_CONFIG_INVALID when the helper is created. createRouteHandler() without auth logs one warning when NODE_ENV is production. Route auth does not check session ownership, the principal does not reach tools or approval policies yet, and the Cloudflare Worker target keeps the LOUSHO_API_TOKEN token only. See Route auth and principals.
  • OAuth token storage: AgentStore gains a fourth optional part, tokens (OAuthTokenStore: get / set / delete / list per provider and credential owner, single-use pending sign-ins with putPending / takePending, and getClient / setClient for dynamically registered clients). Owners are { owner: 'app' } or { owner: 'user', principalId, issuer? }; tokenStoreKey(provider, owner) is the stable, percent-encoded record key (<provider>|app, <provider>|user|<issuer>|<principalId>). memoryStore() keeps tokens in process memory; fileStore(dir), SqliteStore and KVStore encrypt every record with AES-256-GCM (Web Crypto, a fresh 12-byte IV per write, the record key as additional authenticated data) under a 32-byte key the application supplies as tokenKey or LOUSHO_TOKEN_KEY; there is no default key. Several keys (newest first, or comma-separated in the variable) rotate: writes use the first, reads try each. New error codes LOUSHO_TOKEN_KEY_MISSING (first write, or a read of an existing record, without a key) and LOUSHO_TOKEN_DECRYPT_FAILED (wrong key or a changed record; names the provider, never the token). list() returns metadata only. generateTokenKey() makes a key. SQLite: schema migration 4 adds the oauth_tokens and oauth_pending tables, and prune() also deletes expired pending sign-ins (its result gains oauthPending). KV: keys under <prefix>oauth/, pending sign-ins written with an expirationTtl; KVBinding gains an optional list() (used only by tokens.list()), and KVListOptions / KVListResult are exported from /kv. The generated Cloudflare Worker passes its LOUSHO_TOKEN_KEY secret to KVStore. Nothing signs in yet; the sign-in flow follows. New page OAuth; new ## OAuth section at the end of docs/errors.md.
  • githubChannel({ webhookSecret, botName, token?, app?, botLogin?, name?, apiUrl?, fetch?, triggers?, approvers?, onError? }): an agent that answers GitHub issue, pull-request and review comments. @<botName> in a comment starts a turn and the reply is a new comment in the same thread (a review thread gets a reply under it; text over 60,000 characters is split); one session per issue or pull request and one per review thread, and later comments in a thread with a session are follow-ups. X-Hub-Signature-256 is verified over the raw body in constant time before the body is parsed (401 otherwise); the webhook is acknowledged at once. Comments by bots, by the channel’s own account and every comment the channel posts (a hidden marker) are ignored, and so are edits, deletions and other events. Replies are posted with token (a personal access token, or a function) or as a GitHub App (app: { appId, privateKey }: a PKCS#1 or PKCS#8 key signs an RS256 JWT with Web Crypto, exchanged for an installation token that is cached per installation until 5 minutes before it expires; src/channels/githubAppAuth.ts, not exported). Approvals are comments: the prompt asks for /approve <id> or /deny <id> (first line only, notes below it), and by default only a commenter whose author_association is OWNER, MEMBER or COLLABORATOR may decide, read from the command comment itself; approvers (logins, or a function that sees the association in user.roles) overrides it, and triggers (logins, or a function) restricts who may start a turn or answer a question (default: everyone who can comment, so restrict it on a public repository). A comment is untrusted input to the agent; see the security note in docs/channels.md. An ask_question is answered by the next comment in the thread and survives a restart given durable stores. Errors name the call and the HTTP status, never the token. The LOUSHO_CHANNEL_INVALID hint, docs/agent-directories.md and docs/errors.md now list githubChannel(). New section ## GitHub at the end of docs/channels.md.
  • Agent Forge keeps the traces of its runs: every run is written with fileTraceExporter() to .lousho/agents/<agent id>/traces (the files lousho traces reads), and the Trace tab gets a list of the agent’s past runs (time, duration, model calls, tokens, cost, status) with a “Live” entry while a run is active; choosing one opens its spans in the waterfall, with span kind and error status. New server routes GET /agents/:id/traces?limit=N and GET /agents/:id/traces/:traceId; the server reads only inside the agent’s trace folder. The live span WebSocket messages now carry kind and status (optional fields of SpanEvent). See Agent Forge.
  • A background sub-agent that needs approval pauses the lead when the lead awaits it (agent_await), and resumes with approvals.resolve() / resume(). The lead’s result is awaiting-approval with the child’s call (subagentPath: ['<agent>']) in agent.approvals.list(); the decision runs or rejects the child’s call, the child finishes, and the continued lead gets its answer as the agent_await result. A child that pauses again, or several awaited tasks that are all paused, pause the lead one approval at a time. The child’s usage is added to the lead’s, and its conversation is saved under its taskId. The paused tasks are kept on the lead’s approval record (SubagentSuspension.background, plain JSON), never in the tool arguments the model sees. Without agent_await nothing changes: the task reports awaiting-approval and is not resumable. The task and agent_status tool descriptions tell the model that a task awaiting approval continues only when it calls agent_await on it. Docs: docs/sub-agents.md (“When the lead run ends” and “Continuing a task”).
  • Guardrail starter set: piiGuardrail() (email, phone, credit card with a Luhn check, IBAN with its mod-97 check, US SSN, IPv4; blocks, or rewrites each match to [<type>]), secretsGuardrail() (private keys; Anthropic, OpenRouter, OpenAI, AWS, GitHub, Slack, Google and Stripe live keys; JWTs; Authorization: Bearer tokens; extraPatterns; rewrites to [secret] by default), promptInjectionGuardrail() (phrase, role-marker and Unicode-tag heuristics, plus an optional model check that must answer SAFE or INJECTION: <reason>) and moderationGuardrail({ model }) (one model call that answers NONE or the categories that apply: hate, harassment, self-harm, sexual, sexual-minors, violence, illicit). The PII, secret and injection checks are heuristic pattern checks: they catch common cases and miss others, and are not a security boundary. Model-backed checks fail closed on a reply they cannot read. A guardrail result can now carry info?: GuardrailTripInfo (pii, secret, prompt-injection, moderation or custom), copied to result.guardrail, guardrail.tripped and guardrail.rewrote; it holds types, labels and offsets, never the matched text. Agent spec files can name them in policy.guardrails as pii, secrets, prompt-injection and moderation. New exported types GuardrailTripInfo, PiiType, ModerationCategory. Docs: Guardrails, Configuration, Stream events.
  • telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? }): an agent behind a Telegram bot, mounted like the Slack and Discord channels (POST &channels&telegram). The webhook secret token header (X-Telegram-Bot-Api-Secret-Token) is compared in constant time (401 otherwise); updates are acknowledged with 200 and the turn runs after. A private chat is one session per chat; in a group only &ask, &ask@<botUsername>, an @<botUsername> mention or a reply to the bot wakes it, and a forum topic is its own session. Replies are plain text, split at 4096 characters. Tool approvals are an inline keyboard (Approve & Deny) that only approvers (default: the user who started the turn) can tap; the tap names its chat, so it works after a restart. An ask_question is sent with force_reply; a pending one survives a restart given durable stores, like Slack and Discord. The bot token is never put in an error message or log line. src&channels&channelSupport.ts gains the internal secretsEqual() (constant-time compare with Web Crypto). The LOUSHO_CHANNEL_INVALID hint, docs&agent-directories.md and docs&errors.md now list discordChannel() and telegramChannel(). New section ## Telegram at the end of docs&channels.md (attachments are not read yet).&r
  • todo.updated stream event and useTodos() (React, Vue) / loushoTodos() (Svelte): every successful todo_write emits todo.updated { todos, counts, toolCallId } right after its tool.done (sub-agents too, with subagent). The shared UI reducer keeps the list in a new AgentUIState.todos (carried across turns, cleared by reset()), useLoushoAgent() / loushoAgent() expose it, useTodos(agent) / loushoTodos(agent) add counts, the current item and progress (todoView() computes the same view framework-free), and toUIMessageStream() sends a data-lousho-todos part for the AI SDK UI. See Todos.
  • Cloudflare Worker target: the openrouter provider and the http tool (with a required LOUSHO_HTTP_ALLOW host allowlist). openrouter reads its key from the OPENROUTER_API_KEY binding and is @ai-sdk/openai pointed at OpenRouter, so its bundle passes the node: leak check like openai. The Worker’s http is http_request with the Node tool’s input, over the platform fetch(): since a Worker cannot see or pin where a host name resolves, it reaches only the host names (api.github.com) and *. wildcards (subdomains only) listed in the comma-separated LOUSHO_HTTP_ALLOW binding, refuses IP-address hosts even when listed and any scheme but http:/https:, checks every redirect hop the same way, and refuses every request when the binding is unset or empty. An invalid entry fails every request with an error naming it. wrangler.toml gets a commented [vars] LOUSHO_HTTP_ALLOW line when the spec lists http. ollama and web-fetch stay unsupported on Workers. Internally, the request, redirect and response logic of http_request moved to the Node-free src/tools/built-in/httpCore.ts, shared by both tools; the Node tool’s behaviour is unchanged. See docs/cloudflare-workers.md#providers-and-tools.
  • fromAiSdk(model): any AI SDK LanguageModel (Google, Bedrock, Azure, Mistral, Gateway,…) as createAgent({ provider }). Options name (default: the model’s provider field), fileMediaTypes, replaysReasoning and maxRetries (default 0); exported with FromAiSdkOptions from the package root. Throws LOUSHO_CONFIG_INVALID for a model id string, for a model built for another ai major than the installed one, and for a call with another model id than the wrapped one. See docs/providers.md#any-ai-sdk-model-fromaisdk.
  • Two ready-made durable stores. @lousho/build-ai-agent/kv is a new subpath exporting KVStore, KVCheckpointStore, CHECKPOINT_KV_BINDING and the types KVStoreOptions, KVBinding, KVPutOptions, so a hand-written Cloudflare Worker can use createAgent({ provider, store: new KVStore(env.AGENT_KV) }); nothing in its import graph touches node:*, so it bundles without shims (assertSessionId moved to the Node-free src/session/sessionId.ts and is still exported where it was). fileStore(dir, { historyLimit? }) (root export) is an AgentStore of plain JSON files: sessions/<id>.json, checkpoints/<id>.json, checkpoint-history/<id>.json and approvals/<id>.json, each written to a temp file and renamed into place, with no lock files and no StorageService; resolving an approval claims it with an exclusive create, so of two processes resolving one approval only one gets it. It replaces combining FileSessionStore, LocalStorageCheckpointStore and StorageServiceApprovalStore by hand. See docs/sessions.md#choosing-a-store and docs/deployment.md.
  • web_fetch built-in tool: webFetchTool / createWebFetchTool(options), and web-fetch in spec files. It GETs one public web page and returns { url, finalUrl, status, contentType, content, truncated }: HTML converted to text by a small built-in converter (scripts and styles dropped, link URLs kept, entities decoded), JSON and text/* as sent, a note for other types; a 4xx/5xx is returned with its body. Loopback, private and link-local destinations are refused on every hop with the connection pinned to the checked address; redirects (10), bytes read (2 MiB), characters returned (50 000) and time (30 s) are capped; allowedHosts / blockedHosts are checked before DNS and allowPrivate exempts named hosts. Node only. See docs/tools.md#built-in-tools.
  • src/security/privateAddress.ts (internal): isPrivateAddress() and pinnedLookup(), shared by the credential broker, http_request and web_fetch. The credential broker uses it instead of its own list, so it also refuses 192.0.0.0/24, 198.18.0.0/15, NAT64 and 6to4 addresses.
  • Slack and Discord: a pending ask_question survives a restart. Given durable stores for sessions, checkpoints and approvals, the next message in the Slack thread (or the next /ask in the Discord channel) after a restart is still the answer: the turn continues, the reply is posted, and the question, the answer and the reply are appended to the session transcript (before, the answer became a new turn and the question was orphaned). A message in a conversation that waits on a tool approval still does not decide it. New ChannelContext.pendingQuestion(sessionKey) for custom channels: the id of the ask_question that key’s session waits on, also one asked before a restart (it binds the approval to the session, so the continuation is recorded); handed out once until that answer has run. A channel’s answer and click continuations now run one at a time with the session’s turns. Supporting additions: Checkpoint.approvalKind, PendingTurn.approvalKind (session.pending()) and SessionAwaitingApprovalError.approvalKind are 'question' for a turn paused on an ask_question. Slack thread replies that answer a pending question no longer need a saved transcript first (a first turn paused on a question with checkpoints has none yet). See docs/channels.md.
  • Local traces and lousho traces: createAgent({ exporter, captureContent }) traces every run of the agent (send(), stream(), session turns, agent.resume() and runs continued by agent.approvals.resolve(); sub-agents join the lead’s trace). The new subpath @lousho/build-ai-agent/traces exports fileTraceExporter({ dir }), which writes each run as JSON Lines to <dir>/<YYYY-MM-DD>/<traceId>.jsonl (default .lousho/traces; one finished span per line; a write error warns once and never fails the run), and listTraces() / readTrace() to read them. npx lousho traces [--dir D] [--limit N] [--json] lists recent runs with duration, model and tool calls, tokens and cost; npx lousho traces <id|prefix> [--json] [--content] prints one run as a span tree with duration bars. Projects made by lousho init now ignore .lousho/. See docs/observability.md#local-traces.
  • openApiTools(document, options): an OpenAPI 3.0 / 3.1 document (object, JSON or YAML string, or https URL) becomes one typed tool per operation, exported from the root and ./tools. Names come from operationId (or <method>_<path>); the input has path, query, header and cookie parameters plus an application/json body, with $refs resolved; every HTTP response is returned as { status, statusText, body }. GET, HEAD and OPTIONS run and other methods ask for approval by default (approval), with read-only / destructive annotations. Options: baseUrl, include, exclude, prefix, headers, bearerToken, providedArguments (removed from the model’s schema), timeoutMs, maxResponseChars, fetch. The base URL must be https (http only for loopback), credentials never reach events or the transcript, and redirects are followed only on the base origin. Swagger 2.0, multipart bodies and remote $refs are refused. jsonSchemaToZod(schema, root?) takes an optional root for $ref resolution. New page docs/openapi-tools.md.
  • Built-in OpenAI, Anthropic and OpenRouter providers send PDF file parts on ai 6 and 7 (Anthropic also text/plain); ai 4 and Ollama keep the text note. A provider subclass opts more media types in with fileMediaTypes() (acceptsFileParts = true still sends every type). The text-note warning is now once per provider and media type and names the type and the ai major. Added npm run test:live (vitest.live.config.ts) for *.live.test.ts files, which the default suite excludes. See docs/providers.md#multimodal-input.
  • Principals in tools, approval policies and permissions: the run’s principal reaches a tool’s execute(args, ctx) as ctx.principal, needsApproval functions (ApprovalCheckContext.principal), permission rules’ when(args, ctx) (PermissionContext.principal), preToolCall / postToolCall hooks (ToolCallHookContext.principal), onPermissionDecision’s new second argument (PermissionAuditContext), pending approvals (PendingApproval.principal, seen by approve and by a channel’s approvers function as request.principal) and in-process sub-agents (task, background tasks, createDelegateTool(); remoteAgent() does not forward it). New ExecuteOptions.principal, set by createAgent() for send(), stream(), session turns and channel turns. It is saved in checkpoints (Checkpoint.principal) and approval snapshots (ExecutionSnapshot.principal), so a static or dynamic run resumed after an approval or a crash acts for the same caller. agent.approvals.resolve() / answer() / streamResolve() / streamAnswer() take { principal } (new ResolveApprovalOptions) for who decides, and the approved tool sees it as ctx.approval.by; resumeAfterApproval() takes it as executeOptions.approver. The approvals route (POST /chat/:sessionId/approvals/:id) passes the caller route auth accepted, and mountChannels() the clicking user ({ id, type: 'user', authenticator: <channel name> }) or, for a question answered by a message, its sender. agent.fork() keeps the source run’s principal; session.fork() copies only the conversation. The principal is not added to events, spans or trace files. See Principals in tools and approvals.

Deprecated

  • SlackTriggerAdapter, CronTriggerAdapter and WebhookTriggerAdapter (@lousho/build-ai-agent/triggers) are deprecated and will be removed in a future major version. Use slackChannel() for Slack (sessions per thread, approval buttons), defineSchedule() with startSchedules() for cron (or schedules/ in an agent directory, or cron triggers in a spec file), and webhookChannel() for webhooks, each mounted with mountChannels(). verifySlackSignature(), the WebhookAuth helpers, parseCronExpression(), TriggerAdapter and TriggerRegistry are not deprecated. Their options types (SlackTriggerAdapterOptions, CronTriggerAdapterOptions with CronIntervalOptions and CronExpressionOptions, WebhookTriggerAdapterOptions) and WebhookTriggerHandle carry @deprecated too. Nothing changes at run time. See docs/triggers.md.

Fixed

  • lousho CLI surface: lousho dev/lousho chat --traces now writes traces for a .ts/.js module that exports an already-built createAgent() agent - the module’s export could not take the flag’s exporter after the fact, so nothing was written. createAgent() remembers the config it was built with (readable via the internal createAgentConfigOf()), and the loader rebuilds the agent with the flag’s exporter (the module’s own exporter is replaced while the flag is set; a module exporting an agent not made by createAgent() prints a warning and keeps its own). A spec path that does not exist (e.g. lousho chat missing.yaml) now fails with the coded LOUSHO_SPEC_NOT_FOUND instead of a raw ENOENT. lousho add --dry-run no longer fails when a target file already exists; it prints the file list with an “(exists - a real install needs —overwrite)” marker and exits 0 (the symlink checks still run). Top-level lousho --help lists the implemented flags again: --no-schedules/--traces on dev and chat, eval’s record/replay/drift/--config flags, init’s --sdk-path, and build’s positional form.
  • A cassette failure keeps its type through agent.send(): a replay mismatch (or a missing cassette raised by the provider-interception seam that lousho eval installs) was compacted into a generic CompactedLLMProviderError, losing the cassette path, the call number and the re-record hint. CassetteMismatchError is now an SDKError with code LOUSHO_CASSETTE_INVALID (docs/errors.md already claimed cassette errors carry it), and the run loop rethrows cassette errors untouched instead of compacting them, so send() rejects with the CassetteMismatchError itself (.cassette, .callNumber). setProviderInterceptor() and the ProviderInterceptor type are now exported from @lousho/build-ai-agent/testing, the public entry for the model-boundary seam docs/evals.md describes.
  • A tool call approved with agent.approvals.resolve() (or resumeAfterApproval()) now has its execute_tool span. It ran before the continued run started, outside any span, so OpenTelemetry and fileTraceExporter() showed the continued run’s invoke_agent and chat spans but not the approved tool. The continued run’s invoke_agent span now opens first and the approved call runs inside it: its execute_tool span is a child of it (a run_code call’s inner calls and a sub-agent the tool starts are children of the tool span), with the same captureContent / redactContent rules as any tool span, and no span is made for a rejected call. A pause that happens again (sign-in) leaves the invoke_agent span with the tool span and no chat.
  • A tool that returns undefined (or an async generator that yields nothing) no longer writes a tool message with content: undefined into the transcript. Its result is now null everywhere: the transcript and the next model request carry "null", and tool.done, approval resumes, run_code and flows see null. Providers, session stores and checkpoints get a valid string.
  • recordReplay matches a tool’s parameter schema the same way under zod 3 and zod 4. A zod 4 schema was fingerprinted from its JSON Schema (with $schema, required, additionalProperties) while a zod 3 one, and so every recorded cassette, used a fingerprint of the schema itself, so cassettes recorded with zod 3 failed to replay with zod 4 installed (the CI peers jobs ai4-zod4, ai6-zod4 and ai7-zod4 failed on every replay test). Both now give the same fingerprint for the same schema; existing cassettes stay valid and need no re-recording, and a real change to a tool’s parameters still fails the match.
  • Parallel task calls now get their taskIds, and background tasks start, in call order: allocating an id awaited a SHA-256 digest whose completion order is not fixed, so with maxConcurrent: 1 the second task could take the slot first (#296, the flaky “queues tasks beyond maxConcurrent” test).
  • SubprocessSandbox.run() no longer fails with HTTP 404 “no such container” for a command that exits at once: the container is AutoRemoved, and wait() was only called after start(), so a fast command could be gone by then (10 of 40 parallel true runs failed on Docker Desktop). It now begins wait({ condition: 'next-exit' }) before start(), and removes the container if start() itself fails.
  • The cloudflare-worker build’s Node-builtin leak check now accepts the runtime-guarded loadNodeModule("node:module" | "node:dns") probes that @ai-sdk/provider-utils 4 (installed with ai 6) uses, as it already did for ai 7’s loadBuiltinModule; without it a Worker bundle built on ai 6 failed with “Node builtins leaked” (found by the new ai6 matrix entries).
  • isAgentEvent() is now exhaustive (the runtime type list is a Record<AgentEventType, true>, so the compiler rejects a missing type). It had no agent.drift, so remote UI clients (parseEventStream(), the React, Vue and Svelte bindings) silently dropped that event.
  • A remote sub-agent’s token usage is added to the lead’s result.usage. It was dropped, so budgets and cost reports undercounted delegation to a remoteAgent(). The lead adds what the remote agent reports on its run.done event to its totals, to usage.delegated and to byModel['remote:<name>'], which keeps the remote’s own costUsd (the lead’s costUsd is undefined when the remote sends none). A remote run that pauses for an approval adds what it spent up to the pause, and the continuation adds only what it spent after it; background remote tasks roll up the same way. A deployment that sends no usage adds nothing. RemoteRunOptions has a new optional onUsage(usage) callback; RemoteSubagent.run() still returns Promise<string>, so hand-written ones compile unchanged. See docs/sub-agents.md#remote-sub-agents.
  • lousho studio finds the Agent Forge build that ships inside the installed package when it is run from a project that does not have apps/agent-forge (it used to fail with “could not find apps/agent-forge” everywhere except the SDK repo). A project’s own apps/agent-forge still wins, and .lousho/ is still created in the directory you ran it from. --dev from an installed package still needs the TypeScript source and says so.
  • Documentation corrections: install commands, CLI command lists, optional peers, durable execution and compaction descriptions, the Status section, reasoning and file-part notes in the providers guide, and the KVStore note in the deployment guide now match the code. Ticket ids are gone from user-facing prose.

Tests

  • Two more load-sensitive tests fixed. SandboxShell.test.ts “passes only set values and allowed host names, never planted secrets” starts two real node -e processes and timed out at the 5 s default in 1 of 20 parallel runs; it has a 30 s timeout now (pure slowness, no race: it passes in under a second alone). backgroundSubagents.test.ts “reports a sub-agent paused for approval as awaiting-approval” waited a fixed 10 ms for the child’s pause and failed in 9 of 20 parallel runs with the task still running; the lead now asks agent_status again until the task has left running.
  • http.test.ts “rejects near the configured timeout” no longer compares real elapsed time to a real timeout (flaky under load, #324): it drives the request timer with a fake clock and checks the request is still pending at 499 ms, rejects with “timed out after 500ms” at 500 ms, and that the connection is closed.
  • src/tools/workspace/checkpoints.node.test.ts “rewinds three turns” has a 30 s timeout: it takes well under a second alone, but timed out at the 5 s default when eight copies of the suite ran at once. The rewind itself is correct; every failure was the timeout.
  • Live-model cassettes recorded: real gpt-4o-mini runs through OpenRouter are now replayed in CI with no key, for the coding agent in the docs, the Telegram, GitHub and Teams channels, plan mode, web_fetch, streaming send(), the guardrail starter set, fromAiSdk() and PDF/PNG file parts, plus a recorded lousho traces fixture. The live files that never ran (sendStreams, guardrailStarterSet, fileTraceExporter, remoteUsage) were missing the import '../providers' that registers OpenRouter; fixed. New live tests (skipped without a key): ai 6 through OpenRouter and aiSdkEmbedder() over OpenRouter embeddings.
  • pack-smoke allows a 16 MiB unpacked tarball (was 14 MiB): main was 45 KB under the old cap and permission modes went over it; see #316 for shrinking the package instead.
  • Sandbox egress and the credential broker are tested against a real Docker Engine: a new CI workflow, “Docker Engine” (.github/workflows/docker.yml, on pull requests touching the sandbox, broker or docker deploy adapter, on demand and weekly), runs npm run test:docker on GitHub’s ubuntu-latest runner (rootful Engine 28.0.4). src/security/sandboxEgress.docker.test.ts checks nine cases of SubprocessSandbox({ network: { allow }, broker }) with curlimages/curl: an allowed HTTPS host answers through the broker, another host gets a 403, bypassing the proxy and raw IPs have no route, outside names do not resolve, the broker injects a credential the container never sees, a container outside the internal network cannot use the gateway listener, an aborted run and close() leave no container or network, and a reused non-internal network is refused. The docker deploy image test (/health and /chat) moved to src/deploy/adapters/docker.docker.test.ts and runs in the same job; it was skipped in CI before and passes there. No product defect was found. *.docker.test.ts files are excluded from npm test and npm run test:coverage; they skip without a daemon unless LOUSHO_DOCKER_TESTS=1 is set (the workflow sets it), which makes a missing daemon fail. docs/workspace-tools.md says what the job checks; CONTRIBUTING.md mentions npm run test:docker.
  • src/execution/principal.test.ts and principal.test-d.ts: the principal in tools (send, stream, session and channel turns), policies, rules, hooks and sub-agents (local, background, remote), pause and resume with another approver, a restart, a crash resume on an on-disk SqliteStore, old checkpoints and snapshots, forks, the approvals route and channel clicks; frozen in strict mode; absent from events and spans.
  • Test files can be type-checked: npm run typecheck:tests runs tsc over src/ including every *.test.ts through the new tsconfig.tests.json, and the test files under src/execution, src/context, src/session, src/subagents, src/acp and src/testing now pass it. The check is not in CI yet. One type change: textOf() also accepts a message or content whose parts are readonly, such as a mockModel request snapshot.

Docs

  • The vendor/ model prefix note: every docs page whose snippets hardcode a provider/model string now says the prefix chooses the provider and that with OpenRouter the id is openrouter/<vendor>/<model> (e.g. openrouter/openai/gpt-4o-mini), so createAgent() does not throw LOUSHO_PROVIDER_MISSING_API_KEY when only OPENROUTER_API_KEY is set. Stale model ids refreshed: anthropic/claude-3-5-haiku-latest examples are now anthropic/claude-haiku-4-5, 'anthropic/claude-3-5-sonnet-latest' in errors.md is 'anthropic/claude-sonnet-4-5', google('gemini-2.0-flash') is google('gemini-2.5-flash') and the OpenRouter fallback example uses openrouter/meta-llama/llama-3.3-70b-instruct. (anthropic/claude-3-5-sonnet-latest stays where it documents the ANTHROPIC_API_KEY env default, which is still that id in src/providers/providerSpec.ts.)
  • Corrections in Errors, Troubleshooting and Testing: not every intentional error is an SDKError (the named Error subclasses — PropagatingToolError, CassetteMismatchError, CronExpressionError, DecryptionError — carry no code); the Find a code by area table now lists the Auth section and every code that has one; LOUSHO_CASSETTE_INVALID no longer claims to cover request mismatches (that is CassetteMismatchError), and its example uses webhookChannel() rather than a webhookTrigger() that does not exist; createAgent()’s default retry is documented as applying only to model strings and env-resolved models, not a provider instance; the file-parts entry now matches providers.md (PDFs and text/plain do reach providers on ai 6/7); connectMcp().status() lists 'needs-auth'; the mockModel usage default is “none reported” (the run estimates it) rather than zero; and the request-assertion snippet notes where temperature comes from, since createAgent() has no temperature option.
  • Stream events gains the missing agent.drift row (emitted on a resume under onAgentDrift: 'warn', before the continuation’s first step) and the fields the table understated: executedBy: 'provider' on tool.start / tool.done / tool.error (hosted tools), replacedByHook on tool.done, hook on permission.decision, trigger: 'manual' on compaction.start / compaction.done, and the full usage shape (inputTokens / outputTokens, estimated, costUsd, and modelCalls / hostedToolCalls on run.done). The ordering guarantees now say that a streamed approval continuation reports agent.drift and the decided call’s tool.start / tool.done before its first step.start, so those events fall outside a step. Runs uses the canonical event names tool.start / tool.done / run.done instead of the deprecated tool-call / tool-result / finish, and Testing no longer claims a mockModel turn without usage reports zeros (it reports none).
  • Long-tail corrections across the guides: lousho eval --config, lousho init’s InitUsageError and -y, .cts among the dev-server module extensions and streamed approval continuations in docs/cli.md; lousho build --target=... (not lousho deploy) and the public createRouteHandler().handler (not the internal serveFetch()) in docs/sub-agents.md; description as a createAgent() option and createDeployedServer() as build-internal in docs/agent-directories.md, docs/channels.md and docs/schedules.md; approval continuations on Workers emit tool.start / tool.done, deploy-runtime-worker is bundler-internal and handleScheduled needs a store in docs/cloudflare-workers.md; schedule-<name> sessions, checkpoint-history/ and the late-appearing approvals/ directory in docs/schedules.md and docs/sessions.md; saveAttachment/readAttachment signatures in docs/utilities.md; 256-bit OAuth state in docs/oauth.md; the recall_<name> description’s <name> in docs/memory.md; ctx.sessionId in docs/tools.md; the throw flow node in docs/flows.md; the triggers spec field in docs/configuration.md; principal in a permission rule’s when in docs/approvals.md; the 'not-a-file' rewind skip and NodeWorkspace’s required root in docs/workspace-tools.md; a built-in channel’s name setting its route in docs/channels.md; the completed() ‘max-steps’ message in docs/evals.md; formatUsage’s $0.0000 in docs/models-and-cost.md; the completed registry static-check list and the leading letter/digit name rule in docs/registry.md; exporter, captureContent and redactContent as createAgent() options in docs/migrating-to-create-agent.md; connectMcp().tools as a Record that combines with array tools in docs/mcp.md; HookRegistry.size() as a method in docs/hooks.md; *.example.com matching subdomains only in docs/tools.md, docs/workspace-tools.md and docs/registry.md; resumeAfterApproval() named as an export, not an executor method, and the fork divergedAt comment corrected in docs/durable-execution.md.
  • New page, Permission modes: the modes and their table, which tools are read-only, the editsFiles marker, the order of evaluation, switching, the audit log, sub-agents and resume. Approvals “Permission policies” links to it; Tools, Stream events and Sub-agents (“What a sub-agent inherits”) gained a row each.
  • New page, Route auth and principals: the ordered list and its three outcomes, each helper, 401 / 403 / WWW-Authenticate, which helpers run where (Node, Workers, edge), createRouteHandler, the node server and auth.ts, reading the principal in the run, and security notes (no session ownership check; basic() only over HTTPS). docs/errors.md gains a ## Auth section at the end (LOUSHO_AUTH_CONFIG_INVALID). One-paragraph links from deployment.md (### Auth), nextjs.md (## Routes), memory.md (## Scopes), agent-directories.md (layout and deploy), api-overview.md and a “Route auth” row in the cloudflare-workers.md limits table; no heading of an existing page changed.
  • New page, Cloudflare Workers: a table of what the Worker target supports and what it does not comes first, then build and deploy, bindings, sessions, checkpoints and approvals in KV, scheduled runs, consistency, and bundle size and Node builtins. The Worker sections moved out of docs/deployment.md unchanged (Bindings, sessions and the API on Workers, Cron triggers and handleScheduled and Durable execution (pause/resume) on Workers are gone from it); deployment.md keeps a short cloudflare-worker summary that links to the page. Links to deployment.md#cron-triggers-and-handlescheduled moved to cloudflare-workers.md#scheduled-runs.
  • Two dead heading links fixed: docs/executor-api.md now links to tools.md#advanced-toolregistry, and docs/troubleshooting.md links to mcp.md#use-mcp-servers-in-an-agent (the configuration anchor moved with the MCP section). No other link in docs/ or the README points to a missing heading. docs/approvals.md lists fileStore(dir) among the approval stores.
  • Long pages split; text moved unchanged. New pages: Runs, Models and cost, Stream events, Queued input and steering. Moved anchors (old to new): api-overview.md#finish-reasons, #cancellation and #parallel-tool-calls to runs.md (same anchors); api-overview.md#models-tokens-and-cost to models-and-cost.md#models-and-the-price-table; api-overview.md#usage-and-cost-of-a-run to models-and-cost.md#usage-and-cost-of-a-run; api-overview.md#flow-expressions to flows.md#flow-expressions; api-overview.md#todo-tools to tools.md#todo-tools; api-overview.md#tool-errors to tools.md#errors; api-overview.md#context-compaction to compaction.md; streaming.md#event-schema-version-1, #ordering-guarantees, #typescript and #versioning to stream-events.md (same anchors); streaming.md#queued-input and #steering to queue-and-steer.md (same anchors); the AgentExecutor.execute() options table of configuration.md to executor-api.md#options-of-agentexecutorexecute. The error codes page gained a “Find a code by area” table; its headings are unchanged.
  • The API overview, providers, structured output, tools, tracing, guardrails and testing guides teach createAgent() first: usage and multimodal examples use it, the testing tool example uses defineTool(), and every executor, AgentBuilder or ToolRegistry snippet sits under an “Advanced” heading that links to the executor API. They say that createAgent() does not take exporter, captureContent or sandbox yet.
  • New page, Triggers: the @lousho/build-ai-agent/triggers adapters, a table that says when to use triggers, channels or schedules, the TriggerAdapter interface (with a custom adapter and TriggerRegistry), and the webhook, Slack and cron sections that moved from the API overview, unchanged. The API overview now points to it; links to api-overview.md#triggers, #webhook-authentication and #slack-request-signatures moved to triggers.md. The missing-auth warning of WebhookTriggerAdapter and the missing-signingSecret warning of SlackTriggerAdapter now link to docs/triggers.md.
  • New page docs/migrating-to-create-agent.md: from AgentBuilder, AgentExecutor, ToolRegistry and resumeAfterApproval() to createAgent(), with a before-and-after example, a mapping table, the ExecuteOptions that createAgent() does not take yet (with alternatives), the behavior differences and a step-by-step checklist. Linked from docs/executor-api.md and the README docs table.
  • New page, Hooks: the four hook points, the outcomes of a preToolCall / postToolCall hook, four type-checked recipes (deny a tool, add a default argument, redact a result, inject context), ordering, and HookRegistry. The HookRegistry bullet and the ### Hook outcomes section moved there from the API overview, which now points to it; links to api-overview.md#hook-outcomes moved to hooks.md#hook-outcomes.
  • Approvals, sessions, streaming, sub-agents, compaction and skills guides show createAgent() first. Executor snippets (AgentExecutor, resumeAfterApproval, streamResumeAfterApproval, InputQueue, HookRegistry) moved under headings named “Advanced: the executor API” (links to docs/executor-api.md); approvals and streaming renamed a section to that name. createAgent({ hooks: [createCompactionHook(...)] }) is the compaction example. Removed a statement from the sub-agents guide that createAgent() takes no approvalStore (it does, and agent.approvals resolves sub-agent pauses).
  • Stale statements removed: ticket ids in the Agent Forge page, the “removed next minor” promise on AgentType in the API overview, and the installation note that read as if every user needs Node 22.19 for the http tool (it comes from the undici@8 dependency, which is loaded only for validateSSL: false requests). The ProposedAction doc comment no longer refers to an unlanded ticket.
  • New page docs/mcp.md, “MCP (Model Context Protocol)”: using MCP servers in an agent, connectMcp(), approval for MCP tools, loadMcpTools(), serving an agent with serveMcp() and lousho mcp, and a Limits list. These sections moved out of docs/configuration.md, which keeps the mcpServers spec field and links to the new page; links from approvals, CLI, tools, API overview and the README now point to mcp.md.
  • docs/durable-execution.md and docs/workspace-tools.md lead with createAgent() (send() with a sessionId, agent.resume(), agent.approvals.resolve(), agent.fork()) instead of AgentExecutor. The executor snippets (execute() with a checkpointStore, resumeAfterApproval(), AgentExecutor.fork(), the ToolRegistry setup) moved under “Advanced: the executor API”. In durable-execution the heading “What happens when you call execute() again with the same sessionId” is now “What happens when you send again with the same sessionId”.
  • New page docs/troubleshooting.md: start from the symptom (setup, runs that end without an answer, tools, providers, sandbox and MCP), with cause, fix and a link for each. README docs table, docs/installation.md and docs/errors.md link to it.
  • New guide, Build a coding agent: a terminal coding agent in six steps (workspace tools confined to the project, approval before writes and risky commands, a streamed UI that handles the approval pause, a session for follow-up questions, offline tests with MemoryWorkspace and mockModel), with an offline test of the same agent (docs/buildACodingAgent.test.ts; its replay of a recorded real-model run is skipped until the cassette docs/__cassettes__/build-a-coding-agent.json is recorded).
  • The Quick Start is rewritten around createAgent(): hello world, a tool, streaming, a session, an approval, an offline test with mockModel, a custom provider and spec files, each runnable with no API key (the first excepted). The AgentBuilder + AgentExecutor section moved to a new page, docs/executor-api.md (with the ToolRegistry note); the Quick Start no longer shows either API.
  • create-lousho-agent has a README (its npm page was empty) and license, homepage and repository fields; they appear on npm with its next release. lousho init --help no longer says --sdk-path is needed until the package is on npm.
  • docs/auth.md gains a section at its end, ## Principals in tools and approvals (with ### In a tool, ### Approval policies and permission rules, ### Who approved, ### Pauses, crashes and forks, ### Sub-agents, ### What is stored and logged); its “Reading the principal in the run” and “Security notes” text is updated. One-sentence links, no new headings: docs/approvals.md (needsApproval context, approve), docs/tools.md (ctx.principal and ctx.approval rows), docs/permission-modes.md (the audit log) and docs/channels.md (approvers).
  • UI and server examples corrected: docs/ai-sdk-ui.md’s client snippet used useChat({ api: '/api/chat' }), the ai 4 signature, which is invalid for the documented ai 6/7 combos — it now uses useChat({ transport: new DefaultChatTransport({ api }) }) and a note says which ai majors are supported (ai 4 keeps useChat({ api }) and returns input / handleInputChange / handleSubmit; ai 5 is not in the peer range). docs/nextjs.md’s useChat snippet has the same version note. The route handlers of ai-sdk-ui.md and nextjs.md opened agent.session({ id }) per request with no store, so a second turn forgot the first: both now pass store: memoryStore() and say to use a durable store on serverless; docs/react.md’s server section says the same for a per-request session. The data-lousho-approval part no longer reads as if kind / question only mark an ask_question: a tool waiting on an OAuth sign-in carries kind: 'sign-in' and signIn: { provider, displayName?, url }; docs/react.md’s pendingApproval row says the same.

[1.0.0-alpha.8] - 2026-10-02

Changed

  • No any left in the SDK’s types: npm run lint now fails on any ESLint warning, and no-explicit-any, no-unused-vars and ban-ts-comment are errors. Runtime behavior is unchanged; some exported types are stricter, which can be a compile error where code read an any value without checking it. What changed, and how to migrate:
    • Values the SDK cannot know are unknown (narrow them, or cast to the shape you expect): FlowExecutionResult.output and .variables, FlowExecutionContext.variables / session / memory, GenerateResult.rawResponse, StreamChunk.toolResult.result, extra keys of LLMProviderConfig, AgentConfig.expectedResult / events / metadata, AgentExecutionResult.result, ResultData.result, SessionData.data, JiraTicket.customFields, the extra keys of formatZodError()’s result, ToolConfiguration.options, ToolSetting.options, FlowToolSetting.options, ToolNode.toolOptions, UIComponentNode.componentProps, FlowChunkEvent.issues / input / toolResults[].args / componentProps, and ToolDefinition.function.parameters.
    • FlowExecutionEvent is a union discriminated on type, with data typed per event type (new FlowExecutionEventOf<T> and FlowExecutionEventDataMap): check event.type before reading event.data (if (event.type === 'tool-call') event.data?.tool).
    • AgentConfig.settings (and AgentBuilder.setSettings()) is the new AgentSettings ({ model?: string; [key: string]: unknown }).
    • StorageService.readPlainJSONAttachment<T>() (and IStorageService’s) defaults T to unknown: pass the type you stored, readPlainJSONAttachment<MyRecord>(key).
    • OpenRouterProvider.getModelInfo() returns the new OpenRouterModel ({ id: string; [key: string]: unknown }), null or undefined.
    • FlowBuilder.addAgent() / setAgents() take FlowAgentDefinition; injectVariables() and applyInputTransformation() take a FlowDefinitionNode (injectVariables() returns the type it was given); validateFlowInput() takes Record<string, unknown>; validateAgentTools() takes Record<string, { tool?: unknown }>; createDynamicZodSchemaForInputs() returns z.ZodObject<Record<string, z.ZodTypeAny>>.
    • Still accepted as before: needsApproval predicates typed for a tool’s own arguments, any argument to formatAxiosError() and hasRequiredKeys(), and anything as writePlainJSONAttachment() data. The deprecated ExecutionEvent keeps toolResult.result: any.
  • Eval cassettes hook in at the model boundary: lousho eval --record / --replay / --drift no longer reassigns AgentExecutor.execute at runtime. The run loop routes every model call through a small provider-interception seam (setProviderInterceptor() / interceptProvider() in src/providers/interception.ts; a no-op unless an interceptor is installed), and the eval runner installs one that answers with the per-case recordReplay() wrapper. Cassette files, keying, --drift output and JUnit reports are unchanged, so existing cassettes keep replaying. Streamed runs and sub-agents inside an eval case are covered by tests.
  • More errors carry SDK error codes: the plain Errors thrown by src/execution (historyLimit, toolConcurrency, a second iteration of an AgentRun), the tool registry, the built-in tools, serveMcp(), NodeWorkspace and the lousho init / studio / chat helpers are now SDKErrors with an existing code (LOUSHO_CONFIG_INVALID via ConfigurationError, LOUSHO_RUN_ALREADY_ITERATED, LOUSHO_APPROVAL_NOT_FOUND, LOUSHO_PROVIDER_UNKNOWN, LOUSHO_TOOL_EXECUTION_FAILED). Messages are unchanged; error.code, error.hint and a [code] hint (docs) line (not on the built-in tools’ run-time failures, whose message is the model-visible tool result) are added. Code that matched error.constructor === Error or error.name === 'Error' needs error instanceof SDKError.
  • The remaining user-reachable plain Errors carry SDK error codes: agent directories, flows, memory, skills, storage (SQLite), triggers, deploy, evals, record/replay cassettes, defineTool(), sub-agent options, channels, sandbox/credential-broker options and the llm registry now throw an SDKError (message text unchanged, plus the [code] hint (docs) line, except for tool results and messages tests assert, which stay as written). New codes: LOUSHO_TOOL_ARGS_INVALID (what ToolArgumentsValidationError carries now), LOUSHO_AGENT_DIR_INVALID, LOUSHO_SKILL_INVALID, LOUSHO_FLOW_INVALID, LOUSHO_STORAGE_FAILED, LOUSHO_TRIGGER_INVALID, LOUSHO_DEPLOY_FAILED, LOUSHO_EVALS_INVALID, LOUSHO_TEST_FAILED, LOUSHO_CASSETTE_INVALID and LOUSHO_CHANNEL_REQUEST_FAILED, all in docs/errors.md. Code that matched these errors by error.constructor === Error or error.name === 'Error' must check instanceof SDKError / error.code instead. ToolExecutionError takes an optional fourth code argument. A new test (src/utils/plainErrors.test.ts) fails when new SDK code throws a plain Error; the 5 that remain are listed there with the reason.
  • The last two allowlisted plain Errors are SDKErrors: OpenRouter’s model-catalog fetch (LOUSHO_PROVIDER_REQUEST_FAILED; getModels() / getModelInfo() still catch it and fall back) and the UI runner’s failed POST to a remote agent (LOUSHO_REMOTE_REQUEST_FAILED, as used by useLoushoAgent() and the Vue/Svelte bindings). Both keep their message text exactly (no help line appended), so the UI’s error event shows the same message, now with name: 'SDKError' instead of 'Error'. SDKError itself moved to src/utils/sdkError.ts (re-exported from the same places as before) so the browser entries can throw it without importing ai. The allowlist in src/utils/plainErrors.test.ts is down to the 3 intended sites.
  • zod 3 or zod 4: the zod peer is now ^3.25.76 || ^4.0.0. Schemas of either major (including zod/v4 on zod 3.25 and zod/v3 on zod 4) work in defineTool({ input }), structured output and argument validation: zod 4 schemas are sent to the model as z.toJSONSchema output (also to ai v4, whose own converter only reads zod 3), zod 3 schemas through the ai SDK’s converter as before, and both are parsed with their own safeParse. defineTool also takes any Standard Schema that exposes ~standard.jsonSchema; tool arguments validate with any Standard Schema’s ~standard.validate. The SDK’s own schemas (AgentSpec, registry documents, built-in tools, MCP tool conversion) run on whichever major is installed, and issue messages read the same on both (zod 4’s Invalid input: expected string, received undefined is reported as Required). lousho init keeps zod 3 for the ai 4 scaffold (Ollama), whose packages peer on zod 3. Ollama on ai 6/7 (ollama-ai-provider-v2, which peers on zod 4) is no longer blocked by the SDK’s zod peer. CI runs the type check, build and suite on zod 4 too. Migration: DefineToolOptions, DefinedTool and ToolDescriptor.inputSchema are typed with the new exported StandardSchemaV1 (parsed type: InferSchemaOutput) instead of zod 3’s ZodTypeAny; code that called zod methods on descriptor.inputSchema needs a cast. The task tool’s error for an unknown sub-agent now reads Unknown sub-agent "x". Expected one of: 'a', 'b'. createAgent({ output }) is still typed with the installed major’s ZodType.
  • Slack and Discord approvals are starter-only by default (behaviour change): without approvers, only the user who started the turn (the Slack message author, the Discord command’s user) can approve or deny a tool call; before, anyone who could see the message could. Migration: pass approvers: () => true for the old behaviour, or a list of user ids / a function for a team. Approval button values (Slack) and custom ids (Discord) now carry the starter (<starter>:<approval id>), so buttons posted before the upgrade carry no starter and only an approvers list or function can approve them.
  • Package entries share one copy of each module: tsup code splitting is on, so @lousho/build-ai-agent, /hooks, /tools, /mcp and the rest import shared chunks instead of each bundling their own copy. HookRegistry, SDKError and module-level registries are now the same object across entries (they were duplicated, so instanceof and singletons could disagree), and dist/ shrinks from about 25 MB to 8.8 MB. instanceof SDKError and instanceof HookRegistry also hold between the ESM and CJS copies a mixed-format process loads (a Symbol.for brand). See Installation.
  • A crash resume of a dynamic agent restores the run’s config: checkpoints now carry runConfig (the ctx and model the run was resolved with, as approval snapshots already did), and agent.resume(id) / session.resume() / send(…, { sessionId }) on an unfinished run use the saved model and re-resolve tools and instructions with the saved ctx, instead of input: [] and no metadata; a model chosen from metadata no longer changes mid-run. Static agents are unchanged.
  • Resumed approved calls must run with the approved arguments (behaviour change): after the pre-tool hooks ran on the resumed call, the arguments are compared (deep, key order ignored) with the approved ones whether a hook returned { input } or changed ctx.args in place, and a difference is refused with the existing kind: 'validation' error (“approved with different input”); a hook that rebuilds the same arguments in another key order is no longer refused. Migration: a hook that rewrites arguments (a redactor, a normalizer) must also run on the original run, so the approval record already holds the rewritten input; a hook added only after the pause, that changes the arguments, now refuses the call. A call whose tool no longer exists after an approval (snapshots with an agent fingerprint) now rejects with LOUSHO_RESUME_TOOL_MISSING instead of giving the model a not-found tool result; older snapshots keep the old behaviour.
  • Cancelled and settled tool calls use the shared tool-error shape: a tool call cancelled before it ran (the run was aborted or steered) and a sub-agent call dropped because the lead run was already pausing for another approval now reach the model as { error: 'ToolNotRunError', toolName, message, kind: 'not-run' } with the transcript message flagged isError. Before, the result was { error: '<text>' } (and the cancelled one was not flagged isError); the text is now under message.
  • A permissions allow (or ask) rule no longer overrides a tool’s own needsApproval deny (behaviour change): the tool’s needsApproval is now called for those calls too, and its 'deny' / { deny } denies the call; an allow still skips the tool’s ask. A deny rule still wins without calling needsApproval. Migration: a tool that should run under an allow rule must not deny it from needsApproval. See docs/approvals.md.
  • agent.session() passes the agent’s createAgent({ compaction }) to the session, so session.compact() uses the agent’s strategy and sizes unless agent.session({ compaction }) sets its own.
  • The cloudflare-worker target builds with ai v7 installed. With ai v7 (@ai-sdk/openai/@ai-sdk/anthropic v4), lousho build --target=cloudflare-worker failed with “Node builtins leaked” (node:module, node:dns, node:diagnostics_channel, node:async_hooks). Those are not imports: ai v7 and @ai-sdk/provider-utils v5 probe them at run time through process.getBuiltinModule(), only when running on Node, so the bundle never loads them on Workers. The build’s leak check now exempts exactly those four ids, and only as the argument of a getBuiltinModule/loadBuiltinModule call; any other node: reference still fails the build. No nodejs_compat flag is needed. The 16 Worker bundle tests that were skipped on ai v7 now run on both majors. The bundle is about 3.4 MB raw on v7 (1.7 MB on v4), well under the 64 MiB limit.
  • BREAKING: sandboxed and workspace commands get an allowlisted environment. Commands run by NodeWorkspace.exec() and SandboxShell no longer see the host’s process.env, so env/printenv cannot reveal API keys or cloud credentials. They get a small base a shell needs (PATH, HOME/USERPROFILE, TMP/TEMP/TMPDIR, LANG, LC_*, TERM, plus SystemRoot, SystemDrive, ComSpec, PATHEXT, WINDIR on Windows) and what you add. A container (SubprocessSandbox) gets only what you add, never the host env. SandboxShell gains env and inheritEnv options; NodeWorkspaceOptions.inheritEnv and SandboxShellOptions.inheritEnv accept true; SandboxRunOptions gains inheritEnv (NoopSandbox keeps passing the host env unless it is false, which SandboxShell sets). SubprocessSandbox gains network: 'none' | 'default' | { allow: string[] } (default 'none', as before); { allow } is validated and kept on sandbox.network but runs with no network until the egress proxy enforces it (fail closed). Migration: pass what commands need, either values (env: { NODE_ENV: 'test' }) or host names to copy (inheritEnv: ['CI', 'NODE_OPTIONS']); to restore the old behavior, pass inheritEnv: true. See docs/workspace-tools.md.
  • Internal: the test suite runs with ai v7 installed as ai. A test helper (src/providers/aiMajor.testkit.ts: installedAiMajor, describeOnAiV4, itOnAiV4) reads the installed major; tests whose behavior is the same on both majors are made major-agnostic, the 66 that only make sense on v4 (v4 message and call shapes, MockLanguageModelV1) or on a Worker bundle that still leaks node: built-ins on v7 are skipped there. The typecheck-ai7 CI job now also builds and runs npx vitest run. Test and CI change only; no product change.
  • Internal: the SDK source now type-checks against ai v7 (with @ai-sdk/openai/@ai-sdk/anthropic v4) as well as ai v4. AiSdkProvider builds its ai v4 request with SDK-owned structural types instead of the v4-only CoreMessage/CoreAssistantMessage/CoreToolMessage/Output types and no longer calls ai’s tool() (an identity function on v4); the legacy .tool that defineTool()/toolDescriptorFromSchema() hand-build is cast once at that boundary. No runtime change on v4. A new CI job runs tsc --noEmit with ai@7 installed. The ai/@ai-sdk/* peer ranges are unchanged for now.
  • MCP tools without readOnlyHint now ask for approval by default (BREAKING for MCP users): loadMcpTools(), connectMcp() and createAgent({ mcpServers }) set needsApproval from each tool’s MCP annotations: readOnlyHint: true runs, destructiveHint true or absent (the MCP spec default) asks, destructiveHint: false runs. Choose per server with the new approval: 'annotations' | 'always' | 'never' | ({ name, annotations }) => boolean (loadMcpTools(client, name, { approval }), connectMcp() server entries, createAgent({ mcpServers }) and AgentSpec.mcpServers, which validates it; a spec file takes the three strings). The descriptor keeps the raw annotations on the new ToolDescriptor.metadata?.mcp.annotations (types McpToolAnnotations, ToolMetadata, McpApproval) and uses the annotation title as displayName. Migration: pass approval: 'never' to restore the old behaviour (every MCP tool runs without asking). createAgent() agents pause with finishReason: 'awaiting-approval', while a bare AgentExecutor without an approvalStore now throws for such tools. See docs/configuration.md#mcp-tool-approval-approval.
  • Small built-in tools are defined with defineTool (not breaking): currentDateTool, dayNameTool, createEmailTool(), createHttpTool(), createSlackTool(), createDelegateTool() and the descriptors loadMcpTools() builds no longer call ai’s tool(). They now carry canonical inputSchema / execute (the legacy .tool stays), and the built-ins have the tool names current_date, day_name, send_email, http_request, slack_alert and delegate_to_<agent>. Descriptions, schemas, approval and sandbox behaviour and the factory signatures are unchanged. MCP descriptors are built with the new internal toolDescriptorFromSchema(), which (unlike defineTool) accepts any server-provided name or empty description. routeFetchThroughSandbox() reads the canonical execute first.
  • GitHub and Jira tools are defined with defineTool (not breaking): the 28 createGitHubTools() tools and the 20 createJiraTools() tools no longer call ai’s tool(), so nothing under src/tools imports ai any more. They now carry canonical inputSchema / execute (the legacy .tool stays). Tool names, descriptions, schemas, the sandbox flags and the factory signatures are unchanged. The GitHub out-of-scope tools (branch/file writes, code search, issue CRUD, merge) are disabled through the canonical execute as well as tool.execute, so calling one still throws “out of scope” before any HTTP request. JiraTools.register() now also routes tools registered with defineTool through the sandbox seam.
  • BREAKING (types only): Message.content is widened from string to string | ContentPart[]. Messages you build keep working unchanged, but code that reads message.content as a string (.length, .startsWith(), a template literal) no longer type-checks. Migration: read textOf(message) instead, or narrow with typeof message.content === 'string'. A custom LLMProvider that forwards content should handle the parts or send textOf(message).
  • The execute context is our own type (not breaking): the new exported ToolExecutionContext ({ toolCallId, messages: readonly Message[], abortSignal?, sessionId?, onDelegatedUsage? }, Message from @lousho/build-ai-agent) replaces the ai SDK’s ToolExecutionOptions as the type of the second argument of defineTool()’s execute, ToolDescriptor.execute, DefinedTool.execute and the third argument of sandboxExecute, and is what buildToolRunContext() returns; the public types no longer import ToolExecutionOptions from ai. A function typed for ai’s options that only reads toolCallId or abortSignal stays assignable. ToolRunContext is now a deprecated alias of the optional fields of ToolExecutionContext (it already existed with onDelegatedUsage and toolCallId). AgentExecutionOptions.messages is typed Message[] instead of the ai SDK’s CoreMessage[] (the field is unused by the SDK). The legacy ToolDescriptor.tool (ai v4 Tool) is unchanged. See docs/tools.md#execute-context.
  • BREAKING (small): SDKError.code values are now the LOUSHO_* codes: AGENT_EXECUTION_ERROR -> LOUSHO_AGENT_EXECUTION_FAILED, TOOL_EXECUTION_ERROR -> LOUSHO_TOOL_EXECUTION_FAILED, LLM_PROVIDER_ERROR -> LOUSHO_PROVIDER_REQUEST_FAILED, SESSION_AWAITING_APPROVAL -> LOUSHO_SESSION_AWAITING_APPROVAL, FLOW_EXECUTION_ERROR -> LOUSHO_FLOW_EXECUTION_FAILED, CONFIGURATION_ERROR -> LOUSHO_CONFIG_INVALID, VALIDATION_ERROR -> LOUSHO_VALIDATION_FAILED, TIMEOUT_ERROR -> LOUSHO_OPERATION_TIMEOUT, RATE_LIMIT_ERROR -> LOUSHO_PROVIDER_RATE_LIMITED; code is no longer optional (new SDKError(message) gets LOUSHO_GENERIC_ERROR). No class was renamed. The messages of SDKErrors other than ToolExecutionError, LLMProviderError, TimeoutError and RateLimitError gain a second line with the code, hint and docs link, and loadSpec() now rejects a spec whose top-level field is a likely typo of a spec field (LOUSHO_SPEC_UNKNOWN_FIELD; other unknown fields are still ignored). Migration: compare code against the new values (or use instanceof); match messages with toContain / a regex, or compare error.detail, instead of exact equality.
  • BREAKING (small): tool failures that did not go through the thrown-error path now use the shared shape, so error is an error name instead of a message. Before: an unknown tool or a missing registry gave { error: "Tool 'x' not found" } / { error: 'No tool registry available' }; a rejected approval gave { error: 'Tool execution was rejected by the reviewer', note }; a tool that threw after an approval gave { error: '<message>' }; a call left without a result on resume gave { error: 'Tool call was not run: ...' }. Now each is { error: '<ToolNotFoundError | ToolRejectedError | <thrown error name> | ToolNotRunError>', toolName, message: '<the old text>', kind, ... }. A tool approved but missing from the registry on resume used to reject resumeAfterApproval() with Tool 'x' not found in registry; it now resolves with a not-found error result. The sandbox guard throws SandboxRequiredError (same message, still an Error). Migration: read message instead of error when you want the text, and branch on kind. ToolArgumentsValidationError.toToolResult() now also returns kind: 'validation'.
  • Background sub-agents still running when the lead run ends are now cancelled instead of running to completion on their own; a lead run that pauses for approval cancels them too (the resumed run starts with none). Migration: to keep them, have the lead collect them with agent_await before its final answer, or set subagentOptions: { awaitBackgroundOnFinish: true }.
  • Heavy dependencies are optional peers: dockerode (Docker sandboxing, SubprocessSandbox), @modelcontextprotocol/sdk (serveMcp, lousho mcp, MCP clients) and prompts (the interactive questions of lousho init) moved from dependencies to peerDependencies, marked optional in peerDependenciesMeta. They were already loaded lazily; now a project that uses none of them does not install them. Using one without its package fails that call with MissingPeerDependencyError, which now also carries feature and names the exact command (for example npm install dockerode@^5.0.1). lousho doctor lists the three with what they enable (a missing dockerode fails the check when the agent spec uses a sandboxed tool), and its version lookup no longer returns undefined for packages whose exports map hides package.json. Migration: install the peer if you use Docker sandboxing (npm install dockerode), MCP (npm install @modelcontextprotocol/sdk), or interactive lousho init (npm install prompts; npm create lousho-agent already does, and lousho init --yes needs nothing). See docs/installation.md.
  • The http tool no longer loads undici for default requests: with TLS verification on (the default) it uses the runtime’s global fetch; undici (still a regular dependency) is loaded only for validateSSL: false, whose per-request TLS dispatcher the global fetch cannot express. yaml stays a dependency (agent specs and skills need a YAML parser).
  • Retries no longer stack: the built-in providers (OpenAIProvider, AnthropicProvider, OllamaProvider, OpenRouterProvider) now pass maxRetries to the ai SDK calls: config.maxRetries, or 2 (the ai SDK’s default, so behaviour is unchanged) when unset. createAgent() builds the providers it resolves from strings with maxRetries: 0 and retries in its withRetry() wrapper instead, so retries happen in one place (at most 3 calls by default, as before) and each one is observable. If you wrap a built-in provider in withRetry() / resilientProvider() yourself, build it with maxRetries: 0; note that a maxRetries you already set in a provider config is now honoured by the ai SDK.
  • AgentType is optional and deprecated (not breaking): AgentBuilder.build() no longer requires setType() and AgentConfig.agentType is now optional (createAgent() and specToAgent() agents carry no type). AgentType, setType() and the agent-types registry/validators are marked @deprecated: they have no runtime effect and will be removed in the next minor; they stay exported for now. Drop your setType(...) calls.
  • BREAKING: encrypt() now generates a random salt per call instead of a hardcoded one. Ciphertext produced before this change cannot be decrypted with the new code and must be re-encrypted.
  • BREAKING: The mock repositories (MockAgentRepository, MockSessionRepository, MockResultRepository, MockMemoryRepository, MockAttachmentRepository — previously re-exported from src/data/mocks.ts via the package root/./data subpath; this package has no createMockRepositories factory) are no longer exported from the package root. Import them from @lousho/build-ai-agent/testing instead.
  • One session-API client behind remoteAgent() and remoteTarget(): both now share an internal client (src/server/sessionClient.ts) for POST <url>/chat, the SSE read, bearer-token scrubbing and the error mapping, and use one pair of codes, LOUSHO_REMOTE_REQUEST_FAILED and LOUSHO_REMOTE_UNAUTHORIZED. The unreleased LOUSHO_REMOTE_AGENT_FAILED is removed: a remoteAgent() failure now carries LOUSHO_REMOTE_REQUEST_FAILED (network, non-2xx, truncated stream, or a remote run that ends in an error, with “the remote run ended in an error” in the message) or LOUSHO_REMOTE_UNAUTHORIZED (401). No option or behavior of either function changed.

Added

  • Remote sub-agent approvals go through the lead run: a remoteAgent() task whose remote run pauses for a tool approval now pauses the lead run the way a local sub-agent does (it used to fail with LOUSHO_SESSION_AWAITING_APPROVAL): the lead’s pending approval (agent.approvals.list(), channel buttons, the dev chat, ACP permission requests) has the remote tool’s name and input and subagentPath: [<remote agent>], and a remote ask_question arrives as a question. Deciding it on the lead (resolve, streamResolve, answer) posts the decision to the remote POST <url>/chat/:sessionId/approvals/:id and the continuation’s final answer is the task result; a further pause pauses the lead again. The lead’s approval snapshot stores the remote session id, the remote approval id, the taskId and the agent name (never the token), so a fresh lead process on the same store can decide it. Failures while deciding (401, other non-2xx including the remote’s 404 for an approval no longer pending, network) are the task call’s structured tool error with LOUSHO_REMOTE_UNAUTHORIZED / LOUSHO_REMOTE_REQUEST_FAILED. A remote agent with an output schema now returns its object as JSON with the footer (the V4.2 shape), read from run.done’s object. RemoteSubagent.run() takes pausable and decision (type RemoteRunOptions); the internal session client gains resolveRemoteApproval() and SessionTurnSummary.object. Only a lead run without an approval store keeps the old LOUSHO_SESSION_AWAITING_APPROVAL error. See docs/sub-agents.md#remote-approvals.
  • Structured output for sessions and sub-agents, typed for either zod major: createAgent({ output }) and ExecuteOptions.output accept a zod 3 schema, a zod 4 schema (zod/v4 on zod 3.25, or zod 4) or a Standard Schema that can produce JSON Schema, and result.object is inferred from each without a cast (InferSchemaOutput, as defineTool). AgentSession is generic (AgentSession<TObject = unknown>): agent.session().send() and .stream() results carry the typed object. A sub-agent with its own output returns its validated object as JSON (then the taskId footer) as the task and agent_await result; its output-invalid finish is a structured tool error. Sub-agents do not inherit the lead’s output; remoteAgent() returns text only. The exported spec schemas (agentSpecSchema, …) are typed as SpecSchema<T> / SpecObjectSchema<T>, so the published schema-*.d.ts no longer depends on zod 3 generics (skipLibCheck: false projects on zod 4). The Ollama missing-peer note now says ollama-ai-provider-v2 needs zod 4 (npm install zod@^4.0.0). See docs/structured-output.md.
  • Publish readiness: npm run pack-smoke (scripts/pack-smoke.ts, a CI job) packs the SDK and create-lousho-agent, checks the tarball (no .env, tests or secret-looking strings; entry count and size caps), runs npm publish --dry-run for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every exports entry, a mock-model agent turn, the lousho bin (--help, doctor) and tsc with moduleResolution bundler and node16.
  • One event system: AgentEvent listeners for callers who do not iterate a run. createAgent({ onEvent: (event: AgentEvent) => void }) and the new ExecuteOptions.onAgentEvent (also taken by AgentExecutor.stream() and resumeAfterApproval()) are called synchronously with every AgentEvent of the run, on send() / execute() as on stream(), sub-agents’ events included: the same events in the same order as the stream yields (a non-streamed run generates each model step whole, so its text is one text.delta per step). A run with a listener also reports hook events, permission decisions, budgets and guardrails to it when it is not streamed. A non-streamed resumeAfterApproval() with a listener now reports the decided call (run.start, tool.start, tool.done) like a streamed one. See docs/streaming.md#listening-without-iterating.
  • Reasoning: new reasoning option on createAgent(), send() / stream() (per call, overriding the agent’s), ExecuteOptions and GenerateOptions: 'none' | 'minimal' | 'low' | 'medium' | 'high' or { effort?, budgetTokens?, summary?: 'auto' | 'none', force? } (types ReasoningOption, ReasoningEffort, ReasoningSettings). The built-in providers send it through providerOptions on ai 4.3 and 6/7: OpenAI reasoningEffort (+ reasoningSummary), Anthropic thinking: { type: 'enabled', budgetTokens } (effort table 1024 / 2048 / 8192 / 24576 tokens), Ollama think (ollama-ai-provider-v2 only; ignored with one warning on ai 4), and OpenRouter’s unified reasoning body field (effort or max_tokens). It is only sent to model families known to accept it (force: true overrides); 'none' sends nothing. New events reasoning.start, reasoning.delta (text) and reasoning.done (text, tokens?) in the AgentEvent union, emitted inside the step before its first text or tool call, from ai v4 reasoning parts and v6/v7 reasoning-start/delta/end; ExecutionResult.reasoning holds the run’s reasoning text and GenerateResult.reasoning a call’s blocks (new type ReasoningBlock); new stream chunk types reasoning-delta / reasoning-end (StreamChunk.reasoning). Reasoning is not written to the transcript as text; an assistant tool-call turn keeps Anthropic’s signed or redacted thinking blocks in the new Message.reasoning, which the Anthropic provider sends back unmodified (it survives checkpoints and resumes). The UI reducer keeps UIMessage.reasoning, toUIMessageStream() emits reasoning-start / reasoning-delta / reasoning-end, lousho acp sends agent_thought_chunk, lousho chat prints reasoning dimmed, and chat spans carry lousho.usage.reasoning_tokens. Cassettes record the reasoning chunks. See docs/reasoning.md.
  • Tools know their session: ToolExecutionContext.sessionId is now set whenever the run has one: AgentExecutor.execute({ sessionId }), send({ sessionId }), every agent.session() turn (the session id; a checkpointed turn’s own <id>.turn-<n>, as hooks see it), approval resumes (the paused run’s), and sub-agents (<parent session>/<task tool call id>). A session turn’s run now carries the session id even without a checkpoint store (no checkpoint is written), so hooks and the invoke_agent span’s conversation id see it too.
  • Hardened Slack and Discord channels: approvers (a list of platform user ids, or (user: { id, name?, roles? }, { toolName, input, sessionId }) => boolean | Promise<boolean>) says who may click Approve / Deny (a refused click gets an ephemeral “not allowed” and the approval stays pending); onError(error, { channel, stage, sessionId? }) on both channels, on mountChannels() and on defineChannel() receives failures after the acknowledgment (reply delivery, a failed turn, an approval continuation; default console.error with channel, stage, session and SDK error code, never a token) and a failed turn tells the user so; mountChannels({ onDecision }) reports who decided; parse gets a third ctx argument (ChannelContext: pending approval, session id, hasSession) and a { decision } may carry inbound and approver. Pending approvals now resolve from the click itself and the Slack ‘active thread’ check asks the session store, so both survive a restart. Slack: the clicked message is replaced with the outcome (buttons removed) and direct messages (message.im, scope im:history) are sessions keyed on the DM channel. See docs/channels.md.
  • Resumable sub-agent tasks: every task result ends with a taskId (the footer is now [sub-agent '<name>': N step(s), finish reason '<reason>', taskId 'task_1']; a remote one gains , taskId '...' too), and task takes optional taskId and mode: 'new' | 'resume' | 'fork' (default new without a taskId, resume with one). resume continues that sub-agent with its transcript and the new prompt as the next user turn; fork starts a new task (new taskId) from a copy of it and leaves the original alone. Conversations are kept per lead session in the agent’s store.sessions (new SubagentOptions.sessions, set by createAgent({ store })) for lead runs with a sessionId (checkpointed send() and session turns), under a key hashed from the lead session and the taskId, so they survive a restart and cannot be reached from another session; other runs keep them in memory for the run. Background tasks share the ids (a background task’s id is now task_<n> counted with the synchronous ones): a finished one can be resumed, a running one is refused with the new LOUSHO_SUBAGENT_TASK_BUSY; an unknown, foreign or other sub-agent’s id gets the new LOUSHO_SUBAGENT_TASK_NOT_FOUND, both as the structured tool error. An approval inside a resumed child pauses and resumes the lead as before (streamed or not), and a resumed child’s usage counts toward the lead like a fresh call. remoteAgent() tasks resumed by taskId continue in the same remote session (RemoteSubagent.run() takes sessionId and taskId); remote approvals are still not proxied, but a task whose remote run paused can be continued once the approval was decided on the remote agent. The model-facing task description and the sub-agents prompt block say how to continue a task. See docs/sub-agents.md#continuing-a-task.
  • Agent-directory and spec builds keep optional peers external, and the node server runs spec cron triggers: lousho build --target=node-server|docker leaves every optional peer of the SDK (read from its peerDependenciesMeta) out of the bundle, replacing the hand-kept dockerode / ollama-ai-provider-v2 list, so a build no longer needs peers the agent does not use; a spec’s { type: 'cron' } triggers now start on the built server (and are validated at build time), as on the Cloudflare Worker target. See Deployment.
  • Agent fingerprint on resume: every checkpoint and approval snapshot now carries agentFingerprint (new type AgentFingerprint: the model id, each tool’s name with a hash of its JSON input schema, a hash of the instructions, and a SHA-256 prefix over them, via Web Crypto; functions are ignored), and a resume compares it with the resuming agent’s before any model call or tool runs. New option onAgentDrift: 'warn' | 'error' | 'ignore' (type AgentDriftMode) on createAgent(), AgentExecutor.execute() and resumeAfterApproval(): 'warn' (default) emits the new agent.drift event (AgentDriftEvent: model?, toolsAdded, toolsRemoved, toolsChanged, instructions) and a console.warn, 'error' rejects with the new LOUSHO_AGENT_DRIFT and leaves the checkpoint (or the pending approval) untouched. A pending tool call whose tool no longer exists always rejects with the new LOUSHO_RESUME_TOOL_MISSING. Works for crash resume, session.resume() and approval resume, streamed or not; old checkpoints and snapshots have no fingerprint and resume unchecked. A sub-agent’s nested approval snapshot carries its own fingerprint, but only the top-level agent is compared. resumeAfterApproval()’s options take currentAgent (set by createAgent()) so instructions can be compared. See docs/durable-execution.md#resuming-with-a-changed-agent.
  • Docker sandbox network allowlists are enforced through the credential broker: new SubprocessSandbox({ network: { allow }, broker }) creates (or reuses, by networkName) an internal Docker network (Internal: true, label com.lousho.sandbox=egress), has the broker listen on its gateway address for that subnet only, and starts each container on it with HTTP_PROXY/HTTPS_PROXY pointing there, so the broker (allowlist: its rule hosts plus allow) is the container’s only route out. New sandbox.close() stops the listener and removes the network it created. New broker.listen({ host, clients, allow? }) adds a listener on another address that drops peers outside the clients subnet; the broker still listens on loopback only by default. Enforced on Docker Engine 25.0.5+ for Linux with the agent on the same host; Docker Desktop, rootless Docker, a remote daemon, a non-internal reused network and older Engines are refused with the new code LOUSHO_SANDBOX_EGRESS_UNSUPPORTED (no container is started). Without a broker, { allow } still means no network. See docs/workspace-tools.md.
  • The Docker sandbox honors cancellation: SubprocessSandbox.run() takes signal (SandboxRunOptions). When it aborts, the container is killed and force-removed (errors from an already stopped or removed container are ignored) and run() rejects with an AbortError, like NoopSandbox; an already-aborted signal starts no container; a timeout uses the same cleanup. SandboxShell passes the tool’s abort signal down, so a cancelled shell call stops its container (it used to run until the timeout) and reports aborted: true. See docs/workspace-tools.md.
  • Schedules on Cloudflare Workers: the cloudflare-worker target writes the spec’s { type: 'cron', cron, input, name?, timezone? } triggers (deduplicated) to wrangler.toml as [triggers] crons = [...], and the generated Worker exports scheduled(controller, env, ctx), which runs every trigger whose expression equals controller.cron as an agent turn inside ctx.waitUntil(), in session schedule:<name> (visible in the KV store when bound). A failing trigger is logged with console.error (name and error code) and never stops the others. The build fails with LOUSHO_SCHEDULE_INVALID naming the trigger for what Cloudflare would not fire: a timezone (crons are UTC), a seconds field or @daily shortcut, a numeric day-of-week (Cloudflare counts 1 as Sunday). New handleScheduled(agent, schedules, controller, ctx) (root and deploy-runtime-worker) wires defineSchedule schedules to a hand-written Worker’s scheduled(). startSchedules shares its fire step with it. See docs/schedules.md#on-cloudflare-workers.
  • ai v6 and v7 as peers: peerDependencies now accept ai ^4.3.19 || ^6.0.0 || ^7.0.0 and @ai-sdk/openai / @ai-sdk/anthropic ^0.0.42 || ^1.0.0 || ^3.0.0 || ^4.0.0 (still optional), plus the new optional peer ollama-ai-provider-v2 ^2.0.0 || ^3.0.0 || ^4.0.0, so a project on the current ai major installs without peer conflicts. Pairings: ai 4 with @ai-sdk/* 0.0.x/1.x and ollama-ai-provider 1.x; ai 6 with @ai-sdk/* 3.x and ollama-ai-provider-v2 2.x/3.x; ai 7 with @ai-sdk/* 4.x and ollama-ai-provider-v2 4.x. A missing provider package’s MissingPeerDependencyError.installCommand names the version for the installed ai major (npm install @ai-sdk/openai@^4.0.0 on ai 7; unchanged on ai 4). OllamaProvider loads ollama-ai-provider-v2 on ai 6/7; that package needs zod 4, which the SDK does not support yet, so its install hint says so and Ollama stays on ai 4 for now. lousho doctor checks provider packages against the installed ai major and flags a mismatched pair (e.g. ai 7 with @ai-sdk/openai 1.x) with the version to install; a missing or unsupported ai gets npm install ai@^7.0.0. lousho init / npm create lousho-agent scaffold ai@^7.0.0 with @ai-sdk/openai@^4.0.0 / @ai-sdk/anthropic@^4.0.0 for OpenAI and Anthropic, and keep ai@^4.3.19 for Ollama (zod 4) and OpenRouter (@ai-sdk/openai 2+ defaults to the Responses API, not yet verified there). The hint of resolveProvider()’s rare synchronous missing-peer error lists the command for each ai major. See Installation.
  • lousho add: lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run] installs a tool, skill, channel, schedule or memory slot from a static JSON registry (an index plus one document per item that carries the file contents) into an agent directory as source you own; lousho add --list prints the index. The registry comes from --registry or LOUSHO_REGISTRY (there is no hosted registry yet). It prints the item’s permission manifest (hosts, env vars, filesystem, exec, whether its tools ask for approval) and the files first and asks for confirmation (--yes skips it; a non-interactive stdin without --yes refuses; --dry-run writes nothing). Paths must be relative, inside the folder of the item’s type and inside the agent directory (no .., absolute paths, drive letters, backslashes or symlink escapes), files and items have size caps, existing files need --overwrite, fetches time out and only http(s) and local paths are read; nothing from a registry is executed and dependencies are only printed as an npm install line. New error codes LOUSHO_REGISTRY_UNREACHABLE, LOUSHO_REGISTRY_ITEM_NOT_FOUND, LOUSHO_REGISTRY_INVALID, LOUSHO_REGISTRY_UNSAFE_PATH, LOUSHO_REGISTRY_FILE_EXISTS. See docs/registry.md.
  • Checkpoint history for KVCheckpointStore and Agent Forge’s file store: KVCheckpointStore (and KVStore, with the new historyLimit option) keeps the bounded per-session history memoryStore() keeps, as one index key (<prefix><sessionId>#history) and one key per entry (<prefix><sessionId>#history/<id>) next to the unchanged latest-checkpoint key, so agent.fork(), compareTrajectories() and time travel work for Worker-deployed agents; a store written before this change still loads. A save now makes one get and two puts more (historyLimit: 0 turns the history off), and two concurrent saves of one session can lose an index update (KV has no transactions). Agent Forge’s FileCheckpointStore reads a partially written history file as empty and writes its files atomically. The history contract suite now runs against KVCheckpointStore too. See docs/durable-execution.md#checkpoint-history.
  • Hook outcomes: a preToolCall hook may return { deny: reason } (the call does not run; the model gets the same kind: 'denied' tool error as a needsApproval deny, streams see tool.error, and onPermissionDecision / permission.decision record decision: 'deny' with the new hook field and reason), { result: value } (the call does not run; value is its result) or { input: args } (the call runs with args, validated against the tool’s schema again; a mismatch is a kind: 'validation' tool error naming the hook). A postToolCall hook may return { result: value } to replace the result the model sees. Pre-hooks run in registration order: the first deny or result skips the later ones, inputs chain. A replaced result is marked replacedByHook on the tool.done event, the ToolCallOutcome / tool-result event and the transcript’s tool message metadata. Hooks still run first (after argument validation, before permission rules, tool guardrails and needsApproval), so the approval sees the hook’s input; on a resumed approved call the pre-hooks run again and an { input } that differs from the approved input is refused. Sub-agents inherit the outcomes. Hooks that return nothing type-check and behave as before; HookRegistry.runPreToolCall() now resolves to a PreToolCallDecision and runPostToolCall() to the name of the replacing hook (new types PreToolCallOutcome, PostToolCallOutcome, PreToolCallDecision). A hook that throws still rejects the run. See docs/api-overview.md#hook-outcomes.
  • lousho acp: lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] serves an agent over the Agent Client Protocol (v1) on stdio, so Zed and other ACP editors can run it as an external agent; stdout carries only JSON-RPC lines (the agent’s console.log goes to stderr). It implements initialize, session/new, session/prompt (text and resource_link blocks) and session/cancel, streams session/updates (agent_message_chunk, tool_call, tool_call_update), asks session/request_permission (Allow / Reject) when a tool needs approval and streams the continuation, and maps finish reasons to stop reasons (max-steps to max_turn_requests, budget-exceeded / length to max_tokens, guardrail to refusal, a cancel to cancelled). One ACP session is one SDK session. An ask_question pause ends the turn with the question as the agent’s message; the next prompt answers it. A failed run answers a JSON-RPC error whose data.code is the SDK error code. The protocol core is exported as serveAcp(agent, { input, write, store? }) (new type ServeAcpOptions), transport-independent. Not supported yet: session/load, the client’s fs/* and terminal/* methods, images, audio and embedded resources, plan and thought chunks. See docs/acp.md.
  • Agent directories deploy and serve with their schedules and channels: lousho build <agent-dir> --target=node-server (and docker; the path may also be --agent) builds a directory into a server whose entry calls resolveAgentDir() and createDeployedServer(agent, { schedules, channels }), so the deployed process starts the schedules/ and mounts the channels/ under /channels and logs which it found. The code files are pre-bundled by the existing tsup step into dist/agent/**.js (one ESM build sharing one SDK copy; dist/ is marked ESM) and the rest of the directory is copied, so nothing needs a TypeScript loader at run time; spec builds are unchanged. lousho dev <agent-dir> mounts the directory’s channels and starts its schedules, swapping both on hot reload (old schedules stopped first); --no-schedules starts none. The deploy runtime also exports createAgent, resolveAgentDir and storeFromEnv. The Cloudflare Worker target is unchanged (P9). See docs/agent-directories.md#deploy-it-with-lousho-build.
  • Route handler: createRouteHandler(agent, { basePath?, auth?, uiMessageStream? }) returns { GET, POST, handler }, Fetch handlers ((request: Request) => Promise<Response>) that serve the deployed session API under basePath (default /api/agent; trailing slash accepted, other paths 404) from a Next.js App Router app/api/agent/[[...path]]/route.ts, SvelteKit +server.ts, Hono or Bun.serve, with no framework or node:* import. auth is a bearer token or a (request) => boolean | Promise<boolean> (default none: a public route needs one; GET /health stays open). useLoushoAgent({ url, approvalsUrl }) works against it (POST <basePath> with { input, sessionId? }, POST <basePath>/approvals/:id), and uiMessageStream: true adds POST <basePath>/ui for useChat. hasBearerToken in src/server/fetchRoutes.ts is now exported for it. See docs/nextjs.md.
  • AI SDK UI stream: toUIMessageStream(run) maps a run’s events to the Vercel AI SDK’s UI message stream chunks (start, start-step, text-start / text-delta / text-end, tool-input-start / tool-input-available / tool-output-available / tool-output-error, finish-step, error, finish with the AI SDK finish reason), and toUIMessageStreamResponse(run, init?) returns the SSE Response (data: [DONE], header x-vercel-ai-ui-message-stream: v1) for a route handler, so useChat can render a Lousho run. An approval pause or ask_question is a data-lousho-approval part (approvalId, toolCallId, toolName, input, kind?, question?); usage and the run’s own finish reason are in the finish chunk’s messageMetadata. fromUIMessages(messages, { lastUserOnly? }) converts the UIMessage[] useChat posts (text, image and file parts; others ignored) to an AgentInput. Own structural chunk types (LoushoUIMessageChunk, UIMessageLike, …), no ai import and no node:*, so it also runs on Workers; exported from the package root (a dedicated subpath can follow). See docs/ai-sdk-ui.md.
  • Approval policies: a needsApproval function may return (or resolve to) 'approve', 'deny', 'ask' or { deny: reason } besides a boolean (true is 'ask', false is 'approve'; new type ApprovalOutcome), and gets a second argument { toolName, toolCallId, sessionId?, messages } (new type ApprovalCheckContext). A deny does not pause: the call is not run, the model gets a kind: 'denied' tool error with the reason, streams see tool.error, and onPermissionDecision / permission.decision record decision: 'deny' with the new reason field (no rule); the audit entry is now reported once the call is decided (after tool guardrails) instead of before them. New helpers always(), never() and once({ per?: 'tool' | 'args' }) (with type ApprovalPolicy): once() asks the first time a tool is called in a session and runs later calls once a human approved one (a rejection is not remembered; per: 'args' keys on the arguments’ hash). The memory is the approved call’s tool message (metadata.approval, set by resumeAfterApproval() and its streamed form), so it persists with sessions, checkpoints and approval snapshots and survives a resume in another process. A permissions deny rule wins; an allow or ask rule replaces the tool’s ask but not its deny (see Changed); the tool’s outcome applies when no rule matches. Existing boolean functions type-check and behave as before; a test asserting needsApproval was called with exactly one argument now sees the context too. See docs/approvals.md#approve-deny-or-ask.
  • Approval continuations stream live: POST /chat/:sessionId/approvals/:id (node server, Cloudflare Worker, lousho dev) now streams the continuation from agent.approvals.streamResolve() / streamAnswer() instead of replaying it after the turn ends; createAgentRunner’s approve() / reject() / answer() (React, Vue, Svelte) read that SSE stream event by event (an ApprovalOutcome JSON from an older server still works), and lousho chat prints the continuation as it streams. The UI reducer maps a streamed tool.error named ToolRejectedError to a rejected tool call. A second pause arrives as approval.requested. The approvals route has always answered with SSE, so no client opt-in was added.
  • session.compact() and session.clear(): await session.compact({ strategy?, protectedTokens?, contextWindow?, signal? }) compacts the session’s transcript now, whatever its size, with the given strategy, else agent.session({ compaction }) (new option, the value of createAgent({ compaction })), else by pruning old tool results; it saves the result through the session’s store and resolves to { messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }. clear() (which already existed and forgot the conversation) now emits context.cleared (new ContextClearedEvent in the AgentEvent union) and rejects with LOUSHO_SESSION_AWAITING_APPROVAL when a durable turn waits on an approval; it keeps the session id. New session.on(listener) receives compaction.start / compaction.done (which gain an optional trigger: 'manual') and context.cleared. Both reject with the new LOUSHO_SESSION_BUSY while a turn is in flight; compact() also with LOUSHO_SESSION_TURN_PENDING for an interrupted durable turn. lousho chat gains /compact and /clear. See docs/compaction.md#compacting-a-session.
  • Discord channel: discordChannel({ publicKey, applicationId, botToken?, name?, fetch? }) serves Discord’s HTTP Interactions endpoint through mountChannels() (Web Crypto and fetch only, Worker-safe, no gateway, no new dependency). It verifies X-Signature-Ed25519 / X-Signature-Timestamp (Ed25519 over timestamp + body, 401 otherwise) and answers PING with PONG. A slash command (/ask prompt:<text>) is acknowledged at once with a deferred response; its session is keyed on guild + channel (+ thread), and the reply edits the original response, with text over 2000 characters continued in follow-up messages. A tool approval is posted with Approve / Deny buttons and resolved by the click; an ask_question is answered by the next /ask in the channel. See docs/channels.md#discord.
  • Streaming resume after an approval: streamResumeAfterApproval(decision, approvalStore, toolRegistry, provider, options?, checkpointStore?) takes resumeAfterApproval()’s arguments and returns an AgentRun whose result is what resumeAfterApproval() returns. Its events are run.start, the decided call’s tool.start / tool.done (tool.error for a rejection), then the continuation’s events as in a fresh stream() run; a further pause ends it with approval.requested. Abort, enqueue() and steer() work as on any run, and the approval can be resolved in another process. createAgent() agents get agent.approvals.streamResolve(decision, { signal }) and streamAnswer({ id, answer }, { signal }) (a pause made in a session continues in it, run.done after the transcript is saved; a dynamic agent keeps the model the paused run used). Also new: the ResumeRequest type and resumeRequest(request) (resumeAfterApproval() with one object argument). Additive: resolve(), answer() and resumeAfterApproval() are unchanged. See docs/streaming.md#streaming-after-an-approval.
  • Credential broker: createCredentialBroker({ rules, allow?, allowPrivate?, port?, host?, pathFormScheme? }) starts a host-side HTTP forward proxy (Node-only, on an ephemeral 127.0.0.1 port by default) and resolves to { url, env, baseUrl(host), close() }. rules map a host (exact or *.suffix) to headers to inject, as strings or per-request functions, so a command the model runs can call an authenticated API without the token entering its environment: pass broker.env (HTTP_PROXY/HTTPS_PROXY/NO_PROXY, both cases) to NodeWorkspace or SandboxShell’s env. Hosts outside the rules and allow get a 403 without a connection; hosts resolving to loopback, link-local or private addresses are refused unless in allowPrivate; a client Authorization header for a brokered host is replaced; hop-by-hop headers are dropped. Injection covers plain-HTTP requests and the /__broker/<host>/<path> form (forwarded to https://<host>/<path>, returned by baseUrl(host)); HTTPS CONNECT tunnels are allowlist-checked and passed through untouched (no TLS interception). SubprocessSandbox’s network: { allow } still fails closed: routing containers through the broker is a separate follow-up. New types CredentialBroker, CredentialBrokerOptions, BrokerHeaderValue. See docs/workspace-tools.md#credential-broker.
  • Memory in agent directories: memory/*.ts|js|mjs files default-export a memory slot (defineMemory(), or the same options without a name; name = file name unless set). Unlike schedules and channels they are part of the agent: loadAgentDir() passes them to createAgent({ memory }), resolveAgentDir() lists them in manifest.memory, and a memory override is merged by name (the override wins a clash). A bad file fails with the new LOUSHO_MEMORY_INVALID naming the file. A directory without memory/ is unchanged. See docs/agent-directories.md#memory.
  • Channels in agent directories: channels/*.ts|js|mjs files default-export a channel (defineChannel() or a built-in factory; name = file name unless set); resolveAgentDir() returns them as channels and manifest.channels, and a file that exports no channel fails with the new LOUSHO_CHANNEL_INVALID naming the file. createDeployedServer(agent, { channels }) mounts them under /channels next to the chat routes. loadSchedules() and loadChannels() share one loader (schedule files that do not export a schedule now throw an SDKError with LOUSHO_SCHEDULE_INVALID, same message). lousho dev and the Cloudflare Worker target do not mount them yet. See docs/agent-directories.md#channels.
  • serveMcp annotations: defineTool({ annotations }) (readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title; stored as metadata.mcp.annotations) is sent in tools/list verbatim, and a tool with needsApproval is advertised readOnlyHint: false, destructiveHint: true (never read-only). An unannotated tool sends none. A Lousho agent consuming the server therefore runs read-only tools without an approval pause, pauses for needsApproval ones and keeps asking for unannotated ones. The built-in read_file, list_dir, glob, grep, todo_read, current_date and day_name tools are marked read-only. See docs/configuration.md#annotations.
  • Svelte store: new @lousho/build-ai-agent/svelte subpath with loushoAgent(source, options?). It returns a Svelte store (subscribe(run) => unsubscribe, so $agent works in Svelte 4 and 5) whose value is the same state as the React hook and the Vue composable (messages, status, pendingApproval, error, usage, lastEvent), plus send(), stop(), approve(), reject(), answer() and reset(). The run in flight is aborted by stop() and when the last subscriber unsubscribes. The store contract is implemented by hand: the entry imports nothing from svelte, so there is no new peer dependency. See docs/svelte.md.
  • Per-run dynamic config: createAgent()’s model, instructions / prompt and tools each also take a function of the run, (ctx) => value | Promise<value> (new types PerRun<T> and RunConfigContext = { sessionId?, input, metadata? }), resolved once at the start of each run and of each session turn, before the first model call. fallbackModels, retry, projectInstructions, memory, MCP tools, sub-agents, permissions, approvals and guardrails apply to the resolved values; a dynamic agent used as a sub-agent resolves with the task prompt as input. session.send() / session.stream() gain the metadata option (send() / stream() already had it, and now pass it to these functions too). A function that throws fails the run with the new LOUSHO_CONFIG_RESOLVER_FAILED (field names the option, cause is the error); a session keeps its transcript. A run paused for approval stores its ctx and resolved model in the approval snapshot (agent.metadata.loushoRunConfig): resuming it uses that model and re-resolves the tools with the same ctx; a crash resume from a checkpoint resolves with input: []. Static options behave and type as before. SessionRunner / SessionStreamRunner take an optional fourth call argument (new type SessionTurnCall). See docs/api-overview.md#dynamic-config.
  • Vue composable: new @lousho/build-ai-agent/vue subpath with useLoushoAgent(source, options?) for Vue 3. It takes the same sources and options as the React hook (either may be a ref, read when a turn starts) and returns messages, status, pendingApproval, error, usage and lastEvent as read-only refs, plus send(), stop(), approve(), reject(), answer() and a new reset() (aborts, forgets the in-process session, clears the chat). The run in flight is aborted by stop() and when the owning scope is disposed (onScopeDispose: component unmount, effectScope().stop()). vue (^3) is an optional peer dependency, loaded by no other entry. To share the logic, the reducer and the stream parser moved from src/react/ to a framework-neutral src/ui/, together with the run logic extracted from the React hook (createAgentRunner()); the ./react exports are unchanged, and the reducer gains an additive ui.reset action. See docs/vue.md.
  • One flag parser for the lousho CLI: every command (dev, chat, eval, build, mcp, doctor, studio; init already did) parses its flags with node:util parseArgs in strict mode through src/cli/args.ts. --flag value and --flag=value work everywhere, -- ends the flags, -h / --help prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with LOUSHO_CONFIG_INVALID and the command’s usage as the hint. Behaviour change (migration): dev, studio, mcp, build and doctor used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (--portx 1 read as --port); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with - must be written --flag=-x (a bare --flag -x is a missing value); --port must be an integer from 0 to 65535 for dev, studio and mcp; dev, mcp and doctor reject a second path; studio --prod --dev is rejected instead of preferring --prod. lousho dev and lousho studio parsing moved from bin/lousho.js into src/cli/dev.ts / src/cli/studio.ts (parseDevArgs, runDev, parseStudioArgs, runStudio). See docs/cli.md.
  • sqliteMemory(store, { maxItems? }) (exported from @lousho/build-ai-agent/sqlite) keeps defineMemory slots in the agent’s SqliteStore file: a new memory_items table (migration 3, one JSON array per scope key, with the same serialization, maxItems and query rules as fileMemory). An existing database gains the table on open and keeps its sessions and checkpoints. The memory provider contract tests now run against the in-memory, file and SQLite providers. See docs/memory.md#sqlite.
  • Slack channel: slackChannel({ signingSecret, botToken, name?, fetch? }) (new export, with types SlackChannelOptions, SlackChannelEvent, SlackThread) serves a Slack app’s Events API and interactivity requests through mountChannels(). It verifies the v0 request signature with Web Crypto (no node:* import; the timestamp and header checks are shared with verifySlackSignature()), answers the url_verification challenge, and acknowledges every request before the turn runs. Each Slack thread is one session (team + channel + thread root ts): a mention starts or continues it, and later messages in a thread the bot was mentioned in continue it. Retries (X-Slack-Retry-Num) and bot messages are skipped. Replies go to the thread with chat.postMessage over fetch; a tool approval is posted as Approve / Deny buttons whose click resumes the session, and an ask_question as text answered by the next thread message. The channel contract gains two additive hooks for this: parse(req, respond) may call respond to answer the request before the turn runs, and may return { decision } (new type ChannelDecision; ChannelApprovalDecision now lives in defineChannel.ts, same public export) to resolve a pause instead of starting a turn. See docs/channels.md#slack.
  • Remote sub-agents: remoteAgent({ url, auth?, name?, description?, headers?, fetch? }) (new export, with types RemoteAgentOptions and RemoteSubagent) makes a deployed agent usable wherever a local sub-agent is: in createAgent({ subagents }) records and SubagentCatalog.resolve(), delegated to by the task tool and by background: true tasks. Each task opens a fresh session on the remote agent over POST <url>/chat (bearer auth: a string or a function, called per task), reads the SSE stream to the end and returns the remote agent’s final text; the lead run’s abort signal aborts the request. Failures (network, 401 or other non-2xx, malformed stream, remote run error) are structured tool errors with the new code LOUSHO_REMOTE_AGENT_FAILED, and the token never appears in errors or events; a remote run that pauses for approval fails with LOUSHO_SESSION_AWAITING_APPROVAL naming the remote session (proxying approvals is a follow-up). Worker-safe (fetch only). See docs/sub-agents.md#remote-sub-agents.
  • Eval against a deployed agent: lousho eval --url <baseUrl> [--token <bearer>] (token also from LOUSHO_EVAL_TOKEN) runs every case of the trajectory eval files against a deployment (node server or Cloudflare Worker) instead of the in-process agent: one remote session per case over POST /chat { sessionId, input }, the SSE stream read to run.done and turned into the usual result (tool calls, reply, finish reason, steps, usage), so checks, scorers, t.judge(), the summary and --junit work unchanged. A check that needs data the stream lacks (maxTokens without usage) fails and names what is missing. Programmatic equivalent: defineEval({ target: remoteTarget({ url, auth?, fetch? }) }) (new remoteTarget(), EvalTarget; agent is now optional when a target is given, and AgentSource also accepts any { send() }). --url with --record / --replay / --drift is rejected with LOUSHO_CONFIG_CONFLICTING_OPTIONS; an unreachable deployment, a non-2xx answer or a truncated stream fails the case with the new LOUSHO_REMOTE_REQUEST_FAILED, and 401 with LOUSHO_REMOTE_UNAUTHORIZED. The token never reaches output or reports. See docs/evals.md#run-evals-against-a-deployment.
  • Schedules: defineSchedule({ cron, timezone?, name?, prompt | run }) declares a cron schedule (a prompt sent to the agent as a new turn, or run({ agent, firedAt, name })); an invalid cron expression, or not exactly one of prompt/run, throws the new LOUSHO_SCHEDULE_INVALID at definition time. An agent directory’s schedules/*.ts|js|mjs files default-export one each (name = file name unless set); resolveAgentDir() returns them as schedules and manifest.schedules. startSchedules(agent, schedules, { now?, setTimer?, onError? }) runs them with injectable clock and timers, isolates errors, skips a fire while the previous one runs and returns stop(); createDeployedServer(agent, { schedules }) starts them on listen and stops them on close. The Cloudflare Worker target is not covered yet. See docs/schedules.md.
  • Channels: defineChannel({ name, verify?, parse, reply, onApproval?, sessionId?, stream? }) describes one surface: verify authenticates a request (false or { ok: false } answers 401), parse maps it to { sessionKey, input, metadata?, replyTo } (or null to acknowledge it without a turn), reply delivers the agent’s reply (with stream: true, also partial text as the model writes) and onApproval renders a pause (default: a text prompt through reply). mountChannels(agent, channels, { store, basePath }) returns a framework-free (req, res) handler, in the style of the /chat routes, that serves POST <basePath>/<name> (verify -> parse -> a turn in session `${name}:${sessionKey}` -> reply; turns of one session run one at a time) and POST <basePath>/<name>/approvals/<id> ({ approved, note? } or { answer }); handler.resolveApproval() decides a pause from code (e.g. a button callback) and replies through the same channel. Built in: httpChannel() (JSON { sessionKey, input } in, { sessionId, text, finishReason, approval? } out) and webhookChannel({ secret }) (WebhookTriggerAdapter’s behaviour; the adapter now delegates its auth and parsing to it, unchanged for callers). Slack and Discord channels are separate follow-ups. See docs/channels.md.
  • Cloudflare Worker parity: the cloudflare-worker target now serves the same API as the node server: POST /chat { sessionId, input } streamed as SSE, history per session, GET /chat/:sessionId, POST /chat/:sessionId/approvals/:id and GET /health; the deprecated POST /chat { message, sessionId? } still works and still checkpoints under sessionId. LOUSHO_API_TOKEN (a Worker secret: wrangler secret put LOUSHO_API_TOKEN) makes every route except /health require Authorization: Bearer <token> (constant-time compare). New KVStore(kvBinding, { prefix?, ttl? }) (src/deploy/kvStore.ts) is an AgentStore on a Workers KV namespace: sessions/<id> (transcript JSON, bytes as { "$bytes" }), checkpoints/<id> (KVCheckpointStore, which gains an optional TTL) and approvals/<id>, with optional per-kind TTLs; the Worker builds it from the existing AGENT_CHECKPOINTS binding, and keeps sessions in the isolate’s memory without one. An approval paused on one request can be decided by another request on a new isolate. The routes are now Fetch-native (src/server/fetchRoutes.ts: Request in, Response and a ReadableStream SSE body out, bearer auth with Web Crypto); src/server/chatRoutes.ts adapts them to node:http for lousho dev and the node server, and src/server/bearerAuth.ts is gone. The built Worker runs a createAgent() agent, so the build swaps its Node-only imports for src/deploy/shims/node.worker.ts, and the node: leak check now also catches bare builtin specifiers; the bundle grows to about 1.7 MB. The generated wrangler.toml documents the KV binding and both secrets. The wrangler dev test now streams a session turn through workerd with a KV binding and a token. See docs/deployment.md#bindings-sessions-and-the-api-on-workers.
  • Steering: run.steer(input) on AgentRun (from agent.stream(), session.stream() and AgentExecutor.stream()), and InputQueue.steer(input) for non-streaming callers, redirect a running run to new user input. If a model call is in flight and has not emitted text or tool calls yet, it is aborted with a per-call signal (not the run’s), its partial output is discarded, the input is appended as a user message and the model is called again (applied: 'immediate'; that step ends with step.done 'steered' and counts toward maxSteps; a provider that ignores the signal is not waited for). Once the model has emitted output, the input waits for the next safe point like enqueue() ('queued'); after the run has finished, applied is false. Tool calls already running finish and keep their results; calls of that turn not started yet get the usual “cancelled before it ran” result. It returns { id, applied, joined } (new type SteerResult; joined is a promise of whether the input reached the transcript). New event input.steered { id, text, mode: 'immediate' | 'queued' } (InputSteeredEvent, additive, schema v1), followed by the existing input.applied. With checkpointing, the input is checkpointed when it is taken, before the model is called again, and the discarded partial turn is never checkpointed. agent.session({ turnPolicy: 'steer' }) makes a send() / stream() made while a turn runs steer that turn ('queue' and 'wait' are unchanged). AgentRun gains the required steer() member, so a hand-written AgentRun object must add it. See docs/streaming.md#steering and docs/sessions.md.
  • ai v6/v7 stream(): the built-in providers’ stream() (and so agent.stream()) now works on ai v6 and v7 as well as v4, through a compatibility layer (streamCompat()): the request is mapped as for generate(), and either major’s fullStream is read into the same StreamChunks: text deltas, tool calls (the whole call, or one assembled from tool-input-start/-delta/-end when the model sends none), and a finish chunk with the finish reason and usage, including cached and reasoning tokens. An error part now rejects the stream with its error on both majors (on v4 the step used to end with finish reason error and the partial text), an abort part with the signal’s reason; reasoning deltas are dropped until a reasoning chunk type exists. StreamChunk/StreamResult are unchanged. The protected AiSdkProvider.convertMessages() now returns our structural AiSdkMessage[] instead of ai v4’s CoreMessage[] (which v6/v7 do not export) and is marked deprecated; an override returning CoreMessage[] still compiles. The ai/@ai-sdk/* peer ranges still name v4. Tested on the real ai v7 (MockLanguageModelV4), with agent.stream() events asserted by one helper on v4 and v7. See docs/providers.md#vercel-ai-sdk-versions.
  • spec.policy is enforced: specToAgent() compiles the policy block into createAgent() options through the new compilePolicy(). requiresApproval (true or a list of tool names) becomes permissions: [ask(...)]; guardrails (max-length, secret-scan, regex, deny-topics, llm-judge, by name or { name, ...options, on }) become input and output guardrails; limits, askQuestion and compaction pass through. loadSpec() validates the known fields (an unknown guardrail name fails with the names available and a did-you-mean; unknown policy keys are still kept for the generators), and lousho doctor <spec> prints one line per policy block and flags unknown guardrail names. Behaviour change: requiresApproval: true now actually pauses tool calls (finishReason: 'awaiting-approval'); before, a spec that set it ran its tools without asking, and a spec with a guardrail name outside the built-ins (for example diff-size-cap) now fails validation. See docs/configuration.md#policy-policy.
  • ai v6/v7 generate(): the built-in providers’ generate() now works on ai v6 and v7 as well as v4, through a compatibility layer that detects the installed major (v5+ exports stepCountIs). On v6/v7 it sends messages as ModelMessages (tool calls with input, tool results as output, mediaType), maxTokens as maxOutputTokens, one step as stopWhen: stepCountIs(1), tools as inputSchema without execute and responseFormat as a JSON-mode output, and reads usage from inputTokens/outputTokens/totalTokens (cached and reasoning tokens from their details) into the same GenerateResult. LLMProvider, GenerateOptions and GenerateResult are unchanged, and v4 behaves as before. stream() on v6/v7 throws an error until that is supported; the ai and @ai-sdk/* peer ranges still name v4. Tested against the real ai v7 (MockLanguageModelV4) next to the v4 contract tests. See docs/providers.md#vercel-ai-sdk-versions.
  • Queued follow-up input: run.enqueue(input) on AgentRun (from agent.stream(), session.stream() and AgentExecutor.stream()) adds user input to a run that is still going; it joins the transcript at the next safe point (after the current step’s tool results, before the next model call) and the run continues as if the user had typed it, with one more step when it arrives during the final reply. It returns { id, applied }: applied is false when the run had already finished (send the input as a new turn, e.g. session.send()), otherwise a promise of whether it was applied. New events input.queued { id, text } and input.applied { id, step } (additive, schema v1). Non-streaming callers pass an InputQueue (new export) as ExecuteOptions.inputQueue and call its push(input). With checkpointing, a waiting input is saved right away at the end of the checkpoint (the queued-input slot), so a crash does not lose it. agent.session({ turnPolicy: 'queue' }) makes a send() / stream() made while a turn runs (or waits to start) join that turn instead of waiting for its own ('wait', the default, keeps today’s behaviour). AgentRun gains the required enqueue() member, so a hand-written AgentRun object must add it. Steering (aborting the in-flight model call to redirect) is a separate follow-up. See docs/streaming.md#queued-input and docs/sessions.md.
  • Input and output guardrails: guardrails?: { input?, output?, tools?, onTripped? } on createAgent() and ExecuteOptions (new type AgentGuardrails). A guardrail is { name, check(ctx) } (new type IoGuardrail; ctx is { kind: 'input' | 'output' | 'tool', text, messages, toolName?, args?, signal? }) returning { ok: true } or { ok: false, reason, action?: 'block' | 'rewrite', replacement? }. Input guardrails run on each new user message before the first model call; output guardrails on the final reply (in a streamed run, on every step’s text, before its text.done); tool guardrails on a call’s arguments after the permission rules (skipped on deny) and before needsApproval. A block ends the run with the new finishReason: 'guardrail' and result.guardrail ({ name, kind, reason, toolName? }, new type GuardrailTrip), with no model call for an input block; onTripped: 'throw' rejects with the new GuardrailError (LOUSHO_GUARDRAIL_TRIPPED) instead. A rewrite replaces the text. stream() emits the new guardrail.tripped (before run.done) and guardrail.rewrote events. Sub-agents run their parent’s guardrails, then their own. Built-ins: maxLengthGuardrail({ maxChars }), regexGuardrail({ name, pattern?, action?, replacement? }) (defaults to the secret-scan patterns, now exported as SECRET_PATTERNS), denyTopicsGuardrail({ topics }) and llmJudgeGuardrail({ model, instruction }). The patch guardrails (runGuardrails(), secretScanGuardrail, …) are unchanged; the new types are named IoGuardrail* because Guardrail and GuardrailResult are theirs. spec.policy.guardrails in agent spec files is not wired yet. See docs/guardrails.md#input-and-output-guardrails.
  • Deployed /chat upgrade: the node-server and docker targets (dist/server.js) now serve the lousho dev protocol: POST /chat { sessionId, input } streams the turn as SSE (data: <AgentEvent JSON>, then event: done) with history kept per session, GET /chat/:sessionId, POST /chat/:sessionId/approvals/:id ({ approved, note? } or { answer }) and GET /health; the single-turn POST /chat { message } still works (now with a Deprecation: true header). The routes are one shared module, src/server/chatRoutes.ts, used by lousho dev and the deployed runtime. LOUSHO_STORE (memory, the default, or sqlite:<path>, Node >= 22) picks where sessions live. Bearer auth: set LOUSHO_API_TOKEN (or pass { auth: { token } } as the new optional third argument of adapter.scaffold(); the variable wins) and every route except /health requires Authorization: Bearer <token> (constant-time compare, 401 JSON otherwise); treat it as required for anything not on localhost. The docker image is now based on node:22-slim (was node:20-slim) for node:sqlite. specToAgent(spec, { store }) takes an optional store. The Cloudflare Worker target is unchanged (sessions over KV and SSE there are a separate follow-up). See docs/deployment.md#http-api.
  • lousho chat: a terminal REPL for an agent. lousho chat <spec|dir|module> [--model provider/model] [--session id] [--store sqlite:<file>] loads the target like lousho dev and reads one turn per line through agent.session({ id, store }).stream(): text deltas as they arrive, each tool call as a dim [tool_name] {args} line followed by -> result, Approve <tool>(args)? [y/N] for a tool that needs approval, a numbered prompt with free text for an ask_question call, and [usage] tokens and cost after each turn. Slash commands: /new, /model <provider/model> (rebuilds the agent, the session continues), /history, /quit. SDK errors print with their [LOUSHO_...] code and fix. The loop is runChatRepl({ input, output, createAgent }) in src/cli/chatRepl.ts (testable with scripted lines and a mockModel agent); loadTarget() is now exported from src/cli/devReload.ts. See docs/cli.md#lousho-chat.
  • Memory slots: defineMemory({ name, description?, scope, provider, recall?, expose? }) (new export) defines a named long-term memory, and createAgent({ memory: [slot] }) wires it in. On the first model call of every run (send(), stream(), each session turn), a preGenerate hook recalls the slot’s newest recall.maxItems (default 10) items into the system prompt as a <memory name="..."> block (recall.query: 'last-input' passes the last user message as the provider query; recall.onSessionStart: false turns recall off). The model gets remember_<name>({ text }) and recall_<name>({ query?, limit? }) tools (expose: { remember?, recall? }, both on by default). scope is 'global', 'session' (keyed by agent.session({ id })’s id or send()’s sessionId) or a function of { sessionId, metadata }; the new SendOptions.metadata feeds it. Providers implement MemoryProvider (list / add / remove); built in are inMemoryMemory() and fileMemory({ dir }) (one JSON file per scope key), both bounded by maxItems (default 1000, oldest dropped). See docs/memory.md.
  • Budgets: limits?: { maxTokens?, maxInputTokens?, maxOutputTokens?, maxCostUsd?, maxDurationMs?, maxSteps?, onExceeded? } on createAgent() and ExecuteOptions (new type RunLimits). Limits are checked before every model call (so after every tool batch) and after a model call that asks for tools, and maxDurationMs aborts an in-flight model or tool call through the run’s signal. A tripped limit ends the run with the new finishReason: 'budget-exceeded' and result.budget: { limit, value, max, scope } (BudgetExceeded); tool calls of that step get a cancelled result and the run is checkpointed as finished, like 'max-steps'. stream() emits the new typed budget.exceeded event (BudgetExceededEvent) before run.done (additive, the event schema version stays 1). onExceeded: 'throw' rejects with the new BudgetExceededError (LOUSHO_BUDGET_EXCEEDED, no longer reserved) instead. limits.maxSteps is an alias of maxSteps (the stricter wins; alone it replaces the default of 10). Sub-agents’ usage counts toward their lead’s budget. agent.session({ id, limits }) applies limits across a session’s turns: what the turns spent is saved as metadata.sessionUsage on the transcript’s last message (new types BudgetSpent, SessionBudget, SessionTurnOptions; ExecuteOptions.sessionBudget carries it to the run), so maxCostUsd per session holds across processes. See docs/configuration.md#budgets.
  • Stateful streaming dev chat: lousho dev serves one session per browser tab. POST /chat with { sessionId, input } streams the turn as SSE (data: <AgentEvent JSON> per event, then event: done) through agent.session({ id, store }).stream(input) over an in-process memoryStore() (or the agent’s own store, when a module’s createAgent() options or overrides set one); GET /chat/:sessionId returns the transcript and the pending approval; POST /chat/:sessionId/approvals/:id with { approved, note? } or { answer } decides an approval or answers a question and streams the continuation (rebuilt from the continued run’s result, since agent.approvals.resolve() is not streamed). The chat page renders text deltas, tool calls with arguments and results, Approve / Reject and question buttons, errors and run.done usage and cost, with a “New session” button and the id kept in sessionStorage. Sessions survive a hot reload and continue on the new agent. The { message } body of POST /chat still works and is deprecated (no session, JSON ExecutionResult, Deprecation: true header). See docs/cli.md#lousho-dev and docs/streaming.md.
  • Agent Forge History tab: the bottom drawer’s new History tab lists the loaded agent’s run steps (step, status, finish reason, tool calls, tokens, cost). “Edit and replay from here” appends a user message or edits one of the step’s tool results, forks the run at that step through POST /runs/:id/fork, and shows the fork next to the original as a side-by-side trajectory with the diverging turn and the drift entries highlighted, refreshed when the fork finishes. See docs/agent-forge.md#the-history-tab.
  • lousho dev for agent directories and TS agents, with hot reload: lousho dev <path> takes a spec file (as before), an agent directory (loadAgentDir()) or a .ts/.js module whose default (or agent) export is a SimpleAgent or a createAgent() options object, detected by path type and extension (a bad path, extension or export fails with LOUSHO_CONFIG_INVALID / LOUSHO_SPEC_UNSUPPORTED_FORMAT). It watches the directory tree, or the module and its relative imports, and rebuilds the agent about 100 ms after a change with a ?t=<time> cache-busted import, so edited tools reload; the new agent is built and ready() before it replaces the old one, which is then close()d. A failed rebuild keeps the last good agent and reports the error in the console, in a banner on the chat page and in the new GET /dev/status ({ kind, path, reloads, error }). startDevServer(path, port?, host?, { overrides?, debounceMs? }) gains the options argument. Spec-file behaviour is unchanged; the chat is not streamed or per-tab. See docs/cli.md#lousho-dev and docs/agent-directories.md#run-it-with-lousho-dev.
  • Multimodal input through the public API: agent.send() / agent.stream(), session.send() / stream(), t.send() in evals and useLoushoAgent().send() take the new exported AgentInput (string | ContentPart[] | Message[]): a string or parts become one user message, a Message[] is passed through (in a session it is appended to the transcript). Checkpoints, agent.resume() and queued input hold the parts like any message. The React user bubble shows the text with an [image] / [file] marker per non-text part. SqliteStore sessions and checkpoints save Uint8Array parts as { "$bytes": "<base64>" }, as FileSessionStore does. Finishes the earlier change (its note that agent.send() / session.send() take no parts is out of date). See docs/providers.md#multimodal-input.
  • Built-in ask_question tool: createAgent({ askQuestion: true }) (off by default) or askQuestionTool() gives the agent ask_question({ question, options?, allowFreeText? }). A call pauses the run through the approval mechanism, so it waits durably like any approval (sessions, memoryStore() / SqliteStore, a restart between question and answer). The pending record gains optional kind: 'question' and question: { text, options?, allowFreeText? } (new types ApprovalKind, ApprovalQuestion; describeApproval() and ASK_QUESTION_TOOL_NAME are exported), and so do the approval.requested event and the React hook’s pendingApproval. The new agent.approvals.answer({ id, answer }) (the same as resolve({ id, approved: true, note: answer })) continues the run with { answer, option? } as the tool result (option: index of the matching option); approved: false gives the model a kind: 'rejected' error saying the user declined to answer. useLoushoAgent() gets answer(text). The approve callback may now return a string (ApproveToolCall returns boolean | string), which approves with that note, so code can answer questions. A tool run after an approval sees the decision’s note as ctx.approval.note (new optional ToolExecutionContext.approval). See docs/approvals.md “Asking the user a question”.
  • Agent Forge time travel API: Agent Forge’s FileCheckpointStore keeps the bounded per-session checkpoint history (history(), historyLimit option, delete({ keepHistory })) with the same semantics as LocalStorageCheckpointStore, checked by the SDK’s history contract suite. The runtime control server gains GET /runs/:id/history (each step’s status, save time, finish reason, tool calls, tokens and cost), POST /runs/:id/fork ({ fromStep, patch?: { toolResult?, appendInput?, businessState? } }, forks with AgentExecutor.fork() and starts the fork as a run of its own) and GET /runs/compare?a=&b= (compareTrajectories()). Fixed on the way: Agent Forge’s chat transcript compiles against multimodal Message.content again, keeping each message’s text. See docs/agent-forge.md#time-travel.
  • Fork and replay: AgentExecutor.fork({ sessionId, fromStep, newSessionId?, checkpointStore, patch? }) takes the newest entry of fromStep in the session’s checkpoint history, applies patch (messages(messages), businessState, toolResult: { toolCallId, result } replaced in place so the transcript stays provider-valid, appendInput queued as a user message) and saves it as the 'in-progress' checkpoint of newSessionId (default <sessionId>.fork-<n>), leaving the original session untouched; it returns { sessionId, step, checkpoint }, and execute({ sessionId, checkpointStore, input: [] }) continues the fork. A missing step throws the new LOUSHO_CHECKPOINT_NOT_FOUND code. createAgent() agents gain agent.fork(sessionId, { fromStep, newSessionId?, patch? }) over store.checkpoints (resume with agent.resume()). compareTrajectories(a, b) compares two checkpoints or transcripts step by step: each run’s steps (text, tool calls and results), the first diverging step and the lousho eval --drift diff. New types ForkOptions, ForkPatch, ForkResult, TrajectoryComparison, TrajectoryStep and DriftEntry. See docs/durable-execution.md#fork-and-replay.
  • Multimodal message parts: Message.content is now string | ContentPart[], where a ContentPart is { type: 'text', text }, { type: 'image', image, mimeType? } (an http(s) URL, a data: URL or a Uint8Array) or { type: 'file', data, mimeType, filename? } (new types ContentPart, TextContentPart, ImageContentPart, FileContentPart). The built-in providers map the parts of user messages to the ai v4 user-content parts: images go to the model with all four (the ai SDK downloads an image URL first for Anthropic and Ollama); file parts become a [file <name> (<mimeType>) not sent] text note with a one-time console.warn, since the pinned peers (@ai-sdk/* 0.0.x, ollama-ai-provider) cannot send files (a subclass sets acceptsFileParts = true to send them). system, assistant and tool messages are sent as their text. The new textOf(message) returns a message’s text (the string, or its text parts joined), and is what estimateTokens() (each image or file part counts 1,000 tokens), compaction, recordReplay() fingerprints (cassette messages gain an optional attachments list: each image or file as its URL or a digest of its bytes), mockModel(), MockLLMProvider, OpenTelemetry content attributes and the React reducer (ui.send takes parts too) now read. FileSessionStore saves Uint8Arrays as { "$bytes": "<base64>" } and loads them back. Pass multimodal messages as AgentExecutor.execute({ input: Message[] }); agent.send() / session.send() taking parts is a separate follow-up. See docs/providers.md#multimodal-input.
  • Declarative permission policies: permissions?: PermissionRule[] on createAgent(), ExecuteOptions and resumeAfterApproval() options. A rule is { tool: string | string[] | RegExp | '*', when?: (args, { toolName, toolCallId, sessionId }) => boolean | Promise<boolean>, action: 'allow' | 'deny' | 'ask', reason? }; rules are checked in order for each tool call (after argument validation and preToolCall hooks, before needsApproval) and the first match decides: allow runs the call without approval even when needsApproval would ask, deny gives the model a tool error with the new kind: 'denied' (ToolDeniedError, plus reason) and streams tool.error, ask pauses for approval (or asks approve). No match keeps today’s behaviour. New helpers allow(tools), deny(tools, reason?), ask(tools) and types PermissionRule, PermissionAction, PermissionToolMatcher, PermissionContext, PermissionDecision, PermissionDecisionEntry, PermissionOptions. Audit log: onPermissionDecision(entry) gets { toolName, toolCallId, decision: 'allow' | 'deny' | 'ask' | 'default', rule?: { index, reason? }, args?, at } per call (args left out under redactContent), and streams get the same entry as the new typed permission.decision event (PermissionDecisionEvent; additive, the event schema version stays 1). Neither is produced unless permissions or onPermissionDecision is set. Sub-agents inherit the lead’s rules (checked before their own) and its onPermissionDecision. See docs/approvals.md#permission-policies.
  • Compaction events and the compaction option: agent.stream(), session.stream() and AgentExecutor.stream() emit two new typed events whenever the compaction hook compacts a request: compaction.start (strategy, tokensBefore, contextWindow, thresholdTokens) before the work and compaction.done (strategy, tokensBefore, tokensAfter, prunedToolCallIds, summary?, error?: { message }) after it, inside the step and before the model call; error is set when the strategy failed and the hook fell back. Additive: the event schema version stays 1. GenerateHookContext gains the optional emit(event) (set in streamed runs only) that the hook uses. createAgent({ compaction }) takes true (the prune hook with its defaults) or { strategy?, thresholdPercent?, contextWindow?, protectedTokens?, summarizer? }, where summarizer (a 'provider/model' string or an LLMProvider) selects twoPhaseStrategy() with that model; summarizer together with strategy is a ConfigurationError. createAgent({ hooks }) (new) takes any AgentHook[], run before the compaction hook. See docs/compaction.md.
  • Connect MCP servers from config: connectMcp(servers, { lazy?, onError?, logger? }) (@lousho/build-ai-agent/mcp and the root) connects stdio (command/args/env) and streamable HTTP (url/headers) servers, lists their tools as <server>__<tool> descriptors and returns { tools, close(), status() }. Every server connects up front (listing tools needs a connection); lazy (default true) reconnects on the next tool call after close() or a dropped connection. onError: 'skip' leaves a failing server out with a warning instead of rejecting. createAgent({ mcpServers }) connects them on the new agent.ready() or the first send() / stream() and adds their tools; the new agent.close() disconnects them (both are no-ops without mcpServers). specToAgent() now connects spec.mcpServers the same way (closes TODO); agent.mcpServers still lists them. loadMcpTools() accepts any { listTools, callTool } (McpClientLike). See docs/configuration.md#connect-mcp-servers-mcpservers-connectmcp.
  • Error codes with fixes: every SDKError now has a stable code (LOUSHO_<AREA>_<NAME>, e.g. LOUSHO_CONFIG_MISSING_PROVIDER, LOUSHO_PEER_MISSING, LOUSHO_SPEC_INVALID, LOUSHO_SESSION_AWAITING_APPROVAL), a one-sentence hint and a docs link to its section of the new docs/errors.md; its message ends with a [code] hint (docs) line (detail is the message without it), and toString() always shows it. ERROR_CODES / ErrorCode (new exports) are the registry, and a test keeps it, the codes used in src/ and docs/errors.md in sync. The plain Errors thrown by createAgent() (no model, instructions + prompt, sessionId without checkpoints), resolveProvider() (bad spec, unknown prefix, missing API key, missing peer), AgentExecutor.execute() / stream() (missing provider / agent / input, approval with no approvalStore), resumeAfterApproval() (unknown approval), sessions (invalid id, corrupt file, second iteration, no stream runner), loadSpec() and specToAgent() are now ConfigurationError / ValidationError / SDKError with codes; MissingPeerDependencyError extends SDKError. Existing message text is unchanged (the help line is appended). loadSpec() suggests the field a top-level typo meant (unknown field 'promt' (did you mean 'prompt'?)). See docs/errors.md.
  • Checkpoint history: memoryStore(), SqliteStore and LocalStorageCheckpointStore keep a bounded history per session: every save() also appends the record to a ring (historyLimit option, default 50, 0 keeps none; the oldest are dropped), and the new optional CheckpointStore.history(sessionId, { limit? }) returns { step, savedAt, status, checkpoint } entries newest first. CheckpointStore.delete(sessionId, { keepHistory: true }) keeps the history (by default delete() clears it too), getCheckpointHistory(store, sessionId) reads it and returns undefined for a store without history(), and SqliteStore gains the checkpoint_history table (added when an existing database file is opened; prune() removes old entries). New types CheckpointHistoryEntry, CheckpointHistoryOptions, CheckpointDeleteOptions and MemoryStoreOptions. KVCheckpointStore and Agent Forge’s file store keep no history yet. This is the first step of time-travel from a past step. See docs/durable-execution.md#checkpoint-history.
  • lousho eval --record / --replay / --drift: --record runs every eval case against its agent’s real provider through recordReplay() and writes one cassette per case next to the eval file (__cassettes__/<eval-name>/<case>.json, the normal cassette format); --replay runs every case from its cassette with no network, and a missing cassette fails the case with the --record command to run. Plain lousho eval with CI set replays the cases that have a cassette; without CI it is unchanged. --drift re-records into a temp directory and compares each case with its committed cassette (ordered tool names, JSON-normalized tool arguments, step count, finish reason; tokens with --drift-usage): the summary gets a Drift: table and each drifted case a soft drift assertion (a JUnit <system-out> note), or a gate failure with --strict. Existing eval files need no change: while a case runs, AgentExecutor.execute() wraps its provider for that case. EvalResult gains cassettes. Fixed on the way: trajectory and classic eval results now carry their file (it was read before the test ran and was always empty). See docs/evals.md#record-replay-and-drift.
  • OpenTelemetry GenAI metrics and cost: createOtelTraceExporter() (@lousho/build-ai-agent/otel) now also records the GenAI client metrics gen_ai.client.token.usage (histogram, {token}, one record per gen_ai.token.type input/output) and gen_ai.client.operation.duration (histogram, s, for every model call and tool call) through @opentelemetry/api’s metrics API: the global MeterProvider, or the new meter option; metrics: false turns them off. Without a registered MeterProvider they are discarded by OpenTelemetry’s no-op meter. Spans gain lousho.cost_usd (estimated USD: per step on chat spans, cumulative on invoke_agent spans, absent when the price table does not know a model) and lousho.usage.estimated on invoke_agent spans (it was already on chat spans). Any TraceExporter sees the cumulative attributes: withSpan() sums the cost of finished child spans onto their parent. See docs/observability.md.
  • One store option: createAgent({ store }) takes an AgentStore ({ sessions?, checkpoints?, approvals? }, new export) and wires all three from it. SqliteStore is one; the new memoryStore() returns in-memory sessions, checkpoints and approvals, and docs/sessions.md shows the file-based combination (FileSessionStore, LocalStorageCheckpointStore, StorageServiceApprovalStore). agent.session({ id }) then keeps its transcript in store.sessions and checkpoints every turn in store.checkpoints; store.approvals is the default approvalStore. SendOptions.sessionId makes send() / stream() a durable run checkpointed in store.checkpoints (an error without one), so a one-shot durable job needs no AgentExecutor, and agent.approvals.resolve() keeps checkpointing it. The new agent.resume(sessionId) finishes an interrupted send(..., { sessionId }) run, or else the session’s pending turn (as session.resume()), and returns null when nothing is pending. A session’s own store / checkpointStore and an explicit approvalStore still win, part by part. Without store, nothing changes.
  • One tool-error shape: every failed tool call reaches the model as { error, toolName, message, kind } (message capped at 2,000 characters, transcript message flagged isError), whichever path failed: kind is 'execution', 'validation' (plus issues), 'not-found', 'rejected' (plus note), 'not-run', 'mcp' or 'sandbox'. New exports toolErrorResult(), ToolErrorResult, ToolErrorKind and ToolErrorInput; McpToolError and the sandbox guard’s error (named SandboxRequiredError, not exported) carry a toolErrorKind. kind is additive on thrown-error and validation results. The paths that built their own shapes changed, see Changed. See docs/tools.md.
  • Background sub-agents end with the lead run: when a run ends (any finishReason, or an error), its background sub-agents still queued or running are cancelled, and the run resolves once their runs have stopped, so none of their events reaches onEvent afterwards. withSubagentOptions(subagents, { awaitBackgroundOnFinish: true }) waits for them instead (an aborted or failed lead still cancels them). The new result.backgroundTasks lists the run’s background tasks as { taskId, agent, status, elapsedMs, ... } (absent when it started none). createAgent({ subagentOptions: { maxConcurrent, awaitBackgroundOnFinish } }) sets the same options (over any attached with withSubagentOptions(), without changing the subagents value). The executor hook behind it is public: ExecuteOptions.onRunEnd({ result } | { error }) is called exactly once per execute() / stream() run, however it ends; an error it throws rejects the run. See docs/sub-agents.md.
  • Durable sessions: agent.session({ id, store, checkpointStore }) (or a store that carries both, { sessions, checkpoints }, such as a SqliteStore) runs each turn with sessionId: '<id>.turn-<n>' and that CheckpointStore, so it is checkpointed after every model response and tool result. session.resume() finishes a turn interrupted by a crash, a failed checkpoint write or a PropagatingToolError (also in a new process) without re-running recorded tool calls or model responses, adds it to the transcript as send() would and returns its result (null when nothing is pending); session.pending() reports an unfinished turn and session.discardPending() drops it. send() / stream() resume a pending turn before sending the new message. A turn paused for approval stays in its checkpoint until it finishes: resume() / send() throw SessionAwaitingApprovalError, and agent.approvals.resolve() continues it in the session. Sessions without a checkpoint store are unchanged. See docs/sessions.md.
  • Structured output: createAgent({ output: zodSchema }) (and ExecuteOptions.output) makes the final reply a JSON object validated by the schema. send(), run.result and agent.approvals.resolve() resolve with it as result.object, typed z.output<typeof schema> from send() and stream() of createAgent() agents (SimpleAgent, AgentRun and ExecutionResult gain a type parameter that defaults to unknown); result.text keeps the raw JSON. The system prompt gets an ## Output format section with the schema as JSON Schema, and each model call carries the new GenerateOptions.responseFormat: { type: 'json', schema? } hint, which the ai-SDK providers map to experimental_output JSON mode. The reply is parsed (a code fence is tolerated) and validated; when invalid, one repair step sends the model the issues (it counts against maxSteps), and a reply still invalid ends the run with the new finishReason: 'output-invalid', no object and outputError: { message, issues }. run.done gains an optional object field (additive: the event schema version stays 1). See docs/structured-output.md.
  • Background sub-agents: the task tool takes background: true, which starts the sub-agent and returns { taskId, status: 'running', agent } at once. Agents with subagents also get agent_status({ taskId? }) (queued/running/done/failed/cancelled/awaiting-approval, plus elapsedMs), agent_await({ taskId | taskIds, timeoutMs? }) (the synchronous task result, or status: 'timeout') and agent_cancel({ taskId }). withSubagentOptions(subagents, { maxConcurrent }) bounds how many run at once per lead run (default 3; the rest queue). Background sub-agents inherit the lead run’s runtime and maxSubagentDepth, and aborting the lead cancels them. Not yet: resuming one that paused for approval (it reports awaiting-approval with its approvalId). A user tool named agent_status, agent_await or agent_cancel now conflicts with subagents, like task. See docs/sub-agents.md.
  • React hook: new @lousho/build-ai-agent/react subpath with useLoushoAgent(source, options?). source is { agent, sessionId? } (in process, via agent.stream() or agent.session({ id }).stream()) or { url, headers?, fetch? } (POSTs { input } and reads the SSE or NDJSON event stream). It returns messages (text and tool calls with status, args and result), status (idle/streaming/awaiting-approval/error), pendingApproval, error, usage, lastEvent, send(), stop() (aborts; unmount aborts too), approve(note?) and reject(note?) (via agent.approvals.resolve() in process, or POST ${approvalsUrl}/${id} remotely). The framework-neutral reduceAgentEvents() reducer and parseEventStream() parser are exported from the same subpath. react (^18 || ^19) is an optional peer dependency. See docs/react.md.
  • Summarizing compaction: summarizeStrategy({ model, protectedTokens?, prompt?, maxSummaryTokens? }) replaces the turns before the protected tail with one [Conversation summary] user message written by model (an LLMProvider or a "provider/model" spec), keeping system and pinned messages and each assistant turn together with its tool results; if the summary call fails it falls back to pruning and reports error. twoPhaseStrategy() (the recommended strategy) prunes first and summarizes only when still above the threshold. pinMessage() / isPinned() and the new optional Message.metadata (never sent to providers) mark messages no built-in strategy compacts. CompactionStrategy.compact() may now be async, so compactMessages() returns a Promise; CompactionResult / CompactionInfo gain summary and error, and CompactionInput gains thresholdTokens and signal. A strategy that throws no longer fails the run: the hook reports the error to onCompaction. See docs/compaction.md.
  • createAgent({ retry, fallbackModels }): retry (withRetry() options, or false) retries failed model calls and defaults to { maxRetries: 2 } for models given as provider/model strings (or picked from the environment); a provider instance is wrapped only when retry is set. fallbackModels are provider/model strings tried in order once the primary model’s retries are used up (withFallback([withRetry(primary), withRetry(fallback), ...])). agent.stream(), session.stream() and AgentExecutor.stream() report them as two new typed events, provider.retry (attempt, maxRetries, delayMs, error: { message, category? }, provider) and provider.fallback (from, to, error: { message }), for any withRetry() / withFallback() provider. Additive: the event schema version stays 1.
  • Context compaction: createCompactionHook() returns an AgentHook that, before a model call estimated above thresholdPercent (default 0.9) of the model’s context window, replaces tool results older than the newest protectedTokens (default 40,000) with a [pruned: <tool> result, N chars] marker, in the run’s transcript itself. compactMessages() compacts a conversation by hand; CompactionStrategy / pruneToolResultsStrategy() make the strategy pluggable. See docs/compaction.md.
  • AgentSpec.mcpServers: a validated map of MCP servers (stdio command/args/env or HTTP url/headers) in agent spec files. loadSpec() reports a bad entry with its name, lousho doctor reads the validated field instead of the raw file, and specToAgent() exposes the parsed servers as agent.mcpServers (connecting them is TODO). Existing specs are unaffected.
  • createAgent() agents can pause for approval: a needsApproval tool no longer fails the run with “requires approval but no approvalStore”. The run pauses (finishReason: 'awaiting-approval') in a per-agent InMemoryApprovalStore (or the new approvalStore option), and agent.approvals.list() / agent.approvals.resolve({ id, approved, note? }) continue it, in its session if it paused in one. The approve option decides calls in code without pausing.
  • Tools own their contract: ToolDescriptor gains optional inputSchema (zod) and execute(args, ctx), which are now the canonical fields. defineTool() sets both and no longer calls ai’s tool(). Argument validation, the schema sent to the model, and tool execution read them first and fall back to tool.parameters / tool.execute. ToolDescriptor.tool (the ai v4 Tool) is now legacy: it is still built by defineTool() and still accepted on hand-written descriptors this release, but new code should set inputSchema and execute.
  • ✅ Complete Phase 5 migration: Security, Storage, Templates, and Utils modules
  • ✅ Security module with encryption, hashing, and quota validation
  • ✅ Storage service with file locking mechanism
  • ✅ Template rendering engine with Jinja2-like syntax
  • ✅ Comprehensive utility functions (errors, formatters, validators)
  • ✅ File extraction and processing utilities
  • ✅ JSON path navigation utilities
  • ✅ Framework-agnostic architecture (zero framework dependencies)

Fixed

  • lousho --help, -h and help print the usage and exit 0 (they were “unknown command” with exit 1).
  • Install truth: the README, installation, CLI, quick start and Agent Forge docs, lousho init --help and the message after a failed lousho init install now say the package is not on npm yet and point to one section, “Installing before the first release” (docs/installation.md); npm install github:LinuxDevil/agent-sdk is documented as not working. Stale “planned / not yet” statements about agent-directory channels, toolCallId in sandboxed tools and the Agent Forge Settings tab are corrected.
  • On ai 5+ the providers send images as file parts with an image mediaType (image/* when unknown) instead of the deprecated image part, which made ai 7 log a deprecation warning for every image. ai 4 still gets image parts.
  • OpenRouter on @ai-sdk/openai 2+, and the Ollama base URL (behaviour fix): OpenRouterProvider now builds its model with provider.chat(modelId) (Chat Completions, the only API OpenRouter implements) instead of the bare call, which targets the Responses API from @ai-sdk/openai 2 on; no change on ai 4. OllamaProvider appends /api to a base URL that has no path (http://host:11434 or http://host:11434/), the form ollama-ai-provider and ollama-ai-provider-v2 expect, so a configured bare host no longer hits /chat outside /api (before, getModels() hit <baseURL>/api/tags but chat requests went to <baseURL>/chat); a URL ending in /api or with any other path is used as it is, and getModels() no longer doubles /api for a base URL that has it. lousho init (and create-lousho-agent) now scaffolds OpenRouter projects on ai@^7.0.0 with @ai-sdk/openai@^4.0.0.

Deprecated

  • ExecuteOptions.onEvent, ExecutionEvent and ExecutionEventType. onEvent keeps working: the executor now emits only AgentEvents, and an adapter derives the old events from them in the old order (start, text-complete, tool-call, tool-result, error, abort, finish, sub-agents’ tagged with subagent), with a one-time console.warn. Differences: finish now comes after the run’s checkpoint is written (it was just before), and a run that fails outside a step (an input guardrail that throws, onRunEnd throwing) now gets an error event too. Migration: replace onEvent with onAgentEvent (or createAgent({ onEvent })); start -> run.start, text-complete -> text.done (step usage on step.done), tool-call -> tool.start, tool-result -> tool.done / tool.error, abort / finish -> run.done (finishReason), error -> error ({ name, message }). The full table is in docs/streaming.md#migrating-from-onevent—executionevent.

Removed

  • ExecuteOptions.streaming: it was never read. Use AgentExecutor.stream() / agent.stream() to stream a run. Passing it in an object literal is now a type error; remove the property.
  • ToolDescriptor.injectStreamingController and defineTool({ injectStreamingController }) (deprecated earlier in this release): no SDK path ever called it, so removing the property changes nothing at runtime. Passing it is now a type error; remove the property.
  • AgentExecutionOptions.streaming: it was never read (AgentExecutionOptions is a legacy type no SDK API takes). Remove the property; stream a run with agent.stream() / AgentExecutor.stream().
  • BREAKING: validateTokenQuotas() (src/security/quotas.ts) and the SaaS-era types SaaSContext, QuotaConfig, UsageStats and QuotaValidationResult no longer ship from the package root. Nothing in the SDK called them. No replacement; copy the file into your project if you relied on it.
  • BREAKING: ConfigManager and SDKConfig (src/core/ConfigManager.ts) no longer ship from the package root or ./core (which still exports AgentBuilder). Nothing in the SDK used them. No replacement; copy the file into your project if you relied on it.
  • BREAKING: The formatters getCurrentTS(), getTS(), formatDate(), safeJsonParse(), removeCodeBlocks(), findCodeBlocks(), checkApiKey() and the types CodeBlock, CodeBlockError, CodeBlockResult (src/utils/formatters.ts) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
  • BREAKING: The JSON path helpers getObjectByPath() and setRecursiveNames() (src/utils/json-path.ts) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
  • BREAKING: The file extraction helpers getMimeType(), getFileExtensionFromMimeType(), replaceBase64Content(), isBinaryData(), extractBase64Data(), createDataUri() and ProcessFilesParams (src/utils/file-extractor.ts) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
  • BREAKING: The flows-ai converters are gone: convertToFlowDefinition() and convertFromFlowDefinition() (src/flows/converters.ts) no longer ship from the package root or ./flows. There is no replacement: the flows-ai engine they targeted was never a dependency of this package and FlowExecutor never used them. Run flows with FlowExecutor directly.
  • BREAKING: MemoryManager and its types MemoryManagerConfig, StoreMemoryOptions, RecallMemoryOptions and MemorySearchResult (src/execution/MemoryManager.ts) no longer ship from the package root. Nothing in the SDK used them (AgentExecutor, createAgent, resume and the flows never called them; only their own test and the execution/index.ts re-export). Migrate to defineMemory() and createAgent({ memory }) (memory slots, see docs/memory.md).
  • BREAKING: ContextBuilder, ContextBuilderOptions and ExecutionContext (src/execution/ContextBuilder.ts) no longer ship from the package root. Nothing in the SDK used them; they truncated by message count only. Migrate to createAgent({ compaction }) (token-aware compaction, see docs/compaction.md).
  • BREAKING: The retry() family (retry, retryOnError, retryWithTimeout, retryBatch, RetryableOperation, RetryOptions, RetryResult; src/execution/retry.ts) no longer ships from the package root. Provider calls retry through the provider wrappers; nothing else in the SDK used it. Migrate to createAgent({ retry, fallbackModels }), or copy the file into your project for general-purpose retries.
  • BREAKING: The data/ module is gone: the classes Agent, Session, Result, Memory, Attachment and the repository interfaces BaseRepository, AgentRepository, SessionRepository, ResultRepository, MemoryRepository, AttachmentRepository, RepositoryCollection, RepositoryFactory, PaginationOptions, PaginatedResult no longer ship from the package root. They were donor-product data tables that nothing in the SDK used once MemoryManager was removed. No replacement: unused. Use AgentConfig, sessions (agent.session()) and defineMemory() for the SDK’s own concepts.
  • BREAKING: @lousho/build-ai-agent/testing exports test utilities only. The in-memory repository mocks MockAgentRepository, MockSessionRepository, MockResultRepository, MockMemoryRepository and MockAttachmentRepository are removed with the data/ module. No replacement: unused. mockModel and recordReplay are unchanged.
  • BREAKING: The template engine (TemplateManager, renderTemplate() and the types TemplateFilter, TemplateContext, TemplateOptions, ITemplateManager; src/templates) no longer ships from the package root. Nothing in the SDK, lousho init or Agent Forge used it (the executor never rendered prompts through it; the scaffold templates are separate files under src/cli/init). No replacement: unused; use a template literal or your own renderer.
  • nanoid is no longer a dependency. Generated ids (agent, run, trace, memory ids) now come from globalThis.crypto.randomUUID() via an internal newId(), so they are UUIDs instead of 21-character nanoids. Nothing public depended on the old format.
  • finishReason: 'max-steps': a run that exhausts maxSteps while the model still wanted to continue (last turn ended in tool calls) now resolves with finishReason: 'max-steps' instead of the stale last-turn reason (usually 'tool_calls'), on ExecutionResult, the finish event and run.done. Resumed runs count initialSteps toward the budget. A run that finishes naturally within the budget is unchanged. Code that treated 'tool_calls' as “hit maxSteps” should check 'max-steps' instead (the eval completed() message and the MCP server’s agent tool do).

Docs

  • README revamped into a short front page; the details it dropped moved to docs/ (new pages: tools, approvals, providers, cli, flows, guardrails, utilities).

Renamed

  • The project is now lousho (it was loushy), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package @lousho/build-ai-agent (was @loushy/build-ai-agent), the lousho CLI (was loushy), create-lousho-agent (was create-loushy-agent), the exports useLoushoAgent, loushoAgent, LoushoAgentSource, LoushoUIMessageChunk and the other Lousho* types, every LOUSHO_* error code and environment variable (LOUSHO_MODEL, LOUSHO_API_TOKEN, LOUSHO_STORE, …), the .lousho/ directory, the lousho.* span attributes and the data-lousho-approval stream part. Migration for a checkout that used the old name: replace loushy with lousho (keeping the case) in imports, scripts, environment variables and config, and rename an existing .loushy/ directory to .lousho/.

Published

  • @lousho/build-ai-agent and create-lousho-agent are on npm. The README and the installation, quick start, CLI and Agent Forge docs no longer say the package is unpublished; “Installing before the first release” is now “Installing from a local build” (docs/installation.md#installing-from-a-local-build) and covers trying an unreleased commit. The hint printed after a failed lousho init install no longer mentions a 404; it points to --sdk-path. The docs site moved to https://lousho.com.