mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
## 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>
572 lines
25 KiB
TypeScript
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, " ");
|
|
}
|