hanh.tonguyen/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement agent hiring, approval workflows, config revisions, LLM reflection, and sidebar badges

Browse Source 
Agent management: hire endpoint with permission gates and pending_approval status,
config revision tracking with rollback, agent duplicate route, permission CRUD.
Block pending_approval agents from auth, heartbeat, and assignments.

Approvals: revision request/resubmit flow, approval comments CRUD, issue-approval
linking, auto-wake agents on approval decisions with context snapshot.

Costs: per-agent breakdown, period filtering (month/week/day/all), cost by agent
list endpoint.

Adapters: agentConfigurationDoc on all adapters, /llms/agent-configuration.txt
reflection routes. Inject PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS,
PAPERCLIP_LINKED_ISSUE_IDS into adapter environments.

Sidebar badges endpoint for pending approval/inbox counts. Dashboard and company
settings extensions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Forgotten
2026-02-19 13:02:41 -06:00
parent db0b19bf9d
commit c09037ffad
28 changed files with 2393 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
server/src/routes/approvals.ts
View File

@@ -1,13 +1,27 @@
import { Router } from "express";
import type { Db } from "@paperclip/db";
import { createApprovalSchema, resolveApprovalSchema } from "@paperclip/shared";
import {
addApprovalCommentSchema,
createApprovalSchema,
requestApprovalRevisionSchema,
resolveApprovalSchema,
resubmitApprovalSchema,
} from "@paperclip/shared";
import { validate } from "../middleware/validate.js";
import { approvalService, logActivity } from "../services/index.js";
import { logger } from "../middleware/logger.js";
import {
approvalService,
heartbeatService,
issueApprovalService,
logActivity,
} from "../services/index.js";
import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
export function approvalRoutes(db: Db) {
const router = Router();
const svc = approvalService(db);
const heartbeat = heartbeatService(db);
const issueApprovalsSvc = issueApprovalService(db);
router.get("/companies/:companyId/approvals", async (req, res) => {
const companyId = req.params.companyId as string;
@@ -17,16 +31,33 @@ export function approvalRoutes(db: Db) {
res.json(result);
});
router.get("/approvals/:id", async (req, res) => {
const id = req.params.id as string;
const approval = await svc.getById(id);
if (!approval) {
res.status(404).json({ error: "Approval not found" });
return;
}
assertCompanyAccess(req, approval.companyId);
res.json(approval);
});
router.post("/companies/:companyId/approvals", validate(createApprovalSchema), async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
const rawIssueIds = req.body.issueIds;
const issueIds = Array.isArray(rawIssueIds)
? rawIssueIds.filter((value: unknown): value is string => typeof value === "string")
: [];
const uniqueIssueIds = Array.from(new Set(issueIds));
const { issueIds: _issueIds, ...approvalInput } = req.body;
const actor = getActorInfo(req);
const approval = await svc.create(companyId, {
...req.body,
...approvalInput,
requestedByUserId: actor.actorType === "user" ? actor.actorId : null,
requestedByAgentId:
req.body.requestedByAgentId ?? (actor.actorType === "agent" ? actor.actorId : null),
approvalInput.requestedByAgentId ?? (actor.actorType === "agent" ? actor.actorId : null),
status: "pending",
decisionNote: null,
decidedByUserId: null,
@@ -34,6 +65,13 @@ export function approvalRoutes(db: Db) {
updatedAt: new Date(),
});
if (uniqueIssueIds.length > 0) {
await issueApprovalsSvc.linkManyForApproval(approval.id, uniqueIssueIds, {
agentId: actor.agentId,
userId: actor.actorType === "user" ? actor.actorId : null,
});
}
await logActivity(db, {
companyId,
actorType: actor.actorType,
@@ -42,16 +80,31 @@ export function approvalRoutes(db: Db) {
action: "approval.created",
entityType: "approval",
entityId: approval.id,
details: { type: approval.type },
details: { type: approval.type, issueIds: uniqueIssueIds },
});
res.status(201).json(approval);
});
router.get("/approvals/:id/issues", async (req, res) => {
const id = req.params.id as string;
const approval = await svc.getById(id);
if (!approval) {
res.status(404).json({ error: "Approval not found" });
return;
}
assertCompanyAccess(req, approval.companyId);
const issues = await issueApprovalsSvc.listIssuesForApproval(id);
res.json(issues);
});
router.post("/approvals/:id/approve", validate(resolveApprovalSchema), async (req, res) => {
assertBoard(req);
const id = req.params.id as string;
const approval = await svc.approve(id, req.body.decidedByUserId ?? "board", req.body.decisionNote);
const linkedIssues = await issueApprovalsSvc.listIssuesForApproval(approval.id);
const linkedIssueIds = linkedIssues.map((issue) => issue.id);
const primaryIssueId = linkedIssueIds[0] ?? null;
await logActivity(db, {
companyId: approval.companyId,
@@ -60,9 +113,76 @@ export function approvalRoutes(db: Db) {
action: "approval.approved",
entityType: "approval",
entityId: approval.id,
details: { type: approval.type },
details: {
type: approval.type,
requestedByAgentId: approval.requestedByAgentId,
linkedIssueIds,
},
});
if (approval.requestedByAgentId) {
try {
const wakeRun = await heartbeat.wakeup(approval.requestedByAgentId, {
source: "automation",
triggerDetail: "system",
reason: "approval_approved",
payload: {
approvalId: approval.id,
approvalStatus: approval.status,
issueId: primaryIssueId,
issueIds: linkedIssueIds,
},
requestedByActorType: "user",
requestedByActorId: req.actor.userId ?? "board",
contextSnapshot: {
source: "approval.approved",
approvalId: approval.id,
approvalStatus: approval.status,
issueId: primaryIssueId,
issueIds: linkedIssueIds,
taskId: primaryIssueId,
wakeReason: "approval_approved",
},
});
await logActivity(db, {
companyId: approval.companyId,
actorType: "user",
actorId: req.actor.userId ?? "board",
action: "approval.requester_wakeup_queued",
entityType: "approval",
entityId: approval.id,
details: {
requesterAgentId: approval.requestedByAgentId,
wakeRunId: wakeRun?.id ?? null,
linkedIssueIds,
},
});
} catch (err) {
logger.warn(
{
err,
approvalId: approval.id,
requestedByAgentId: approval.requestedByAgentId,
},
"failed to queue requester wakeup after approval",
);
await logActivity(db, {
companyId: approval.companyId,
actorType: "user",
actorId: req.actor.userId ?? "board",
action: "approval.requester_wakeup_failed",
entityType: "approval",
entityId: approval.id,
details: {
requesterAgentId: approval.requestedByAgentId,
linkedIssueIds,
error: err instanceof Error ? err.message : String(err),
},
});
}
}
res.json(approval);
});
@@ -84,5 +204,100 @@ export function approvalRoutes(db: Db) {
res.json(approval);
});
router.post(
"/approvals/:id/request-revision",
validate(requestApprovalRevisionSchema),
async (req, res) => {
assertBoard(req);
const id = req.params.id as string;
const approval = await svc.requestRevision(
id,
req.body.decidedByUserId ?? "board",
req.body.decisionNote,
);
await logActivity(db, {
companyId: approval.companyId,
actorType: "user",
actorId: req.actor.userId ?? "board",
action: "approval.revision_requested",
entityType: "approval",
entityId: approval.id,
details: { type: approval.type },
});
res.json(approval);
},
);
router.post("/approvals/:id/resubmit", validate(resubmitApprovalSchema), async (req, res) => {
const id = req.params.id as string;
const existing = await svc.getById(id);
if (!existing) {
res.status(404).json({ error: "Approval not found" });
return;
}
assertCompanyAccess(req, existing.companyId);
if (req.actor.type === "agent" && req.actor.agentId !== existing.requestedByAgentId) {
res.status(403).json({ error: "Only requesting agent can resubmit this approval" });
return;
}
const approval = await svc.resubmit(id, req.body.payload);
const actor = getActorInfo(req);
await logActivity(db, {
companyId: approval.companyId,
actorType: actor.actorType,
actorId: actor.actorId,
agentId: actor.agentId,
action: "approval.resubmitted",
entityType: "approval",
entityId: approval.id,
details: { type: approval.type },
});
res.json(approval);
});
router.get("/approvals/:id/comments", async (req, res) => {
const id = req.params.id as string;
const approval = await svc.getById(id);
if (!approval) {
res.status(404).json({ error: "Approval not found" });
return;
}
assertCompanyAccess(req, approval.companyId);
const comments = await svc.listComments(id);
res.json(comments);
});
router.post("/approvals/:id/comments", validate(addApprovalCommentSchema), async (req, res) => {
const id = req.params.id as string;
const approval = await svc.getById(id);
if (!approval) {
res.status(404).json({ error: "Approval not found" });
return;
}
assertCompanyAccess(req, approval.companyId);
const actor = getActorInfo(req);
const comment = await svc.addComment(id, req.body.body, {
agentId: actor.agentId ?? undefined,
userId: actor.actorType === "user" ? actor.actorId : undefined,
});
await logActivity(db, {
companyId: approval.companyId,
actorType: actor.actorType,
actorId: actor.actorId,
agentId: actor.agentId,
action: "approval.comment_added",
entityType: "approval",
entityId: approval.id,
details: { commentId: comment.id },
});
res.status(201).json(comment);
});
return router;
}