diff --git a/packages/shared/src/validators/status-card.ts b/packages/shared/src/validators/status-card.ts index 0dccd38bed2..9095a835a40 100644 --- a/packages/shared/src/validators/status-card.ts +++ b/packages/shared/src/validators/status-card.ts @@ -102,6 +102,8 @@ export const statusCardSchema = z.object({ 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({ diff --git a/server/src/__tests__/openapi-routes.test.ts b/server/src/__tests__/openapi-routes.test.ts index baae442e78c..9dcba27a991 100644 --- a/server/src/__tests__/openapi-routes.test.ts +++ b/server/src/__tests__/openapi-routes.test.ts @@ -557,6 +557,14 @@ describe("openapi routes", () => { expect(dismiss.description).toContain("viewers may dismiss their own"); }); + it("tells agents that archiving keeps a status card and where a person restores it", async () => { + const res = await request(createApp()).get("/api/openapi.json"); + const patch = res.body.paths["/api/status-cards/{id}"].patch; + expect(patch.description).toContain("it is not deleted"); + expect(patch.description).toContain("give them the returned href as a Markdown link"); + expect(patch.description).toContain("Restoring (archived: false) starts a fresh full summary"); + }); + it("documents exact failed-run selection and durable accepted retry responses", async () => { const res = await request(createApp()).get("/api/openapi.json"); const wake = res.body.paths["/api/agents/{id}/wakeup"].post; diff --git a/server/src/__tests__/status-cards.test.ts b/server/src/__tests__/status-cards.test.ts index c1faade83fa..a0a89a7dd82 100644 --- a/server/src/__tests__/status-cards.test.ts +++ b/server/src/__tests__/status-cards.test.ts @@ -168,6 +168,73 @@ describeEmbeddedPostgres("status card routes", () => { expect(await db.select().from(issues).then((rows) => rows[0])).toMatchObject({ status: "cancelled" }); }); + it("creates nothing when the card link cannot be resolved", async () => { + const company = await seedCompany(); + await enableStatusCards(); + await seedSummarizer(company.id); + // The link lookup runs before the card is created, so its failure cannot strand a queued compile task. + const failingPrefixDb = new Proxy(db, { + get(target, property) { + if (property === "select") { + return (fields?: Record) => { + if (fields && "issuePrefix" in fields) throw new Error("company read unavailable"); + return target.select(fields as never); + }; + } + const value = Reflect.get(target, property, target); + return typeof value === "function" ? value.bind(target) : value; + }, + }) as Db; + const response = await request(createApp(failingPrefixDb, localBoardActor())) + .post(`/api/companies/${company.id}/status-cards`) + .send({ interestPrompt: "Recently updated launch tasks" }); + + expect(response.status).toBe(500); + expect(await db.select().from(statusCards)).toEqual([]); + expect(await db.select().from(issues)).toEqual([]); + }); + + it("keeps a card with a queued compile when its activity record fails", async () => { + const company = await seedCompany(); + await enableStatusCards(); + await seedSummarizer(company.id); + // Fail only the card's creation activity record, which is written after the compile is queued. + const failingActivityDb = new Proxy(db, { + get(target, property) { + if (property === "insert") { + return (table: unknown) => { + const builder = target.insert(table as never); + if (table !== activityLog) return builder; + return new Proxy(builder, { + get(inner, key) { + if (key === "values") { + return (values: { action?: string }) => { + if (values?.action === "status_card.created") throw new Error("activity log unavailable"); + return inner.values(values as never); + }; + } + const value = Reflect.get(inner, key, inner); + return typeof value === "function" ? value.bind(inner) : value; + }, + }); + }; + } + const value = Reflect.get(target, property, target); + return typeof value === "function" ? value.bind(target) : value; + }, + }) as Db; + const response = await request(createApp(failingActivityDb, localBoardActor())) + .post(`/api/companies/${company.id}/status-cards`) + .send({ interestPrompt: "Recently updated launch tasks" }); + + expect(response.status).toBe(500); + const cards = await db.select().from(statusCards); + expect(cards).toHaveLength(1); + const generation = await db.select().from(issues).where(eq(issues.id, cards[0]!.generatingIssueId!)).then((rows) => rows[0]); + expect(generation).toBeDefined(); + expect(generation!.status).not.toBe("cancelled"); + }); + it("creates, patches, archives, restores, lists updates, and deletes a card", async () => { const company = await seedCompany(); await enableStatusCards(); @@ -211,7 +278,9 @@ describeEmbeddedPostgres("status card routes", () => { const archived = await request(app).patch(`/api/status-cards/${created.body.id}`).send({ archived: true }); expect(archived.status).toBe(200); - expect(archived.body).toMatchObject({ archivedAt: expect.any(String), generatingIssueId: null }); + // The person's restore route travels with the archive receipt, so an agent can link it. + expect(archived.body).toMatchObject({ archivedAt: expect.any(String), generatingIssueId: null, href: `/${company.issuePrefix}/status/${created.body.id}` }); + expect((await request(app).get(`/api/status-cards/${created.body.id}`)).body.href).toBe(`/${company.issuePrefix}/status/${created.body.id}`); expect(await db.select().from(issues).where(eq(issues.id, created.body.generatingIssueId)).then((rows) => rows[0]?.status)).toBe("cancelled"); expect((await request(app).get(`/api/companies/${company.id}/status-cards`)).body).toEqual([]); expect((await request(app).get(`/api/companies/${company.id}/status-cards?archived=true`)).body).toHaveLength(1); diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index b52b5c716e7..d6745237251 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -3443,6 +3443,9 @@ registerCurrentRoute({ path: "/api/status-cards/{id}", tags: ["status-cards"], summary: "Update, archive, or restore a status card", + description: "Archiving (archived: true) hides the card from the active list but keeps the card, its summary and its update history; it is not deleted. " + + "A person views and restores archived cards on the company's Status page (Show archived, then Restore); give them the returned href as a Markdown link. " + + "Restoring (archived: false) starts a fresh full summary for a card with a compiled query, so restored content is regenerated before it is current.", body: patchStatusCardSchema, }); diff --git a/server/src/routes/status-cards.ts b/server/src/routes/status-cards.ts index d21616b7cf2..b86de76ae97 100644 --- a/server/src/routes/status-cards.ts +++ b/server/src/routes/status-cards.ts @@ -1,5 +1,6 @@ import { Router, type Request } from "express"; -import type { Db } from "@paperclipai/db"; +import { companies, type Db } from "@paperclipai/db"; +import { eq } from "drizzle-orm"; import { createStatusCardSchema, listStatusCardsQuerySchema, @@ -30,6 +31,16 @@ export function statusCardRoutes(db: Db, opts: { heartbeat?: IssueAssignmentWake const issueSvc = issueService(db); const heartbeat = opts.heartbeat ?? heartbeatService(db); + // People view, restore and refresh a card on the company's Status page. Single-card responses carry that + // route so an agent can give the person a usable link instead of an API instruction. + async function companyIssuePrefix(companyId: string) { + const [company] = await db.select({ issuePrefix: companies.issuePrefix }).from(companies).where(eq(companies.id, companyId)).limit(1); + return company?.issuePrefix ?? null; + } + function withHref(card: T, issuePrefix: string | null) { + return issuePrefix ? { ...card, href: `/${issuePrefix}/status/${card.id}` } : card; + } + async function assertStatusCardsEnabled() { const experimental = await settings.getExperimental(); if (experimental.enableStatusCards !== true) throw notFound("Status cards are not enabled"); @@ -161,27 +172,32 @@ export function statusCardRoutes(db: Db, opts: { heartbeat?: IssueAssignmentWake await assertCanMutate(req, companyId); assertAgentPromptLimit(req, req.body.interestPrompt); const actor = getActorInfo(req); + // Resolve the link before creating the card, so a failed lookup leaves nothing behind. + const issuePrefix = await companyIssuePrefix(companyId); const card = await service.create(companyId, req.body, { agentId: actor.actorType === "agent" ? actor.actorId : null, userId: actor.actorType === "user" ? actor.actorId : null, }); + // Only a failure to queue the compile removes the new card. Once the compile is queued, the card + // and its generation task exist together, so later failures must not delete the card alone. + let compile: Awaited>; try { - const compile = await enqueueCompile(req, card.id); - await logMutation(req, companyId, "status_card.created", card.id, { state: card.state }); - res.status(201).json(publicCard(compile.card)); + compile = await enqueueCompile(req, card.id); } catch (error) { await service.remove(card.id); throw error; } + await logMutation(req, companyId, "status_card.created", card.id, { state: card.state }); + res.status(201).json(withHref(publicCard(compile.card), issuePrefix)); }); router.get("/status-cards/:id", async (req, res) => { await assertStatusCardsEnabled(); const card = await getAccessibleResource(req, res, service.getById(req.params.id as string), "Status card not found"); if (!card) return; - res.json(publicCard(await service.hydrate(card, { + res.json(withHref(publicCard(await service.hydrate(card, { issueReadCondition: await issueReadSqlCondition(db, req.actor), - }))); + })), await companyIssuePrefix(card.companyId))); }); router.patch("/status-cards/:id", validate(patchStatusCardSchema), async (req, res) => { @@ -203,7 +219,7 @@ export function statusCardRoutes(db: Db, opts: { heartbeat?: IssueAssignmentWake fields: Object.keys(req.body), archived: Boolean(updated.archivedAt), }); - res.json(publicCard(compile?.card ?? restore?.card ?? updated)); + res.json(withHref(publicCard(compile?.card ?? restore?.card ?? updated), await companyIssuePrefix(card.companyId))); }); router.delete("/status-cards/:id", async (req, res) => {