## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Operators need visibility into who initiated work, which agents ran,
and how tasks were delegated across a company.
> - The existing control plane stores the raw data across issues,
heartbeat runs, comments, approvals, interactions, and activity logs.
> - There was no single company-scoped API response that reconstructed
those records into timeline actors, spans, events, and edges for a
Gantt-style view.
> - This pull request adds that aggregation endpoint behind the same
company and issue read authorization model used elsewhere.
> - The benefit is that UI work can consume one bounded endpoint instead
of reimplementing timeline joins client-side.
## Linked Issues or Issue Description
No public GitHub issue exists for this feature.
## Problem or motivation
Paperclip stores enough execution and delegation data to show work over
time, but consumers need a single endpoint that aggregates it
consistently.
## Proposed solution
Add `GET /api/companies/:companyId/timeline` with date and entity
filters, bounded windows, pagination, actor normalization, run spans,
human events, and delegation/assignment edges.
## Alternatives considered
Querying each source separately from the UI would duplicate ACL and
attribution logic and make client rendering depend on storage details.
## Roadmap alignment
This supports operator visibility and auditability, and does not
duplicate a listed roadmap item.
## What Changed
- Added a `workTimelineService` that aggregates issue candidates from
runs, activity, comments, approvals, interactions, and recently touched
issues.
- Added `GET /api/companies/:companyId/timeline` with `from`, `to`,
`userId`, `goalId`, `projectId`, `issueId`, `limit`, and `offset` query
parameters.
- Enforced company-scope access plus per-issue `issue:read` filtering
before emitting spans, events, or edges.
- Added 31-day window capping, in-progress span handling for null
`finishedAt`, retry/continuation metadata, user-lens subtree filtering,
and activity-log run attribution fallback.
- Added embedded-Postgres tests for aggregation joins, route behavior,
ACL filtering, window capping, and user-lens closure.
## Verification
- `pnpm vitest run server/src/__tests__/work-timeline-service.test.ts`
- `pnpm exec tsc -p server/tsconfig.json --noEmit`
Additional smoke attempted:
- `pnpm dev:once` did not start the local app because the existing
embedded instance has pending migration drift: Postgres rejected a
foreign key on `pipeline_case_blockers.company_id` because that column
does not exist. I did not manually alter the embedded database.
## Risks
- Medium risk: this introduces a new aggregate endpoint over several
tables, so query volume should be watched on very large companies.
- The endpoint caps windows and paginates issue candidates to keep the
first version bounded.
- ACL behavior is fail-closed per issue: unreadable issues are filtered
before response rows are emitted.
- No migrations or schema changes are included.
## Model Used
OpenAI GPT-5 via Codex coding agent, with tool use for repository
inspection, editing, local Vitest execution, TypeScript checking, git,
and GitHub CLI operations.
## 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
- [ ] 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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
dea7c4e274