studiograph 1.1.1 → 1.1.3

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,117 @@ 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 { loadSkillIndex, buildSkillIndexPrompt, loadEagerSkills } from './skills/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 { 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', 'bundled');
+        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 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 system prompt — base + eager skills + skill index
+        const systemPrompt = this.buildSystemPrompt(skillIndex);
+        // Built-in graph tools + load_skill tool
+        const tools = [
+            ...createGraphTools(this.workspaceManager, this.gitUser),
+            createLoadSkillTool(skillIndex),
+        ];
+        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.
      */
-    loadSystemPrompt() {
+    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, ...connectorTools];
+            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.
+     */
+    buildSystemPrompt(skillIndex) {
         const promptPath = join(__dirname, 'prompts', 'system.md');
-        if (!existsSync(promptPath)) {
-            // Fallback to basic prompt
-            return this.getDefaultSystemPrompt();
+        const base = existsSync(promptPath)
+            ? readFileSync(promptPath, 'utf-8')
+            : this.getDefaultSystemPrompt();
+        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);
+        }
+        // Inline eager skills directly into the system prompt
+        const eagerContent = loadEagerSkills(skillIndex);
+        if (eagerContent) {
+            parts.push(eagerContent);
         }
-        return readFileSync(promptPath, 'utf-8');
+        // 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 +136,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 +152,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,168 @@
+# 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 Conversational:**
+- Ask clarifying questions before taking action
+- 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 graph management tools that allow you to:
+- Create, read, update, delete entities
+- Search and filter entities across repos
+- Manage wikilinks and relationships
+- Upload and manage assets
+- Get workspace statistics
+- Query dataset rows with filters (`query_dataset`) and append new rows (`append_rows`)
+
+Use these tools to help users build and navigate 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/skills/bundled/enrich-entities.md

@@ -0,0 +1,124 @@
+---
+name: enrich-entities
+description: Proactively suggest enrichment for incomplete entities using context
+loading: eager
+---
+
+# Entity Enrichment
+
+When you discover incomplete entities (missing recommended fields), proactively suggest enrichment using contextual inference.
+
+## When to Enrich
+
+**Proactive discovery:**
+- User asks to "clean up" or "enrich" entities
+- You call `lint_entities` and find incomplete records
+- You fetch an entity and notice missing recommended fields
+
+**During normal work:**
+- User asks about a specific entity and you notice gaps
+- You're creating related entities and spot incomplete references
+
+## How to Enrich
+
+### 1. Discover gaps
+Use `lint_entities` to find incomplete entities:
+```
+lint_entities({ entityType: "project" })
+→ 12 projects missing client, start_date, or end_date
+```
+
+### 2. Gather context for each incomplete entity
+- **Fetch the entity:** `get_entity({ entityId: "..." })`
+- **Find related entities:** `get_backlinks({ entityId: "..." })`
+- **Search for references:** Look in meeting notes, proposals, briefs
+- **Check memory:** Review past conversations about this entity
+
+### 3. Infer missing values from context
+
+**Missing client:**
+- Search entity markdown body for `[[client-name]]` wikilinks
+- Check backlinks from meetings, proposals, deals
+- Look for client mentions in related artifacts
+
+**Missing dates:**
+- Extract from related meetings (kickoff = start_date)
+- Check proposal expected_start or contract signed_date
+- Look for date mentions in project description
+
+**Missing relationships:**
+- Scan for wikilinks in markdown body
+- Check what entities reference this one (backlinks)
+- Infer from entity type (artifact → deliverable → project)
+
+### 4. Suggest, don't assume
+Always confirm before updating:
+
+> "I notice this project is missing a client. I see Meridian Health mentioned in 3 related meetings and the project brief. Should I add `client: [[meridian-rebrand]]`?"
+
+Wait for user confirmation, then call `update_entity`.
+
+## Example Workflows
+
+**Batch enrichment:**
+```
+User: "Help me fill in missing clients for incomplete projects"
+
+You:
+1. lint_entities({ entityType: "project" }) → 8 missing client
+2. For each project:
+   - get_entity() → read markdown body
+   - get_backlinks() → find meetings, proposals
+   - Search for client wikilinks
+   - Suggest: "Add client: [[acme]]?" → confirm → update
+3. Report: "Enriched 6/8 projects. 2 need manual review (no clear client in context)."
+```
+
+**Focused enrichment:**
+```
+User: "Fill in missing deal values"
+
+You:
+1. lint_entities({ entityType: "deal" }) → 5 deals missing deal_value
+2. For each deal:
+   - get_backlinks() → find related proposal
+   - get_entity() on proposal → extract fees
+   - Suggest: "This deal's proposal shows $50k. Add deal_value: 50000?" → confirm → update
+```
+
+**Inline during work:**
+```
+User: "Show me the Acme project"
+
+You:
+1. get_entity({ entityId: "acme-rebrand" })
+2. Notice missing: client, start_date
+3. Get context: search for Acme client entity, check proposal
+4. Suggest inline: "This project is missing a client and start date. I found the Acme client entity and a proposal dated 2026-01-15. Should I add those?"
+```
+
+## Guidelines
+
+**Do:**
+- Use multiple context sources (backlinks, search, memory, markdown body)
+- Present evidence: "I see X mentioned in 3 meetings"
+- Batch similar fields: "Should I add client and start_date?"
+- Report progress: "Enriched 8/12, 4 need review"
+
+**Don't:**
+- Update without confirmation
+- Guess when evidence is weak ("I'm not sure which client this is")
+- Over-enrich — only fill recommended fields that are clearly missing
+- Make up data — if no context exists, say so: "I couldn't find a clear client reference. Would you like to specify it?"
+
+## Priority Fields
+
+Focus enrichment on high-value semantic fields:
+1. **Relationships** — client, project, deliverable (wikilinks)
+2. **Dates** — start_date, due_date, expected_close
+3. **People** — assignee, decision_makers, attendees
+4. **Values** — deal_value, fees, budget
+
+Low-priority (often intentionally omitted):
+- Tags, notes, optional descriptions
+- Status (user may want to set this themselves)

package/dist/agent/skills/bundled/gather-context.md

@@ -0,0 +1,46 @@
+---
+name: gather-context
+description: Gather full context on named entities before taking action
+loading: eager
+---
+
+# Context Gathering
+
+When a user references a specific named entity in their request, gather full context before proceeding:
+
+## When to Gather Context
+
+User mentions a specific entity by name:
+- "Help me write a proposal for Acme"
+- "Create a deck for the FII10 project"
+- "What's the status of the Meridian Health deliverables?"
+- "Find all open tasks for the Terra Finance project"
+
+## What to Gather
+
+1. **Fetch the named entity** — use `get_entity` to load the full record
+2. **Pull related entities** — use `get_backlinks` to find connections:
+   - For clients: related projects, deals, contacts, proposals
+   - For projects: client, deliverables, artifacts, meetings, decisions, tasks
+   - For deals: client, contacts, proposal documents
+3. **Check recent activity** — search for recent meetings, decisions, or tasks related to the entity
+4. **Load memory context** — check if there's relevant session memory about this entity
+
+## Example Flow
+
+User: "Help me write a proposal for Acme"
+
+**Before writing anything:**
+1. `get_entity({ repo: "clients", entityType: "client", entityId: "acme" })`
+2. `get_backlinks({ repo: "clients", entityType: "client", entityId: "acme" })`
+3. `search_entities({ query: "Acme", entityTypes: ["deal", "project", "person", "proposal"] })`
+4. Review memory for past Acme conversations
+
+**Then proceed** with full context to draft the proposal.
+
+## Important
+
+- Don't make assumptions about entity details — fetch them first
+- A few seconds gathering context saves minutes of back-and-forth
+- If the entity doesn't exist, offer to create it before proceeding
+- Present a brief context summary to the user before taking action: "I see Acme is a prospect with two past deals and three contacts on file. Let me draft a proposal..."