Polish board settings and skills workflow

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-04-30 11:20:43 -05:00
1 parent c0ce35d1fb
commit 8af1f418ac
48 files changed
+2605 -248

No files matched your search

+181 -1
View File
@@ -3,7 +3,7 @@ import request from "supertest";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { afterAll, afterEach, beforeAll } from "vitest";
import { randomUUID } from "node:crypto";
import { createDb, companies, agents, costEvents, financeEvents, projects } from "@paperclipai/db";
import { createDb, companies, agents, costEvents, financeEvents, issues, projects } from "@paperclipai/db";
import { costService } from "../services/costs.ts";
import { financeService } from "../services/finance.ts";
import {
@@ -45,6 +45,10 @@ const mockAgentService = vi.hoisted(() => ({
getById: vi.fn(),
update: vi.fn(),
}));
const mockIssueService = vi.hoisted(() => ({
getById: vi.fn(),
getByIdentifier: vi.fn(),
}));
const mockHeartbeatService = vi.hoisted(() => ({
cancelBudgetScopeWork: vi.fn().mockResolvedValue(undefined),
}));
@@ -57,6 +61,15 @@ const mockCostService = vi.hoisted(() => ({
byAgentModel: vi.fn().mockResolvedValue([]),
byProvider: vi.fn().mockResolvedValue([]),
byBiller: vi.fn().mockResolvedValue([]),
issueTreeSummary: vi.fn().mockResolvedValue({
issueId: "issue-1",
issueCount: 1,
includeDescendants: true,
costCents: 0,
inputTokens: 0,
cachedInputTokens: 0,
outputTokens: 0,
}),
windowSpend: vi.fn().mockResolvedValue([]),
byProject: vi.fn().mockResolvedValue([]),
}));
@@ -87,6 +100,7 @@ function registerModuleMocks() {
financeService: () => mockFinanceService,
companyService: () => mockCompanyService,
agentService: () => mockAgentService,
issueService: () => mockIssueService,
heartbeatService: () => mockHeartbeatService,
logActivity: mockLogActivity,
}));
@@ -161,6 +175,16 @@ beforeEach(() => {
budgetMonthlyCents: 100,
spentMonthlyCents: 0,
});
mockIssueService.getById.mockResolvedValue({
id: "issue-1",
companyId: "company-1",
identifier: "PAP-1",
});
mockIssueService.getByIdentifier.mockResolvedValue({
id: "issue-1",
companyId: "company-1",
identifier: "PAP-1",
});
mockBudgetService.upsertPolicy.mockResolvedValue(undefined);
});
@@ -201,6 +225,24 @@ describe("cost routes", () => {
});
});
it("returns issue subtree cost summaries for issue refs", async () => {
const app = await createApp();
const res = await request(app).get("/api/issues/PAP-1/cost-summary");
expect(res.status).toBe(200);
expect(mockIssueService.getByIdentifier).toHaveBeenCalledWith("PAP-1");
expect(mockCostService.issueTreeSummary).toHaveBeenCalledWith("company-1", "issue-1");
expect(res.body).toEqual({
issueId: "issue-1",
issueCount: 1,
includeDescendants: true,
costCents: 0,
inputTokens: 0,
cachedInputTokens: 0,
outputTokens: 0,
});
});
it("returns 400 for invalid finance event list limits", async () => {
const { parseCostLimit } = await loadCostParsers();
expect(() => parseCostLimit({ limit: "0" })).toThrow(/invalid 'limit'/i);
@@ -351,6 +393,7 @@ describeEmbeddedPostgres("cost and finance aggregate overflow handling", () => {
afterEach(async () => {
await db.delete(financeEvents);
await db.delete(costEvents);
await db.delete(issues);
await db.delete(projects);
await db.delete(agents);
await db.delete(companies);
@@ -435,6 +478,143 @@ describeEmbeddedPostgres("cost and finance aggregate overflow handling", () => {
expect(byAgentModelRow?.costCents).toBe(4_000_000_000);
});
it("aggregates issue costs across recursive descendants only", async () => {
const companyId = randomUUID();
const agentId = randomUUID();
const rootIssueId = randomUUID();
const childIssueId = randomUUID();
const grandchildIssueId = randomUUID();
const siblingIssueId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await db.insert(agents).values({
id: agentId,
companyId,
name: "Cost Agent",
role: "engineer",
status: "active",
adapterType: "codex_local",
adapterConfig: {},
runtimeConfig: {},
permissions: {},
});
await db.insert(issues).values([
{
id: rootIssueId,
companyId,
title: "Root",
status: "in_progress",
priority: "medium",
issueNumber: 1,
identifier: "TST-1",
},
{
id: childIssueId,
companyId,
parentId: rootIssueId,
title: "Child",
status: "done",
priority: "medium",
issueNumber: 2,
identifier: "TST-2",
},
{
id: grandchildIssueId,
companyId,
parentId: childIssueId,
title: "Grandchild",
status: "done",
priority: "medium",
issueNumber: 3,
identifier: "TST-3",
},
{
id: siblingIssueId,
companyId,
title: "Sibling",
status: "done",
priority: "medium",
issueNumber: 4,
identifier: "TST-4",
},
]);
await db.insert(costEvents).values([
{
companyId,
agentId,
issueId: rootIssueId,
provider: "openai",
biller: "openai",
billingType: "metered_api",
model: "gpt-5",
inputTokens: 10,
cachedInputTokens: 1,
outputTokens: 2,
costCents: 100,
occurredAt: new Date("2026-04-10T00:00:00.000Z"),
},
{
companyId,
agentId,
issueId: childIssueId,
provider: "openai",
biller: "openai",
billingType: "metered_api",
model: "gpt-5",
inputTokens: 20,
cachedInputTokens: 2,
outputTokens: 4,
costCents: 200,
occurredAt: new Date("2026-04-10T00:01:00.000Z"),
},
{
companyId,
agentId,
issueId: grandchildIssueId,
provider: "openai",
biller: "openai",
billingType: "metered_api",
model: "gpt-5",
inputTokens: 30,
cachedInputTokens: 3,
outputTokens: 6,
costCents: 300,
occurredAt: new Date("2026-04-10T00:02:00.000Z"),
},
{
companyId,
agentId,
issueId: siblingIssueId,
provider: "openai",
biller: "openai",
billingType: "metered_api",
model: "gpt-5",
inputTokens: 40,
cachedInputTokens: 4,
outputTokens: 8,
costCents: 400,
occurredAt: new Date("2026-04-10T00:03:00.000Z"),
},
]);
const summary = await costs.issueTreeSummary(companyId, rootIssueId);
expect(summary).toEqual({
issueId: rootIssueId,
issueCount: 3,
includeDescendants: true,
costCents: 600,
inputTokens: 60,
cachedInputTokens: 6,
outputTokens: 12,
});
});
it("aggregates finance event sums above int32 without raising Postgres integer overflow", async () => {
const companyId = randomUUID();
@@ -17,6 +17,7 @@ const mockInteractionService = vi.hoisted(() => ({
rejectInteraction: vi.fn(),
rejectSuggestedTasks: vi.fn(),
answerQuestions: vi.fn(),
cancelQuestions: vi.fn(),
}));
const mockHeartbeatService = vi.hoisted(() => ({
@@ -249,6 +250,36 @@ describe.sequential("issue thread interaction routes", () => {
updatedAt: "2026-04-20T12:06:00.000Z",
resolvedAt: "2026-04-20T12:06:00.000Z",
});
mockInteractionService.cancelQuestions.mockResolvedValue({
id: "interaction-2",
companyId: "company-1",
issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
kind: "ask_user_questions",
status: "cancelled",
continuationPolicy: "wake_assignee",
idempotencyKey: null,
sourceCommentId: "comment-2",
sourceRunId: "run-2",
payload: {
version: 1,
questions: [{
id: "scope",
prompt: "Scope?",
selectionMode: "single",
options: [{ id: "phase-1", label: "Phase 1" }],
}],
},
result: {
version: 1,
answers: [],
cancelled: true,
cancellationReason: null,
summaryMarkdown: null,
},
createdAt: "2026-04-20T12:00:00.000Z",
updatedAt: "2026-04-20T12:05:00.000Z",
resolvedAt: "2026-04-20T12:05:00.000Z",
});
});
it("lists and creates board-authored interactions", async () => {
@@ -363,6 +394,42 @@ describe.sequential("issue thread interaction routes", () => {
);
});
it("cancels question interactions and emits a continuation wake", async () => {
const app = await createApp();
const res = await request(app)
.post("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/interactions/interaction-2/cancel")
.send({});
expect(res.status).toBe(200);
expect(res.body.status).toBe("cancelled");
expect(mockInteractionService.cancelQuestions).toHaveBeenCalledWith(
expect.objectContaining({ id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" }),
"interaction-2",
{},
expect.objectContaining({ userId: "local-board" }),
);
expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
ASSIGNEE_AGENT_ID,
expect.objectContaining({
reason: "issue_commented",
payload: expect.objectContaining({
interactionId: "interaction-2",
interactionKind: "ask_user_questions",
interactionStatus: "cancelled",
sourceCommentId: "comment-2",
sourceRunId: "run-2",
}),
}),
);
expect(mockLogActivity).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({
action: "issue.thread_interaction_cancelled",
}),
);
});
it("accepts request confirmations and wakes the current assignee when configured for accept-only wakeups", async () => {
mockInteractionService.acceptInteraction.mockResolvedValueOnce({
interaction: {
@@ -427,6 +427,85 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
})).rejects.toThrow("Interaction has already been resolved");
});
it("persists cancelled ask_user_questions interactions without answer data", async () => {
const companyId = randomUUID();
const goalId = randomUUID();
const issueId = randomUUID();
await db.insert(companies).values({
id: companyId,
name: "Paperclip",
issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
requireBoardApprovalForNewAgents: false,
});
await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: false });
await db.insert(goals).values({
id: goalId,
companyId,
title: "Cancel question answers",
level: "task",
status: "active",
});
await db.insert(issues).values({
id: issueId,
companyId,
goalId,
title: "Question parent",
status: "in_review",
priority: "medium",
});
const created = await interactionsSvc.create({
id: issueId,
companyId,
}, {
kind: "ask_user_questions",
continuationPolicy: "wake_assignee",
payload: {
version: 1,
questions: [{
id: "scope",
prompt: "Choose the scope",
selectionMode: "single",
required: true,
options: [
{ id: "phase-1", label: "Phase 1" },
{ id: "phase-2", label: "Phase 2" },
],
}],
},
}, {
userId: "local-board",
});
const cancelled = await interactionsSvc.cancelQuestions({
id: issueId,
companyId,
}, created.id, {
reason: "Not needed anymore",
}, {
userId: "local-board",
});
expect(cancelled.status).toBe("cancelled");
expect(cancelled.result).toEqual({
version: 1,
answers: [],
cancelled: true,
cancellationReason: "Not needed anymore",
summaryMarkdown: null,
});
await expect(interactionsSvc.answerQuestions({
id: issueId,
companyId,
}, created.id, {
answers: [{ questionId: "scope", optionIds: ["phase-1"] }],
}, {
userId: "local-board",
})).rejects.toThrow("Interaction has already been resolved");
});
it("reuses the existing interaction when the same idempotency key is submitted twice", async () => {
const companyId = randomUUID();
const goalId = randomUUID();
+5 -2
View File
@@ -14,7 +14,10 @@
* - Exact types: "application/pdf"
* - Wildcards: "image/*" or "application/vnd.openxmlformats-officedocument.*"
*/
import { MAX_COMPANY_ATTACHMENT_MAX_BYTES } from "@paperclipai/shared";
import {
DEFAULT_COMPANY_ATTACHMENT_MAX_BYTES,
MAX_COMPANY_ATTACHMENT_MAX_BYTES,
} from "@paperclipai/shared";
export const DEFAULT_ALLOWED_TYPES: readonly string[] = [
"image/png",
@@ -96,7 +99,7 @@ export const MAX_ATTACHMENT_BYTES =
export function normalizeIssueAttachmentMaxBytes(value: number | null | undefined): number {
if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
return MAX_ATTACHMENT_BYTES;
return Math.min(DEFAULT_COMPANY_ATTACHMENT_MAX_BYTES, MAX_ATTACHMENT_BYTES);
}
return Math.min(Math.floor(value), MAX_COMPANY_ATTACHMENT_MAX_BYTES, MAX_ATTACHMENT_BYTES);
}
+1 -1
View File
@@ -34,7 +34,7 @@ You MUST delegate work rather than doing it yourself. When a task is assigned to
- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.
- Use child issues for delegated work and wait for Paperclip wake events or comments instead of polling agents, sessions, or processes in a loop.
- Create child issues directly when ownership and scope are clear. Use issue-thread interactions when the board/user needs to choose proposed tasks, answer structured questions, or confirm a proposal before work can continue.
- Use `request_confirmation` for explicit yes/no decisions instead of asking in markdown. For plan approval, update the `plan` document, create a confirmation targeting the latest plan revision with an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, and wait for acceptance before delegating implementation subtasks.
- Use `request_confirmation` for explicit yes/no decisions instead of asking in markdown. For plan approval, update the `plan` document, create a confirmation targeting the latest plan revision with an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, put the source issue in `in_review`, and wait for acceptance before delegating implementation subtasks.
- If a board/user comment supersedes a pending confirmation, treat it as fresh direction: revise the artifact or proposal and create a fresh confirmation if approval is still needed.
- Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.
- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).
@@ -40,7 +40,7 @@ Status quick guide:
- `todo`: ready to execute, but not yet checked out.
- `in_progress`: actively owned work. Agents should reach this by checkout, not by manually flipping status.
- `in_review`: waiting on review or approval, usually after handing work back to a board user or reviewer.
- `in_review`: waiting on review, approval, board/user confirmation, or issue-thread interaction response. Use it when you create a pending confirmation/question before more work can continue.
- `blocked`: cannot move until something specific changes. Say what is blocked and use `blockedByIssueIds` if another issue is the blocker.
- `done`: finished.
- `cancelled`: intentionally dropped.
@@ -49,7 +49,7 @@ Status quick guide:
- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`. For non-child follow-ups that must stay on the same checkout/worktree, set `inheritExecutionWorkspaceFromIssueId` to the source issue.
- When you know the needed work and owner, create those subtasks directly. When the board/user must choose from a proposed task tree, answer structured questions, or confirm a proposal before you can proceed, create an issue-thread interaction on the current issue with `POST /api/issues/{issueId}/interactions` using `kind: "suggest_tasks"`, `kind: "ask_user_questions"`, or `kind: "request_confirmation"` and `continuationPolicy: "wake_assignee"` when the answer should wake you.
- For plan approval, update the `plan` document first, create `request_confirmation` targeting the latest `plan` revision, use an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, and do not create implementation subtasks until the board/user accepts it.
- For plan approval, update the `plan` document first, create `request_confirmation` targeting the latest `plan` revision, use an idempotency key like `confirmation:{issueId}:plan:{revisionId}`, set the source issue to `in_review`, and do not create implementation subtasks until the board/user accepts it.
- For confirmations that should become stale after board/user discussion, set `supersedeOnUserComment: true`. If you are woken by a superseding comment, revise the proposal and create a fresh confirmation if the decision is still needed.
- Use `paperclip-create-agent` skill when hiring new agents.
- Assign work to the right agent for the job.
+21
View File
@@ -14,6 +14,7 @@ import {
financeService,
companyService,
agentService,
issueService,
heartbeatService,
logActivity,
} from "../services/index.js";
@@ -58,6 +59,14 @@ export function costRoutes(
const budgets = budgetService(db, budgetHooks);
const companies = companyService(db);
const agents = agentService(db);
const issues = issueService(db);
async function resolveIssueByRef(rawId: string) {
if (/^[A-Z]+-\d+$/i.test(rawId)) {
return issues.getByIdentifier(rawId);
}
return issues.getById(rawId);
}
router.post("/companies/:companyId/cost-events", validate(createCostEventSchema), async (req, res) => {
const companyId = req.params.companyId as string;
@@ -126,6 +135,18 @@ export function costRoutes(
res.json(summary);
});
router.get("/issues/:id/cost-summary", async (req, res) => {
const rawId = req.params.id as string;
const issue = await resolveIssueByRef(rawId);
if (!issue) {
res.status(404).json({ error: "Issue not found" });
return;
}
assertCompanyAccess(req, issue.companyId);
const summary = await costs.issueTreeSummary(issue.companyId, issue.id);
res.json(summary);
});
router.get("/companies/:companyId/costs/by-agent", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
+52
View File
@@ -3182,6 +3182,58 @@ export function issueRoutes(
},
);
router.post(
"/issues/:id/interactions/:interactionId/cancel",
validate(rejectIssueThreadInteractionSchema),
async (req, res) => {
const id = req.params.id as string;
const interactionId = req.params.interactionId as string;
const issue = await svc.getById(id);
if (!issue) {
res.status(404).json({ error: "Issue not found" });
return;
}
assertCompanyAccess(req, issue.companyId);
assertBoard(req);
const actor = getActorInfo(req);
const interaction = await issueThreadInteractionService(db).cancelQuestions(issue, interactionId, req.body, {
agentId: actor.agentId,
userId: actor.actorType === "user" ? actor.actorId : null,
});
await logActivity(db, {
companyId: issue.companyId,
actorType: actor.actorType,
actorId: actor.actorId,
agentId: actor.agentId,
runId: actor.runId,
action: "issue.thread_interaction_cancelled",
entityType: "issue",
entityId: issue.id,
details: {
interactionId: interaction.id,
interactionKind: interaction.kind,
interactionStatus: interaction.status,
cancellationReason:
interaction.kind === "ask_user_questions"
? (interaction.result?.cancellationReason ?? null)
: null,
},
});
queueResolvedInteractionContinuationWakeup({
heartbeat,
issue,
interaction,
actor,
source: "issue.interaction.cancel",
});
res.json(interaction);
},
);
router.get("/issues/:id/comments/:commentId", async (req, res) => {
const id = req.params.id as string;
const commentId = req.params.commentId as string;
+56 -1
View File
@@ -1,4 +1,4 @@
import { and, desc, eq, gte, isNotNull, lt, lte, sql } from "drizzle-orm";
import { and, desc, eq, gte, isNotNull, isNull, lt, lte, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { activityLog, agents, companies, costEvents, issues, projects } from "@paperclipai/db";
import { notFound, unprocessable } from "../errors.js";
@@ -134,6 +134,61 @@ export function costService(db: Db, budgetHooks: BudgetServiceHooks = {}) {
};
},
issueTreeSummary: async (companyId: string, issueId: string) => {
const issueTreeCondition = sql<boolean>`
${issues.id} IN (
WITH RECURSIVE issue_tree(id) AS (
SELECT ${issues.id}
FROM ${issues}
WHERE ${issues.companyId} = ${companyId}
AND ${issues.id} = ${issueId}
AND ${issues.hiddenAt} IS NULL
UNION
SELECT child.id
FROM ${issues} child
JOIN issue_tree ON child.parent_id = issue_tree.id
WHERE child.company_id = ${companyId}
AND child.hidden_at IS NULL
)
SELECT id FROM issue_tree
)
`;
const [row] = await db
.select({
issueCount: sql<number>`count(distinct ${issues.id})::int`,
costCents: sumAsNumber(costEvents.costCents),
inputTokens: sumAsNumber(costEvents.inputTokens),
cachedInputTokens: sumAsNumber(costEvents.cachedInputTokens),
outputTokens: sumAsNumber(costEvents.outputTokens),
})
.from(issues)
.leftJoin(
costEvents,
and(
eq(costEvents.companyId, companyId),
eq(costEvents.issueId, issues.id),
),
)
.where(
and(
eq(issues.companyId, companyId),
isNull(issues.hiddenAt),
issueTreeCondition,
),
);
return {
issueId,
issueCount: Number(row?.issueCount ?? 0),
includeDescendants: true,
costCents: Number(row?.costCents ?? 0),
inputTokens: Number(row?.inputTokens ?? 0),
cachedInputTokens: Number(row?.cachedInputTokens ?? 0),
outputTokens: Number(row?.outputTokens ?? 0),
};
},
byAgent: async (companyId: string, range?: CostDateRange) => {
const conditions: ReturnType<typeof eq>[] = [eq(costEvents.companyId, companyId)];
if (range?.from) conditions.push(gte(costEvents.occurredAt, range.from));
@@ -1148,5 +1148,60 @@ export function issueThreadInteractionService(db: Db) {
await touchIssue(db, issue.id);
return hydrateInteraction(updated);
},
cancelQuestions: async (
issue: { id: string; companyId: string },
interactionId: string,
input: RejectIssueThreadInteraction,
actor: InteractionActor,
) => {
const data = rejectIssueThreadInteractionSchema.parse(input);
const current = await db
.select()
.from(issueThreadInteractions)
.where(eq(issueThreadInteractions.id, interactionId))
.then((rows) => rows[0] ?? null);
if (!current) throw notFound("Interaction not found");
if (current.companyId !== issue.companyId || current.issueId !== issue.id) {
throw notFound("Interaction not found");
}
if (current.kind !== "ask_user_questions") {
throw unprocessable("Only ask_user_questions interactions can be cancelled");
}
if (current.status !== "pending") {
throw conflict("Interaction has already been resolved");
}
const reason = data.reason?.trim() || null;
const [updated] = await db
.update(issueThreadInteractions)
.set({
status: "cancelled",
result: {
version: 1,
answers: [],
cancelled: true,
cancellationReason: reason,
summaryMarkdown: null,
},
resolvedByAgentId: actor.agentId ?? null,
resolvedByUserId: actor.userId ?? null,
resolvedAt: new Date(),
updatedAt: new Date(),
})
.where(and(
eq(issueThreadInteractions.id, interactionId),
eq(issueThreadInteractions.status, "pending"),
))
.returning();
if (!updated) {
throw conflict("Interaction has already been resolved");
}
await touchIssue(db, issue.id);
return hydrateInteraction(updated);
},
};
}