studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/agent/skills/schema-rules.md

@@ -1,6 +1,6 @@
 ---
 name: schema-rules
-description: Critical rules for creating and updating entities — valid enums, field types, common pitfalls
+description: Critical rules for creating and updating entities — enum discovery, field types, common pitfalls
 loading: eager
 ---
 
@@ -14,41 +14,41 @@ These rules apply whenever you create or update entries. For the full field refe
 
 **Never wrap the `content` parameter in quotes.** The `content` field is raw markdown, not a JSON string. Do not add leading or trailing `"` characters. Pass the markdown directly.
 
-## Field Types
+## Enum Fields — Always Check the Schema
 
-- **website** / **url** fields: must be a valid URL with protocol (e.g., `https://example.com`) or omitted entirely
-- **email** fields: must be a valid email address or omitted
-- **date** fields (start_date, end_date, due_date, expected_close): must be ISO format `YYYY-MM-DD` or omitted
-- **number** fields (deal_value, probability, year): must be actual numbers, not strings
+Many entity fields are enums (a closed set of allowed values). Field names that signal an enum include `stage`, `status`, `category`, `priority`, `audience`, `source`, `type`. **Do not guess enum values from memory.** Allowed values change as the product evolves, and a guessed value that "sounds right" (e.g. `negotiating` vs the actual `negotiation`) will fail validation.
 
-## Valid Enum Values
+**Before writing any enum-shaped field on create or update:**
 
-### Organization
-- **category**: `client`, `vendor`, `partner`, `prospect`, `industry-body`, `other`
-- **status**: `active`, `inactive`, `former`
+1. Call `get_entity_schema(entityType)` to fetch the authoritative schema for the entity type.
+2. Inspect the returned `fields` object. For each enum field, the descriptor includes:
+   - `type: "enum"` (or `"enum[]"` for arrays of enums)
+   - `enum: [...]` — the full list of allowed values
+   - `default: ...` — the value applied when the field is omitted (when present)
+3. Use only values from the `enum` array. If you want the default, omit the field entirely.
 
-For prospect organizations, use `category: "prospect"` with `status: "active"`.
+You may cache the schema response within a single conversation turn, but re-fetch when starting work on a different entity type or after a schema change is mentioned.
 
-### Person
-- **status**: `current`, `former`, `contractor`, `client`, `partner`
+## Field Types (from `get_entity_schema`)
 
-### Project
-- **status**: `planning`, `scoping`, `active`, `on-hold`, `completed`, `archived`
+- `string` — free text
+- `string` with format `url` — must be a valid URL with protocol (e.g., `https://example.com`)
+- `string` with format `email` — must be a valid email
+- `datetime` — ISO 8601 datetime (auto-stamped on `created_at` / `updated_at` — do not pass these)
+- `number` — actual number, not a quoted string
+- `boolean` — `true` / `false`
+- `enum` — one of the values listed under the field's `enum` array
+- `string[]` — array of strings; for wikilink arrays (`attendees`, `services`, etc.) each entry is a wikilink id like `[[acme-corp]]`
+- `enum[]` — array of enum values; each entry must be one of `itemEnum`
 
-### Deal
-- **stage**: `scoping`, `proposal`, `negotiating`, `won`, `lost`
-- **source**: `referral`, `inbound`, `outbound`, `repeat`, `partner`, `other`
+Dates use exactly two fields. `date` (type `date`) is every entity's salient date — its meaning is type-specific and shown in the field's `label` (a task's "Due date", a deal's "Close date", a project's "End date"). `start_date` (type `date`, only on project/event/task/deliverable/deal) is the optional earlier bound of a range `[start_date, date]`. Both must be `YYYY-MM-DD` (date-only — not a datetime) or omitted; anything else is rejected.
 
-### Task
-- **status**: `open`, `in-progress`, `done`, `cancelled`
-- **priority**: `low`, `medium`, `high`, `urgent`
-
-### Decision
-- **status**: `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`
+## Error Recovery
 
-### Case Study
-- No status enum — uses base fields only
+When an entry creation or update fails with a validation error, read the message carefully:
 
-## Error Recovery
+- If it names an enum field (e.g. `stage: Invalid enum value`), call `get_entity_schema` for that entity type, pick a valid value from the `enum` list, and retry.
+- If it complains about a URL or email format, drop the field rather than substituting a placeholder.
+- If it complains about a missing required field, ask the user or omit the entry and explain.
 
-When an entry creation fails, read the error message, fix the offending field, and retry immediately. Do not skip the entry or tell the user it failed without retrying.
+Do not skip the entry silently — either retry with corrected data or tell the user what went wrong.

package/dist/agent/tools/artifact-tools.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Artifact tools let the agent hand a renderable bundle to the web canvas.
+ * The active transport decides whether that bundle updates the currently
+ * scoped artifact entry or creates a new persisted artifact entry.
+ */
+import { Type as T } from 'typebox';
+import { type ArtifactBundle } from '../../core/artifact-bundle.js';
+import { type ArtifactInspectOptions, type ArtifactInspectionResult } from '../../services/artifact-render-export.js';
+export interface ArtifactCallbackResult {
+    repo: string;
+    entityType: 'artifact';
+    entityId: string;
+    action: 'created' | 'updated';
+}
+export interface ArtifactToolTarget {
+    repo?: string;
+    entityId?: string;
+}
+/** Optional concurrency/safety controls threaded from `create_artifact` to the
+ *  write callback. `baseHash` is the hash the agent received from `read_artifact`;
+ *  the writer rejects the update if the current artifact's hash differs (someone
+ *  else changed it since the read). `replace` opts out of the destructive-shrink
+ *  guard for intentional blank/rewrite. */
+export interface ArtifactWriteOptions {
+    baseHash?: string;
+    replace?: boolean;
+}
+export type ArtifactCallback = (bundle: ArtifactBundle, target?: ArtifactToolTarget, options?: ArtifactWriteOptions) => void | ArtifactCallbackResult | Promise<void | ArtifactCallbackResult>;
+/** What `read_artifact` hands back: the parsed bundle plus the hash + timestamp
+ *  the agent passes to `create_artifact` as `baseHash` for stale-write detection. */
+export interface ArtifactReadResult {
+    bundle: ArtifactBundle;
+    hash: string;
+    updatedAt?: string;
+}
+export type ArtifactReadCallback = (target?: ArtifactToolTarget) => ArtifactReadResult | Promise<ArtifactReadResult>;
+/** Stable content hash of an artifact's stored body STRING (not the parsed
+ *  bundle), so `read_artifact` and the write-time guard hash the exact same
+ *  serialization — no canonicalization, no false mismatches from key reordering. */
+export declare function hashArtifactBody(body: string): string;
+export interface ArtifactToolOptions {
+    readArtifact?: ArtifactReadCallback | null;
+    inspectArtifact?: (bundle: ArtifactBundle, options?: ArtifactInspectOptions) => Promise<ArtifactInspectionResult>;
+}
+export declare function createArtifactTools(onArtifact?: ArtifactCallback | null, options?: ArtifactToolOptions): ({
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        bundle: T.TObject<{}>;
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        baseHash: T.TOptional<T.TString>;
+        replace: T.TOptional<T.TBoolean>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        bundle?: unknown;
+        target?: ArtifactToolTarget;
+        baseHash?: string;
+        replace?: boolean;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        bundle: T.TOptional<T.TObject<{}>>;
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        context: T.TOptional<T.TUnion<[T.TLiteral<"editor">, T.TLiteral<"fullscreen">]>>;
+        frameSelector: T.TOptional<T.TString>;
+        frameIndexes: T.TOptional<T.TArray<T.TNumber>>;
+        maxFrames: T.TOptional<T.TNumber>;
+        includePageScreenshot: T.TOptional<T.TBoolean>;
+        includeFrameScreenshots: T.TOptional<T.TBoolean>;
+        screenshotFormat: T.TOptional<T.TUnion<[T.TLiteral<"jpeg">, T.TLiteral<"png">]>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        bundle?: unknown;
+        target?: ArtifactToolTarget;
+        context?: "editor" | "fullscreen";
+        frameSelector?: string;
+        frameIndexes?: number[];
+        maxFrames?: number;
+        includePageScreenshot?: boolean;
+        includeFrameScreenshots?: boolean;
+        screenshotFormat?: "png" | "jpeg";
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        target?: ArtifactToolTarget;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+})[];

package/dist/agent/tools/artifact-tools.js

@@ -0,0 +1,207 @@
+/**
+ * Artifact tools let the agent hand a renderable bundle to the web canvas.
+ * The active transport decides whether that bundle updates the currently
+ * scoped artifact entry or creates a new persisted artifact entry.
+ */
+import { createHash } from 'crypto';
+import { Type as T } from 'typebox';
+import { validateArtifactBundle } from '../../core/artifact-bundle.js';
+import { ArtifactRenderExportUnavailableError, inspectArtifactRender, } from '../../services/artifact-render-export.js';
+import { wrapToolResult } from './graph-tools.js';
+/** Stable content hash of an artifact's stored body STRING (not the parsed
+ *  bundle), so `read_artifact` and the write-time guard hash the exact same
+ *  serialization — no canonicalization, no false mismatches from key reordering. */
+export function hashArtifactBody(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex').slice(0, 16);
+}
+export function createArtifactTools(onArtifact, options = {}) {
+    const inspectArtifact = options.inspectArtifact ?? inspectArtifactRender;
+    return [
+        {
+            name: 'create_artifact',
+            label: 'Create Artifact',
+            description: 'Create or update a persisted sandboxed canvas artifact from HTML/CSS/JS text files. Use this for slide decks, documents, social graphics, prototypes, diagrams, and other visual outputs. When chat is scoped to an artifact entry, this updates that canvas. If the user references another artifact entry, pass target.entityId and target.repo when known. Otherwise this creates a new artifact entry. To EDIT an existing artifact, first call read_artifact to get the current source and its hash, modify the full bundle, and pass that hash as baseHash so a concurrent change is detected instead of silently overwritten.',
+            parameters: T.Object({
+                bundle: T.Object({}, {
+                    description: 'ArtifactBundle object with schemaVersion, artifactId, title, kind, viewport, optional libraries (three, d3, motion), files, and entrypoint.',
+                    additionalProperties: true,
+                }),
+                target: T.Optional(T.Object({
+                    repo: T.Optional(T.String({ description: 'Folder/repo containing the artifact entry to update.' })),
+                    entityId: T.Optional(T.String({ description: 'Existing artifact entity id to update.' })),
+                }, {
+                    description: 'Optional existing artifact entry to update when the user references one outside the current canvas context.',
+                })),
+                baseHash: T.Optional(T.String({
+                    description: 'The hash returned by read_artifact for the version you edited. Required when updating an existing artifact — the update is rejected if the artifact changed since that read.',
+                })),
+                replace: T.Optional(T.Boolean({
+                    description: 'Set true to intentionally blank or wholesale-replace an existing artifact (bypasses the guard that blocks accidentally dropping its content).',
+                })),
+            }),
+            execute: async (_toolCallId, params) => {
+                const result = validateArtifactBundle(params.bundle);
+                if (!result.ok || !result.bundle) {
+                    return wrapToolResult({
+                        success: false,
+                        error: 'Invalid artifact bundle',
+                        errors: result.errors,
+                        byteSize: result.byteSize,
+                    });
+                }
+                if (!onArtifact) {
+                    return wrapToolResult({
+                        success: false,
+                        error: 'No artifact canvas is available in this context',
+                    });
+                }
+                let location;
+                try {
+                    location = await onArtifact(result.bundle, params.target, { baseHash: params.baseHash, replace: params.replace });
+                }
+                catch (err) {
+                    // Surface stale-write / destructive-shrink rejections as a tool error
+                    // the agent can recover from (re-read, retry) rather than a thrown turn.
+                    return wrapToolResult({
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                if (!location) {
+                    return wrapToolResult({
+                        success: false,
+                        error: 'No artifact canvas is available in this context',
+                    });
+                }
+                return wrapToolResult({
+                    success: true,
+                    artifact: {
+                        artifactId: result.bundle.artifactId,
+                        title: result.bundle.title,
+                        kind: result.bundle.kind,
+                        viewport: result.bundle.viewport,
+                    },
+                    location,
+                    message: `Created artifact: ${result.bundle.title}`,
+                });
+            },
+        },
+        {
+            name: 'inspect_artifact',
+            label: 'Inspect Artifact',
+            description: 'Use Playwright to visually inspect an ArtifactBundle or a persisted artifact target. Returns a page screenshot, frame/page/slide metadata, optional individual frame screenshots, console messages, page errors, and failed requests. Use this after creating or revising artifacts to verify layout and individual slides/pages before responding.',
+            parameters: T.Object({
+                bundle: T.Optional(T.Object({}, {
+                    description: 'ArtifactBundle object to inspect before saving. If omitted, pass target or rely on the currently scoped artifact canvas.',
+                    additionalProperties: true,
+                })),
+                target: T.Optional(T.Object({
+                    repo: T.Optional(T.String({ description: 'Folder/repo containing the persisted artifact entry.' })),
+                    entityId: T.Optional(T.String({ description: 'Persisted artifact entity id to inspect.' })),
+                }, {
+                    description: 'Persisted artifact entry to inspect. If omitted while chat is scoped to an artifact, the current artifact is used.',
+                })),
+                context: T.Optional(T.Union([T.Literal('editor'), T.Literal('fullscreen')], {
+                    description: '"editor" renders the canvas overview/grid; "fullscreen" renders the share/fullscreen view. Defaults to editor.',
+                })),
+                frameSelector: T.Optional(T.String({
+                    description: 'CSS selector for individual frames/pages/slides. Defaults to display.controls.stepper.selector, then [data-artifact-frame], [data-artifact-page], .page.',
+                })),
+                frameIndexes: T.Optional(T.Array(T.Number(), {
+                    description: 'Specific zero-based frame/page/slide indexes to screenshot.',
+                })),
+                maxFrames: T.Optional(T.Number({
+                    description: 'Maximum number of individual frames/pages/slides to screenshot. Defaults to 6, max 24.',
+                })),
+                includePageScreenshot: T.Optional(T.Boolean({
+                    description: 'Whether to include a screenshot of the whole rendered page. Defaults to true.',
+                })),
+                includeFrameScreenshots: T.Optional(T.Boolean({
+                    description: 'Whether to include screenshots for selected frames/pages/slides. Defaults to true.',
+                })),
+                screenshotFormat: T.Optional(T.Union([T.Literal('jpeg'), T.Literal('png')], {
+                    description: 'Screenshot encoding. Defaults to jpeg to keep tool results compact.',
+                })),
+            }),
+            execute: async (_toolCallId, params) => {
+                let bundle;
+                if (params.bundle !== undefined) {
+                    const result = validateArtifactBundle(params.bundle);
+                    if (!result.ok || !result.bundle) {
+                        return wrapToolResult({
+                            success: false,
+                            error: 'Invalid artifact bundle',
+                            errors: result.errors,
+                            byteSize: result.byteSize,
+                        });
+                    }
+                    bundle = result.bundle;
+                }
+                else if (options.readArtifact) {
+                    try {
+                        bundle = (await options.readArtifact(params.target)).bundle;
+                    }
+                    catch (err) {
+                        return wrapToolResult({
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+                else {
+                    return wrapToolResult({
+                        success: false,
+                        error: 'No artifact bundle or readable artifact target was provided',
+                    });
+                }
+                try {
+                    const inspection = await inspectArtifact(bundle, {
+                        context: params.context,
+                        frameSelector: params.frameSelector,
+                        frameIndexes: params.frameIndexes,
+                        maxFrames: params.maxFrames,
+                        includePageScreenshot: params.includePageScreenshot,
+                        includeFrameScreenshots: params.includeFrameScreenshots,
+                        screenshotFormat: params.screenshotFormat,
+                    });
+                    return wrapToolResult({ success: true, inspection });
+                }
+                catch (err) {
+                    if (err instanceof ArtifactRenderExportUnavailableError) {
+                        return wrapToolResult({ success: false, error: err.message, code: 'PLAYWRIGHT_UNAVAILABLE' });
+                    }
+                    return wrapToolResult({
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            },
+        },
+        {
+            name: 'read_artifact',
+            label: 'Read Artifact',
+            description: 'Return the current source of a persisted artifact: its full ArtifactBundle plus a `hash` you MUST pass back to create_artifact as `baseHash` when saving an edit (so a concurrent change is detected rather than silently overwritten). When chat is scoped to an artifact, omit target to read the current canvas; otherwise pass target.repo and target.entityId. Call this before editing an existing artifact — its source is not kept in the conversation, so read it fresh each time you need to modify it.',
+            parameters: T.Object({
+                target: T.Optional(T.Object({
+                    repo: T.Optional(T.String({ description: 'Folder/repo containing the persisted artifact entry.' })),
+                    entityId: T.Optional(T.String({ description: 'Persisted artifact entity id to read.' })),
+                }, {
+                    description: 'Persisted artifact entry to read. If omitted while chat is scoped to an artifact, the current artifact is used.',
+                })),
+            }),
+            execute: async (_toolCallId, params) => {
+                if (!options.readArtifact) {
+                    return wrapToolResult({ success: false, error: 'No readable artifact is available in this context' });
+                }
+                try {
+                    const { bundle, hash, updatedAt } = await options.readArtifact(params.target);
+                    return wrapToolResult({ success: true, hash, updatedAt, bundle });
+                }
+                catch (err) {
+                    return wrapToolResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+                }
+            },
+        },
+    ];
+}
+//# sourceMappingURL=artifact-tools.js.map

package/dist/agent/tools/artifact-tools.js.map

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

package/dist/agent/tools/capture-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Capture-flow Tools for Studiograph Agent
+ *
+ * Single tool used by the quick-capture surface (POST /api/capture[/stream]).
+ * When the agent decides nothing in the user's input is worth saving as an
+ * entity, it calls `nothing_to_capture(reason)` and stops. The server
+ * captures the structured reason and surfaces it in the toast — no freeform
+ * assistant prose, no followup-suggestion marker leaking through.
+ *
+ * The tool is registered globally on every agent (so the Anthropic tool
+ * schema is consistent across sessions), but it's only meaningful when the
+ * capture flow has wired up `onNothingToCapture` in the AgentContext. In
+ * other contexts the callback is absent and the tool is effectively a
+ * no-op confirming back to the agent.
+ */
+import { Type as T } from 'typebox';
+export declare function createCaptureTools(onNothingToCapture: () => ((reason: string) => void) | null | undefined): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        reason: T.TString;
+    }>;
+    execute: (_toolCallId: string, params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+}[];

package/dist/agent/tools/capture-tools.js

@@ -0,0 +1,40 @@
+/**
+ * Capture-flow Tools for Studiograph Agent
+ *
+ * Single tool used by the quick-capture surface (POST /api/capture[/stream]).
+ * When the agent decides nothing in the user's input is worth saving as an
+ * entity, it calls `nothing_to_capture(reason)` and stops. The server
+ * captures the structured reason and surfaces it in the toast — no freeform
+ * assistant prose, no followup-suggestion marker leaking through.
+ *
+ * The tool is registered globally on every agent (so the Anthropic tool
+ * schema is consistent across sessions), but it's only meaningful when the
+ * capture flow has wired up `onNothingToCapture` in the AgentContext. In
+ * other contexts the callback is absent and the tool is effectively a
+ * no-op confirming back to the agent.
+ */
+import { Type as T } from 'typebox';
+import { wrapToolResult } from './graph-tools.js';
+export function createCaptureTools(onNothingToCapture) {
+    return [
+        {
+            name: 'nothing_to_capture',
+            label: 'Nothing to Capture',
+            description: 'Use ONLY in the quick-capture flow when the user\'s input contains no substantive content worth saving as an entity (e.g. an error page, an empty URL fetch, a redirect-only page, or pure noise). Call this with a brief one-line reason and STOP — do not produce any assistant text after, do not emit followups. Do not use this when the input is a normal note or article you should save: in that case call create_entity instead.',
+            parameters: T.Object({
+                reason: T.String({ description: 'One short sentence explaining why nothing is worth capturing. Shown to the user verbatim.' }),
+            }),
+            execute: async (_toolCallId, params) => {
+                const reason = String(params?.reason ?? '').trim();
+                if (!reason) {
+                    return wrapToolResult({ success: false, error: 'reason is required' });
+                }
+                const cb = onNothingToCapture();
+                if (cb)
+                    cb(reason);
+                return wrapToolResult({ success: true, recorded: true });
+            },
+        },
+    ];
+}
+//# sourceMappingURL=capture-tools.js.map

package/dist/agent/tools/capture-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-tools.js","sourceRoot":"","sources":["../../../src/agent/tools/capture-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,UAAU,kBAAkB,CAChC,kBAAuE;IAEvE,OAAO;QACL;YACE,IAAI,EAAE,oBAAoB;YAC1B,KAAK,EAAE,oBAAoB;YAC3B,WAAW,EAAE,2aAA2a;YACxb,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;gBACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2FAA2F,EAAE,CAAC;aAC/H,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,MAAW,EAAE,EAAE;gBAClD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBACnD,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,OAAO,cAAc,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,CAAC;gBACzE,CAAC;gBACD,MAAM,EAAE,GAAG,kBAAkB,EAAE,CAAC;gBAChC,IAAI,EAAE;oBAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBACnB,OAAO,cAAc,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/tools/folder-tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Folder Management Tools for the Studiograph Agent
+ *
+ * Five tools that let the agent operate on the folder layout within a repo:
+ *   - list_folders     — read the folder tree of a repo
+ *   - create_subfolder — create a new subfolder inside an existing repo
+ *                        (distinct from graph-tools' `create_folder`, which
+ *                        creates a brand-new top-level repo)
+ *   - rename_folder    — rename / move within the same repo
+ *   - move_entity      — relocate an entry to a different folder within the
+ *                        same repo (distinct from graph-tools'
+ *                        `transfer_entity`, which moves across repos)
+ *   - delete_folder    — remove a folder (recursive opt-in, blast-radius reported)
+ *
+ * The system prompt restraint rule applies to all of these:
+ * never reorganize/rename/delete without explicit user request.
+ */
+import { Type as T } from 'typebox';
+import { WorkspaceManager } from '../../core/workspace-manager.js';
+import { type AuthUser, type AuthService } from '../../services/auth-service.js';
+import type { MutationEvent } from './graph-tools.js';
+export declare function createFolderTools(workspaceManager: WorkspaceManager, gitUser: {
+    id: string;
+    name: string;
+    email: string;
+}, onMutation?: (m: MutationEvent) => void, getCurrentUser?: () => AuthUser | null, authService?: AuthService | null, 
+/**
+ * Same activity hook as createGraphTools. Currently accepted but not wrapped
+ * around individual folder ops — folder mutations are rare relative to entity
+ * mutations, and the chip wouldn't have time to render before completing.
+ * Param exists so the orchestrator can pass a single callback symmetrically.
+ */
+_onAgentActivity?: (action: 'enter' | 'leave' | 'heartbeat', repo: string) => void): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        repo: T.TString;
+    }>;
+    execute: (_toolCallId: string, params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+}[];