mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - People talk to their agents in chat, and the agent replies in plain
text
> - In a full chat-eval cohort, 47 of 158 passing replies showed raw
UUIDs, error codes, field keys, tool names or server paths
> - Users must not see internal jargon or raw IDs, so these replies are
a product defect, even when the facts are correct
> - Agents copy these terms from API error messages and saved fields;
the chat directive did not tell them to translate
> - This pull request fixes the sources: the chat directive, and API
denial messages that put IDs and policy codes in the human message
> - The benefit is plain replies for every model, while machine codes
stay available in separate fields
## Linked Issues or Issue Description
**What happened?**
Chat replies quote internal names and raw IDs. Examples: run, handoff,
revision, interaction and trigger UUIDs in prose;
`native_session_retry_exhausted`, `board_access_required`,
`review_policy_denied`, `local-board`, `enableCases`; a raw user ID
inside the inbox denial message.
**Expected behavior**
Replies name records the way the person sees them (task identifier,
title or name, with a link) and explain codes in plain words. IDs stay
only in link targets, in commands the person must run, or when the
person asks for an ID.
**Steps to reproduce**
Run the chat-features OpenCode cohort (for example `cases.close-case`,
`routines.webhook-trigger`, `inbox-search.archive-without-grant`) and
read the agent replies.
**Paperclip version or commit**
`master` at f30005440b.
**Agent adapter(s) involved**
Not adapter-specific (core bug). Seen with the Paperclip runner and
OpenCode.
**Deployment mode**
Local dev server (embedded PGlite) and the CI chat-eval runner.
**Installation method**
Source checkout (`pnpm dev`).
## What Changed
- `AGENT_CHAT_DIRECTIVE`: add one rule. Name records by their
identifier, title or name and link them. Do not write raw IDs, internal
codes, field keys, tool names, process names or server paths, even in
inline code. The rule has exceptions for link targets, commands the
person runs, and IDs the person asks for. The rejection rule now asks
for the platform's reason "in plain words".
- Authorization denials (inbox management, membership, responsible user)
no longer put user or agent IDs in the explanation. The `reason` and
`code` values do not change.
- Review-policy denials explain the rule in plain words. The
`review_policy_denied` code and the `policy` and `allowedActor` fields
do not change.
## Verification
- Red/green: `server/src/__tests__/agent-conversations.test.ts`
(directive rule, and it reaches the chat task prompt),
`server/src/__tests__/authorization-service.test.ts` (inbox denials
carry no IDs), `server/src/__tests__/issue-review-policy.test.ts` and
`server/src/services/issue-thread-interaction-resolution.test.ts` (plain
review messages). Each new assertion failed before the fix.
- `pnpm verify` and the server typecheck pass locally.
- A paid OpenCode run on 8 affected chat cases is in progress; results
will be added here.
## Risks
- Low risk. Only human-readable messages and prompt text change. No
client matches the old message text; codes and machine fields stay the
same.
- The directive grows by one paragraph. A model can still copy an ID;
the rule reduces this but cannot prevent it.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code
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>
250 lines
11 KiB
TypeScript
250 lines
11 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
addressedHumanOnlyDenialMessage,
|
|
evaluateIssueThreadInteractionResolverAudience,
|
|
issueThreadInteractionAttentionAgentAllowed,
|
|
} from "./issue-thread-interaction-resolution.js";
|
|
|
|
const agent = { type: "agent", agentId: "agent-1", runId: "run-1" } as const;
|
|
|
|
function interaction(overrides: Record<string, unknown> = {}) {
|
|
return {
|
|
createdByAgentId: "agent-1",
|
|
createdByUserId: null,
|
|
sourceRunId: "run-1",
|
|
addresseeAgentId: null,
|
|
addresseeUserId: null,
|
|
effectiveResolverPolicy: "anyone",
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
describe("issue-thread interaction resolver audience", () => {
|
|
it("allows the creator and creating run under anyone", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction(),
|
|
})).toMatchObject({ allowed: true, effectiveResolverPolicy: "anyone", reason: "allow_anyone" });
|
|
});
|
|
|
|
it.each([
|
|
["creator agent", { createdByAgentId: "agent-1", sourceRunId: "run-other" }],
|
|
["creating run", { createdByAgentId: "agent-other", sourceRunId: "run-1" }],
|
|
])("excludes the %s only when not_creator is effective", (_name, creator) => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction({ ...creator, effectiveResolverPolicy: "not_creator" }),
|
|
});
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_creator_excluded" });
|
|
});
|
|
|
|
it("enforces an explicit addressee", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction({ addresseeAgentId: "agent-2" }),
|
|
});
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_addressee_mismatch" });
|
|
});
|
|
|
|
it("allows only the addressed user to resolve a user-addressed interaction", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "alice" },
|
|
interaction: interaction({ addresseeUserId: "alice", effectiveResolverPolicy: "human_only" }),
|
|
})).toMatchObject({ allowed: true, reason: "allow_addressee" });
|
|
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "bob" },
|
|
interaction: interaction({ addresseeUserId: "alice", effectiveResolverPolicy: "human_only" }),
|
|
})).toMatchObject({ allowed: false, code: "interaction_addressee_mismatch" });
|
|
});
|
|
|
|
it("requires run attribution for agents", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "agent", agentId: "agent-1", runId: null },
|
|
interaction: interaction(),
|
|
});
|
|
expect(decision).toMatchObject({
|
|
allowed: false,
|
|
status: 422,
|
|
code: "interaction_run_attribution_required",
|
|
});
|
|
});
|
|
|
|
it("allows a server-derived restriction to narrow but never widen the audience", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction({ createdByAgentId: "agent-other", sourceRunId: "run-other" }),
|
|
additionalRestriction: "human_only",
|
|
})).toMatchObject({ allowed: false, code: "interaction_human_only" });
|
|
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction({ effectiveResolverPolicy: "human_only" }),
|
|
additionalRestriction: "anyone",
|
|
})).toMatchObject({ allowed: false, code: "interaction_human_only" });
|
|
});
|
|
|
|
it("intersects human-only and creator-separation restrictions", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "user-1" },
|
|
interaction: interaction({
|
|
createdByAgentId: null,
|
|
createdByUserId: "user-1",
|
|
effectiveResolverPolicy: "not_creator",
|
|
}),
|
|
additionalRestriction: "human_only",
|
|
})).toMatchObject({ allowed: false, code: "interaction_creator_excluded" });
|
|
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "user-1" },
|
|
interaction: interaction({
|
|
createdByAgentId: null,
|
|
createdByUserId: "user-1",
|
|
effectiveResolverPolicy: "human_only",
|
|
}),
|
|
additionalRestriction: "not_creator",
|
|
})).toMatchObject({ allowed: false, code: "interaction_creator_excluded" });
|
|
});
|
|
|
|
it("excludes the review requester when a review card has null creator columns", () => {
|
|
const restriction = {
|
|
policy: "not_creator",
|
|
excludedActor: { type: "user", id: "review-requester" },
|
|
source: "issue_review",
|
|
} as const;
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "review-requester" },
|
|
interaction: interaction({
|
|
createdByAgentId: null,
|
|
createdByUserId: null,
|
|
sourceRunId: null,
|
|
}),
|
|
additionalRestriction: restriction,
|
|
})).toMatchObject({
|
|
allowed: false,
|
|
code: "review_policy_denied",
|
|
message: "Whoever sent this task for review cannot also approve or reject it; someone else must submit the verdict.",
|
|
details: {
|
|
policy: "not_creator",
|
|
allowedActor: "writer_other_than_review_requester",
|
|
},
|
|
});
|
|
expect(evaluateIssueThreadInteractionResolverAudience({
|
|
actor: { type: "user", userId: "peer-reviewer" },
|
|
interaction: interaction({
|
|
createdByAgentId: null,
|
|
createdByUserId: null,
|
|
sourceRunId: null,
|
|
}),
|
|
additionalRestriction: restriction,
|
|
})).toMatchObject({ allowed: true, effectiveResolverPolicy: "not_creator" });
|
|
});
|
|
|
|
it("keeps governed actions independently human-only", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction(),
|
|
governedAction: true,
|
|
});
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_governed_action_denied" });
|
|
});
|
|
|
|
it("preserves legacy inherited board_or_agents creator separation", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({
|
|
actor: agent,
|
|
interaction: interaction({
|
|
effectiveResolverPolicy: "board_or_agents",
|
|
resolverPolicyProvenance: "legacy_inherited_restriction",
|
|
}),
|
|
});
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_creator_excluded" });
|
|
});
|
|
|
|
it("derives agent attention ownership from the same effective audience", () => {
|
|
expect(issueThreadInteractionAttentionAgentAllowed({
|
|
agentId: "agent-1",
|
|
interaction: interaction(),
|
|
})).toBe(true);
|
|
expect(issueThreadInteractionAttentionAgentAllowed({
|
|
agentId: "agent-1",
|
|
interaction: interaction({ effectiveResolverPolicy: "not_creator" }),
|
|
})).toBe(false);
|
|
expect(issueThreadInteractionAttentionAgentAllowed({
|
|
agentId: "agent-2",
|
|
interaction: interaction({ effectiveResolverPolicy: "human_only" }),
|
|
})).toBe(false);
|
|
});
|
|
|
|
describe("human-only card addressed to someone else", () => {
|
|
const card = interaction({ createdByAgentId: null, createdByUserId: "alex", addresseeUserId: "riley", effectiveResolverPolicy: "human_only" });
|
|
|
|
it("tells the agent only the addressee resolves it and not to send the asker to the card", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({ actor: { ...agent, relayedHumanUserId: "alex" }, interaction: card });
|
|
expect(decision).toMatchObject({ allowed: false, status: 403, code: "interaction_human_only", details: { addresseeUserId: "riley", askerIsNotAddressee: true } });
|
|
const message = decision.allowed ? "" : decision.message;
|
|
expect(message).toContain("This issue-thread interaction is human-only and addressed to");
|
|
expect(message).toContain("Only the addressee can accept or decline it");
|
|
expect(message).toContain("do not ask the person asking to accept or decline it");
|
|
});
|
|
|
|
it("names the addressee once the route knows their display name", () => {
|
|
const message = addressedHumanOnlyDenialMessage("Riley", true);
|
|
expect(message).toContain("addressed to Riley.");
|
|
expect(message).toContain("Only Riley can accept or decline it");
|
|
expect(message).toContain("the card waits on Riley");
|
|
expect(message).not.toContain("addresseeUserId");
|
|
});
|
|
|
|
it.each([
|
|
["no verified replying user", agent],
|
|
["the addressee as the replying user", { ...agent, relayedHumanUserId: "riley" }],
|
|
])("keeps the advice neutral with %s", (_name, actor) => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({ actor, interaction: card });
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_human_only", details: { addresseeUserId: "riley", askerIsNotAddressee: false } });
|
|
const message = decision.allowed ? "" : decision.message;
|
|
expect(message).toContain("Only the addressee can accept or decline it");
|
|
expect(message).not.toContain("do not ask the person asking");
|
|
});
|
|
|
|
it("keeps the plain human-only denial when the card has no addressee", () => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({ actor: agent,
|
|
interaction: interaction({ effectiveResolverPolicy: "human_only" }) });
|
|
expect(decision).toMatchObject({ allowed: false, code: "interaction_human_only", message: "This issue-thread interaction is human-only" });
|
|
});
|
|
});
|
|
|
|
describe("relayed human decision", () => {
|
|
const relay = { ...agent, relayedHumanUserId: "user-1" };
|
|
const humanOnly = (overrides: Record<string, unknown> = {}) =>
|
|
interaction({ effectiveResolverPolicy: "human_only", effectiveResolverPolicySource: "requested",
|
|
resolverPolicyProvenance: "explicit", ...overrides });
|
|
|
|
it("allows a verified reply on a card whose creator requested human_only", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({ actor: relay, interaction: humanOnly() }))
|
|
.toMatchObject({ allowed: true, effectiveResolverPolicy: "human_only", reason: "allow_relayed_human" });
|
|
});
|
|
|
|
it.each([
|
|
["no relay", { actor: agent }],
|
|
["a company cap", { interaction: humanOnly({ effectiveResolverPolicySource: "company_cap" }) }],
|
|
["a governed-action source", { interaction: humanOnly({ effectiveResolverPolicySource: "governed_action" }) }],
|
|
["an unknown legacy source", { interaction: humanOnly({ effectiveResolverPolicySource: null }) }],
|
|
["a governed action", { governedAction: true }],
|
|
["an issue-review restriction", { additionalRestriction: "human_only" as const }],
|
|
["another addressed user", { interaction: humanOnly({ addresseeUserId: "user-2" }) }],
|
|
["a human-created card", { interaction: humanOnly({ createdByAgentId: null, createdByUserId: "user-1" }) }],
|
|
["another agent's card", { interaction: humanOnly({ createdByAgentId: "agent-2" }) }],
|
|
["an inherited company default", { interaction: humanOnly({ resolverPolicyProvenance: "inherited" }) }],
|
|
])("still denies %s", (_name, override) => {
|
|
const decision = evaluateIssueThreadInteractionResolverAudience({ actor: relay, interaction: humanOnly(), ...override });
|
|
expect(decision).toMatchObject({ allowed: false });
|
|
});
|
|
|
|
it("never widens a non-human-only card", () => {
|
|
expect(evaluateIssueThreadInteractionResolverAudience({ actor: relay,
|
|
interaction: interaction({ effectiveResolverPolicy: "not_creator" }) }))
|
|
.toMatchObject({ allowed: false, code: "interaction_creator_excluded" });
|
|
});
|
|
});
|
|
});
|