Migration

Migration guide

Use this guide when upgrading an app to 0.2.0-beta.0. This release includes breaking config and file-convention changes. Read the full root CHANGELOG.md before upgrading production bots.

Before upgrading

  1. Stop the running heypi process.
  2. Back up state/ and workspace/.
  3. Update packages.
  4. Run diagnostics before starting traffic again:
npm exec heypi -- doctor --boot --env .env --db ./state/heypi.db --runtime-root ./workspace

Agent files

Rename old prompt convention files:

agent/AGENTS.md -> agent/instructions.md
agent/SOUL.md   -> merge into agent/instructions.md
agent/SYSTEM.md -> agent/system.md

instructions.md is the primary app instruction file. system.md is optional and replaces heypi's generated system prompt when present.

Built-in tools

Move built-in runtime tools from tools to builtinTools:

// Before
loadAgent("./agent", {
  tools: defaultTools(),
});

// After
loadAgent("./agent", {
  builtinTools: defaultTools(),
});

Use tools only for trusted authored JavaScript tools. loadAgent("./agent") discovers authored tools from agent/tools/ by default.

Agent id

loadAgent() now defaults the durable agent id to default. If an existing app relied on the old folder-basename id and must keep reading the same persisted threads, approvals, jobs, and traces, set id explicitly:

loadAgent("./agent", {
  id: "agent",
});

New apps should usually keep the default id.

Adapter responses

Response placement moved into adapter-local response objects.

Slack:

// Before
slack({
  reply: "thread",
  replyBroadcast: false,
});

// After
slack({
  response: { placement: "thread", broadcast: false },
});

Discord and Telegram use the same response.placement shape for their supported placements. See each adapter page for provider-specific options.

Admin HTTP

Admin no longer shares the public adapter HTTP listener. It has its own admin.http, defaulting to 127.0.0.1:4321.

createHeypi({
  http: { host: "0.0.0.0", port: 3000 },
  admin: {
    http: { host: "127.0.0.1", port: 4321 },
    secret: process.env.HEYPI_ADMIN_SECRET!,
  },
});

heypi dev enables admin by default when admin is omitted. heypi start does not; set admin: true or admin: { ... } explicitly when you want admin in normal runtime.

Evals

Behavior eval discovery moved to root evals/:

agent/evals/ -> evals/

Author eval files with defineEval() from @hunvreus/heypi/authoring, then inspect them with:

npm exec heypi -- eval check --evals ./evals

Reply URLs

Webhook replyUrl callbacks require HTTPS by default. For stricter callback routing, prefer replyUrls or replyOrigins allowlists. Plain HTTP callbacks require unsafeReplyHttp: true and should be limited to trusted local or private networks.