@graview/tools 0.1.0

package/LICENSE

@@ -0,0 +1,96 @@
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Copyright 2025-2026 En Dash Consulting

package/README.md

@@ -0,0 +1,47 @@
+# @graview/tools
+
+What can legally be done with a selection, and the agent surface that shares it.
+
+Nobody authors an affordance. Providers notice things — a violation and the
+repairs it names, a mutation whose subject accepts every selected kind, a
+neighbour all but one of them share — and the results merge into one ranked
+set. An LLM is one optional provider among these rather than the mechanism.
+
+`createToolRuntime` generates a tool per mutation from the same declarations,
+so an external agent over MCP and a seat inside the interface use literally the
+same actions and produce literally the same diffs. That is why watching an
+agent work needs no bespoke observability layer.
+
+Read-only calls report the nodes they looked at, which is the half a diff
+cannot show. A seat holding a principal gets tools for what that principal may
+run, and is told plainly about the ones it may not.
+
+## The host: `graview mcp` and `graview apply`
+
+An external agent — an editor's assistant, a worker on a schedule — used to
+edit the seed file, because the seed was the only thing it could reach. These
+two commands put the runtime where the data is, so it evolves the live graph
+the way a person does: through `store.apply`, under its own seat, judged by the
+same policy, logged with its name.
+
+```sh
+graview mcp ./dist/domain/app.js --data ./data --as cursor --roles keeper
+graview mcp ./dist/domain/app.js --remote-url https://host.example/app --header "authorization: Bearer …"
+graview mcp ./dist/domain/app.js --list --roles keeper        # the seat's tools as tools/list JSON
+
+graview apply ./dist/domain/app.js --data ./data --roles keeper \
+  --call add-task --args '{"listId":"today","label":"Book the van","id":"t-van"}'
+graview apply ./dist/domain/app.js --data ./data --roles keeper --plan ./plan.json --preview
+graview apply ./dist/domain/app.js --data ./data --roles keeper --undo batch:7
+```
+
+`mcp` speaks MCP over stdio — JSON-RPC, one message per line, no SDK — around
+`createToolRuntime` and `createMcpAdapter`; a reply waits for the write to
+land, or for the server's verdict against a remote, so "done" is never said
+before it is true. `apply` is one act, a plan of many as one batch (`[{
+mutation, args, as? }]`, a later call naming an earlier one's node as
+`{ "$plan": "<as>" }`), or a take-back; `--preview` writes nothing. Both take
+the store backends `graview serve` takes — `--data`, `--sqlite`,
+`--remote-url` — and the seat flags `--as` and `--roles`. Every act that
+creates a kind accepts an optional `id` for the node it makes; every kind has
+a derived `remove-<kind>`, permitted through the acts that create it.

package/dist/agent/adapters.d.ts

@@ -0,0 +1,43 @@
+import type { AnySchema, GraphDiff, NodeOfSchema } from "@graview/core";
+import type { ToolRuntime } from "./tools.js";
+/** The shape an MCP server expects from `tools/list`. */
+export interface McpTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+export interface McpContent {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface McpToolResult {
+    readonly content: readonly McpContent[];
+    readonly isError?: boolean;
+}
+/**
+ * Exposes the runtime to an external agent (Claude Code, Cursor) over MCP.
+ *
+ * This is a TRANSPORT, not a second implementation: it renames fields and
+ * stringifies results, and that is all it does. The moment it starts making
+ * decisions the two agent surfaces have begun to diverge.
+ */
+export declare function createMcpAdapter<S extends AnySchema>(runtime: ToolRuntime<S>): {
+    listTools(): McpTool[];
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+};
+export interface InAppAgent<S extends AnySchema> {
+    readonly tools: ToolRuntime<S>["definitions"];
+    run(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Watch every change, whoever caused it. */
+    watch(listener: (diff: GraphDiff<NodeOfSchema<S>>) => void): () => void;
+}
+/**
+ * The same runtime, driven from a surface inside the interface.
+ *
+ * Both adapters emit the same diff stream, which is the whole point: a human
+ * edit and an agent edit are indistinguishable downstream, so the renderer
+ * highlights an agent's work with exactly the code that highlights yours.
+ */
+export declare function createInAppAdapter<S extends AnySchema>(runtime: ToolRuntime<S>): InAppAgent<S>;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/agent/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/agent/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;iBAE5D,OAAO,EAAE;mBAUd,MAAM,SACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,aAAa,CAAC;EAY5B;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,SAAS;IAC7C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC9C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,6CAA6C;IAC7C,KAAK,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,SAAS,EACpD,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,CAAC,CAYf"}

package/dist/agent/adapters.js

@@ -0,0 +1,52 @@
+/**
+ * Exposes the runtime to an external agent (Claude Code, Cursor) over MCP.
+ *
+ * This is a TRANSPORT, not a second implementation: it renames fields and
+ * stringifies results, and that is all it does. The moment it starts making
+ * decisions the two agent surfaces have begun to diverge.
+ */
+export function createMcpAdapter(runtime) {
+    return {
+        listTools() {
+            return runtime.definitions.map((tool) => ({
+                name: tool.name,
+                ...(tool.title === undefined ? {} : { title: tool.title }),
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            }));
+        },
+        async callTool(name, args = {}) {
+            const result = await runtime.call(name, args);
+            if (!result.ok) {
+                return { content: [{ type: "text", text: result.error }], isError: true };
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ data: result.data, diff: result.diff }, null, 2) },
+                ],
+            };
+        },
+    };
+}
+/**
+ * The same runtime, driven from a surface inside the interface.
+ *
+ * Both adapters emit the same diff stream, which is the whole point: a human
+ * edit and an agent edit are indistinguishable downstream, so the renderer
+ * highlights an agent's work with exactly the code that highlights yours.
+ */
+export function createInAppAdapter(runtime) {
+    return {
+        tools: runtime.definitions,
+        async run(name, args = {}) {
+            const result = await runtime.call(name, args);
+            if (!result.ok)
+                throw new Error(result.error);
+            return result.data;
+        },
+        watch(listener) {
+            return runtime.onDiff(listener);
+        },
+    };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/agent/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../src/agent/adapters.ts"],"names":[],"mappings":"AAqBA;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAsB,OAAuB;IAC3E,OAAO;QACL,SAAS;YACP,OAAO,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACxC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC1D,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;aAC9B,CAAC,CAAC,CAAC;QACN,CAAC;QAED,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,OAAgC,EAAE;YAElC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC5E,CAAC;YACD,OAAO;gBACL,OAAO,EAAE;oBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;iBAC1F;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAuB;IAEvB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,WAAW;QAC1B,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE;YACvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QACD,KAAK,CAAC,QAAQ;YACZ,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/tools.d.ts

@@ -0,0 +1,105 @@
+import { type AnySchema, type GraphDiff, type JsonSchema, type NodeOfSchema, type Place, type Principal, type Store } from "@graview/core";
+import { applyAffordance, type DeriveOptions } from "../derive.js";
+export interface ToolDefinition {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    /** False for the read tools, true for anything that changes the graph. */
+    readonly mutating: boolean;
+}
+export type ToolResult<S extends AnySchema> = {
+    readonly ok: true;
+    readonly data: unknown;
+    readonly diff?: GraphDiff<NodeOfSchema<S>>;
+    /**
+     * The nodes this call LOOKED AT.
+     *
+     * A diff can only ever show what changed, and an agent that reassigns
+     * one run after reading the whole week is doing something different
+     * from one that reassigns it after reading nothing. The runtime is the
+     * only place that knows, so it says so — and an interface can then draw
+     * attention as well as change.
+     */
+    readonly reads?: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export interface ToolRuntimeOptions<S extends AnySchema> {
+    /**
+     * Who this seat acts as. A principal is an author with roles, so the seat's
+     * attribution and its authorisation are the same fact — there is no way to
+     * write as one participant and be permitted as another.
+     */
+    readonly author?: Principal;
+    /**
+     * Options for the seat's own deriveAffordances calls. A FUNCTION is read
+     * fresh on every call — which is how a person's pins, toggled in the
+     * menu after this runtime was built, still reach the agent's tool list.
+     * The strip, the pointer menu and the seat must never disagree about
+     * the same acts.
+     */
+    readonly derive?: DeriveOptions<S> | (() => DeriveOptions<S>);
+    /** Refuse every mutating tool. Useful for a read-only agent seat. */
+    readonly readOnly?: boolean;
+    /**
+     * The places the app's pictures name, so `search_graph` can answer "where
+     * do I go for X" as well as "where is X". The store cannot see pictures;
+     * whoever built the runtime beside a view registry can.
+     */
+    readonly places?: readonly Place[] | (() => readonly Place[]);
+}
+/**
+ * One tool call, as it happens.
+ *
+ * The claim was that watching an agent needs no bespoke observability
+ * because its edits produce the same diffs a human's do. True, and not
+ * enough: a diff says what changed, never what was CONSIDERED. An agent that
+ * reads six nodes and then reassigns one run appears, through diffs alone,
+ * as a single unexplained write — the interface can only offer a spinner and
+ * a toast. Emitting the calls themselves is what turns that into something a
+ * person can follow, and read-only calls are the interesting half.
+ */
+export interface ToolCall {
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly mutating: boolean;
+    /** `running` on the way in; `ok` or `failed` on the way out. */
+    readonly phase: "running" | "ok" | "failed";
+    readonly error?: string;
+    readonly at: string;
+    /**
+     * The nodes a settled read-only call looked at. Absent while running, and
+     * absent for a mutating call — a change already reports its own reads
+     * through the op log, and reporting them twice would double-count.
+     */
+    readonly reads?: readonly string[];
+}
+export interface ToolRuntime<S extends AnySchema> {
+    readonly definitions: readonly ToolDefinition[];
+    /**
+     * Who this seat writes as.
+     *
+     * Exposed because a read has to be attributed to the SAME participant the
+     * writes are, or one agent looking at the graph and then changing it reads
+     * as two people editing at once.
+     */
+    readonly author?: ToolRuntimeOptions<S>["author"];
+    call(name: string, args: Record<string, unknown>): Promise<ToolResult<S>>;
+    /** Every applied change, whoever caused it. */
+    onDiff(listener: (diff: GraphDiff<NodeOfSchema<S>>) => void): () => void;
+    /** Every call, mutating or not, as it starts and as it settles. */
+    onCall(listener: (call: ToolCall) => void): () => void;
+}
+/**
+ * Tool definitions generate ONCE from the schema and are transport-agnostic.
+ *
+ * The MCP adapter and the in-app adapter are two thin wrappers over the same
+ * runtime, so an external agent and a surface inside the interface are using
+ * literally the same actions and emitting literally the same diffs. That is
+ * why watching an agent work needs no bespoke observability layer.
+ */
+export declare function createToolRuntime<S extends AnySchema>(store: Store<S>, options?: ToolRuntimeOptions<S>): ToolRuntime<S>;
+export { applyAffordance };
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"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"}

package/dist/agent/tools.js

@@ -0,0 +1,311 @@
+import { mutationToolSchema, search, } from "@graview/core";
+import { deriveAffordances, applyAffordance, } from "../derive.js";
+const READ_TOOLS = [
+    {
+        name: "search_graph",
+        description: "Find things by name: records whose name or readable fields carry the words, and the kinds, places and rules the words name — each with why it matched. Reach for this before get_graph when you know what something is called. Words match the start of words, case and accents aside; key:value tokens narrow as a list's filter does (done:false, is:any for past records, kind:<kind>). Pass subject (a node id) to get the acts you may run on it as hits too.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Words, with optional key:value conditions." },
+                limit: { type: "number", description: "Most hits to return; 20 when unsaid." },
+                subject: { type: "string", description: "A node id whose acts to include." },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "get_graph",
+        description: "Read the whole graph: every node with its fields, and every edge. Start here when you need the shape of the domain rather than one thing in it.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "get_node",
+        description: "Read one node, its edges, and the violations that implicate it. Use this to check a thing before you change it.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string", description: "Node id." } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "get_violations",
+        description: "List every invariant violation the graph currently has, with the repairs that would resolve each one. Read this before proposing work: a rule that is already broken is more urgent than anything you could add.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                context: {
+                    type: "object",
+                    description: "Evaluation context, e.g. { weekStart }.",
+                },
+            },
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "get_affordances",
+        description: "Ask what can legally be done with a selection, ranked. Prefer these over composing a mutation by hand: they are derived from the schema, the invariants and the shape of the graph, so they cannot name an action that does not exist.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selection: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Node ids.",
+                },
+                context: { type: "object" },
+            },
+            required: ["selection"],
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "preview_mutation",
+        description: "Try a mutation without applying it: get back the diff it would produce and any invariant it would break. Do this when you are unsure, rather than applying and undoing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mutation: { type: "string" },
+                args: { type: "object" },
+            },
+            required: ["mutation", "args"],
+            additionalProperties: false,
+        },
+        mutating: false,
+    },
+    {
+        name: "undo_batch",
+        description: "Undo one batch of operations. Fails, naming the blocking operation, when a later operation read what it wrote.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                batch: { type: "string" },
+                include: { type: "array", items: { type: "string" } },
+            },
+            required: ["batch"],
+            additionalProperties: false,
+        },
+        mutating: true,
+    },
+];
+/**
+ * Tool definitions generate ONCE from the schema and are transport-agnostic.
+ *
+ * The MCP adapter and the in-app adapter are two thin wrappers over the same
+ * runtime, so an external agent and a surface inside the interface are using
+ * literally the same actions and emitting literally the same diffs. That is
+ * why watching an agent work needs no bespoke observability layer.
+ */
+export function createToolRuntime(store, options = {}) {
+    /*
+     * Only what this seat MAY do.
+     *
+     * The narrowing is the store's, not the runtime's: a seat holding a
+     * principal gets tools for what that principal can run, and there is no
+     * second list to keep in step with the policy. A seat that then calls a
+     * mutation it was not given still hits the store's refusal, because the
+     * schema is a convenience and the enforcement is elsewhere.
+     */
+    const mutationTools = store
+        .permittedMutations(options.author ?? { kind: "agent" })
+        .map((mutation) => {
+        const tool = mutationToolSchema(mutation);
+        return {
+            name: mutation.name,
+            ...(tool.title === undefined ? {} : { title: tool.title }),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            mutating: true,
+        };
+    });
+    const definitions = options.readOnly
+        ? [...READ_TOOLS.filter((tool) => !tool.mutating)]
+        : [...READ_TOOLS, ...mutationTools];
+    /**
+     * The call itself, separated from the announcing so that every exit —
+     * including an early return for an unknown tool — is reported exactly once.
+     */
+    const run = async (name, args) => {
+        try {
+            const definition = definitions.find((tool) => tool.name === name);
+            if (!definition) {
+                /*
+                 * A tool this seat may not use EXISTS, and saying "unknown" would be
+                 * a lie an agent then reasons from — it would conclude the capability
+                 * is missing and go looking for a workaround. The same honesty the
+                 * interface owes a person: it is there, you may not use it, here is
+                 * who can.
+                 */
+                const withheld = store.allMutations().find((mutation) => mutation.name === name);
+                if (withheld) {
+                    const verdict = store.permits({ name, args }, options.author ?? { kind: "agent" });
+                    if (!verdict.ok)
+                        return { ok: false, error: verdict.refusal.message };
+                }
+                return {
+                    ok: false,
+                    error: `Unknown tool "${name}". Available: ${definitions.map((t) => t.name).join(", ")}`,
+                };
+            }
+            if (definition.mutating && options.readOnly) {
+                return {
+                    ok: false,
+                    error: `"${name}" changes the graph, and this seat is read-only.`,
+                };
+            }
+            switch (name) {
+                case "search_graph": {
+                    const places = typeof options.places === "function" ? options.places() : options.places;
+                    const subject = typeof args["subject"] === "string" ? args["subject"] : undefined;
+                    const found = search(store, String(args["query"] ?? ""), {
+                        principal: options.author ?? { kind: "agent" },
+                        limit: typeof args["limit"] === "number" ? args["limit"] : 20,
+                        ...(places ? { places } : {}),
+                        ...(subject ? { subject, from: [subject] } : {}),
+                    });
+                    return {
+                        ok: true,
+                        data: found,
+                        // What came back was looked at: the records named, and nothing else.
+                        reads: found.hits.flatMap((hit) => (hit.about === "node" ? [hit.id] : [])),
+                    };
+                }
+                case "get_graph": {
+                    const snapshot = store.graph.snapshot();
+                    return {
+                        ok: true,
+                        data: snapshot,
+                        reads: snapshot.nodes.map((node) => node.id),
+                    };
+                }
+                case "get_node": {
+                    const id = String(args["id"] ?? "");
+                    const node = store.graph.getNode(id);
+                    if (!node)
+                        return { ok: false, error: `No node "${id}".` };
+                    const out = store.graph.outEdges(id);
+                    const inbound = store.graph.inEdges(id);
+                    return {
+                        ok: true,
+                        data: {
+                            node,
+                            out,
+                            in: inbound,
+                            violations: store
+                                .violations()
+                                .filter((violation) => violation.nodeIds.includes(id)),
+                        },
+                        // Asking about a node is asking about its neighbourhood: the
+                        // answer names them, so looking at it looked at them.
+                        reads: [id, ...out.map((edge) => edge.to), ...inbound.map((edge) => edge.from)],
+                    };
+                }
+                case "get_violations":
+                    {
+                        const violations = store.violations(args["context"]);
+                        return {
+                            ok: true,
+                            data: violations,
+                            reads: [...new Set(violations.flatMap((violation) => violation.nodeIds))],
+                        };
+                    }
+                case "get_affordances": {
+                    const selection = args["selection"] ?? [];
+                    const derived = deriveAffordances(store, selection, {
+                        ...(typeof options.derive === "function" ? options.derive() : options.derive),
+                        // The seat asks as ITSELF, so what it is offered is what it may
+                        // do — and what it may not is stated rather than hidden, which
+                        // is how an agent learns a capability exists that it lacks.
+                        ...(options.author ? { principal: options.author } : {}),
+                        ...(args["context"]
+                            ? { context: args["context"] }
+                            : {}),
+                    });
+                    return { ok: true, data: derived, reads: selection };
+                }
+                case "preview_mutation": {
+                    const preview = store.preview({
+                        name: String(args["mutation"]),
+                        args: args["args"] ?? {},
+                    });
+                    return { ok: true, data: preview };
+                }
+                case "undo_batch": {
+                    const batch = String(args["batch"]);
+                    const include = args["include"] ?? [];
+                    const check = store.canUndo([batch, ...include]);
+                    if (!check.ok)
+                        return { ok: false, error: check.message };
+                    const result = store.undo([batch, ...include], {
+                        ...(options.author ? { author: options.author } : {}),
+                    });
+                    return { ok: true, data: result, diff: result.diff };
+                }
+                default: {
+                    const result = store.apply({ name, args }, { ...(options.author ? { author: options.author } : {}) });
+                    return {
+                        ok: true,
+                        data: {
+                            batch: result.batch,
+                            intent: result.intent,
+                            introduces: result.introduces,
+                            resolves: result.resolves,
+                        },
+                        diff: result.diff,
+                    };
+                }
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+    const watchers = new Set();
+    const announce = (call) => {
+        for (const watcher of watchers)
+            watcher(call);
+    };
+    return {
+        definitions,
+        ...(options.author ? { author: options.author } : {}),
+        onDiff(listener) {
+            return store.subscribe(listener);
+        },
+        onCall(listener) {
+            watchers.add(listener);
+            return () => watchers.delete(listener);
+        },
+        async call(name, args) {
+            const mutating = definitions.find((tool) => tool.name === name)?.mutating ?? false;
+            const started = { name, args, mutating, at: new Date().toISOString() };
+            announce({ ...started, phase: "running" });
+            const settle = (result) => {
+                announce(result.ok
+                    ? {
+                        ...started,
+                        phase: "ok",
+                        ...(!mutating && result.reads ? { reads: result.reads } : {}),
+                    }
+                    : { ...started, phase: "failed", error: result.error });
+                return result;
+            };
+            return settle(await run(name, args));
+        },
+    };
+}
+export { applyAffordance };
+//# sourceMappingURL=tools.js.map