@granular-software/sdk 0.1.0 → 0.2.1

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 };

package/dist/index.d.ts

@@ -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.js';
-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.js';
+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.js';
+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.js';
+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 };