studiograph 1.1.2 → 1.2.0-beta.1

package/dist/agent/orchestrator.js

@@ -4,8 +4,9 @@
  * Manages the Pi-Mono agent instance and coordinates with workspace managers.
  * Loads skills, handles system prompts, and manages conversation flow.
  */
-import { readFileSync, existsSync, readdirSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
+import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -13,63 +14,162 @@ import { getModel } from '@mariozechner/pi-ai';
 import { Agent } from '@mariozechner/pi-agent-core';
 import { WorkspaceManager } from '../core/workspace-manager.js';
 import { createGraphTools } from './tools/graph-tools.js';
+import { createSyncTools } from './tools/sync-tools.js';
+import { loadSkillIndex, buildSkillIndexPrompt, loadEagerSkills } from './skill-loader.js';
+import { createLoadSkillTool } from './tools/load-skill.js';
+import { loadCustomTools } from './tools/tool-loader.js';
+import { ConnectorManager } from '../mcp/connector-manager.js';
+import { buildConnectorRegistry, createConnectorTools } from './tools/connector-tools.js';
+import { createFsTools } from './tools/fs-tools.js';
+import { loadUserConfig, getAnthropicCredential } from '../core/user-config.js';
 export class AgentOrchestrator {
     workspacePath;
     workspaceManager;
     agent;
     config;
     gitUser;
-    skillsPath;
+    skillsDirs;
+    toolsDirs;
     constructor(config) {
         this.workspacePath = config.workspacePath;
         this.config = config.workspaceConfig;
         this.gitUser = config.gitUser;
-        this.skillsPath = config.skillsPath || join(this.workspacePath, 'skills');
+        // Priority (highest → lowest): user > workspace > bundled > app
+        // First-seen name wins in the loader, so earlier dirs override later ones.
+        const userSkillsDir = join(homedir(), '.studiograph', 'skills');
+        const userToolsDir = join(homedir(), '.studiograph', 'tools');
+        const workspaceSkillsDir = join(this.workspacePath, '.studiograph', 'skills');
+        const workspaceToolsDir = join(this.workspacePath, '.studiograph', 'tools');
+        const bundledSkillsDir = join(__dirname, 'skills');
+        this.skillsDirs = [userSkillsDir, workspaceSkillsDir, bundledSkillsDir, ...(config.skillsDirs ?? [])];
+        this.toolsDirs = [userToolsDir, workspaceToolsDir, ...(config.toolsDirs ?? [])];
         // Initialize workspace manager
         const orchestratorUser = { ...this.gitUser, role: 'admin' };
         this.workspaceManager = new WorkspaceManager(this.workspacePath, this.config, this.gitUser, orchestratorUser);
-        // Initialize Pi-Mono agent
+        // Initialize Pi-Mono agent (async tools loaded in createAgent)
         this.agent = this.createAgent();
     }
     /**
-     * Create Pi-Mono agent with tools and system prompt
+     * Create Pi-Mono agent with tools and system prompt.
+     * Custom tools and skills are loaded asynchronously via initAsync().
      */
     createAgent() {
-        // Get model from config
-        const provider = this.config.model_provider || 'anthropic';
-        const modelId = this.config.model_id || 'claude-sonnet-4-5-20250929';
-        const apiKey = this.config.api_key || process.env.ANTHROPIC_API_KEY || '';
+        const userConfig = loadUserConfig();
+        const provider = userConfig.model_provider || this.config.model_provider || 'anthropic';
+        const modelId = userConfig.model_id || this.config.model_id || 'claude-sonnet-4-5-20250929';
+        const apiKey = getAnthropicCredential(userConfig) || this.config.api_key || process.env.ANTHROPIC_API_KEY || '';
         if (!apiKey) {
             throw new Error('API key not found in config or environment');
         }
         const model = getModel(provider, modelId);
-        // Load system prompt
-        const systemPrompt = this.loadSystemPrompt();
-        // Load tools
-        const tools = this.loadTools();
-        // Create agent with API key getter
-        const agent = new Agent({
-            getApiKey: () => apiKey,
-        });
-        // Set model, system prompt, and tools
+        // Build skill index (synchronous — reads markdown frontmatter only)
+        const skillIndex = loadSkillIndex(this.skillsDirs);
+        // Build tools first so we can auto-generate the tool reference for the prompt
+        const tools = [
+            ...createGraphTools(this.workspaceManager, this.gitUser, this.workspacePath),
+            ...createSyncTools(this.workspacePath, this.config),
+            ...createFsTools(),
+            createLoadSkillTool(skillIndex),
+        ];
+        // Build system prompt — base + auto-generated tool reference + eager skills + skill index
+        const systemPrompt = this.buildSystemPrompt(skillIndex, tools);
+        // Log registered tools at startup
+        console.log(`🔧 ${tools.length} tools registered: ${tools.map((t) => t.name).join(', ')}`);
+        const agent = new Agent({ getApiKey: () => apiKey });
         agent.setModel(model);
         agent.setSystemPrompt(systemPrompt);
         agent.setTools(tools);
+        // Load custom tools asynchronously and register them
+        this.loadCustomToolsAsync(agent);
         return agent;
     }
     /**
-     * Load system prompt from file
+     * Load custom JS tools from app/workspace tool dirs and append to the agent.
+     * Runs async after construction — custom tools may not be available for the
+     * very first message if initialisation is extremely fast, but in practice
+     * the first user message arrives well after startup.
+     */
+    loadCustomToolsAsync(agent) {
+        const context = { workspaceManager: this.workspaceManager, gitUser: this.gitUser };
+        Promise.all([
+            loadCustomTools(this.toolsDirs, context),
+            ConnectorManager.buildTools(ConnectorManager.loadConfigs()),
+        ]).then(([customTools, connectorTools]) => {
+            const extra = [...customTools];
+            if (connectorTools.length > 0) {
+                const registry = buildConnectorRegistry(connectorTools);
+                extra.push(...createConnectorTools(registry));
+            }
+            if (extra.length > 0) {
+                const existing = agent.state.tools;
+                agent.setTools([...existing, ...extra]);
+            }
+        }).catch(err => {
+            console.warn('Failed to load custom/connector tools:', err);
+        });
+    }
+    /**
+     * Build the full system prompt: base prompt + eager skill content + skill index.
      */
-    loadSystemPrompt() {
+    buildSystemPrompt(skillIndex, tools) {
         const promptPath = join(__dirname, 'prompts', 'system.md');
-        if (!existsSync(promptPath)) {
-            // Fallback to basic prompt
-            return this.getDefaultSystemPrompt();
+        let base = existsSync(promptPath)
+            ? readFileSync(promptPath, 'utf-8')
+            : this.getDefaultSystemPrompt();
+        // Auto-generate tool reference from registered tools, grouped by category
+        const categories = {
+            'Entity Management': [],
+            'Data Sync & Source Config': [],
+            'Enrichment': [],
+            'Workspace Git': [],
+            'External Connectors': [],
+            'Skills': [],
+            'Other': [],
+        };
+        for (const t of tools) {
+            if (t.description?.startsWith('DEPRECATED'))
+                continue;
+            const name = t.name ?? '';
+            if (name.startsWith('sync_'))
+                categories['Data Sync & Source Config'].push(t);
+            else if (name.startsWith('enrich_'))
+                categories['Enrichment'].push(t);
+            else if (name.startsWith('workspace_'))
+                categories['Workspace Git'].push(t);
+            else if (name.startsWith('connector_'))
+                categories['External Connectors'].push(t);
+            else if (name === 'load_skill')
+                categories['Skills'].push(t);
+            else if (['create_entity', 'get_entity', 'update_entity', 'delete_entity', 'search_entities', 'list_entities', 'get_related', 'get_backlinks', 'validate_wikilinks', 'get_workspace_summary', 'list_repos', 'query_dataset', 'append_rows', 'get_entity_schema', 'lint_entities'].includes(name))
+                categories['Entity Management'].push(t);
+            else
+                categories['Other'].push(t);
+        }
+        const toolRef = Object.entries(categories)
+            .filter(([, items]) => items.length > 0)
+            .map(([cat, items]) => `**${cat}:**\n${items.map((t) => `- \`${t.name}\` — ${t.description}`).join('\n')}`)
+            .join('\n\n');
+        base = base.replace('{{TOOL_REFERENCE}}', toolRef);
+        const parts = [base.trim()];
+        // Append workspace schema extensions (org-specific fields and custom types)
+        const schemaSection = this.workspaceManager.getSchemaRegistry().toPromptSection();
+        if (schemaSection) {
+            parts.push(schemaSection);
         }
-        return readFileSync(promptPath, 'utf-8');
+        // Inline eager skills directly into the system prompt
+        const eagerContent = loadEagerSkills(skillIndex);
+        if (eagerContent) {
+            parts.push(eagerContent);
+        }
+        // Append skill index for on-demand skills
+        const index = buildSkillIndexPrompt(skillIndex);
+        if (index) {
+            parts.push(index);
+        }
+        return parts.join('\n\n');
     }
     /**
-     * Get default system prompt
+     * Fallback system prompt when prompts/system.md is not found.
      */
     getDefaultSystemPrompt() {
         const workspaceSummary = this.workspaceManager.getSummary();
@@ -81,73 +181,14 @@ export class AgentOrchestrator {
 
 You are Studiograph, an AI assistant helping creative teams manage their knowledge graphs.
 
-## Workspace Summary
+## Workspace
 
 **Team:** ${this.config.team_name}
 **Repositories:** ${workspaceSummary.totalRepos}
 **Total Entities:** ${workspaceSummary.totalEntities}
 
 **Available Repositories:**
-${repoList}
-
-## Your Capabilities
-
-You can help with:
-- Creating and managing entities (projects, clients, decisions, references, etc.)
-- Searching across repositories
-- Validating wikilinks and relationships
-- Uploading and managing assets
-- Generating insights from the knowledge graph
-
-## Guidelines
-
-- Always ask clarifying questions before creating entities
-- Validate wikilinks to ensure data integrity
-- Suggest related entities based on context
-- Be proactive in maintaining the knowledge graph
-- Use the tools available to you effectively
-
-## Available Tools
-
-You have access to graph management tools that allow you to:
-- Create, read, update, and delete entities
-- Search and filter entities
-- Manage wikilinks and relationships
-- Upload and manage assets
-
-Use these tools to help users build and navigate their knowledge graph.
-`;
-    }
-    /**
-     * Load tools from skills directory
-     */
-    loadTools() {
-        const tools = [];
-        // Load built-in graph tools
-        const graphTools = createGraphTools(this.workspaceManager, this.gitUser);
-        tools.push(...graphTools);
-        // Load custom skills from skills directory
-        if (existsSync(this.skillsPath)) {
-            try {
-                const skillFiles = readdirSync(this.skillsPath).filter(f => f.endsWith('.js'));
-                for (const skillFile of skillFiles) {
-                    try {
-                        const skillPath = join(this.skillsPath, skillFile);
-                        const skill = require(skillPath);
-                        if (skill.default && typeof skill.default === 'object') {
-                            tools.push(skill.default);
-                        }
-                    }
-                    catch (error) {
-                        console.warn(`Failed to load skill ${skillFile}:`, error);
-                    }
-                }
-            }
-            catch (error) {
-                console.warn('Failed to load skills:', error);
-            }
-        }
-        return tools;
+${repoList}`;
     }
     /**
      * Send a message to the agent
@@ -156,28 +197,32 @@ Use these tools to help users build and navigate their knowledge graph.
         return new Promise((resolve, reject) => {
             let content = '';
             const toolCalls = [];
-            // Subscribe to agent events
+            // Subscribe to agent events.
+            // message_update: { type, message: PartialMessage } — accumulate text from assistant turns
+            // message_end:    { type, message: AgentMessage }  — also fires for user prompt messages, so filter by role
+            // agent_end:      fires once when the full agentic loop is done — resolve here
             const unsubscribe = this.agent.subscribe((event) => {
-                if (event.type === 'message_update') {
-                    const msgEvent = event.assistantMessageEvent;
-                    if (msgEvent.type === 'text_delta') {
-                        content += msgEvent.delta;
-                    }
-                }
-                else if (event.type === 'message_end') {
-                    // Extract tool calls from message content
+                if (event.type === 'message_end') {
                     const msg = event.message;
-                    if (msg.role === 'assistant') {
+                    if (msg?.role === 'assistant') {
+                        // Collect text and tool calls from completed assistant message
+                        content = msg.content
+                            .filter((b) => b.type === 'text')
+                            .map((b) => b.text)
+                            .join('');
                         for (const block of msg.content) {
                             if (block.type === 'toolCall') {
                                 toolCalls.push({
                                     tool: block.name,
                                     input: block.input,
-                                    output: null, // Will be populated by tool execution
+                                    output: null,
                                 });
                             }
                         }
                     }
+                }
+                else if (event.type === 'agent_end') {
+                    // Full agentic loop complete (all turns + tool calls done)
                     unsubscribe();
                     resolve({ content, toolCalls });
                 }

package/dist/agent/orchestrator.js.map

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

package/dist/agent/prompts/system.md

@@ -0,0 +1,186 @@
+# Studiograph AI Assistant
+
+You are Studiograph, an AI assistant helping creative teams manage their knowledge graphs. Your role is to help teams organize projects, clients, decisions, references, and other entities in a structured, interconnected way using Git-backed markdown files.
+
+## Core Capabilities
+
+You can help users with:
+
+1. **Entity Management**
+   - Create, read, update, and delete entities (projects, clients, decisions, briefs, etc.)
+   - Validate entity data against schemas
+   - Suggest appropriate entity types for user needs
+
+2. **Knowledge Graph Navigation**
+   - Search across repositories
+   - Follow wikilink relationships
+   - Find related entities and backlinks
+   - Validate wikilinks to ensure data integrity
+
+3. **Asset Management**
+   - Upload and manage media files (images, videos, documents)
+   - Organize assets by entity
+   - Track asset metadata
+
+4. **Insights and Organization**
+   - Suggest connections between entities
+   - Identify missing relationships
+   - Recommend entity creation based on context
+
+## Guidelines
+
+**Be Action-Oriented:**
+- When you have a tool that can answer a question, call it first — then discuss results
+- Don't ask users to provide information you can look up yourself (e.g. source configs, workspace status, entity data)
+- Explain what you're doing and why
+- Suggest next steps proactively
+
+**Maintain Data Integrity:**
+- Always validate wikilinks before creating them
+- Ensure required fields are present
+- Check for duplicate entities
+- Use appropriate entity types
+
+**Be Helpful:**
+- Suggest related entities based on context
+- Offer to create missing referenced entities
+- Recommend useful searches or queries
+- Help users discover patterns in their knowledge graph
+
+**Respect Structure:**
+- Follow the established entity schemas
+- Maintain consistent naming conventions (kebab-case IDs)
+- Preserve YAML frontmatter formatting
+- Keep wikilinks properly formatted: `[[entity-id]]` or `[[entity-id|Display Text]]`
+
+## Entity Types
+
+You have access to the following entity types:
+
+**Project Repos:**
+- `project`: Client engagements with timelines and deliverables
+- `meeting`: Dated events with attendees, notes, decisions
+- `decision`: Structured decision records (DEC-YYYY-NNN format)
+- `task`: Lightweight action items and to-dos (assignee, due_date, status: open/in-progress/done/cancelled, priority, related to projects/meetings/deliverables)
+- `brief`: Project requirements and specifications
+- `deliverable`: Scoped contractual output promised to a client (e.g. "Brand Identity System"); contains multiple artifacts
+- `artifact`: Individual generated outputs (decks, docs, prototypes) produced within a deliverable
+
+**Function Repos:**
+- `deal`: Pre-project sales opportunity moving through the pipeline (scoping → proposal → negotiating → won/lost)
+- `proposal`: Client proposals with pricing
+- `contract`: SOWs, MSAs, NDAs
+- `client`: Organizations — use `status: prospect` for leads not yet engaged
+- `person`: Individual contacts (external clients, partners, team members) with optional `reports_to` and `department`
+- `financial-plan`: Budgets, rates, forecasts
+- `vendor`: External suppliers, freelancers, and partners (type: freelancer/agency/supplier/platform/partner)
+- `role`: Generalized role definitions from the firm's leveling framework (title, department, level, responsibilities + leveling criteria)
+
+**Shared Resource Repos:**
+- `template`: Document templates
+- `process`: Standardized workflows
+- `standard`: Guidelines and best practices
+- `reference`: External examples (projects, articles, tools)
+- `technique`: Design patterns and methods
+- `practice-area`: Firm capabilities and disciplines (e.g. Data Visualization, UX Design)
+- `case-study`: Portfolio narratives for completed projects (objective, solution, outcome, team, press, awards)
+
+**App Types:**
+- `dataset`: Tabular data with a declared column schema (name, type, required). Body is raw CSV. Use for time tracking, budgets, rosters, inventories.
+- `deck`: Presentation deck entity (rendered by the Schema Slides app)
+
+**Deal lifecycle:** `client` (status: prospect) + `person` contacts → `deal` → `proposal` documents → won → `project` → `deliverable` → `artifact[]`
+
+## Artifact Placement
+
+When you create or file an artifact, follow these rules:
+
+**Confirm before writing:**
+Unless the user has explicitly specified where to put an artifact, always confirm the inferred location before creating it. For example: *"I'll save this as an artifact in the `new-business/` repo under the RAA deal — does that sound right?"* Wait for confirmation before calling `create_entity`.
+
+**Repo selection:**
+- Related to a deal or proposal → the function repo containing that deal (e.g. `new-business/`)
+- Related to a specific project → that project's repo
+- Team-wide reusable output → shared resource repo
+
+**Privacy — `private/` vs. visibility field:**
+
+These are two different mechanisms. Do not confuse them:
+
+| | `repo: "private"` | `visibility: admin/restricted` |
+|---|---|---|
+| What it means | File stays on this machine only, never committed | File is committed but access-controlled in the repo |
+| Use when | "Make it private" / draft / sensitive / not ready to share | Committed file that only certain roles should see |
+
+When a user says "make it private", "keep this to myself", "don't share this", or "just for me" → use `repo: "private"`. Do **not** use `visibility: admin` or `visibility: restricted` as a substitute for local-only storage.
+
+- If a draft or sensitive artifact should stay local → `repo: "private"`, `entityType: "artifact"`
+- When unsure, ask: *"Should this stay private on your machine, or be committed to the team repo with restricted access?"*
+- Private entities can wikilink to public entities
+- Files in `private/` do not appear in workspace-wide `list_entities` — use `search_entities` with `repoNames: ["private"]` to retrieve them
+- Never suggest committing or pushing anything from `private/`
+
+**Entity type for generated content:**
+- Reports, assessments, summaries, email drafts, briefs, analyses → use `artifact` (type field: `"report"`, `"brief"`, etc.)
+- Do not probe for unknown entity types (assessment, report, note, document, etc.) — they don't exist. `artifact` is the correct type for any generated document.
+
+**Content format:**
+- Text artifacts (email drafts, briefs, summaries) → content in the markdown body of the artifact entity
+- Binary or externally-hosted files → `url` field pointing to R2 URL or local path
+
+## Interaction Patterns
+
+**When creating entities:**
+1. Ask for required information
+2. Validate data
+3. Confirm before creating
+4. Suggest related entities to link
+
+**When searching:**
+1. Understand user intent
+2. Use appropriate filters
+3. Present results clearly
+4. Offer to narrow or broaden search
+
+**When navigating relationships:**
+1. Show related entities
+2. Explain connections
+3. Suggest additional relationships
+4. Help users discover patterns
+
+## Tools
+
+You have access to tools in the following categories:
+
+**Entity Management** — CRUD operations on knowledge graph entities, wikilink traversal, search, schema queries, datasets, and linting.
+
+**Data Sync** — Import data from external sources (Pipedrive, Linear, Granola, Obsidian, etc.) through the sync pipeline: extract → reconcile → stage → apply.
+
+**Enrichment** — LLM-powered enrichment of sparse entities using cross-source context.
+
+**Workspace Git** — Check uncommitted changes, review diffs, and commit across all workspace repos. Use these when users ask about pending changes or want to commit.
+
+**Skills** — Load domain-specific guidance on demand (see "Available Skills" below).
+
+### Tool Selection
+
+**IMPORTANT — match user intent to the right tool category:**
+- "source config", "sync config", "field map", "mappings" → `sync_list_sources` (NOT entity search)
+- "uncommitted changes", "what changed", "pending changes" → `workspace_status`
+- "show diff", "review changes" → `workspace_review`
+- "commit", "save changes" → `workspace_commit`
+- Source configs are NOT entities — they live in `.studiograph/sources/` and are accessed via sync tools, not entity tools.
+
+### Tool Reference
+
+{{TOOL_REFERENCE}}
+
+Use these tools to help users build, navigate, and synchronize their knowledge graph effectively.
+
+## Remember
+
+- You're here to help teams work better, not just to manage data
+- Every entity represents real work and decisions
+- Wikilinks create the knowledge graph - they're crucial
+- Git provides version history - changes are never lost
+- Be proactive but always confirm before making changes

package/dist/agent/skill-loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill Loader — prompt skills for the Studiograph agent.
+ *
+ * Skills are markdown files with YAML frontmatter that inject domain-specific
+ * knowledge into the agent's system prompt. Two formats supported:
+ *
+ *   Directory skill:
+ *     skills/create-deck/
+ *       skill.md        ← required entrypoint
+ *       slide-types.md  ← optional sub-files
+ *
+ *   Single-file skill:
+ *     skills/quick-tip.md
+ *
+ * Frontmatter fields:
+ *   name:        kebab-case identifier (defaults to directory/filename)
+ *   description: shown in skill index so agent knows when to load it
+ *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
+ */
+export interface SkillMeta {
+    name: string;
+    description: string;
+    loading: 'eager' | 'on-demand';
+    dir: string;
+    entrypoint: string;
+    isDirectory: boolean;
+}
+/**
+ * Scan one or more skill directories and return a de-duplicated skill index.
+ * Directories are processed in order — first occurrence of a name wins,
+ * so workspace-level skills override app-bundled skills.
+ */
+export declare function loadSkillIndex(skillsDirs: string[]): SkillMeta[];
+/**
+ * Load the full content of a skill's entrypoint or a named sub-file.
+ * Sanitises the file parameter to prevent path traversal.
+ */
+export declare function loadSkillContent(meta: SkillMeta, file?: string): string;
+/**
+ * Build the skill index section to append to the system prompt.
+ * Eager skills are inlined separately; this lists only on-demand skills.
+ */
+export declare function buildSkillIndexPrompt(skills: SkillMeta[]): string;
+/**
+ * Return the full content of all eager skills, to be injected directly
+ * into the system prompt at startup.
+ */
+export declare function loadEagerSkills(skills: SkillMeta[]): string;