Files
PaperClipAI/ui/src/lib/activity-format.ts
T
DottaandClaude Opus 5.5 90ae3c4337 fix(native): process a superseded export's late stop receipt and stop its sandbox when none arrives (#21143)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - A native run can be retired as superseded while its workspace export
fails. Its files stay unsaved, and the run stays the writer of the
task's workspace.
> - #21136 records those files for the automatic workspace recovery.
That record needs the sandbox's stop-and-retain receipt.
> - The native run projection worker checked for that receipt for one
hour after the run ended. After that, it dropped the run. Nothing woke
it when the receipt arrived later.
> - If the receipt came late or never, the run kept the task's workspace
fenced. Every queued run on the task waited and then failed setup.
Nobody owned the problem.
> - This pull request makes the worker process a late receipt, stop and
keep the sandbox itself when no receipt arrives, and never drop the run
silently.
> - The benefit is that the task's queue moves again by itself, and two
writers never use one workspace.

## Linked Issues or Issue Description

Refs #21136 (review thread on
`native-superseded-workspace-export.ts:84`)

**What happened?**
`preserveSupersededWorkspaceExport` returned `recheckAt: null` when the
sandbox stop receipt had not arrived within `finishedAt + 1h`. The
projection worker then deleted its entry. A later stop receipt
(`settleStopOnlyCleanup`) woke only the workspace recovery queue, not
the projection queue. `preserveNativeFailedWorkspace` requires
`hasConfirmedSandboxStopAndRetain`, so no hold was recorded. The run
stayed the dirty writer, and queued runs kept failing setup.

**Expected behavior**
A late receipt is processed at once. When no receipt arrives, Paperclip
stops and keeps the sandbox itself and waits for the provider's
confirmation. The workspace stays held while the sandbox may still run.
When the provider confirms that the sandbox is gone, the task continues
from its last save. When the stop stays unconfirmed for hours, the task
shows one plain notice, and the check continues.

**Steps to reproduce**
1. Retire a native run as superseded after its workspace export fails
(the #21136 shape).
2. Let the run's sandbox stop not settle (for example, the server that
owned the release is replaced).
3. Wait more than one hour after the run ended.
4. See that the projection worker drops the run, and that a later stop
receipt records nothing. The workspace stays held.

## What Changed

- `sandbox-stop-and-retain.ts`: a confirmed stop-only receipt now also
notifies `DELIVERY_QUEUES.nativeRunProjection` (scoped to the company
and run). New `prepareUnconfirmedSourceSandboxStop` puts a
stop-and-retain intent on the source lease from its current status. It
skips a destroyed sandbox, a stop already in progress, and a cleanup in
flight.
- `native-superseded-workspace-export.ts`:
- Within one hour of the run ending, the worker checks every minute
(unchanged).
- After that hour, it requests the stop-and-retain itself. The existing
pending-cleanup sweep dispatches the stop and retries it until the
provider confirms. The worker checks again every 15 minutes, and the
receipt wakes it at once. The workspace stays held.
  - A sandbox that another lease holds is never stopped.
- When the provider confirms that the sandbox was destroyed, the files
cannot be saved. In one transaction (task, run, then workspace locks),
the worker sets aside only that run's workspace epoch, wakes queued-run
dispatch, and records `issue.previous_run_files_lost` on the task.
- When the stop is still unconfirmed six hours after the run ended (or
the sandbox is held by another lease), the task gets one
`issue.previous_run_files_waiting` activity entry. The worker keeps
checking. It never drops the run.
- A stop-only dispatch now settles when the provider confirms that the
exact sandbox is already gone. Before, the runtime accepted only a
`stopped` reply and threw on `destroyed`, so a gone sandbox kept the
stop pending forever.
- `sandbox-stop-and-retain.ts`: new `acceptedStopOnlyReceipt` accepts
`stopped`, or `destroyed` for a stop-and-retain intent (a native
workspace export resume still needs `stopped`). `settleStopOnlyCleanup`
stores a `destroyed` receipt as `released` / `success` /
`workspace_source_unavailable`, removes the stop intent, never writes a
retain receipt, and wakes the projection and workspace recovery queues.
- `environment-runtime.ts`: the plugin `environmentStopLease` and
built-in `stopLease` checks use `acceptedStopOnlyReceipt`.
- `workspace-recovery.ts`: when its own stop settles as `destroyed`, the
source is unavailable (the existing alternative-strategy path) instead
of a binding failure.
- Daytona plugin: stop of a sandbox that Daytona reports as not found
returns `destroyed` (destroy already did this) instead of throwing. boxd
already returns `destroyed`. Other sandbox plugins have no stop-only
method, so nothing changes for them.
- New shared `SANDBOX_ALLOCATION_HOLDER_STATUSES` (`active`, `retained`,
`pending_cleanup`). The stop-only cleanup ownership check and the
worker's "held by another lease" guard both use it, so a retained warm
sandbox is never stopped and the two checks cannot drift.
- `ui/src/lib/activity-format.ts`: plain labels for the two task
activity entries. They do not ask a person to fix anything.
- `doc/execution-semantics.md`: document the rule.
- Not changed: the shared owner prover still refuses to treat a stopped
instance on another host as proof that its child processes stopped.

## Verification

- `server/src/services/superseded-workspace-export-recovery.test.ts` (4
new tests, red/green):
- "checks again every minute while the run's own release may still stop
its sandbox": the recheck branch. Nothing is recorded or stopped, and
the workspace keeps its writer.
- "stops and keeps the sandbox itself when no stop receipt arrived, and
records the files once the late receipt lands": after the hour, the
lease gets a stop-only intent. A second pass changes nothing. The late
receipt wakes the projection queue. The next check records the hold, and
the system recovery frees the workspace. Fails on master (`expected {
…(19) } to match object { status: 'pending_cleanup' }`).
- "names the unconfirmed stop on the task once, and keeps checking, when
the provider never confirms it": the expiry branch. One notice, the
check continues, no hold, and the workspace stays held. Fails on master.
- "continues from the last save when the provider confirms the sandbox
is gone": epoch 1 is set aside, the workspace is free, the task says so,
and the result is not applied. Fails on master.
- Review-round tests (all 5 fail on the first head `a208bfa58f`, pass
now):
- `environment-runtime.test.ts` "settles a plugin stop whose provider
reports the sandbox gone (boxd, Daytona not found) through the cleanup
sweep": provider dispatch through `releaseRunLeases` and
`sweepPendingCleanupLeases`. The lease settles `released` with a
`destroyed` receipt and no retain receipt.
- `environment-runtime.test.ts` "settles a built-in stop whose provider
reports the sandbox gone, without claiming retained files": the built-in
`stopLease` path. No destroy call.
- `superseded-workspace-export-recovery.test.ts` "continues from the
last save when Paperclip's own stop finds the sandbox already gone": the
worker's stop request gets a `destroyed` reply, the projection queue
wakes, and the workspace is freed at epoch 2.
- `superseded-workspace-export-recovery.test.ts` "never stops a sandbox
a retained warm lease still holds, says so once and keeps checking": the
source lease is unchanged, a recheck is returned, and `sandbox_in_use`
is recorded.
- Daytona `plugin.test.ts` "explicit stop confirms a sandbox Daytona no
longer has as destroyed".
- `environment-runtime.test.ts` (207) and Daytona `plugin.test.ts` (421)
pass.
- Related suites pass: `native-run-projection-work`,
`retained-native-session-cleanup-work`, `workspace-recovery-stop-proof`,
`native-failed-workspace-recovery`, `legacy-workspace-restore-recovery`,
`environment-retained-orphan-sandbox`,
`workspace-recovery-retry-copyback`, `workspace-recovery-fallback` (398
tests), and `ui/src/lib/activity-format.test.ts`.
- `tsc --noEmit` for `server`.

## Risks

- Low to medium risk. The new behavior acts only on an ended superseded
run that failed in its workspace export, still holds a dirty workspace,
and has no retained-file hold.
- The worker now stops an ended run's sandbox one hour after the run
ended if no stop receipt arrived. The stop uses the existing stop-only
contract and keeps the sandbox. A sandbox held by another lease is never
stopped.
- A destroyed sandbox's unsaved files are not recoverable. The task
continues from its last save and says so.
- If a provider never confirms a stop, the workspace stays held (by
design: no second writer). The task shows one notice, and Paperclip
keeps retrying.
- Shared cleanup code now treats a confirmed `destroyed` stop-only reply
as settled. Every caller was checked: the cleanup sweep and run release
count it as settled; the workspace recovery treats the source as
unavailable; the fallback treats it as stopped (nothing can run there).
No caller reads it as retained files, because no retain receipt is
written. A native workspace export resume still requires `stopped`.
- Each extra delivery notification per settled stop-only cleanup is
cheap. The projection worker's scoped load finds nothing for runs that
do not match.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use (code
search, shell, test execution) in Claude Code.

## 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
- [x] 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-12 11:54:47 -06:00

572 lines
25 KiB
TypeScript

import type { Agent } from "@paperclipai/shared";
import type { CompanyUserProfile } from "./company-members";
import { formatReviewPolicyValue } from "./review-policy";
type ActivityDetails = Record<string, unknown> | null | undefined;
type ActivityParticipant = {
type: "agent" | "user";
agentId?: string | null;
userId?: string | null;
};
type ActivityIssueReference = {
id?: string | null;
identifier?: string | null;
title?: string | null;
};
interface ActivityFormatOptions {
agentMap?: Map<string, Agent>;
userProfileMap?: Map<string, CompanyUserProfile>;
currentUserId?: string | null;
}
const ACTIVITY_ROW_VERBS: Record<string, string> = {
"case.created": "created",
"case.updated": "updated",
"case.fields_changed": "updated details on",
"case.status_changed": "changed status on",
"case.issue_linked": "linked a task to",
"case.issue_unlinked": "unlinked a task from",
"case.child_linked": "linked a child to",
"case.attachment_added": "attached a file to",
"case.label_added": "added a label to",
"case.label_removed": "removed a label from",
"case.document_revised": "updated a document on",
"case.handoff_requested": "requested a handoff for",
"case.handoff_applied": "handed off",
"case.handoff_delivered": "delivered a handoff for",
"case.handoff_retry_requested": "retried a handoff for",
"case.handoff_cancelled": "cancelled a handoff for",
"case.handoff_completed": "completed",
"issue.created": "created",
"issue.updated": "updated",
"issue.read_marked": "read",
"issue.read_unmarked": "marked unread",
"issue.checked_out": "checked out",
"issue.released": "released",
"issue.comment_added": "commented on",
"issue.comment_cancelled": "cancelled a queued comment on",
"issue.queued_comment_edited": "edited a queued comment on",
"issue.queued_comments_reordered": "reordered queued comments on",
"issue.queued_comment_discarded": "discarded a queued comment on",
"issue.comment_deleted": "deleted a comment on",
"issue.attachment_added": "attached file to",
"issue.attachment_removed": "removed attachment from",
"issue.document_created": "created document for",
"issue.document_updated": "updated document on",
"issue.document_locked": "locked document on",
"issue.document_unlocked": "unlocked document on",
"issue.document_deleted": "deleted document from",
"issue.monitor_scheduled": "scheduled monitor on",
"issue.monitor_triggered": "triggered monitor for",
"issue.monitor_cleared": "cleared monitor on",
"issue.monitor_skipped": "skipped monitor for",
"issue.monitor_exhausted": "exhausted monitor on",
"issue.monitor_recovery_wake_queued": "queued monitor recovery for",
"issue.monitor_recovery_issue_created": "created monitor recovery for",
"issue.monitor_escalated_to_board": "escalated monitor for",
"issue.commented": "commented on",
"issue.deleted": "deleted",
"issue.successful_run_handoff_required": "flagged missing next step on",
"issue.successful_run_handoff_resolved": "recorded next step chosen on",
"issue.successful_run_handoff_escalated": "escalated missing next step on",
"issue.accepted_plan_decomposition_updated": "updated accepted-plan decomposition on",
"issue.recovery_action_opened": "opened a recovery action on",
"issue.workspace_recovered": "recovered saved work for",
"issue.retry_continued_from_saved_work": "continued from saved work on",
"issue.workspace_recovery_requested": "requested workspace recovery for",
"issue.previous_run_files_waiting": "is still working to save the previous run's files on",
"issue.previous_run_files_lost": "continued from the last save on",
"issue.recovery_action_resolved": "resolved the recovery action on",
"issue.recovery_action_escalated": "escalated the recovery action on",
"agent.created": "created",
"agent.updated": "updated",
"agent.paused": "paused",
"agent.resumed": "resumed",
"agent.error_cleared": "cleared error on",
"agent.terminated": "terminated",
"agent.key_created": "created API key for",
"agent.budget_updated": "updated budget for",
"agent.runtime_session_reset": "reset session for",
"heartbeat.invoked": "invoked heartbeat for",
"heartbeat.cancelled": "cancelled heartbeat for",
"heartbeat.output_stale_source_resolved": "system-folded stale run on",
"heartbeat.output_stale_recovery_recursion_refused": "refused recovery-on-recovery for",
"approval.created": "requested approval",
"approval.approved": "approved",
"approval.rejected": "rejected",
// Interaction outcomes (PAP-16506). An agent may now resolve one — including a
// review of its own work — so these must read as outcomes in the feed instead
// of falling through to the raw "issue thread interaction accepted" action id.
// `details.interactionKind` sharpens the wording; see INTERACTION_OUTCOME_LABELS.
"issue.thread_interaction_created": "asked for a decision on",
"issue.thread_interaction_accepted": "accepted the request on",
"issue.thread_interaction_rejected": "rejected the request on",
"issue.thread_interaction_answered": "answered the request on",
"issue.thread_interaction_withdrawn": "withdrew the request on",
"issue.thread_interaction_cancelled": "cancelled the request on",
"issue.thread_interaction_skipped": "skipped the request on",
"issue.thread_interaction_dismissed": "deferred the request on",
"issue.thread_interaction_expired": "expired the request on",
"issue.thread_interaction_item_verdicts_submitted": "submitted verdicts on",
"issue.stalled_review_decided": "recorded a review verdict on",
"project.created": "created",
"project.updated": "updated",
"project.deleted": "deleted",
"goal.created": "created",
"goal.updated": "updated",
"goal.deleted": "deleted",
"cost.reported": "reported cost for",
"cost.recorded": "recorded cost for",
"company.created": "created organization",
"company.updated": "updated organization",
"company.archived": "archived",
"company.reactivated": "reactivated",
"company.budget_updated": "updated budget for",
"audit.exported": "exported the agent audit log for",
"tool_app.connected": "connected",
"tool_app.oauth_connected": "connected credentials for",
"tool_app.oauth_failed": "failed to connect credentials for",
"tool_app.oauth_access_finalized": "finished credential access for",
"tool_app.finished": "finished setup for",
"tool_app.reconnected": "reconnected",
"tool_connection.created": "created",
"tool_connection.updated": "updated",
"tool_connection.archived": "removed",
"tool_connection.catalog_refresh": "refreshed actions for",
"tool_connection.installs_synced": "changed agent installs for",
"tool_connection.install_access_extended": "extended agent access for",
"tool_connection.grant_audience_replaced": "changed human access for",
"tool_connection.grant_added": "added credentials to",
"tool_connection.grant_revoked": "revoked credentials from",
"tool_connection.grant_delegated": "delegated credentials for",
"tool_connection.grant_delegation_revoked": "revoked credential delegation for",
};
const ISSUE_ACTIVITY_LABELS: Record<string, string> = {
"issue.created": "created the issue",
"issue.updated": "updated the issue",
"issue.checked_out": "checked out the issue",
"issue.released": "released the issue",
"issue.comment_added": "added a comment",
"issue.comment_cancelled": "cancelled a queued comment",
"issue.queued_comment_edited": "edited a queued comment",
"issue.queued_comments_reordered": "reordered queued comments",
"issue.queued_comment_discarded": "discarded a queued comment",
"issue.comment_deleted": "deleted a comment",
"issue.feedback_vote_saved": "saved feedback on an AI output",
"issue.attachment_added": "added an attachment",
"issue.attachment_removed": "removed an attachment",
"issue.document_created": "created a document",
"issue.document_updated": "updated a document",
"issue.document_locked": "locked a document",
"issue.document_unlocked": "unlocked a document",
"issue.document_deleted": "deleted a document",
"issue.monitor_scheduled": "scheduled a monitor",
"issue.monitor_triggered": "triggered a monitor",
"issue.monitor_cleared": "cleared a monitor",
"issue.monitor_skipped": "skipped a monitor",
"issue.monitor_exhausted": "exhausted a monitor",
"issue.monitor_recovery_wake_queued": "queued a monitor recovery wake",
"issue.monitor_recovery_issue_created": "created a monitor recovery issue",
"issue.monitor_escalated_to_board": "escalated a monitor to the board",
"issue.deleted": "deleted the issue",
"issue.successful_run_handoff_required": "Run finished without a clear next step",
"issue.successful_run_handoff_resolved": "Next step chosen",
"issue.successful_run_handoff_escalated": "Run finished without a next step - recovery escalated",
"issue.cross_issue_influence_cap_rejected": "hit the per-run cross-task write cap",
"issue.cross_issue_influence_observed": "made a cross-task write",
"issue.attribution_spoof_rejected": "tried to choose its own responsible user",
"issue.recovery_action_opened": "Opened a source-scoped recovery action",
"issue.workspace_recovered": "Saved work recovered.",
"issue.retry_continued_from_saved_work": "Retry continued from saved work.",
"issue.workspace_recovery_requested": "Requested workspace recovery",
"issue.previous_run_files_waiting": "Still working to save the previous run's unsaved files. New runs start once they are saved. Paperclip keeps trying on its own.",
"issue.previous_run_files_lost": "Could not save the previous run's unsaved files because they were already gone. This task continues from its last save.",
"issue.recovery_action_resolved": "Resolved the recovery action",
"issue.recovery_action_escalated": "Escalated the recovery action",
"issue.accepted_plan_decomposition_updated": "updated the accepted-plan decomposition",
"agent.created": "created an agent",
"agent.updated": "updated the agent",
"agent.paused": "paused the agent",
"agent.resumed": "resumed the agent",
"agent.error_cleared": "cleared the agent error",
"agent.terminated": "terminated the agent",
"heartbeat.invoked": "invoked a heartbeat",
"heartbeat.cancelled": "cancelled a heartbeat",
"heartbeat.output_stale_source_resolved": "System folded a stale run",
"heartbeat.output_stale_recovery_recursion_refused": "Refused recovery-on-recovery escalation",
"approval.created": "requested approval",
"approval.approved": "approved",
"approval.rejected": "rejected",
"issue.thread_interaction_created": "asked for a decision",
"issue.thread_interaction_accepted": "accepted the request",
"issue.thread_interaction_rejected": "rejected the request",
"issue.thread_interaction_answered": "answered the request",
"issue.thread_interaction_withdrawn": "withdrew the request",
"issue.thread_interaction_cancelled": "cancelled the request",
"issue.thread_interaction_skipped": "skipped the request",
"issue.thread_interaction_dismissed": "deferred the request",
"issue.thread_interaction_expired": "expired the request",
"issue.thread_interaction_item_verdicts_submitted": "submitted verdicts on the request",
"issue.stalled_review_decided": "recorded a review verdict",
};
/**
* `issue.stalled_review_decided` carries the verb the actor chose, so the line
* names the verdict ("approved the review") rather than the generic action.
* Mirrors `StalledReviewDecisionAction` in shared.
*/
const STALLED_REVIEW_DECISION_LABELS: Record<string, string> = {
approve: "approved the review",
request_changes: "requested changes on the review",
send_back: "sent the review back to work",
};
/**
* `issue.thread_interaction_accepted` / `_rejected` fire for *every* interaction
* kind, not only for a review. A task suggestion or a question is accepted, not
* approved, so the kind on the event picks the verb. Kinds absent from a map
* keep the neutral "accepted the request" wording from the tables above, which
* is also the fallback for an event that carries no kind.
*/
const INTERACTION_ACCEPTED_LABELS: Record<string, string> = {
request_confirmation: "approved the request",
request_checkbox_confirmation: "approved the request",
suggest_tasks: "accepted the task suggestions",
ask_user_questions: "accepted the answers",
};
const INTERACTION_REJECTED_LABELS: Record<string, string> = {
request_confirmation: "rejected the request",
request_checkbox_confirmation: "rejected the request",
suggest_tasks: "declined the task suggestions",
ask_user_questions: "declined the questions",
};
/**
* Kind-aware wording for an interaction outcome, or `null` when the tables
* above already say it well enough.
*/
function formatInteractionOutcomeLabel(action: string, details: ActivityDetails): string | null {
const table = action === "issue.thread_interaction_accepted"
? INTERACTION_ACCEPTED_LABELS
: action === "issue.thread_interaction_rejected"
? INTERACTION_REJECTED_LABELS
: null;
if (!table) return null;
const kind = typeof details?.interactionKind === "string" ? details.interactionKind : null;
return kind ? table[kind] ?? null : null;
}
function asRecord(value: unknown): Record<string, unknown> | null {
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
return value as Record<string, unknown>;
}
function humanizeValue(value: unknown): string {
if (typeof value !== "string") return String(value ?? "none");
return value.replace(/_/g, " ");
}
function isActivityParticipant(value: unknown): value is ActivityParticipant {
const record = asRecord(value);
if (!record) return false;
return record.type === "agent" || record.type === "user";
}
function isActivityIssueReference(value: unknown): value is ActivityIssueReference {
return asRecord(value) !== null;
}
function readParticipants(details: ActivityDetails, key: string): ActivityParticipant[] {
const value = details?.[key];
if (!Array.isArray(value)) return [];
return value.filter(isActivityParticipant);
}
function readIssueReferences(details: ActivityDetails, key: string): ActivityIssueReference[] {
const value = details?.[key];
if (!Array.isArray(value)) return [];
return value.filter(isActivityIssueReference);
}
function formatUserLabel(userId: string | null | undefined, options: ActivityFormatOptions = {}): string {
if (!userId || userId === "local-board") return "Board";
if (options.currentUserId && userId === options.currentUserId) return "You";
const profile = options.userProfileMap?.get(userId);
if (profile) return profile.label;
return `user ${userId.slice(0, 5)}`;
}
function formatParticipantLabel(participant: ActivityParticipant, options: ActivityFormatOptions): string {
if (participant.type === "agent") {
const agentId = participant.agentId ?? "";
return options.agentMap?.get(agentId)?.name ?? "agent";
}
return formatUserLabel(participant.userId, options);
}
function formatIssueReferenceLabel(reference: ActivityIssueReference): string {
if (reference.identifier) return reference.identifier;
if (reference.title) return reference.title;
if (reference.id) return reference.id.slice(0, 8);
return "task";
}
function formatChangedEntityLabel(
singular: string,
plural: string,
labels: string[],
): string {
if (labels.length <= 0) return plural;
if (labels.length === 1) return `${singular} ${labels[0]}`;
return `${labels.length} ${plural}`;
}
function readNumber(value: unknown): number | null {
if (typeof value === "number" && Number.isFinite(value)) return value;
return null;
}
function readStringArrayLength(value: unknown): number {
if (!Array.isArray(value)) return 0;
return value.filter((entry) => typeof entry === "string" && entry.length > 0).length;
}
function formatAcceptedPlanDecompositionDetail(details: ActivityDetails): string | null {
if (!details) return null;
const status = typeof details.status === "string" ? details.status : null;
const requested = readNumber(details.requestedChildCount);
const totalChildren = readStringArrayLength(details.childIssueIds);
const newlyCreated = readStringArrayLength(details.newlyCreatedChildIssueIds);
const reused = Math.max(0, totalChildren - newlyCreated);
const parts: string[] = [];
if (newlyCreated > 0) parts.push(`created ${newlyCreated} new`);
if (reused > 0) parts.push(`reused ${reused} existing`);
if (parts.length === 0 && requested !== null) parts.push(`${requested} requested`);
const summary = parts.length > 0 ? parts.join(", ") : null;
if (status === "completed" && summary) return `decomposition completed (${summary})`;
if (status === "completed") return "decomposition completed";
if (status === "in_flight" && summary) return `decomposition in flight (${summary})`;
return summary;
}
function formatIssueUpdatedVerb(details: ActivityDetails): string | null {
if (!details) return null;
const previous = asRecord(details._previous) ?? {};
if (details.status !== undefined) {
const from = previous.status;
const to = humanizeValue(details.status === "in_review" && details.externalConversationState === "waiting" ? "idle" : details.status);
return from
? `changed status from ${humanizeValue(from)} to ${to} on`
: `changed status to ${to} on`;
}
if (details.priority !== undefined) {
const from = previous.priority;
return from
? `changed priority from ${humanizeValue(from)} to ${humanizeValue(details.priority)} on`
: `changed priority to ${humanizeValue(details.priority)} on`;
}
return null;
}
function formatAssigneeName(details: ActivityDetails, options: ActivityFormatOptions): string | null {
if (!details) return null;
const agentId = details.assigneeAgentId;
const userId = details.assigneeUserId;
if (typeof agentId === "string" && agentId) {
return options.agentMap?.get(agentId)?.name ?? "agent";
}
if (typeof userId === "string" && userId) {
return formatUserLabel(userId, options);
}
return null;
}
function formatIssueUpdatedAction(details: ActivityDetails, options: ActivityFormatOptions = {}): string | null {
if (!details) return null;
const previous = asRecord(details._previous) ?? {};
const parts: string[] = [];
if (details.status !== undefined) {
const from = previous.status;
const to = humanizeValue(details.status === "in_review" && details.externalConversationState === "waiting" ? "idle" : details.status);
parts.push(
from
? `changed the status from ${humanizeValue(from)} to ${to}`
: `changed the status to ${to}`,
);
}
if (details.priority !== undefined) {
const from = previous.priority;
parts.push(
from
? `changed the priority from ${humanizeValue(from)} to ${humanizeValue(details.priority)}`
: `changed the priority to ${humanizeValue(details.priority)}`,
);
}
if (details.assigneeAgentId !== undefined || details.assigneeUserId !== undefined) {
const assigneeName = formatAssigneeName(details, options);
parts.push(assigneeName ? `made ${assigneeName} responsible for the task` : "cleared the responsible");
}
if (details.reviewPolicy !== undefined) {
// `null` is the default ("anyone can approve"), so it must not read as
// "changed the review policy to none" (PAP-16506).
parts.push(`changed who can approve to ${formatReviewPolicyValue(details.reviewPolicy)}`);
}
if (details.title !== undefined) parts.push("updated the title");
if (details.description !== undefined) parts.push("updated the description");
return parts.length > 0 ? parts.join(", ") : null;
}
function formatStructuredIssueChange(input: {
action: string;
details: ActivityDetails;
options: ActivityFormatOptions;
forIssueDetail: boolean;
}): string | null {
const details = input.details;
if (!details) return null;
if (input.action === "issue.blockers_updated") {
const added = readIssueReferences(details, "addedBlockedByIssues").map(formatIssueReferenceLabel);
const removed = readIssueReferences(details, "removedBlockedByIssues").map(formatIssueReferenceLabel);
if (added.length > 0 && removed.length === 0) {
const changed = formatChangedEntityLabel("blocker", "blockers", added);
return input.forIssueDetail ? `added ${changed}` : `added ${changed} to`;
}
if (removed.length > 0 && added.length === 0) {
const changed = formatChangedEntityLabel("blocker", "blockers", removed);
return input.forIssueDetail ? `removed ${changed}` : `removed ${changed} from`;
}
return input.forIssueDetail ? "updated blockers" : "updated blockers on";
}
if (input.action === "issue.reviewers_updated" || input.action === "issue.approvers_updated") {
const added = readParticipants(details, "addedParticipants").map((participant) => formatParticipantLabel(participant, input.options));
const removed = readParticipants(details, "removedParticipants").map((participant) => formatParticipantLabel(participant, input.options));
const singular = input.action === "issue.reviewers_updated" ? "reviewer" : "approver";
const plural = input.action === "issue.reviewers_updated" ? "reviewers" : "approvers";
if (added.length > 0 && removed.length === 0) {
const changed = formatChangedEntityLabel(singular, plural, added);
return input.forIssueDetail ? `added ${changed}` : `added ${changed} to`;
}
if (removed.length > 0 && added.length === 0) {
const changed = formatChangedEntityLabel(singular, plural, removed);
return input.forIssueDetail ? `removed ${changed}` : `removed ${changed} from`;
}
return input.forIssueDetail ? `updated ${plural}` : `updated ${plural} on`;
}
return null;
}
export function formatActivityVerb(
action: string,
details?: Record<string, unknown> | null,
options: ActivityFormatOptions = {},
): string {
if (action.startsWith("tool_gateway.")) {
const rawTool = typeof details?.tool === "string"
? details.tool
: typeof details?.upstreamToolName === "string"
? details.upstreamToolName
: "an app action";
const tool = rawTool.replace(/[._-]+/g, " ");
const isTest = details?.source === "test";
if (action === "tool_gateway.call_completed") return `${isTest ? "tested" : "used"} ${tool} on`;
if (action === "tool_gateway.call_allowed") return `${isTest ? "started a test of" : "was allowed to use"} ${tool} on`;
if (action === "tool_gateway.call_denied") return `was blocked from using ${tool} on`;
if (action === "tool_gateway.approval_requested") return `asked to use ${tool} on`;
if (action === "tool_gateway.session_created") return "opened an app session for";
if (action === "tool_gateway.session_rejected") return "was blocked from opening an app session for";
if (action === "tool_gateway.discovery") return "discovered app actions for";
}
if (action === "issue.updated") {
const issueUpdatedVerb = formatIssueUpdatedVerb(details);
if (issueUpdatedVerb) return issueUpdatedVerb;
}
if (action === "issue.stalled_review_decided") {
const decision = typeof details?.action === "string" ? details.action : null;
const label = decision ? STALLED_REVIEW_DECISION_LABELS[decision] : null;
if (label) return `${label} on`;
}
const outcomeLabel = formatInteractionOutcomeLabel(action, details);
if (outcomeLabel) return `${outcomeLabel} on`;
const structuredChange = formatStructuredIssueChange({
action,
details,
options,
forIssueDetail: false,
});
if (structuredChange) return structuredChange;
return ACTIVITY_ROW_VERBS[action] ?? action.replace(/[._]/g, " ");
}
export function formatIssueActivityAction(
action: string,
details?: Record<string, unknown> | null,
options: ActivityFormatOptions = {},
): string {
if (action === "issue.updated") {
const issueUpdatedAction = formatIssueUpdatedAction(details, options);
if (issueUpdatedAction) return issueUpdatedAction;
}
const structuredChange = formatStructuredIssueChange({
action,
details,
options,
forIssueDetail: true,
});
if (structuredChange) return structuredChange;
if (action === "issue.accepted_plan_decomposition_updated") {
const detail = formatAcceptedPlanDecompositionDetail(details);
if (detail) return detail;
}
if (action === "issue.stalled_review_decided") {
const decision = typeof details?.action === "string" ? details.action : null;
const label = decision ? STALLED_REVIEW_DECISION_LABELS[decision] : null;
if (label) return label;
}
const outcomeLabel = formatInteractionOutcomeLabel(action, details);
if (outcomeLabel) return outcomeLabel;
if (action.startsWith("issue.monitor_") && details) {
const serviceName = typeof details.serviceName === "string" && details.serviceName.trim()
? details.serviceName.trim()
: null;
const base = ISSUE_ACTIVITY_LABELS[action] ?? action.replace(/[._]/g, " ");
return serviceName ? `${base} for ${serviceName}` : base;
}
if (
(
action === "issue.document_created" ||
action === "issue.document_updated" ||
action === "issue.document_locked" ||
action === "issue.document_unlocked" ||
action === "issue.document_deleted"
) &&
details
) {
const key = typeof details.key === "string" ? details.key : "document";
const title = typeof details.title === "string" && details.title ? ` (${details.title})` : "";
return `${ISSUE_ACTIVITY_LABELS[action] ?? action} ${key}${title}`;
}
return ISSUE_ACTIVITY_LABELS[action] ?? action.replace(/[._]/g, " ");
}