studiograph 1.1.2 → 1.2.0-beta.1

package/dist/agent/skills/sync-setup.md

@@ -0,0 +1,68 @@
+---
+name: sync-setup
+description: Guide for setting up and running entity sync from external sources
+loading: eager
+---
+
+# Entity Sync
+
+You can sync data from external sources (Linear, Pipedrive, Granola, Obsidian, etc.) into the knowledge graph using the sync tools.
+
+## First-Time Setup
+
+1. **Check what's available:** Call `sync_list_sources` immediately — it returns configured sources (with full entity_mappings), available connectors, and known source definitions
+2. **Verify the connector exists** — connectors hold API credentials and are CLI-only for security. If missing, tell the user:
+   > "You'll need to set up the connector first. Run `studiograph connector add <name>` in your terminal."
+3. **Add the source:** `sync_setup_source({ name: "linear" })` — uses default mappings from built-in definitions when available
+4. **Customize if needed:** Built-in definitions (Pipedrive, Granola, Linear, Asana) provide ready-to-use defaults. To customize, pass `entity_mappings` to `sync_setup_source` to override field maps, add co-location, change target repos, or add status maps. See the `sync-configuration` skill for field map syntax and options.
+5. **No built-in definition?** Guide the user through building `entity_mappings` from scratch — choose extraction mode, define field maps, set target repo. Reference the `sync-configuration` skill for the full mapping schema.
+6. **Run the sync:** `sync_run({ sources: ["linear"] })`
+7. **Review staging:** `sync_status` — show the user what will be committed
+8. **Apply on confirmation:** Only call `sync_apply` after the user approves
+9. **Review & commit:** `studiograph review` (interactive diff review with approve/reject per entity), then `studiograph commit` (git commit across all repos)
+
+## Modifying an Existing Source
+
+When a user asks to adjust, change, or view a source config, **immediately call `sync_list_sources`** to read the current configuration. Do not ask the user to paste the config — you can read it yourself.
+
+1. `sync_list_sources` — call this FIRST, before asking questions (returns full `entity_mappings` with field maps, transforms, etc.)
+2. Show the user the relevant parts of their config and ask what they want to change
+3. Build the updated `entity_mappings` array (you must pass the complete array — it replaces, not merges)
+4. `sync_setup_source({ name: "...", entity_mappings: [...], force: true })` — overwrite with updated config
+
+Common adjustments: changing `field_map` entries, adding/removing entity mappings, changing `target_repo`, adding `co_locate`, switching `write_mode`, adjusting `status_map`, adding `list_tool`/`read_tool`.
+
+## Repeat Sync Flow
+
+1. `sync_run({ incremental: true })` — only fetches records updated since last sync
+2. `sync_status` — present the summary
+3. Wait for user confirmation
+4. `sync_apply` — writes entity files (no git commit)
+5. `workspace_status` — show what files changed across repos
+6. `workspace_review` — show diffs (optionally filter by `entityType`)
+7. `workspace_commit({ messagePrefix: "sync" })` — git commits across repos (or let user run `studiograph commit`)
+
+## Post-Apply Results
+
+After `sync_apply`, explain what happened to the user:
+
+- **Standard entities** are written as: `{target_repo}/{entity_id}/main.md` (entity folder with sentinel file)
+- **Co-located entities** are written as: `{target_repo}/{parent_id}/{subfolder}/{entity_id}.md` (flat file inside parent folder). Co-located files are sub-content, not graph entities.
+- **Skipped entities** — when co-location is configured but the parent field is empty or missing, those entities are skipped (not an error)
+- **Auto-registered repos** — if a `target_repo` doesn't exist yet, it's automatically created and registered in the workspace
+
+## Troubleshooting
+
+- **"Uncommitted changes"** — sync requires a clean working tree. Tell the user to commit or stash changes first, or use `--force` to override
+- **"Connector not found"** — the connector isn't set up. User must run `studiograph connector add <name>` in terminal
+- **Entities skipped during apply** — for co-located entities, check that the `parent_field` has a value in the extracted frontmatter. Missing parent = skip.
+- **Obsidian template file** — Obsidian creates a `.template` file instead of default mappings (every vault is different). Tell the user to copy mappings from the template into the source config and adjust `directory_patterns` and `field_map` for their vault.
+
+## Important Rules
+
+- **Never auto-commit** — always show `sync_status` and get user confirmation before `sync_apply`
+- **Connector management is CLI-only** — API keys and tokens must be set up via `studiograph connector add/remove`. Never ask users to provide API keys in chat
+- **Use incremental for repeat syncs** — avoids re-processing unchanged records
+- **Use dry run for previews** — `sync_run({ dryRun: true })` shows what would be extracted without writing staging
+- **Abort if needed** — `sync_abort` clears staging if the user wants to start over
+- **sync_commit is deprecated** — use `sync_apply` then `workspace_commit` instead

package/dist/agent/tools/connector-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * On-demand connector tools
+ *
+ * Instead of registering hundreds of individual MCP connector tools with the
+ * agent (which bloats every API call), this module provides two lightweight
+ * proxy tools:
+ *
+ *   connector_list  — discover available connectors and their tools
+ *   connector_call  — route a call to a specific connector tool
+ *
+ * The actual MCP tool wrappers are stored in a registry built from
+ * ConnectorManager.buildTools() output.
+ */
+export interface ConnectorToolEntry {
+    /** Namespaced name: "pipedrive__deals_search" */
+    name: string;
+    /** Local name within the connector: "deals_search" */
+    localName: string;
+    /** Connector name: "pipedrive" */
+    connector: string;
+    description: string;
+    parameters: any;
+    execute: (toolCallId: string, params: any) => Promise<any>;
+}
+export interface ConnectorRegistry {
+    connectors: Map<string, ConnectorToolEntry[]>;
+}
+/**
+ * Build a registry from ConnectorManager's wrapped tool objects.
+ * Parses the namespaced tool names (e.g. "pipedrive__deals_search")
+ * into connector → tool[] groupings.
+ */
+export declare function buildConnectorRegistry(tools: any[]): ConnectorRegistry;
+/**
+ * Create two proxy tools for on-demand connector access.
+ */
+export declare function createConnectorTools(registry: ConnectorRegistry): any[];

package/dist/agent/tools/connector-tools.js

@@ -0,0 +1,132 @@
+/**
+ * On-demand connector tools
+ *
+ * Instead of registering hundreds of individual MCP connector tools with the
+ * agent (which bloats every API call), this module provides two lightweight
+ * proxy tools:
+ *
+ *   connector_list  — discover available connectors and their tools
+ *   connector_call  — route a call to a specific connector tool
+ *
+ * The actual MCP tool wrappers are stored in a registry built from
+ * ConnectorManager.buildTools() output.
+ */
+/**
+ * Build a registry from ConnectorManager's wrapped tool objects.
+ * Parses the namespaced tool names (e.g. "pipedrive__deals_search")
+ * into connector → tool[] groupings.
+ */
+export function buildConnectorRegistry(tools) {
+    const connectors = new Map();
+    for (const tool of tools) {
+        const sep = tool.name.indexOf('__');
+        const connector = sep !== -1 ? tool.name.slice(0, sep) : tool.name;
+        const localName = sep !== -1 ? tool.name.slice(sep + 2) : tool.name;
+        if (!connectors.has(connector))
+            connectors.set(connector, []);
+        connectors.get(connector).push({
+            name: tool.name,
+            localName,
+            connector,
+            description: tool.description ?? '',
+            parameters: tool.parameters,
+            execute: tool.execute,
+        });
+    }
+    return { connectors };
+}
+/**
+ * Create two proxy tools for on-demand connector access.
+ */
+export function createConnectorTools(registry) {
+    return [
+        {
+            name: 'connector_list',
+            description: 'List available external connectors and their tools. Call with no arguments to see all connectors, or with connector name to see its tools, or with both connector and tool to see a tool\'s parameter schema.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    connector: {
+                        type: 'string',
+                        description: 'Show tools for this connector (e.g. "pipedrive", "linear")',
+                    },
+                    tool: {
+                        type: 'string',
+                        description: 'Show the parameter schema for this specific tool',
+                    },
+                },
+            },
+            execute: async (_toolCallId, params) => {
+                // Specific tool schema
+                if (params.connector && params.tool) {
+                    const tools = registry.connectors.get(params.connector);
+                    if (!tools) {
+                        return { content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }] };
+                    }
+                    const tool = tools.find(t => t.localName === params.tool);
+                    if (!tool) {
+                        return { content: [{ type: 'text', text: `Tool "${params.tool}" not found in ${params.connector}.` }] };
+                    }
+                    return { content: [{ type: 'text', text: `${params.connector} / ${params.tool}\n${tool.description}\n\nParameters:\n${JSON.stringify(tool.parameters, null, 2)}` }] };
+                }
+                // Tools for a specific connector
+                if (params.connector) {
+                    const tools = registry.connectors.get(params.connector);
+                    if (!tools) {
+                        return { content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }] };
+                    }
+                    const list = tools.map(t => `- ${t.localName}: ${t.description}`).join('\n');
+                    return { content: [{ type: 'text', text: `${params.connector} (${tools.length} tools):\n${list}` }] };
+                }
+                // All connectors overview
+                const summary = [...registry.connectors.entries()]
+                    .map(([name, tools]) => `- ${name} (${tools.length} tools)`)
+                    .join('\n');
+                return { content: [{ type: 'text', text: `Available connectors:\n${summary}\n\nCall with connector to see available tools.` }] };
+            },
+        },
+        {
+            name: 'connector_call',
+            description: 'Call a tool on an external service (Pipedrive, Linear, Granola, Asana, Obsidian). Use connector_list first to discover available tools and their parameters.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    connector: {
+                        type: 'string',
+                        description: 'Connector name (e.g. "pipedrive", "linear", "granola")',
+                    },
+                    tool: {
+                        type: 'string',
+                        description: 'Tool name within the connector (e.g. "deals_search", "list_issues")',
+                    },
+                    arguments: {
+                        type: 'object',
+                        description: 'Arguments to pass to the tool',
+                        additionalProperties: true,
+                    },
+                },
+                required: ['connector', 'tool'],
+            },
+            execute: async (_toolCallId, params) => {
+                const tools = registry.connectors.get(params.connector);
+                if (!tools) {
+                    return {
+                        content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }],
+                        isError: true,
+                    };
+                }
+                const tool = tools.find(t => t.localName === params.tool);
+                if (!tool) {
+                    const available = tools.slice(0, 20).map(t => t.localName).join(', ');
+                    const suffix = tools.length > 20 ? ` ... and ${tools.length - 20} more` : '';
+                    return {
+                        content: [{ type: 'text', text: `Tool "${params.tool}" not found in ${params.connector}. Available: ${available}${suffix}` }],
+                        isError: true,
+                    };
+                }
+                return tool.execute(_toolCallId, params.arguments || {});
+            },
+        },
+    ];
+}
+//# sourceMappingURL=connector-tools.js.map

package/dist/agent/tools/connector-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-tools.js","sourceRoot":"","sources":["../../../src/agent/tools/connector-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY;IACjD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAgC,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACnE,MAAM,SAAS,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACpE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC9D,UAAU,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC;YAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS;YACT,SAAS;YACT,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;YACnC,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA2B;IAC9D,OAAO;QACL;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,+MAA+M;YAC5N,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,4DAA4D;qBAC1E;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,kDAAkD;qBAChE;iBACF;aACF;YACD,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,MAAW,EAAE,EAAE;gBAClD,uBAAuB;gBACvB,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;oBACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACxD,IAAI,CAAC,KAAK,EAAE,CAAC;wBACX,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,cAAc,MAAM,CAAC,SAAS,2BAA2B,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;oBAC/J,CAAC;oBACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;wBACV,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,SAAS,MAAM,CAAC,IAAI,kBAAkB,MAAM,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,CAAC;oBACnH,CAAC;oBACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,SAAS,MAAM,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,WAAW,oBAAoB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;gBACjL,CAAC;gBAED,iCAAiC;gBACjC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;oBACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACxD,IAAI,CAAC,KAAK,EAAE,CAAC;wBACX,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,cAAc,MAAM,CAAC,SAAS,2BAA2B,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;oBAC/J,CAAC;oBACD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAC7E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,SAAS,KAAK,KAAK,CAAC,MAAM,aAAa,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;gBACjH,CAAC;gBAED,0BAA0B;gBAC1B,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;qBAC/C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,KAAK,CAAC,MAAM,SAAS,CAAC;qBAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,0BAA0B,OAAO,iDAAiD,EAAE,CAAC,EAAE,CAAC;YAC5I,CAAC;SACF;QACD;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,8JAA8J;YAC3K,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,wDAAwD;qBACtE;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,qEAAqE;qBACnF;oBACD,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,+BAA+B;wBAC5C,oBAAoB,EAAE,IAAI;qBAC3B;iBACF;gBACD,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC;aAChC;YACD,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,MAAW,EAAE,EAAE;gBAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACxD,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO;wBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,cAAc,MAAM,CAAC,SAAS,2BAA2B,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;wBACjJ,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACtE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7E,OAAO;wBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,SAAS,MAAM,CAAC,IAAI,kBAAkB,MAAM,CAAC,SAAS,gBAAgB,SAAS,GAAG,MAAM,EAAE,EAAE,CAAC;wBACtI,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;YAC3D,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/tools/fs-tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Filesystem tools for the agent.
+ *
+ * Gives the agent read/write access to local files outside the workspace
+ * (e.g. Obsidian vaults, project docs, config files).
+ */
+export declare function createFsTools(): ({
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+        content: import("@sinclair/typebox").TString;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        content: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+})[];

package/dist/agent/tools/fs-tools.js

@@ -0,0 +1,106 @@
+/**
+ * Filesystem tools for the agent.
+ *
+ * Gives the agent read/write access to local files outside the workspace
+ * (e.g. Obsidian vaults, project docs, config files).
+ */
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { Type as T } from '@sinclair/typebox';
+import { wrapToolResult } from './graph-tools.js';
+export function createFsTools() {
+    return [
+        {
+            name: 'read_file',
+            description: 'Read a file from the local filesystem by absolute or ~-relative path. ' +
+                'Returns the file contents as text. Use for reading docs, configs, or any file outside the workspace.',
+            parameters: T.Object({
+                path: T.String({ description: 'Absolute path or ~/relative path to the file' }),
+            }),
+            execute: async (_toolCallId, params) => {
+                try {
+                    const resolved = resolvePath(params.path);
+                    const stat = statSync(resolved);
+                    if (stat.isDirectory()) {
+                        return wrapToolResult({
+                            success: false,
+                            error: `Path is a directory, not a file. Use list_directory instead.`,
+                        });
+                    }
+                    const content = readFileSync(resolved, 'utf-8');
+                    return wrapToolResult({ success: true, path: resolved, content });
+                }
+                catch (error) {
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            },
+        },
+        {
+            name: 'list_directory',
+            description: 'List files and subdirectories at a given path. ' +
+                'Returns names with a trailing / for directories. Use to explore folders before reading files.',
+            parameters: T.Object({
+                path: T.String({ description: 'Absolute path or ~/relative path to the directory' }),
+            }),
+            execute: async (_toolCallId, params) => {
+                try {
+                    const resolved = resolvePath(params.path);
+                    if (!existsSync(resolved)) {
+                        return wrapToolResult({ success: false, error: `Path not found: ${resolved}` });
+                    }
+                    const entries = readdirSync(resolved).map(name => {
+                        const full = join(resolved, name);
+                        try {
+                            return statSync(full).isDirectory() ? `${name}/` : name;
+                        }
+                        catch {
+                            return name;
+                        }
+                    });
+                    return wrapToolResult({ success: true, path: resolved, entries });
+                }
+                catch (error) {
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            },
+        },
+        {
+            name: 'write_file',
+            description: 'Write content to a file on the local filesystem. Creates parent directories if needed. ' +
+                'Overwrites the file if it already exists. Use for creating or updating docs, configs, or any file outside the workspace.',
+            parameters: T.Object({
+                path: T.String({ description: 'Absolute path or ~/relative path to the file' }),
+                content: T.String({ description: 'Full file content to write' }),
+            }),
+            execute: async (_toolCallId, params) => {
+                try {
+                    const resolved = resolvePath(params.path);
+                    mkdirSync(dirname(resolved), { recursive: true });
+                    writeFileSync(resolved, params.content, 'utf-8');
+                    return wrapToolResult({ success: true, path: resolved, bytesWritten: Buffer.byteLength(params.content, 'utf-8') });
+                }
+                catch (error) {
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            },
+        },
+    ];
+}
+/** Expand ~ and resolve to absolute path */
+function resolvePath(p) {
+    if (p.startsWith('~/') || p === '~') {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return resolve(join(home, p.slice(1)));
+    }
+    return resolve(p);
+}
+//# sourceMappingURL=fs-tools.js.map

package/dist/agent/tools/fs-tools.js.map

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

package/dist/agent/tools/graph-tools.d.ts

@@ -8,6 +8,16 @@
  * - Upload assets
  */
 import { WorkspaceManager } from '../../core/workspace-manager.js';
+/**
+ * Helper to wrap tool results in AgentToolResult format
+ */
+export declare function wrapToolResult(result: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: any;
+};
 /**
  * Create graph tools for the agent
  */
@@ -15,7 +25,7 @@ export declare function createGraphTools(workspaceManager: WorkspaceManager, git
     id: string;
     name: string;
     email: string;
-}): {
+}, workspacePath?: string): ({
     name: string;
     label: string;
     description: string;
@@ -27,4 +37,22 @@ export declare function createGraphTools(workspaceManager: WorkspaceManager, git
         }[];
         details: any;
     }>;
-}[];
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        repo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        entityType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (toolCallId: string, params: {
+        repo?: string;
+        entityType?: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+})[];