@roam-research/roam-tools-core 0.5.1 → 0.6.1

package/dist/tools.js

@@ -1,7 +1,5 @@
 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";
@@ -9,7 +7,6 @@ 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";
 // Common schema for graph parameter (used by most tools)
 const GraphSchema = z.object({
     graph: z
@@ -22,7 +19,7 @@ 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,
@@ -32,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,
@@ -41,15 +38,10 @@ 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." +
@@ -78,6 +70,10 @@ const contentTools = [
         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),
@@ -87,7 +83,12 @@ const contentTools = [
         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);
 }
@@ -167,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"
@@ -214,9 +209,9 @@ 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, {
+                        await updateTokenStatus(resolvedGraph.nickname, {
                             lastKnownTokenStatus: "revoked",
                         });
                     }
@@ -238,17 +233,17 @@ 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",
                         });
@@ -264,9 +259,9 @@ 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
@@ -277,11 +272,11 @@ export async function routeToolCall(toolName, args) {
             }
             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;
     }

package/dist/types.d.ts

@@ -14,8 +14,8 @@ export declare const GraphConfigSchema: z.ZodObject<{
     accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
     lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
 }, "strip", z.ZodTypeAny, {
-    type: "hosted" | "offline";
     name: string;
+    type: "hosted" | "offline";
     token: string;
     nickname: string;
     accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -39,8 +39,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
         accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
         lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
     }, "strip", z.ZodTypeAny, {
-        type: "hosted" | "offline";
         name: string;
+        type: "hosted" | "offline";
         token: string;
         nickname: string;
         accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -55,8 +55,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     graphs: {
-        type: "hosted" | "offline";
         name: string;
+        type: "hosted" | "offline";
         token: string;
         nickname: string;
         accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -75,12 +75,15 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
     version?: number | undefined;
 }>;
 export type RoamMcpConfig = z.infer<typeof RoamMcpConfigSchema>;
-export interface ResolvedGraph {
+export interface ToolGraph {
     name: string;
     type: GraphType;
-    token: string;
     nickname: string;
     accessLevel?: AccessLevel;
+    token?: string;
+}
+export interface ResolvedGraph extends ToolGraph {
+    token: string;
     lastKnownTokenStatus?: "active" | "revoked";
 }
 export declare const ErrorCodes: {
@@ -104,6 +107,12 @@ export declare const ErrorCodes: {
     readonly GRAPH_NOT_SELECTED: "GRAPH_NOT_SELECTED";
     readonly CONNECTION_FAILED: "CONNECTION_FAILED";
     readonly CONFIG_TOO_NEW: "CONFIG_TOO_NEW";
+    readonly MISSING_AUTH: "MISSING_AUTH";
+    readonly INSUFFICIENT_PERMISSION: "INSUFFICIENT_PERMISSION";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+    readonly GRAPH_UNSUPPORTED: "GRAPH_UNSUPPORTED";
+    readonly ACTION_NOT_AVAILABLE: "ACTION_NOT_AVAILABLE";
+    readonly PEER_NOT_READY: "PEER_NOT_READY";
 };
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 export declare class RoamError extends Error {
@@ -277,10 +286,8 @@ export type TokenInfoResult = {
 } | {
     status: "unknown";
 };
-export interface RoamClientConfig {
-    graphName: string;
-    graphType: GraphType;
-    token: string;
-    port?: number;
+export interface RoamActionClient {
+    call<T = unknown>(action: string, args?: unknown[]): Promise<RoamResponse<T>>;
+    getTokenInfo?(): Promise<TokenInfoResult>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACpG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAGzD;AAGD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAE1E;AAGD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAE3D;AAOD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAG7C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;AAM/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAsB5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAGhE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7C;AAOD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;CAkCb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAGrE,qBAAa,SAAU,SAAQ,KAAK;aAGhB,IAAI,CAAC,EAAE,SAAS;aAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,SAAS,YAAA,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAUD,eAAO,MAAM,cAAc,IAAI,CAAC;AAYhC,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAG5C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAIhF;AAGD,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAGD,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACvD,oBAAoB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;CAC3D;AAGD,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;IACnB,oBAAoB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;CAC3D;AAID,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAClC;AAGD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;AAErF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAGD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,KAAK,GACL,OAAO,GACP,SAAS,GACT,KAAK,GACL,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAGD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAGD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACX,oBAAoB,EAAE,CAAC,kBAAkB,GAAG,sBAAsB,CAAC,EAAE,CAAC;QACtE,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;KAC3C,CAAC;CACH;AAGD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAGD,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB;AAGD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAGD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAG1B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -71,6 +71,15 @@ export const ErrorCodes = {
     GRAPH_NOT_SELECTED: "GRAPH_NOT_SELECTED",
     CONNECTION_FAILED: "CONNECTION_FAILED",
     CONFIG_TOO_NEW: "CONFIG_TOO_NEW",
+    // Cloud-transport codes — emitted by RoamCloudClient (relemma/functions_v2)
+    // against the AWS Clojure backend at proxy.api.roamresearch.com. Local does
+    // not emit these today.
+    MISSING_AUTH: "MISSING_AUTH", // 401 — WorkOS auth gate failed (no token, malformed token, or signature/issuer/audience invalid). Same agent semantics as MISSING_TOKEN; distinct for operational telemetry across transports.
+    INSUFFICIENT_PERMISSION: "INSUFFICIENT_PERMISSION", // 403 — Picker grant existed in RTDB but Roam-side graph access has been revoked since (firebase.graph/readable? or writeable? returned false). Distinct from TOKEN_NOT_FOUND ("never authorized"): INSUFFICIENT_PERMISSION = "ask user to re-grant"; TOKEN_NOT_FOUND = "pick a different graph or grant fresh access".
+    NOT_IMPLEMENTED: "NOT_IMPLEMENTED", // 501 — Action recognized in dispatch but handler not yet wired (Phase 3 backlog). Distinct from ACTION_NOT_AVAILABLE: NOT_IMPLEMENTED implies "will work eventually"; ACTION_NOT_AVAILABLE implies "not available on this transport, period".
+    GRAPH_UNSUPPORTED: "GRAPH_UNSUPPORTED", // 400 — Encrypted graph rejection (backend can't decrypt). Agent should not retry; instruct user the graph type isn't supported via cloud transport.
+    ACTION_NOT_AVAILABLE: "ACTION_NOT_AVAILABLE", // 501 — Action symbol absent from cloud's dispatch entirely (typo OR action like file.upload that's local-only and intentionally not on cloud). Same agent semantics as UNKNOWN_ACTION (which is local-API 404); distinct for operational telemetry across transports.
+    PEER_NOT_READY: "PEER_NOT_READY", // 503 — Backend peer instance starting up. Always retryable; reads use exponential backoff (200/400/800ms × 3 attempts) before surfacing; writes throw immediately (non-idempotent).
 };
 // Custom error class with error code and optional context
 export class RoamError extends Error {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@roam-research/roam-tools-core",
-  "version": "0.5.1",
-  "description": "Core library for Roam Research tools",
+  "version": "0.6.1",
+  "description": "Transport-agnostic core for Roam Research MCP and CLI tools",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Roam-Research/roam-tools.git",
@@ -15,11 +15,6 @@
       "types": "./dist/index.d.ts",
       "development": "./src/index.ts",
       "import": "./dist/index.js"
-    },
-    "./connect": {
-      "types": "./dist/connect.d.ts",
-      "development": "./src/connect.ts",
-      "import": "./dist/connect.js"
     }
   },
   "files": [
@@ -33,12 +28,14 @@
     "node": ">=18"
   },
   "scripts": {
-    "prepublishOnly": "npm run --prefix ../.. build"
+    "prepublishOnly": "npm run --prefix ../.. build",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "open": "^11.0.0",
     "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
   }
 }

package/dist/client.d.ts

@@ -1,34 +0,0 @@
-import type { RoamResponse, RoamClientConfig, TokenInfoResult } from "./types.js";
-export declare class RoamClient {
-    private graphName;
-    private graphType;
-    private token;
-    private port;
-    constructor(config: RoamClientConfig);
-    private getPort;
-    private openRoamDeepLink;
-    private sleep;
-    private isConnectionError;
-    private isVersionMismatch;
-    private handleVersionMismatch;
-    /**
-     * Get user-friendly guidance for authentication errors
-     */
-    private getAuthErrorGuidance;
-    /**
-     * Get user-friendly guidance for permission errors
-     */
-    private getPermissionErrorGuidance;
-    /**
-     * Handle API error responses based on HTTP status and error code
-     */
-    private handleApiError;
-    private checkResponse;
-    /**
-     * Query the token info endpoint for current permissions.
-     * Best-effort: returns "unknown" on any failure except confirmed revocation.
-     */
-    getTokenInfo(): Promise<TokenInfoResult>;
-    call<T = unknown>(action: string, args?: unknown[]): Promise<RoamResponse<T>>;
-}
-//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAGpB,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAuB;gBAEvB,MAAM,EAAE,gBAAgB;YAoBtB,OAAO;YAeP,gBAAgB;YAKhB,KAAK;IAInB,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAiBlC;;OAEG;IACH,OAAO,CAAC,cAAc;IAsCtB,OAAO,CAAC,aAAa;IAMrB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAsCxC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAuExF"}