49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# Token Optimization Implementation Report
|
|
|
|
Implemented the token-optimization plan across heartbeat orchestration, issue context APIs, adapter prompt construction, skill exposure, and agent configuration UX.
|
|
|
|
The main behavior changes are:
|
|
|
|
- Heartbeat telemetry now normalizes sessioned local adapter usage as per-run deltas instead of blindly trusting cumulative session totals.
|
|
- Timer and manual wakes now preserve task sessions by default; fresh sessions are forced only for explicit `forceFreshSession` wakes or new issue assignment wakes.
|
|
- Heartbeat session rotation is now policy-driven in the control plane, with a handoff note injected when a session is compacted and restarted.
|
|
- Paperclip issue context now has incremental APIs: `GET /api/agents/me/inbox-lite`, `GET /api/issues/:id/heartbeat-context`, and comment delta queries via `GET /api/issues/:id/comments?after=...&order=asc`.
|
|
- The `paperclip` skill now teaches agents to use those compact/incremental APIs first, while keeping full-thread fetches as a cold-start fallback.
|
|
- All local adapters now separate first-session bootstrap prompts from per-heartbeat prompt templates, and emit prompt size metrics in invocation metadata.
|
|
- Adapter create flows now persist `bootstrapPromptTemplate` correctly.
|
|
- The agent config UI now explains the difference between bootstrap prompts and heartbeat prompts and warns about prompt churn.
|
|
- Runtime skill defaults now include `paperclip`, `para-memory-files`, and `paperclip-create-agent`. `create-agent-adapter` was moved to `.agents/skills/create-agent-adapter`.
|
|
|
|
Important follow-up finding from real-run review:
|
|
|
|
- `codex_local` currently injects Paperclip skills into the shared Codex skills home (`$CODEX_HOME/skills` or `~/.codex/skills`) rather than mounting a worktree-local skill directory.
|
|
- If a Paperclip-owned skill symlink already points at another live checkout, the adapter currently skips it instead of repointing it.
|
|
- In practice, this means a worktree can contain newer `skills/paperclip/SKILL.md` guidance while Codex still follows an older checkout's skill content.
|
|
- That likely explains why PAP-507 still showed full issue/comment reload behavior even though the incremental context work was already implemented in this branch.
|
|
- This should be treated as a separate follow-up item for `codex_local` skill isolation or symlink repair.
|
|
|
|
Files with the most important implementation work:
|
|
|
|
- `server/src/services/heartbeat.ts`
|
|
- `server/src/services/issues.ts`
|
|
- `server/src/routes/issues.ts`
|
|
- `server/src/routes/agents.ts`
|
|
- `server/src/routes/access.ts`
|
|
- `skills/paperclip/SKILL.md`
|
|
- `packages/adapters/*/src/server/execute.ts`
|
|
- `packages/adapters/*/src/ui/build-config.ts`
|
|
- `ui/src/components/AgentConfigForm.tsx`
|
|
|
|
Verification completed successfully:
|
|
|
|
- `pnpm -r typecheck`
|
|
- `pnpm test:run`
|
|
- `pnpm build`
|
|
|
|
While verifying, I also fixed two existing embedded-postgres typing mismatches so repo-wide `typecheck` and `build` pass again:
|
|
|
|
- `packages/db/src/migration-runtime.ts`
|
|
- `cli/src/commands/worktree.ts`
|
|
|
|
Next useful follow-up is measuring the before/after effect in real runs now that telemetry is less misleading and prompt/session reuse behavior is consistent across adapters.
|