[codex] Add plugin orchestration host APIs (#4114)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The plugin system is the extension path for optional capabilities
that should not require core product changes for every integration.
> - Plugins need scoped host APIs for issue orchestration, documents,
wakeups, summaries, activity attribution, and isolated database state.
> - Without those host APIs, richer plugins either cannot coordinate
Paperclip work safely or need privileged core-side special cases.
> - This pull request adds the plugin orchestration host surface, scoped
route dispatch, a database namespace layer, and a smoke plugin that
exercises the contract.
> - The benefit is a broader plugin API that remains company-scoped,
auditable, and covered by tests.

## What Changed

- Added plugin orchestration host APIs for issue creation, document
access, wakeups, summaries, plugin-origin activity, and scoped API route
dispatch.
- Added plugin database namespace tables, schema exports, migration
checks, and idempotent replay coverage under migration
`0059_plugin_database_namespaces`.
- Added shared plugin route/API types and validators used by server and
SDK boundaries.
- Expanded plugin SDK types, protocol helpers, worker RPC host behavior,
and testing utilities for orchestration flows.
- Added the `plugin-orchestration-smoke-example` package to exercise
scoped routes, restricted database namespaces, issue orchestration,
documents, wakeups, summaries, and UI status surfaces.
- Kept the new orchestration smoke fixture out of the root pnpm
workspace importer so this PR preserves the repository policy of not
committing `pnpm-lock.yaml`.
- Updated plugin docs and database docs for the new orchestration and
database namespace surfaces.
- Rebased the branch onto `public-gh/master`, resolved conflicts, and
removed `pnpm-lock.yaml` from the final PR diff.

## Verification

- `pnpm install --frozen-lockfile`
- `pnpm --filter @paperclipai/db typecheck`
- `pnpm exec vitest run packages/db/src/client.test.ts`
- `pnpm exec vitest run server/src/__tests__/plugin-database.test.ts
server/src/__tests__/plugin-orchestration-apis.test.ts
server/src/__tests__/plugin-routes-authz.test.ts
server/src/__tests__/plugin-scoped-api-routes.test.ts
server/src/__tests__/plugin-sdk-orchestration-contract.test.ts`
- From `packages/plugins/examples/plugin-orchestration-smoke-example`:
`pnpm exec vitest run --config ./vitest.config.ts`
- `pnpm --dir
packages/plugins/examples/plugin-orchestration-smoke-example run
typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- PR CI on latest head `293fc67c`: `policy`, `verify`, `e2e`, and
`security/snyk` all passed.

## Risks

- Medium risk: this expands plugin host authority, so route auth,
company scoping, and plugin-origin activity attribution need careful
review.
- Medium risk: database namespace migration behavior must remain
idempotent for environments that may have seen earlier branch versions.
- Medium risk: the orchestration smoke fixture is intentionally excluded
from the root workspace importer to avoid a `pnpm-lock.yaml` PR diff;
direct fixture verification remains listed above.
- Low operational risk from the PR setup itself: the branch is rebased
onto current `master`, the migration is ordered after upstream
`0057`/`0058`, and `pnpm-lock.yaml` is not in the final diff.

> 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`.

Roadmap checked: this work aligns with the completed Plugin system
milestone and extends the plugin surface rather than duplicating an
unrelated planned core feature.

## Model Used

- OpenAI Codex, GPT-5-based coding agent in a tool-enabled CLI
environment. Exact hosted model build and context-window size are not
exposed by the runtime; reasoning/tool use were enabled for repository
inspection, editing, testing, git operations, and PR creation.

## 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
- [x] If this change affects the UI, I have included before/after
screenshots (N/A: no core UI screen change; example plugin UI contract
is covered by tests)
- [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>

packages/plugins/examples/plugin-orchestration-smoke-example/tests/plugin.spec.ts

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { pluginManifestV1Schema, type Issue } from "@paperclipai/shared";
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import manifest from "../src/manifest.js";
+import plugin from "../src/worker.js";
+
+function issue(input: Partial<Issue> & Pick<Issue, "id" | "companyId" | "title">): Issue {
+  const now = new Date();
+  const { id, companyId, title, ...rest } = input;
+  return {
+    id,
+    companyId,
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title,
+    description: null,
+    status: "todo",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: null,
+    identifier: null,
+    originKind: "manual",
+    originId: null,
+    originRunId: null,
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    createdAt: now,
+    updatedAt: now,
+    ...rest,
+  };
+}
+
+describe("orchestration smoke plugin", () => {
+  it("declares the Phase 1 orchestration surfaces", () => {
+    expect(pluginManifestV1Schema.parse(manifest)).toMatchObject({
+      id: "paperclipai.plugin-orchestration-smoke-example",
+      database: {
+        migrationsDir: "migrations",
+        coreReadTables: ["issues"],
+      },
+      apiRoutes: [
+        expect.objectContaining({ routeKey: "initialize" }),
+        expect.objectContaining({ routeKey: "summary" }),
+      ],
+    });
+  });
+
+  it("creates plugin-owned orchestration rows, issue tree, document, wakeup, and summary reads", async () => {
+    const companyId = randomUUID();
+    const rootIssueId = randomUUID();
+    const agentId = randomUUID();
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      issues: [
+        issue({
+          id: rootIssueId,
+          companyId,
+          title: "Root orchestration issue",
+          assigneeAgentId: agentId,
+        }),
+      ],
+    });
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.performAction<{
+      rootIssueId: string;
+      childIssueId: string;
+      blockerIssueId: string;
+      billingCode: string;
+      subtreeIssueIds: string[];
+      wakeupQueued: boolean;
+    }>("initialize-smoke", {
+      companyId,
+      issueId: rootIssueId,
+      assigneeAgentId: agentId,
+    });
+
+    expect(result.rootIssueId).toBe(rootIssueId);
+    expect(result.childIssueId).toEqual(expect.any(String));
+    expect(result.blockerIssueId).toEqual(expect.any(String));
+    expect(result.billingCode).toBe(`plugin-smoke:${rootIssueId}`);
+    expect(result.wakeupQueued).toBe(true);
+    expect(result.subtreeIssueIds).toEqual(expect.arrayContaining([rootIssueId, result.childIssueId]));
+    expect(harness.dbExecutes[0]?.sql).toContain(".smoke_runs");
+    expect(harness.dbQueries.some((entry) => entry.sql.includes("JOIN public.issues"))).toBe(true);
+
+    const relations = await harness.ctx.issues.relations.get(result.childIssueId, companyId);
+    expect(relations.blockedBy).toEqual([
+      expect.objectContaining({
+        id: result.blockerIssueId,
+        status: "done",
+      }),
+    ]);
+    const docs = await harness.ctx.issues.documents.list(result.childIssueId, companyId);
+    expect(docs).toEqual([
+      expect.objectContaining({
+        key: "orchestration-smoke",
+        title: "Orchestration Smoke",
+      }),
+    ]);
+  });
+
+  it("dispatches the scoped API route through the same smoke path", async () => {
+    const companyId = randomUUID();
+    const rootIssueId = randomUUID();
+    const agentId = randomUUID();
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      issues: [
+        issue({
+          id: rootIssueId,
+          companyId,
+          title: "Scoped API root",
+          assigneeAgentId: agentId,
+        }),
+      ],
+    });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(plugin.definition.onApiRequest?.({
+      routeKey: "initialize",
+      method: "POST",
+      path: `/issues/${rootIssueId}/smoke`,
+      params: { issueId: rootIssueId },
+      query: {},
+      body: { assigneeAgentId: agentId },
+      actor: {
+        actorType: "user",
+        actorId: "board",
+        userId: "board",
+        agentId: null,
+        runId: null,
+      },
+      companyId,
+      headers: {},
+    })).resolves.toMatchObject({
+      status: 201,
+      body: expect.objectContaining({
+        rootIssueId,
+        wakeupQueued: true,
+      }),
+    });
+  });
+});