diff --git a/skills/create-agent-adapter/SKILL.md b/.agents/skills/create-agent-adapter/SKILL.md similarity index 100% rename from skills/create-agent-adapter/SKILL.md rename to .agents/skills/create-agent-adapter/SKILL.md diff --git a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md index 678444ac..e85cfdfc 100644 --- a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md +++ b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md @@ -121,7 +121,7 @@ Local adapters inject repo skills into runtime skill directories. Current repo skill sizes: - `skills/paperclip/SKILL.md`: 17,441 bytes -- `skills/create-agent-adapter/SKILL.md`: 31,832 bytes +- `.agents/skills/create-agent-adapter/SKILL.md`: 31,832 bytes - `skills/paperclip-create-agent/SKILL.md`: 4,718 bytes - `skills/para-memory-files/SKILL.md`: 3,978 bytes diff --git a/docs/adapters/creating-an-adapter.md b/docs/adapters/creating-an-adapter.md index e33b5411..fae0e4b3 100644 --- a/docs/adapters/creating-an-adapter.md +++ b/docs/adapters/creating-an-adapter.md @@ -6,7 +6,7 @@ summary: Guide to building a custom adapter Build a custom adapter to connect Paperclip to any agent runtime. -If you're using Claude Code, the `create-agent-adapter` skill can guide you through the full adapter creation process interactively. Just ask Claude to create a new adapter and it will walk you through each step. +If you're using Claude Code, the `.agents/skills/create-agent-adapter` skill can guide you through the full adapter creation process interactively. Just ask Claude to create a new adapter and it will walk you through each step. ## Package Structure diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts index 30f0c9bd..52e52b4c 100644 --- a/packages/adapter-utils/src/server-utils.ts +++ b/packages/adapter-utils/src/server-utils.ts @@ -112,6 +112,16 @@ export function renderTemplate(template: string, data: Record) return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path) => resolvePathValue(data, path)); } +export function joinPromptSections( + sections: Array, + separator = "\n\n", +) { + return sections + .map((value) => (typeof value === "string" ? value.trim() : "")) + .filter(Boolean) + .join(separator); +} + export function redactEnvForLogs(env: Record): Record { const redacted: Record = {}; for (const [key, value] of Object.entries(env)) { diff --git a/packages/adapter-utils/src/types.ts b/packages/adapter-utils/src/types.ts index 6503e5a1..df0d075a 100644 --- a/packages/adapter-utils/src/types.ts +++ b/packages/adapter-utils/src/types.ts @@ -99,6 +99,7 @@ export interface AdapterInvocationMeta { commandNotes?: string[]; env?: Record; prompt?: string; + promptMetrics?: Record; context?: Record; } diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.ts index be85439d..13d92df8 100644 --- a/packages/adapters/claude-local/src/server/execute.ts +++ b/packages/adapters/claude-local/src/server/execute.ts @@ -12,6 +12,7 @@ import { parseObject, parseJson, buildPaperclipEnv, + joinPromptSections, redactEnvForLogs, ensureAbsoluteDirectory, ensureCommandResolvable, @@ -363,7 +364,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); + const prompt = joinPromptSections([ + renderedBootstrapPrompt, + sessionHandoffNote, + renderedPrompt, + ]); + const promptMetrics = { + promptChars: prompt.length, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + heartbeatPromptChars: renderedPrompt.length, + }; const buildClaudeArgs = (resumeSessionId: string | null) => { const args = ["--print", "-", "--output-format", "stream-json", "--verbose"]; @@ -416,6 +435,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); + const prompt = joinPromptSections([ + instructionsPrefix, + renderedBootstrapPrompt, + sessionHandoffNote, + renderedPrompt, + ]); + const promptMetrics = { + promptChars: prompt.length, + instructionsChars, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + heartbeatPromptChars: renderedPrompt.length, + }; const buildArgs = (resumeSessionId: string | null) => { const args = ["exec", "--json"]; @@ -346,6 +368,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); const paperclipEnvNote = renderPaperclipEnvNote(env); - const prompt = `${instructionsPrefix}${paperclipEnvNote}${renderedPrompt}`; + const prompt = joinPromptSections([ + instructionsPrefix, + renderedBootstrapPrompt, + sessionHandoffNote, + paperclipEnvNote, + renderedPrompt, + ]); + const promptMetrics = { + promptChars: prompt.length, + instructionsChars, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + runtimeNoteChars: paperclipEnvNote.length, + heartbeatPromptChars: renderedPrompt.length, + }; const buildArgs = (resumeSessionId: string | null) => { const args = ["-p", "--output-format", "stream-json", "--workspace", cwd]; @@ -340,6 +364,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); const paperclipEnvNote = renderPaperclipEnvNote(env); const apiAccessNote = renderApiAccessNote(env); - const prompt = `${instructionsPrefix}${paperclipEnvNote}${apiAccessNote}${renderedPrompt}`; + const prompt = joinPromptSections([ + instructionsPrefix, + renderedBootstrapPrompt, + sessionHandoffNote, + paperclipEnvNote, + apiAccessNote, + renderedPrompt, + ]); + const promptMetrics = { + promptChars: prompt.length, + instructionsChars: instructionsPrefix.length, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length, + heartbeatPromptChars: renderedPrompt.length, + }; const buildArgs = (resumeSessionId: string | null) => { const args = ["--output-format", "stream-json"]; @@ -309,6 +332,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); + const prompt = joinPromptSections([ + instructionsPrefix, + renderedBootstrapPrompt, + sessionHandoffNote, + renderedPrompt, + ]); + const promptMetrics = { + promptChars: prompt.length, + instructionsChars: instructionsPrefix.length, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + heartbeatPromptChars: renderedPrompt.length, + }; const buildArgs = (resumeSessionId: string | null) => { const args = ["run", "--format", "json"]; @@ -264,6 +284,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise`], env: redactEnvForLogs(env), prompt, + promptMetrics, context, }); } diff --git a/packages/adapters/opencode-local/src/ui/build-config.ts b/packages/adapters/opencode-local/src/ui/build-config.ts index 3abfd6cd..0d425cf1 100644 --- a/packages/adapters/opencode-local/src/ui/build-config.ts +++ b/packages/adapters/opencode-local/src/ui/build-config.ts @@ -55,6 +55,7 @@ export function buildOpenCodeLocalConfig(v: CreateConfigValues): Record 0 + ? renderTemplate(bootstrapPromptTemplate, templateData).trim() + : ""; + const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim(); + const userPrompt = joinPromptSections([ + renderedBootstrapPrompt, + sessionHandoffNote, + renderedHeartbeatPrompt, + ]); + const promptMetrics = { + systemPromptChars: renderedSystemPromptExtension.length, + promptChars: userPrompt.length, + bootstrapPromptChars: renderedBootstrapPrompt.length, + sessionHandoffChars: sessionHandoffNote.length, + heartbeatPromptChars: renderedHeartbeatPrompt.length, + }; const commandNotes = (() => { if (!resolvedInstructionsFilePath) return [] as string[]; @@ -345,6 +355,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise; diff --git a/report/2026-03-13-08-46-token-optimization-implementation.md b/report/2026-03-13-08-46-token-optimization-implementation.md new file mode 100644 index 00000000..9bee83ca --- /dev/null +++ b/report/2026-03-13-08-46-token-optimization-implementation.md @@ -0,0 +1,40 @@ +# 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`. + +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. diff --git a/server/src/__tests__/heartbeat-workspace-session.test.ts b/server/src/__tests__/heartbeat-workspace-session.test.ts index 650556d1..bca52142 100644 --- a/server/src/__tests__/heartbeat-workspace-session.test.ts +++ b/server/src/__tests__/heartbeat-workspace-session.test.ts @@ -93,16 +93,26 @@ describe("shouldResetTaskSessionForWake", () => { expect(shouldResetTaskSessionForWake({ wakeReason: "issue_assigned" })).toBe(true); }); - it("resets session context on timer heartbeats", () => { - expect(shouldResetTaskSessionForWake({ wakeSource: "timer" })).toBe(true); + it("preserves session context on timer heartbeats", () => { + expect(shouldResetTaskSessionForWake({ wakeSource: "timer" })).toBe(false); }); - it("resets session context on manual on-demand invokes", () => { + it("preserves session context on manual on-demand invokes by default", () => { expect( shouldResetTaskSessionForWake({ wakeSource: "on_demand", wakeTriggerDetail: "manual", }), + ).toBe(false); + }); + + it("resets session context when a fresh session is explicitly requested", () => { + expect( + shouldResetTaskSessionForWake({ + wakeSource: "on_demand", + wakeTriggerDetail: "manual", + forceFreshSession: true, + }), ).toBe(true); }); diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts index c13366ff..ee156091 100644 --- a/server/src/routes/access.ts +++ b/server/src/routes/access.ts @@ -97,7 +97,11 @@ function requestBaseUrl(req: Request) { function readSkillMarkdown(skillName: string): string | null { const normalized = skillName.trim().toLowerCase(); - if (normalized !== "paperclip" && normalized !== "paperclip-create-agent") + if ( + normalized !== "paperclip" && + normalized !== "paperclip-create-agent" && + normalized !== "para-memory-files" + ) return null; const moduleDir = path.dirname(fileURLToPath(import.meta.url)); const candidates = [ @@ -1610,6 +1614,10 @@ export function accessRoutes( res.json({ skills: [ { name: "paperclip", path: "/api/skills/paperclip" }, + { + name: "para-memory-files", + path: "/api/skills/para-memory-files" + }, { name: "paperclip-create-agent", path: "/api/skills/paperclip-create-agent" diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts index b1b53759..6c60b644 100644 --- a/server/src/routes/agents.ts +++ b/server/src/routes/agents.ts @@ -575,6 +575,34 @@ export function agentRoutes(db: Db) { res.json({ ...agent, chainOfCommand }); }); + router.get("/agents/me/inbox-lite", async (req, res) => { + if (req.actor.type !== "agent" || !req.actor.agentId || !req.actor.companyId) { + res.status(401).json({ error: "Agent authentication required" }); + return; + } + + const issuesSvc = issueService(db); + const rows = await issuesSvc.list(req.actor.companyId, { + assigneeAgentId: req.actor.agentId, + status: "todo,in_progress,blocked", + }); + + res.json( + rows.map((issue) => ({ + id: issue.id, + identifier: issue.identifier, + title: issue.title, + status: issue.status, + priority: issue.priority, + projectId: issue.projectId, + goalId: issue.goalId, + parentId: issue.parentId, + updatedAt: issue.updatedAt, + activeRun: issue.activeRun, + })), + ); + }); + router.get("/agents/:id", async (req, res) => { const id = req.params.id as string; const agent = await svc.getById(id); @@ -1275,6 +1303,7 @@ export function agentRoutes(db: Db) { contextSnapshot: { triggeredBy: req.actor.type, actorId: req.actor.type === "agent" ? req.actor.agentId : req.actor.userId, + forceFreshSession: req.body.forceFreshSession === true, }, }); diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts index f02067a6..bc938910 100644 --- a/server/src/routes/issues.ts +++ b/server/src/routes/issues.ts @@ -314,6 +314,79 @@ export function issueRoutes(db: Db, storage: StorageService) { }); }); + router.get("/issues/:id/heartbeat-context", async (req, res) => { + const id = req.params.id as string; + const issue = await svc.getById(id); + if (!issue) { + res.status(404).json({ error: "Issue not found" }); + return; + } + assertCompanyAccess(req, issue.companyId); + + const wakeCommentId = + typeof req.query.wakeCommentId === "string" && req.query.wakeCommentId.trim().length > 0 + ? req.query.wakeCommentId.trim() + : null; + + const [ancestors, project, goal, commentCursor, wakeComment] = await Promise.all([ + svc.getAncestors(issue.id), + issue.projectId ? projectsSvc.getById(issue.projectId) : null, + issue.goalId + ? goalsSvc.getById(issue.goalId) + : !issue.projectId + ? goalsSvc.getDefaultCompanyGoal(issue.companyId) + : null, + svc.getCommentCursor(issue.id), + wakeCommentId ? svc.getComment(wakeCommentId) : null, + ]); + + res.json({ + issue: { + id: issue.id, + identifier: issue.identifier, + title: issue.title, + description: issue.description, + status: issue.status, + priority: issue.priority, + projectId: issue.projectId, + goalId: goal?.id ?? issue.goalId, + parentId: issue.parentId, + assigneeAgentId: issue.assigneeAgentId, + assigneeUserId: issue.assigneeUserId, + updatedAt: issue.updatedAt, + }, + ancestors: ancestors.map((ancestor) => ({ + id: ancestor.id, + identifier: ancestor.identifier, + title: ancestor.title, + status: ancestor.status, + priority: ancestor.priority, + })), + project: project + ? { + id: project.id, + name: project.name, + status: project.status, + targetDate: project.targetDate, + } + : null, + goal: goal + ? { + id: goal.id, + title: goal.title, + status: goal.status, + level: goal.level, + parentId: goal.parentId, + } + : null, + commentCursor, + wakeComment: + wakeComment && wakeComment.issueId === issue.id + ? wakeComment + : null, + }); + }); + router.post("/issues/:id/read", async (req, res) => { const id = req.params.id as string; const issue = await svc.getById(id); @@ -791,7 +864,26 @@ export function issueRoutes(db: Db, storage: StorageService) { return; } assertCompanyAccess(req, issue.companyId); - const comments = await svc.listComments(id); + const afterCommentId = + typeof req.query.after === "string" && req.query.after.trim().length > 0 + ? req.query.after.trim() + : typeof req.query.afterCommentId === "string" && req.query.afterCommentId.trim().length > 0 + ? req.query.afterCommentId.trim() + : null; + const order = + typeof req.query.order === "string" && req.query.order.trim().toLowerCase() === "asc" + ? "asc" + : "desc"; + const limitRaw = + typeof req.query.limit === "string" && req.query.limit.trim().length > 0 + ? Number(req.query.limit) + : null; + const limit = limitRaw && Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : null; + const comments = await svc.listComments(id, { + afterCommentId, + order, + limit, + }); res.json(comments); }); diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts index f0665c9a..1a9dba74 100644 --- a/server/src/services/heartbeat.ts +++ b/server/src/services/heartbeat.ts @@ -18,7 +18,7 @@ import { logger } from "../middleware/logger.js"; import { publishLiveEvent } from "./live-events.js"; import { getRunLogStore, type RunLogHandle } from "./run-log-store.js"; import { getServerAdapter, runningProcesses } from "../adapters/index.js"; -import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec } from "../adapters/index.js"; +import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec, UsageSummary } from "../adapters/index.js"; import { createLocalAgentJwt } from "../agent-auth-jwt.js"; import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js"; import { costService } from "./costs.js"; @@ -47,6 +47,14 @@ const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 10; const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext"; const startLocksByAgent = new Map>(); const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__"; +const SESSIONED_LOCAL_ADAPTERS = new Set([ + "claude_local", + "codex_local", + "cursor", + "gemini_local", + "opencode_local", + "pi_local", +]); const heartbeatRunListColumns = { id: heartbeatRuns.id, @@ -117,6 +125,26 @@ interface WakeupOptions { contextSnapshot?: Record; } +type UsageTotals = { + inputTokens: number; + cachedInputTokens: number; + outputTokens: number; +}; + +type SessionCompactionPolicy = { + enabled: boolean; + maxSessionRuns: number; + maxRawInputTokens: number; + maxSessionAgeHours: number; +}; + +type SessionCompactionDecision = { + rotate: boolean; + reason: string | null; + handoffMarkdown: string | null; + previousRunId: string | null; +}; + interface ParsedIssueAssigneeAdapterOverrides { adapterConfig: Record | null; useProjectWorkspace: boolean | null; @@ -142,6 +170,88 @@ function readNonEmptyString(value: unknown): string | null { return typeof value === "string" && value.trim().length > 0 ? value : null; } +function normalizeUsageTotals(usage: UsageSummary | null | undefined): UsageTotals | null { + if (!usage) return null; + return { + inputTokens: Math.max(0, Math.floor(asNumber(usage.inputTokens, 0))), + cachedInputTokens: Math.max(0, Math.floor(asNumber(usage.cachedInputTokens, 0))), + outputTokens: Math.max(0, Math.floor(asNumber(usage.outputTokens, 0))), + }; +} + +function readRawUsageTotals(usageJson: unknown): UsageTotals | null { + const parsed = parseObject(usageJson); + if (Object.keys(parsed).length === 0) return null; + + const inputTokens = Math.max( + 0, + Math.floor(asNumber(parsed.rawInputTokens, asNumber(parsed.inputTokens, 0))), + ); + const cachedInputTokens = Math.max( + 0, + Math.floor(asNumber(parsed.rawCachedInputTokens, asNumber(parsed.cachedInputTokens, 0))), + ); + const outputTokens = Math.max( + 0, + Math.floor(asNumber(parsed.rawOutputTokens, asNumber(parsed.outputTokens, 0))), + ); + + if (inputTokens <= 0 && cachedInputTokens <= 0 && outputTokens <= 0) { + return null; + } + + return { + inputTokens, + cachedInputTokens, + outputTokens, + }; +} + +function deriveNormalizedUsageDelta(current: UsageTotals | null, previous: UsageTotals | null): UsageTotals | null { + if (!current) return null; + if (!previous) return { ...current }; + + const inputTokens = current.inputTokens >= previous.inputTokens + ? current.inputTokens - previous.inputTokens + : current.inputTokens; + const cachedInputTokens = current.cachedInputTokens >= previous.cachedInputTokens + ? current.cachedInputTokens - previous.cachedInputTokens + : current.cachedInputTokens; + const outputTokens = current.outputTokens >= previous.outputTokens + ? current.outputTokens - previous.outputTokens + : current.outputTokens; + + return { + inputTokens: Math.max(0, inputTokens), + cachedInputTokens: Math.max(0, cachedInputTokens), + outputTokens: Math.max(0, outputTokens), + }; +} + +function formatCount(value: number | null | undefined) { + if (typeof value !== "number" || !Number.isFinite(value)) return "0"; + return value.toLocaleString("en-US"); +} + +function parseSessionCompactionPolicy(agent: typeof agents.$inferSelect): SessionCompactionPolicy { + const runtimeConfig = parseObject(agent.runtimeConfig); + const heartbeat = parseObject(runtimeConfig.heartbeat); + const compaction = parseObject( + heartbeat.sessionCompaction ?? heartbeat.sessionRotation ?? runtimeConfig.sessionCompaction, + ); + const supportsSessions = SESSIONED_LOCAL_ADAPTERS.has(agent.adapterType); + const enabled = compaction.enabled === undefined + ? supportsSessions + : asBoolean(compaction.enabled, supportsSessions); + + return { + enabled, + maxSessionRuns: Math.max(0, Math.floor(asNumber(compaction.maxSessionRuns, 200))), + maxRawInputTokens: Math.max(0, Math.floor(asNumber(compaction.maxRawInputTokens, 2_000_000))), + maxSessionAgeHours: Math.max(0, Math.floor(asNumber(compaction.maxSessionAgeHours, 72))), + }; +} + export function resolveRuntimeSessionParamsForWorkspace(input: { agentId: string; previousSessionParams: Record | null; @@ -246,29 +356,20 @@ function deriveTaskKey( export function shouldResetTaskSessionForWake( contextSnapshot: Record | null | undefined, ) { + if (contextSnapshot?.forceFreshSession === true) return true; + const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason); if (wakeReason === "issue_assigned") return true; - - const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource); - if (wakeSource === "timer") return true; - - const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail); - return wakeSource === "on_demand" && wakeTriggerDetail === "manual"; + return false; } function describeSessionResetReason( contextSnapshot: Record | null | undefined, ) { + if (contextSnapshot?.forceFreshSession === true) return "forceFreshSession was requested"; + const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason); if (wakeReason === "issue_assigned") return "wake reason is issue_assigned"; - - const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource); - if (wakeSource === "timer") return "wake source is timer"; - - const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail); - if (wakeSource === "on_demand" && wakeTriggerDetail === "manual") { - return "this is a manual invoke"; - } return null; } @@ -501,6 +602,159 @@ export function heartbeatService(db: Db) { .then((rows) => rows[0] ?? null); } + async function getLatestRunForSession( + agentId: string, + sessionId: string, + opts?: { excludeRunId?: string | null }, + ) { + const conditions = [ + eq(heartbeatRuns.agentId, agentId), + eq(heartbeatRuns.sessionIdAfter, sessionId), + ]; + if (opts?.excludeRunId) { + conditions.push(sql`${heartbeatRuns.id} <> ${opts.excludeRunId}`); + } + return db + .select() + .from(heartbeatRuns) + .where(and(...conditions)) + .orderBy(desc(heartbeatRuns.createdAt)) + .limit(1) + .then((rows) => rows[0] ?? null); + } + + async function resolveNormalizedUsageForSession(input: { + agentId: string; + runId: string; + sessionId: string | null; + rawUsage: UsageTotals | null; + }) { + const { agentId, runId, sessionId, rawUsage } = input; + if (!sessionId || !rawUsage) { + return { + normalizedUsage: rawUsage, + previousRawUsage: null as UsageTotals | null, + derivedFromSessionTotals: false, + }; + } + + const previousRun = await getLatestRunForSession(agentId, sessionId, { excludeRunId: runId }); + const previousRawUsage = readRawUsageTotals(previousRun?.usageJson); + return { + normalizedUsage: deriveNormalizedUsageDelta(rawUsage, previousRawUsage), + previousRawUsage, + derivedFromSessionTotals: previousRawUsage !== null, + }; + } + + async function evaluateSessionCompaction(input: { + agent: typeof agents.$inferSelect; + sessionId: string | null; + issueId: string | null; + }): Promise { + const { agent, sessionId, issueId } = input; + if (!sessionId) { + return { + rotate: false, + reason: null, + handoffMarkdown: null, + previousRunId: null, + }; + } + + const policy = parseSessionCompactionPolicy(agent); + if (!policy.enabled) { + return { + rotate: false, + reason: null, + handoffMarkdown: null, + previousRunId: null, + }; + } + + const runs = await db + .select({ + id: heartbeatRuns.id, + createdAt: heartbeatRuns.createdAt, + usageJson: heartbeatRuns.usageJson, + resultJson: heartbeatRuns.resultJson, + error: heartbeatRuns.error, + }) + .from(heartbeatRuns) + .where(and(eq(heartbeatRuns.agentId, agent.id), eq(heartbeatRuns.sessionIdAfter, sessionId))) + .orderBy(desc(heartbeatRuns.createdAt)) + .limit(Math.max(policy.maxSessionRuns + 1, 4)); + + if (runs.length === 0) { + return { + rotate: false, + reason: null, + handoffMarkdown: null, + previousRunId: null, + }; + } + + const latestRun = runs[0] ?? null; + const oldestRun = runs[runs.length - 1] ?? latestRun; + const latestRawUsage = readRawUsageTotals(latestRun?.usageJson); + const sessionAgeHours = + latestRun && oldestRun + ? Math.max( + 0, + (new Date(latestRun.createdAt).getTime() - new Date(oldestRun.createdAt).getTime()) / (1000 * 60 * 60), + ) + : 0; + + let reason: string | null = null; + if (policy.maxSessionRuns > 0 && runs.length > policy.maxSessionRuns) { + reason = `session exceeded ${policy.maxSessionRuns} runs`; + } else if ( + policy.maxRawInputTokens > 0 && + latestRawUsage && + latestRawUsage.inputTokens >= policy.maxRawInputTokens + ) { + reason = + `session raw input reached ${formatCount(latestRawUsage.inputTokens)} tokens ` + + `(threshold ${formatCount(policy.maxRawInputTokens)})`; + } else if (policy.maxSessionAgeHours > 0 && sessionAgeHours >= policy.maxSessionAgeHours) { + reason = `session age reached ${Math.floor(sessionAgeHours)} hours`; + } + + if (!reason || !latestRun) { + return { + rotate: false, + reason: null, + handoffMarkdown: null, + previousRunId: latestRun?.id ?? null, + }; + } + + const latestSummary = summarizeHeartbeatRunResultJson(latestRun.resultJson); + const latestTextSummary = + readNonEmptyString(latestSummary?.summary) ?? + readNonEmptyString(latestSummary?.result) ?? + readNonEmptyString(latestSummary?.message) ?? + readNonEmptyString(latestRun.error); + + const handoffMarkdown = [ + "Paperclip session handoff:", + `- Previous session: ${sessionId}`, + issueId ? `- Issue: ${issueId}` : "", + `- Rotation reason: ${reason}`, + latestTextSummary ? `- Last run summary: ${latestTextSummary}` : "", + "Continue from the current task state. Rebuild only the minimum context you need.", + ] + .filter(Boolean) + .join("\n"); + + return { + rotate: true, + reason, + handoffMarkdown, + previousRunId: latestRun.id, + }; + } + async function resolveSessionBeforeForWakeup( agent: typeof agents.$inferSelect, taskKey: string | null, @@ -1016,9 +1270,10 @@ export function heartbeatService(db: Db) { run: typeof heartbeatRuns.$inferSelect, result: AdapterExecutionResult, session: { legacySessionId: string | null }, + normalizedUsage?: UsageTotals | null, ) { await ensureRuntimeState(agent); - const usage = result.usage; + const usage = normalizedUsage ?? normalizeUsageTotals(result.usage); const inputTokens = usage?.inputTokens ?? 0; const outputTokens = usage?.outputTokens ?? 0; const cachedInputTokens = usage?.cachedInputTokens ?? 0; @@ -1270,15 +1525,42 @@ export function heartbeatService(db: Db) { context.projectId = executionWorkspace.projectId; } const runtimeSessionFallback = taskKey || resetTaskSession ? null : runtime.sessionId; - const previousSessionDisplayId = truncateDisplayId( + let previousSessionDisplayId = truncateDisplayId( taskSessionForRun?.sessionDisplayId ?? (sessionCodec.getDisplayId ? sessionCodec.getDisplayId(runtimeSessionParams) : null) ?? readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback, ); + let runtimeSessionIdForAdapter = + readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback; + let runtimeSessionParamsForAdapter = runtimeSessionParams; + + const sessionCompaction = await evaluateSessionCompaction({ + agent, + sessionId: previousSessionDisplayId ?? runtimeSessionIdForAdapter, + issueId, + }); + if (sessionCompaction.rotate) { + context.paperclipSessionHandoffMarkdown = sessionCompaction.handoffMarkdown; + context.paperclipSessionRotationReason = sessionCompaction.reason; + context.paperclipPreviousSessionId = previousSessionDisplayId ?? runtimeSessionIdForAdapter; + runtimeSessionIdForAdapter = null; + runtimeSessionParamsForAdapter = null; + previousSessionDisplayId = null; + if (sessionCompaction.reason) { + runtimeWorkspaceWarnings.push( + `Starting a fresh session because ${sessionCompaction.reason}.`, + ); + } + } else { + delete context.paperclipSessionHandoffMarkdown; + delete context.paperclipSessionRotationReason; + delete context.paperclipPreviousSessionId; + } + const runtimeForAdapter = { - sessionId: readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback, - sessionParams: runtimeSessionParams, + sessionId: runtimeSessionIdForAdapter, + sessionParams: runtimeSessionParamsForAdapter, sessionDisplayId: previousSessionDisplayId, taskKey, }; @@ -1522,6 +1804,14 @@ export function heartbeatService(db: Db) { previousDisplayId: runtimeForAdapter.sessionDisplayId, previousLegacySessionId: runtimeForAdapter.sessionId, }); + const rawUsage = normalizeUsageTotals(adapterResult.usage); + const sessionUsageResolution = await resolveNormalizedUsageForSession({ + agentId: agent.id, + runId: run.id, + sessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId, + rawUsage, + }); + const normalizedUsage = sessionUsageResolution.normalizedUsage; let outcome: "succeeded" | "failed" | "cancelled" | "timed_out"; const latestRun = await getRun(run.id); @@ -1550,9 +1840,23 @@ export function heartbeatService(db: Db) { : "failed"; const usageJson = - adapterResult.usage || adapterResult.costUsd != null + normalizedUsage || adapterResult.costUsd != null ? ({ - ...(adapterResult.usage ?? {}), + ...(normalizedUsage ?? {}), + ...(rawUsage ? { + rawInputTokens: rawUsage.inputTokens, + rawCachedInputTokens: rawUsage.cachedInputTokens, + rawOutputTokens: rawUsage.outputTokens, + } : {}), + ...(sessionUsageResolution.derivedFromSessionTotals ? { usageSource: "session_delta" } : {}), + ...((nextSessionState.displayId ?? nextSessionState.legacySessionId) + ? { persistedSessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId } + : {}), + sessionReused: runtimeForAdapter.sessionId != null || runtimeForAdapter.sessionDisplayId != null, + taskSessionReused: taskSessionForRun != null, + freshSession: runtimeForAdapter.sessionId == null && runtimeForAdapter.sessionDisplayId == null, + sessionRotated: sessionCompaction.rotate, + sessionRotationReason: sessionCompaction.reason, ...(adapterResult.costUsd != null ? { costUsd: adapterResult.costUsd } : {}), ...(adapterResult.billingType ? { billingType: adapterResult.billingType } : {}), } as Record) @@ -1609,7 +1913,7 @@ export function heartbeatService(db: Db) { if (finalizedRun) { await updateRuntimeState(agent, finalizedRun, adapterResult, { legacySessionId: nextSessionState.legacySessionId, - }); + }, normalizedUsage); if (taskKey) { if (adapterResult.clearSession || (!nextSessionState.params && !nextSessionState.displayId)) { await clearTaskSessions(agent.companyId, agent.id, { diff --git a/server/src/services/issues.ts b/server/src/services/issues.ts index 807a97eb..d6f5a643 100644 --- a/server/src/services/issues.ts +++ b/server/src/services/issues.ts @@ -1060,13 +1060,70 @@ export function issueService(db: Db) { .returning() .then((rows) => rows[0] ?? null), - listComments: (issueId: string) => - db + listComments: async ( + issueId: string, + opts?: { + afterCommentId?: string | null; + order?: "asc" | "desc"; + limit?: number | null; + }, + ) => { + const order = opts?.order === "asc" ? "asc" : "desc"; + const afterCommentId = opts?.afterCommentId?.trim() || null; + const limit = opts?.limit && opts.limit > 0 ? Math.floor(opts.limit) : null; + + const conditions = [eq(issueComments.issueId, issueId)]; + if (afterCommentId) { + const anchor = await db + .select({ + id: issueComments.id, + createdAt: issueComments.createdAt, + }) + .from(issueComments) + .where(and(eq(issueComments.issueId, issueId), eq(issueComments.id, afterCommentId))) + .then((rows) => rows[0] ?? null); + + if (!anchor) return []; + conditions.push( + sql`(${issueComments.createdAt} > ${anchor.createdAt} OR (${issueComments.createdAt} = ${anchor.createdAt} AND ${issueComments.id} <> ${anchor.id}))`, + ); + } + + const query = db .select() .from(issueComments) + .where(and(...conditions)) + .orderBy(order === "asc" ? asc(issueComments.createdAt) : desc(issueComments.createdAt)); + + const comments = limit ? await query.limit(limit) : await query; + return comments.map(redactIssueComment); + }, + + getCommentCursor: async (issueId: string) => { + const latest = await db + .select({ + latestCommentId: issueComments.id, + latestCommentAt: issueComments.createdAt, + }) + .from(issueComments) .where(eq(issueComments.issueId, issueId)) - .orderBy(desc(issueComments.createdAt)) - .then((comments) => comments.map(redactIssueComment)), + .orderBy(desc(issueComments.createdAt), desc(issueComments.id)) + .limit(1) + .then((rows) => rows[0] ?? null); + + const [{ totalComments }] = await db + .select({ + totalComments: sql`count(*)::int`, + }) + .from(issueComments) + .where(eq(issueComments.issueId, issueId)); + + return { + totalComments: Number(totalComments ?? 0), + latestCommentId: latest?.latestCommentId ?? null, + latestCommentAt: latest?.latestCommentAt ?? null, + }; + }, getComment: (commentId: string) => db diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index d1858ee6..928e3bc1 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -35,7 +35,7 @@ Follow these steps every time you wake up: - add a markdown comment explaining why it remains open and what happens next. Always include links to the approval and issue in that comment. -**Step 3 — Get assignments.** `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked`. Results sorted by priority. This is your inbox. +**Step 3 — Get assignments.** Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked` only when you need the full issue objects. **Step 4 — Pick work (with mention exception).** Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it. **Blocked-task dedup:** Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`). @@ -56,8 +56,15 @@ Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLI If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. **Never retry a 409.** -**Step 6 — Understand context.** `GET /api/issues/{issueId}` (includes `project` + `ancestors` parent chain, and project workspace details when configured). `GET /api/issues/{issueId}/comments`. Read ancestors to understand _why_ this task exists. -If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and treat it as the immediate trigger you must respond to. Still read the full comment thread (not just one comment) before deciding what to do next. +**Step 6 — Understand context.** Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata without forcing a full thread replay. + +Use comments incrementally: + +- if `PAPERCLIP_WAKE_COMMENT_ID` is set, fetch that exact comment first with `GET /api/issues/{issueId}/comments/{commentId}` +- if you already know the thread and only need updates, use `GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc` +- use the full `GET /api/issues/{issueId}/comments` route only when you are cold-starting, when session memory is unreliable, or when the incremental path is not enough + +Read enough ancestor/comment context to understand _why_ the task exists and what changed. Do not reflexively reload the whole thread on every heartbeat. **Step 7 — Do the work.** Use your tools and capabilities. @@ -226,10 +233,13 @@ PATCH /api/agents/{agentId}/instructions-path | Action | Endpoint | | ------------------------------------- | ------------------------------------------------------------------------------------------ | | My identity | `GET /api/agents/me` | +| My compact inbox | `GET /api/agents/me/inbox-lite` | | My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,blocked` | | Checkout task | `POST /api/issues/:issueId/checkout` | | Get task + ancestors | `GET /api/issues/:issueId` | +| Get compact heartbeat context | `GET /api/issues/:issueId/heartbeat-context` | | Get comments | `GET /api/issues/:issueId/comments` | +| Get comment delta | `GET /api/issues/:issueId/comments?after=:commentId&order=asc` | | Get specific comment | `GET /api/issues/:issueId/comments/:commentId` | | Update task | `PATCH /api/issues/:issueId` (optional `comment` field) | | Add comment | `POST /api/issues/:issueId/comments` | diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsx index 5f92a588..abfc04fb 100644 --- a/ui/src/components/AgentConfigForm.tsx +++ b/ui/src/components/AgentConfigForm.tsx @@ -444,23 +444,28 @@ export function AgentConfigForm(props: AgentConfigFormProps) { /> {isLocal && ( - - mark("adapterConfig", "promptTemplate", v ?? "")} - placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..." - contentClassName="min-h-[88px] text-sm font-mono" - imageUploadHandler={async (file) => { - const namespace = `agents/${props.agent.id}/prompt-template`; - const asset = await uploadMarkdownImage.mutateAsync({ file, namespace }); - return asset.contentPath; - }} - /> - + <> + + mark("adapterConfig", "promptTemplate", v ?? "")} + placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..." + contentClassName="min-h-[88px] text-sm font-mono" + imageUploadHandler={async (file) => { + const namespace = `agents/${props.agent.id}/prompt-template`; + const asset = await uploadMarkdownImage.mutateAsync({ file, namespace }); + return asset.contentPath; + }} + /> + +
+ Prompt template is replayed on every heartbeat. Keep it compact and dynamic to avoid recurring token cost and cache churn. +
+ )} @@ -576,19 +581,24 @@ export function AgentConfigForm(props: AgentConfigFormProps) { {/* Prompt template (create mode only — edit mode shows this in Identity) */} {isLocal && isCreate && ( - - set!({ promptTemplate: v })} - placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..." - contentClassName="min-h-[88px] text-sm font-mono" - imageUploadHandler={async (file) => { - const namespace = "agents/drafts/prompt-template"; - const asset = await uploadMarkdownImage.mutateAsync({ file, namespace }); - return asset.contentPath; - }} - /> - + <> + + set!({ promptTemplate: v })} + placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..." + contentClassName="min-h-[88px] text-sm font-mono" + imageUploadHandler={async (file) => { + const namespace = "agents/drafts/prompt-template"; + const asset = await uploadMarkdownImage.mutateAsync({ file, namespace }); + return asset.contentPath; + }} + /> + +
+ Prompt template is replayed on every heartbeat. Prefer small task framing and variables like {"{{ context.* }}"} or {"{{ run.* }}"}; avoid repeating stable instructions here. +
+ )} {/* Adapter-specific fields */} @@ -704,6 +714,9 @@ export function AgentConfigForm(props: AgentConfigFormProps) { }} /> +
+ Bootstrap prompt is only sent for fresh sessions. Put stable setup, habits, and longer reusable guidance here. Frequent changes reduce the value of session reuse because new sessions must replay it. +
{adapterType === "claude_local" && ( )} diff --git a/ui/src/components/agent-config-primitives.tsx b/ui/src/components/agent-config-primitives.tsx index 77a5b14c..3384c366 100644 --- a/ui/src/components/agent-config-primitives.tsx +++ b/ui/src/components/agent-config-primitives.tsx @@ -26,7 +26,7 @@ export const help: Record = { capabilities: "Describes what this agent can do. Shown in the org chart and used for task routing.", adapterType: "How this agent runs: local CLI (Claude/Codex/OpenCode), OpenClaw Gateway, spawned process, or generic HTTP webhook.", cwd: "Default working directory fallback for local adapters. Use an absolute path on the machine running Paperclip.", - promptTemplate: "The prompt sent to the agent on each heartbeat. Supports {{ agent.id }}, {{ agent.name }}, {{ agent.role }} variables.", + promptTemplate: "Sent on every heartbeat. Keep this small and dynamic. Use it for current-task framing, not large static instructions. Supports {{ agent.id }}, {{ agent.name }}, {{ agent.role }} and other template variables.", model: "Override the default model used by the adapter.", thinkingEffort: "Control model reasoning depth. Supported values vary by adapter/model.", chrome: "Enable Claude's Chrome integration by passing --chrome.", @@ -44,7 +44,7 @@ export const help: Record = { args: "Command-line arguments, comma-separated.", extraArgs: "Extra CLI arguments for local adapters, comma-separated.", envVars: "Environment variables injected into the adapter process. Use plain values or secret references.", - bootstrapPrompt: "Optional prompt prepended on the first run to bootstrap the agent's environment or habits.", + bootstrapPrompt: "Only sent when Paperclip starts a fresh session. Use this for stable setup guidance that should not be repeated on every heartbeat.", payloadTemplateJson: "Optional JSON merged into remote adapter request payloads before Paperclip adds its standard wake and workspace fields.", webhookUrl: "The URL that receives POST requests when the agent is invoked.", heartbeatInterval: "Run this agent automatically on a timer. Useful for periodic tasks like checking for new work.",