Developer workflow for the agent runtime (src/agent/agents/) in the Apus repo.

Type checking and linting

• Default local gate: pnpm check (typecheck, lint, policy guards)
• Build gate: pnpm build when the change can affect build output, packaging, or lazy-loading/module boundaries
• Full pre-push gate: pnpm build && pnpm check && pnpm check:test-types && pnpm test

Running Agent Runtime Tests

Run the agent runtime unit suites:

pnpm test \
  "src/agent/agents/agent-*.test.ts" \
  "src/agent/agents/embedded-agent-*.test.ts" \
  "src/agent/agents/agent-hooks/**/*.test.ts"

The first glob also covers the agent-tools*, agent-settings, and agent-tool-definition-adapter* suites.

Live tests are excluded from the unit config; run them through the live wrapper (sets APUS_LIVE_TEST=1 and needs provider credentials):

pnpm test:live src/agent/agents/embedded-agent-runner-extraparams.live.test.ts

Manual testing

• Run the Gateway in dev mode (skips channel connections via APUS_SKIP_CHANNELS=1): pnpm gateway:dev
• Trigger one agent turn through the Gateway: pnpm apus agent --message "Hello" --thinking low
• Use the TUI for interactive debugging: pnpm tui

For tool call behavior, prompt for a read or exec action so you can watch tool streaming and payload handling.

Clean slate reset

State lives in the Apus state directory: ~/.apus by default, or $APUS_STATE_DIR when set. Paths relative to that directory:

Delete those paths for a full reset. Narrower resets:

• Sessions only: do not delete agents/<agentId>/agent/apus-agent.sqlite; session rows live there alongside other per-agent state. Use /new or /reset to start a fresh session for one chat, and apus sessions cleanup for session maintenance.
• Keep auth: leave agents/<agentId>/agent/apus-agent.sqlite and credentials/ in place.

Legacy auth-profiles.json files are no longer read at runtime; apus doctor --fix imports them into the SQLite store.

• Apus agent runtime architecture
• Testing
• Getting Started