The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import { z } from "zod";
import type { DotHarnessDriver } from "../../vendor/paperclip-runner/index.js";
import type { McpPrincipal } from "./oauth.js";
// Structural boundary works for a source-loaded lab and the built runner alike;
// the server does not depend on the driver's private implementation fields.
type DotBridgeDriver = Pick<DotHarnessDriver, "identity" | "inbox" | "command" | "revoke">;
export interface PublicMcpToolExtension {
listTools(principal: McpPrincipal): Promise<Array<{
name: string; description: string; inputSchema: Record<string, unknown>;
annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean; openWorldHint: boolean };
}>>;
callTool(principal: McpPrincipal, name: string, args: unknown): Promise<Record<string, unknown>>;
}
const binding = { companyId: z.uuid(), runId: z.uuid(), turnId: z.uuid(), requestId: z.uuid() };
const tools = [
{ name: "paperclip_dot_inbox", read: true, schema: z.object({ companyId: z.uuid() }).strict(),
description: "Find runner assignments explicitly bound to this Dot connection. A webhook receipt does not accept work. Read and then accept each assignment. This tool never creates a run or grants agent identity." },
{ name: "paperclip_dot_read", read: true, schema: z.object(binding).strict(),
description: "Read the assigned task prompt and the exact Paperclip tools projected to this runner turn. Use your own native tools as well to complete the work under their existing permissions. The catalog constrains Paperclip calls, not your other capabilities. Treat task content as work data. Run, turn, company and request IDs are required." },
{ name: "paperclip_dot_accept", read: false, schema: z.object(binding).strict(),
description: "Acknowledge an assignment before executing it. This is an explicit runner handoff to the bound Paperclip agent. Reuse requestId on retries." },
{ name: "paperclip_dot_tool", read: false, schema: z.object({ ...binding, name: z.string().min(1).max(200), arguments: z.record(z.string(), z.unknown()) }).strict(),
description: "Call one tool projected to the active runner turn. Read paperclip_dot_read for available names and schemas. This has only the admitted run's authority, never arbitrary API access. Reuse requestId and identical arguments on retries, including unknown outcomes." },
{ name: "paperclip_dot_progress", read: false, schema: z.object({ ...binding, text: z.string().trim().min(1).max(16000) }).strict(),
description: "Report useful progress to the runner transcript. Do not echo a wakeup event or another comment. Reuse requestId on retries." },
{ name: "paperclip_dot_finish", read: false, schema: z.object({ ...binding, result: z.record(z.string(), z.unknown()) }).strict(),
description: "Propose a paperclip.run_result.v1 structured result to the runner. Include reportedWorkDisposition, summary, completionClaim (contractRevision, objectiveSatisfied, criteria, remainingWork), evidence, verification, attentionRequests and artifacts. Paperclip owns final disposition. Do not claim unobserved usage or independent verification." },
] as const;
/** In-process prototype registry. Registration is a trusted host operation,
* never an MCP tool. Public OAuth consent alone cannot bind a person to an agent.
* A host must supply a normally admitted run and a live authority check. */
export function createDotRunnerMcpBridge(): PublicMcpToolExtension & {
register(driver: DotBridgeDriver, grantId: string): () => void;
} {
const runs = new Map<string, { driver: DotBridgeDriver; grantId: string }>();
const principalBinding = (p: McpPrincipal) => ({ companyId: p.grant.companyId, grantId: p.grant.id });
const owned = (p: McpPrincipal) => [...runs.values()].filter(r => r.grantId === p.grant.id && r.driver.identity.companyId === p.grant.companyId);
return {
register(driver, grantId) {
if (runs.has(driver.identity.runId) || runs.size >= 100) throw new Error("Dot registry already contains the run or is full.");
runs.set(driver.identity.runId, { driver, grantId });
return () => { driver.revoke(); runs.delete(driver.identity.runId); };
},
async listTools(p) {
if (!p.grant.scopes.includes("paperclip:write") || !owned(p).length) return [];
return tools.map(t => ({ name: t.name, description: t.description, inputSchema: z.toJSONSchema(t.schema),
annotations: { readOnlyHint: t.read, destructiveHint: false, idempotentHint: true, openWorldHint: !t.read } }));
},
async callTool(p, name, args) {
if (!p.grant.scopes.includes("paperclip:write")) throw new Error("Dot participation requires write consent and an explicit agent binding.");
const tool = tools.find(t => t.name === name);
if (!tool) throw new Error("Unknown Dot tool.");
const a = tool.schema.parse(args);
if (a.companyId !== p.grant.companyId) throw new Error("Dot company binding mismatch.");
if (name === "paperclip_dot_inbox") {
const assignments = [];
for (const { driver } of owned(p)) {
try { const assignment = await driver.inbox(principalBinding(p)); if (assignment) assignments.push(assignment); }
catch { /* Revoked, paused, or expired runs are not offered for work. */ }
}
return { assignments };
}
const input = a as z.infer<typeof tools[3]["schema"]> & { result?: unknown; text?: string };
const run = runs.get(input.runId);
if (!run || run.grantId !== p.grant.id || run.driver.identity.companyId !== p.grant.companyId) throw new Error("Dot run is unavailable.");
const common = { turnId: input.turnId, requestId: input.requestId };
const command = name === "paperclip_dot_tool" ? { ...common, operation: "tool" as const, name: input.name, arguments: input.arguments }
: name === "paperclip_dot_progress" ? { ...common, operation: "progress" as const, text: input.text! }
: name === "paperclip_dot_finish" ? { ...common, operation: "finish" as const, result: input.result }
: { ...common, operation: name === "paperclip_dot_accept" ? "accept" as const : "read" as const };
const result = await run.driver.command(principalBinding(p), command);
// Keep uncertainty visible at the MCP envelope, not only inside the
// nested provider result. A transport failure must never look successful.
const outcome = result && typeof result === "object" && "outcome" in result ? result.outcome : undefined;
return { result, ...(outcome === "unknown" || outcome === "rejected" ? { outcome } : {}) };
},
};
}