privateer-agent 0.12.16 → 0.12.17

package/extensions/privateer-gate.ts

@@ -22,6 +22,7 @@ import {
 import { RelayClient } from "../src/remote/relayClient.ts";
 import { makeSendFileTool } from "../src/tools/sendFile.ts";
 import { makeSaveCargoTool } from "../src/tools/cargo.ts";
+import { makeChartTools } from "../src/tools/charts.ts";
 import { makeSaveAttachmentTool } from "../src/tools/saveAttachment.ts";
 import { AttachmentStore, type StoredAttachment } from "../src/util/attachmentStore.ts";
 import { makeExtensionsControl } from "../src/remote/extensionsControl.ts";
@@ -480,6 +481,12 @@ export default function privateerControl(pi: any): void {
   // relay isn't this file's. Unlike the pair it hands the app PLAINTEXT to encrypt —
   // the terminal has no master key, so the round trip is the feature (cargoSave.ts).
   pi.registerTool?.(makeSaveCargoTool(bridge));
+  // The chart tools, for the same reasons and one more. Same: this bridge, the same
+  // "needs a connected app" precondition, the same plaintext-out/app-encrypts round trip
+  // (chartOps.ts). More: they also READ the user's stored content back, so registering
+  // them anywhere the relay isn't this file's would mean a session asking for decrypted
+  // charts over a relay nobody is driving.
+  for (const tool of makeChartTools(bridge)) pi.registerTool?.(tool);
 
   // Subagents (and print/rpc) run as headless child `pi` processes with no UI. There
   // no one can approve, so a "default" gate would fail-closed on every tool and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.16",
+  "version": "0.12.17",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/src/config/moat.ts

@@ -35,6 +35,7 @@ import { managedNames } from "./moatManifest.ts";
 import type { GateController } from "../ext/permissionGate.ts";
 import type { SendFileBridge } from "../tools/sendFile.ts";
 import type { CargoSaveBridge } from "../tools/cargo.ts";
+import type { ChartOpBridge } from "../tools/charts.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
 /** A Pi extension factory, as DefaultResourceLoader takes them. */
@@ -62,7 +63,7 @@ export interface MoatOptions {
    * its module-level bridge and stands them down inside the daemon, so a live spawn's own
    * pair is what the model gets (see tools/relayFileTools.ts).
    */
-  relayFiles?: { bridge: SendFileBridge & CargoSaveBridge; attachments: AttachmentStore };
+  relayFiles?: { bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge; attachments: AttachmentStore };
   /**
    * THIS run's inbox-attachment staging area (routines/resultMedia.ts). Passed only by
    * a path whose result reaches the app's Inbox — a scheduled routine, a submitted

package/src/permissions/classify.ts

@@ -289,6 +289,63 @@ export function classifyToolCall(
   // — the same disclosure the media tools flag on their inputs, and the reason `outside`
   // has to be set here: it forces a prompt even under acceptEdits, which would otherwise
   // swallow the call as an ordinary in-scope write.
+  // The chart tools (src/tools/charts.ts) — read and write the boards in the user's app.
+  //
+  // Split by direction, because they are not the same act. list_charts and read_chart are
+  // READS, and left to the unknown-tool branch they'd be bash-kind prompts denied outright
+  // in plan/readonly — wrong twice over: they touch nothing on this machine, and "look at
+  // what's already on my board" is exactly the kind of thing a plan-mode turn wants.
+  //
+  // read_chart is still worth naming precisely in the prompt rather than folding in with
+  // the listing. It returns DECRYPTED content out of the user's account — the only tool
+  // here that does — and the detail line says which chart, so an approval is a decision
+  // about a specific board rather than a blanket yes to reading their charts.
+  //
+  // create_chart and edit_chart are WRITES for the same reason save_cargo is: a new,
+  // persistent thing in the user's account against their quota. Not alwaysAsk — no credit
+  // is spent and the destination is the user's own device, encrypted there before storage,
+  // so there is no third party and nothing irreversible. `outside` is deliberately NOT set:
+  // unlike save_cargo there is no source file, so there is no out-of-scope disclosure to
+  // flag. A delete_node step is the one thing here that destroys something the user made,
+  // so it is surfaced in the title rather than buried in the op list.
+  if (name === "list_charts") {
+    return { tool: toolName, kind: "read", title: "List charts in the Privateer app", detail: "titles and card counts" };
+  }
+  if (name === "read_chart") {
+    const chartId = str(obj.chartId);
+    return {
+      tool: toolName,
+      kind: "read",
+      title: "Read a chart from the Privateer app",
+      detail: chartId ? `chart ${chartId} — the app decrypts its cards on the device` : "a chart's cards",
+    };
+  }
+  if (name === "create_chart") {
+    const nodes = Array.isArray(obj.nodes) ? obj.nodes.length : 0;
+    const titleNote = str(obj.title) ? ` "${str(obj.title)}"` : "";
+    return {
+      tool: toolName,
+      kind: "write",
+      title: "Create a chart in the Privateer app",
+      detail: `${nodes} card${nodes === 1 ? "" : "s"}${titleNote} → the app encrypts them and stores them in Charts`,
+    };
+  }
+  if (name === "edit_chart") {
+    const ops = Array.isArray(obj.ops) ? (obj.ops as Array<Record<string, unknown>>) : [];
+    const deletes = ops.filter((o) => o?.edit === "delete_node").length;
+    const chartId = str(obj.chartId);
+    const kinds = [...new Set(ops.map((o) => str(o?.edit)).filter(Boolean))].join(", ");
+    return {
+      tool: toolName,
+      kind: "write",
+      title: deletes ? "Edit a chart in the Privateer app (deletes cards)" : "Edit a chart in the Privateer app",
+      detail:
+        `${ops.length} step${ops.length === 1 ? "" : "s"}${kinds ? ` (${kinds})` : ""}` +
+        `${chartId ? ` on chart ${chartId}` : ""}` +
+        `${deletes ? ` — ${deletes} card${deletes === 1 ? "" : "s"} deleted` : ""}`,
+    };
+  }
+
   if (name === "save_cargo") {
     const src = str(obj.path);
     if (!src) return unknownTarget(toolName, "write");

package/src/remote/chartOps.ts

@@ -0,0 +1,360 @@
+// The wire contract for CLI → app Chart operations, shared by the three modules that
+// have to agree on it: RelayClient (sends the frames), RemoteBridge (correlates the
+// reply), and the chart tools (validate before either runs).
+//
+// WHY THE ROUND TRIP EXISTS AT ALL. Identical to cargoSave.ts, and for the same reason:
+// a chart's content is ciphertext under the account master key — `encryptedTitle` on the
+// graph, `encryptedPrompt` / `encryptedAiResponse` / `encryptedNoteBody` on every node —
+// and the terminal deliberately holds no master key (crypto/accountVerify.ts). A CLI that
+// POSTed /api/graph by itself could only write cards nothing can open, and could not read
+// back a single one. So it hands the app plaintext over the relay the user already trusts,
+// and the app — already signed in, already holding the key, already owning graphService —
+// does the encrypting and the POSTing. No new endpoint, no new key path.
+//
+// WHY THIS IS NOT JUST cargo's WIRE AGAIN. Cargo is one-way and one-shot: send an
+// artifact, get an id. A chart is a structure the user is editing on a canvas WHILE the
+// agent writes to it, so this contract carries four ops (list / read / create / edit)
+// rather than one, and `edit` is a list of operations rather than a replacement document.
+// Handing over a whole chart to overwrite would clobber whatever the user just typed.
+//
+// WHY NO CHUNKING. Cargo chunks because an artifact runs to 512 KB against a 256 KB frame
+// cap. Charts don't get to be that big, on purpose: a node body is capped at MAX_NODE_BODY
+// characters (a card someone reads on a phone, not a document), a call touches at most
+// MAX_NODES_PER_OP of them, and a `read` truncates each body to READ_BODY_CHARS before it
+// comes back. That last cap is as much about the model as the wire — a full chart dumped
+// into context is expensive and mostly noise when the agent only needs to know what is
+// already there. If media nodes land later they will need chunked binary, and that is the
+// point to revisit this; until then one frame each way keeps both ends simple.
+
+/**
+ * What a card IS, in the vocabulary the model gets. Deliberately NOT the server's
+ * `nodeType` enum, which is `entry | standard | note | file | drawing` and does not mean
+ * what it looks like: a picture on the canvas is a `standard` node with attachments and
+ * NO prompt (GraphViewScreen.tsx's image drop), a `drawing` is not a card at all but the
+ * chart's single freehand ink layer, and an `entry` is bookkeeping the create path owns.
+ * Handing that enum to a model gets you cards that render empty and a corrupted ink layer.
+ *
+ * So the tools speak in card kinds and the app maps them to fields:
+ *   note   → nodeType 'note',     body      → encryptedNoteBody
+ *   answer → nodeType 'standard', prompt    → encryptedPrompt
+ *                                 answer    → encryptedAiResponse  (+ the real modelId)
+ *
+ * `answer` is not a fancier `note`. Because it carries a genuine prompt/response pair it
+ * is a card the user can tap in the app and keep asking questions from — the branch
+ * continues under the app's model. A note is inert text. That difference is the reason
+ * both exist, and the tool descriptions say so.
+ */
+export const CHART_NODE_KINDS = ["note", "answer"] as const;
+export type ChartNodeKind = (typeof CHART_NODE_KINDS)[number];
+
+export function isChartNodeKind(v: unknown): v is ChartNodeKind {
+  return typeof v === "string" && (CHART_NODE_KINDS as readonly string[]).includes(v);
+}
+
+// ── Ceilings ────────────────────────────────────────────────────────────────────
+//
+// Every one of these is enforced on THIS side, where the message can name the offending
+// node and say what to do, rather than arriving as a save failure the model can only
+// report as "it didn't work".
+
+/** Characters in a single card's body (or its answer). A card is read on a phone. */
+export const MAX_NODE_BODY = 8_000;
+
+/** Characters in an `answer` card's prompt — a question, not an essay. */
+export const MAX_NODE_PROMPT = 2_000;
+
+/** Characters in a chart title. Mirrors chatGraphModel's `maxlength: 100`. */
+export const MAX_TITLE = 100;
+
+/** Characters in an edge label. Mirrors chatEdgeModel's own cap. */
+export const MAX_EDGE_LABEL = 60;
+
+/**
+ * Cards one call may create or touch. The in-app fan-out ceiling is 6 (utils/multiNode
+ * MAX_FANOUT), but that bounds one prompt spawning siblings; a chart being drawn as a map
+ * legitimately wants more. 12 is where a canvas is still pannable — past it the user gets
+ * a wall they scroll once and never open again, which is a worse outcome than a refusal.
+ */
+export const MAX_NODES_PER_OP = 12;
+
+/**
+ * Cards a `read` returns, newest first. A chart the user has been working in for months
+ * can hold far more than the agent needs to decide where a new card goes.
+ */
+export const MAX_READ_NODES = 60;
+
+/** Characters of each card's text a `read` returns before truncating. */
+export const READ_BODY_CHARS = 1_500;
+
+/** Charts a `list` returns. */
+export const MAX_LIST_CHARTS = 50;
+
+/**
+ * Bytes one request frame may occupy, checked on the serialized JSON.
+ *
+ * The per-field caps above are in CHARACTERS, and the relay's ceiling is in BYTES
+ * (`maxPayload: 256 * 1024` on the server's WebSocketServer). For English those are close
+ * enough to ignore; for Japanese, Thai, Hindi or Arabic they are not — twelve cards of
+ * 8,000 CJK characters each is roughly 288 KB of UTF-8 and the socket would drop the frame
+ * with no reply at all, which the tool could only report as a timeout. So the real ceiling
+ * is measured where it actually binds, with headroom for the envelope.
+ */
+export const MAX_REQUEST_BYTES = 200 * 1024;
+
+/**
+ * Is this request small enough to survive the relay? Returns a problem for the model, or
+ * null. Takes the already-built request so what is measured is exactly what is sent.
+ */
+export function checkRequestSize(req: ChartOpRequest): string | null {
+  const bytes = Buffer.byteLength(JSON.stringify(req), "utf8");
+  if (bytes <= MAX_REQUEST_BYTES) return null;
+  return (
+    `this call is ${Math.round(bytes / 1024)} KB, over the ${MAX_REQUEST_BYTES / 1024} KB a single relay frame can carry. ` +
+    `Split it into fewer cards per call, or shorten them — a card is meant to be read on a phone.`
+  );
+}
+
+// ── Requests ────────────────────────────────────────────────────────────────────
+
+/** A card to create. Which fields are required depends on `kind` — see validateNewNode. */
+export interface NewChartNode {
+  kind: ChartNodeKind;
+  /**
+   * A handle for THIS call only, so edges and `parent` can name a card that does not
+   * exist yet. The app maps refs to real ids as it creates them. Ids are minted by the
+   * server; a model cannot know one in advance, so without refs a create could only ever
+   * produce disconnected cards — which is not a chart, it's a pile.
+   */
+  ref?: string;
+  /** `note` only: the markdown body. */
+  body?: string;
+  /** `answer` only: the question this card answers. */
+  prompt?: string;
+  /** `answer` only: the response. */
+  answer?: string;
+  /**
+   * A `ref` from this same call, or an existing node id, to hang this card under. The app
+   * draws the edge AND uses it to lay the card out — position is deliberately not on this
+   * interface, because a model asked for coordinates produces overlapping cards and the
+   * app already knows how to place them (utils/multiNode computeFanoutPositions).
+   */
+  parent?: string;
+}
+
+/** An edge to draw between two cards, each named by `ref` or by existing node id. */
+export interface NewChartEdge {
+  from: string;
+  to: string;
+  label?: string;
+  /** Default true. A directional edge reads as "leads to"; bidirectional as "relates to". */
+  directional?: boolean;
+}
+
+/** One step of an `edit`. Applied in order, and the first failure stops the rest. */
+export type ChartEditOp =
+  | { edit: "add_node"; node: NewChartNode }
+  | { edit: "update_node"; nodeId: string; body?: string; prompt?: string; answer?: string }
+  | { edit: "connect"; edge: NewChartEdge }
+  | { edit: "delete_node"; nodeId: string }
+  | { edit: "rename"; title: string };
+
+export type ChartOpRequest =
+  | { op: "list" }
+  | { op: "read"; chartId: string }
+  | { op: "create"; title?: string; nodes: NewChartNode[]; edges?: NewChartEdge[] }
+  | { op: "edit"; chartId: string; ops: ChartEditOp[] };
+
+// ── Replies ─────────────────────────────────────────────────────────────────────
+
+export interface ChartSummary {
+  chartId: string;
+  title: string;
+  nodeCount: number;
+  updatedAt?: string;
+}
+
+export interface ChartNodeView {
+  nodeId: string;
+  kind: ChartNodeKind | "other";
+  /** The card's text, truncated to READ_BODY_CHARS. For `answer` cards, the response. */
+  text: string;
+  /** `answer` cards only: the question. */
+  prompt?: string;
+  truncated?: boolean;
+}
+
+export interface ChartEdgeView {
+  from: string;
+  to: string;
+  label?: string;
+  directional: boolean;
+}
+
+/**
+ * The app's answer. `ok: false` carries a reason written for a person — a locked vault, a
+ * chart cap, a guest session — because the tool hands it straight to the model, and
+ * "failed" is not something it can act on.
+ *
+ * `storageType` rides on the write results for the same reason cargo's does: a chart in a
+ * local-backend project never touches the server, and the user is owed the difference.
+ */
+export type ChartOpResult =
+  | { ok: true; op: "list"; charts: ChartSummary[] }
+  | {
+      ok: true;
+      op: "read";
+      chart: ChartSummary;
+      nodes: ChartNodeView[];
+      edges: ChartEdgeView[];
+      /** True when the chart holds more cards than MAX_READ_NODES and this is a slice. */
+      partial?: boolean;
+    }
+  | { ok: true; op: "create"; chartId: string; title: string; nodeIds: string[]; storageType: string }
+  | { ok: true; op: "edit"; chartId: string; applied: number; nodeIds: string[] }
+  | { ok: false; reason: string };
+
+// ── Validation ──────────────────────────────────────────────────────────────────
+//
+// Shared by the tools (before anything is sent) and worth keeping here rather than in the
+// tool file: the app trusts what arrives on this wire enough to write it into the user's
+// account, so the rules that decide what is well-formed belong with the contract, not
+// with one caller of it.
+
+/** Human-readable problem, or null when the card is well-formed. */
+export function validateNewNode(node: NewChartNode, where: string): string | null {
+  if (!node || typeof node !== "object") return `${where}: not an object.`;
+  if (!isChartNodeKind(node.kind)) {
+    return `${where}: kind must be one of ${CHART_NODE_KINDS.join(", ")} (got ${JSON.stringify(node.kind)}).`;
+  }
+  if (node.kind === "note") {
+    // Refused rather than coerced: a note whose text was passed as `answer` would store an
+    // empty card, and the user finds that out on their phone. Same call cargo makes on a
+    // kind that contradicts its extension.
+    if (!node.body || !node.body.trim()) return `${where}: a note card needs \`body\` (its markdown text).`;
+    if (node.prompt || node.answer) return `${where}: a note card takes \`body\` only — use kind "answer" to store a question and its response.`;
+    if (node.body.length > MAX_NODE_BODY) return `${where}: body is ${node.body.length} characters; a card caps at ${MAX_NODE_BODY}. Split it across cards.`;
+  } else {
+    if (!node.prompt || !node.prompt.trim()) return `${where}: an answer card needs \`prompt\` (the question it answers).`;
+    if (!node.answer || !node.answer.trim()) return `${where}: an answer card needs \`answer\` (the response).`;
+    if (node.body) return `${where}: an answer card takes \`prompt\` + \`answer\` — use kind "note" for plain text.`;
+    if (node.prompt.length > MAX_NODE_PROMPT) return `${where}: prompt is ${node.prompt.length} characters; it caps at ${MAX_NODE_PROMPT}. It should read as a question.`;
+    if (node.answer.length > MAX_NODE_BODY) return `${where}: answer is ${node.answer.length} characters; a card caps at ${MAX_NODE_BODY}. Split it across cards.`;
+  }
+  return null;
+}
+
+/** Human-readable problem with an edge, or null. `known` is every name an edge may use. */
+export function validateEdge(edge: NewChartEdge, known: Set<string>, where: string): string | null {
+  if (!edge || typeof edge !== "object") return `${where}: not an object.`;
+  if (!edge.from || !edge.to) return `${where}: needs both \`from\` and \`to\`.`;
+  if (edge.from === edge.to) return `${where}: an edge can't join a card to itself.`;
+  // Only refs are checkable here — an id belongs to a chart this process has never seen,
+  // so it is left to the app, which is the only end that can tell a real id from a typo.
+  for (const end of [edge.from, edge.to]) {
+    if (!known.has(end) && !looksLikeNodeId(end)) {
+      return `${where}: "${end}" is neither a \`ref\` in this call nor a node id. Known refs: ${[...known].join(", ") || "none"}.`;
+    }
+  }
+  if (edge.label && edge.label.length > MAX_EDGE_LABEL) return `${where}: label caps at ${MAX_EDGE_LABEL} characters.`;
+  return null;
+}
+
+/**
+ * Re-type an inbound `chart_result` payload off the wire. Nothing is trusted: the id keys
+ * a pending tool call and the rest is quoted straight to the model, so a malformed frame
+ * has to degrade into a refusal with a reason rather than an `undefined` the tool prints.
+ * Same posture as RelayClient's cargo_saved handling, factored out here because there are
+ * four result shapes to check instead of one.
+ */
+export function parseChartResult(raw: unknown): ChartOpResult {
+  const refuse = (reason: string): ChartOpResult => ({ ok: false, reason });
+  if (!raw || typeof raw !== "object") return refuse("the app sent an unreadable answer");
+  const r = raw as Record<string, unknown>;
+  if (r.ok !== true) {
+    return refuse(typeof r.reason === "string" && r.reason ? r.reason : "the app refused the operation without giving a reason");
+  }
+  const str = (v: unknown, fallback = ""): string => (typeof v === "string" ? v : fallback);
+  const arr = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
+  switch (r.op) {
+    case "list":
+      return {
+        ok: true,
+        op: "list",
+        charts: arr(r.charts).map((c) => {
+          const o = (c ?? {}) as Record<string, unknown>;
+          return {
+            chartId: str(o.chartId),
+            title: str(o.title),
+            nodeCount: typeof o.nodeCount === "number" ? o.nodeCount : 0,
+            updatedAt: typeof o.updatedAt === "string" ? o.updatedAt : undefined,
+          };
+        }).filter((c) => c.chartId),
+      };
+    case "read": {
+      const chart = (r.chart ?? {}) as Record<string, unknown>;
+      if (!str(chart.chartId)) return refuse("the app answered a read with no chart");
+      return {
+        ok: true,
+        op: "read",
+        chart: {
+          chartId: str(chart.chartId),
+          title: str(chart.title),
+          nodeCount: typeof chart.nodeCount === "number" ? chart.nodeCount : 0,
+          updatedAt: typeof chart.updatedAt === "string" ? chart.updatedAt : undefined,
+        },
+        nodes: arr(r.nodes).map((n) => {
+          const o = (n ?? {}) as Record<string, unknown>;
+          return {
+            nodeId: str(o.nodeId),
+            kind: isChartNodeKind(o.kind) ? o.kind : ("other" as const),
+            text: str(o.text),
+            prompt: typeof o.prompt === "string" ? o.prompt : undefined,
+            truncated: o.truncated === true ? true : undefined,
+          };
+        }).filter((n) => n.nodeId),
+        edges: arr(r.edges).map((e) => {
+          const o = (e ?? {}) as Record<string, unknown>;
+          return {
+            from: str(o.from),
+            to: str(o.to),
+            label: typeof o.label === "string" && o.label ? o.label : undefined,
+            directional: o.directional !== false,
+          };
+        }).filter((e) => e.from && e.to),
+        partial: r.partial === true ? true : undefined,
+      };
+    }
+    case "create": {
+      const chartId = str(r.chartId);
+      if (!chartId) return refuse("the app answered a create with no chart id");
+      return {
+        ok: true,
+        op: "create",
+        chartId,
+        title: str(r.title),
+        nodeIds: arr(r.nodeIds).filter((v): v is string => typeof v === "string"),
+        storageType: r.storageType === "local" ? "local" : "cloud",
+      };
+    }
+    case "edit":
+      return {
+        ok: true,
+        op: "edit",
+        chartId: str(r.chartId),
+        applied: typeof r.applied === "number" ? r.applied : 0,
+        nodeIds: arr(r.nodeIds).filter((v): v is string => typeof v === "string"),
+      };
+    default:
+      return refuse("the app answered with an operation this version doesn't understand");
+  }
+}
+
+/**
+ * Could this string be a server node id? Mongo ObjectIds are 24 hex characters; a
+ * local-backend chart mints 32-char hex ids instead (graphService's isLocalProject note).
+ * Accept either, and nothing else — the point is only to tell "an id I can't verify here"
+ * apart from "a ref you forgot to declare", so the error message can say which.
+ */
+export function looksLikeNodeId(s: string): boolean {
+  return /^[a-f0-9]{24}$/i.test(s) || /^[a-f0-9]{32}$/i.test(s);
+}

package/src/remote/relayClient.ts

@@ -23,6 +23,7 @@ import { MOAT_SHIMS, reservedNames } from "../config/moatManifest.ts";
 import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
 import { CARGO_CHUNK_CHARS, type CargoSaveRequest, type CargoSaveResult } from "./cargoSave.ts";
+import { parseChartResult, type ChartOpRequest, type ChartOpResult } from "./chartOps.ts";
 
 // Display label for THIS running terminal. Deliberately NON-PII: we do NOT send
 // username@hostname or the working-directory name to the server/controller (the
@@ -142,6 +143,12 @@ export interface RelayCallbacks {
   // bridge's bounded wait turns into a clean "this app can't save artifacts yet"
   // rather than a wedged tool call.
   onCargoSaved?: (id: string, result: CargoSaveResult) => void;
+  // The app finished a CLI-initiated Chart operation (the id from requestChartOp): it
+  // read, created or edited the chart and encrypted anything it stored, or refused.
+  // Optional for the same reason onCargoSaved is — a controller too old to understand
+  // chart_request simply never answers, which the bridge's bounded wait turns into a
+  // clean "this app can't do charts yet" rather than a wedged tool call.
+  onChartResult?: (id: string, result: ChartOpResult) => void;
   // The app's composer is autocompleting an `@file` mention — reply with the cwd
   // files/dirs matching `query` (a sendFileMatches frame, keyed by the same id).
   // Read-only; resolution of the picked path still happens on the prompt turn.
@@ -680,6 +687,9 @@ export class RelayClient {
       cargoId?: string;
       storageType?: string;
       reason?: string;
+      // chart_result (the app's answer to a chart op). Left `unknown` on purpose —
+      // it has four shapes and parseChartResult is what decides which one arrived.
+      result?: unknown;
     };
     try {
       frame = JSON.parse(data.toString());
@@ -755,6 +765,14 @@ export class RelayClient {
         this.cb.onCargoSaved?.(frame.id, result);
         break;
       }
+      // The app's answer to a chart op. Re-typed rather than trusted, for the same
+      // reason cargo_saved is: the id keys a pending tool call and the payload is
+      // quoted to the model.
+      case "chart_result": {
+        if (typeof frame.id !== "string" || !frame.id) break;
+        this.cb.onChartResult?.(frame.id, parseChartResult(frame.result));
+        break;
+      }
       case "files_search":
         if (typeof frame.id === "string") this.cb.onFilesSearch?.(frame.id, typeof frame.query === "string" ? frame.query : "");
         break;
@@ -1417,6 +1435,23 @@ export class RelayClient {
     this.rawSend({ type: "cargo_end", id });
   }
 
+  // Ask the app to run a chart operation: it decrypts to read, encrypts to write, and
+  // answers with a chart_result keyed by `id`. See chartOps.ts for why the round trip
+  // is the feature rather than a convenience.
+  //
+  // Unchunked, unlike requestCargoSave — chartOps caps a request well under the relay's
+  // 256 KB frame, which is a product decision (a card is something you read on a phone)
+  // as much as a wire one.
+  //
+  // NOT run through `safe()`, and for cargo's exact reason: that redacts secrets, and
+  // redaction inside content the user asked to store is corruption. A card reading
+  // `[redacted key]` where the model wrote an API shape is a defect the user only finds
+  // on their canvas. The tools decide what is safe to send.
+  requestChartOp(id: string, req: ChartOpRequest): void {
+    this.flushDeltas(); // land the op in order relative to buffered text
+    this.rawSend({ type: "chart_request", id, req });
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/remote/remoteBridge.ts

@@ -16,6 +16,7 @@ import type { PermissionRequest } from "../permissions/gate.ts";
 import type { AskOutcome } from "../permissions/modeGate.ts";
 import type { RelayCallbacks } from "./relayClient.ts";
 import type { CargoSaveRequest, CargoSaveResult } from "./cargoSave.ts";
+import type { ChartOpRequest, ChartOpResult } from "./chartOps.ts";
 
 // How much of a driven turn's reply we hold for possible outbox delivery. The
 // sealed item is capped at 45k plaintext anyway; this just stops a pathological
@@ -29,6 +30,12 @@ const MAX_TURN_CAPTURE = 60_000;
 // module (and so the env is read in the process that actually runs the save).
 const cargoSaveTimeoutMs = (): number => Number(process.env.PRIVATEER_CARGO_TIMEOUT_MS) || 60_000;
 
+// How long the app gets to answer a chart op. Same generosity and the same reasoning as
+// the cargo deadline — a create fans out into one POST per card, each encrypted on the
+// device first, so a chart of a dozen cards over a phone link is several seconds of real
+// work, not a round trip.
+const chartOpTimeoutMs = (): number => Number(process.env.PRIVATEER_CHART_TIMEOUT_MS) || 60_000;
+
 // The outbound surface the bridge needs; RelayClient implements all of it.
 export interface RelayLike {
   requestApproval(id: string, req: PermissionRequest): void;
@@ -48,6 +55,7 @@ export interface RelayLike {
   sendExtensions(payload: ExtensionsPayload): void;
   sendSkills(payload: SkillsPayload): void;
   requestCargoSave(id: string, req: CargoSaveRequest): void;
+  requestChartOp(id: string, req: ChartOpRequest): void;
 }
 
 // The installed-extensions snapshot relayed to the app's extensions manager.
@@ -149,6 +157,7 @@ export class RemoteBridge {
   private readonly pendingSelects = new Map<string, (v: string | null) => void>();
   private readonly pendingInputs = new Map<string, (v: string | null) => void>();
   private readonly pendingCargo = new Map<string, (r: CargoSaveResult) => void>();
+  private readonly pendingCharts = new Map<string, (r: ChartOpResult) => void>();
   private pendingAttachments: RemoteAttachment[] = [];
   // The driven turn in flight, kept only so it can be delivered to the outbox if it
   // turns out nobody was watching (see settleTurn). Bounded: the outbox truncates at
@@ -244,6 +253,10 @@ export class RemoteBridge {
       const resolve = this.pendingCargo.get(id);
       if (resolve) resolve(result);
     },
+    onChartResult: (id, result) => {
+      const resolve = this.pendingCharts.get(id);
+      if (resolve) resolve(result);
+    },
     onFilesSearch: (id, query) => this.cfg.onFilesSearch?.(id, query),
     onNoQuarter: (on) => {
       this.noQuarter = on;
@@ -467,6 +480,43 @@ export class RemoteBridge {
     });
   };
 
+  // Run a chart operation on the app and wait for its answer. Structurally the twin of
+  // saveCargoRemote — the app owns the master key, so reading a card and writing one are
+  // both round trips — with one difference worth stating: this is the only place the CLI
+  // asks the app for the user's stored CONTENT back. A refusal here has to be as legible
+  // as a write failure, because "read the chart first, then add to it" is the normal
+  // shape of the work and the model has to be able to act on why it couldn't.
+  chartOpRemote = (req: ChartOpRequest, signal?: AbortSignal): Promise<ChartOpResult> => {
+    if (!this.relay) return Promise.resolve({ ok: false, reason: "remote access is not enabled — run /remote-access on and drive this terminal from the Privateer app" });
+    if (!this.relay.isConnected()) return Promise.resolve({ ok: false, reason: "the relay is not connected" });
+    if (this.relay.hasController && !this.relay.hasController()) {
+      return Promise.resolve({ ok: false, reason: "the Privateer app is not attached to this terminal — only the app holds the key that opens a chart, so open it and attach first" });
+    }
+    const id = randomUUID();
+    return new Promise<ChartOpResult>((resolve) => {
+      const settle = (r: ChartOpResult) => {
+        if (!this.pendingCharts.has(id)) return; // already settled (abort raced the reply)
+        this.pendingCharts.delete(id);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(r);
+      };
+      const onAbort = () => settle({ ok: false, reason: "the turn was interrupted before the app answered" });
+      const deadline = chartOpTimeoutMs();
+      const timer = setTimeout(
+        () => settle({ ok: false, reason: `the app did not answer within ${Math.round(deadline / 1000)}s — it may be an older version that cannot work with charts from a terminal` }),
+        deadline,
+      );
+      timer.unref?.();
+      this.pendingCharts.set(id, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      this.relay!.requestChartOp(id, req);
+    });
+  };
+
   private rejectAllPending(): void {
     for (const resolve of this.pending.values()) resolve("deny");
     this.pending.clear();
@@ -486,5 +536,14 @@ export class RemoteBridge {
       resolve({ ok: false, reason: "the app disconnected before confirming the save — it may or may not have stored the artifact; check Cargo in the app before saving again" });
     }
     this.pendingCargo.clear();
+    // A chart op whose controller vanished mid-flight gets the same honest "unknown"
+    // wording as a cargo save, and for a sharper reason: `edit` applies its steps in
+    // order, so a socket that died halfway leaves a chart that is PARTLY changed. Telling
+    // the model it failed invites a retry that re-adds every card it already wrote. The
+    // only safe next move is to look, so the reason says exactly that.
+    for (const resolve of this.pendingCharts.values()) {
+      resolve({ ok: false, reason: "the app disconnected before answering — some of the change may already have been applied; open the chart in the app to see what landed before trying again" });
+    }
+    this.pendingCharts.clear();
   }
 }

package/src/routines/resultBrief.ts

@@ -8,9 +8,17 @@
 //
 // So we prepend this. It states the surface (markdown, in an app), what the surface can
 // render beyond prose (ONE fenced artifact, which the app turns into a Cargo card with
-// Preview / Download / Save), and how to hand over media (the attach_to_result tool —
-// only mentioned when it is actually registered, because a brief that advertises a tool
-// the run doesn't have is how a model ends up describing an attachment nobody gets).
+// Preview / Download / Save; and a ```chart fence, which becomes an "Add to Charts"
+// button), and how to hand over media (the attach_to_result tool — only mentioned when it
+// is actually registered, because a brief that advertises a tool the run doesn't have is
+// how a model ends up describing an attachment nobody gets).
+//
+// The chart line earns its tokens because there is NO other way for an unattended run to
+// put one in front of the user. When the app is attached a terminal builds charts
+// directly (the create_chart tool), but the outbox seal is write-only by construction —
+// a headless run cannot reach into the account at all. Describing the chart in the answer
+// and letting the user press a button hours later is the whole mechanism, and a model
+// that doesn't know the fence exists will never use it.
 //
 // Deliberately short. It is prepended to every unattended turn, so every line costs
 // tokens on every run; anything that isn't load-bearing for the delivery is the user's
@@ -43,6 +51,9 @@ export function deliveryBrief(opts: BriefOptions): string {
     "    ```md kind=pdf … ```        a document (also kind=docx, kind=md).",
     "    ```csv kind=sheet … ```     a spreadsheet.",
     "  The app turns that fence into an artifact card with Preview, Download and Save — so don't also paste the same content as prose.",
+    "- If the answer has STRUCTURE worth seeing — parts and how they connect, options and their trade-offs, the branches of an investigation — you may ALSO end with one ```chart fence holding JSON, which the app offers as \"Add to Charts\" (a canvas of cards the user pans around and can keep working in):",
+    '    ```chart {"title":"Auth flow","nodes":[{"kind":"note","ref":"a","body":"markdown text"},{"kind":"answer","ref":"b","parent":"a","prompt":"the question","answer":"the response"}],"edges":[{"from":"a","to":"b","label":"calls"}]} ```',
+    "  Two card kinds only: \"note\" (needs body) and \"answer\" (needs prompt AND answer — the user can tap it and keep the branch going, which a note can't do). Give each card a short `ref` and use `parent` to say what hangs off what; do NOT give positions, the app lays them out. Max 12 cards. A linear answer is not a chart — skip the fence and just write it.",
   ];
   if (opts.canAttach) {
     lines.push(

package/src/tools/charts.ts

@@ -0,0 +1,411 @@
+// The Chart tools — read and write the boards in the user's Privateer app ("Charts" in
+// the UI; `graph` everywhere in the code and the API, which is why this file keeps saying
+// chart to the model and graph to the wire).
+//
+// The interesting part is not this file, it's why every one of these is a round trip
+// through the app — src/remote/chartOps.ts has that. What matters here is the shape that
+// follows from it:
+//
+// THE MODEL NEVER SEES THE SCHEMA. A card on the canvas is not "pick a nodeType": an
+// image card is a `standard` node with attachments and no prompt, a `drawing` is the ink
+// layer rather than a card, and an `entry` is bookkeeping. A model handed that enum
+// produces cards that render empty. So the tools speak two kinds — `note` and `answer` —
+// and the app maps them to fields. Adding a kind means teaching the app, not widening this.
+//
+// THE MODEL NEVER DOES LAYOUT. There is no `position` anywhere in these parameters. Ask a
+// model for coordinates and you get overlapping cards; the app already knows how to place
+// them (computeFanoutPositions). The model supplies structure — what hangs off what — and
+// `parent` is how it says so.
+//
+// REFUSES RATHER THAN GUESSES. Same call cargo.ts makes about a mismatched kind, for the
+// same reason: a note whose text arrived as `answer` stores a blank card, and the user
+// discovers that later, on their phone, with no way to tell what went wrong. So a
+// malformed card is an error naming the card and the fix, checked here — before a single
+// frame goes out — rather than after four of twelve cards have already landed.
+//
+// SAYS WHERE IT LANDED. Like save_cargo, these writes are genuinely end-to-end encrypted:
+// the app encrypts on the device and the server stores ciphertext it cannot read. That is
+// the opposite of the generate_* tools' posture, so the descriptions state it plainly and
+// the success lines repeat it.
+
+import { Type } from "typebox";
+import {
+  MAX_NODES_PER_OP,
+  MAX_TITLE,
+  checkRequestSize,
+  looksLikeNodeId,
+  validateEdge,
+  validateNewNode,
+  type ChartEditOp,
+  type ChartOpRequest,
+  type ChartOpResult,
+  type NewChartEdge,
+  type NewChartNode,
+} from "../remote/chartOps.ts";
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+/** The bridge surface these tools need; RemoteBridge implements it. */
+export interface ChartOpBridge {
+  chartOpRemote(req: ChartOpRequest, signal?: AbortSignal): Promise<ChartOpResult>;
+}
+
+export const CHART_TOOL_NAMES = ["list_charts", "read_chart", "create_chart", "edit_chart"] as const;
+
+// Shared prose. Repeated in every description on purpose: a model that reads only one of
+// these tools must still learn that the app has to be attached and that the two card kinds
+// are not interchangeable.
+const NEEDS_APP =
+  "Needs the Privateer app attached to this terminal: the app holds the key, so it is the only end that can " +
+  "open a chart or encrypt a new card. Nothing readable by the server is ever stored.";
+
+const KIND_NOTE =
+  '"note" — a markdown card you wrote. Inert text the user reads.';
+const KIND_ANSWER =
+  '"answer" — a question and its response. The user can tap this card in the app and keep the branch going ' +
+  "with their own model, which a note cannot do. Prefer it whenever the card IS an answer to something.";
+
+/** The card sub-schema, shared by create_chart and edit_chart. */
+const NODE_SCHEMA = Type.Object({
+  kind: Type.String({ description: `What the card is. ${KIND_NOTE} ${KIND_ANSWER}` }),
+  ref: Type.Optional(
+    Type.String({
+      description:
+        'A short handle for this card within THIS call (e.g. "auth", "db"), so other cards can name it as ' +
+        "their `parent` and edges can join it. Ids are minted by the server, so without a ref you cannot " +
+        "connect cards you are creating in the same call.",
+    }),
+  ),
+  body: Type.Optional(Type.String({ description: 'The markdown text. Required for kind "note", and only for it.' })),
+  prompt: Type.Optional(Type.String({ description: 'The question this card answers. Required for kind "answer".' })),
+  answer: Type.Optional(Type.String({ description: 'The response. Required for kind "answer".' })),
+  parent: Type.Optional(
+    Type.String({
+      description:
+        "A `ref` from this call, or an existing node id, to hang this card under. Draws the edge and decides " +
+        "where the card is placed — this is how you express structure, since there are no coordinates.",
+    }),
+  ),
+});
+
+const EDGE_SCHEMA = Type.Object({
+  from: Type.String({ description: "A `ref` from this call, or an existing node id." }),
+  to: Type.String({ description: "A `ref` from this call, or an existing node id." }),
+  label: Type.Optional(Type.String({ description: 'What the connection means, e.g. "calls", "depends on". Kept short.' })),
+  directional: Type.Optional(
+    Type.Boolean({ description: 'Default true ("leads to"). False draws an undirected "relates to" link.' }),
+  ),
+});
+
+// ── shared validation ────────────────────────────────────────────────────────
+
+/**
+ * Check a set of cards and edges as a batch, returning the first problem or null. Batched
+ * rather than per-card because `ref` resolution is a property of the whole call: an edge
+ * naming a ref that no card declares is only detectable once every card has been seen.
+ */
+function validateBatch(nodes: NewChartNode[], edges: NewChartEdge[], nodeLabel: string): string | null {
+  if (nodes.length > MAX_NODES_PER_OP) {
+    return (
+      `${nodes.length} cards is more than one call can add (max ${MAX_NODES_PER_OP}). ` +
+      `A chart is something the user pans around — split this across calls, or say less per card.`
+    );
+  }
+  const refs = new Set<string>();
+  for (let i = 0; i < nodes.length; i++) {
+    const problem = validateNewNode(nodes[i], `${nodeLabel}[${i}]`);
+    if (problem) return problem;
+    const ref = nodes[i].ref;
+    if (ref) {
+      if (refs.has(ref)) return `${nodeLabel}[${i}]: ref "${ref}" is used twice — refs must be unique within a call.`;
+      refs.add(ref);
+    }
+  }
+  // A parent must resolve to something. Checked after every ref is known, so declaration
+  // order doesn't matter — the app resolves the graph, not the array.
+  for (let i = 0; i < nodes.length; i++) {
+    const parent = nodes[i].parent;
+    if (parent && !refs.has(parent) && !looksLikeNodeId(parent)) {
+      return `${nodeLabel}[${i}]: parent "${parent}" is neither a \`ref\` in this call nor a node id. Known refs: ${[...refs].join(", ") || "none"}.`;
+    }
+  }
+  for (let i = 0; i < edges.length; i++) {
+    const problem = validateEdge(edges[i], refs, `edges[${i}]`);
+    if (problem) return problem;
+  }
+  return null;
+}
+
+/** Render a read result as an outline. Cheaper to read than JSON, for a person or a model. */
+function renderChart(r: Extract<ChartOpResult, { op: "read" }>): string {
+  const lines: string[] = [];
+  lines.push(`Chart "${r.chart.title}" (${r.chart.chartId}) — ${r.chart.nodeCount} cards`);
+  if (r.partial) lines.push(`(showing the ${r.nodes.length} most recent)`);
+  lines.push("");
+  if (r.nodes.length === 0) {
+    lines.push("No cards yet.");
+  } else {
+    for (const n of r.nodes) {
+      const head = n.kind === "answer" && n.prompt ? `[${n.kind}] ${n.nodeId} — ${n.prompt}` : `[${n.kind}] ${n.nodeId}`;
+      lines.push(head);
+      if (n.text) lines.push(`    ${n.text.replace(/\n/g, "\n    ")}${n.truncated ? " …(truncated)" : ""}`);
+    }
+  }
+  if (r.edges.length > 0) {
+    lines.push("");
+    lines.push("Connections:");
+    for (const e of r.edges) {
+      lines.push(`  ${e.from} ${e.directional ? "→" : "—"} ${e.to}${e.label ? ` (${e.label})` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// ── list_charts ──────────────────────────────────────────────────────────────
+
+export function makeListChartsTool(bridge: ChartOpBridge) {
+  return {
+    name: "list_charts",
+    label: "List charts",
+    description:
+      "List the charts (visual boards of connected cards) in the user's Privateer app, with their titles and " +
+      "card counts. Use it to find the chart the user means before reading or editing one — chart ids are not " +
+      "guessable and a title alone is not one. " +
+      NEEDS_APP,
+    parameters: Type.Object({}),
+    async execute(_toolCallId: string, _params: Record<string, never>, signal?: AbortSignal) {
+      const res = await bridge.chartOpRemote({ op: "list" }, signal);
+      if (!res.ok) return text(`Could not list charts: ${res.reason}`);
+      if (res.op !== "list") return text("The app answered the wrong kind of result.");
+      if (res.charts.length === 0) return text("No charts yet. create_chart makes the first one.");
+      const lines = res.charts.map((c) => `${c.chartId}  ${c.title || "(untitled)"} — ${c.nodeCount} cards`);
+      return text(`${res.charts.length} chart${res.charts.length === 1 ? "" : "s"}:\n${lines.join("\n")}`);
+    },
+  };
+}
+
+// ── read_chart ───────────────────────────────────────────────────────────────
+
+export function makeReadChartTool(bridge: ChartOpBridge) {
+  return {
+    name: "read_chart",
+    label: "Read a chart",
+    description:
+      "Read a chart's cards and the connections between them. The app decrypts it on the device — this is the " +
+      "user's stored content, so read one because the work needs it, not to browse. " +
+      "Do this BEFORE edit_chart: card ids come from here, and adding to a chart you haven't looked at is how " +
+      "you end up with duplicates of cards that were already there. Long cards come back truncated. " +
+      NEEDS_APP,
+    parameters: Type.Object({
+      chartId: Type.String({ description: "The chart's id, from list_charts or from a create_chart you just made." }),
+    }),
+    async execute(_toolCallId: string, params: { chartId: string }, signal?: AbortSignal) {
+      if (!params.chartId) return text("Error: chartId is required — run list_charts to find it.");
+      const res = await bridge.chartOpRemote({ op: "read", chartId: params.chartId }, signal);
+      if (!res.ok) return text(`Could not read the chart: ${res.reason}`);
+      if (res.op !== "read") return text("The app answered the wrong kind of result.");
+      return text(renderChart(res));
+    },
+  };
+}
+
+// ── create_chart ─────────────────────────────────────────────────────────────
+
+export function makeCreateChartTool(bridge: ChartOpBridge) {
+  return {
+    name: "create_chart",
+    label: "Create a chart",
+    description:
+      "Create a new chart in the user's Privateer app — a canvas of cards they can open, pan around, and keep " +
+      "working in from any signed-in device. Use it when the thing you have to show HAS STRUCTURE worth seeing: " +
+      "subsystems and how they connect, a set of options and their trade-offs, the branches of an investigation. " +
+      "For a linear answer, a plain reply is better; for a single document, use save_cargo.\n" +
+      `Two card kinds. ${KIND_NOTE} ${KIND_ANSWER}\n` +
+      "Structure, not coordinates: give each card a short `ref` and set `parent` (or list `edges`) to say what " +
+      "hangs off what. The app lays them out. " +
+      `At most ${MAX_NODES_PER_OP} cards per call — add more with edit_chart. ` +
+      NEEDS_APP,
+    parameters: Type.Object({
+      nodes: Type.Array(NODE_SCHEMA, {
+        description: `The cards to create, at most ${MAX_NODES_PER_OP}. The first card with no \`parent\` becomes the chart's starting point.`,
+      }),
+      title: Type.Optional(
+        Type.String({
+          description:
+            "Title for the chart, the way the user would name it. Omitted → the app derives one from the first " +
+            `card's text, which is usually fine. Max ${MAX_TITLE} characters.`,
+        }),
+      ),
+      edges: Type.Optional(
+        Type.Array(EDGE_SCHEMA, {
+          description:
+            "Extra connections beyond the parent links — cross-links, or edges that need a label. Most charts " +
+            "need none of these.",
+        }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { nodes: NewChartNode[]; title?: string; edges?: NewChartEdge[] },
+      signal?: AbortSignal,
+    ) {
+      const nodes = Array.isArray(params.nodes) ? params.nodes : [];
+      const edges = Array.isArray(params.edges) ? params.edges : [];
+      if (nodes.length === 0) return text("Error: a chart needs at least one card — pass `nodes`.");
+      if (params.title && params.title.length > MAX_TITLE) {
+        return text(`Title is ${params.title.length} characters; it caps at ${MAX_TITLE}.`);
+      }
+      const problem = validateBatch(nodes, edges, "nodes");
+      if (problem) return text(problem);
+
+      const req: ChartOpRequest = { op: "create", title: params.title, nodes, edges };
+      // Measured on the built request, because the per-field caps are in characters and
+      // the relay's is in bytes — see checkRequestSize.
+      const oversize = checkRequestSize(req);
+      if (oversize) return text(oversize);
+
+      const res = await bridge.chartOpRemote(req, signal);
+      if (!res.ok) return text(`Could not create the chart: ${res.reason}`);
+      if (res.op !== "create") return text("The app answered the wrong kind of result.");
+      const where = res.storageType === "local" ? "on the device" : "encrypted on the device and stored";
+      return text(
+        `Created "${res.title}" with ${res.nodeIds.length} card${res.nodeIds.length === 1 ? "" : "s"} — ${where}. ` +
+          `Chart id ${res.chartId}. It's in Charts in the app now; edit_chart adds to it.`,
+      );
+    },
+  };
+}
+
+// ── edit_chart ───────────────────────────────────────────────────────────────
+
+export function makeEditChartTool(bridge: ChartOpBridge) {
+  return {
+    name: "edit_chart",
+    label: "Edit a chart",
+    description:
+      "Change an existing chart: add cards, rewrite one, connect two, delete one, or rename the chart. Steps are " +
+      "applied in order and stop at the first failure, so put the cards before the edges that join them.\n" +
+      "Read the chart first (read_chart) — every `nodeId` here comes from there, and it is also how you avoid " +
+      "adding a card the user already has. New cards can carry a `ref` so later steps in the same call can " +
+      "connect them. " +
+      `At most ${MAX_NODES_PER_OP} new cards per call. ` +
+      NEEDS_APP,
+    parameters: Type.Object({
+      chartId: Type.String({ description: "The chart to change, from list_charts or read_chart." }),
+      ops: Type.Array(
+        Type.Object({
+          edit: Type.String({
+            description:
+              'One of: "add_node" (needs `node`), "update_node" (needs `nodeId` plus the fields to rewrite), ' +
+              '"connect" (needs `edge`), "delete_node" (needs `nodeId`), "rename" (needs `title`).',
+          }),
+          node: Type.Optional(NODE_SCHEMA),
+          nodeId: Type.Optional(Type.String({ description: "The card to change or remove, from read_chart." })),
+          body: Type.Optional(Type.String({ description: "update_node: new markdown text for a note card." })),
+          prompt: Type.Optional(Type.String({ description: "update_node: new question for an answer card." })),
+          answer: Type.Optional(Type.String({ description: "update_node: new response for an answer card." })),
+          edge: Type.Optional(EDGE_SCHEMA),
+          title: Type.Optional(Type.String({ description: "rename: the chart's new title." })),
+        }),
+        { description: "The steps to apply, in order." },
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { chartId: string; ops: Array<Record<string, any>> },
+      signal?: AbortSignal,
+    ) {
+      if (!params.chartId) return text("Error: chartId is required — run list_charts to find it.");
+      const raw = Array.isArray(params.ops) ? params.ops : [];
+      if (raw.length === 0) return text("Error: `ops` is empty — say what to change.");
+
+      // Normalize into the wire shape, refusing anything half-specified. Done here rather
+      // than on the app side so the message can name the step and what it is missing —
+      // the app can only answer "step 3 failed", by which point steps 1 and 2 have landed.
+      const ops: ChartEditOp[] = [];
+      const newNodes: NewChartNode[] = [];
+      const newEdges: NewChartEdge[] = [];
+      for (let i = 0; i < raw.length; i++) {
+        const o = raw[i] ?? {};
+        const at = `ops[${i}]`;
+        switch (o.edit) {
+          case "add_node": {
+            if (!o.node) return text(`${at}: add_node needs \`node\`.`);
+            newNodes.push(o.node);
+            ops.push({ edit: "add_node", node: o.node });
+            break;
+          }
+          case "update_node": {
+            if (!o.nodeId) return text(`${at}: update_node needs \`nodeId\` (from read_chart).`);
+            // Shape-checked here because the server can't: a nodeId that isn't an id
+            // fails Mongo's ObjectId cast, which surfaces as "Server error: 500" — a
+            // message the model can do nothing with, on a step that has already let
+            // earlier steps land.
+            if (!looksLikeNodeId(o.nodeId)) return text(`${at}: "${o.nodeId}" is not a node id. Run read_chart and use the ids it lists.`);
+            if (o.body === undefined && o.prompt === undefined && o.answer === undefined) {
+              return text(`${at}: update_node needs at least one of \`body\`, \`prompt\` or \`answer\`.`);
+            }
+            // A note card has a body and an answer card has a prompt/answer pair; mixing
+            // them in one update is a card that would render half-blank either way.
+            if (o.body !== undefined && (o.prompt !== undefined || o.answer !== undefined)) {
+              return text(`${at}: update_node takes \`body\` (a note card) or \`prompt\`/\`answer\` (an answer card), not both.`);
+            }
+            ops.push({ edit: "update_node", nodeId: o.nodeId, body: o.body, prompt: o.prompt, answer: o.answer });
+            break;
+          }
+          case "connect": {
+            if (!o.edge) return text(`${at}: connect needs \`edge\` with \`from\` and \`to\`.`);
+            newEdges.push(o.edge);
+            ops.push({ edit: "connect", edge: o.edge });
+            break;
+          }
+          case "delete_node": {
+            if (!o.nodeId) return text(`${at}: delete_node needs \`nodeId\` (from read_chart).`);
+            if (!looksLikeNodeId(o.nodeId)) return text(`${at}: "${o.nodeId}" is not a node id. Run read_chart and use the ids it lists.`);
+            ops.push({ edit: "delete_node", nodeId: o.nodeId });
+            break;
+          }
+          case "rename": {
+            if (!o.title || !String(o.title).trim()) return text(`${at}: rename needs \`title\`.`);
+            if (String(o.title).length > MAX_TITLE) return text(`${at}: title caps at ${MAX_TITLE} characters.`);
+            ops.push({ edit: "rename", title: String(o.title) });
+            break;
+          }
+          default:
+            return text(
+              `${at}: "${o.edit}" is not an edit. Use add_node, update_node, connect, delete_node or rename.`,
+            );
+        }
+      }
+
+      const problem = validateBatch(newNodes, newEdges, "added cards");
+      if (problem) return text(problem);
+
+      const req: ChartOpRequest = { op: "edit", chartId: params.chartId, ops };
+      const oversize = checkRequestSize(req);
+      if (oversize) return text(oversize);
+
+      const res = await bridge.chartOpRemote(req, signal);
+      if (!res.ok) return text(`Could not edit the chart: ${res.reason}`);
+      if (res.op !== "edit") return text("The app answered the wrong kind of result.");
+      const added = res.nodeIds.length;
+      return text(
+        `Applied ${res.applied} of ${ops.length} step${ops.length === 1 ? "" : "s"} to the chart` +
+          (added ? `, adding ${added} card${added === 1 ? "" : "s"}` : "") +
+          `. Anything stored was encrypted on the device first.`,
+      );
+    },
+  };
+}
+
+/** All four, for a session that has a bridge to bind them to. */
+export function makeChartTools(bridge: ChartOpBridge) {
+  return [
+    makeListChartsTool(bridge),
+    makeReadChartTool(bridge),
+    makeCreateChartTool(bridge),
+    makeEditChartTool(bridge),
+  ];
+}

package/src/tools/relayFileTools.ts

@@ -14,6 +14,7 @@
 import { makeSendFileTool, type SendFileBridge } from "./sendFile.ts";
 import { makeSaveAttachmentTool } from "./saveAttachment.ts";
 import { makeSaveCargoTool, type CargoSaveBridge } from "./cargo.ts";
+import { makeChartTools, type ChartOpBridge } from "./charts.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
 // save_cargo rides with the file pair rather than with the media tools, because it
@@ -21,10 +22,17 @@ import type { AttachmentStore } from "../util/attachmentStore.ts";
 // account. Registering it in the moat's media block would put it in every harbor and
 // channels session, where there is no controller and every call would fail — see
 // remote/cargoSave.ts on why unattended runs deliver an artifact a different way.
-export function makeRelayFileTools(bridge: SendFileBridge & CargoSaveBridge, attachments: AttachmentStore) {
+// The chart tools ride here too, for the same reason save_cargo does and one more of
+// their own. Same reason: they need a CONNECTED APP, not a signed-in account, so the
+// moat's media block would put them in every harbor and channels session where there is
+// no controller and every call would fail. Their own reason: unlike cargo they also READ
+// the user's stored content, so an unattended session that could call them would be a
+// terminal asking for decrypted chat content with nobody watching the request.
+export function makeRelayFileTools(bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge, attachments: AttachmentStore) {
   return function relayFileTools(pi: any): void {
     pi.registerTool?.(makeSendFileTool(bridge));
     pi.registerTool?.(makeSaveAttachmentTool(attachments));
     pi.registerTool?.(makeSaveCargoTool(bridge));
+    for (const tool of makeChartTools(bridge)) pi.registerTool?.(tool);
   };
 }