studiograph 1.1.3 → 1.2.0-beta.10

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,14 +8,30 @@
  * - 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
  */
+export interface MutationEvent {
+    action: 'created' | 'updated' | 'deleted';
+    repo: string;
+    entityType: string;
+    entityId: string;
+}
 export declare function createGraphTools(workspaceManager: WorkspaceManager, gitUser: {
     id: string;
     name: string;
     email: string;
-}): ({
+}, workspacePath?: string, onHighlight?: (ids: string[]) => void, onMutation?: (m: MutationEvent) => void): ({
     name: string;
     label: string;
     description: string;
@@ -45,4 +61,20 @@ export declare function createGraphTools(workspaceManager: WorkspaceManager, git
         }[];
         details: any;
     }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        entityIds: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        entityIds: string[];
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
 })[];

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

@@ -10,10 +10,12 @@
 import { Type as T } from '@sinclair/typebox';
 import { ENTITY_SCHEMAS } from '../../core/validation.js';
 import { lintWorkspace } from '../../services/lint-service.js';
+import { findOrphans } from '../../services/orphan-service.js';
+import { SyncStateManager } from '../../services/sync/sync-state.js';
 /**
  * Helper to wrap tool results in AgentToolResult format
  */
-function wrapToolResult(result) {
+export function wrapToolResult(result) {
     const text = JSON.stringify(result, null, 2);
     return {
         content: [{ type: 'text', text }],
@@ -21,17 +23,22 @@ function wrapToolResult(result) {
     };
 }
 /**
- * Create graph tools for the agent
+ * Strip entity_type/entity_id from data to avoid confusing the LLM
+ * (these are already surfaced as top-level entityType/entityId fields)
  */
-export function createGraphTools(workspaceManager, gitUser) {
+function cleanData(data) {
+    const { entity_type, entity_id, ...rest } = data;
+    return rest;
+}
+export function createGraphTools(workspaceManager, gitUser, workspacePath, onHighlight, onMutation) {
     return [
         // Create entity
         {
             name: 'create_entity',
             label: 'Create Entity',
-            description: 'Create a new entity in a repository. Always validate required fields before calling.',
+            description: 'Create a new entity in a repository. Always validate required fields before calling. Repo is auto-resolved for app-defined types (deck, document, etc.).',
             parameters: T.Object({
-                repo: T.String({ description: 'Repository name' }),
+                repo: T.Optional(T.String({ description: 'Repository name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type (project, client, decision, etc.)' }),
                 entityId: T.String({ description: 'Unique entity ID in kebab-case' }),
                 data: T.Object({}, { description: 'Entity data (YAML frontmatter)', additionalProperties: true }),
@@ -40,7 +47,13 @@ export function createGraphTools(workspaceManager, gitUser) {
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    const graph = workspaceManager.getGraph(params.repo);
+                    let repoName = params.repo;
+                    if (!repoName) {
+                        repoName = workspaceManager.getRepoForEntityType(params.entityType);
+                        if (!repoName)
+                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                    }
+                    const graph = workspaceManager.getGraph(repoName);
                     // Add timestamps and user info
                     const now = new Date().toISOString();
                     const dataWithMeta = {
@@ -51,22 +64,26 @@ export function createGraphTools(workspaceManager, gitUser) {
                         created_by: gitUser.id,
                         updated_by: gitUser.id,
                     };
+                    // Sanitize double-escaped newlines from LLM JSON output
+                    const sanitizedContent = (params.content || '').replace(/\\n/g, '\n');
                     const entity = await graph.create({
                         entityType: params.entityType,
                         entityId: params.entityId,
                         data: dataWithMeta,
-                        content: params.content || '',
+                        content: sanitizedContent,
                         commitMessage: params.commitMessage,
                     });
+                    onMutation?.({ action: 'created', repo: repoName, entityType: params.entityType, entityId: params.entityId });
                     return wrapToolResult({
                         success: true,
                         entity: {
-                            id: entity.id,
-                            type: entity.entityType,
+                            entityId: entity.id,
+                            entityType: entity.entityType,
+                            repo: repoName,
                             path: entity.path,
-                            data: entity.data,
+                            data: cleanData(entity.data),
                         },
-                        message: `Created ${params.entityType}: ${params.entityId}`,
+                        message: `Created ${params.entityType}: ${params.entityId} in ${repoName}. Auto-committed — ready to push.`,
                     });
                 }
                 catch (error) {
@@ -81,23 +98,26 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'get_entity',
             label: 'Get Entity',
-            description: 'Retrieve an entity by type and ID',
+            description: 'Retrieve full entity details. Use repo, entityType, entityId from search/list results. entityType is optional — if omitted it is read from the file.',
             parameters: T.Object({
                 repo: T.String({ description: 'Repository name' }),
-                entityType: T.String({ description: 'Entity type' }),
+                entityType: T.Optional(T.String({ description: 'Entity type (optional — resolved from frontmatter if omitted)' })),
                 entityId: T.String({ description: 'Entity ID' }),
             }),
             execute: async (toolCallId, params) => {
                 try {
                     const graph = workspaceManager.getGraph(params.repo);
-                    const entity = graph.get(params.entityType, params.entityId);
+                    const entity = params.entityType
+                        ? graph.get(params.entityType, params.entityId)
+                        : graph.getById(params.entityId);
                     return wrapToolResult({
                         success: true,
                         entity: {
-                            id: entity.id,
-                            type: entity.entityType,
+                            entityId: entity.id,
+                            entityType: entity.entityType,
+                            repo: params.repo,
                             path: entity.path,
-                            data: entity.data,
+                            data: cleanData(entity.data),
                             content: entity.document.content,
                             wikilinks: entity.document.wikilinks,
                         },
@@ -115,9 +135,9 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'update_entity',
             label: 'Update Entity',
-            description: 'Update an existing entity',
+            description: 'Update an existing entity. Repo is auto-resolved for app-defined types.',
             parameters: T.Object({
-                repo: T.String({ description: 'Repository name' }),
+                repo: T.Optional(T.String({ description: 'Repository name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
                 data: T.Optional(T.Object({}, { description: 'Updated data fields', additionalProperties: true })),
@@ -126,7 +146,13 @@ export function createGraphTools(workspaceManager, gitUser) {
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    const graph = workspaceManager.getGraph(params.repo);
+                    let repoName = params.repo;
+                    if (!repoName) {
+                        repoName = workspaceManager.getRepoForEntityType(params.entityType);
+                        if (!repoName)
+                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                    }
+                    const graph = workspaceManager.getGraph(repoName);
                     // Add update metadata
                     const dataWithMeta = params.data
                         ? {
@@ -135,21 +161,26 @@ export function createGraphTools(workspaceManager, gitUser) {
                             updated_by: gitUser.id,
                         }
                         : undefined;
+                    // Sanitize double-escaped newlines from LLM JSON output
+                    const sanitizedContent = params.content !== undefined
+                        ? params.content.replace(/\\n/g, '\n') : params.content;
                     const entity = await graph.update({
                         entityType: params.entityType,
                         entityId: params.entityId,
                         data: dataWithMeta,
-                        content: params.content,
+                        content: sanitizedContent,
                         commitMessage: params.commitMessage,
                     });
+                    onMutation?.({ action: 'updated', repo: repoName, entityType: params.entityType, entityId: params.entityId });
                     return wrapToolResult({
                         success: true,
                         entity: {
-                            id: entity.id,
-                            type: entity.entityType,
-                            data: entity.data,
+                            entityId: entity.id,
+                            entityType: entity.entityType,
+                            repo: repoName,
+                            data: cleanData(entity.data),
                         },
-                        message: `Updated ${params.entityType}: ${params.entityId}`,
+                        message: `Updated ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
                     });
                 }
                 catch (error) {
@@ -164,20 +195,71 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'delete_entity',
             label: 'Delete Entity',
-            description: 'Delete an entity. Use with caution!',
+            description: 'Delete an entity. Use with caution! Repo is auto-resolved for app-defined types.',
             parameters: T.Object({
-                repo: T.String({ description: 'Repository name' }),
+                repo: T.Optional(T.String({ description: 'Repository name (auto-resolved for app entity types)' })),
                 entityType: T.String({ description: 'Entity type' }),
                 entityId: T.String({ description: 'Entity ID' }),
                 commitMessage: T.Optional(T.String({ description: 'Custom commit message' })),
             }),
             execute: async (toolCallId, params) => {
                 try {
-                    const graph = workspaceManager.getGraph(params.repo);
+                    let repoName = params.repo;
+                    if (!repoName) {
+                        repoName = workspaceManager.getRepoForEntityType(params.entityType);
+                        if (!repoName)
+                            return wrapToolResult({ success: false, error: `repo is required — could not auto-resolve repo for type "${params.entityType}"` });
+                    }
+                    const graph = workspaceManager.getGraph(repoName);
                     await graph.delete(params.entityType, params.entityId, params.commitMessage);
+                    onMutation?.({ action: 'deleted', repo: repoName, entityType: params.entityType, entityId: params.entityId });
                     return wrapToolResult({
                         success: true,
-                        message: `Deleted ${params.entityType}: ${params.entityId}`,
+                        message: `Deleted ${params.entityType}: ${params.entityId}. Auto-committed — ready to push.`,
+                    });
+                }
+                catch (error) {
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            },
+        },
+        // Move entity between repos
+        {
+            name: 'move_entity',
+            label: 'Move Entity',
+            description: 'Move an entity from one repository to another. Preserves all data, content, and wikilinks.',
+            parameters: T.Object({
+                sourceRepo: T.String({ description: 'Source repository name' }),
+                targetRepo: T.String({ description: 'Target repository name' }),
+                entityType: T.String({ description: 'Entity type' }),
+                entityId: T.String({ description: 'Entity ID' }),
+                commitMessage: T.Optional(T.String({ description: 'Custom commit message (optional)' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const sourceGraph = workspaceManager.getGraph(params.sourceRepo);
+                    const targetGraph = workspaceManager.getGraph(params.targetRepo);
+                    // Read the full entity from source
+                    const entity = sourceGraph.get(params.entityType, params.entityId);
+                    // Create in target repo
+                    const now = new Date().toISOString();
+                    await targetGraph.create({
+                        entityType: params.entityType,
+                        entityId: params.entityId,
+                        data: { ...entity.data, updated_at: now, updated_by: gitUser.id },
+                        content: entity.document.content || '',
+                        commitMessage: params.commitMessage || `Move ${params.entityType} ${params.entityId} from ${params.sourceRepo} to ${params.targetRepo}`,
+                    });
+                    // Delete from source repo
+                    await sourceGraph.delete(params.entityType, params.entityId, `Move ${params.entityType} ${params.entityId} to ${params.targetRepo}`);
+                    onMutation?.({ action: 'deleted', repo: params.sourceRepo, entityType: params.entityType, entityId: params.entityId });
+                    onMutation?.({ action: 'created', repo: params.targetRepo, entityType: params.entityType, entityId: params.entityId });
+                    return wrapToolResult({
+                        success: true,
+                        message: `Moved ${params.entityType}: ${params.entityId} from ${params.sourceRepo} to ${params.targetRepo}. Changes were auto-committed in both repos — ready to push.`,
                     });
                 }
                 catch (error) {
@@ -192,7 +274,7 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'search_entities',
             label: 'Search Entities',
-            description: 'Search for entities across repositories with filters',
+            description: 'Search for entities across repositories with filters. Note: source configs, sync settings, and connector configs are NOT entities — use sync_list_sources for those.',
             parameters: T.Object({
                 query: T.Optional(T.String({ description: 'Search query (full-text)' })),
                 entityType: T.Optional(T.String({ description: 'Filter by entity type' })),
@@ -223,9 +305,9 @@ export function createGraphTools(workspaceManager, gitUser) {
                         count: results.length,
                         results: results.map(r => ({
                             repo: r.repoName,
-                            id: r.id,
-                            type: r.entityType,
-                            data: r.data,
+                            entityId: r.id,
+                            entityType: r.entityType,
+                            data: cleanData(r.data),
                         })),
                     });
                 }
@@ -254,9 +336,9 @@ export function createGraphTools(workspaceManager, gitUser) {
                         count: results.length,
                         results: results.map(r => ({
                             repo: r.repoName,
-                            id: r.id,
-                            type: r.entityType,
-                            data: r.data,
+                            entityId: r.id,
+                            entityType: r.entityType,
+                            data: cleanData(r.data),
                         })),
                     });
                 }
@@ -272,7 +354,7 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'get_related',
             label: 'Get Related Entities',
-            description: 'Get entities related to a given entity via wikilinks (cross-repo supported)',
+            description: 'Get entities related to a given entity via wikilinks (cross-repo supported). Pass repo, entityType, entityId from search/list results.',
             parameters: T.Object({
                 repo: T.String({ description: 'Repository name' }),
                 entityType: T.String({ description: 'Entity type' }),
@@ -286,9 +368,9 @@ export function createGraphTools(workspaceManager, gitUser) {
                         count: related.length,
                         related: related.map(r => ({
                             repo: r.repoName,
-                            id: r.id,
-                            type: r.entityType,
-                            data: r.data,
+                            entityId: r.id,
+                            entityType: r.entityType,
+                            data: cleanData(r.data),
                         })),
                     });
                 }
@@ -304,7 +386,7 @@ export function createGraphTools(workspaceManager, gitUser) {
         {
             name: 'get_backlinks',
             label: 'Get Backlinks',
-            description: 'Get entities that link to a given entity (cross-repo supported)',
+            description: 'Get entities that link to a given entity (cross-repo supported). Pass repo, entityType, entityId from search/list results.',
             parameters: T.Object({
                 repo: T.String({ description: 'Repository name' }),
                 entityType: T.String({ description: 'Entity type' }),
@@ -318,9 +400,9 @@ export function createGraphTools(workspaceManager, gitUser) {
                         count: backlinks.length,
                         backlinks: backlinks.map(r => ({
                             repo: r.repoName,
-                            id: r.id,
-                            type: r.entityType,
-                            data: r.data,
+                            entityId: r.id,
+                            entityType: r.entityType,
+                            data: cleanData(r.data),
                         })),
                     });
                 }
@@ -587,6 +669,72 @@ export function createGraphTools(workspaceManager, gitUser) {
                 }
             },
         },
+        // Find orphan entities
+        {
+            name: 'find_orphans',
+            label: 'Find Orphans',
+            description: 'Find entities with zero inbound wikilink references. Optionally tombstone them to exclude from future syncs.',
+            parameters: T.Object({
+                entityTypes: T.Optional(T.Array(T.String(), { description: 'Entity types to check (e.g. ["person", "client"])' })),
+                minAgeDays: T.Optional(T.Number({ description: 'Only flag entities older than N days' })),
+                repos: T.Optional(T.Array(T.String(), { description: 'Repo names to scan (default: all)' })),
+                tombstone: T.Optional(T.Boolean({ description: 'Add orphans to sync-state tombstones' })),
+            }),
+            execute: async (toolCallId, params) => {
+                try {
+                    const result = findOrphans(workspaceManager, {
+                        entityTypes: params.entityTypes,
+                        minAgeDays: params.minAgeDays,
+                        repos: params.repos,
+                    });
+                    // Tombstone if requested
+                    if (params.tombstone && workspacePath && result.orphans.length > 0) {
+                        const syncState = new SyncStateManager(workspacePath);
+                        for (const orphan of result.orphans) {
+                            syncState.addTombstone(orphan.entityId);
+                        }
+                    }
+                    // Group by type for summary
+                    const byType = {};
+                    for (const o of result.orphans) {
+                        byType[o.entityType] = (byType[o.entityType] || 0) + 1;
+                    }
+                    return wrapToolResult({
+                        success: true,
+                        totalScanned: result.totalScanned,
+                        totalOrphans: result.totalOrphans,
+                        tombstoned: params.tombstone ? result.totalOrphans : 0,
+                        byType,
+                        orphans: result.orphans.slice(0, 50), // limit response size
+                    });
+                }
+                catch (error) {
+                    return wrapToolResult({
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                }
+            },
+        },
+        // Highlight entities in graph view
+        {
+            name: 'highlight_entities',
+            label: 'Highlight Entities',
+            description: 'Highlight specific entities in the graph view. Pass entity IDs to highlight them (dimming all others). Pass an empty array to clear highlights.',
+            parameters: T.Object({
+                entityIds: T.Array(T.String(), { description: 'Entity IDs to highlight in the graph' }),
+            }),
+            execute: async (_toolCallId, params) => {
+                onHighlight?.(params.entityIds);
+                const count = params.entityIds.length;
+                return wrapToolResult({
+                    highlighted: count,
+                    message: count > 0
+                        ? `Highlighted ${count} entities in the graph.`
+                        : 'Cleared graph highlights.',
+                });
+            },
+        },
     ];
 }
 //# sourceMappingURL=graph-tools.js.map