papercliped 2.2.1 → 2.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## v2.4.0 — the control room: manage every session, agent and tool inside Paperclip
+
+- **The control room.** The Papercliped plugin now opens a control room inside Paperclip, in Paperclip's own design: a left menu that replaces the company menu (Overview, Sessions, Agents, Tools, Activity, Settings), the way Paperclip's own agent page does. See every connected AI app, what each may use, which agents it applies to, and what it has done. New guides: **The control room** and **API only, Full or Agent only**.
+- **An access switch: API only, Full or Agent only.** One three-position switch (with a sliding knob, keyboard support and a small version for the dashboard) decides how AI apps may work with your Paperclip. **API only**: look and control Paperclip directly (pause, budgets, approvals, goals) but don't hand work to agents. **Agent only**: look and work through agents (create, assign and comment on issues, wake an agent) but no direct control. **Full** (the default, so nothing changes until you choose): both. It takes effect on the app's next request.
+- **Set any agent apart.** On the Agents page, or on a new **Papercliped tab on every agent's page**, give an agent its own mode, or turn it **Off**: AI apps can't see it, touch it, or see what is assigned to it. Off agents are removed from lists and reports before the report is written, so they can't leak into a summary.
+- **Sessions you can manage.** Every connected app is a session: give it a name, change its level, choose exactly which of the tools it may use (grouped as Look, Work through agents and Direct control), and choose whether it applies to everyone or only selected agents. A session limited to selected agents works only with those agents; it can't use views across every agent, and the page says so.
+- **Blocked calls are visible.** A refused call returns a plain message naming the setting and where to change it (with a `policy` code in the API), and shows as **Blocked** in the new Activity page, which lists the newest calls, their session, tool and result, never what was sent or returned. AI apps are no longer shown tools that can never run for their session.
+- **A dashboard widget** with the access switch in small, the number of sessions and how many calls were blocked today.
+- **Tool reference shows each tool's kind** (a new "Works in" column), and `paperclip_api_request` is described correctly: `GET` works in every mode.
+- **For API users:** new management endpoints `GET /sessions`, `POST|DELETE /sessions/:id`, `GET|POST|PUT /policy`, `GET /tools` and `GET /activity`; a new error class `policy_blocked` in the public API's aggregate error classes; migration `007_control_room.sql` adds two nullable columns and needs no backfill.
+- **Update note.** Paperclip won't update a plugin to a version that asks for new permissions without an admin's approval, so to get the control room remove the Papercliped plugin in Settings → Plugins and install it again (or connect your Paperclip again with the install box ticked). Your account, sessions and settings are kept.
+- **The Papercliped plugin now looks like part of Paperclip.** Its sidebar entry has the same paperclip icon, spacing, type, hover and highlighted-when-open look as Tasks, Artifacts and Cases, and the page uses Paperclip’s own cards, inputs, buttons, tabs and text styles, so it follows your theme (light, dark, seasonal) instead of imitating it.
+- **Fixed: the Papercliped page inside Paperclip no longer invites your browser to fill in your Paperclip login.** The page shares an address with Paperclip’s own sign-in, so browsers offered your saved Paperclip email and password in the "Link your Papercliped account" fields, one click from sending that password to Papercliped as a "secret key". Those fields (and the confirm boxes) now tell the browser not to autofill. If you linked an account on 2.2.1, nothing needs doing; if a saved login was ever filled in, do not press Link.
+
+## v2.3.0 — host your Paperclip anywhere, and a prompt gallery
+
+- **Host your Paperclip: a step-by-step guide for every option.** A new docs section takes you from nothing to a running Paperclip with a public `https://` address, connected to Papercliped and answering your first prompt. It covers your own computer with a free tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok), a VPS with Docker and Caddy (Hetzner, DigitalOcean, Linode, Oracle's free tier), Railway, Render, Fly.io and Coolify, with a comparison of cost and effort. Every guide uses the official Paperclip image and the settings current Paperclip needs: authenticated mode with public exposure, your public URL, the two secrets, a persistent disk at `/paperclip`, creating the first admin with `paperclipai auth bootstrap-ceo`, and signing in your agents with API keys or a subscription. They also cover updates and backups. Hosts that sleep or have no disk are flagged as unsuitable.
+- **Prompt gallery.** More than 40 ready-to-copy prompts at papercliped.co/prompts and in the docs (Guides → Prompt gallery). Run Paperclip in plain words instead of clicking through the dashboard: catch up in the morning, hand out issues, wake an agent and follow its run, answer approvals, set budgets and get reports. Each prompt shows the access level it needs and the tools it uses. You can search and filter by category or level.
+- **Docs fixes:** the setup guide now uses Paperclip's real setting names and the current health check fields. Troubleshooting covers "hostname not allowed", connections that stop after Paperclip's 30-day key expiry (reconnect to fix), and agents stopping on restarts. The FAQ explains how Papercliped relates to Paperclip's new built-in MCP endpoint. Numbered steps with code blocks, and quotes, now render properly in the docs.
+
 ## v2.2.1 — the Papercliped plugin now installs in Paperclip
 
 - **Fixed: the Papercliped plugin could not be installed in Paperclip.** Paperclip rejected it with a bare "400" because the sidebar entry declared a page route, which Paperclip only allows on pages. Installing it, automatically while connecting or by hand from Settings → Plugins, now works. The plugin’s tests now run Paperclip’s own manifest check so this can’t come back. If you ticked the box while connecting on 2.2.0, nothing was installed: connect again, or install it from Settings → Plugins.

package/README.md

@@ -12,7 +12,7 @@ Free and open source. Website: [papercliped.co](https://papercliped.co) · Docs:
 
 ## Add it to your AI app
 
-You need a Paperclip with a public `https` address ([no domain? see this](https://docs.papercliped.co/connect-your-paperclip)). The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
+You need a Paperclip with a public `https` address. Don't have one yet? [Host your Paperclip](https://docs.papercliped.co/hosting) has step-by-step guides for your own computer (free tunnel), a VPS, Railway, Render, Fly.io and Coolify. The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
 
 The connector address for every app is:
 
@@ -80,15 +80,19 @@ Add `--env PAPERCLIP_READ_ONLY=1` for reports and sync only.
 
 ## What you can ask
 
-- "What are my agents working on?" · "Which agents are over budget?"
-- "Pause the Web Engineer." · "Wake the CEO and assign it the onboarding issue."
-- "Approve the hire request." · "Weekly cost report, please."
+Talk to your AI app instead of clicking through the dashboard:
+
+- "Catch me up on my Paperclip." · "Which agents are over budget?"
+- "Give the Web Engineer an issue to fix the signup page, and wake them." · "Wake the CEO, wait until they finish, then summarise."
+- "Approve the hire request." · "Weekly report, please."
+
+More than 40 ready-to-copy prompts: [prompt gallery](https://papercliped.co/prompts).
 
 There are 30 tools ([full list](https://docs.papercliped.co/tools)). **Read only** can look at agents, issues, goals, costs and reports. **Full control** can use every tool. The AI asks before anything that can't be undone, and you can change the level or disconnect at any time.
 
 ## Manage your connections in Paperclip
 
-Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a Papercliped page where you see every connected app, switch its level, disconnect it, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin).
+Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a **control room**: see every connected app, choose which tools each may use and which agents it applies to, set **API only / Full / Agent only** for every agent or one at a time (or turn an agent off), read what was blocked, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin) · [The control room](https://docs.papercliped.co/control-room) · [API only, Full or Agent only](https://docs.papercliped.co/access-modes).
 
 ## Security and privacy
 

package/dist/access/guard.js

@@ -0,0 +1,17 @@
+import { redactAgents } from "./policy.js";
+/**
+ * A view of the user's Paperclip in which some agents do not exist. Every response is stripped of those agents before a tool
+ * sees it, so reports, lists and syncs are all consistent: a report built from this client cannot name a hidden agent,
+ * because it never received one. Anything the server already summed (totals) is left as it is.
+ */
+export function guardClient(client, hidden) {
+    if (hidden.size === 0)
+        return client;
+    const g = Object.create(client);
+    const request = async (...args) => redactAgents(await client.request(...args), hidden);
+    g.request = request;
+    g.get = ((path, query) => request("GET", path, { query }));
+    g.post = ((path, body) => request("POST", path, { body: body ?? {} }));
+    g.patch = ((path, body) => request("PATCH", path, { body }));
+    return g;
+}

package/dist/access/policy.js

@@ -0,0 +1,203 @@
+export const MODES = ["api", "full", "agent"];
+export const isMode = (v) => typeof v === "string" && MODES.includes(v);
+export const isAgentMode = (v) => v === "off" || isMode(v);
+export const DEFAULT_ACCOUNT_POLICY = { mode: "full", agents: {} };
+export const DEFAULT_SESSION_POLICY = { label: null, tools: null, agents: null };
+/** Hands work to an agent. Everything else that changes something is direct control of Paperclip. */
+const AGENT_WORK = new Set(["paperclip_create_issue", "paperclip_update_issue", "paperclip_comment_issue", "paperclip_wake_agent"]);
+/** Which surface a call is on. The raw API tool is read for GET and direct control for anything else. */
+export function surfaceOf(tool, input = {}) {
+    if (tool.name === "paperclip_api_request")
+        return input.method === "GET" ? "read" : "api";
+    if (tool.access === "read")
+        return "read";
+    return AGENT_WORK.has(tool.name) ? "agent" : "api";
+}
+/** The surface a tool is on when called in its usual way (what the control room shows). */
+export const surfaceOfTool = (tool) => surfaceOf(tool, {});
+export const surfaceAllowed = (mode, surface) => surface === "read" || mode === "full" || (mode === "api" && surface === "api") || (mode === "agent" && surface === "agent");
+export const MODE_LABEL = { api: "API only", full: "Full", agent: "Agent only", off: "Off" };
+// ───────────── validation of what the manage API receives ─────────────
+export class PolicyInputError extends Error {
+}
+const ID = /^[A-Za-z0-9._:-]{1,80}$/;
+const MAX_AGENTS = 500;
+/** A strict, bounded copy of untrusted input. Unknown keys are dropped; anything invalid is refused. */
+export function parseAccountPolicy(raw) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    const mode = o.mode === undefined ? DEFAULT_ACCOUNT_POLICY.mode : o.mode;
+    if (!isMode(mode))
+        throw new PolicyInputError("mode must be api, full or agent");
+    const agents = {};
+    const src = o.agents === undefined ? {} : o.agents;
+    if (!src || typeof src !== "object" || Array.isArray(src))
+        throw new PolicyInputError("agents must be an object of agent id to mode");
+    const entries = Object.entries(src);
+    if (entries.length > MAX_AGENTS)
+        throw new PolicyInputError(`at most ${MAX_AGENTS} agents`);
+    for (const [id, m] of entries) {
+        if (!ID.test(id))
+            throw new PolicyInputError("invalid agent id");
+        if (!isAgentMode(m))
+            throw new PolicyInputError("an agent's mode must be api, full, agent or off");
+        if (m !== mode)
+            agents[id] = m; // an override equal to the default is no override
+    }
+    return { mode, agents };
+}
+export function parseSessionPolicy(raw, knownTools) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    let label = null;
+    if (o.label !== undefined && o.label !== null) {
+        if (typeof o.label !== "string")
+            throw new PolicyInputError("label must be text");
+        label = o.label.replace(/\s+/g, " ").trim().slice(0, 60) || null;
+    }
+    const list = (v, what, ok) => {
+        if (v === undefined || v === null)
+            return null;
+        if (!Array.isArray(v))
+            throw new PolicyInputError(`${what} must be a list, or null for all`);
+        if (v.length > MAX_AGENTS)
+            throw new PolicyInputError(`too many ${what}`);
+        const out = [...new Set(v.map(String))];
+        if (!out.every(ok))
+            throw new PolicyInputError(`invalid entry in ${what}`);
+        return out;
+    };
+    const tools = list(o.tools, "tools", (s) => knownTools.has(s));
+    const agents = list(o.agents, "agents", (s) => ID.test(s));
+    if (tools && tools.length === 0)
+        throw new PolicyInputError("choose at least one tool, or allow all");
+    if (agents && agents.length === 0)
+        throw new PolicyInputError("choose at least one agent, or apply to everyone");
+    return { label, tools, agents };
+}
+/** Stored JSON back to a policy, tolerating older or damaged rows by falling back to the safe default. */
+export function readAccountPolicy(stored) {
+    try {
+        return parseAccountPolicy(typeof stored === "string" ? JSON.parse(stored) : stored);
+    }
+    catch {
+        return { ...DEFAULT_ACCOUNT_POLICY, agents: {} };
+    }
+}
+export function readSessionPolicy(stored, knownTools) {
+    if (stored === null || stored === undefined)
+        return { ...DEFAULT_SESSION_POLICY };
+    try {
+        return parseSessionPolicy(typeof stored === "string" ? JSON.parse(stored) : stored, knownTools);
+    }
+    catch {
+        return { ...DEFAULT_SESSION_POLICY };
+    }
+}
+const CONTROL_ROOM = "Change it in the Papercliped page inside Paperclip.";
+/** Agent ids a call names, wherever the tool takes them (a target, an assignee, an owner, or a filter). */
+export function targetsOf(input) {
+    const ids = [input.agentId, input.assigneeAgentId, input.ownerAgentId].filter((v) => typeof v === "string" && v.trim().length > 0);
+    return [...new Set(ids.map((s) => s.trim()))];
+}
+/** Tools that act on an issue, whose agent is whoever it is assigned to (not named in the call). */
+const BY_ISSUE = new Set(["paperclip_get_issue", "paperclip_update_issue", "paperclip_comment_issue"]);
+/** Tools a session limited to selected agents may still use without naming an agent. */
+const OPEN_TO_LIMITED = new Set(["papercliped_service_status", "paperclip_list_companies", "paperclip_list_agents"]);
+/** Does this call need the issue's current assignee looked up before it can be judged? */
+export function needsIssueAgent(p, tool) {
+    return BY_ISSUE.has(tool.name) && (p.session.agents !== null || Object.keys(p.account.agents).length > 0);
+}
+/** Agents Papercliped may not touch at all: hidden from every result, refused as a target. */
+export const hiddenAgents = (a) => Object.entries(a.agents).filter(([, m]) => m === "off").map(([id]) => id);
+/**
+ * Decide one call. `issueAgent` is the assignee of the issue the call names (null = unassigned, undefined = not looked up).
+ * Returns null when the call may go ahead, or why not.
+ */
+export function evaluate(p, tool, input, issueAgent) {
+    const { account, session } = p;
+    const label = tool.title || tool.name;
+    if (session.tools && !session.tools.includes(tool.name)) {
+        return { code: "tool_not_allowed", message: `This session isn't allowed to use "${label}". ${CONTROL_ROOM}` };
+    }
+    const surface = surfaceOf(tool, input);
+    const targets = targetsOf(input);
+    if (typeof issueAgent === "string")
+        targets.push(issueAgent);
+    for (const a of new Set(targets)) {
+        const eff = account.agents[a] ?? account.mode;
+        if (eff === "off")
+            return { code: "agent_off", message: `Papercliped isn't allowed to use that agent. ${CONTROL_ROOM}` };
+        if (!surfaceAllowed(eff, surface))
+            return { code: "mode_blocks", message: `That agent is set to "${MODE_LABEL[eff]}", which doesn't allow "${label}". ${CONTROL_ROOM}` };
+        if (session.agents && !session.agents.includes(a))
+            return { code: "agent_not_in_session", message: `This session only applies to selected agents, and that one isn't included. ${CONTROL_ROOM}` };
+    }
+    if (targets.length === 0 && !surfaceAllowed(account.mode, surface)) {
+        return { code: "mode_blocks", message: `Papercliped is set to "${MODE_LABEL[account.mode]}", which doesn't allow "${label}". ${CONTROL_ROOM}` };
+    }
+    if (session.agents && targets.length === 0 && !OPEN_TO_LIMITED.has(tool.name)) {
+        const why = BY_ISSUE.has(tool.name) || tool.name === "paperclip_create_issue" ? "needs an issue assigned to one of its agents" : "looks across every agent";
+        return { code: "needs_all_agents", message: `This session only applies to selected agents, and "${label}" ${why}. ${CONTROL_ROOM}` };
+    }
+    return null;
+}
+/** For a session limited to selected agents: the agent list shows only those. */
+export function narrowAgentList(result, allowed) {
+    const keep = (x) => !!x && typeof x === "object" && allowed.includes(String(x.id));
+    if (Array.isArray(result))
+        return result.filter(keep);
+    if (result && typeof result === "object" && Array.isArray(result.agents)) {
+        return { ...result, agents: result.agents.filter(keep) };
+    }
+    return result;
+}
+const AGENT_REFS = ["id", "agentId", "assigneeAgentId", "ownerAgentId", "executorAgentId", "createdByAgentId"];
+/**
+ * Remove every record that belongs to one of the hidden agents, wherever it appears in a response: list items, nested
+ * rows, and keys named by agent id. Totals the server already summed are left as they are.
+ */
+export function redactAgents(value, hidden) {
+    if (hidden.size === 0)
+        return value;
+    const belongs = (x) => {
+        if (!x || typeof x !== "object")
+            return false;
+        const o = x;
+        return AGENT_REFS.some((k) => typeof o[k] === "string" && hidden.has(o[k]));
+    };
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.filter((x) => !belongs(x)).map(walk);
+        if (v && typeof v === "object") {
+            const out = {};
+            for (const [k, x] of Object.entries(v)) {
+                if (hidden.has(k) || belongs(x))
+                    continue;
+                out[k] = walk(x);
+            }
+            return out;
+        }
+        return v;
+    };
+    return walk(value);
+}
+const takesAgent = (tool) => {
+    const shape = tool.schema.shape ?? {};
+    return "agentId" in shape || "assigneeAgentId" in shape || "ownerAgentId" in shape;
+};
+/**
+ * Could this tool ever run for this session? A tool that can never run is not advertised to the AI, so it doesn't try it.
+ * (Whether a particular call may run is `evaluate`'s answer.)
+ */
+export function canEverRun(p, tool) {
+    if (p.session.tools && !p.session.tools.includes(tool.name))
+        return false;
+    if (tool.name !== "paperclip_api_request") {
+        const surface = surfaceOfTool(tool);
+        const modes = [p.account.mode, ...Object.values(p.account.agents).filter((m) => m !== "off")];
+        if (!modes.some((m) => surfaceAllowed(m, surface)))
+            return false;
+    }
+    if (p.session.agents)
+        return OPEN_TO_LIMITED.has(tool.name) || BY_ISSUE.has(tool.name) || tool.name === "paperclip_create_issue" || takesAgent(tool);
+    return true;
+}

package/dist/execute.js

@@ -1,3 +1,5 @@
+import { guardClient } from "./access/guard.js";
+import { evaluate, hiddenAgents, narrowAgentList, needsIssueAgent } from "./access/policy.js";
 import { PaperclipApiError } from "./client.js";
 import { ToolInputError } from "./errors.js";
 import { requiredScope, scopeAllows } from "./oauth/scopes.js";
@@ -53,8 +55,30 @@ export async function executeTool(client, name, rawInput, opts = {}) {
     if (client.config.readOnly && mutation) {
         return done({ ok: false, status: 403, error: "Bridge is in read-only mode (PAPERCLIP_READ_ONLY); this action was not sent to Paperclip." }, "read_only");
     }
+    let runWith = client;
+    const policy = opts.policy;
+    if (policy) {
+        // An issue's agent is whoever it is assigned to; look it up once, only when the answer can change the decision.
+        let issueAgent;
+        if (needsIssueAgent(policy, tool) && typeof parsed.data.issueId === "string") {
+            try {
+                const issue = await client.get(`/issues/${encodeURIComponent(parsed.data.issueId)}`);
+                issueAgent = typeof issue?.assigneeAgentId === "string" ? issue.assigneeAgentId : null;
+            }
+            catch {
+                issueAgent = undefined; // can't tell: a session limited to selected agents is refused below, anything else lets the tool report the real error
+            }
+        }
+        const denial = evaluate(policy, tool, parsed.data, issueAgent);
+        if (denial)
+            return done({ ok: false, status: 403, error: { message: denial.message, policy: denial.code } }, "policy_blocked");
+        runWith = guardClient(client, new Set(hiddenAgents(policy.account)));
+    }
     try {
-        return done({ ok: true, result: await runTimed(timer, () => tool.run(client, parsed.data)) });
+        let result = await runTimed(timer, () => tool.run(runWith, parsed.data));
+        if (policy?.session.agents && tool.name === "paperclip_list_agents")
+            result = narrowAgentList(result, policy.session.agents);
+        return done({ ok: true, result });
     }
     catch (err) {
         if (err instanceof ToolInputError)

package/dist/manage/routes.js

@@ -1,3 +1,4 @@
+import { PolicyInputError } from "../access/policy.js";
 import { displayName } from "../accounts/alias.js";
 const HEADERS = { "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer" };
 /** A DNS name or IPv4 literal, optionally with a port; undefined when it is anything else. */
@@ -92,8 +93,51 @@ export class ManageRoutes {
             const link = await this.p.manageInstanceLabel(a.id);
             return this.json(res, 200, { name: displayName(a), anonymous: !!a.anonymous, alias: a.alias ?? null, paperclip: link.label, connected: link.connected, createdAt: a.createdAt });
         }
-        if (m === "GET" && route === "/connections")
-            return this.json(res, 200, { connections: await this.p.manageConnections(a.id) });
+        if (m === "GET" && (route === "/connections" || route === "/sessions")) {
+            const list = await this.p.manageConnections(a.id);
+            return this.json(res, 200, route === "/sessions" ? { sessions: list } : { connections: list });
+        }
+        // The control room: the access switch, per-session limits, the tool list and recent calls.
+        if (route === "/policy" && (m === "GET" || m === "POST" || m === "PUT")) {
+            if (m === "GET")
+                return this.json(res, 200, await this.p.manageGetPolicy(a));
+            const b = await this.body(req);
+            if (!b)
+                return this.json(res, 400, { error: "Send JSON" });
+            try {
+                return this.json(res, 200, await this.p.manageSetPolicy(a, b));
+            }
+            catch (e) {
+                return e instanceof PolicyInputError ? this.json(res, 400, { error: e.message }) : this.json(res, 500, { error: "Could not save the access settings" });
+            }
+        }
+        if (m === "GET" && route === "/tools")
+            return this.json(res, 200, { tools: this.p.manageTools() });
+        if (m === "GET" && route === "/activity") {
+            const session = url.searchParams.get("session") ?? undefined;
+            if (session !== undefined && !/^[A-Za-z0-9_-]{1,80}$/.test(session))
+                return this.json(res, 400, { error: "Invalid session" });
+            const limit = Number.parseInt(url.searchParams.get("limit") ?? "50", 10);
+            return this.json(res, 200, { calls: await this.p.manageActivity(a, { session, limit: Number.isFinite(limit) ? limit : 50 }) });
+        }
+        const sess = /^\/sessions\/([A-Za-z0-9_-]{1,80})$/.exec(route);
+        if (sess && m === "POST") {
+            const b = await this.body(req);
+            if (!b)
+                return this.json(res, 400, { error: "Send JSON" });
+            const level = b.level === undefined ? undefined : b.level === "read" ? "paperclip:read" : b.level === "control" ? "paperclip:control" : null;
+            if (level === null)
+                return this.json(res, 400, { error: "level must be read or control" });
+            try {
+                const next = await this.p.manageSetSession(a, sess[1], { label: b.label, tools: b.tools, agents: b.agents, level });
+                return next ? this.json(res, 200, next) : this.json(res, 404, { error: "No such session" });
+            }
+            catch (e) {
+                return e instanceof PolicyInputError ? this.json(res, 400, { error: e.message }) : this.json(res, 500, { error: "Could not save the session" });
+            }
+        }
+        if (sess && m === "DELETE")
+            return (await this.p.manageRevoke(a, sess[1])) ? this.json(res, 200, { ok: true }) : this.json(res, 404, { error: "No such session" });
         const c = /^\/connections\/([A-Za-z0-9_-]{1,80})$/.exec(route);
         if (c && m === "POST") {
             const b = await this.body(req);

package/dist/mcp.js

@@ -2,19 +2,20 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PaperclipClient } from "./client.js";
 import { readConfig } from "./config.js";
 import { executeTool, renderForModel } from "./execute.js";
+import { canEverRun } from "./access/policy.js";
 import { requiredScope, scopeAllows } from "./oauth/scopes.js";
 import { tools } from "./tools.js";
 export { VERSION as SERVER_VERSION } from "./version.js";
 import { VERSION } from "./version.js";
 /** Tools above the caller's scope are not advertised (they would only fail). The raw API tool stays: its GETs need only read. */
-export function visibleTools(scopes) {
-    if (!scopes)
-        return tools;
-    return tools.filter((t) => t.name === "paperclip_api_request" || scopeAllows(scopes, requiredScope(t)));
+export function visibleTools(scopes, policy) {
+    const byScope = !scopes ? tools : tools.filter((t) => t.name === "paperclip_api_request" || scopeAllows(scopes, requiredScope(t)));
+    // Tools the session or the account switch can never allow are not advertised either.
+    return policy ? byScope.filter((t) => canEverRun(policy, t)) : byScope;
 }
 export function createMcpServer(config = readConfig(), client = new PaperclipClient(config), exec = {}) {
     const server = new McpServer({ name: "papercliped", version: VERSION });
-    for (const tool of visibleTools(exec.scopes)) {
+    for (const tool of visibleTools(exec.scopes, exec.policy)) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,

package/dist/oauth/pg-store.js

@@ -28,6 +28,7 @@ const toGrant = (r) => ({
     createdAt: num(r.created_at),
     lastUsedAt: num(r.last_used_at),
     revoked: r.revoked,
+    policy: r.policy ?? null,
 });
 /**
  * Postgres-backed Store (schema `bridge`, see migrations/001_init.sql). Safe to share between several bridge
@@ -174,7 +175,7 @@ export class PgStore {
     }
     // ───────────── accounts ─────────────
     static toAccount(x) {
-        return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta };
+        return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta, policy: x.policy ?? null };
     }
     static toLink(x) {
         return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
@@ -199,6 +200,17 @@ export class PgStore {
     async setGrantScopes(id, scopes) {
         return ((await this.q("update bridge.grants set scopes = $2 where id = $1 and not revoked", [id, scopes])).rowCount ?? 0) === 1;
     }
+    async setGrantPolicy(id, policy) {
+        return ((await this.q("update bridge.grants set policy = $2 where id = $1 and not revoked", [id, policy === null ? null : JSON.stringify(policy)])).rowCount ?? 0) === 1;
+    }
+    async setAccountPolicy(id, policy) {
+        return ((await this.q("update bridge.accounts set policy = $2 where id = $1", [id, JSON.stringify(policy)])).rowCount ?? 0) === 1;
+    }
+    async recentCallsForGrants(grantIds, limit) {
+        if (grantIds.length === 0)
+            return [];
+        return (await this.q("select * from bridge.audit_events where kind = 'tool' and grant_id = any($1) order by id desc limit $2", [[...grantIds], limit])).rows.map(PgStore.toRow);
+    }
     async setAccountPrivacy(id, c) {
         const cl = await this.pool.connect();
         try {

package/dist/oauth/provider.js

@@ -8,6 +8,8 @@ import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-f
 import { Keyring, isValidCodeChallenge, randomToken, safeEqual, sha256Hex, verifyPkce } from "./crypto.js";
 import { approvePage, choosePage, consentPage, errorPage, instancePage, scopePage, secretPage, usernamePage, welcomePage } from "./pages.js";
 import { LoginError, PaperclipLogin } from "./paperclip-login.js";
+import { parseAccountPolicy, parseSessionPolicy, readAccountPolicy, readSessionPolicy, surfaceOfTool } from "../access/policy.js";
+import { tools as ALL_TOOLS } from "../tools.js";
 import { VERSION } from "../version.js";
 import { MemoryStore } from "./store.js";
 import { SCOPES, grantableScopes, isScope, maxRank, normalizeScope, normalizeScopes, scopeAllows, scopesUpTo } from "./scopes.js";
@@ -16,6 +18,8 @@ const PENDING_TTL_MS = 10 * 60_000;
 const CODE_TTL_MS = 60_000;
 const MAX_PENDING = 5000;
 const MAX_INSTANCE_ATTEMPTS = 5;
+/** Every tool name, for checking a session's tool list. */
+const KNOWN_TOOLS = new Set(ALL_TOOLS.map((t) => t.name));
 /** The plugin offered on the instance step: one fixed package, pinned to this bridge's own version (both are released together). */
 const PLUGIN_PACKAGE = "papercliped-paperclip-plugin";
 /** Its id inside Paperclip (the manifest id), used to see whether it is already installed. */
@@ -305,7 +309,52 @@ export class OAuthProvider {
     async manageConnections(accountId) {
         return (await this.store.listAccountGrants(accountId))
             .filter((g) => !g.revoked && g.clientId !== "paperclip-plugin")
-            .map((g) => ({ id: g.id, app: g.clientName, level: levelOf(g.scopes), createdAt: g.createdAt, lastUsedAt: g.lastUsedAt }));
+            .map((g) => {
+            const p = readSessionPolicy(g.policy, KNOWN_TOOLS);
+            return { id: g.id, app: g.clientName, label: p.label, level: levelOf(g.scopes), tools: p.tools, agents: p.agents, createdAt: g.createdAt, lastUsedAt: g.lastUsedAt };
+        });
+    }
+    /** What the policy engine checks on every call for this grant: the account's switch plus this session's limits. */
+    async policyFor(grant) {
+        const account = grant.accountId ? await this.store.getAccount(grant.accountId) : undefined;
+        return { account: readAccountPolicy(account?.policy), session: readSessionPolicy(grant.policy, KNOWN_TOOLS) };
+    }
+    async manageGetPolicy(a) {
+        return readAccountPolicy((await this.store.getAccount(a.id))?.policy);
+    }
+    /** Replace the access switch and per-agent overrides. Throws PolicyInputError on anything invalid. Takes effect on the next call. */
+    async manageSetPolicy(a, raw) {
+        const next = parseAccountPolicy(raw);
+        if (!(await this.store.setAccountPolicy(a.id, next)))
+            throw new Error("No such account");
+        await this.event("updated", { accountId: a.id, username: displayName(a) }, `mode_${next.mode}`);
+        return next;
+    }
+    /** Change one session: its name, tools, agents and (optionally) its access level. False if it isn't this account's live session. */
+    async manageSetSession(a, grantId, change) {
+        const g = await this.store.getGrant(grantId);
+        if (!g || g.revoked || g.accountId !== a.id || g.clientId === "paperclip-plugin")
+            return null;
+        const before = readSessionPolicy(g.policy, KNOWN_TOOLS);
+        const next = parseSessionPolicy({ label: change.label === undefined ? before.label : change.label, tools: change.tools === undefined ? before.tools : change.tools, agents: change.agents === undefined ? before.agents : change.agents }, KNOWN_TOOLS);
+        if (!(await this.store.setGrantPolicy(g.id, next)))
+            return null;
+        if (change.level)
+            await this.store.setGrantScopes(g.id, scopesUpTo(change.level));
+        await this.event("updated", { accountId: a.id, username: displayName(a) }, "session_limits");
+        return next;
+    }
+    /** The tools, as the control room lists them: what each does and which surface it is on. */
+    manageTools() {
+        return ALL_TOOLS.map((t) => ({ name: t.name, title: t.title, description: t.description.slice(0, 240), access: t.access, surface: surfaceOfTool(t) }));
+    }
+    /** The newest tool calls through this account's sessions (names and outcomes only; never arguments or results). */
+    async manageActivity(a, opts) {
+        const grants = (await this.store.listAccountGrants(a.id)).filter((g) => g.clientId !== "paperclip-plugin");
+        const ids = opts.session ? grants.filter((g) => g.id === opts.session).map((g) => g.id) : grants.map((g) => g.id);
+        const byId = new Map(grants.map((g) => [g.id, readSessionPolicy(g.policy, KNOWN_TOOLS).label ?? g.clientName]));
+        const rows = await this.store.recentCallsForGrants(ids, Math.min(Math.max(1, opts.limit), 200));
+        return rows.map((r) => ({ at: r.at, tool: r.name, ok: r.ok, blocked: r.errorClass === "policy_blocked", status: r.status, error: r.errorClass, ms: r.totalMs, session: r.grantId, app: (r.grantId && byId.get(r.grantId)) || r.client }));
     }
     /** Change what a connected app may do: Read only or Full control. */
     async manageSetLevel(a, grantId, level) {

package/dist/oauth/store.js

@@ -239,6 +239,26 @@ export class MemoryStore {
         this.save();
         return true;
     }
+    async setGrantPolicy(id, policy) {
+        const g = this.d.grants[id];
+        if (!g || g.revoked)
+            return false;
+        g.policy = policy ? { ...policy, tools: policy.tools && [...policy.tools], agents: policy.agents && [...policy.agents] } : null;
+        this.save();
+        return true;
+    }
+    async setAccountPolicy(id, policy) {
+        const a = this.accts[id];
+        if (!a)
+            return false;
+        a.policy = { mode: policy.mode, agents: { ...policy.agents } };
+        this.save();
+        return true;
+    }
+    async recentCallsForGrants(grantIds, limit) {
+        const ids = new Set(grantIds);
+        return this.audit.filter((r) => r.kind === "tool" && r.grantId !== null && ids.has(r.grantId)).slice(-limit).reverse();
+    }
     async setAccountPrivacy(id, c) {
         const a = this.accts[id];
         if (!a)

package/dist/public-api/types.js

@@ -11,4 +11,4 @@ export const PUBLIC_WINDOWS = ["1h", "24h", "7d"];
 /** Why a sign-in or connect flow failed. Anything the bridge records outside this list is counted as `other`. */
 export const AUTH_FAILURE_REASONS = ["bad_credentials", "rate_limited", "denied", "expired", "unreachable", "invalid_instance", "too_many_attempts", "other"];
 /** Error classes of tool calls and protocol requests. Anything else is counted as `other`. */
-export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "internal", "other"];
+export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "policy_blocked", "internal", "other"];

package/dist/server.js

@@ -74,11 +74,11 @@ export function createHttpServer(config, http, opts = {}) {
         catch {
             return null; // unreadable credential, expired connection, or instance no longer allowed: an invalid token (the user reconnects)
         }
-        return { kind: "oauth", grantId: grant.id, client: grant.clientName, userId: grant.userId, username: grant.username ?? undefined, instance, scopes: grant.scopes, paperclip };
+        return { kind: "oauth", grantId: grant.id, client: grant.clientName, userId: grant.userId, username: grant.username ?? undefined, instance, scopes: grant.scopes, paperclip, policy: await oauth.policyFor(grant) };
     }
     const execFor = (p) => p.kind === "static"
         ? { client: baseClient, exec: { actor: { id: "static-token" }, audit } }
-        : { client: p.paperclip, exec: { scopes: p.scopes, actor: { id: p.grantId, client: p.client, userId: p.userId, instance: p.instance, username: p.username }, audit } };
+        : { client: p.paperclip, exec: { scopes: p.scopes, policy: p.policy, actor: { id: p.grantId, client: p.client, userId: p.userId, instance: p.instance, username: p.username }, audit } };
     const unauthorized = (res, invalid) => {
         const challenge = oauth ? oauth.challengeHeader(invalid ? "invalid_token" : undefined) : "Bearer";
         json(res, 401, { error: invalid ? "Invalid or expired token" : "Missing or invalid bearer token" }, { "WWW-Authenticate": challenge });

package/dist/site/markdown.js

@@ -55,21 +55,42 @@ export function renderMarkdown(md) {
             out.push(`<div class="tw"><table><thead><tr>${head.map((c) => `<th>${inline(c)}</th>`).join("")}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`);
             continue;
         }
+        if (/^>/.test(line)) {
+            const buf = [];
+            while (i < lines.length && /^>/.test(lines[i]))
+                buf.push(lines[i++].replace(/^>\s?/, ""));
+            out.push(`<blockquote>${renderMarkdown(buf.join("\n"))}</blockquote>`);
+            continue;
+        }
         const ul = /^[-*]\s+/.test(line), ol = /^\d+\.\s+/.test(line);
         if (ul || ol) {
             const items = [];
             const re = ul ? /^[-*]\s+(.*)$/ : /^\d+\.\s+(.*)$/;
             while (i < lines.length && re.test(lines[i])) {
-                let t = re.exec(lines[i++])[1];
-                while (i < lines.length && /^\s+\S/.test(lines[i]) && !re.test(lines[i]))
-                    t += " " + lines[i++].trim();
-                items.push(`<li>${inline(t)}</li>`);
+                const body = [re.exec(lines[i++])[1]];
+                // An item continues on indented lines, including fenced code and blank lines followed by more indented content.
+                while (i < lines.length && !re.test(lines[i])) {
+                    if (/^\s+\S/.test(lines[i]))
+                        body.push(lines[i++]);
+                    else if (!lines[i].trim() && /^\s+\S/.test(lines[i + 1] ?? "") && !re.test(lines[i + 1] ?? ""))
+                        body.push(lines[i++]);
+                    else
+                        break;
+                }
+                const rich = body.some((l) => /^\s*```/.test(l) || !l.trim());
+                if (!rich)
+                    items.push(`<li>${inline(body.map((l) => l.trim()).join(" "))}</li>`);
+                else {
+                    const rest = body.slice(1);
+                    const pad = Math.min(...rest.filter((l) => l.trim()).map((l) => /^\s*/.exec(l)[0].length));
+                    items.push(`<li>${renderMarkdown([body[0], ...rest.map((l) => l.slice(Math.min(pad, /^\s*/.exec(l)[0].length)))].join("\n"))}</li>`);
+                }
             }
             out.push(ul ? `<ul>${items.join("")}</ul>` : `<ol>${items.join("")}</ol>`);
             continue;
         }
         const para = [];
-        while (i < lines.length && lines[i].trim() && !/^(#{1,3}\s|```|[-*]\s|\d+\.\s)/.test(lines[i]) && !/^\|.*\|\s*$/.test(lines[i]))
+        while (i < lines.length && lines[i].trim() && !/^(#{1,3}\s|```|[-*]\s|\d+\.\s|>)/.test(lines[i]) && !/^\|.*\|\s*$/.test(lines[i]))
             para.push(lines[i++].trim());
         out.push(`<p>${inline(para.join(" "))}</p>`);
     }