Add v0.6.0 release notes

release/notes/v0.6.0.md

@@ -0,0 +1,66 @@
+Lightspeed v0.6.0 hardens the agent core for very long-running work. Runs have no default limits, reduced state stays bounded, and a failure becomes an ordinary failed run carrying its real message. It adds explicit session restart, makes API vocabulary consistent, and gives the TypeScript SDK named helpers, a browser proxy, and run inspection tools.
+
+**Breaking changes and compatibility**
+
+- This is a **breaking release that requires fresh databases and a new Temporal namespace**. `scripts/release/workflow-compat.sh v0.5.1` reports `breaking`. Stored event kinds, status values, wire values and bot columns are renamed, and what reduced state keeps is bounded, with no conversion: a session log written by an earlier build does not decode on this one.
+- **Do not point v0.6.0 at a v0.5.1 database.** Runtime schema revision is **14**. Migrations 013 and 014 rewrite nothing, so a database holding earlier bot values or `native` MCP rows fails them at `migrate`. Migration 014 also renames a `sessions` column, which stops an older runtime reading that table. Do not bypass these failures.
+- `session/managed/start` is removed. Use `session/start` with an `integration` for immutable lifecycle and workflow-tool setup. Retrying `session/start` restarts a stopped ordinary session, while a session with an `integration` reports `sessionExecutionStopped` until `session/restart` is called.
+- Every API enum and error kind is now camelCase, so update clients and dashboards that read the old values. MCP `execution: native` becomes `runtime`, including `lightspeed mcp put --execution`, and is refused under the old name. New MCP servers default to the runtime path. The `managed` flag and filter become `lifecycleControlled`, and a run's `completedAtMs` becomes `finishedAtMs`. `session/list` rejects unknown params.
+- `limits.maxToolRounds` is removed, and `limits.maxTurns` is enforced only when set. Sub-agent `maxDescendants` is removed: `maxConcurrent` now counts open descendants across the tree, defaults to 8, and refuses a spawn at the limit rather than queueing it.
+- A session remembers its most recent 256 finished runs and 256 promises, and a run its last 64 steering batches. A submission retried beyond those windows starts new work, an await on a pruned promise reports that it is no longer retained, and a repeated approval decision after pruning gets `notFound`.
+- The public API protocol identifier remains `lightspeed.agent.api.v1`, envd and controller protocols remain **4**, and Platform schema revision remains **4**. These unchanged values do not promise compatibility with old sessions or workflow histories. Use matching clients and components from one release manifest.
+
+**Fresh installation and moving from v0.5.1**
+
+There is no supported in-place upgrade or data-preserving conversion from v0.5.1. If old data must remain accessible, keep the old installation and its recovery set separately.
+
+1. Stop new work in the old installation and drain or cancel affected runs. Preserve its release, configuration, secrets and a coordinated backup of the runtime and Platform databases and object storage. Keep the old Temporal namespace available for inspection until you retire it, and retire it then, because bot schedules left in it start workflows that nothing runs.
+2. Provision fresh runtime and Platform databases, separate object storage or an isolated prefix, and a new Temporal namespace. Set `TEMPORAL_NAMESPACE` to it on every runtime process, on the connector host, and on any custom worker running your workflow tools. Set the runtime's `LIGHTSPEED_POSTGRES_URL` to the **fresh runtime database**, then run these with the v0.6.0 executable:
+
+   ```bash
+   lightspeed-runtime migrate
+   lightspeed-runtime schema-version
+   ```
+
+   Require runtime schema revision 14 before starting services. Normal runtime startup verifies the ledger but does not migrate.
+3. Start matching runtime, Platform, Configurator, connector and client components from one manifest.
+4. Set up accounts, universes, API keys, credentials, profiles, workspaces, MCP servers, bots and optional connectors again. Nothing in the old databases carries over. Update integrations for the renames above, and pin `@lightspeed-ai/sdk` to `0.6.0` if you rely on its types.
+5. Verify sign-in, universe access, a new session and a small tool run before opening ingress. Reconcile any external effects from old work before resubmitting it.
+
+From this release on, release notes state whether a release is `restart-in-place` or `breaking`. See [Upgrades and recovery](https://ls.bot/docs/deployment/upgrades-and-recovery/) for how later breaking releases move to a new namespace while keeping the runtime database, what each kind of open work does afterwards, and how to [restart a stopped session](https://ls.bot/docs/deployment/upgrades-and-recovery/#restart-a-stopped-session).
+
+**Long-running agents**
+
+- Runs have no default turn limit. Reduced session state is bounded by design, and older runs are served from the session log. `session/read` needs no worker and reports `executionFailure` when an open session's workflow has stopped.
+- Failures, including store data rejections, end as failed runs with their real message and a typed kind instead of ending the workflow, and a refused command rejects only that command. Open tool groups are closed, and steering input is kept when a run fails, though cancellation drops it. Caller errors are typed, including `operationPending` for a command still held and `sessionExecutionStopped` for a stopped workflow.
+- `session/restart`, also available as `lightspeed session restart` and from the session banner, brings a stopped session back from its log. A run that was executing fails, so no tool call runs twice, and a parked run keeps waiting. Nothing restarts a session automatically.
+- Automatic compaction gains failure backoff, run-bound proactive compaction and an entry-count trigger. At 2,000 active entries a run makes one more compaction attempt and fails if the count stays that high. Input that can never fit is refused, and a compaction failure names the largest entry. Sessions with compaction explicitly disabled fail every run past that count until compaction is enabled or run.
+- Very long runs return their opening and most recent turns with `earlierEventsOmitted`. `session/events/read` serves the rest; paged run detail is a follow-up.
+
+**Tools and MCP**
+
+- Tool batches dispatch per call, so a spawn beside an approval-gated call waits for the decision. Await and join results report what actually happened, approvals are scoped to their batch, and a run can have 32 invocations of one workflow tool waiting on a promise at once.
+- Native MCP output is bounded and the last known tool list is retained. A disabled MCP server degrades at preparation instead of failing setup. An admin's change to a server's URL or auth applies at once, including to an already approved call.
+- `apply_patch` is atomic and VFS writes are versioned. Sub-agents have no default deadline, and `run_timeout_ms` is optional.
+- Provider errors are classified more accurately, including Anthropic context overflow, and a refused native compaction reports its category instead of an invalid response. Models can be switched within a route, and input capacity is resolved per run.
+
+**Bots**
+
+Bot deliveries no longer wedge on a dead session: the delivery fails and the bot rolls forward to a new generation, so that conversation restarts without earlier context. A force close notifies its controller. Moving to a new namespace also resets undelivered events, dedupe tails, daily budgets and group `/activation` settings, so drain first.
+
+**TypeScript SDK**
+
+- The client could not make a call from a browser, and now can. It also accepts `apiKey`, `universe` and `actor` options, and `withActor(id)` attributes a client's requests to a user.
+- About 50 named helpers such as `startSession`, `readRun` and `cancelRun` cover what most applications need. They return a method's data directly and take target IDs as positional arguments. `client.call` still reaches every method and returns the full envelope.
+- `createRpcProxy` from `@lightspeed-ai/sdk/server` lets a browser use the client without holding an API key. It forwards only listed methods, calls your `authorize` for each, and ignores any identity the browser sends. A universe is one readable namespace for a key allowed to read it, so `blobs/read` is not tied to a session.
+- `runTimeline` merges a run's messages and tool calls into one ordered list, and `readBlobText`, `readBlobBytes` and `putBlob` handle blob encoding. The [run inspector example](https://github.com/smartcomputer-ai/lightspeed/tree/v0.6.0/clients/typescript/examples/run-inspector) shows these together.
+- **Breaking:** `awaitRun` returns `{ run, cursor }` with the finished run, replacing `state` and `page`. `startRun` and `readEvents` return data rather than the envelope, and `onEvent` receives only the run's own events. `rpc.*` and `startRunWithSource` are removed. Aborts and timeouts reject with the signal's own reason rather than `LightspeedTransportError`, and error `kind` comes from the server.
+- `awaitRun` no longer hangs on a skipped event, a stopped workflow, a mistyped run or a run that already finished, and it retries its reads through network failures and stalled connections for about 30 seconds.
+
+**Validation limits**
+
+The hardening work passed the workspace tests and 40 of 41 live suites against a reset database on a new Temporal namespace. That live run predates the final `session/start` and SDK commits. The exception, `anthropic_messages_compaction_live`, fails because Anthropic's classifier refuses its fixtures at random. Not run: `runs_live_slow`, the OpenAI caching suites, the provider prompt and skills suites, `azure_blob_live` and `postgres_tls_live`.
+
+Moving a real installation with open work to a new namespace has not been exercised; the behaviour described in the upgrade guide comes from reading the code and from a live test that terminates workflows in its place, so try it on a copy before relying on it. The SDK's core flows ran live against a development stack and in a real browser, but 18 of its generated helpers, including `decideApprovals`, have not been called against a server.
+
+[Full changelog: v0.5.1...v0.6.0](https://github.com/smartcomputer-ai/lightspeed/compare/v0.5.1...v0.6.0)