studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/agent/orchestrator.js

@@ -10,10 +10,14 @@ import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-import { getModel } from '@mariozechner/pi-ai';
-import { Agent } from '@mariozechner/pi-agent-core';
+import { getModel, completeSimple } from '@earendil-works/pi-ai';
+import { Agent } from '@earendil-works/pi-agent-core';
 import { WorkspaceManager } from '../core/workspace-manager.js';
+import { resolveUtilityModelConfig } from '../services/utility-model-resolver.js';
+import { findPersonRefForUser } from '../services/user-person-bridge.js';
 import { createGraphTools } from './tools/graph-tools.js';
+import { createFolderTools } from './tools/folder-tools.js';
+import { createHistoryTools } from './tools/history-tools.js';
 import { loadSkillIndex, buildSkillIndexPrompt, loadEagerSkills } from './skill-loader.js';
 import { createLoadSkillTool } from './tools/load-skill.js';
 import { loadCustomTools } from './tools/tool-loader.js';
@@ -23,12 +27,20 @@ import { createFsTools } from './tools/fs-tools.js';
 import { createWebTools } from './tools/web-tools.js';
 import { createOpsTools } from './tools/ops-tools.js';
 import { createPermissionTools } from './tools/permission-tools.js';
-import { createMessageTools } from './tools/message-tools.js';
+import { createCaptureTools } from './tools/capture-tools.js';
+import { createArtifactTools, hashArtifactBody, artifactTruncationToolResult } from './tools/artifact-tools.js';
+import { validateArtifactBundle } from '../core/artifact-frame-model.js';
 import { renderEntityTypesSection } from './prompts/entity-types-section.js';
 import { ENTITY_SCHEMAS } from '../core/validation.js';
 import { AuthService } from '../services/auth-service.js';
+import * as access from '../services/access-control.js';
 import { loadUserConfig, resolveApiKey, resolveProvider, resolveModelId } from '../core/user-config.js';
+import { supportsVision } from '../services/model-capabilities.js';
+import { onSecretMutation } from '../core/secrets/index.js';
 import { AgentPool } from './agent-pool.js';
+import { manageContext } from './context-window.js';
+import { addInferenceUsage, createCloudInferenceStreamFn, createInferenceUsageSummary, isStudiographCreditsMode, studiographCreditsModel, } from '../services/cloud-inference-billing.js';
+import { recordAiUsage } from '../services/ai-usage-ledger.js';
 export class AgentOrchestrator {
     workspacePath;
     workspaceManager;
@@ -39,10 +51,11 @@ export class AgentOrchestrator {
     toolsDirs;
     registryRef = { registry: null };
     authService;
-    messageService = null;
+    commentService;
+    chatSessionService;
+    mintInspectAssets;
     recentMemory;
     sessionsDir;
-    onEntityContentMutation;
     // Per-session context — used by tool closures via the pool's contextMap
     // Legacy fields kept for backward compat with callers that set them before chat()
     _currentUser = null;
@@ -55,9 +68,15 @@ export class AgentOrchestrator {
         this.config = config.workspaceConfig;
         this.gitUser = config.gitUser;
         this.recentMemory = config.recentMemory;
-        this.authService = new AuthService(config.workspacePath);
-        this.messageService = config.messageService ?? null;
-        this.onEntityContentMutation = config.onEntityContentMutation;
+        // Prefer the route-level AuthService so we share the master-key
+        // crypto wiring + the OAuth-mutation pubsub. Fallback construction
+        // only fires in tests / CLI scenarios that don't supply one — those
+        // paths don't read encrypted oauth_tokens, so the missing crypto is
+        // harmless there.
+        this.authService = config.authService ?? new AuthService(config.workspacePath);
+        this.commentService = config.commentService ?? null;
+        this.chatSessionService = config.chatSessionService ?? null;
+        this.mintInspectAssets = config.mintInspectAssets;
         this.sessionsDir = join(homedir(), '.studiograph', 'sessions');
         // Skills: filesystem dirs are now bundled-only. User/workspace authoring
         // moves to graph `skill` entities (enumerated per-user in createAgentInstance).
@@ -70,9 +89,30 @@ export class AgentOrchestrator {
         // Initialize agent pool — each session gets its own Agent instance
         this.pool = new AgentPool({
             createAgent: (userId) => this.createAgentInstance(userId),
-            loadCustomTools: (agent) => this.loadCustomToolsAsync(agent),
+            loadCustomTools: (agent, userId) => this.loadCustomToolsAsync(agent, userId),
             sessionsDir: this.sessionsDir,
         });
+        // Evict cached agents when an operator changes a model.* key via
+        // Settings UI / CLI. Without this, the running agent keeps using
+        // the apiKey/provider/modelId it captured at createAgentInstance
+        // time, and the operator's rotation appears to have no effect
+        // until the next process restart. Other keys (r2.*, search.*) are
+        // read fresh on each tool call, so eviction isn't needed for them.
+        onSecretMutation((key) => {
+            if (key.startsWith('model.')) {
+                this.pool.invalidateAll();
+            }
+        });
+        // Evict the user's pooled agent when their OAuth state changes.
+        // ConnectorManager.buildTools resolves per-user OAuth at agent-
+        // construction time only; mid-session connect/disconnect would
+        // otherwise leave the agent with a stale tool list (the connector
+        // would stay invisible after Connect, or stay visible after
+        // Disconnect). Scoped per-user — other users' sessions are
+        // untouched.
+        this.authService.onOAuthMutation((userId) => {
+            this.pool.invalidateUser(userId);
+        });
     }
     /**
      * Create Pi-Mono agent with tools and system prompt.
@@ -80,18 +120,22 @@ export class AgentOrchestrator {
      */
     createAgentInstance(userId) {
         const userConfig = loadUserConfig();
-        const provider = resolveProvider(userConfig, this.config);
-        const modelId = resolveModelId(userConfig, this.config);
-        const apiKey = resolveApiKey(userConfig, this.config);
+        const useCreditsGateway = isStudiographCreditsMode();
+        const provider = useCreditsGateway ? 'studiograph-cloud' : resolveProvider(userConfig, this.config);
+        const modelId = useCreditsGateway ? studiographCreditsModel().id : resolveModelId(userConfig, this.config);
+        const apiKey = useCreditsGateway ? 'studiograph-cloud-gateway' : resolveApiKey(userConfig, this.config);
         if (!apiKey) {
             throw new Error('API key not found in config or environment');
         }
-        const model = getModel(provider, modelId);
+        const model = useCreditsGateway
+            ? studiographCreditsModel()
+            : getModel(provider, modelId);
         // Build skill index — bundled filesystem skills + graph `skill` entries
         // from folders the user can access. Graph skills take priority over
         // bundled on name collision (user-authored overrides can customise
         // built-in skills).
-        const graphSkills = this.enumerateGraphSkills(userId);
+        const promptRepos = this.getPromptRepoScope(userId);
+        const graphSkills = this.enumerateGraphSkills(promptRepos, userId);
         const bundledSkills = loadSkillIndex(this.skillsDirs);
         const seen = new Set(graphSkills.map((s) => s.name));
         const skillIndex = [...graphSkills, ...bundledSkills.filter(s => !seen.has(s.name))];
@@ -105,6 +149,13 @@ export class AgentOrchestrator {
             const sid = this.pool.findSessionForAgent(agent);
             return sid ? (this.pool.getContext(sid).user ?? null) : this._currentUser;
         };
+        // The raw client session id for the active turn (scratch images are keyed by
+        // it). Resolved per call from the pool context so session-scoped tools target
+        // the current conversation. Null for non-web contexts that set no context.
+        const getActiveSessionId = () => {
+            const sid = this.pool.findSessionForAgent(agent);
+            return sid ? (this.pool.getContext(sid).clientSessionId ?? null) : null;
+        };
         const onHighlight = (ids) => {
             const sid = this.pool.findSessionForAgent(agent);
             if (sid)
@@ -119,35 +170,214 @@ export class AgentOrchestrator {
             else
                 this._mutationCallback?.(m);
         };
-        const onContentSync = this.onEntityContentMutation;
+        const onArtifact = (bundle, target, options) => {
+            const sid = this.pool.findSessionForAgent(agent);
+            if (sid)
+                return this.pool.getContext(sid).onArtifact?.(bundle, target, options);
+        };
+        const readArtifact = (target) => {
+            const sid = this.pool.findSessionForAgent(agent);
+            const ctx = sid ? this.pool.getContext(sid) : { user: this._currentUser };
+            const effectiveTarget = target?.entityId ? target : ctx.currentArtifactTarget;
+            if (!effectiveTarget?.entityId) {
+                throw new Error('No artifact target is available. Pass target.entityId or open an artifact canvas first.');
+            }
+            if (!effectiveTarget.repo) {
+                throw new Error('Artifact target repo is required when inspecting by target.');
+            }
+            if (!access.hasRepoAccess(ctx.user ?? undefined, effectiveTarget.repo, this.workspaceManager, this.authService)) {
+                throw new Error(`Folder "${effectiveTarget.repo}" not found`);
+            }
+            const graph = this.workspaceManager.getGraph(effectiveTarget.repo);
+            const entity = graph.get('artifact', effectiveTarget.entityId);
+            // Prefer the live editor Y.Doc body over disk (matches get_entity /
+            // patch_entity), so the agent edits what the user currently sees and the
+            // hash matches the write-time guard's view of "current".
+            const body = graph.getLiveBody('artifact', effectiveTarget.entityId) ?? entity.document.content;
+            let rawBundle;
+            try {
+                rawBundle = JSON.parse(body);
+            }
+            catch {
+                throw new Error(`Artifact ${effectiveTarget.repo}/${effectiveTarget.entityId} body is not a valid JSON bundle.`);
+            }
+            const validation = validateArtifactBundle(rawBundle);
+            if (!validation.ok || !validation.bundle) {
+                throw new Error(`Invalid artifact bundle: ${validation.errors.join('; ')}`);
+            }
+            return {
+                bundle: validation.bundle,
+                hash: hashArtifactBody(body),
+                updatedAt: typeof entity.data?.updated_at === 'string' ? entity.data.updated_at : undefined,
+            };
+        };
+        // Resolve the server origin + a signed asset token for inspect_artifact's
+        // headless render, so workspace `/api/assets/...` images load instead of
+        // showing the broken-image placeholder. Mirrors readArtifact's target
+        // resolution; degrades to null when no mint is injected or no persisted
+        // target is in scope (e.g. an unsaved inline bundle).
+        const resolveInspectAssets = (target, bundle) => {
+            if (!this.mintInspectAssets)
+                return null;
+            const sid = this.pool.findSessionForAgent(agent);
+            const ctx = sid ? this.pool.getContext(sid) : { user: this._currentUser };
+            const effectiveTarget = target?.entityId ? target : ctx.currentArtifactTarget;
+            if (!effectiveTarget?.entityId || !effectiveTarget.repo)
+                return null;
+            const userId = String(ctx.user?.id ?? this._sessionUserId ?? '0');
+            try {
+                return this.mintInspectAssets(effectiveTarget.repo, effectiveTarget.entityId, bundle, userId);
+            }
+            catch {
+                return null;
+            }
+        };
+        const onAgentActivity = (action, repo) => {
+            const sid = this.pool.findSessionForAgent(agent);
+            if (sid)
+                this.pool.getContext(sid).onAgentActivity?.(action, repo);
+        };
+        /** Resolves the per-session capture callback at tool-call time. The
+         *  capture flow installs it via AgentContext; other flows leave it
+         *  undefined and the tool becomes a no-op acknowledgement. */
+        const getNothingToCaptureCallback = () => {
+            const sid = this.pool.findSessionForAgent(agent);
+            if (!sid)
+                return undefined;
+            return this.pool.getContext(sid).onNothingToCapture ?? undefined;
+        };
         const tools = [
-            ...createGraphTools(this.workspaceManager, this.gitUser, this.workspacePath, onHighlight, onMutation, getUser, this.authService, onContentSync),
+            ...createGraphTools(this.workspaceManager, this.gitUser, this.workspacePath, onHighlight, onMutation, getUser, this.authService, onAgentActivity, this.commentService, this.chatSessionService, getActiveSessionId),
+            ...createFolderTools(this.workspaceManager, this.gitUser, onMutation, getUser, this.authService, onAgentActivity),
+            ...createHistoryTools(this.workspaceManager, this.gitUser, onMutation, getUser, this.authService, onAgentActivity),
             ...createOpsTools(this.workspacePath, this.config),
-            ...createPermissionTools(this.authService, getUser),
+            ...createPermissionTools(this.authService, getUser, this.workspaceManager),
             ...createFsTools(getUser),
             ...createWebTools(this.config.search),
-            ...(this.messageService ? createMessageTools(this.messageService, getUser, this.authService) : []),
+            ...createCaptureTools(getNothingToCaptureCallback),
+            ...createArtifactTools(onArtifact, { readArtifact, resolveInspectAssets }),
             createLoadSkillTool(skillIndex, graphResolver),
         ];
-        // Load per-user briefing memo (if userId known)
-        let briefingText;
-        if (userId) {
-            const cached = this.authService.getCachedBriefing(userId);
-            if (cached.briefingText)
-                briefingText = cached.briefingText;
-        }
-        // Build system prompt — base + auto-generated tool reference + memory + briefing + eager skills + skill index
-        const systemPrompt = this.buildSystemPrompt(skillIndex, tools, this.recentMemory, briefingText, graphResolver);
+        // Build system prompt — base + auto-generated tool reference + memory + eager skills + skill index
+        const systemPrompt = this.buildSystemPrompt(skillIndex, tools, this.recentMemory, graphResolver, promptRepos, userId);
         // Log registered tools at startup (verbose only)
         if (process.env.STUDIOGRAPH_VERBOSE === '1') {
             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);
+        // Dedup the bundled tools array — guards against any future
+        // createXxxTools() collision so we never hand a duplicate-name list
+        // to the Agent constructor (Anthropic 400s on `tools: Tool names must
+        // be unique.`).
+        const dedupedTools = [];
+        const bundledSeen = new Set();
+        for (const t of tools) {
+            const name = t.name;
+            if (!name || bundledSeen.has(name))
+                continue;
+            bundledSeen.add(name);
+            dedupedTools.push(t);
+        }
+        // Proactive context-window manager. pi-agent-core calls `transformContext`
+        // once before every LLM request, non-destructively producing the message
+        // array sent to the provider (the persistent transcript in
+        // agent.state.messages — saved to disk / shown in the UI — is untouched).
+        // We estimate tokens and, when a request would overflow the model's window,
+        // stub oversized tool results / evict oldest turns / truncate an over-large
+        // latest turn so the request fits — instead of letting the provider 400 the
+        // whole conversation. The estimator is deliberately conservative (see
+        // context-window.ts); the hook MUST NOT throw (runtime contract), so on any
+        // error we fall back to the untrimmed messages.
+        const transformContext = async (messages) => {
+            try {
+                const { messages: out, stats } = manageContext({
+                    messages,
+                    systemPrompt,
+                    model: model,
+                    // Use the LIVE tool list, not the captured `dedupedTools`: per-user
+                    // connector + custom tools are appended to `agent.state.tools` by
+                    // loadCustomToolsAsync AFTER construction and ride in every request,
+                    // so estimating with the initial set would undercount the schema
+                    // overhead and let a near-limit prompt skip trimming. `agent` is
+                    // assigned just below; this closure only runs at request time, by
+                    // which point it's initialized.
+                    tools: agent.state.tools,
+                });
+                // Log whenever we're at/over budget or actually trimmed — rare path,
+                // high signal for ops/QA. (Quiet on the common under-budget fast path.)
+                if (stats.estimateBefore > stats.budget || stats.stubbedResults || stats.evictedTurns || stats.truncatedLatestTurn) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ctx-window] before=${stats.estimateBefore} after=${stats.estimateAfter} budget=${stats.budget} ` +
+                        `msgs=${messages.length} stubbed=${stats.stubbedResults} evicted=${stats.evictedTurns} truncated=${stats.truncatedLatestTurn}` +
+                        (stats.overBudget ? ' OVER-BUDGET-AFTER-TRIM' : ''));
+                }
+                // Distinct, loud signal for the irreducible case (systemPrompt + tool
+                // schemas alone exceed budget): everything trimmed yet still over. The
+                // reactive isContextOverflow net will surface the 400 to the user; this
+                // tells ops WHY (too many/large tools, not a runaway transcript).
+                if (stats.overBudget) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[ctx-window] STILL OVER BUDGET after full trim (after=${stats.estimateAfter} > budget=${stats.budget}). ` +
+                        `Likely systemPrompt + tool schemas exceed the window (tools=${agent.state.tools.length}). Request may 400.`);
+                }
+                return out;
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.error('[ctx-window] manageContext threw — sending UNTRIMMED messages:', err instanceof Error ? err.stack || err.message : err);
+                return messages;
+            }
+        };
+        // Truncation detection (provider-agnostic). pi-agent-core executes a complete
+        // tool-call block even when the assistant turn stopped on the output-token cap
+        // (agent-loop: tool execution is gated on toolCall presence, not stopReason),
+        // and continues to a follow-up turn afterward. So a large create_artifact /
+        // patch_artifact whose bundle JSON was cut mid-content still runs and saves a
+        // valid-but-short bundle, reporting success. afterToolCall fires right after
+        // the tool runs with the originating assistantMessage (carrying stopReason) in
+        // scope; when that turn was output-capped, we fold a warning into the tool
+        // result so the agent learns the write was truncated and continues with
+        // patch_artifact rather than assuming it finished. The hook returns undefined
+        // (a no-op) for every other tool/turn.
+        const afterToolCall = async (event) => {
+            // The output cap only truncates the FINAL content block of the turn, so
+            // only that block's tool result should be flagged. An earlier, COMPLETE
+            // artifact write in the same capped turn (parallel tool calls, or trailing
+            // content that ran over) must not get a false "truncated" note. Gate on
+            // this toolCall being the last block in the assistant message.
+            const blocks = (event.assistantMessage?.content ?? []);
+            const lastBlock = blocks[blocks.length - 1];
+            const isLastBlock = !!lastBlock && lastBlock.type === 'toolCall' && lastBlock.id === event.toolCall?.id;
+            if (!isLastBlock)
+                return undefined;
+            const out = artifactTruncationToolResult({
+                stopReason: event.assistantMessage?.stopReason,
+                toolName: event.toolCall?.name,
+                content: event.result?.content,
+            });
+            // Runtime shape matches (TextContent | ImageContent)[] — text blocks gain
+            // the note, image blocks pass through untouched; cast to the SDK type.
+            return out ? { content: out.content } : undefined;
+        };
+        const agent = new Agent({
+            getApiKey: () => apiKey,
+            transformContext,
+            afterToolCall,
+            // `thinkingLevel: 'medium'` turns on extended thinking so the runtime
+            // emits thinking_delta events. The chat stream relays those as a
+            // single-line "what the agent is thinking" status (replacing the pulsing
+            // dot). 'medium' is the lowest level that produces readable, followable
+            // reasoning on adaptive-thinking models (e.g. Opus 4.7, where 'low' is too
+            // brief — it flashes by). Forwarded as `reasoning` on both the direct and
+            // credits-gateway stream paths; a no-op for providers without reasoning.
+            initialState: { model, systemPrompt, tools: dedupedTools, thinkingLevel: 'medium' },
+            streamFn: useCreditsGateway ? createCloudInferenceStreamFn() : undefined,
+        });
+        // Custom tools are loaded asynchronously by the pool wrapper
+        // (config.loadCustomTools, wired to loadCustomToolsAsync). Do NOT call
+        // it here — calling it twice fires two concurrent Promise.alls, both
+        // racing to mutate agent.state.tools, and the inter-microtask dedup
+        // can't always prevent Anthropic seeing a duplicated list on the very
+        // first prompt. Single fire site = no race.
         return agent;
     }
     /**
@@ -155,12 +385,20 @@ export class AgentOrchestrator {
      * 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.
+     *
+     * `userId` is forwarded into `ConnectorManager.buildTools` so per-user MCP
+     * OAuth tokens are resolved at tool-build time. Without it the runtime
+     * silently falls back to workspace-shared static headers (the deferred
+     * gap before 2026-05-13). The agent pool keys agents per-session and
+     * supplies the session's userId on creation; CLI / non-interactive
+     * spawns pass `undefined` and intentionally land on the workspace
+     * fallback.
      */
-    loadCustomToolsAsync(agent) {
+    loadCustomToolsAsync(agent, userId) {
         const context = { workspaceManager: this.workspaceManager, gitUser: this.gitUser };
-        Promise.all([
+        return Promise.all([
             loadCustomTools(this.toolsDirs, context),
-            ConnectorManager.buildTools(ConnectorManager.loadConfigs(this.workspacePath)),
+            ConnectorManager.buildTools(ConnectorManager.loadConfigs(this.workspacePath), { userId, authService: this.authService }),
         ]).then(([customTools, connectorTools]) => {
             const extra = [...customTools];
             if (connectorTools.length > 0) {
@@ -184,9 +422,13 @@ export class AgentOrchestrator {
                     merged.push(t);
                 }
                 if (merged.length !== existing.length) {
-                    agent.setTools(merged);
+                    agent.state.tools = merged;
                 }
             }
+            if (process.env.STUDIOGRAPH_VERBOSE === '1') {
+                // eslint-disable-next-line no-console
+                console.log(`[orchestrator] loadCustomToolsAsync done: customTools=${customTools.length}, connectorTools=${connectorTools.length}, total agent.state.tools=${agent.state.tools.length}`);
+            }
         }).catch(err => {
             console.warn('Failed to load custom/connector tools:', err);
         });
@@ -194,11 +436,11 @@ export class AgentOrchestrator {
     /**
      * Build the full system prompt: base prompt + eager skill content + skill index.
      */
-    buildSystemPrompt(skillIndex, tools, recentMemory, briefingText, graphResolver) {
+    buildSystemPrompt(skillIndex, tools, recentMemory, graphResolver, promptRepos = this.workspaceManager.getContentRepoConfigs(), userId) {
         const promptPath = join(__dirname, 'prompts', 'system.md');
         let base = existsSync(promptPath)
             ? readFileSync(promptPath, 'utf-8')
-            : this.getDefaultSystemPrompt();
+            : this.getDefaultSystemPrompt(promptRepos);
         // Auto-generate tool reference from registered tools, grouped by category
         const categories = {
             'Entity Management': [],
@@ -220,8 +462,14 @@ export class AgentOrchestrator {
                 categories['Operations'].push(t);
             else if (name === 'load_skill')
                 categories['Skills'].push(t);
+            else if (['create_artifact', 'inspect_artifact'].includes(name))
+                (categories['Artifacts'] ??= []).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 if (['create_folder', 'create_subfolder', 'rename_folder', 'delete_folder', 'list_folders', 'move_entity', 'transfer_entity'].includes(name))
+                (categories['Folders'] ??= []).push(t);
+            else if (['list_file_history', 'list_folder_history', 'list_recent_deletions', 'read_file_at_commit', 'get_entity_diff', 'restore_file'].includes(name))
+                (categories['Git History'] ??= []).push(t);
             else
                 categories['Other'].push(t);
         }
@@ -239,7 +487,7 @@ export class AgentOrchestrator {
         const parts = [base.trim()];
         // Inject workspace identity from graph entities (org, team, capabilities, guidelines)
         // Falls back to ABOUT.md if the graph has no organization entries
-        const identitySection = this.buildWorkspaceIdentity();
+        const identitySection = this.buildWorkspaceIdentity(promptRepos);
         if (identitySection) {
             parts.push(identitySection);
         }
@@ -257,15 +505,37 @@ export class AgentOrchestrator {
         if (schemaSection) {
             parts.push(schemaSection);
         }
+        // Inject per-repo subfolder inventory so the agent knows the existing
+        // folder layout without calling list_folders for every routing decision.
+        // Capped per-repo to keep system prompt size bounded.
+        const folderInventory = this.buildFolderInventory(promptRepos);
+        if (folderInventory) {
+            parts.push(folderInventory);
+        }
         // Inject recent memory context (today + yesterday daily memory)
         if (recentMemory) {
             parts.push(`## Memory Context\n\n${recentMemory}`);
         }
-        // Inject workspace briefing memo (per-user, daily)
-        if (briefingText) {
-            // Truncation safety valve — cap at 2000 chars to prevent runaway system prompt growth
-            const truncated = briefingText.length > 2000 ? briefingText.slice(0, 2000) + '...' : briefingText;
-            parts.push(`## Workspace Briefing\n\nThe following briefing was generated based on this user's workspace and focus areas. Use it to greet the user — lead with the most notable finding, keep it conversational. Don't recite the full briefing. Cherry-pick 1-3 items by urgency.\n\n${truncated}`);
+        // Inject current-user identity + bridge so the agent can read its own
+        // handle and the linked person entity from the prompt instead of
+        // having to call list_users on every turn.
+        if (userId) {
+            const u = this.authService.findUserById(userId);
+            if (u) {
+                const ref = findPersonRefForUser(this.workspaceManager, u.handle);
+                const lines = [
+                    `## Current User`,
+                    ``,
+                    `- Display name: ${u.displayName}`,
+                    `- Handle: \`${u.handle}\` (use this for created_by/updated_by audit, @mentions, and link_person_to_user)`,
+                    `- Email: ${u.email}`,
+                    `- Role: ${u.role}`,
+                    ref
+                        ? `- Linked person entity: \`[[${ref.entityId}]]\` in \`${ref.repo}\` — when the user refers to themselves, this is their record. Write enrichments here via update_entity; never call link_person_to_user for the current user.`
+                        : `- Linked person entity: **none.** This account has no person record yet (new/legacy account, or a previously-linked record was deleted). The link is optional but powers their "My Tasks", @mentions, and lets teammates assign tasks to them. If they'd like to link, offer to either (a) find an existing person record that is them and link it (search_entities → link_person_to_user), or (b) create a person entity for them and link it (create_entity → link_person_to_user). You can also point them to Settings → Profile → "Create & link" for a one-click repair. Don't push workspace-wide config changes for this.`,
+                ];
+                parts.push(lines.join('\n'));
+            }
         }
         // Inline eager skills directly into the system prompt
         const eagerContent = loadEagerSkills(skillIndex, graphResolver);
@@ -285,20 +555,23 @@ export class AgentOrchestrator {
      * entrypoint. Priority order: user's private folder first, then shared
      * folders alphabetically. First occurrence of a given name wins.
      */
-    enumerateGraphSkills(userId) {
+    getPromptRepoScope(userId) {
+        if (!userId)
+            return this.workspaceManager.getAllRepoConfigs();
+        const user = this.authService.findUserById(userId);
+        if (!user)
+            return [];
+        return access.getAccessibleRepos(user, this.workspaceManager, this.authService);
+    }
+    enumerateGraphSkills(accessibleRepos, userId) {
         const skills = [];
         const seen = new Set();
-        const allRepos = this.workspaceManager.getAllRepoConfigs();
-        const accessible = userId
-            ? new Set(this.authService.getUserFolders(userId))
-            : new Set(allRepos.map(r => r.name));
-        const privateRepo = userId ? this.workspaceManager.getUserPrivateRepo(userId) : undefined;
-        const sortedRepos = [...allRepos]
-            .filter(r => accessible.has(r.name))
+        const personalRepo = userId ? this.workspaceManager.getUserSeedRepo(userId) : undefined;
+        const sortedRepos = [...accessibleRepos]
             .sort((a, b) => {
-            if (privateRepo && a.name === privateRepo.name)
+            if (personalRepo && a.name === personalRepo.name)
                 return -1;
-            if (privateRepo && b.name === privateRepo.name)
+            if (personalRepo && b.name === personalRepo.name)
                 return 1;
             return a.name.localeCompare(b.name);
         });
@@ -349,9 +622,17 @@ export class AgentOrchestrator {
      * to compose a concise identity summary for the system prompt.
      * Returns null if no organization entries exist.
      */
-    buildWorkspaceIdentity() {
+    buildWorkspaceIdentity(repos) {
         try {
-            const orgs = this.workspaceManager.list('organization');
+            const listScoped = (entityType) => repos.flatMap(repo => {
+                try {
+                    return this.workspaceManager.getGraph(repo.name).list(entityType);
+                }
+                catch {
+                    return [];
+                }
+            });
+            const orgs = listScoped('organization');
             if (orgs.length === 0)
                 return null;
             const lines = ['## Workspace Identity'];
@@ -367,7 +648,7 @@ export class AgentOrchestrator {
                 }
             }
             // Team
-            const people = this.workspaceManager.list('person');
+            const people = listScoped('person');
             if (people.length > 0) {
                 lines.push('\n### Team');
                 for (const person of people.slice(0, 15)) {
@@ -377,14 +658,19 @@ export class AgentOrchestrator {
                     lines.push(`- ${name}${role}${location}`);
                 }
             }
-            // Practice areas
-            const areas = this.workspaceManager.list('practice-area');
-            if (areas.length > 0) {
+            // Services (capabilities + methodologies — replaces former practice areas)
+            const services = listScoped('service');
+            if (services.length > 0) {
                 lines.push('\n### Capabilities');
-                lines.push(areas.map(a => a.data.name || a.id).join(', '));
+                // Top-level services (no `sprint` parent) read as the firm's overall
+                // capabilities; nested services are sprint-level details. Surface
+                // top-level only here to keep the system prompt compact.
+                const topLevel = services.filter(s => !s.data.sprint);
+                const list = topLevel.length > 0 ? topLevel : services;
+                lines.push(list.map(s => s.data.name || s.id).join(', '));
             }
-            // Guidelines (communication style, preferences)
-            const guidelines = this.workspaceManager.list('guideline');
+            // Guidelines (communication style, preferences) — now document.category=guideline
+            const guidelines = listScoped('document').filter(d => d.data.category === 'guideline');
             if (guidelines.length > 0) {
                 lines.push('\n### Guidelines');
                 for (const g of guidelines.slice(0, 5)) {
@@ -402,13 +688,62 @@ export class AgentOrchestrator {
             return null;
         }
     }
+    /**
+     * Per-repo subfolder summary for the system prompt. Lists each accessible
+     * repo with up to MAX_PER_REPO subfolder paths so the agent can route new
+     * entries into existing folders without calling list_folders for every
+     * decision. Refresh cadence is per-session (system prompt is built once).
+     */
+    buildFolderInventory(repos) {
+        const MAX_PER_REPO = 8;
+        // System folders (the reserved asset store) are never a place the agent
+        // should create entries — keep them out of the folder inventory.
+        repos = repos.filter(r => !r.system);
+        if (repos.length === 0)
+            return null;
+        const lines = [];
+        for (const repo of repos) {
+            let folders = [];
+            try {
+                folders = this.workspaceManager.getGraph(repo.name).listFolders();
+            }
+            catch {
+                continue;
+            }
+            const display = repo.display_name || repo.name;
+            if (folders.length === 0) {
+                lines.push(`- **${display}** (\`${repo.name}\`): no subfolders`);
+            }
+            else {
+                // Render `path` plus an explicit display_name override in quotes when one
+                // exists — so the agent can refer to folders by their human label (e.g. in
+                // follow-up suggestions) instead of the kebab path. Folders without an
+                // override title-case the last segment for display.
+                const shown = folders
+                    .slice(0, MAX_PER_REPO)
+                    .map(f => (f.display_name ? `\`${f.path}\` ("${f.display_name}")` : `\`${f.path}\``))
+                    .join(', ');
+                const more = folders.length > MAX_PER_REPO ? ` (+${folders.length - MAX_PER_REPO} more)` : '';
+                lines.push(`- **${display}** (\`${repo.name}\`): ${shown}${more}`);
+            }
+        }
+        if (lines.length === 0)
+            return null;
+        return `## Folder Inventory\n\nExisting subfolders per repo. Prefer placing new entries in an existing folder when one fits. Folder paths are repo-relative POSIX; a quoted "Display Name" after a path is that folder's human label.\n\nThe **bold** name is the repo's display name — use it in any text the user sees (e.g. "My Folder"), never the \`slug\` in parentheses. The slug is only for tool calls and URL/wikilink paths.\n\n${lines.join('\n')}`;
+    }
     /**
      * Fallback system prompt when prompts/system.md is not found.
      */
-    getDefaultSystemPrompt() {
-        const workspaceSummary = this.workspaceManager.getSummary();
-        const repoList = this.workspaceManager
-            .getAllRepoConfigs()
+    getDefaultSystemPrompt(promptRepos = this.workspaceManager.getContentRepoConfigs()) {
+        const totalEntities = promptRepos.reduce((count, repo) => {
+            try {
+                return count + this.workspaceManager.getGraph(repo.name).search({}).length;
+            }
+            catch {
+                return count;
+            }
+        }, 0);
+        const repoList = promptRepos
             .map(r => `  - ${r.name} (${r.type}): ${r.description}`)
             .join('\n');
         return `# Studiograph AI Assistant
@@ -418,8 +753,8 @@ You are Studiograph, an AI assistant helping creative teams manage their knowled
 ## Workspace
 
 **Team:** ${this.config.team_name}
-**Repositories:** ${workspaceSummary.totalRepos}
-**Total Entities:** ${workspaceSummary.totalEntities}
+**Repositories:** ${promptRepos.length}
+**Total Entities:** ${totalEntities}
 
 **Available Repositories:**
 ${repoList}`;
@@ -438,28 +773,41 @@ ${repoList}`;
             onHighlight: this._highlightCallback,
             onMutation: this._mutationCallback,
         };
+        // Usage-ledger ownership: this hook records the CLI path. The web SSE route
+        // (routes/chat.ts) prompts the agent directly and records its own turns.
+        const modelSel = this.getModelSelection();
         return this.pool.withAgent(sessionId, ctx, async (agent) => {
             return new Promise((resolve, reject) => {
                 let content = '';
                 const toolCalls = [];
+                const usage = createInferenceUsageSummary();
                 const unsubscribe = agent.subscribe((event) => {
                     if (event.type === 'message_end') {
                         const msg = event.message;
                         if (msg?.role === 'assistant') {
+                            addInferenceUsage(usage, msg.usage);
+                            recordAiUsage({
+                                feature: 'chat',
+                                provider: msg.provider ?? modelSel.provider,
+                                modelId: msg.model ?? modelSel.modelId,
+                                usage: msg.usage,
+                                userId: this._sessionUserId ?? null,
+                                sessionId,
+                            });
                             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 });
+                                    toolCalls.push({ tool: block.name, input: block.arguments ?? block.input, output: null });
                                 }
                             }
                         }
                     }
                     else if (event.type === 'agent_end') {
                         unsubscribe();
-                        resolve({ content, toolCalls });
+                        resolve({ content, toolCalls, usage });
                     }
                 });
                 agent.prompt(userMessage).catch((error) => {
@@ -475,28 +823,41 @@ ${repoList}`;
      */
     async chatInSession(sessionId, userMessage, opts) {
         const ctx = { user: opts?.user ?? null };
+        // Usage-ledger ownership: this hook records the non-stream POST /api/chat
+        // path. The web SSE route (routes/chat.ts) records its own turns.
+        const modelSel = this.getModelSelection();
         return this.pool.withAgent(sessionId, ctx, async (agent) => {
             return new Promise((resolve, reject) => {
                 let content = '';
                 const toolCalls = [];
+                const usage = createInferenceUsageSummary();
                 const unsubscribe = agent.subscribe((event) => {
                     if (event.type === 'message_end') {
                         const msg = event.message;
                         if (msg?.role === 'assistant') {
+                            addInferenceUsage(usage, msg.usage);
+                            recordAiUsage({
+                                feature: 'chat',
+                                provider: msg.provider ?? modelSel.provider,
+                                modelId: msg.model ?? modelSel.modelId,
+                                usage: msg.usage,
+                                userId: opts?.userId ?? opts?.user?.id ?? null,
+                                sessionId,
+                            });
                             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 });
+                                    toolCalls.push({ tool: block.name, input: block.arguments ?? block.input, output: null });
                                 }
                             }
                         }
                     }
                     else if (event.type === 'agent_end') {
                         unsubscribe();
-                        resolve({ content, toolCalls });
+                        resolve({ content, toolCalls, usage });
                     }
                 });
                 agent.prompt(userMessage).catch((error) => {
@@ -512,6 +873,117 @@ ${repoList}`;
     getWorkspaceManager() {
         return this.workspaceManager;
     }
+    getModelSelection() {
+        const userConfig = loadUserConfig();
+        return {
+            provider: resolveProvider(userConfig, this.config),
+            modelId: resolveModelId(userConfig, this.config),
+        };
+    }
+    /**
+     * The active chat model's context window (max prompt tokens), or null if it
+     * can't be resolved. Used by the chat route's reactive overflow detection
+     * (isContextOverflow needs the window to catch silent overflow). Mirrors the
+     * model resolution in createAgentInstance, including the Credits gateway.
+     */
+    getContextWindow() {
+        try {
+            if (isStudiographCreditsMode()) {
+                return studiographCreditsModel().contextWindow ?? null;
+            }
+            const { provider, modelId } = this.getModelSelection();
+            const model = getModel(provider, modelId);
+            return model?.contextWindow ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Can the active chat model accept image input? Drives the composer's
+     *  vision-attach affordance (disable + tooltip when false). The Studiograph
+     *  Credits gateway is vision-capable (A6); otherwise resolve from the model. */
+    supportsVision() {
+        if (isStudiographCreditsMode())
+            return true;
+        const { provider, modelId } = this.getModelSelection();
+        return supportsVision(provider, modelId);
+    }
+    /**
+     * Delete the agent-pool's persisted state for a chat session — evicts the warm
+     * agent + unlinks its on-disk JSON, which holds base64 copies of any vision
+     * images the agent saw. Called when a chat is deleted so those copies don't
+     * outlive the conversation (composer-vision cleanup). `rawSessionId` is the
+     * client session id; the pool keys by the resolved `user:{id}:{raw}` form.
+     */
+    deleteChatSessionState(userId, rawSessionId) {
+        this.pool.deleteSession(userId, `user:${userId}:${rawSessionId}`);
+    }
+    /** Delete agent-pool state for ALL of a user's chats (reset / delete-all). */
+    deleteAllChatSessionState(userId) {
+        this.pool.deleteAllSessions(userId);
+    }
+    /**
+     * One-shot, tool-free model call that names a conversation from its opening
+     * exchange (the ChatGPT pattern). Used by POST /api/chat/title after the
+     * first assistant reply. Deliberately lightweight: no agent pool, no tools,
+     * no system context — just the configured model and a tight instruction.
+     *
+     * Returns null (caller keeps the truncated first-message title) when there's
+     * no usable title, no API key, or we're in Studiograph Credits gateway mode —
+     * the gateway routes inference through its own client (cloud-inference-billing),
+     * not pi-ai's complete(), so a direct completeSimple() can't reach it. Titles
+     * via the gateway are a follow-up if we want them.
+     */
+    async generateConversationTitle(firstUserMessage, assistantReply) {
+        if (isStudiographCreditsMode())
+            return null;
+        const userConfig = loadUserConfig();
+        const apiKey = resolveApiKey(userConfig, this.config);
+        if (!apiKey)
+            return null;
+        // Title generation is a background utility task — route to the cheap tier.
+        const { provider, modelId } = resolveUtilityModelConfig({
+            provider: resolveProvider(userConfig, this.config),
+            modelId: resolveModelId(userConfig, this.config),
+            apiKey,
+        });
+        const model = getModel(provider, modelId);
+        const systemPrompt = 'You name a conversation from its opening exchange. Reply with ONLY the ' +
+            'title: 3 to 6 words, Title Case, no surrounding quotes, no trailing ' +
+            'punctuation. Describe the topic, not the speaker (e.g. "Cooper Hewitt ' +
+            'DEM Sync Notes", not "User Talks About a Meeting").';
+        const userText = `First message:\n${firstUserMessage}\n\nAssistant reply:\n${assistantReply}`.slice(0, 2000);
+        // No `temperature` — newer models (e.g. claude-opus-4-7) reject it with a
+        // 400 "temperature is deprecated for this model". maxTokens is plenty for a
+        // few-word title.
+        const startedAt = Date.now();
+        const result = await completeSimple(model, { systemPrompt, messages: [{ role: 'user', content: userText, timestamp: Date.now() }] }, { apiKey, maxTokens: 32 });
+        // Record even when the title comes back empty or errored — tokens were spent.
+        recordAiUsage({
+            feature: 'title',
+            provider,
+            modelId,
+            usage: result.usage,
+            durationMs: Date.now() - startedAt,
+        });
+        // Surface provider errors (e.g. a rejected option) so the route logs them
+        // instead of silently returning null and the client keeping its fallback.
+        if (result.stopReason === 'error') {
+            throw new Error(result.errorMessage || 'title model call failed');
+        }
+        const raw = result.content
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text)
+            .join('')
+            .trim();
+        // Strip wrapping quotes / trailing punctuation the model may add anyway.
+        const title = raw.replace(/^["'`]+|["'`]+$/g, '').replace(/[.!?]+$/, '').trim().slice(0, 60);
+        if (!title)
+            return null;
+        const usage = createInferenceUsageSummary();
+        addInferenceUsage(usage, result.usage);
+        return { title, usage };
+    }
     /**
      * Get workspace summary
      */
@@ -525,7 +997,7 @@ ${repoList}`;
         return this.workspaceManager.getRepoNames();
     }
     /**
-     * Set the current authenticated user for per-collection access filtering.
+     * Set the current authenticated user for per-folder access filtering.
      * Called per-request by the chat endpoint. Null = full access (API key / open mode).
      */
     setCurrentUser(user) {