@roam-research/roam-tools-core 0.5.0 → 0.6.0

package/dist/operations/pages.js

@@ -4,12 +4,22 @@ import { textResult } from "../types.js";
 export const CreatePageSchema = z.object({
     title: z.string().describe("Page title"),
     markdown: z.string().optional().describe("Markdown content for the page"),
-    uid: z.string().optional(),
+    uid: z
+        .string()
+        .optional()
+        .describe("Custom UID to assign to the new page. Omit to let Roam auto-generate one (recommended)"),
+    childrenViewType: z
+        .enum(["document", "bullet", "numbered"])
+        .optional()
+        .describe("How children are displayed (document, bullet, or numbered)"),
 });
 export const GetPageSchema = z.object({
     title: z.string().optional().describe("Page title (alternative to uid)"),
     uid: z.string().optional().describe("Page UID"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (omit for full tree)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (omit for full tree)"),
 });
 export const DeletePageSchema = z.object({
     uid: z.string().describe("Page UID to delete"),
@@ -17,21 +27,31 @@ export const DeletePageSchema = z.object({
 export const UpdatePageSchema = z.object({
     uid: z.string().describe("Page UID"),
     title: z.string().optional().describe("New page title"),
-    childrenViewType: z.enum(["document", "bullet", "numbered"]).optional().describe("How children are displayed (document, bullet, or numbered)"),
-    mergePages: z.boolean().optional().describe("If true, merge with existing page when renaming to a title that already exists (default: false)"),
+    childrenViewType: z
+        .enum(["document", "bullet", "numbered"])
+        .optional()
+        .describe("How children are displayed (document, bullet, or numbered)"),
+    mergePages: z
+        .boolean()
+        .optional()
+        .describe("If true, merge with existing page when renaming to a title that already exists (default: false)"),
 });
 export const GetGuidelinesSchema = z.object({});
 export async function createPage(client, params) {
+    const page = { title: params.title };
+    if (params.uid !== undefined)
+        page.uid = params.uid;
+    if (params.childrenViewType !== undefined)
+        page["children-view-type"] = params.childrenViewType;
     const response = await client.call("data.page.fromMarkdown", [
-        {
-            page: { title: params.title, uid: params.uid },
-            "markdown-string": params.markdown,
-        },
+        { page, "markdown-string": params.markdown },
     ]);
     return textResult(response.result ?? { uid: "" });
 }
 export async function getPage(client, params) {
-    const apiParams = params.uid ? { uid: params.uid } : { title: params.title };
+    const apiParams = params.uid
+        ? { uid: params.uid }
+        : { title: params.title };
     if (params.maxDepth !== undefined)
         apiParams.maxDepth = params.maxDepth;
     const response = await client.call("data.ai.getPage", [apiParams]);
@@ -55,7 +75,11 @@ export async function updatePage(client, params) {
 }
 export async function getGuidelines(client) {
     const response = await client.call("data.ai.getGraphGuidelines", []);
-    const result = response.result ?? { guidelines: null, starredPages: [], todaysDailyNotePage: null };
+    const result = response.result ?? {
+        guidelines: null,
+        starredPages: [],
+        todaysDailyNotePage: null,
+    };
     const dnpTitle = result.todaysDailyNotePage;
     const nextSteps = dnpTitle
         ? `Start by reading today's daily note page ("${dnpTitle}") with get_page — this is the user's primary workspace for the day. If you need more context, call search with an empty query for recently edited and viewed content. Skip these orientation steps only when the user has already given you a specific task to execute (e.g. "create a page called X").`

package/dist/operations/query.d.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import type { RoamClient } from "../client.js";
-import type { CallToolResult } from "../types.js";
+import type { CallToolResult, RoamActionClient } from "../types.js";
 export declare const QuerySchema: z.ZodObject<{
     uid: z.ZodOptional<z.ZodString>;
     query: z.ZodOptional<z.ZodString>;
@@ -13,22 +12,22 @@ export declare const QuerySchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
     uid?: string | undefined;
-    query?: string | undefined;
-    sortOrder?: "asc" | "desc" | undefined;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    maxDepth?: number | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | undefined;
+    query?: string | undefined;
 }, {
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
     uid?: string | undefined;
-    query?: string | undefined;
-    sortOrder?: "asc" | "desc" | undefined;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    maxDepth?: number | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | undefined;
+    query?: string | undefined;
 }>;
 export type QueryParams = z.infer<typeof QuerySchema>;
-export declare function query(client: RoamClient, params: QueryParams): Promise<CallToolResult>;
+export declare function query(client: RoamActionClient, params: QueryParams): Promise<CallToolResult>;
 //# sourceMappingURL=query.d.ts.map

package/dist/operations/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/operations/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,aAAa,CAAC;AAKjE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;EAStB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wBAAsB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA2B5F"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/operations/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAiB,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKnF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BtB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wBAAsB,KAAK,CACzB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC,CA2BzB"}

package/dist/operations/query.js

@@ -3,14 +3,32 @@ import { textResult } from "../types.js";
 // Schema for executing Roam queries ({{query: }} or {{[[query]]: }} blocks, NOT Datalog)
 // Supports two modes: UID mode (execute existing query block) or Query mode (raw query string)
 export const QuerySchema = z.object({
-    uid: z.string().optional().describe("UID of a block containing {{query: ...}} or {{[[query]]: ...}} - uses the block's saved display settings and filters"),
-    query: z.string().optional().describe("Raw Roam query string (e.g., \"{and: [[TODO]] {not: [[DONE]]}}\") - NOT Datalog - results are flat list, no user filters applied"),
-    sort: z.enum(["created-date", "edited-date", "daily-note-date"]).optional().describe("Sort order (only for query mode, default: created-date)"),
-    sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (only for query mode, default: desc)"),
-    includePath: z.boolean().optional().describe("Include breadcrumb path in results (only for query mode, default: true)"),
+    uid: z
+        .string()
+        .optional()
+        .describe("UID of a block containing {{query: ...}} or {{[[query]]: ...}} - uses the block's saved display settings and filters"),
+    query: z
+        .string()
+        .optional()
+        .describe('Raw Roam query string (e.g., "{and: [[TODO]] {not: [[DONE]]}}") - NOT Datalog - results are flat list, no user filters applied'),
+    sort: z
+        .enum(["created-date", "edited-date", "daily-note-date"])
+        .optional()
+        .describe("Sort order (only for query mode, default: created-date)"),
+    sortOrder: z
+        .enum(["asc", "desc"])
+        .optional()
+        .describe("Sort direction (only for query mode, default: desc)"),
+    includePath: z
+        .boolean()
+        .optional()
+        .describe("Include breadcrumb path in results (only for query mode, default: true)"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results to return (default: 20)"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 1)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (default: 1)"),
 });
 export async function query(client, params) {
     // Validate: exactly one of uid or query must be provided

package/dist/operations/search.d.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import type { RoamClient } from "../client.js";
-import type { CallToolResult } from "../types.js";
+import type { CallToolResult, RoamActionClient } from "../types.js";
 export declare const SearchSchema: z.ZodObject<{
     query: z.ZodString;
     scope: z.ZodOptional<z.ZodEnum<["pages", "blocks", "all"]>>;
@@ -10,17 +9,17 @@ export declare const SearchSchema: z.ZodObject<{
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     query: string;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    maxDepth?: number | undefined;
+    includePath?: boolean | undefined;
     scope?: "pages" | "blocks" | "all" | undefined;
 }, {
     query: string;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    maxDepth?: number | undefined;
+    includePath?: boolean | undefined;
     scope?: "pages" | "blocks" | "all" | undefined;
 }>;
 export declare const SearchTemplatesSchema: z.ZodObject<{
@@ -32,6 +31,6 @@ export declare const SearchTemplatesSchema: z.ZodObject<{
 }>;
 export type SearchParams = z.infer<typeof SearchSchema>;
 export type SearchTemplatesParams = z.infer<typeof SearchTemplatesSchema>;
-export declare function search(client: RoamClient, params: SearchParams): Promise<CallToolResult>;
-export declare function searchTemplates(client: RoamClient, params: SearchTemplatesParams): Promise<CallToolResult>;
+export declare function search(client: RoamActionClient, params: SearchParams): Promise<CallToolResult>;
+export declare function searchTemplates(client: RoamActionClient, params: SearchTemplatesParams): Promise<CallToolResult>;
 //# sourceMappingURL=search.d.ts.map

package/dist/operations/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAsE,cAAc,EAAE,MAAM,aAAa,CAAC;AAItH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAEhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAY9F;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAIV,cAAc,EACd,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAIrB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAoBvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAOhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAC1B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,cAAc,CAAC,CAczB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}

package/dist/operations/search.js

@@ -2,15 +2,29 @@ import { z } from "zod";
 import { textResult } from "../types.js";
 // Schemas
 export const SearchSchema = z.object({
-    query: z.string().describe("Search query — use empty string to get recently edited and viewed content"),
-    scope: z.enum(["pages", "blocks", "all"]).optional().describe("Search scope: 'pages' for page titles only, 'blocks' for block content only, 'all' for both (default: 'all')"),
+    query: z
+        .string()
+        .describe("Search query — use empty string to get recently edited and viewed content"),
+    scope: z
+        .enum(["pages", "blocks", "all"])
+        .optional()
+        .describe("Search scope: 'pages' for page titles only, 'blocks' for block content only, 'all' for both (default: 'all')"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results (default: 20)"),
-    includePath: z.boolean().optional().describe("Include breadcrumb path to each result (default: true)"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 0)"),
+    includePath: z
+        .boolean()
+        .optional()
+        .describe("Include breadcrumb path to each result (default: true)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (default: 0)"),
 });
 export const SearchTemplatesSchema = z.object({
-    query: z.string().optional().describe("Keywords to filter templates by name (case-insensitive). Try relevant keywords first before listing all."),
+    query: z
+        .string()
+        .optional()
+        .describe("Keywords to filter templates by name (case-insensitive). Try relevant keywords first before listing all."),
 });
 export async function search(client, params) {
     const apiParams = {
@@ -22,7 +36,9 @@ export async function search(client, params) {
     };
     if (params.maxDepth !== undefined)
         apiParams.maxDepth = params.maxDepth;
-    const response = await client.call("data.ai.search", [apiParams]);
+    const response = await client.call("data.ai.search", [
+        apiParams,
+    ]);
     return textResult(response.result ?? { total: 0, results: [] });
 }
 export async function searchTemplates(client, params) {

package/dist/tools.d.ts

@@ -1,11 +1,10 @@
 import { z } from "zod";
-import type { CallToolResult } from "./types.js";
-import { RoamClient } from "./client.js";
+import type { CallToolResult, AccessLevel, RoamActionClient, ToolGraph } from "./types.js";
 export interface ClientToolDefinition {
     name: string;
     description: string;
     schema: z.ZodObject<z.ZodRawShape>;
-    action: (client: RoamClient, args: unknown) => Promise<CallToolResult>;
+    action: (client: RoamActionClient, args: unknown) => Promise<CallToolResult>;
     type: "client";
 }
 export interface StandaloneToolDefinition {
@@ -16,7 +15,41 @@ export interface StandaloneToolDefinition {
     type: "standalone";
 }
 export type ToolDefinition = ClientToolDefinition | StandaloneToolDefinition;
+export declare function defineTool<T extends z.ZodRawShape>(name: string, description: string, schema: z.ZodObject<T>, action: (client: RoamActionClient, args: z.infer<z.ZodObject<T>>) => Promise<CallToolResult>): ClientToolDefinition;
+export declare function defineStandaloneTool<T extends z.ZodRawShape>(name: string, description: string, schema: z.ZodObject<T>, action: (args: z.infer<z.ZodObject<T>>) => Promise<CallToolResult>): StandaloneToolDefinition;
+export declare const dataTools: ClientToolDefinition[];
+export declare const desktopUiTools: ClientToolDefinition[];
+export declare const contentTools: ClientToolDefinition[];
 export declare const tools: ToolDefinition[];
 export declare function findTool(name: string): ToolDefinition | undefined;
-export declare function routeToolCall(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+export interface RouteToolCallOptions {
+    /**
+     * Resolve a graph identifier (nickname/name) to a ToolGraph. Required.
+     * Local consumers use the resolver from @roam-research/roam-tools-local;
+     * hosted consumers wire their own (e.g., reading picker grants from RTDB).
+     */
+    resolveGraph: (providedGraph?: string) => Promise<ToolGraph>;
+    /**
+     * Construct a client for the resolved graph. Required.
+     * Local consumers return a RoamClient; hosted consumers return a transport
+     * that talks to proxy.api.roamresearch.com.
+     */
+    createClient: (graph: ToolGraph) => Promise<RoamActionClient> | RoamActionClient;
+    /**
+     * "local-sync" runs the desktop token-info side-flow on get_graph_guidelines:
+     * parallel getTokenInfo, access-level validation, status writes, and result
+     * enrichment. "skip" (default) disables that side-flow entirely. Graph-name
+     * prefix (prependGraphInfo) is unaffected by this mode and runs in both.
+     */
+    tokenInfoMode?: "local-sync" | "skip";
+    /**
+     * Only consulted in local-sync mode. Hosted callers may use this to write to
+     * their own grant store. If omitted, status changes are not persisted.
+     */
+    onTokenStatusUpdate?: (nickname: string, patch: {
+        accessLevel?: AccessLevel;
+        lastKnownTokenStatus?: "active" | "revoked";
+    }) => Promise<void>;
+}
+export declare function routeToolCall(toolName: string, args: Record<string, unknown>, options: RouteToolCallOptions): Promise<CallToolResult>;
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAkC,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+BzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;CAChB;AAGD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AA+L7E,eAAO,MAAM,KAAK,EAAE,cAAc,EAGjC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AA0FD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CA+HzB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -1,24 +1,25 @@
 import { z } from "zod";
 import { RoamError } from "./types.js";
-import { RoamClient } from "./client.js";
-import { resolveGraph, getPort, updateGraphTokenStatus } from "./graph-resolver.js";
 import { CreatePageSchema, GetPageSchema, DeletePageSchema, UpdatePageSchema, GetGuidelinesSchema, createPage, getPage, deletePage, updatePage, getGuidelines, } from "./operations/pages.js";
 import { CreateBlockSchema, GetBlockSchema, UpdateBlockSchema, DeleteBlockSchema, MoveBlockSchema, GetBacklinksSchema, AddCommentSchema, GetCommentsSchema, createBlock, getBlock, updateBlock, deleteBlock, moveBlock, getBacklinks, addComment, getComments, } from "./operations/blocks.js";
-import { SearchSchema, SearchTemplatesSchema, search, searchTemplates } from "./operations/search.js";
+import { SearchSchema, SearchTemplatesSchema, search, searchTemplates, } from "./operations/search.js";
 import { QuerySchema, query } from "./operations/query.js";
+import { DatalogQuerySchema, datalogQuery } from "./operations/datalog.js";
 import { GetOpenWindowsSchema, GetSelectionSchema, OpenMainWindowSchema, OpenSidebarSchema, getOpenWindows, getSelection, openMainWindow, openSidebar, } from "./operations/navigation.js";
-import { FileGetSchema, FileUploadSchema, FileDeleteSchema, getFile, uploadFile, deleteFile } from "./operations/files.js";
-import { ListGraphsSchema, SetupNewGraphSchema, listGraphs, setupNewGraph } from "./operations/graphs.js";
+import { FileGetSchema, FileUploadSchema, FileDeleteSchema, getFile, uploadFile, deleteFile, } from "./operations/files.js";
 // Common schema for graph parameter (used by most tools)
 const GraphSchema = z.object({
-    graph: z.string().optional().describe("Graph nickname or name (optional - auto-selects if only one graph is configured)"),
+    graph: z
+        .string()
+        .optional()
+        .describe("Graph nickname or name (optional - auto-selects if only one graph is configured)"),
 });
 // Helper to extend any schema with graph parameter
 function withGraph(schema) {
     return schema.extend(GraphSchema.shape);
 }
 // Helper to create tool with graph parameter
-function defineTool(name, description, schema, action) {
+export function defineTool(name, description, schema, action) {
     return {
         name,
         description,
@@ -28,7 +29,7 @@ function defineTool(name, description, schema, action) {
     };
 }
 // Helper to create standalone tool (no graph parameter, handles its own resolution)
-function defineStandaloneTool(name, description, schema, action) {
+export function defineStandaloneTool(name, description, schema, action) {
     return {
         name,
         description,
@@ -37,43 +38,57 @@ function defineStandaloneTool(name, description, schema, action) {
         type: "standalone",
     };
 }
-// Graph Management Tools (standalone - handle their own resolution)
-const graphManagementTools = [
-    defineStandaloneTool("list_graphs", "List all configured graphs with their nicknames. Also provides setup instructions for connecting additional graphs.", ListGraphsSchema, listGraphs),
-    defineStandaloneTool("setup_new_graph", "Set up a new Roam graph for access, or list available graphs. Call without arguments to see which graphs are available in Roam Desktop. Call with graph and nickname to connect a specific graph — ask the user what they'd like to call the graph before choosing a nickname. The user will see an approval dialog in Roam desktop app and must approve the token request. If the graph is already configured, returns the existing configuration without making changes.", SetupNewGraphSchema, setupNewGraph),
-];
 // Note appended to all client tool descriptions
 const GUIDELINES_NOTE = "\n\nNote: Call get_graph_guidelines first when starting to work with a graph.";
-// Content Tools (require graph/client)
-const contentTools = [
+// Data Tools (require graph/client; reusable across local + hosted MCP transports)
+export const dataTools = [
     defineTool("get_graph_guidelines", "IMPORTANT: Call this tool first when starting to work with a graph, before performing any other operations. Returns user-defined instructions and preferences for AI agents. The user may have specified naming conventions, preferred structures, or constraints that should guide your behavior. After receiving the response, follow the nextSteps field — it contains orientation actions you should take before proceeding.", GetGuidelinesSchema, getGuidelines),
     defineTool("create_page", "Create a new page in Roam, optionally with markdown content." + GUIDELINES_NOTE, CreatePageSchema, createPage),
-    defineTool("create_block", "Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation." + GUIDELINES_NOTE, CreateBlockSchema, createBlock),
+    defineTool("create_block", "Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation." +
+        GUIDELINES_NOTE, CreateBlockSchema, createBlock),
     defineTool("update_block", "Update an existing block's content or properties." + GUIDELINES_NOTE, UpdateBlockSchema, updateBlock),
     defineTool("delete_block", "Delete a block and all its children." + GUIDELINES_NOTE, DeleteBlockSchema, deleteBlock),
     defineTool("move_block", "Move a block to a new location." + GUIDELINES_NOTE, MoveBlockSchema, moveBlock),
-    defineTool("add_comment", "Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment." + GUIDELINES_NOTE, AddCommentSchema, addComment),
-    defineTool("get_comments", "Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages." + GUIDELINES_NOTE, GetCommentsSchema, getComments),
+    defineTool("add_comment", "Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment." +
+        GUIDELINES_NOTE, AddCommentSchema, addComment),
+    defineTool("get_comments", "Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages." +
+        GUIDELINES_NOTE, GetCommentsSchema, getComments),
     defineTool("delete_page", "Delete a page and all its contents." + GUIDELINES_NOTE, DeletePageSchema, deletePage),
-    defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." + GUIDELINES_NOTE, UpdatePageSchema, updatePage),
-    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths. Call with an empty query to get recently edited and viewed content — useful for understanding what the user is currently working on." + GUIDELINES_NOTE, SearchSchema, search),
-    defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." + GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
-    defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' + GUIDELINES_NOTE, QuerySchema, query),
-    defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." + GUIDELINES_NOTE, GetPageSchema, getPage),
-    defineTool("get_block", "Get a block's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large blocks." + GUIDELINES_NOTE, GetBlockSchema, getBlock),
-    defineTool("get_backlinks", "Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths." + GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
+    defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." +
+        GUIDELINES_NOTE, UpdatePageSchema, updatePage),
+    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths. Call with an empty query to get recently edited and viewed content — useful for understanding what the user is currently working on." +
+        GUIDELINES_NOTE, SearchSchema, search),
+    defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." +
+        GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
+    defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' +
+        GUIDELINES_NOTE, QuerySchema, query),
+    defineTool("datalog_query", "Execute a datomic-style datalog query against the graph's datascript database. Supported clauses: :find, :where, :in, and :timeout (ms). Inputs are positional parameters bound to :in variables after $. Write specific :where clauses to keep results bounded." +
+        GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery),
+    defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." +
+        GUIDELINES_NOTE, GetPageSchema, getPage),
+    defineTool("get_block", "Get a block's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large blocks." +
+        GUIDELINES_NOTE, GetBlockSchema, getBlock),
+    defineTool("get_backlinks", "Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths." +
+        GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
+];
+// Desktop UI Tools (require local Roam Desktop — file ops + window/selection introspection;
+// hosted MCP omits these because the parameters/effects assume a local environment).
+export const desktopUiTools = [
     defineTool("get_open_windows", "Get the current view in the main window and all open sidebar windows." + GUIDELINES_NOTE, GetOpenWindowsSchema, getOpenWindows),
     defineTool("get_selection", "Get the currently focused block and any multi-selected blocks." + GUIDELINES_NOTE, GetSelectionSchema, getSelection),
     defineTool("open_main_window", "Navigate to a page or block in the main window." + GUIDELINES_NOTE, OpenMainWindowSchema, openMainWindow),
     defineTool("open_sidebar", "Open a page or block in the right sidebar." + GUIDELINES_NOTE, OpenSidebarSchema, openSidebar),
     defineTool("file_get", "Fetch a file hosted on Roam (handles decryption for encrypted graphs)." + GUIDELINES_NOTE, FileGetSchema, getFile),
-    defineTool("file_upload", "Upload a file to Roam. Returns the Firebase storage URL. Usually you'll want to create a new block with the file as markdown: `![](url)`. Provide ONE of: filePath (preferred - local file, server reads directly), url (remote URL, server fetches), or base64 (raw data, fallback for sandboxed clients)." + GUIDELINES_NOTE, FileUploadSchema, uploadFile),
+    defineTool("file_upload", "Upload a file to Roam. Returns the Firebase storage URL. Usually you'll want to create a new block with the file as markdown: `![](url)`. Provide ONE of: filePath (preferred - local file, server reads directly), url (remote URL, server fetches), or base64 (raw data, fallback for sandboxed clients)." +
+        GUIDELINES_NOTE, FileUploadSchema, uploadFile),
     defineTool("file_delete", "Delete a file hosted on Roam." + GUIDELINES_NOTE, FileDeleteSchema, deleteFile),
 ];
-export const tools = [
-    ...graphManagementTools,
-    ...contentTools,
-];
+// Backwards-compatible aggregate of all client tools.
+export const contentTools = [...dataTools, ...desktopUiTools];
+// All client tools available in core. Local standalone tools (list_graphs,
+// setup_new_graph) live in @roam-research/roam-tools-local since they touch
+// ~/.roam-tools.json and the Roam Desktop API.
+export const tools = [...dataTools, ...desktopUiTools];
 export function findTool(name) {
     return tools.find((t) => t.name === name);
 }
@@ -89,19 +104,13 @@ function prependGraphInfo(result, nickname) {
     if (first.type === "text") {
         return {
             ...result,
-            content: [
-                { ...first, text: `${prefix}\n\n${first.text}` },
-                ...content.slice(1),
-            ],
+            content: [{ ...first, text: `${prefix}\n\n${first.text}` }, ...content.slice(1)],
         };
     }
     // For image or other content types, prepend a text block
     return {
         ...result,
-        content: [
-            { type: "text", text: prefix },
-            ...content,
-        ],
+        content: [{ type: "text", text: prefix }, ...content],
     };
 }
 /**
@@ -159,46 +168,40 @@ function roamErrorResult(error) {
         isError: true,
     };
 }
-export async function routeToolCall(toolName, args) {
+export async function routeToolCall(toolName, args, options) {
     const tool = findTool(toolName);
     if (!tool) {
         throw new Error(`Unknown tool: ${toolName}`);
     }
+    // Core only registers client tools. Standalone tools live in
+    // @roam-research/roam-tools-local; route them through that wrapper.
+    if (tool.type !== "client") {
+        throw new Error(`Tool ${toolName}: core's routeToolCall only handles client tools. ` +
+            `Standalone tools live in @roam-research/roam-tools-local.`);
+    }
     // Validate and parse args with Zod
     const parsed = tool.schema.safeParse(args);
     if (!parsed.success) {
         throw new Error(`Invalid arguments: ${parsed.error.message}`);
     }
-    // Handle standalone tools (graph management)
-    if (tool.type === "standalone") {
-        try {
-            return await tool.action(parsed.data);
-        }
-        catch (error) {
-            if (error instanceof RoamError) {
-                return roamErrorResult(error);
-            }
-            throw error;
-        }
-    }
-    // Handle client tools (require graph resolution)
+    const tokenInfoMode = options.tokenInfoMode ?? "skip";
+    const updateTokenStatus = options.onTokenStatusUpdate;
     try {
-        // Extract graph from validated args and resolve it
-        const { graph, ...restArgs } = parsed.data;
-        const resolvedGraph = await resolveGraph(graph);
-        const port = await getPort();
-        // Create client with full config
-        const client = new RoamClient({
-            graphName: resolvedGraph.name,
-            graphType: resolvedGraph.type,
-            token: resolvedGraph.token,
-            port,
-        });
-        // Special handling for get_graph_guidelines: sync token info in parallel
-        if (tool.name === "get_graph_guidelines") {
+        const { graph: graphArg, ...restArgs } = parsed.data;
+        const graph = await options.resolveGraph(graphArg);
+        const client = await options.createClient(graph);
+        // Special handling for get_graph_guidelines: sync token info in parallel.
+        // Only fires in local-sync mode AND when the client implements getTokenInfo.
+        // Bind early so TS narrows the optional method through the truthy check.
+        const getTokenInfoFn = client.getTokenInfo?.bind(client);
+        if (tool.name === "get_graph_guidelines" && tokenInfoMode === "local-sync" && getTokenInfoFn) {
+            // In local-sync mode, the resolver is expected to return ResolvedGraph
+            // (with lastKnownTokenStatus). If a custom resolver omits the field,
+            // the read returns undefined and behavior is identical.
+            const resolvedGraph = graph;
             const [actionSettled, tokenInfoSettled] = await Promise.allSettled([
                 tool.action(client, restArgs),
-                client.getTokenInfo(),
+                getTokenInfoFn(),
             ]);
             // getTokenInfo() never throws, so always fulfilled
             const tokenInfoResult = tokenInfoSettled.status === "fulfilled"
@@ -206,11 +209,15 @@ export async function routeToolCall(toolName, args) {
                 : { status: "unknown" };
             // Handle revoked token FIRST (before examining action result)
             if (tokenInfoResult.status === "revoked") {
-                if (resolvedGraph.lastKnownTokenStatus !== "revoked") {
+                if (updateTokenStatus && resolvedGraph.lastKnownTokenStatus !== "revoked") {
                     try {
-                        await updateGraphTokenStatus(resolvedGraph.nickname, { lastKnownTokenStatus: "revoked" });
+                        await updateTokenStatus(resolvedGraph.nickname, {
+                            lastKnownTokenStatus: "revoked",
+                        });
+                    }
+                    catch {
+                        // best-effort status update
                     }
-                    catch { }
                 }
                 const baseResult = actionSettled.status === "fulfilled"
                     ? actionSettled.value
@@ -226,22 +233,24 @@ export async function routeToolCall(toolName, args) {
             const result = actionSettled.value;
             if (tokenInfoResult.status === "active") {
                 const info = tokenInfoResult.info;
-                // Validate access level before writing to prevent config corruption
+                // Validate access level before writing to prevent status corruption
                 const validLevels = ["read-only", "read-append", "full"];
                 const level = validLevels.includes(info.grantedAccessLevel)
                     ? info.grantedAccessLevel
                     : undefined;
-                // Only write to config if something actually changed
+                // Only write if something actually changed
                 const accessLevelChanged = level && resolvedGraph.accessLevel !== level;
                 const tokenStatusChanged = resolvedGraph.lastKnownTokenStatus !== "active";
-                if (accessLevelChanged || tokenStatusChanged) {
+                if (updateTokenStatus && (accessLevelChanged || tokenStatusChanged)) {
                     try {
-                        await updateGraphTokenStatus(resolvedGraph.nickname, {
+                        await updateTokenStatus(resolvedGraph.nickname, {
                             ...(accessLevelChanged ? { accessLevel: level } : {}),
                             lastKnownTokenStatus: "active",
                         });
                     }
-                    catch { }
+                    catch {
+                        // best-effort status update
+                    }
                 }
                 if (!result.isError) {
                     const enriched = enrichResultWithTokenInfo(result, info);
@@ -250,22 +259,24 @@ export async function routeToolCall(toolName, args) {
                 return result;
             }
             // status === "unknown" — action succeeded, so token isn't revoked; clear stale status
-            if (resolvedGraph.lastKnownTokenStatus !== "active") {
+            if (updateTokenStatus && resolvedGraph.lastKnownTokenStatus !== "active") {
                 try {
-                    await updateGraphTokenStatus(resolvedGraph.nickname, { lastKnownTokenStatus: "active" });
+                    await updateTokenStatus(resolvedGraph.nickname, { lastKnownTokenStatus: "active" });
+                }
+                catch {
+                    // best-effort status update
                 }
-                catch { }
             }
             if (!result.isError) {
                 return prependGraphInfo(result, resolvedGraph.nickname);
             }
             return result;
         }
-        // Normal flow for all other tools
+        // Normal flow for all other tools (and get_graph_guidelines when token-info
+        // sync is skipped or unavailable). Graph-name prefix runs in both modes.
         const result = await tool.action(client, restArgs);
-        // Prepend graph info to successful responses
         if (!result.isError) {
-            return prependGraphInfo(result, resolvedGraph.nickname);
+            return prependGraphInfo(result, graph.nickname);
         }
         return result;
     }