Who needs this page
Anyone with code written against1.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 holdscreateAgent() 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 thesetType(...)call and theagentTypefield. A checkpoint saved withagentTypestill loads; the field is ignored.ExecuteOptions.onEventand theExecutionEvent/ExecutionEventTypetypes. PassonAgentEventtoAgentExecutor.execute()/stream()/resumeAfterApproval()instead; the events you now receive areAgentEvents. The event-name mapping is in Streaming. WithcreateAgent(),onEventalready receivesAgentEvents and is unchanged.createDelegateTool(),DelegateAgentOptions,DelegateAgentResultandDelegationDepthExceededError. Use thesubagentsoption oncreateAgent()orAgentExecutor.execute(): the model gets onetasktool per sub-agent, with a depth limit (maxSubagentDepth, default1) 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,AgentDefinitionandToolSetting. 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 ofcreateAgent({ 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
### Breakingsection; the notes below are the### Changedentries that alter behavior. - A tool whose
executereturns an async generator is now iterated - its last yielded value is the result - andAgentEventgainstool.partial(ToolPartialEvent); wrap a generator you mean to return as a value ({ items: generator }). See Tools and Stream events. AgentEventgains thehandoffevent andExecutionResultthe optionalagentName: an exhaustiveswitchoverevent.typeneeds ahandoffcase. See Handoffs.McpServerStatusgains'needs-auth'andAgentOAuthgainsmcpSignInUrl(server): an exhaustiveswitchoverconnectMcp().status()needs the new case. See MCP and OAuth.ToolExecutionContextgainsgetToken(provider)andrequireAuth(provider), andApprovalKindgains'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()andexecute()now stream model calls: a step’s text arrives as severaltext.deltaevents instead of one.execute({ streamModelCalls: false })restores the old shape. See Stream events. MockLLMProvider/createMockProvider():stream()now streams the same stepgenerate()returns - the same tool calls, finish reason and usage - so a streamed mock run calls tools assend()does. See Testing.- Agent Forge runs stream their model calls; the chat, logs and trace views are unchanged. See Agent Forge.
lousho init --provider ollamanow scaffoldsai@^7withollama-ai-provider-v2@^4andzod@^4(it wasai@^4withollama-ai-provider@^1and 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 rejectsagent.approvals.resolve()too. See Durable execution. lousho addenforces the registry permission manifest at install, and a loaded agent directory runs each item’s tools inside its accepted manifest (approval always on forexec/needsApproval/unattested items,fetchandprocess.envscoped to the declaration); mismatched code is refused withLOUSHO_REGISTRY_MANIFEST_MISMATCH, and--yesneeds--allowfor elevated permissions. See Registry.- Continuing an unfinished checkpointed run with a
principalother than the one it was saved with now throwsLOUSHO_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 by1.0.0-alpha.19or earlier are not read any more; runmigrateMemoryKeys(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(theirsourcesstill resolve to the shippedsrc/). 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 aslousho-studio and is no longer
part of the lousho tarball. What to do:
- Install it once:
npm i -g lousho-studio, then runlousho-studio. Or runnpx lousho-studio.lousho studioinside a project keeps working - it finds the installed Studio and opens that folder as a workspace; with none installed it printsStudio 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/--devnow 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
loushothroughlousho bridgewhen 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.
What 1.0 promises
Starting at 1.0 the package follows semver on its public surface:- Public: every entry point
exportsdeclares - the rootloushoand the/executor,/tools,/flows,/integrations,/utils,/mcp,/types,/testing,/otel,/hooks,/sqlite,/auth,/kv,/worker,/traces,/triggers,/react,/vueand/sveltesubpaths - 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/orsrc/(any pathexportsdoes not list) and names a public signature uses but does not export (theae-forgotten-exportentries in the reports). These can change in any release. - Deprecated: names marked
@deprecatedkeep working through 1.x and are removed in 2.0.