Files
PaperClipAI/server
DottaandClaude Opus 5.5 eb65fc0941 fix(server): turn agents' made-up-host Paperclip links into relative routes (#21762)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents post chat replies and task comments that link board pages and
attachments
> - Some models invent a hostname for these links, such as
`https://paperclip.local/COM/agents/<id>` or
`https://paperclip/api/attachments/<id>/content`
> - Those hosts do not exist, so the person clicks a broken link
> - The chat guidance already says never to invent a hostname, but a
model can still do it
> - This pull request rewrites such links to relative app routes before
an agent comment is saved, and adds the rule to the Paperclip skill
> - The benefit is that every board and attachment link an agent writes
opens, on whatever origin the reader uses

## Linked Issues or Issue Description

**What happened?**
Chat-eval cohort 16 (OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master 819f61f1fd). In
`agents.edit-instructions`, the reply linked Morgan as
`[Morgan](https://paperclip.local/COM/agents/<id>)`. In
`onboarding.first-work`, the worker's summary linked its attachments as
`https://paperclip/api/attachments/<id>/content`. Neither host exists.

**Expected behavior**
An agent's link to a Paperclip board or API route opens. Genuine
external links, the instance's own origin, and links inside code stay as
written.

**Steps to reproduce**
Post an agent comment that contains
`[Morgan](https://paperclip.local/<PREFIX>/agents/<id>)`. Before this
change it is stored as written. After it, the stored body links
`/<PREFIX>/agents/<id>`.

## What Changed

- New `server/src/services/agent-invented-host-links.ts`. It rewrites an
absolute link to a relative route only when all of these are true:
- The host is made up: `paperclip`, or `paperclip.<reserved TLD>`
(`local`, `localhost`, `internal`, `test`, `example`, `invalid`, `lan`),
or a loopback host.
- The path is a known board route (`/<PREFIX>/<board root>…`) or, on a
made-up Paperclip host only, `/api/…`.
- A loopback host (`localhost`, `127.x`, `[::1]`) qualifies only for a
board route under the comment's own company prefix. A local app that the
agent built keeps its link, including its `/api` paths.
  - The origin is not this instance's configured public origin.
  - The link is outside fenced and inline code.
- Markdown link targets keep their place. Bare links and autolinks
become Markdown links, so they stay clickable.
- `issueService.addComment` applies it to agent-authored comments,
before the redaction and dedupe steps, so a retried identical comment
still deduplicates. The run-presentation check still compares the text
that the agent wrote. People's comments are not changed.
- `skills/paperclip/SKILL.md` now tells agents to write board and
attachment links as relative paths and never add a hostname.

## Verification

- `pnpm vitest run
server/src/services/agent-invented-host-links.test.ts` (19 tests):
recorded cohort 16 links are rewritten. Negative controls stay
unchanged: external links, a production Paperclip host, the instance's
own origin, local app links, another prefix on localhost, a non-route
path, another single-label host, inline code, a fence, and relative
links.
- `server/src/__tests__/issues-service.test.ts` new case: an agent
comment is stored with the relative route, and a person's identical
comment is stored as written. It fails on master and passes with this
change.
- Per-message cost (local tsx micro-benchmark): the gate on a comment
with no candidate host takes 0.3 µs (500 chars), 1.2 µs (2 KB) and 4.7
µs (8 KB). Only when a candidate exists does it read the company prefix
(one indexed select) and the public origin (config read once per
process), and rewrite (4–40 µs). Nothing runs before a turn starts.
- `server` typecheck passes.

## Risks

- A link on a made-up host to a board route of another company prefix
becomes relative. It opens that route on the reader's instance, where
access checks still apply.
- External channels that cannot resolve relative links already get
relative links from agents today. This change does not alter their
delivery.

## Model Used

- Claude, `claude-opus-5-5` (Claude Code agent 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
- [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-15 08:44:06 -06:00
..