studiograph 1.3.48-next.2 → 1.3.48-next.201

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)
+├── acme-rebrand/           # Folder (client project)
+├── website-redesign/       # Folder (another project)
+├── team-knowledge/         # Folder (processes, standards)
 └── private/                # Local-only, gitignored
 ```
 
-### 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

@@ -0,0 +1,117 @@
+/**
+ * Agent Pool — manages per-session Agent instances for concurrent access.
+ *
+ * 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 type { AuthUser } from '../services/auth-service.js';
+import type { MutationEvent } from './tools/graph-tools.js';
+export interface AgentContext {
+    user: AuthUser | null;
+    onHighlight?: ((ids: string[]) => void) | null;
+    onMutation?: ((m: MutationEvent) => void) | 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). 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;
+}
+export declare class AgentPool {
+    private pool;
+    private reapTimer;
+    private config;
+    /** Per-session context — set before each call, read by tool closures. */
+    private contextMap;
+    constructor(config: SharedAgentConfig);
+    /**
+     * Get the current context for a session (used by tool closures).
+     * Returns null user if no context is set.
+     */
+    getContext(sessionId: string): AgentContext;
+    /**
+     * Acquire an agent for a session, run a callback, then release.
+     * Per-session locking ensures serialized access within the same session.
+     * Different sessions run in parallel.
+     */
+    withAgent<T>(sessionId: string, ctx: AgentContext, fn: (agent: Agent) => Promise<T>, opts?: {
+        userId?: number;
+        fallbackHistory?: Array<{
+            role: string;
+            content: string;
+        }>;
+    }): Promise<T>;
+    /** Get the raw Agent for a session (for subscribe/streaming). Must be used with withAgent. */
+    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. */
+    clearSessions(userId?: number): number;
+    get size(): number;
+    /** Find the session ID for a given agent instance. */
+    findSessionForAgent(agent: Agent): string | null;
+    private getOrCreate;
+    private loadSession;
+    private saveSession;
+    private getUserDir;
+    private pruneSessions;
+    private reap;
+}

package/dist/agent/agent-pool.js

@@ -0,0 +1,287 @@
+/**
+ * Agent Pool — manages per-session Agent instances for concurrent access.
+ *
+ * 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 { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+const IDLE_TIMEOUT_MS = 10 * 60_000; // 10 minutes
+const REAP_INTERVAL_MS = 60_000; // check every 60s
+const MAX_SESSIONS_PER_USER = 20;
+export class AgentPool {
+    pool = new Map();
+    reapTimer = null;
+    config;
+    /** Per-session context — set before each call, read by tool closures. */
+    contextMap = new Map();
+    constructor(config) {
+        this.config = config;
+        this.reapTimer = setInterval(() => this.reap(), REAP_INTERVAL_MS);
+    }
+    /**
+     * Get the current context for a session (used by tool closures).
+     * Returns null user if no context is set.
+     */
+    getContext(sessionId) {
+        return this.contextMap.get(sessionId) ?? { user: null };
+    }
+    /**
+     * Acquire an agent for a session, run a callback, then release.
+     * Per-session locking ensures serialized access within the same session.
+     * Different sessions run in parallel.
+     */
+    async withAgent(sessionId, ctx, fn, opts) {
+        const entry = this.getOrCreate(sessionId, opts?.userId, opts?.fallbackHistory);
+        // Chain on the session's lock to serialize calls. Also await
+        // toolsLoaded so the first turn's prompt-to-Anthropic sees the
+        // full tool list (bundled + custom + per-user connector). On
+        // subsequent turns this promise is already resolved — no wait.
+        // Toolloading errors were caught upstream; the await is purely
+        // for ordering, never throws.
+        const result = entry.lock.then(async () => {
+            await entry.toolsLoaded;
+            entry.lastUsedAt = Date.now();
+            this.contextMap.set(sessionId, ctx);
+            try {
+                return await fn(entry.agent);
+            }
+            finally {
+                this.contextMap.delete(sessionId);
+                // Save session after each call
+                this.saveSession(entry);
+            }
+        });
+        // Update the lock — next caller for this session waits for this one
+        entry.lock = result.then(() => { }, () => { });
+        return result;
+    }
+    /** Get the raw Agent for a session (for subscribe/streaming). Must be used with withAgent. */
+    getAgent(sessionId) {
+        return this.pool.get(sessionId)?.agent ?? null;
+    }
+    /** Abort the agent for a session. */
+    abort(sessionId) {
+        this.pool.get(sessionId)?.agent.abort();
+    }
+    /**
+     * 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() {
+        for (const entry of this.pool.values()) {
+            this.saveSession(entry);
+        }
+        this.pool.clear();
+    }
+    /**
+     * 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) {
+        for (const [sessionId, entry] of this.pool.entries()) {
+            if (entry.userId === userId) {
+                this.saveSession(entry);
+                this.pool.delete(sessionId);
+                this.contextMap.delete(sessionId);
+            }
+        }
+    }
+    /** Save all sessions and stop the reaper. */
+    async shutdown() {
+        if (this.reapTimer) {
+            clearInterval(this.reapTimer);
+            this.reapTimer = null;
+        }
+        for (const entry of this.pool.values()) {
+            this.saveSession(entry);
+        }
+        this.pool.clear();
+    }
+    /** Clear all saved session files for a user. */
+    clearSessions(userId) {
+        const dir = this.getUserDir(userId);
+        if (!existsSync(dir))
+            return 0;
+        const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+        for (const f of files) {
+            try {
+                unlinkSync(join(dir, f));
+            }
+            catch { /* ignore */ }
+        }
+        return files.length;
+    }
+    get size() {
+        return this.pool.size;
+    }
+    /** Find the session ID for a given agent instance. */
+    findSessionForAgent(agent) {
+        for (const [sid, entry] of this.pool) {
+            if (entry.agent === agent)
+                return sid;
+        }
+        return null;
+    }
+    // ── Private ──
+    getOrCreate(sessionId, userId, fallbackHistory) {
+        const existing = this.pool.get(sessionId);
+        if (existing)
+            return existing;
+        // Create a fresh agent instance (pass userId for per-user context)
+        const agent = this.config.createAgent(userId);
+        // Kick off async tool loading. The returned promise gets stashed on
+        // the pool entry so the first withAgent call can await it — that's
+        // what closes the timing race between agent construction and the
+        // user's first chat turn referencing a connector tool. If the
+        // callback returns undefined (legacy or test surfaces that don't
+        // need to gate on it), treat it as already-resolved.
+        const toolsLoaded = (this.config.loadCustomTools?.(agent, userId) ?? Promise.resolve()).catch((err) => {
+            // Swallow the rejection here — the agent should proceed with
+            // whatever subset of tools landed. The orchestrator's own
+            // catch path already logged the underlying failure.
+            // eslint-disable-next-line no-console
+            console.warn(`[agent-pool] tool loading rejected, proceeding with bundled tools: ${err instanceof Error ? err.message : err}`);
+        });
+        // Try loading session from disk
+        const loaded = this.loadSession(agent, sessionId, userId);
+        // Fallback: rebuild the transcript as proper role-tagged messages when
+        // the saved session file is missing (cleared, corrupted, or first turn
+        // on a fresh container). The previous implementation flattened the
+        // entire history into a single role: 'user' message with "Assistant:" /
+        // "User:" prefixes embedded as plain text — the model then had to parse
+        // those textual prefixes to know what was its own output, and would
+        // sometimes mis-attribute its prior turns to the user (e.g. "you
+        // mentioned that Watowa consults" when the user had just said "we
+        // consult on..."). Mapping each turn to its actual role tag lets the
+        // model distinguish reliably without parsing-by-prefix.
+        if (!loaded && fallbackHistory && fallbackHistory.length > 0) {
+            const model = agent.state.model;
+            const baseTime = Date.now() - fallbackHistory.length * 1000;
+            agent.state.messages = fallbackHistory.map((m, i) => {
+                const timestamp = baseTime + i * 1000;
+                if (m.role === 'assistant') {
+                    return {
+                        role: 'assistant',
+                        content: [{ type: 'text', text: m.content }],
+                        api: model.api,
+                        provider: model.provider,
+                        model: model.id,
+                        usage: {
+                            input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+                        },
+                        stopReason: 'stop',
+                        timestamp,
+                    };
+                }
+                return {
+                    role: 'user',
+                    content: [{ type: 'text', text: m.content }],
+                    timestamp,
+                };
+            });
+        }
+        const entry = {
+            agent,
+            sessionId,
+            userId,
+            lastUsedAt: Date.now(),
+            lock: Promise.resolve(),
+            toolsLoaded,
+        };
+        this.pool.set(sessionId, entry);
+        return entry;
+    }
+    loadSession(agent, sessionId, userId) {
+        const userDir = this.getUserDir(userId);
+        const sessionPath = join(userDir, `${sessionId}.json`);
+        // Path traversal guard
+        if (!resolve(sessionPath).startsWith(resolve(userDir)))
+            return false;
+        if (existsSync(sessionPath)) {
+            try {
+                const data = JSON.parse(readFileSync(sessionPath, 'utf-8'));
+                if (Array.isArray(data.messages) && data.messages.length > 0) {
+                    agent.state.messages = data.messages;
+                    return true;
+                }
+            }
+            catch { /* corrupted — fall through */ }
+        }
+        return false;
+    }
+    saveSession(entry) {
+        const messages = entry.agent.state.messages;
+        if (messages.length === 0)
+            return;
+        const userDir = this.getUserDir(entry.userId);
+        if (!existsSync(userDir)) {
+            mkdirSync(userDir, { recursive: true });
+        }
+        const sessionPath = join(userDir, `${entry.sessionId}.json`);
+        writeFileSync(sessionPath, JSON.stringify({
+            sessionId: entry.sessionId,
+            updatedAt: new Date().toISOString(),
+            messages,
+        }), 'utf-8');
+        this.pruneSessions(userDir, MAX_SESSIONS_PER_USER);
+    }
+    getUserDir(userId) {
+        if (userId)
+            return join(this.config.sessionsDir, String(userId));
+        return this.config.sessionsDir;
+    }
+    pruneSessions(dir, keep) {
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter(f => f.endsWith('.json'))
+            .map(f => {
+            try {
+                return { name: f, mtime: statSync(join(dir, f)).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter(Boolean);
+        if (files.length <= keep)
+            return;
+        files.sort((a, b) => b.mtime - a.mtime);
+        for (const f of files.slice(keep)) {
+            try {
+                unlinkSync(join(dir, f.name));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    reap() {
+        const now = Date.now();
+        for (const [key, entry] of this.pool) {
+            if (now - entry.lastUsedAt > IDLE_TIMEOUT_MS) {
+                this.saveSession(entry);
+                this.pool.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=agent-pool.js.map

package/dist/agent/agent-pool.js.map

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

package/dist/agent/followups.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Follow-up suggestion marker parsing.
+ *
+ * The system prompt instructs the agent to end every response with an HTML
+ * comment of the form:
+ *
+ *   <!-- followups: ["prompt 1", "prompt 2", "prompt 3"] -->
+ *
+ * Each transport (web, CLI, MCP) must strip this marker from the content it
+ * displays and surface the suggestions in whatever form fits its UI — chips
+ * in the web client, a dim numbered list in the CLI, a `suggestions` field
+ * in MCP, etc.
+ *
+ * Keep the parser in one place so a new transport can't silently leak the
+ * raw marker.
+ */
+export interface ParsedFollowups {
+    /** Response content with the marker removed and trailing whitespace trimmed. */
+    content: string;
+    /** Parsed suggestions, if the marker was present and valid JSON. */
+    suggestions?: string[];
+}
+/**
+ * Parse a raw agent response and split it into clean content plus optional
+ * follow-up suggestions. Malformed markers are left in place (the caller can
+ * choose to strip or render as-is), matching the existing web behaviour.
+ */
+export declare function parseFollowups(raw: string): ParsedFollowups;
+/**
+ * Return true if `text` contains an *unclosed* followups marker — used by
+ * streaming consumers to know whether to defer rendering the tail of a
+ * delta until the closing `-->` arrives.
+ */
+export declare function hasOpenFollowupsMarker(text: string): boolean;

package/dist/agent/followups.js

@@ -0,0 +1,52 @@
+/**
+ * Follow-up suggestion marker parsing.
+ *
+ * The system prompt instructs the agent to end every response with an HTML
+ * comment of the form:
+ *
+ *   <!-- followups: ["prompt 1", "prompt 2", "prompt 3"] -->
+ *
+ * Each transport (web, CLI, MCP) must strip this marker from the content it
+ * displays and surface the suggestions in whatever form fits its UI — chips
+ * in the web client, a dim numbered list in the CLI, a `suggestions` field
+ * in MCP, etc.
+ *
+ * Keep the parser in one place so a new transport can't silently leak the
+ * raw marker.
+ */
+/** Matches the trailing followups HTML comment at end of text (with optional trailing whitespace). */
+const FOLLOWUPS_RE = /<!--\s*followups:\s*(\[[\s\S]*?\])\s*-->\s*$/;
+/**
+ * Parse a raw agent response and split it into clean content plus optional
+ * follow-up suggestions. Malformed markers are left in place (the caller can
+ * choose to strip or render as-is), matching the existing web behaviour.
+ */
+export function parseFollowups(raw) {
+    const match = raw.match(FOLLOWUPS_RE);
+    if (!match)
+        return { content: raw };
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === 'string')) {
+            return { content: raw };
+        }
+        const content = raw.slice(0, match.index).trimEnd();
+        return { content, suggestions: parsed };
+    }
+    catch {
+        return { content: raw };
+    }
+}
+/**
+ * Return true if `text` contains an *unclosed* followups marker — used by
+ * streaming consumers to know whether to defer rendering the tail of a
+ * delta until the closing `-->` arrives.
+ */
+export function hasOpenFollowupsMarker(text) {
+    const lastOpen = text.lastIndexOf('<!--');
+    if (lastOpen < 0)
+        return false;
+    const lastClose = text.lastIndexOf('-->');
+    return lastClose < lastOpen;
+}
+//# sourceMappingURL=followups.js.map

package/dist/agent/followups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"followups.js","sourceRoot":"","sources":["../../src/agent/followups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sGAAsG;AACtG,MAAM,YAAY,GAAG,8CAA8C,CAAC;AASpE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC1E,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACpD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,SAAS,GAAG,QAAQ,CAAC;AAC9B,CAAC"}