mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-17 19:20:39 +09:00
[codex] Add structured issue-thread interactions (#4244)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Operators supervise that work through issues, comments, approvals, and the board UI. > - Some agent proposals need structured board/user decisions, not hidden markdown conventions or heavyweight governed approvals. > - Issue-thread interactions already provide a natural thread-native surface for proposed tasks and questions. > - This pull request extends that surface with request confirmations, richer interaction cards, and agent/plugin/MCP helpers. > - The benefit is that plan approvals and yes/no decisions become explicit, auditable, and resumable without losing the single-issue workflow. ## What Changed - Added persisted issue-thread interactions for suggested tasks, structured questions, and request confirmations. - Added board UI cards for interaction review, selection, question answers, and accept/reject confirmation flows. - Added MCP and plugin SDK helpers for creating interaction cards from agents/plugins. - Updated agent wake instructions, onboarding assets, Paperclip skill docs, and public docs to prefer structured confirmations for issue-scoped decisions. - Rebased the branch onto `public-gh/master` and renumbered branch migrations to `0063` and `0064`; the idempotency migration uses `ADD COLUMN IF NOT EXISTS` for old branch users. ## Verification - `git diff --check public-gh/master..HEAD` - `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts packages/mcp-server/src/tools.test.ts packages/shared/src/issue-thread-interactions.test.ts ui/src/lib/issue-thread-interactions.test.ts ui/src/lib/issue-chat-messages.test.ts ui/src/components/IssueThreadInteractionCard.test.tsx ui/src/components/IssueChatThread.test.tsx server/src/__tests__/issue-thread-interaction-routes.test.ts server/src/__tests__/issue-thread-interactions-service.test.ts server/src/services/issue-thread-interactions.test.ts` -> 9 files / 79 tests passed - `pnpm -r typecheck` -> passed, including `packages/db` migration numbering check ## Risks - Medium: this adds a new issue-thread interaction model across db/shared/server/ui/plugin surfaces. - Migration risk is reduced by placing this branch after current master migrations (`0063`, `0064`) and making the idempotency column add idempotent for users who applied the old branch numbering. - UI interaction behavior is covered by component tests, but this PR does not include browser screenshots. > 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 - OpenAI Codex, GPT-5-class coding agent runtime. Exact model ID and context window are not exposed in this Paperclip run; tool use and local shell/code execution were enabled. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
014aa0eb2d
commit
a957394420
93 changed files with 10089 additions and 752 deletions
|
|
@ -7,6 +7,7 @@ import {
|
|||
type IssueChatComment,
|
||||
type IssueChatLinkedRun,
|
||||
} from "./issue-chat-messages";
|
||||
import type { SuggestTasksInteraction } from "./issue-thread-interactions";
|
||||
import type { IssueTimelineEvent } from "./issue-timeline-events";
|
||||
import type { LiveRunForIssue } from "../api/heartbeats";
|
||||
|
||||
|
|
@ -51,6 +52,39 @@ function createComment(overrides: Partial<IssueChatComment> = {}): IssueChatComm
|
|||
};
|
||||
}
|
||||
|
||||
function createInteraction(
|
||||
overrides: Partial<SuggestTasksInteraction> = {},
|
||||
): SuggestTasksInteraction {
|
||||
return {
|
||||
id: "interaction-1",
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
kind: "suggest_tasks",
|
||||
title: "Suggested follow-up work",
|
||||
summary: "Preview the next issue tree before accepting it.",
|
||||
status: "pending",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdByAgentId: "agent-1",
|
||||
createdByUserId: null,
|
||||
resolvedByAgentId: null,
|
||||
resolvedByUserId: null,
|
||||
createdAt: new Date("2026-04-06T12:02:00.000Z"),
|
||||
updatedAt: new Date("2026-04-06T12:02:00.000Z"),
|
||||
resolvedAt: null,
|
||||
payload: {
|
||||
version: 1,
|
||||
tasks: [
|
||||
{
|
||||
clientKey: "task-1",
|
||||
title: "Prototype the card",
|
||||
},
|
||||
],
|
||||
},
|
||||
result: null,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("buildAssistantPartsFromTranscript", () => {
|
||||
it("maps assistant text, reasoning, and tool activity while omitting noisy stderr", () => {
|
||||
const result = buildAssistantPartsFromTranscript([
|
||||
|
|
@ -343,6 +377,63 @@ describe("buildIssueChatMessages", () => {
|
|||
});
|
||||
});
|
||||
|
||||
it("merges thread interactions into the same chronological feed as comments and runs", () => {
|
||||
const messages = buildIssueChatMessages({
|
||||
comments: [
|
||||
createComment({
|
||||
id: "comment-1",
|
||||
createdAt: new Date("2026-04-06T12:01:00.000Z"),
|
||||
updatedAt: new Date("2026-04-06T12:01:00.000Z"),
|
||||
}),
|
||||
],
|
||||
interactions: [
|
||||
createInteraction({
|
||||
id: "interaction-2",
|
||||
createdAt: new Date("2026-04-06T12:02:00.000Z"),
|
||||
updatedAt: new Date("2026-04-06T12:02:00.000Z"),
|
||||
}),
|
||||
],
|
||||
timelineEvents: [],
|
||||
linkedRuns: [],
|
||||
liveRuns: [
|
||||
{
|
||||
id: "run-live-1",
|
||||
status: "running",
|
||||
invocationSource: "manual",
|
||||
triggerDetail: null,
|
||||
startedAt: "2026-04-06T12:03:00.000Z",
|
||||
finishedAt: null,
|
||||
createdAt: "2026-04-06T12:03:00.000Z",
|
||||
agentId: "agent-1",
|
||||
agentName: "CodexCoder",
|
||||
adapterType: "codex_local",
|
||||
},
|
||||
],
|
||||
transcriptsByRunId: new Map([
|
||||
[
|
||||
"run-live-1",
|
||||
[{ kind: "assistant", ts: "2026-04-06T12:03:01.000Z", text: "Working on it." }],
|
||||
],
|
||||
]),
|
||||
hasOutputForRun: (runId) => runId === "run-live-1",
|
||||
currentUserId: "user-1",
|
||||
});
|
||||
|
||||
expect(messages.map((message) => `${message.role}:${message.id}`)).toEqual([
|
||||
"user:comment-1",
|
||||
"system:interaction:interaction-2",
|
||||
"assistant:run-assistant:run-live-1",
|
||||
]);
|
||||
expect(messages[1]).toMatchObject({
|
||||
metadata: {
|
||||
custom: {
|
||||
kind: "interaction",
|
||||
anchorId: "interaction-interaction-2",
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps succeeded runs as assistant messages when transcript output exists", () => {
|
||||
const agentMap = new Map<string, Agent>([["agent-1", createAgent("agent-1", "CodexCoder")]]);
|
||||
const messages = buildIssueChatMessages({
|
||||
|
|
|
|||
|
|
@ -10,6 +10,10 @@ import type {
|
|||
import type { Agent, IssueComment } from "@paperclipai/shared";
|
||||
import type { ActiveRunForIssue, LiveRunForIssue } from "../api/heartbeats";
|
||||
import { formatAssigneeUserLabel } from "./assignees";
|
||||
import {
|
||||
buildIssueThreadInteractionSummary,
|
||||
type IssueThreadInteraction,
|
||||
} from "./issue-thread-interactions";
|
||||
import type { IssueTimelineEvent } from "./issue-timeline-events";
|
||||
import {
|
||||
summarizeNotice,
|
||||
|
|
@ -387,6 +391,23 @@ function createTimelineEventMessage(args: {
|
|||
return message;
|
||||
}
|
||||
|
||||
function createInteractionMessage(interaction: IssueThreadInteraction) {
|
||||
const message: ThreadSystemMessage = {
|
||||
id: `interaction:${interaction.id}`,
|
||||
role: "system",
|
||||
createdAt: toDate(interaction.createdAt),
|
||||
content: [{ type: "text", text: buildIssueThreadInteractionSummary(interaction) }],
|
||||
metadata: {
|
||||
custom: {
|
||||
kind: "interaction",
|
||||
anchorId: `interaction-${interaction.id}`,
|
||||
interaction,
|
||||
},
|
||||
},
|
||||
};
|
||||
return message;
|
||||
}
|
||||
|
||||
function runTimestamp(run: IssueChatLinkedRun) {
|
||||
return run.finishedAt ?? run.startedAt ?? run.createdAt;
|
||||
}
|
||||
|
|
@ -738,6 +759,7 @@ function createLiveRunMessage(args: {
|
|||
|
||||
export function buildIssueChatMessages(args: {
|
||||
comments: readonly IssueChatComment[];
|
||||
interactions?: readonly IssueThreadInteraction[];
|
||||
timelineEvents: readonly IssueTimelineEvent[];
|
||||
linkedRuns: readonly IssueChatLinkedRun[];
|
||||
liveRuns: readonly LiveRunForIssue[];
|
||||
|
|
@ -754,6 +776,7 @@ export function buildIssueChatMessages(args: {
|
|||
}) {
|
||||
const {
|
||||
comments,
|
||||
interactions = [],
|
||||
timelineEvents,
|
||||
linkedRuns,
|
||||
liveRuns,
|
||||
|
|
@ -779,6 +802,14 @@ export function buildIssueChatMessages(args: {
|
|||
});
|
||||
}
|
||||
|
||||
for (const interaction of sortByCreated(interactions)) {
|
||||
orderedMessages.push({
|
||||
createdAtMs: toTimestamp(interaction.createdAt),
|
||||
order: 2,
|
||||
message: createInteractionMessage(interaction),
|
||||
});
|
||||
}
|
||||
|
||||
for (const event of sortByCreated(timelineEvents)) {
|
||||
orderedMessages.push({
|
||||
createdAtMs: toTimestamp(event.createdAt),
|
||||
|
|
|
|||
150
ui/src/lib/issue-thread-interactions.test.ts
Normal file
150
ui/src/lib/issue-thread-interactions.test.ts
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
buildIssueThreadInteractionSummary,
|
||||
buildSuggestedTaskTree,
|
||||
collectSuggestedTaskClientKeys,
|
||||
countSuggestedTaskNodes,
|
||||
getQuestionAnswerLabels,
|
||||
} from "./issue-thread-interactions";
|
||||
|
||||
describe("buildSuggestedTaskTree", () => {
|
||||
it("preserves parent-child relationships from client keys", () => {
|
||||
const roots = buildSuggestedTaskTree([
|
||||
{
|
||||
clientKey: "root",
|
||||
title: "Root",
|
||||
},
|
||||
{
|
||||
clientKey: "child",
|
||||
parentClientKey: "root",
|
||||
title: "Child",
|
||||
},
|
||||
{
|
||||
clientKey: "grandchild",
|
||||
parentClientKey: "child",
|
||||
title: "Grandchild",
|
||||
},
|
||||
]);
|
||||
|
||||
expect(roots).toHaveLength(1);
|
||||
expect(roots[0]?.task.clientKey).toBe("root");
|
||||
expect(roots[0]?.children[0]?.task.clientKey).toBe("child");
|
||||
expect(countSuggestedTaskNodes(roots[0]!)).toBe(3);
|
||||
expect(collectSuggestedTaskClientKeys(roots[0]!)).toEqual(["root", "child", "grandchild"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("issue thread interaction helpers", () => {
|
||||
it("summarizes task and question interactions", () => {
|
||||
expect(buildIssueThreadInteractionSummary({
|
||||
id: "interaction-1",
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
kind: "suggest_tasks",
|
||||
status: "pending",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdAt: "2026-04-06T12:00:00.000Z",
|
||||
updatedAt: "2026-04-06T12:00:00.000Z",
|
||||
payload: {
|
||||
version: 1,
|
||||
tasks: [
|
||||
{ clientKey: "task-1", title: "One" },
|
||||
{ clientKey: "task-2", title: "Two" },
|
||||
],
|
||||
},
|
||||
})).toBe("Suggested 2 tasks");
|
||||
|
||||
expect(buildIssueThreadInteractionSummary({
|
||||
id: "interaction-accepted",
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
kind: "suggest_tasks",
|
||||
status: "accepted",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdAt: "2026-04-06T12:00:00.000Z",
|
||||
updatedAt: "2026-04-06T12:00:00.000Z",
|
||||
payload: {
|
||||
version: 1,
|
||||
tasks: [
|
||||
{ clientKey: "task-1", title: "One" },
|
||||
{ clientKey: "task-2", title: "Two" },
|
||||
],
|
||||
},
|
||||
result: {
|
||||
version: 1,
|
||||
createdTasks: [{ clientKey: "task-1", issueId: "child-1" }],
|
||||
skippedClientKeys: ["task-2"],
|
||||
},
|
||||
})).toBe("Accepted 1 of 2 tasks");
|
||||
|
||||
expect(buildIssueThreadInteractionSummary({
|
||||
id: "interaction-2",
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
kind: "ask_user_questions",
|
||||
status: "pending",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdAt: "2026-04-06T12:00:00.000Z",
|
||||
updatedAt: "2026-04-06T12:00:00.000Z",
|
||||
payload: {
|
||||
version: 1,
|
||||
questions: [
|
||||
{
|
||||
id: "question-1",
|
||||
prompt: "Pick one",
|
||||
selectionMode: "single",
|
||||
options: [{ id: "option-1", label: "Option 1" }],
|
||||
},
|
||||
],
|
||||
},
|
||||
})).toBe("Asked 1 question");
|
||||
|
||||
expect(buildIssueThreadInteractionSummary({
|
||||
id: "interaction-answered",
|
||||
companyId: "company-1",
|
||||
issueId: "issue-1",
|
||||
kind: "ask_user_questions",
|
||||
status: "answered",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdAt: "2026-04-06T12:00:00.000Z",
|
||||
updatedAt: "2026-04-06T12:00:00.000Z",
|
||||
payload: {
|
||||
version: 1,
|
||||
questions: [
|
||||
{
|
||||
id: "question-1",
|
||||
prompt: "Pick one",
|
||||
selectionMode: "single",
|
||||
options: [{ id: "option-1", label: "Option 1" }],
|
||||
},
|
||||
],
|
||||
},
|
||||
result: {
|
||||
version: 1,
|
||||
answers: [{ questionId: "question-1", optionIds: ["option-1"] }],
|
||||
},
|
||||
})).toBe("Answered 1 question");
|
||||
});
|
||||
|
||||
it("maps stored option ids back to labels for answered summaries", () => {
|
||||
const labels = getQuestionAnswerLabels({
|
||||
question: {
|
||||
id: "question-1",
|
||||
prompt: "Pick options",
|
||||
selectionMode: "multi",
|
||||
options: [
|
||||
{ id: "option-1", label: "Option 1" },
|
||||
{ id: "option-2", label: "Option 2" },
|
||||
],
|
||||
},
|
||||
answers: [
|
||||
{
|
||||
questionId: "question-1",
|
||||
optionIds: ["option-2", "option-1"],
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
expect(labels).toEqual(["Option 2", "Option 1"]);
|
||||
});
|
||||
});
|
||||
140
ui/src/lib/issue-thread-interactions.ts
Normal file
140
ui/src/lib/issue-thread-interactions.ts
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
export type {
|
||||
AskUserQuestionsAnswer,
|
||||
AskUserQuestionsInteraction,
|
||||
AskUserQuestionsPayload,
|
||||
AskUserQuestionsQuestion,
|
||||
AskUserQuestionsQuestionOption,
|
||||
AskUserQuestionsResult,
|
||||
IssueThreadInteraction,
|
||||
IssueThreadInteractionActorFields,
|
||||
IssueThreadInteractionBase,
|
||||
IssueThreadInteractionContinuationPolicy,
|
||||
IssueThreadInteractionStatus,
|
||||
RequestConfirmationInteraction,
|
||||
RequestConfirmationIssueDocumentTarget,
|
||||
RequestConfirmationPayload,
|
||||
RequestConfirmationResult,
|
||||
RequestConfirmationTarget,
|
||||
SuggestedTaskDraft,
|
||||
SuggestTasksInteraction,
|
||||
SuggestTasksPayload,
|
||||
SuggestTasksResult,
|
||||
SuggestTasksResultCreatedTask,
|
||||
} from "@paperclipai/shared";
|
||||
import type {
|
||||
AskUserQuestionsAnswer,
|
||||
AskUserQuestionsInteraction,
|
||||
AskUserQuestionsQuestion,
|
||||
IssueThreadInteraction,
|
||||
RequestConfirmationInteraction,
|
||||
SuggestedTaskDraft,
|
||||
SuggestTasksInteraction,
|
||||
SuggestTasksResultCreatedTask,
|
||||
} from "@paperclipai/shared";
|
||||
|
||||
export interface SuggestedTaskTreeNode {
|
||||
task: SuggestedTaskDraft;
|
||||
children: SuggestedTaskTreeNode[];
|
||||
}
|
||||
|
||||
export function isIssueThreadInteraction(
|
||||
value: unknown,
|
||||
): value is IssueThreadInteraction {
|
||||
if (!value || typeof value !== "object") return false;
|
||||
const candidate = value as Partial<IssueThreadInteraction>;
|
||||
return typeof candidate.id === "string"
|
||||
&& typeof candidate.companyId === "string"
|
||||
&& typeof candidate.issueId === "string"
|
||||
&& (
|
||||
candidate.kind === "suggest_tasks"
|
||||
|| candidate.kind === "ask_user_questions"
|
||||
|| candidate.kind === "request_confirmation"
|
||||
);
|
||||
}
|
||||
|
||||
export function buildIssueThreadInteractionSummary(
|
||||
interaction: IssueThreadInteraction,
|
||||
) {
|
||||
if (interaction.kind === "suggest_tasks") {
|
||||
const count = interaction.payload.tasks.length;
|
||||
if (interaction.status === "accepted") {
|
||||
const createdCount = interaction.result?.createdTasks?.length ?? 0;
|
||||
const skippedCount = interaction.result?.skippedClientKeys?.length ?? 0;
|
||||
if (skippedCount > 0) {
|
||||
return `Accepted ${createdCount} of ${count} tasks`;
|
||||
}
|
||||
return createdCount === 1 ? "Accepted 1 task" : `Accepted ${createdCount} tasks`;
|
||||
}
|
||||
if (interaction.status === "rejected") {
|
||||
return count === 1 ? "Rejected 1 task" : `Rejected ${count} tasks`;
|
||||
}
|
||||
return count === 1 ? "Suggested 1 task" : `Suggested ${count} tasks`;
|
||||
}
|
||||
|
||||
if (interaction.kind === "request_confirmation") {
|
||||
if (interaction.status === "accepted") return "Confirmed request";
|
||||
if (interaction.status === "rejected") return "Declined request";
|
||||
if (interaction.status === "expired") {
|
||||
const outcome = interaction.result?.outcome;
|
||||
if (outcome === "superseded_by_comment") return "Confirmation expired after comment";
|
||||
if (outcome === "stale_target") return "Confirmation expired after target changed";
|
||||
return "Confirmation expired";
|
||||
}
|
||||
return "Requested confirmation";
|
||||
}
|
||||
|
||||
const count = interaction.payload.questions.length;
|
||||
if (interaction.status === "answered") {
|
||||
return count === 1 ? "Answered 1 question" : `Answered ${count} questions`;
|
||||
}
|
||||
return count === 1 ? "Asked 1 question" : `Asked ${count} questions`;
|
||||
}
|
||||
|
||||
export function buildSuggestedTaskTree(
|
||||
tasks: readonly SuggestedTaskDraft[],
|
||||
): SuggestedTaskTreeNode[] {
|
||||
const nodes = new Map<string, SuggestedTaskTreeNode>();
|
||||
for (const task of tasks) {
|
||||
nodes.set(task.clientKey, { task, children: [] });
|
||||
}
|
||||
|
||||
const roots: SuggestedTaskTreeNode[] = [];
|
||||
for (const task of tasks) {
|
||||
const node = nodes.get(task.clientKey);
|
||||
if (!node) continue;
|
||||
const parentNode = task.parentClientKey ? nodes.get(task.parentClientKey) : null;
|
||||
if (parentNode) {
|
||||
parentNode.children.push(node);
|
||||
continue;
|
||||
}
|
||||
roots.push(node);
|
||||
}
|
||||
|
||||
return roots;
|
||||
}
|
||||
|
||||
export function countSuggestedTaskNodes(node: SuggestedTaskTreeNode): number {
|
||||
return 1 + node.children.reduce((sum, child) => sum + countSuggestedTaskNodes(child), 0);
|
||||
}
|
||||
|
||||
export function collectSuggestedTaskClientKeys(node: SuggestedTaskTreeNode): string[] {
|
||||
return [
|
||||
node.task.clientKey,
|
||||
...node.children.flatMap((child) => collectSuggestedTaskClientKeys(child)),
|
||||
];
|
||||
}
|
||||
|
||||
export function getQuestionAnswerLabels(args: {
|
||||
question: AskUserQuestionsQuestion;
|
||||
answers: readonly AskUserQuestionsAnswer[];
|
||||
}) {
|
||||
const { question, answers } = args;
|
||||
const selectedIds =
|
||||
answers.find((answer) => answer.questionId === question.id)?.optionIds ?? [];
|
||||
const optionLabelById = new Map(
|
||||
question.options.map((option) => [option.id, option.label] as const),
|
||||
);
|
||||
return selectedIds
|
||||
.map((optionId) => optionLabelById.get(optionId))
|
||||
.filter((label): label is string => typeof label === "string");
|
||||
}
|
||||
|
|
@ -45,6 +45,7 @@ export const queryKeys = {
|
|||
["issues", companyId, "execution-workspace", executionWorkspaceId] as const,
|
||||
detail: (id: string) => ["issues", "detail", id] as const,
|
||||
comments: (issueId: string) => ["issues", "comments", issueId] as const,
|
||||
interactions: (issueId: string) => ["issues", "interactions", issueId] as const,
|
||||
feedbackVotes: (issueId: string) => ["issues", "feedback-votes", issueId] as const,
|
||||
attachments: (issueId: string) => ["issues", "attachments", issueId] as const,
|
||||
documents: (issueId: string) => ["issues", "documents", issueId] as const,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue