mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-01 06:42:06 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Issue interactions give agents and people a structured decision record. > - Resolver routes used different authorization rules. > - Some routes blocked valid agents, including task watchdogs with normal issue access. > - The API did not show who could resolve a pending interaction. > - This pull request gives every interaction kind one resolver policy evaluator. > - The benefit is a clear decision path with consistent governance and company isolation. ## Linked Issues or Issue Description Fixes: #8087 Refs: #7403 Related PR: #11082 proposes board-only confirmation rules. This change keeps human-only review as an explicit policy. **What happened?** Agents could create issue interactions. Some resolver routes still required board access. This left valid agent confirmations pending. Task watchdogs could see the same problem without board identity. **Expected behavior** Every interaction kind must use one resolver policy contract. The contract must support `anyone`, `not_creator`, and `human_only`. It must also apply all normal governance controls. **Steps to reproduce** 1. Create a `request_confirmation` interaction as an agent. 2. Resolve it with another authorized agent. 3. Observe the board-only denial. **Paperclip version or commit** The problem exists on `master` before this change. **Deployment mode** Local development with `pnpm dev`. ## What Changed - Add canonical policies for `anyone`, `not_creator`, and `human_only`. - Use one server evaluator for every interaction kind. - Apply named addressees, company limits, review rules, and task watchdog scope. - Charge cross-issue resolutions to the existing per-run action limit. - Return the effective resolver audience in attention and interaction data. - Show the audience, governance choices, and denial reasons in the board UI. - Add telemetry, API documents, product documents, and regression fixtures. - Add migration provenance for safe legacy behavior. - Make migration `0218` safe for complete replays and partial prior runs. ## Product Rules - An interaction records a response. It does not grant authority for the next action. - `anyone` lets any authorized issue participant respond. - `not_creator` requires a responder other than the interaction creator. - `human_only` requires an authorized person. - A named addressee, company policy, or governed action can narrow the audience. - These controls cannot widen the audience. - A task watchdog uses the same rules as an ordinary agent. - A task watchdog does not receive board authority. - An agent resolution on another issue uses the shared cross-issue action limit. - Legacy pending interactions keep their earlier restrictions. - The UI shows the effective audience and a permanent denial reason. ## Verification - `pnpm --filter @paperclipai/db check:migrations` - `pnpm --filter @paperclipai/db typecheck` - `pnpm exec vitest run packages/db/src/issue-thread-interaction-resolver-policy-migration.test.ts` - The focused PostgreSQL test applies migration `0218` twice. - The test also completes a partial prior run and preserves existing provenance. - The latest GitHub head has 29 successful checks. - The opt-in Storybook visual check skipped as expected. - Greptile reports 5/5 with no open comments. ## Risks - New interaction writes use `anyone` by default. - Callers must select `not_creator` or `human_only` when they need stricter review. - Legacy pending interactions keep the old creator and human restrictions. - Migration `0218` fills only missing provenance fields during recovery. - Cross-issue resolutions can reach the existing action limit. - The shared evaluator affects every interaction kind. - Route, service, database, shared contract, and UI tests cover these rules. > This work matches the Agent Reviews and Approvals direction in `ROADMAP.md`. It does not duplicate a planned item. ## Model Used OpenAI Codex, GPT-5. The runtime does not expose the exact deployment ID or context window. The agent used reasoning, repository tools, shell commands, and test 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 linked public issues or described the issue with the required labels - [x] I have not referenced internal Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation - [x] I have considered and documented the risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open comments - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
77 lines
3.8 KiB
TypeScript
77 lines
3.8 KiB
TypeScript
import type {
|
|
IssueThreadInteractionCanonicalResolverPolicy,
|
|
IssueThreadInteractionEffectiveResolverPolicySource,
|
|
IssueThreadInteractionPayload,
|
|
IssueThreadInteractionResolverPolicyProvenance,
|
|
IssueThreadInteractionResult,
|
|
} from "@paperclipai/shared";
|
|
import { sql } from "drizzle-orm";
|
|
import { pgTable, uuid, text, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
|
|
import { agents } from "./agents.js";
|
|
import { companies } from "./companies.js";
|
|
import { heartbeatRuns } from "./heartbeat_runs.js";
|
|
import { issueComments } from "./issue_comments.js";
|
|
import { issues } from "./issues.js";
|
|
|
|
export const issueThreadInteractions = pgTable(
|
|
"issue_thread_interactions",
|
|
{
|
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
companyId: uuid("company_id").notNull().references(() => companies.id),
|
|
issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
|
|
kind: text("kind").notNull(),
|
|
status: text("status").notNull().default("pending"),
|
|
continuationPolicy: text("continuation_policy").notNull().default("wake_assignee"),
|
|
requestedResolverPolicy: text("requested_resolver_policy")
|
|
.$type<IssueThreadInteractionCanonicalResolverPolicy>()
|
|
.notNull()
|
|
.default("anyone"),
|
|
effectiveResolverPolicy: text("effective_resolver_policy")
|
|
.$type<IssueThreadInteractionCanonicalResolverPolicy>()
|
|
.notNull()
|
|
.default("anyone"),
|
|
resolverPolicyProvenance: text("resolver_policy_provenance")
|
|
.$type<IssueThreadInteractionResolverPolicyProvenance>()
|
|
.notNull()
|
|
.default("inherited"),
|
|
effectiveResolverPolicySource: text("effective_resolver_policy_source")
|
|
.$type<IssueThreadInteractionEffectiveResolverPolicySource>()
|
|
.notNull()
|
|
.default("requested"),
|
|
idempotencyKey: text("idempotency_key"),
|
|
sourceCommentId: uuid("source_comment_id").references(() => issueComments.id, { onDelete: "set null" }),
|
|
sourceRunId: uuid("source_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
|
|
title: text("title"),
|
|
summary: text("summary"),
|
|
createdByAgentId: uuid("created_by_agent_id").references(() => agents.id),
|
|
addresseeAgentId: uuid("addressee_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
|
createdByUserId: text("created_by_user_id"),
|
|
resolvedByAgentId: uuid("resolved_by_agent_id").references(() => agents.id),
|
|
resolvedByRunId: uuid("resolved_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
|
|
resolvedByUserId: text("resolved_by_user_id"),
|
|
payload: jsonb("payload").$type<IssueThreadInteractionPayload>().notNull(),
|
|
result: jsonb("result").$type<IssueThreadInteractionResult>(),
|
|
resolvedAt: timestamp("resolved_at", { withTimezone: true }),
|
|
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
|
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
|
|
},
|
|
(table) => ({
|
|
issueIdx: index("issue_thread_interactions_issue_idx").on(table.issueId),
|
|
companyIssueCreatedAtIdx: index("issue_thread_interactions_company_issue_created_at_idx").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.createdAt,
|
|
),
|
|
companyIssueStatusIdx: index("issue_thread_interactions_company_issue_status_idx").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.status,
|
|
),
|
|
companyIssueIdempotencyUq: uniqueIndex("issue_thread_interactions_company_issue_idempotency_uq")
|
|
.on(table.companyId, table.issueId, table.idempotencyKey)
|
|
.where(sql`${table.idempotencyKey} IS NOT NULL`),
|
|
sourceCommentIdx: index("issue_thread_interactions_source_comment_idx").on(table.sourceCommentId),
|
|
addresseeAgentIdx: index("issue_thread_interactions_addressee_agent_idx").on(table.addresseeAgentId),
|
|
}),
|
|
);
|