mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 10:48:12 +02:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use connections to reach external services. > - A fresh native task can have no service tools installed. > - The agent needs a way to discover services and ask the responsible person for access. > - This pull request brings the existing connection-intent flow into native task execution. > - The person can connect from the task, and the agent can continue with updated tools. ## Linked Issues or Issue Description **Subsystem affected** Native runner tool authority, connection intents, task interactions, and shared connection setup. **Problem or motivation** A task that needs an unconnected service cannot finish its work. Leaving the task to configure access also loses context. A resolved request must survive a restart and resume the correct agent once. **Proposed solution** Expose connection discovery and access requests as server-owned native tools. Render a durable task card and use the shared setup dialog. Persist outcome delivery and start a fresh provider session after access is ready. **Alternatives considered** Sending the person to the Connections page adds navigation and does not solve continuation. Polling for authorization consumes runs and can create duplicate requests. **Roadmap alignment** This extends the existing connection-intent runtime and setup experience. It reuses the shared access model and the native runner. Related: #12345, #12347. The service-slug fix in #12906 is related but separate. Companion evaluation PR: https://github.com/paperclipai/paperclip-evals/pull/21. ## What Changed - Expose `connections_search` and `connection_request` with server-bound company, task, agent, and responsible user. Preserve the legacy entry points. - Discover catalog services and authorized custom connections. Check installation, identity, health, and executable permissions before reporting ready. - Keep pending cards through ordinary messages. Reuse requests and retire stale ownership. Put Connect at the right of Not now. - Reuse the shared setup flow in a task dialog. Keep access additive and default to the requesting agent. Recover from cancelled or blocked OAuth windows with a new-tab fallback. - Persist outcome delivery with an idempotent wake key. Resume in a fresh session and recheck ownership before dispatch. - Add native browser fixtures, offline Storybook states, server contracts, and evaluation fixtures. Update guidance and documentation. ## Verification - `pnpm build`: passed after replaying the change on current master. - `pnpm -r typecheck`: passed. - `pnpm check:token-gates`: passed. - `pnpm --filter @paperclipai/ui build-storybook`: passed. - New continuation-policy regression cases: 16 passed. - Docker-backed PostgreSQL regressions passed for requester-only OAuth access, assignment-only expiry, terminal expiry, and credential-free setup metadata. - Shared setup and task-card UI tests: 121 passed, including configured MCP reconnect URL recovery and preserving user edits across refetch. - Storybook browser checks: all 119 passed on the latest reconnect fix. - `pnpm test:run`: 4,734 tests passed in the first server group, but embedded PostgreSQL startup failures and resulting cleanup errors prevented a complete local pass. All Linux CI lanes passed on the latest reviewed commit. One external-object route test returned an unexplained 500 on the first run; it passed twice locally and the failed shard passed on retry without code changes. - Earlier feature-checkout evidence: three deterministic native browser journeys passed, including restart delivery and an actual fixture tool result. Legacy scripted coverage also passed. All 59 added stories were inspected in light and dark themes. - Live Notion testing recorded successful provider reads. The manual test used a local-trusted instance. It does not prove authenticated/cloud deployment or every provider journey. - Native browser rerun reached the embedded PostgreSQL startup limit before bootstrap, so the latest checkout’s full native browser journey remains unverified. Both OAuth page/task regression cases passed against isolated Docker-backed PostgreSQL 17. They verify no premature task access, requester-only completion, additive retries, and reconnect preservation. - Applied both new migrations twice to isolated PostgreSQL 17. Foreign keys remained intact, duplicate active delivery keys were rejected, and failed delivery records did not block retries. Reviewer path: start a fresh test drive, enable the native runner, use an agent that can perform work directly, and ask it to summarize a Notion page. Connect from the card, then verify the resumed provider call and source-linked answer. The default test-drive CEO is instructed to delegate, so it can introduce an unrelated hiring step. ## Risks - Two additive migrations create durable deliveries and a partial unique wake index. They are idempotent. The wake index can require a maintenance window on large tables because migrations run in a transaction. - OAuth and continuation cross asynchronous boundaries. Tests cover ownership changes, retries, additive access, and restart delivery; live provider behavior still varies. - The latest requester-scope fix has not yet been exercised through live OAuth. GitHub, API-key, authenticated-user, and all recovery journeys are not claimed as verified. ## Model Used OpenAI GPT-6-based Codex assisted with implementation, tests, and review using tools and code execution. The runtime does not expose the exact model version, context window, or reasoning setting. Live evaluation used `gpt-5.6-luna`; manual native testing used `gpt-5.6-sol`. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used and disclosed unavailable runtime details - [x] I have checked ROADMAP.md and confirmed this extends existing connection work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have described the issue in-PR following the feature issue template - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [ ] I have run all required 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 risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
123 lines
8.1 KiB
JavaScript
123 lines
8.1 KiB
JavaScript
#!/usr/bin/env node
|
|
// Deterministic provider only. The production Rust runner, tool authority, and
|
|
// authenticated MCP gateway still execute every tool and enforce access.
|
|
import { randomUUID } from 'node:crypto';
|
|
import { readFileSync } from 'node:fs';
|
|
import { join, resolve } from 'node:path';
|
|
import { createInterface } from 'node:readline';
|
|
if (process.argv.includes('--version')) { console.log('codex-cli 0.115.0 (in-feed fixture)'); process.exit(0); }
|
|
let threadId = `fixture-${randomUUID()}`;
|
|
let turnId, toolSequence = 0, declined = false;
|
|
let completionContract = { revision: "1", criterionIds: ["objective"] };
|
|
const pending = new Map();
|
|
const send = (value) => process.stdout.write(`${JSON.stringify(value)}\n`);
|
|
const call = (tool, args) => new Promise((resolve, reject) => {
|
|
const id = `connection-tool-${++toolSequence}`;
|
|
pending.set(id, { resolve, reject });
|
|
send({ id, method: 'item/tool/call', params: { threadId, turnId, callId: id, tool, arguments: args } });
|
|
});
|
|
function unwrap(result) {
|
|
const texts = result?.contentItems ?? result?.content ?? [];
|
|
for (const item of texts) {
|
|
try { const parsed = JSON.parse(item.text); return parsed.value ?? parsed; } catch {}
|
|
}
|
|
return result;
|
|
}
|
|
async function mcp(method, params = {}) {
|
|
// Native execution creates a dedicated provider home and issues a short-lived
|
|
// gateway token for this fixture run. Never load the user's normal Codex home.
|
|
if (!process.env.CODEX_HOME || !process.env.HOME
|
|
|| resolve(process.env.CODEX_HOME) !== resolve(process.env.HOME)) {
|
|
throw new Error('The fixture requires an isolated native provider home');
|
|
}
|
|
const config = readFileSync(join(process.env.CODEX_HOME, 'config.toml'), 'utf8');
|
|
const url = JSON.parse(config.match(/^url = (.+)$/m)?.[1] ?? 'null');
|
|
const authorization = JSON.parse(config.match(/Authorization = (".*?")/m)?.[1] ?? 'null');
|
|
if (!url || !authorization) throw new Error('Native continuation did not install the MCP gateway');
|
|
const endpoint = new URL(url);
|
|
if (endpoint.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname)
|
|
|| endpoint.username || endpoint.password || endpoint.hash) {
|
|
throw new Error('The fixture only accepts a local native gateway');
|
|
}
|
|
const response = await fetch(endpoint, { redirect: 'error', method: 'POST', headers: { Authorization: authorization, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' }, body: JSON.stringify({ jsonrpc: '2.0', id: ++toolSequence, method, params }) });
|
|
if (!response.ok) throw new Error(`Gateway HTTP ${response.status}`);
|
|
const text = await response.text();
|
|
const envelope = JSON.parse(text.startsWith('event:') || text.startsWith('data:') ? text.split('\n').find((line) => line.startsWith('data:')).slice(5) : text);
|
|
if (envelope.error) throw new Error(envelope.error.message);
|
|
return envelope.result;
|
|
}
|
|
async function finish(text, evidenceRef) {
|
|
return call('paperclip_finish', { schema: 'paperclip.run_result.v1', reportedWorkDisposition: 'done', summary: text,
|
|
completionClaim: { contractRevision: completionContract.revision, objectiveSatisfied: true, criteria: completionContract.criterionIds.map((criterionId) => ({ criterionId, status: 'satisfied', evidenceRefs: [evidenceRef] })), remainingWork: [] },
|
|
evidence: [{ ref: evidenceRef }], verification: [{ commandOrCheck: 'Fixture outcome', status: 'passed' }], attentionRequests: [], artifacts: [] });
|
|
}
|
|
async function execute() {
|
|
if (declined) {
|
|
const text = 'Connection declined. I will use the information already in this task and pursue alternatives.';
|
|
await call('report_progress', { idempotencyKey: `declined-${turnId}`, body: text });
|
|
await finish(text, 'task:declined-alternative');
|
|
send({ method: 'item/completed', params: { threadId, turnId, item: { id: `answer-${turnId}`, type: 'agentMessage', text } } });
|
|
send({ method: 'turn/completed', params: { threadId, turn: { id: turnId, status: 'completed' } } });
|
|
return;
|
|
}
|
|
const discovery = unwrap(await call('connections_search', { query: 'heliotrope' }));
|
|
const service = discovery.results?.find((item) => item.source === 'configured');
|
|
if (!service) throw new Error('Authorized Research Archive fixture was not discoverable');
|
|
const request = unwrap(await call('connection_request', { service: service.service }));
|
|
const refreshingTools = request.state === 'ready' && request.instruction?.includes('fresh continuation with updated tools is queued');
|
|
let text;
|
|
if (request.state === 'needs_user_action') {
|
|
text = 'I need access to the research archive. I can organize the launch checklist while you connect it.';
|
|
} else if (refreshingTools) {
|
|
// Follow the authority's yield instruction when authorization arrives after
|
|
// this provider session pinned its tools. The next session must do the read.
|
|
text = 'Access is ready. I will continue the archive read with the updated tools.';
|
|
} else {
|
|
await mcp('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'in-feed-fixture', version: '1' } });
|
|
const list = await mcp('tools/list');
|
|
const tool = list.tools.find((item) => /heliotrope/.test(item.description ?? '') || /archive_read/.test(item.name));
|
|
if (!tool) throw new Error('Updated native tool snapshot does not contain archive_read');
|
|
const result = await mcp('tools/call', { name: tool.name, arguments: {} });
|
|
if (result.isError) throw new Error(JSON.stringify(result));
|
|
text = result.content.filter((item) => item.type === 'text').map((item) => item.text).join('\n');
|
|
if (!text.includes('HELIOTROPE-42')) throw new Error('Provider fixture value missing');
|
|
}
|
|
await call('report_progress', { idempotencyKey: `fixture-answer-${turnId}`, body: text });
|
|
if (request.state === 'ready' && !refreshingTools) await finish(text, 'mcp:archive_read');
|
|
send({ method: 'item/completed', params: { threadId, turnId, item: { id: `answer-${turnId}`, type: 'agentMessage', text } } });
|
|
send({ method: 'turn/completed', params: { threadId, turn: { id: turnId, status: 'completed' } } });
|
|
}
|
|
createInterface({ input: process.stdin }).on('line', (line) => {
|
|
const message = JSON.parse(line);
|
|
if (!message.method && pending.has(message.id)) {
|
|
const promise = pending.get(message.id); pending.delete(message.id);
|
|
message.error ? promise.reject(new Error(message.error.message)) : promise.resolve(message.result); return;
|
|
}
|
|
const { id, method } = message;
|
|
if (method === 'initialize') send({ id, result: { user: { sessionId: threadId } } });
|
|
else if (method === 'thread/start' || method === 'thread/resume') {
|
|
if (method === 'thread/resume' && message.params?.threadId) threadId = message.params.threadId;
|
|
if (message.params?.completionContract) completionContract = message.params.completionContract;
|
|
send({ id, result: { model: 'in-feed-fixture', modelProvider: 'fixture', thread: { id: threadId, sessionId: threadId } } });
|
|
}
|
|
else if (method === 'thread/read') send({ id, result: { thread: { id: threadId, turns: [] } } });
|
|
else if (method === 'turn/start') {
|
|
declined = /connection_intent/.test(JSON.stringify(message.params)) && /rejected/.test(JSON.stringify(message.params));
|
|
for (const part of message.params?.input ?? []) {
|
|
try {
|
|
const envelope = JSON.parse(part.text);
|
|
const contract = envelope.task?.completionContract ?? envelope.completionContract;
|
|
if (contract?.revision && contract.criteria) completionContract = { revision: contract.revision, criterionIds: contract.criteria.map((criterion) => criterion.id) };
|
|
} catch { /* Non-envelope text is ordinary task context. */ }
|
|
}
|
|
turnId = randomUUID();
|
|
send({ id, result: { turn: { id: turnId, status: 'inProgress' } } });
|
|
send({ method: 'turn/started', params: { threadId, turn: { id: turnId, status: 'inProgress' } } });
|
|
// Deliver model output on a later tick, after the runner accepts turn/start.
|
|
setTimeout(() => void execute().catch((error) => {
|
|
process.stderr.write(`In-feed fixture: ${error.message}\n`);
|
|
send({ method: 'turn/completed', params: { threadId, turn: { id: turnId, status: 'failed', error: { message: error.message } } } });
|
|
}), 50);
|
|
} else if (id != null) send({ id, result: {} });
|
|
});
|