studiograph 1.3.48-next.27 → 1.3.48-next.270

package/README.md

@@ -31,22 +31,27 @@ To create repos on GitHub during init:
 studiograph init "My Studio" --github --github-org my-org
 ```
 
-### Join an Existing Workspace
+### Clone an Existing Workspace
 
 ```bash
-studiograph join https://github.com/my-org/.studiograph.git
+studiograph clone https://studiograph.example.com /path/to/local/copy
 ```
 
-This clones the config repo, identifies your role from the team roster, and clones all repos you have access to.
+Authenticates as the workspace owner against a running Studiograph server,
+mints a per-machine API token, persists it to `~/.studiograph/user.json`, and
+clones every accessible repo. Subsequent `pull`/`push` runs are non-interactive
+via the stored token.
 
-### Start the Agent
+### Boot the Workspace
 
 ```bash
 cd my-studio
-studiograph start
+studiograph serve
 ```
 
-On first run, you'll be prompted to select an AI provider and model. The agent provides a chat interface where you can create, search, and manage entities across your knowledge graph.
+This starts the local HTTP server + opens the web UI. The web chat panel is the canonical agent surface: a richer chat UX, real-time graph view, and inline editor. On first boot you'll be prompted to set up an AI provider and model.
+
+If you want a terminal-side agent (Claude Desktop / Cursor integration), run `studiograph mcp` — it exposes the same toolset over MCP.
 
 ## How It Works
 
@@ -57,15 +62,15 @@ A Studiograph workspace is a directory containing a `.studiograph/` configuratio
 ```
 my-studio/
 ├── .studiograph/           # Config repo (workspace.json, team roster, migrations)
-├── acme-rebrand/           # Collection (client project)
-├── website-redesign/       # Collection (another project)
-├── team-knowledge/         # Collection (processes, standards)
-└── private/                # Local-only, gitignored
+├── acme-rebrand/           # Folder (client project)
+├── website-redesign/       # Folder (another project)
+├── team-knowledge/         # Folder (processes, standards)
+└── private/                # Personal folder — owner-private, its own git repo
 ```
 
-### Collections
+### Folders
 
-Each subdirectory is a **collection** — a Git repo containing related entities. Collections are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.
+Each subdirectory is a **folder** — a Git repo containing related entities. Folders are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.
 
 ### Entities
 
@@ -118,14 +123,13 @@ There are 17 built-in entity types (project, meeting, person, organization, deci
 | Command | Description |
 |---------|-------------|
 | `studiograph init <team-name> [dir]` | Initialize a new workspace |
-| `studiograph join <url> [dir]` | Join an existing workspace via GitHub URL |
-| `studiograph auth` | Manage GitHub authentication |
+| `studiograph clone <url> [dir]` | Clone an existing workspace from a running server |
 
 ### Daily Workflow
 
 | Command | Description |
 |---------|-------------|
-| `studiograph start` | Launch the AI agent chat interface |
+| `studiograph serve` | Boot the local HTTP server + open the web UI |
 | `studiograph pull` | Pull latest changes from remote |
 | `studiograph push` | Push local commits to remote |
 
@@ -133,7 +137,7 @@ There are 17 built-in entity types (project, meeting, person, organization, deci
 
 | Command | Description |
 |---------|-------------|
-| `studiograph collection` | Manage collections (add, list, rename, remove) |
+| `studiograph folder` | Manage folders (add, list, rename, remove) |
 | `studiograph provision` | Push workspace config to GitHub as a separate repo |
 | `studiograph members` | Manage team members and roles |
 | `studiograph index` | Rebuild search index |
@@ -190,7 +194,7 @@ Studiograph exposes a [Model Context Protocol](https://modelcontextprotocol.io/)
 
 If you're running from the workspace directory, you can omit the path: `studiograph mcp`.
 
-MCP tools available: `list_repos`, `list_entities`, `get_entity`, `search_entities`, `create_entity`, `update_entity`, `delete_entity`.
+MCP tools available: `list_repos`, `create_repo`, `list_entities`, `get_entity`, `search_entities`, `create_entity`, `update_entity`, `delete_entity`.
 
 ### Third-Party Connectors
 
@@ -245,6 +249,12 @@ The guided wizard walks through setup. Required environment variables:
 | `API_KEYS` | Semicolon-separated bearer tokens for client auth |
 | `WEBHOOK_SECRET` | GitHub webhook HMAC-SHA256 secret (optional) |
 | `PORT` | Set automatically by Railway |
+| `STUDIOGRAPH_CLOUD_URL` | Optional Studiograph Cloud control-plane URL for hosted inference billing |
+| `STUDIOGRAPH_CLOUD_ORG_ID` | Optional cloud organization ID for this managed runtime |
+| `STUDIOGRAPH_CLOUD_WORKSPACE_ID` | Optional cloud workspace ID for this managed runtime |
+| `STUDIOGRAPH_CLOUD_TOKEN` | Optional bearer token for machine-to-machine cloud billing calls |
+| `STUDIOGRAPH_CLOUD_BILLING_REQUIRED` | Set to `1` to fail chat when cloud billing reservation/settlement fails |
+| `STUDIOGRAPH_CLOUD_INFERENCE_ESTIMATE_CENTS` | Reservation estimate per chat turn, default `100` |
 
 On first boot, the server clones the config repo and all content repos automatically.
 

package/dist/agent/agent-pool.d.ts

@@ -1,26 +1,63 @@
 /**
  * Agent Pool — manages per-session Agent instances for concurrent access.
  *
- * Each session (collection chat, private chat, capture) gets its own Agent
+ * Each session (folder chat, private chat, capture) gets its own Agent
  * with independent conversation history. Shared resources (tools, system
  * prompt, model) are created once and passed to each new agent.
  *
  * Per-session locking ensures only one call runs per session at a time,
  * while different sessions can run in parallel.
  */
-import { Agent } from '@mariozechner/pi-agent-core';
+import { Agent } from '@earendil-works/pi-agent-core';
 import type { AuthUser } from '../services/auth-service.js';
 import type { MutationEvent } from './tools/graph-tools.js';
+import type { ArtifactCallback, ArtifactToolTarget } from './tools/artifact-tools.js';
 export interface AgentContext {
     user: AuthUser | null;
+    /**
+     * The RAW client session id for this turn (the chat's id as the client knows
+     * it — what conversation-scratch images are keyed by). Distinct from the
+     * pool's resolved session key (`user:<id>:<clientId>`). Lets session-scoped
+     * tools (e.g. `save_file_to_assets`) target the current conversation's
+     * scratch images rather than the user's other chats. Optional — unset for
+     * CLI/non-web contexts.
+     */
+    clientSessionId?: string | null;
     onHighlight?: ((ids: string[]) => void) | null;
     onMutation?: ((m: MutationEvent) => void) | null;
+    onArtifact?: ArtifactCallback | null;
+    currentArtifactTarget?: ArtifactToolTarget | null;
+    /**
+     * Called by tool wrappers at the start (`enter`) and end (`leave`) of any
+     * mutation that targets a folder. Powers the "X's agent is acting" sidebar
+     * chip via wsHub.handleAgentActivity. Optional — no-op if unset.
+     */
+    onAgentActivity?: ((action: 'enter' | 'leave' | 'heartbeat', repo: string) => void) | null;
+    /**
+     * Wired only by the quick-capture flow. When the agent calls the
+     * `nothing_to_capture` tool, this receives the structured reason so the
+     * UI can render a toast without going through freeform assistant prose
+     * (which is variable-quality and leaks the followups marker).
+     */
+    onNothingToCapture?: ((reason: string) => void) | null;
 }
 export interface SharedAgentConfig {
     /** Factory to create a fresh Agent instance with tools, prompt, and model. */
     createAgent: (userId?: number) => Agent;
-    /** Callback to load custom tools async (called once per new agent). */
-    loadCustomTools?: (agent: Agent) => void;
+    /**
+     * Callback to load custom tools async (called once per new agent). The
+     * pool passes the session's `userId` so per-user MCP connector OAuth
+     * tokens can be resolved at tool-build time — without this, the agent
+     * runtime can't read tokens stored under `(user, connector)`.
+     *
+     * Must return a Promise that resolves when tool loading is done (or
+     * rejects on failure — the pool catches and treats it as "load gave
+     * up, proceed with bundled tools"). `withAgent` awaits this on the
+     * first chat call for the session so the first turn doesn't race
+     * against still-loading MCP connector tools. The promise resolves
+     * once and subsequent turns see it as a no-op.
+     */
+    loadCustomTools?: (agent: Agent, userId?: number) => Promise<void>;
     /** Base sessions directory. */
     sessionsDir: string;
 }
@@ -30,7 +67,31 @@ export declare class AgentPool {
     private config;
     /** Per-session context — set before each call, read by tool closures. */
     private contextMap;
+    /**
+     * Turn-scoped binding: the Agent instance currently executing a turn → that
+     * turn's session id. Set for the duration of `fn` in `withAgent`, kept
+     * INDEPENDENT of `pool`/`contextMap` so a mid-turn eviction (invalidateUser /
+     * invalidateAll / reap) can't strip a running turn of its context.
+     *
+     * Tool closures resolve their session via `findSessionForAgent`, which scans
+     * `pool` by agent identity — but eviction deletes the pool entry, so that
+     * scan would return null and every session-scoped tool would silently lose
+     * context (create_artifact fails with "No artifact canvas is available in
+     * this context"; getUser falls back to a stale default; onMutation/onHighlight
+     * no-op). This map is the durable fallback findSessionForAgent checks first.
+     */
+    private activeTurns;
+    /**
+     * Optional predicate: returns true for a resolved sessionId that must NOT be
+     * pruned even when it's beyond the per-user keep budget. Wired by the server
+     * to the AgentTaskJobStore so a delegated task's session (which a background
+     * run + crash recovery depend on) is never evicted out from under a live job.
+     * Unset for CLI/tests → prune behaves exactly as before.
+     */
+    private isSessionProtected?;
     constructor(config: SharedAgentConfig);
+    /** Install the prune-protection predicate (see {@link isSessionProtected}). */
+    setSessionProtectedPredicate(fn: (sessionId: string) => boolean): void;
     /**
      * Get the current context for a session (used by tool closures).
      * Returns null user if no context is set.
@@ -52,6 +113,30 @@ export declare class AgentPool {
     getAgent(sessionId: string): Agent | null;
     /** Abort the agent for a session. */
     abort(sessionId: string): void;
+    /**
+     * Evict every cached agent instance. Persists each session's history
+     * first so no in-memory transcript is lost. Next chat for any session
+     * spins up a fresh agent (via `createAgent` from the config), which
+     * re-reads model/provider/api_key via `resolveApiKey` — picking up
+     * whatever the store now has.
+     *
+     * Used as the eviction hook on secret/setting mutations: when the
+     * operator rotates an API key or switches providers via Settings UI,
+     * the running agent's captured apiKey is stale until restart. This
+     * is the surgical fix instead of restarting the whole process.
+     */
+    invalidateAll(): void;
+    /**
+     * Evict every pool entry owned by a specific user. Used as the eviction
+     * hook on per-user OAuth mutations: when a user OAuths a new connector
+     * (or revokes one), their running agent's tool list — captured at
+     * createAgentInstance time — no longer matches reality. Sessions
+     * belonging to OTHER users stay in the pool untouched.
+     *
+     * Saved sessions are written to disk before removal, same as
+     * `invalidateAll`, so no transcript is lost.
+     */
+    invalidateUser(userId: number): void;
     /** Save all sessions and stop the reaper. */
     shutdown(): Promise<void>;
     /** Clear all saved session files for a user. */
@@ -61,8 +146,49 @@ export declare class AgentPool {
     findSessionForAgent(agent: Agent): string | null;
     private getOrCreate;
     private loadSession;
+    /**
+     * Bound what RIDES IN PERSISTED HISTORY after each turn (DESTRUCTIVE — mutates
+     * the saved transcript). This is the privacy/baseline complement to the
+     * proactive per-call manager (context-window.ts / orchestrator
+     * `transformContext`), and the two have a clean division of labor:
+     *
+     *   - The proactive manager handles the live TOKEN BUDGET non-destructively
+     *     (large text tool results are stubbed/evicted in the per-call VIEW only),
+     *     so big text stays in the on-disk transcript and the user can still scroll
+     *     back through it. We deliberately do NOT destructively stub large text
+     *     here — that would degrade saved-chat display and fight the manager's
+     *     recent-turn pinning.
+     *   - This pass removes the payloads that MUST NOT PERSIST regardless of budget:
+     *       1. ARTIFACT tool RESULTS (`read_artifact` / `inspect_artifact` /
+     *          `get_artifact_manifest`) — an ArtifactBundle inlines all its
+     *          HTML/CSS/JS (large + re-readable), inspect returns vision image
+     *          blocks, and a manifest with `frameId` carries one frame's full
+     *          content. Replaced with an artifact-specific stub (size-gated, so a
+     *          small structure-only manifest stays inline); images stripped regardless of size.
+     *       2. The bundle ARGUMENT of `create_artifact` tool calls — elided.
+     *       3. VISION IMAGES in any OTHER tool result (e.g. a future `read_asset`):
+     *          stripped so they neither re-bloat every prompt nor outlive the chat
+     *          on disk (the "delete chat → images gone" promise). Text blocks are
+     *          kept — only the image blocks are removed.
+     *
+     * Idempotent and defensive: a stubbed/stripped result has no image and a small
+     * text body, so it isn't re-touched; a malformed message never breaks persistence.
+     */
+    private compactArtifactHistory;
     private saveSession;
     private getUserDir;
+    /**
+     * Delete a session's persisted state: evict the warm in-memory entry AND
+     * unlink its on-disk JSON. Used when a chat is deleted — the per-session JSON
+     * holds base64 copies of any vision images the agent saw, so it must be
+     * removed for the "delete chat → images gone" promise to hold (composer-vision).
+     * `sessionId` is the RESOLVED id the pool keys by (e.g. `user:7:abc`).
+     */
+    deleteSession(userId: number | undefined, sessionId: string): void;
+    /** Delete EVERY persisted session for a user (the reset / delete-all path). */
+    deleteAllSessions(userId: number | undefined): void;
+    /** Unlink a session's on-disk JSON (best-effort, path-traversal guarded). */
+    private removeSessionFile;
     private pruneSessions;
     private reap;
 }