Debug and test

Debug and Test

Contract

By the end of this skill the agent can:

• Build the package locally (pnpm --filter @hec-ovi/agentickit build).
• Run the test suite (pnpm --filter @hec-ovi/agentickit test).
• Run the todo example against the local package (pnpm --filter @agentickit-examples/todo dev).
• Diagnose the most common failure modes with a specific fix.

Iron Law: reproduce before you change

Never attempt a fix without first seeing the failure locally. The pnpm workspace links agentickit from packages/agentickit/dist/ into the example. If dist/ is stale, the example runs last build's behavior and your "fix" targets the wrong tree. pnpm --filter @hec-ovi/agentickit build before every reproduction, no exceptions.

Phases

Phase 1: understand the layout

agentickit/
  package.json              # workspace root (declares pnpm workspaces)
  pnpm-workspace.yaml       # workspace globs
  packages/
    agentickit/             # the published package
      src/
        index.ts            # public client exports
        hooks/              # usePilotState, usePilotAction, usePilotForm
        components/         # <Pilot>, <PilotSidebar>
        server/             # createPilotHandler
        protocol/           # .pilot/ loader
      dist/                 # tsup output, regenerated on build
      tsup.config.ts
      vitest.config.ts
  examples/
    todo/                   # consumes agentickit via the workspace link
      app/
        api/pilot/route.ts
        page.tsx

Always use absolute paths from repo root when editing. Never cd.

Phase 2: build the package

cd /home/hector/workspace/test-task/agentickit
pnpm --filter @hec-ovi/agentickit build

Runs tsup (config at packages/agentickit/tsup.config.ts), producing three entry points under dist/: index, server, protocol. Each ships ESM + CJS + .d.ts.

If the build fails with a TypeScript error, the src/ tree has a real type bug. Fix the source, not the build config.

Phase 3: run the tests

pnpm --filter @hec-ovi/agentickit test

Runs Vitest once (vitest run in package.json scripts). Happy-DOM environment. Fast; no external network.

For watch mode during iteration:

pnpm --filter @hec-ovi/agentickit test:watch

Phase 4: run the example

pnpm --filter @agentickit-examples/todo dev

Starts Next.js on port 3000 against a fresh build of agentickit.

Before running, set a provider env var in examples/todo/.env.local:

OPENROUTER_API_KEY=sk-or-v1-...

(See skills/choose-provider/SKILL.md for the supported keys.)

The example's route at examples/todo/app/api/pilot/route.ts omits model; it relies on auto-detection. See skills/install-and-setup/SKILL.md for the auto-detect priority list.

Phase 5: rebuild-and-retry after source edits

The example imports from the built dist/ via the workspace link, so:

pnpm --filter @hec-ovi/agentickit build && pnpm --filter @agentickit-examples/todo dev

For an iteration loop:

pnpm --filter @hec-ovi/agentickit dev   # tsup --watch in one terminal
pnpm --filter @agentickit-examples/todo dev   # next dev in another

Phase 6: common failure modes

Symptom	Likely cause	Fix
Example imports but types are any	Stale dist/	pnpm --filter @hec-ovi/agentickit build
"no model configured" on first message	No env var in example .env.local	Set OPENROUTER_API_KEY (or another supported key)
500 MODULE_NOT_FOUND for @ai-sdk/xxx	Env var set but adapter not installed in the example	cd examples/todo && npm install @ai-sdk/<provider>
Sidebar renders but no messages appear	<PilotSidebar> outside <Pilot> tree	Move sidebar inside the provider
usePilotAction warning in console, no tool call	Hook called outside <Pilot>	Move the hook into a descendant of the provider
Manifest fetch fails silently	.pilot/ folder not under public/	Move to public/pilot/ so Next.js serves it
Tool call stalls the loop	Registered handler throws before addToolOutput	Catch in handler, return { ok: false, reason }
Two tool calls with same name execute twice	Two components registered the same name	Pick unique names; check dev-mode warning

Phase 7: where to look when the code disagrees with the docs

Priority order, always:

1. packages/agentickit/src/: the source.
2. Tests under the same tree (if present): executable contract.
3. README.md and packages/agentickit/README.md: consumer-facing narrative.
4. .pilot/skills/*: agent procedures.

If a .pilot/skill disagrees with (1) or (2), the skill is out of date. Fix the skill. Report the drift in your final message.

Anti-Patterns

• Editing dist/ directly. It's regenerated on every build.
• Using npm install at the workspace root. Use pnpm install; this is a pnpm workspace and npm install will fight the lockfile.
• Bypassing the workspace link by installing agentickit from npm into the example. The local source becomes invisible to the running example; you'll chase ghosts.
• Running tests against the published package instead of src/. Vitest reads from src/ via the config at packages/agentickit/vitest.config.ts; there's no reason to publish-and-retry.

Output Format

After a debugging session, report:

• The exact command sequence that reproduced the failure.
• The file and line number of the root cause.
• The fix (as a diff summary, not a full patch; the caller can read the file).
• Any drift between docs and code you noticed along the way.

Tools Used

• pnpm --filter @hec-ovi/agentickit build / test / dev.
• pnpm --filter @agentickit-examples/todo dev.
• Read source files under packages/agentickit/src/.