@granular-software/sdk 0.2.0 → 0.2.1

package/dist/adapters/anthropic.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.mjs';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.js';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/langchain.d.mts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.mjs';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/langchain.d.ts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.js';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/mastra.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.mjs';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/mastra.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.js';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/openai.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.mjs';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-DiMEb3SE.js';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/cli/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 'use strict';
 
+var fs = require('fs');
 var path = require('path');
 var readline = require('readline');
-var fs = require('fs');
 var process6 = require('process');
 var os = require('os');
 var tty = require('tty');
+var child_process = require('child_process');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -28,9 +29,9 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
-var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var process6__default = /*#__PURE__*/_interopDefault(process6);
 var os__default = /*#__PURE__*/_interopDefault(os);
 var tty__default = /*#__PURE__*/_interopDefault(tty);
@@ -1185,7 +1186,7 @@ var require_command = __commonJS({
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
     var path4 = __require("path");
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var process10 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -2165,7 +2166,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs4.existsSync(executableFile)) return;
+        if (fs5.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2184,10 +2185,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path4.resolve(baseDir, baseName);
-          if (fs4.existsSync(localBin)) return localBin;
+          if (fs5.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path4.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs4.existsSync(`${localBin}${ext}`)
+            (ext) => fs5.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2199,7 +2200,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs4.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs5.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
@@ -3430,7 +3431,7 @@ var require_package = __commonJS({
 // ../../node_modules/.bun/dotenv@16.6.1/node_modules/dotenv/lib/main.js
 var require_main = __commonJS({
   "../../node_modules/.bun/dotenv@16.6.1/node_modules/dotenv/lib/main.js"(exports, module) {
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var path4 = __require("path");
     var os2 = __require("os");
     var crypto = __require("crypto");
@@ -3539,7 +3540,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs4.existsSync(filepath)) {
+            if (fs5.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -3549,7 +3550,7 @@ var require_main = __commonJS({
       } else {
         possibleVaultPath = path4.resolve(process.cwd(), ".env.vault");
       }
-      if (fs4.existsSync(possibleVaultPath)) {
+      if (fs5.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
@@ -3598,7 +3599,7 @@ var require_main = __commonJS({
       const parsedAll = {};
       for (const path5 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs4.readFileSync(path5, { encoding }));
+          const parsed = DotenvModule.parse(fs5.readFileSync(path5, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
@@ -5535,6 +5536,18 @@ function createDefaultManifest(name) {
     }
   };
 }
+var STD_CLASS_NAMES = /* @__PURE__ */ new Set(["entity", "class", "user", "company", "string", "number", "boolean", "tool_parameter"]);
+function getClassNamesFromManifest(manifest) {
+  const names = /* @__PURE__ */ new Set();
+  for (const vol of manifest.volumes ?? []) {
+    for (const op of vol.operations ?? []) {
+      if (op.create && !STD_CLASS_NAMES.has(op.create)) {
+        names.add(op.create);
+      }
+    }
+  }
+  return Array.from(names);
+}
 function resolveConfig(options) {
   const apiKey = loadApiKey();
   const apiUrl = loadApiUrl();
@@ -7119,6 +7132,183 @@ function buildStatus(status) {
 }
 
 // src/cli/commands/init.ts
+var EFFECTS_SCRIPT_NAME = "granular-effects.ts";
+function toWsUrl(apiUrl) {
+  return apiUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
+}
+function generateEffectsScript(sandboxId, apiUrl, classNames) {
+  const wsUrl = toWsUrl(apiUrl);
+  classNames.length > 0;
+  const mockDataEntries = classNames.map(
+    (c) => `        ${c}: [
+            { id: '${c}_001', name: 'Sample ${c}' },
+            { id: '${c}_002', name: 'Another ${c}' },
+        ]`
+  );
+  const mockDataBlock = mockDataEntries.length > 0 ? `const MOCK_DATA: Record<string, any[]> = {
+${mockDataEntries.join(",\n")},
+    };` : "const MOCK_DATA: Record<string, any[]> = {};";
+  const instanceEffects = classNames.map((className) => {
+    className.charAt(0).toUpperCase() + className.slice(1);
+    return `        {
+            name: 'get_info',
+            description: \`Get details of a ${className} by ID\`,
+            className: '${className}',
+            inputSchema: {
+                type: 'object',
+                properties: { include_related: { type: 'boolean', description: 'Include related items' } },
+            },
+            handler: async (id: string, params: any) => {
+                logEffect('get_info', '${className}', id, params);
+                const item = (MOCK_DATA['${className}'] || []).find((x: any) => x.id === id);
+                if (!item) return { error: \`${className} "\${id}" not found\` };
+                return { ...item, ...(params?.include_related ? { related: [] } : {}) };
+            },
+        }`;
+  });
+  const staticEffects = classNames.map((className) => {
+    const searchName = "search_" + className + "s";
+    return `        {
+            name: '${searchName}',
+            description: \`Search ${className}s by keyword\`,
+            className: '${className}',
+            static: true,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search keyword' },
+                    limit: { type: 'number', description: 'Max results' },
+                },
+                required: ['query'],
+            },
+            handler: async (params: any) => {
+                logEffect('${searchName}', null, null, params);
+                const q = ((params?.query) || '').toLowerCase();
+                const limit = params?.limit ?? 10;
+                const list = (MOCK_DATA['${className}'] || []).filter((x: any) =>
+                    String(x.name || x.id || '').toLowerCase().includes(q)
+                ).slice(0, limit);
+                return { query: params?.query, results: list, total: list.length };
+            },
+        }`;
+  });
+  const allEffects = [...instanceEffects, ...staticEffects];
+  if (allEffects.length > 0) {
+    allEffects.push(`        {
+            name: 'full_text_search',
+            description: 'Search across all types',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search query' },
+                    types: { type: 'array', items: { type: 'string' }, description: 'Filter by type' },
+                },
+                required: ['query'],
+            },
+            handler: async (params: any) => {
+                logEffect('full_text_search', null, null, params);
+                const q = ((params?.query) || '').toLowerCase();
+                const types: string[] = params?.types || [${classNames.map((c) => `'${c}'`).join(", ")}];
+                const matches: any[] = [];
+                for (const type of types) {
+                    const items = MOCK_DATA[type] || [];
+                    for (const item of items) {
+                        const text = Object.values(item).join(' ').toLowerCase();
+                        if (!q || text.includes(q)) {
+                            matches.push({ type, id: item.id, label: item.name || item.id, snippet: text.slice(0, 60) });
+                        }
+                    }
+                }
+                return { query: params?.query, types, matches, total: matches.length };
+            },
+        }`);
+  }
+  const effectsArray = allEffects.length > 0 ? `[
+${allEffects.join(",\n")}
+    ]` : "[]";
+  return `/**
+ * Granular effects script for sandbox ${sandboxId}
+ * Run with: npx tsx ${EFFECTS_SCRIPT_NAME}
+ * Requires: GRANULAR_API_KEY in env or .env.local, and optional "ws" package for Node.
+ *
+ * Keeps the process alive so the simulator can invoke these effect handlers.
+ */
+
+import { Granular } from '@granular-software/sdk';
+
+const SANDBOX_ID = '${sandboxId}';
+const API_URL = '${wsUrl}';
+
+function log(msg: string) {
+    console.log(\`[\${new Date().toISOString()}] [Effects] \${msg}\`);
+}
+
+function logEffect(name: string, className: string | null, id: string | null, params: any) {
+    const target = className ? (id ? \`\${className}(\${id})\` : \`\${className}\`) : 'global';
+    console.log(\`  [EFFECT] \${name}(\${target}) \${JSON.stringify(params || {})}\`);
+}
+
+async function main() {
+    const apiKey = process.env.GRANULAR_API_KEY;
+    if (!apiKey) {
+        console.error('[Effects] GRANULAR_API_KEY is required (set in .env.local or environment).');
+        process.exit(1);
+    }
+
+    let WebSocketCtor: any;
+    try {
+        WebSocketCtor = (await import('ws')).default;
+    } catch {
+        log('Optional: install "ws" for Node.js WebSocket support. Using global WebSocket.');
+    }
+
+    log('Initializing client...');
+    const granular = new Granular({
+        apiKey,
+        apiUrl: API_URL,
+        ...(WebSocketCtor && { WebSocketCtor }),
+    });
+
+    const userId = 'effects_user';
+    log(\`Recording user \${userId}\`);
+    const user = await granular.recordUser({
+        userId,
+        name: 'Effects Host',
+        permissions: ['default'],
+    });
+
+    log(\`Connecting to sandbox \${SANDBOX_ID}\`);
+    const env = await granular.connect({ sandbox: SANDBOX_ID, user, clientId: 'effects-host' });
+
+    log('Waiting for graph container to be ready...');
+    for (let i = 0; i < 6; i++) {
+        await new Promise((r) => setTimeout(r, 5000));
+        try {
+            const probe = await env.graphql(\`query { model(path: "class") { path } }\`);
+            if ((probe as any)?.data?.model?.path) {
+                log(\`Graph ready after \${(i + 1) * 5}s\`);
+                break;
+            }
+        } catch {
+            log(\`Not ready yet (\${(i + 1) * 5}s)...\`);
+        }
+    }
+
+    log('Publishing effects...');
+    ${mockDataBlock}
+
+    await env.publishEffects(${effectsArray});
+
+    log('Effects published. Process kept alive for simulator. Press Ctrl+C to exit.');
+    await new Promise(() => {});
+}
+
+main().catch((err) => {
+    console.error('[Effects] Failed:', err);
+    process.exit(1);
+});
+`;
+}
 function prompt(question, defaultValue) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   const suffix = defaultValue ? ` ${brand.muted(`(${defaultValue})`)}` : "";
@@ -7228,6 +7418,11 @@ async function initCommand(projectName) {
       dim("You can retry with `granular build`");
     }
   }
+  const classNames = getClassNamesFromManifest(project.manifest);
+  const effectsPath = path__namespace.join(getProjectRoot(), EFFECTS_SCRIPT_NAME);
+  const effectsContent = generateEffectsScript(sandbox.sandboxId, apiUrl, classNames);
+  fs__namespace.writeFileSync(effectsPath, effectsContent, "utf-8");
+  success(`Created ${brand.bold(EFFECTS_SCRIPT_NAME)} (effects script for simulator)`);
   console.log();
   divider();
   console.log();
@@ -7237,13 +7432,20 @@ async function initCommand(projectName) {
     "Sandbox": sandbox.sandboxId,
     "Manifest": "granular.json",
     "Config": ".granularrc",
-    "API Key": ".env.local"
+    "API Key": ".env.local",
+    "Effects script": EFFECTS_SCRIPT_NAME
   });
   nextSteps([
     { command: "granular add class <name>", description: "Add a class to your schema" },
     { command: "granular build", description: "Build your sandbox" },
     { command: "granular status", description: "Check build status" }
   ]);
+  console.log();
+  dim("Run the effects script (keeps process alive for simulator):");
+  hint(`npx tsx ${EFFECTS_SCRIPT_NAME}`, "requires tsx and GRANULAR_API_KEY in .env.local");
+  dim("Open the simulator in your browser:");
+  hint("granular simulate", "opens app.granular.software/simulator for this sandbox");
+  console.log();
 }
 function promptSecret2(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
@@ -7994,6 +8196,22 @@ console.log('Connected to:', env.environmentId);`);
   spinner2.succeed(`Generated ${brand.bold("GRANULAR.md")}`);
   info(`Open GRANULAR.md to see your project documentation.`);
 }
+var SIMULATOR_BASE = "https://app.granular.software/simulator";
+function openUrl(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  child_process.spawn(cmd, [url], { stdio: "ignore", shell: platform === "win32" });
+}
+async function simulateCommand(sandboxIdArg) {
+  const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
+  if (!sandboxId) {
+    error("No sandbox ID. Run from a project with `granular init` or pass a sandbox ID: granular simulate <sandbox-id>");
+    process.exit(1);
+  }
+  const url = `${SIMULATOR_BASE}?sandboxId=${encodeURIComponent(sandboxId)}`;
+  info(`Opening simulator: ${url}`);
+  openUrl(url);
+}
 
 // src/cli/index.ts
 var VERSION = "0.2.0";
@@ -8096,4 +8314,12 @@ program2.command("document").description("Generate GRANULAR.md documentation fro
     process.exit(1);
   }
 });
+program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").action(async (sandboxId) => {
+  try {
+    await simulateCommand(sandboxId);
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+});
 program2.parse(process.argv);

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as Automerge from '@automerge/automerge';
-import { Doc } from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, b as GraphQLResult, c as DefineRelationshipOptions, d as RelationshipInfo, M as ModelRef, e as ManifestContent, f as RecordObjectOptions, g as RecordObjectResult, S as SandboxListResponse, h as Sandbox, i as CreateSandboxData, j as DeleteResponse, k as PermissionProfile, l as CreatePermissionProfileData, m as CreateEnvironmentData, n as Subject, A as AssignmentListResponse } from './types-D46q5WTh.mjs';
-export { $ as APIError, r as Assignment, w as Build, x as BuildListResponse, B as BuildPolicy, v as BuildStatus, s as EnvironmentListResponse, y as JobStatus, z as JobSubmitResult, t as Manifest, Z as ManifestImport, u as ManifestListResponse, Y as ManifestOperation, V as ManifestPropertySpec, X as ManifestRelationshipDef, _ as ManifestVolume, q as PermissionProfileListResponse, p as PermissionRules, F as Prompt, H as RPCRequest, N as RPCRequestFromServer, K as RPCResponse, L as SyncMessage, O as ToolInvokeParams, Q as ToolResultParams, o as ToolSchema } from './types-D46q5WTh.mjs';
+import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, b as ToolInfo, c as ToolsChangedEvent, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, d as GraphQLResult, e as DefineRelationshipOptions, f as RelationshipInfo, M as ModelRef, g as ManifestContent, h as RecordObjectOptions, i as RecordObjectResult, S as SandboxListResponse, j as Sandbox, k as CreateSandboxData, l as DeleteResponse, m as PermissionProfile, n as CreatePermissionProfileData, o as CreateEnvironmentData, p as Subject, A as AssignmentListResponse } from './types-DiMEb3SE.mjs';
+export { a1 as APIError, t as Assignment, y as Build, z as BuildListResponse, B as BuildPolicy, x as BuildStatus, u as EnvironmentListResponse, F as JobStatus, H as JobSubmitResult, v as Manifest, $ as ManifestImport, w as ManifestListResponse, _ as ManifestOperation, Y as ManifestPropertySpec, Z as ManifestRelationshipDef, a0 as ManifestVolume, s as PermissionProfileListResponse, r as PermissionRules, K as Prompt, L as RPCRequest, Q as RPCRequestFromServer, N as RPCResponse, O as SyncMessage, V as ToolInvokeParams, X as ToolResultParams, q as ToolSchema } from './types-DiMEb3SE.mjs';
+import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
     private ws;
@@ -17,6 +17,7 @@ declare class WSClient {
     private syncState;
     private reconnectTimer;
     private isExplicitlyDisconnected;
+    private options;
     constructor(options: WSClientOptions);
     /**
      * Connect to the WebSocket server
@@ -73,6 +74,10 @@ declare class Session {
     /** Tracks which tools are instance methods (className set, not static) */
     private instanceTools;
     private currentDomainRevision;
+    /** Local effect registry: name → full ToolWithHandler */
+    private effects;
+    /** Last known tools for diffing */
+    private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
     get document(): Doc<Record<string, unknown>>;
     get domainRevision(): string | null;
@@ -140,6 +145,64 @@ declare class Session {
      * ```
      */
     publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
+    /**
+     * Publish a single effect (tool) to the sandbox.
+     *
+     * Adds the effect to the local registry and re-publishes the
+     * full tool catalog to the server. If an effect with the same
+     * name already exists, it is replaced.
+     *
+     * @param effect - The effect (tool) to publish
+     * @returns PublishToolsResult with domainRevision
+     *
+     * @example
+     * ```typescript
+     * await env.publishEffect({
+     *   name: 'get_bio',
+     *   description: 'Get biography of an author',
+     *   className: 'author',
+     *   inputSchema: { type: 'object', properties: { detailed: { type: 'boolean' } } },
+     *   handler: async (id, params) => ({ bio: `Bio of ${id}` }),
+     * });
+     * ```
+     */
+    publishEffect(effect: ToolWithHandler): Promise<PublishToolsResult>;
+    /**
+     * Publish multiple effects (tools) at once.
+     *
+     * Adds all effects to the local registry and re-publishes the
+     * full tool catalog in a single RPC call.
+     *
+     * @param effects - Array of effects to publish
+     * @returns PublishToolsResult with domainRevision
+     *
+     * @example
+     * ```typescript
+     * await env.publishEffects([
+     *   { name: 'get_bio', description: '...', inputSchema: {}, handler: async (id) => ({}) },
+     *   { name: 'search', description: '...', inputSchema: {}, handler: async (params) => ({}) },
+     * ]);
+     * ```
+     */
+    publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
+    /**
+     * Remove an effect by name and re-publish the remaining catalog.
+     *
+     * @param name - The name of the effect to remove
+     * @returns PublishToolsResult with domainRevision
+     */
+    unpublishEffect(name: string): Promise<PublishToolsResult>;
+    /**
+     * Remove all effects and publish an empty catalog.
+     *
+     * @returns PublishToolsResult with domainRevision
+     */
+    unpublishAllEffects(): Promise<PublishToolsResult>;
+    /**
+     * Internal: re-publish the full effect catalog to the server.
+     * Called after any mutation to the effects Map.
+     */
+    private _syncEffects;
     /**
      * Submit a job to execute code in the sandbox.
      *
@@ -166,6 +229,17 @@ declare class Session {
      * Respond to a prompt request from the sandbox
      */
     answerPrompt(promptId: string, answer: unknown): Promise<void>;
+    /**
+     * Get the current list of available tools.
+     * Consolidates tools from all connected clients.
+     */
+    getTools(): ToolInfo[];
+    /**
+     * Subscribe to tool changes (added, removed, updated).
+     * @param callback - Function called with change events
+     * @returns Unsubscribe function
+     */
+    onToolsChanged(callback: (event: ToolsChangedEvent) => void): () => void;
     /**
      * Get the current domain state and available tools
      */
@@ -208,6 +282,10 @@ declare class Session {
     private setupToolInvokeHandler;
     private setupEventHandlers;
     private emit;
+    /**
+     * Check for changes in the tool catalog and emit 'tools:changed' if needed
+     */
+    private checkForToolChanges;
 }
 
 /**
@@ -219,6 +297,7 @@ declare class Session {
  * 3. Publish tools via `publishTools()` (instance methods, static methods, global tools — with typed I/O)
  * 4. Submit jobs via `submitJob()` that import auto-generated typed classes from `./sandbox-tools`
  * 5. Execute GraphQL queries via `graphql()` (authenticated automatically)
+ * 6. List available tools via `getTools()` and listen for updates via `onToolsChanged()`
  *
  * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
  *
@@ -485,11 +564,49 @@ declare class Environment extends Session {
      * ```
      */
     publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
+    /**
+     * Publish a single effect (tool) incrementally.
+     *
+     * Adds the effect to the local registry and re-publishes the
+     * full tool catalog to the server. If an effect with the same
+     * name already exists, it is replaced.
+     *
+     * @example
+     * ```typescript
+     * await env.publishEffect({
+     *   name: 'get_bio',
+     *   description: 'Get biography',
+     *   inputSchema: { type: 'object', properties: { detailed: { type: 'boolean' } } },
+     *   handler: async (params) => ({ bio: 'Hello' }),
+     * });
+     * ```
+     */
+    publishEffect(effect: ToolWithHandler): Promise<PublishToolsResult>;
+    /**
+     * Publish multiple effects (tools) at once.
+     *
+     * Adds all effects to the local registry and re-publishes the
+     * full tool catalog in a single RPC call.
+     */
+    publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
+    /**
+     * Remove an effect by name and re-publish the remaining catalog.
+     */
+    unpublishEffect(name: string): Promise<PublishToolsResult>;
+    /**
+     * Remove all effects and publish an empty catalog.
+     */
+    unpublishAllEffects(): Promise<PublishToolsResult>;
 }
 declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private WebSocketCtor?;
+    /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
+    private sandboxEffects;
+    /** Active environments tracker: sandboxId → Environment[] */
+    private activeEnvironments;
     /**
      * Create a new Granular client
      * @param options - Client configuration
@@ -547,6 +664,34 @@ declare class Granular {
      * ```
      */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * Register an effect (tool) for a specific sandbox.
+     *
+     * The effect will be automatically published to:
+     * 1. Any currently active environments for this sandbox
+     * 2. Any new environments created/connected for this sandbox
+     *
+     * @param sandboxNameOrId - The name or ID of the sandbox
+     * @param effect - The tool definition and handler
+     */
+    registerEffect(sandboxNameOrId: string, effect: ToolWithHandler): Promise<void>;
+    /**
+     * Register multiple effects (tools) for a specific sandbox.
+     *
+     * batch version of `registerEffect`.
+     */
+    registerEffects(sandboxNameOrId: string, effects: ToolWithHandler[]): Promise<void>;
+    /**
+     * Unregister an effect from a sandbox.
+     *
+     * Removes it from the local registry and unpublishes it from
+     * all active environments.
+     */
+    unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * Unregister all effects for a sandbox.
+     */
+    unregisterAllEffects(sandboxNameOrId: string): Promise<void>;
     /**
      * Find a sandbox by name or create it if it doesn't exist
      */
@@ -613,4 +758,4 @@ declare class Granular {
     private request;
 }
 
-export { AssignmentListResponse, ConnectOptions, CreateEnvironmentData, CreatePermissionProfileData, CreateSandboxData, DefineRelationshipOptions, DeleteResponse, DomainState, Environment, EnvironmentData, Granular, GranularOptions, GraphQLResult, InstanceToolHandler, Job, ManifestContent, ModelRef, PermissionProfile, PublishToolsResult, RecordObjectOptions, RecordObjectResult, RecordUserOptions, RelationshipInfo, Sandbox, SandboxListResponse, Session, Subject, ToolHandler, ToolWithHandler, User, WSClient, WSClientOptions };
+export { AssignmentListResponse, ConnectOptions, CreateEnvironmentData, CreatePermissionProfileData, CreateSandboxData, DefineRelationshipOptions, DeleteResponse, DomainState, Environment, EnvironmentData, Granular, GranularOptions, GraphQLResult, InstanceToolHandler, Job, ManifestContent, ModelRef, PermissionProfile, PublishToolsResult, RecordObjectOptions, RecordObjectResult, RecordUserOptions, RelationshipInfo, Sandbox, SandboxListResponse, Session, Subject, ToolHandler, ToolInfo, ToolWithHandler, ToolsChangedEvent, User, WSClient, WSClientOptions };