mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents split work into tasks. A task can have a parent task. > - Today agents can nest tasks to any depth: parent, child, grandchild, and deeper. > - Deep agent-made trees are hard to follow, and an agent that works on a child task makes grandchildren by default. > - This pull request limits agent-created trees to two levels: a top-level task and its children. > - A request for a grandchild does not fail. The server puts the new task beside the requester and tells the agent. > - Board users keep full control. They can still nest to any depth. Existing deep trees stay valid. > - The pull request also records which task created each new task, so the audit trail stays complete when the parent changes. ## Linked Issues or Issue Description No public issue exists. This is the feature description. Related: #16853 (budgets that include descendant work) also reasons about task trees; this change does not alter its traversal. **Subsystem affected** Issues (tasks): create, child create and move in the issue service and routes. Agent tools, chat suggestions and creation provenance use these paths. **Problem or motivation** Agents create subtasks as deep as they want. An agent that runs on a child task gets that child as the default parent, so its follow-ups become grandchildren. The trees become deep and hard to read. The parent link is also the only record of which task created a follow-up, so that record is lost when the parent changes. **Proposed solution** Limit agent-created trees to a parent and its children. When an agent asks for a grandchild, put the new task under the requester's parent and return `parentAdjusted`. Do not reject the request. Keep board users unrestricted. Record the originating task in a new server-set `origin_issue_id` column. Keep `origin_run_id` as the originating run. **Alternatives considered** Reject grandchild requests with an error. We did not do this, because agents then fail mid-task. Add a database constraint. We did not do this, because existing deep trees must stay valid and nesting can return later. ## What Changed - Add `MAX_AGENT_TASK_HIERARCHY_DEPTH` (2) and the `IssueParentAdjustment` type in `packages/shared`. - Add `resolveNewTaskParent` and `planIssueParentChange` in `server/src/services/issues.ts`. `create`, `createChild` and `update` use the agent limit by default (`parentDepthPolicy: "flatten"`). - The issue create, `/children` and PATCH routes pass `allow_nested` for board users. For agents, the routes check authorization against the parent that the server actually writes. - The requester keeps its behavior when the server moves a task beside it: `blockParentUntilDone` blocks the requester, and the new task inherits the requester's workspace and privacy. - The server never moves a task above a low-trust boundary root that contains the requester. - These subsystems keep any depth, because they find their work by parent: watchdog reviews, monitor recovery, email-channel placement, and routines that a person configured. - An agent move of a task that has children skips only the parent change and returns `reason: "has_children"`. - Add `issues.origin_issue_id` (nullable, `on delete set null`, indexed) in migration `0434`. Only the server sets it. The `createdFrom` detail field, the `createdFromIssueId` filter and task-creation provenance read it first. - Chat prompts now let a chat agent create one task, a task with children, or separate tasks. The conversation is never a parent. - The runner `create_task` tool accepts an optional `parentTaskId`. A chat agent can create a top-level task and then put subtasks under it. The run must be able to read and change the parent. A conversation is never a parent. The depth limit still applies. Project tools map the field to `parentId` through the issue route. The protocol manifest, semantic contracts and eval fixture are regenerated. - Watchdog runs that have an active watchdog keep their requested parent on all create paths, because their access is limited to the watched subtree. - Fix a bug that the test drive found: the chat (MCP) `create_task` ignored the requested `status`, so a `backlog` task became `todo` and started to run. It now uses the same rule as the native tool. - Update `skills/paperclip`, `doc/SPEC-implementation.md`, and add the plan `doc/plans/2026-11-05-two-level-task-hierarchy.md`. ## Verification - `cd server && npx vitest run src/__tests__/agent-task-hierarchy-depth.test.ts src/__tests__/agent-task-hierarchy-depth-routes.test.ts`: 19 new tests for service and route behavior, all pass. - Related suites (64 files: issues service, thread interactions, privacy, watchdogs, provenance, runner tool authority, decisions, routines, project tools): 1208 tests pass. Two tests changed because of the intended behavior and pass now. Two `email-channels.integration` tests fail locally because the test cannot find a bundled skill file from this worktree path. This change does not touch that code. - `packages/db`: migration safety, snapshot drift and journal tests pass. - Typecheck passes for `server`, `packages/shared`, `packages/db`, `cli` and `ui` (local `ui` errors come only from generated Storybook catalog files that are absent). - Local test drive on an isolated instance with real Claude agents: 29 of 29 use cases pass, including an agent on a child task (follow-ups placed beside it, with the notice) and a chat that creates a top-level task with three subtasks. - I did not run the full `pnpm test:run` or `pnpm build` locally. CI runs them. ## Risks - Behavior change for agents: some follow-ups that were grandchildren are now siblings. The parent of the requester is woken when all its children finish, which now includes these tasks. - The runner `create_task` input contract adds one optional field, so the protocol manifest and the pack contract change. The tool output does not change: it shows the actual `parentId`, and the activity log records `parentAdjusted`. - Migration `0434` adds a nullable column, a foreign key and an index. It does not backfill rows. - `IssueCreationSource.run` is now nullable. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, local test runs). ## 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 - [ ] 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>
193 lines
9.6 KiB
TypeScript
193 lines
9.6 KiB
TypeScript
import { randomUUID } from "node:crypto";
|
|
import express from "express";
|
|
import request from "supertest";
|
|
import { and, eq } from "drizzle-orm";
|
|
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
|
import { activityLog, agents, companies, createDb, heartbeatRuns, issues } from "@paperclipai/db";
|
|
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
|
|
import { issueRoutes } from "../routes/issues.js";
|
|
import { errorHandler } from "../middleware/index.js";
|
|
|
|
const support = await getEmbeddedPostgresTestSupport();
|
|
const describePostgres = support.supported ? describe : describe.skip;
|
|
|
|
describePostgres("agent task hierarchy depth through the issue routes", () => {
|
|
let db: ReturnType<typeof createDb>;
|
|
let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
|
const companyId = randomUUID();
|
|
const agentId = randomUUID();
|
|
const rootId = randomUUID();
|
|
const childId = randomUUID();
|
|
const conversationId = randomUUID();
|
|
const runOnChild = randomUUID();
|
|
const runOnConversation = randomUUID();
|
|
const legacyConversationChildId = randomUUID();
|
|
|
|
beforeAll(async () => {
|
|
database = await startEmbeddedPostgresTestDatabase("paperclip-agent-task-depth-routes-");
|
|
db = createDb(database.connectionString);
|
|
await db.insert(companies).values({
|
|
id: companyId, name: "Paperclip", issuePrefix: "DEP", defaultResponsibleUserId: "board-user",
|
|
requireBoardApprovalForNewAgents: false,
|
|
});
|
|
await db.insert(agents).values({ id: agentId, companyId, name: "Coder", role: "engineer", adapterType: "codex_local", status: "active" });
|
|
await db.insert(issues).values([
|
|
{ id: rootId, companyId, title: "Ship the feature", identifier: "DEP-1", issueNumber: 1, status: "in_progress", assigneeAgentId: agentId },
|
|
{ id: childId, companyId, parentId: rootId, title: "Build the API", identifier: "DEP-2", issueNumber: 2, status: "in_progress", assigneeAgentId: agentId },
|
|
{ id: conversationId, companyId, title: "Chat", identifier: "DEP-3", issueNumber: 3, status: "in_review", assigneeAgentId: agentId,
|
|
conversationAgentId: agentId, conversationUserId: "board-user", conversationState: "waiting" },
|
|
]);
|
|
await db.insert(issues).values({
|
|
id: legacyConversationChildId, companyId, parentId: conversationId, title: "Legacy chat child",
|
|
identifier: "DEP-4", issueNumber: 4, status: "todo", assigneeAgentId: agentId,
|
|
});
|
|
await db.insert(heartbeatRuns).values([
|
|
{ id: runOnChild, companyId, agentId, scopeKind: "issue", issueId: childId, nativeIssueId: childId, status: "running", contextSnapshot: { issueId: childId } },
|
|
{ id: runOnConversation, companyId, agentId, scopeKind: "issue", issueId: conversationId, status: "running", contextSnapshot: { issueId: conversationId } },
|
|
]);
|
|
}, 30_000);
|
|
afterAll(async () => { await database?.cleanup(); });
|
|
|
|
const boardActor = { type: "board", userId: "board-user", source: "local_implicit", isInstanceAdmin: true } as Express.Request["actor"];
|
|
function agentActor(runId: string): Express.Request["actor"] {
|
|
return { type: "agent", companyId, agentId, runId, source: "agent_jwt", onBehalfOfUserId: null, onBehalfOfMemberships: [] } as Express.Request["actor"];
|
|
}
|
|
function app(actor: Express.Request["actor"]) {
|
|
const instance = express();
|
|
instance.use(express.json());
|
|
instance.use((req, _res, next) => { req.actor = actor; next(); });
|
|
instance.use("/api", issueRoutes(db, {} as never));
|
|
instance.use(errorHandler);
|
|
return instance;
|
|
}
|
|
async function activity(issueId: string, action: string) {
|
|
const [row] = await db.select().from(activityLog)
|
|
.where(and(eq(activityLog.entityId, issueId), eq(activityLog.action, action)));
|
|
return row ?? null;
|
|
}
|
|
const expectedAdjustment = {
|
|
reason: "max_agent_depth",
|
|
applied: true,
|
|
requestedParent: { id: childId, identifier: "DEP-2" },
|
|
effectiveParent: { id: rootId, identifier: "DEP-1" },
|
|
};
|
|
|
|
it("places a run's default follow-up beside the child task it is working on", async () => {
|
|
const created = await request(app(agentActor(runOnChild)))
|
|
.post(`/api/companies/${companyId}/issues`)
|
|
.send({ title: "Write the migration" });
|
|
expect(created.status, JSON.stringify(created.body)).toBe(201);
|
|
expect(created.body.parentId).toBe(rootId);
|
|
expect(created.body.originIssueId).toBe(childId);
|
|
expect(created.body.originRunId).toBe(runOnChild);
|
|
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
|
|
expect((await activity(created.body.id, "issue.created"))?.details).toMatchObject({
|
|
parentId: rootId,
|
|
parentAdjusted: expectedAdjustment,
|
|
parentDefaultedFromRunIssue: true,
|
|
});
|
|
|
|
const detail = await request(app(boardActor)).get(`/api/issues/${created.body.id}`);
|
|
expect(detail.body.createdFrom).toMatchObject({ issue: { id: childId, identifier: "DEP-2" } });
|
|
});
|
|
|
|
it("places an explicit agent grandchild beside the requester instead of failing", async () => {
|
|
const created = await request(app(agentActor(runOnChild)))
|
|
.post(`/api/companies/${companyId}/issues`)
|
|
.send({ title: "Add tests", parentId: childId });
|
|
expect(created.status, JSON.stringify(created.body)).toBe(201);
|
|
expect(created.body.parentId).toBe(rootId);
|
|
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
|
|
});
|
|
|
|
it("places an agent child created through the children route beside the requester", async () => {
|
|
const created = await request(app(agentActor(runOnChild)))
|
|
.post(`/api/issues/${childId}/children`)
|
|
.send({ title: "Update the docs" });
|
|
expect(created.status, JSON.stringify(created.body)).toBe(201);
|
|
expect(created.body.parentId).toBe(rootId);
|
|
expect(created.body.originIssueId).toBe(childId);
|
|
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
|
|
expect((await activity(created.body.id, "issue.child_created"))?.details).toMatchObject({
|
|
parentId: rootId,
|
|
requestedParentId: childId,
|
|
});
|
|
});
|
|
|
|
it("lets board users create grandchildren", async () => {
|
|
const created = await request(app(boardActor))
|
|
.post(`/api/companies/${companyId}/issues`)
|
|
.send({ title: "Board grandchild", parentId: childId });
|
|
expect(created.status, JSON.stringify(created.body)).toBe(201);
|
|
expect(created.body.parentId).toBe(childId);
|
|
expect(created.body).not.toHaveProperty("parentAdjusted");
|
|
|
|
const viaChildren = await request(app(boardActor))
|
|
.post(`/api/issues/${childId}/children`)
|
|
.send({ title: "Board grandchild via children route" });
|
|
expect(viaChildren.status, JSON.stringify(viaChildren.body)).toBe(201);
|
|
expect(viaChildren.body.parentId).toBe(childId);
|
|
});
|
|
|
|
it("flattens agent moves into a child and lets board users move freely", async () => {
|
|
const [agentMoved, boardMoved] = [randomUUID(), randomUUID()];
|
|
await db.insert(issues).values([
|
|
{ id: agentMoved, companyId, title: "Loose task", status: "todo", assigneeAgentId: agentId },
|
|
{ id: boardMoved, companyId, title: "Board loose task", status: "todo", assigneeAgentId: agentId },
|
|
]);
|
|
|
|
const byAgent = await request(app(agentActor(runOnChild)))
|
|
.patch(`/api/issues/${agentMoved}`)
|
|
.send({ parentId: childId });
|
|
expect(byAgent.status, JSON.stringify(byAgent.body)).toBe(200);
|
|
expect(byAgent.body.parentId).toBe(rootId);
|
|
expect(byAgent.body.parentAdjusted).toEqual(expectedAdjustment);
|
|
expect((await activity(agentMoved, "issue.updated"))?.details).toMatchObject({
|
|
parentId: rootId,
|
|
requestedParentId: childId,
|
|
parentAdjusted: expectedAdjustment,
|
|
});
|
|
|
|
const byBoard = await request(app(boardActor))
|
|
.patch(`/api/issues/${boardMoved}`)
|
|
.send({ parentId: childId });
|
|
expect(byBoard.status, JSON.stringify(byBoard.body)).toBe(200);
|
|
expect(byBoard.body.parentId).toBe(childId);
|
|
expect(byBoard.body).not.toHaveProperty("parentAdjusted");
|
|
});
|
|
|
|
it("records a top-level placement when an agent moves under a legacy conversation child", async () => {
|
|
const movingId = randomUUID();
|
|
await db.insert(issues).values({ id: movingId, companyId, parentId: rootId, title: "Move to top", status: "todo", assigneeAgentId: agentId });
|
|
|
|
const moved = await request(app(agentActor(runOnChild)))
|
|
.patch(`/api/issues/${movingId}`)
|
|
.send({ parentId: legacyConversationChildId });
|
|
expect(moved.status, JSON.stringify(moved.body)).toBe(200);
|
|
expect(moved.body.parentId).toBeNull();
|
|
expect(moved.body.parentAdjusted).toMatchObject({ reason: "max_agent_depth", effectiveParent: null });
|
|
expect((await activity(movingId, "issue.updated"))?.details).toMatchObject({
|
|
parentId: null,
|
|
requestedParentId: legacyConversationChildId,
|
|
});
|
|
});
|
|
|
|
it("lets a chat create a top-level task and a child under it", async () => {
|
|
const top = await request(app(agentActor(runOnConversation)))
|
|
.post(`/api/companies/${companyId}/issues`)
|
|
.send({ title: "Plan the launch", assigneeAgentId: agentId });
|
|
expect(top.status, JSON.stringify(top.body)).toBe(201);
|
|
expect(top.body.parentId).toBeNull();
|
|
expect(top.body.originIssueId).toBe(conversationId);
|
|
|
|
const child = await request(app(agentActor(runOnConversation)))
|
|
.post(`/api/companies/${companyId}/issues`)
|
|
.send({ title: "Draft the announcement", parentId: top.body.id, assigneeAgentId: agentId });
|
|
expect(child.status, JSON.stringify(child.body)).toBe(201);
|
|
expect(child.body.parentId).toBe(top.body.id);
|
|
// Both originate from the chat that created them.
|
|
expect(child.body.originIssueId).toBe(conversationId);
|
|
expect(child.body).not.toHaveProperty("parentAdjusted");
|
|
});
|
|
});
|