Migrate from 0.13

This hop replaces the 0.13 Hono + agent.run() + AG-UI starter. Upgrade the compatibility set together. After you reach 0.15, continue with 0.15 → 0.17.

Historical mentions of Agent from Harness, agent.run(), new Runtime(), serveAgents, --agent-url, AG-UI, Node 22.19, and memory-by-default storage belong on this page only. They are not the current default path.

1. Require Node 24.
2. Author with import { Agent, tool } from "@nylorun/agents". Export agents from agents/index.ts. Remove agent.run().
3. Install @nylorun/cli for nylorun configure, dev, serve, and studio. The binary is no longer owned by Runtime. (0.15 docs said nylorun start; that command is removed in 0.17 — use serve.)
4. Delete the generated Hono src/index.ts, new Runtime(), serveAgents, and openSession usage. Compiled start loads dist/agents/index.js.
5. Point Studio at the Runtime origin (http://127.0.0.1:8787). Remove AG-UI and --agent-url mount paths. Default Runtime port is 8787, not 3000.
6. Import explicit engine execution from @nylorun/harness/run (run, bindingFromAgent, RunBinding, createRunState, runDurable).
7. Prefer tool input / output / run. Keep effects and approval off the manifest.
8. On 0.15, durable definitions used the old hook names. 0.17 replaces them with before("turn"|"step") and after("step"|"turn"). See 0.15 → 0.17.
9. Treat .nylorun/runtime.sqlite as the local store. Old SessionRecord / events.jsonl roots are not converted. Start new sessions after definition changes.

Custom backends use createClient (trusted ownerUserId, content, idempotency keys) and connectAgents with scoped executor credentials.

Update an existing generated project (0.4 env / exported-app)

These steps applied to the 0.13 Hono starter. They are not sufficient for 0.15 — continue with the section above, or generate a new project.

1. Back up any existing .env/ directory and leftover config/model.json outside the project. Translate model.json fields provider, model, and custom.baseUrl into MODEL_PROVIDER, MODEL, and MODEL_PROVIDER_BASE_URL. Copy API keys into MODEL_PROVIDER_API_KEY or provider-native variables. Replace NYLO_CUSTOM_API_KEY with MODEL_PROVIDER_API_KEY. Merge integrations.env into .env. Move OAuth records into .nylorun/auth.json.
2. Add .env, .env.local, and .nylorun/ to .gitignore. Remove old .env/ exceptions.
3. On 0.13 only: replace serve(...) with export default app and set "dev": "nylorun dev". On 0.15 the entrypoint is the agents registry, not a Hono default export.

0.13 / 0.5 execution migration

Historical hop from the session-object API to await agent.run({ input, state }), info instead of scope, capability catalogs, and @nylorun/runtime/node adapters. That surface is not the current application path: definitions no longer expose run(), and the starter no longer constructs new Runtime(). Keep this section only if you are reading old 0.13 code.

1. Replace agent.run() session objects with await agent.run({ input, state, ... }) (0.13 hosts). Statuses are completed, paused, cancelled, and failed.
2. Move scope and userId / context to info on run(), or Runtime getInfo.
3. Move outputSchema onto Agent({ ... }). There is no per-input schema.
4. Remove capability state factories. Create and close resources in the application.
5. Import Node adapters from leftover 0.13 hosts only. They are not the current starter path.
6. Treat old session journals as archive. SessionRecord / events.jsonl are not ExecutionState and are not auto-replayed.