Skip to main content

Who needs this page

Anyone with code written against 1.0.0-alpha.8 or an earlier 1.0.0-alpha.* release. Between those alphas and the 1.0 line (the changes listed under 1.0.0-alpha.19 in the changelog, first published in 1.0.0-alpha.15) the package’s public surface was reorganized: imports moved to subpaths, dead or superseded APIs were removed, and the patch guardrails were renamed patch checks. createAgent() and its options did not change - an agent that only does createAgent({ model, instructions, tools }) and agent.send() upgrades by changing nothing but the version. Already on 1.0.0-alpha.19? Skip to Upgrading from alpha.19 for what changed on main since.

Import paths that moved

The package root now holds createAgent() and the names its config and results use. Everything below moved to a dedicated subpath; the declarations are unchanged apart from where they live. The lousho/core subpath no longer exists; everything it exported is under /executor.

Removed APIs and their replacements

  • AgentType, AgentTypeDescriptor, AgentConfig.agentType, AgentBuilder.setType() and the agent-type registry (agentTypesRegistry, getAgentTypeDescriptor, getAllAgentTypeDescriptors, isValidAgentType, validateAgentConfig, validateAgentTools). They had no runtime effect: delete the setType(...) call and the agentType field. A checkpoint saved with agentType still loads; the field is ignored.
  • ExecuteOptions.onEvent and the ExecutionEvent / ExecutionEventType types. Pass onAgentEvent to AgentExecutor.execute() / stream() / resumeAfterApproval() instead; the events you now receive are AgentEvents. The event-name mapping is in Streaming. With createAgent(), onEvent already receives AgentEvents and is unchanged.
  • createDelegateTool(), DelegateAgentOptions, DelegateAgentResult and DelegationDepthExceededError. Use the subagents option on createAgent() or AgentExecutor.execute(): the model gets one task tool per sub-agent, with a depth limit (maxSubagentDepth, default 1) instead of the thrown error. See Sub-agents.
  • Types nothing implemented or used: 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, copy its declaration into your project.

Renamed APIs

The patch guardrails are now called patch checks, so “guardrail” only means the input/output/tool guardrails of createAgent({ guardrails }). Arguments, results and behavior are unchanged; SECRET_PATTERNS keeps its name. See Guardrails and sandboxing.

Migrating from triggers

WebhookTriggerAdapter, SlackTriggerAdapter, CronTriggerAdapter and their option/handle types were removed from lousho/triggers. TriggerAdapter, TriggerRegistry, the WebhookAuth helpers, verifySlackSignature() and parseCronExpression() stay. See Triggers.

Deprecated, still working in 1.x

These names still work in 1.x and are removed in 2.0. Move off them when you touch the code; nothing breaks if you do not.

Other behavior changes since alpha.8

The full list is in the CHANGELOG. The entries that change runtime behavior or types your code may rely on, one line each:
  • The moves, removals and renames above are the ### Breaking section; the notes below are the ### Changed entries that alter behavior.
  • A tool whose execute returns an async generator is now iterated - its last yielded value is the result - and AgentEvent gains tool.partial (ToolPartialEvent); wrap a generator you mean to return as a value ({ items: generator }). See Tools and Stream events.
  • AgentEvent gains the handoff event and ExecutionResult the optional agentName: an exhaustive switch over event.type needs a handoff case. See Handoffs.
  • McpServerStatus gains 'needs-auth' and AgentOAuth gains mcpSignInUrl(server): an exhaustive switch over connectMcp().status() needs the new case. See MCP and OAuth.
  • ToolExecutionContext gains getToken(provider) and requireAuth(provider), and ApprovalKind gains 'sign-in': a hand-built tool context in a test needs the two methods (or a cast). See OAuth.
  • With a listener (createAgent({ onEvent }), onAgentEvent), send() and execute() now stream model calls: a step’s text arrives as several text.delta events instead of one. execute({ streamModelCalls: false }) restores the old shape. See Stream events.
  • MockLLMProvider / createMockProvider(): stream() now streams the same step generate() returns - the same tool calls, finish reason and usage - so a streamed mock run calls tools as send() does. See Testing.
  • Agent Forge runs stream their model calls; the chat, logs and trace views are unchanged. See Agent Forge.
  • lousho init --provider ollama now scaffolds ai@^7 with ollama-ai-provider-v2@^4 and zod@^4 (it was ai@^4 with ollama-ai-provider@^1 and zod 3). Existing projects are untouched. See Installation.
  • A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead’s onAgentDrift - with 'error' a changed sub-agent now rejects agent.approvals.resolve() too. See Durable execution.
  • lousho add enforces the registry permission manifest at install, and a loaded agent directory runs each item’s tools inside its accepted manifest (approval always on for exec/needsApproval/unattested items, fetch and process.env scoped to the declaration); mismatched code is refused with LOUSHO_REGISTRY_MANIFEST_MISMATCH, and --yes needs --allow for elevated permissions. See Registry.
  • Continuing an unfinished checkpointed run with a principal other than the one it was saved with now throws LOUSHO_CONFIG_INVALID; checkpoints and approval snapshots store the run’s principal. See Route auth and principals.
  • Memory slots store their items under <slot name>#<scope key> (notes#global) instead of the bare scope key (global), so two slots with the same scope no longer share items. Items written by 1.0.0-alpha.19 or earlier are not read any more; run migrateMemoryKeys(slot) once per slot to copy them. See Memory.
  • The published package is smaller: test-only files no longer ship, and source maps no longer embed sourcesContent (their sources still resolve to the shipped src/). No API change.

Upgrading from alpha.19

1.0.0-alpha.19 is the latest release on npm. The changes on main since then (the [Unreleased] section of the CHANGELOG) are mostly fixes and additions, but some change a default or a behavior your code may rely on. Each is listed below with the way back to the old behavior, where there is one. A change marked “no opt-out” closed a security or data-loss bug.

HTTP routes, servers and channels

Sessions, approvals and durability

Providers and model calls

Tools, MCP and tracing

CLI, evals and Studio

Studio moved to its own package

Lousho Studio is published separately as lousho-studio and is no longer part of the lousho tarball. What to do:
  • Install it once: npm i -g lousho-studio, then run lousho-studio. Or run npx lousho-studio. lousho studio inside a project keeps working - it finds the installed Studio and opens that folder as a workspace; with none installed it prints Studio is a separate install: npx lousho-studio.
  • Studio-wide settings and secrets moved from a project’s .lousho/ to ~/.lousho/studio/. On first launch Studio offers Import settings and keys from <workspace> once and copies them; the originals stay put.
  • lousho studio --prod/--dev now only apply inside the SDK’s own repository checkout; an installed Studio is always the production build.
  • A workspace’s agents run on the project’s own lousho through lousho bridge when the installed SDK is new enough; older SDKs make the workspace read-only until updated (the banner names the minimum). Studio and the SDK update independently.
See Lousho Studio for the full picture.

What 1.0 promises

Starting at 1.0 the package follows semver on its public surface:
  • Public: every entry point exports declares - the root lousho and the /executor, /tools, /flows, /integrations, /utils, /mcp, /types, /testing, /otel, /hooks, /sqlite, /auth, /kv, /worker, /traces, /triggers, /react, /vue and /svelte subpaths - and every name in the checked-in API reports (api/index.api.md, api/executor.api.md, … in the repository). Removing or renaming one, or changing a signature, needs a major version.
  • Internal: everything else, including deep imports into dist/ or src/ (any path exports does not list) and names a public signature uses but does not export (the ae-forgotten-export entries in the reports). These can change in any release.
  • Deprecated: names marked @deprecated keep working through 1.x and are removed in 2.0.
CI compares the reports on every pull request, so a change to the public surface is always a deliberate, reviewed diff.