mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 21:34:48 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Status cards are saved summaries of company work. People and agents
can archive and restore them.
> - A person asked a chat agent to archive a card "to reuse it next
quarter". The agent archived it correctly.
> - The archive response had no board route, and the PATCH operation had
no description. The completion guidance tells agents not to guess
routes.
> - So the agent told the person to restore the card "by clearing
`archived`". That is an API instruction, not a route a person can use.
> - This pull request gives single-card responses an `href` to the
Status page and documents archive and restore on the PATCH operation.
> - The benefit is that an agent can give the person a usable link and a
true account of restore, which starts a fresh summary.
## Linked Issues or Issue Description
**What happened**
A chat agent archived a status card. Its reply told the person to
restore the card by clearing `archived` on the card. It gave no link to
the place where a person restores it.
**Expected behavior**
The reply links the card on the Status page, where a person can show
archived cards and click Restore. It also says that restore starts a
fresh summary.
**Steps to reproduce**
1. Enable status cards and create a card as an agent.
2. Ask the CEO agent in chat to archive the card for later reuse.
3. Read the reply. It has no usable restore route, because `PATCH
/api/status-cards/{id}` returns no `href` and has no description.
## What Changed
- `POST /api/companies/{companyId}/status-cards`, `GET
/api/status-cards/{id}` and `PATCH /api/status-cards/{id}` now return
`href`, the company-scoped Status page route for the card.
- The shared `statusCardSchema` has an optional `href` field.
- The `PATCH /api/status-cards/{id}` OpenAPI operation has a
description. It says that archive keeps the card and its history, that a
person restores it on the Status page with the returned `href`, and that
restore starts a fresh full summary.
- The create route reads the company issue prefix before it creates the
card. A failed link lookup can not delete a card whose compile task is
queued.
- Regression tests cover the `href` on the archive and get responses,
the new PATCH description, and a failed prefix read on create (no card
and no task are left).
## Verification
- `pnpm exec vitest run server/src/__tests__/status-cards.test.ts
server/src/__tests__/openapi-routes.test.ts` (71 tests pass). The new
create-route test fails on the first commit and passes on the fix.
- End to end: the chat eval `status-cards.archive-card` runs with this
change on an eval branch. The result is in the eval report for that
case.
## Risks
- Low risk. The change adds one optional response field and one
description. List responses do not change. The UI ignores the new field.
- Each single-card response does one more small company read for the
issue prefix. On create, this read occurs before the card exists, so its
failure leaves nothing behind.
## Model Used
- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used in Claude Code
with tool use and code execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
200 lines
7.9 KiB
TypeScript
200 lines
7.9 KiB
TypeScript
import { z } from "zod";
|
|
import { companySearchQuerySchema } from "./search.js";
|
|
|
|
export const STATUS_CARD_AGENT_MAX_CARDS = 20;
|
|
export const STATUS_CARD_AGENT_MAX_INTEREST_PROMPT_LENGTH = 4_000;
|
|
|
|
function isValidTimeZone(timezone: string) {
|
|
try {
|
|
new Intl.DateTimeFormat("en", { timeZone: timezone }).format();
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
export const statusCardStateSchema = z.enum(["compiling", "active", "error", "paused_budget", "paused_hours"]);
|
|
export const statusCardUpdateKindSchema = z.enum(["compile", "full", "incremental"]);
|
|
export const statusCardUpdateTriggerSchema = z.enum(["manual", "interval", "reactive", "restore"]);
|
|
export const statusCardUpdateStatusSchema = z.enum(["running", "ok", "failed"]);
|
|
|
|
export const statusCardRefreshTriggersSchema = z.object({
|
|
statusTransitions: z.boolean().default(true),
|
|
membershipChanges: z.boolean().default(true),
|
|
humanComments: z.boolean().default(true),
|
|
assigneeChanges: z.boolean().default(true),
|
|
anyUpdate: z.boolean().default(false),
|
|
});
|
|
|
|
export const statusCardRefreshPolicySchema = z
|
|
.object({
|
|
mode: z.enum(["manual", "interval", "reactive"]).default("manual"),
|
|
intervalMinutes: z.number().int().positive().optional(),
|
|
debounceSeconds: z.number().int().positive().optional(),
|
|
maxUpdatesPerHour: z.number().int().positive().optional(),
|
|
triggers: statusCardRefreshTriggersSchema.prefault({}),
|
|
activeHours: z
|
|
.object({
|
|
start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/),
|
|
end: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/),
|
|
timezone: z.string().trim().min(1).refine(isValidTimeZone, { message: "Invalid timezone identifier" }),
|
|
})
|
|
.optional(),
|
|
dailyTokenCap: z.number().int().positive().optional(),
|
|
})
|
|
.superRefine((policy, ctx) => {
|
|
if (policy.mode === "interval" && policy.intervalMinutes === undefined) {
|
|
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["intervalMinutes"], message: "Required for interval mode" });
|
|
}
|
|
if (policy.mode === "reactive" && policy.debounceSeconds === undefined) {
|
|
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["debounceSeconds"], message: "Required for reactive mode" });
|
|
}
|
|
});
|
|
|
|
export const defaultStatusCardRefreshPolicy = statusCardRefreshPolicySchema.parse({ mode: "manual" });
|
|
|
|
export const statusCardFingerprintSchema = z.record(
|
|
z.string(),
|
|
z.object({
|
|
status: z.string(),
|
|
updatedAt: z.string().datetime(),
|
|
latestHumanCommentAt: z.string().datetime().nullable().optional(),
|
|
identifier: z.string().nullable().optional(),
|
|
title: z.string().optional(),
|
|
assigneeAgentId: z.string().guid().nullable().optional(),
|
|
assigneeUserId: z.string().nullable().optional(),
|
|
}),
|
|
);
|
|
|
|
export const statusCardSchema = z.object({
|
|
id: z.string().guid(),
|
|
companyId: z.string().guid(),
|
|
createdByUserId: z.string().nullable(),
|
|
createdByAgentId: z.string().guid().nullable(),
|
|
title: z.string().nullable(),
|
|
titlePinned: z.boolean(),
|
|
interestPrompt: z.string(),
|
|
queries: z.array(companySearchQuerySchema),
|
|
queryVersion: z.number().int().nonnegative(),
|
|
queryCompiledAt: z.string().datetime().nullable(),
|
|
queryCompiledByAgentId: z.string().guid().nullable(),
|
|
agentId: z.string().guid().nullable(),
|
|
refreshPolicy: statusCardRefreshPolicySchema,
|
|
state: statusCardStateSchema,
|
|
pendingChangeCount: z.number().int().nonnegative(),
|
|
lastChangeAt: z.string().datetime().nullable(),
|
|
fingerprint: statusCardFingerprintSchema.nullable(),
|
|
fingerprintAt: z.string().datetime().nullable(),
|
|
mentionedIssueIds: z.array(z.string().guid()).default([]),
|
|
documentId: z.string().guid().nullable(),
|
|
lastUpdateRunKind: z.enum(["full", "incremental"]).nullable(),
|
|
lastGeneratedAt: z.string().datetime().nullable(),
|
|
lastModel: z.string().nullable(),
|
|
generatingIssueId: z.string().guid().nullable(),
|
|
failureReason: z.string().nullable(),
|
|
nextEvalAt: z.string().datetime().nullable(),
|
|
archivedAt: z.string().datetime().nullable(),
|
|
archivedByUserId: z.string().nullable(),
|
|
archivedByAgentId: z.string().guid().nullable(),
|
|
createdAt: z.string().datetime(),
|
|
updatedAt: z.string().datetime(),
|
|
summaryBody: z.string().nullable().optional(),
|
|
watchedIssueCount: z.number().int().nonnegative().optional(),
|
|
todayTokens: z.number().int().nonnegative().optional(),
|
|
todayCostCents: z.number().nonnegative().optional(),
|
|
/** Company-scoped board route where people view, restore and refresh the card. */
|
|
href: z.string().optional(),
|
|
});
|
|
|
|
export const statusCardUpdateChangeSchema = z.object({
|
|
issueId: z.string().guid(),
|
|
identifier: z.string(),
|
|
from: z.string().nullable(),
|
|
to: z.string().nullable(),
|
|
changeKind: z.string(),
|
|
});
|
|
|
|
export const statusCardUpdateSchema = z.object({
|
|
id: z.string().guid(),
|
|
cardId: z.string().guid(),
|
|
kind: statusCardUpdateKindSchema,
|
|
trigger: statusCardUpdateTriggerSchema,
|
|
generationIssueId: z.string().guid().nullable(),
|
|
runId: z.string().guid().nullable(),
|
|
changes: z.array(statusCardUpdateChangeSchema),
|
|
inputTokens: z.number().int().nonnegative(),
|
|
outputTokens: z.number().int().nonnegative(),
|
|
costCents: z.number().nonnegative(),
|
|
model: z.string().nullable(),
|
|
queryVersion: z.number().int().nonnegative().nullable(),
|
|
changeSummary: z.string().nullable(),
|
|
startedAt: z.string().datetime(),
|
|
finishedAt: z.string().datetime().nullable(),
|
|
status: statusCardUpdateStatusSchema,
|
|
error: z.string().nullable(),
|
|
});
|
|
|
|
export const statusCardSummaryRevisionSchema = z.object({
|
|
id: z.string().guid(),
|
|
revisionNumber: z.number().int().positive(),
|
|
title: z.string().nullable(),
|
|
body: z.string(),
|
|
changeSummary: z.string().nullable(),
|
|
createdAt: z.string().datetime(),
|
|
});
|
|
|
|
export const listStatusCardsQuerySchema = z.object({
|
|
archived: z.preprocess(
|
|
(value) => (value === "true" ? true : value === "false" ? false : value),
|
|
z.boolean().default(false),
|
|
),
|
|
});
|
|
|
|
export const createStatusCardSchema = z.object({
|
|
interestPrompt: z.string().trim().min(1).max(20_000),
|
|
title: z.string().trim().min(1).max(300).optional(),
|
|
titlePinned: z.boolean().default(false),
|
|
agentId: z.string().guid().nullable().optional(),
|
|
refreshPolicy: statusCardRefreshPolicySchema.default(defaultStatusCardRefreshPolicy),
|
|
});
|
|
|
|
export const patchStatusCardSchema = z
|
|
.object({
|
|
interestPrompt: z.string().trim().min(1).max(20_000).optional(),
|
|
title: z.string().trim().min(1).max(300).nullable().optional(),
|
|
titlePinned: z.boolean().optional(),
|
|
agentId: z.string().guid().nullable().optional(),
|
|
refreshPolicy: statusCardRefreshPolicySchema.optional(),
|
|
archived: z.boolean().optional(),
|
|
})
|
|
.refine((value) => Object.keys(value).length > 0, "At least one field is required");
|
|
|
|
export const refreshStatusCardSchema = z.object({
|
|
full: z.boolean().default(false),
|
|
});
|
|
|
|
export const writeStatusCardQuerySchema = z.object({
|
|
queries: z.array(companySearchQuerySchema).min(1).max(10),
|
|
title: z.string().trim().min(1).max(300),
|
|
changeSummary: z.string().trim().min(1).max(2_000),
|
|
generationIssueId: z.string().guid(),
|
|
});
|
|
|
|
export const writeStatusCardSummarySchema = z.object({
|
|
markdown: z.string().trim().min(1).max(200_000),
|
|
title: z.string().trim().min(1).max(300).optional(),
|
|
changeSummary: z.string().trim().min(1).max(2_000),
|
|
generationIssueId: z.string().guid(),
|
|
model: z.string().trim().min(1).max(200).optional().nullable(),
|
|
});
|
|
|
|
export type StatusCard = z.infer<typeof statusCardSchema>;
|
|
export type StatusCardRefreshPolicy = z.infer<typeof statusCardRefreshPolicySchema>;
|
|
export type StatusCardUpdate = z.infer<typeof statusCardUpdateSchema>;
|
|
export type StatusCardSummaryRevision = z.infer<typeof statusCardSummaryRevisionSchema>;
|
|
export type CreateStatusCard = z.infer<typeof createStatusCardSchema>;
|
|
export type PatchStatusCard = z.infer<typeof patchStatusCardSchema>;
|
|
export type RefreshStatusCard = z.infer<typeof refreshStatusCardSchema>;
|
|
export type WriteStatusCardQuery = z.infer<typeof writeStatusCardQuerySchema>;
|
|
export type WriteStatusCardSummary = z.infer<typeof writeStatusCardSummarySchema>;
|