Files
PaperClipAI/packages/shared/src/validators/status-card.ts
T
DottaandClaude Opus 5.5 adb7633d7b fix(status-cards): give agents the person's restore route when archiving a card (#19903)
## 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>
2026-11-07 16:28:11 -06:00

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>;