@granular-software/sdk 0.4.4 → 0.4.6

package/README.md

@@ -8,7 +8,7 @@ The official TypeScript SDK for Granular.
 
 - 🏗️ **Domain Ontology** — Define classes, properties, and relationships as a typed graph
 - 🔧 **Class-Based Tools** — Attach instance methods, static methods, and global tools with typed I/O
-- 🤖 **Domain Synthesis** — Auto-generated TypeScript classes with `find()`, relationship accessors, and typed methods
+- 🤖 **Domain Synthesis** — Auto-generated TypeScript classes with `get({ path })`, `list()`, relationship accessors, and typed methods
 - 🔒 **Secure Execution** — Run AI-generated code in isolated sandboxes
 - 👥 **User Permissions** — Control what each user can access
 - ⚡ **Real-time** — WebSocket-based streaming and events
@@ -33,7 +33,7 @@ Inside this monorepo, prefer the workspace package instead of installing from np
 By default, the SDK resolves endpoints like this:
 
 - Local mode (`NODE_ENV=development`): `ws://localhost:8787/granular`
-- Production mode (default): `wss://api.granular.dev/v2/ws`
+- Production mode (default): `wss://cf-api-gateway.arthur6084.workers.dev/granular`
 
 Overrides:
 
@@ -147,8 +147,10 @@ await granular.registerEffects(env.sandboxId, [
 const job = await env.submitJob(`
   import { Customer } from './sandbox-tools';
 
-  // Find returns a typed Customer instance with loaded field values
-  const acme = await Customer.find({ id: 'cust_42' });
+  // list() discovers instances; get({ path }) hydrates a specific graph object
+  const customers = await Customer.list();
+  const acme = customers.find((customer) => customer.name === 'Acme Corp');
+  if (!acme) throw new Error('Customer not found');
   console.log(acme.name);   // "Acme Corp"
   console.log(acme.email);  // "billing@acme.com"
 
@@ -340,8 +342,11 @@ export declare class Author {
 
   constructor(id: string, fields?: Record<string, any>);
 
-  /** Find an Author by ID */
-  static find(query: { id: string }): Promise<Author | null>;
+  /** Get a cached Author by graph path, hydrating from the graph when needed */
+  static get(query: { path: string; refresh?: boolean }): Promise<Author | null>;
+
+  /** List known Author instances */
+  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Author[]>;
 
   /** Get biography of an author */
   get_bio(input?: { detailed?: boolean }): Promise<{ bio: string; source?: string }>;
@@ -359,7 +364,9 @@ export declare class Book {
   readonly isbn: string;
   readonly published_year: number;
 
-  static find(query: { id: string }): Promise<Book | null>;
+  static get(query: { path: string; refresh?: boolean }): Promise<Book | null>;
+
+  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Book[]>;
 
   /** Navigate to author (many_to_one) */
   get_author(): Promise<Author | null>;
@@ -374,7 +381,9 @@ The LLM or user writes code against these typed classes:
 ```typescript
 import { Author, Book, global_search } from './sandbox-tools';
 
-const tolkien = await Author.find({ id: 'tolkien' });
+const authors = await Author.list();
+const tolkien = authors.find((author) => author.name === 'J.R.R. Tolkien');
+if (!tolkien) throw new Error('Author not found');
 console.log(tolkien.name);              // "J.R.R. Tolkien"
 
 const bio = await tolkien.get_bio({ detailed: true });

package/dist/cli/index.js

@@ -5387,7 +5387,7 @@ var import_dotenv = __toESM(require_main());
 
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
-var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
 var LOCAL_AUTH_URL = "http://localhost:3000";
 var PRODUCTION_AUTH_URL = "https://app.granular.software";
 function readEnv(name) {
@@ -5775,6 +5775,9 @@ var ApiClient = class {
       return false;
     }
   }
+  async validateKeyOrThrow() {
+    await this.request("/control/sandboxes");
+  }
   // ── Sandboxes ──
   async listSandboxes() {
     const result = await this.request("/control/sandboxes");
@@ -7768,7 +7771,31 @@ async function main() {
     await granular.registerEffects(SANDBOX_ID, ${effectsArray});
 
     log('Effects registered. Process kept alive for simulator. Press Ctrl+C to exit.');
-    await new Promise(() => {});
+
+    const keepAliveTimer = setInterval(() => {
+        // Keep an active event-loop handle so Bun/Node does not exit immediately.
+    }, 60_000);
+
+    await new Promise<void>((resolve) => {
+        let shuttingDown = false;
+
+        const shutdown = async (signal: string) => {
+            if (shuttingDown) return;
+            shuttingDown = true;
+            clearInterval(keepAliveTimer);
+            log(\`Received \${signal}. Shutting down effects host...\`);
+            try {
+                await granular.disconnectEffects(SANDBOX_ID);
+            } catch (error) {
+                console.warn('[Effects] Failed to disconnect live effects cleanly:', error);
+            }
+            resolve();
+            process.exit(0);
+        };
+
+        process.once('SIGINT', () => { void shutdown('SIGINT'); });
+        process.once('SIGTERM', () => { void shutdown('SIGTERM'); });
+    });
 }
 
 main().catch((err) => {
@@ -7847,9 +7874,11 @@ async function initCommand(projectName, options) {
   const apiUrl = loadApiUrl();
   const api = new ApiClient(apiKey, apiUrl);
   const validating = spinner("Validating API key...");
-  const isValid = await api.validateKey();
-  if (!isValid) {
-    validating.fail("  Invalid API key. Please check your key and try again.");
+  try {
+    await api.validateKeyOrThrow();
+  } catch (err) {
+    const detail = err?.message ? ` (${err.message})` : "";
+    validating.fail(`  API key validation failed${detail}.`);
     process.exit(1);
   }
   validating.succeed("  API key validated.");
@@ -8015,9 +8044,11 @@ async function loginCommand(options = {}) {
   }
   const spinner2 = spinner("Validating...");
   const api = new ApiClient(apiKey, apiUrl);
-  const valid = await api.validateKey();
-  if (!valid) {
-    spinner2.fail("  Invalid API key.");
+  try {
+    await api.validateKeyOrThrow();
+  } catch (err) {
+    const detail = err?.message ? ` (${err.message})` : "";
+    spinner2.fail(`  API key validation failed${detail}.`);
     process.exit(1);
   }
   saveApiKey(apiKey);
@@ -8707,12 +8738,16 @@ console.log('Connected to:', env.environmentId);`);
   if (classes.length > 0) {
     const cls = classes[0];
     const ClassName = cls.name.charAt(0).toUpperCase() + cls.name.slice(1);
-    lines.push(`  // 1. Find object`);
-    lines.push(`  const item = await ${ClassName}.find({ id: 'unique_${cls.name}_id' });`);
-    lines.push(`  console.log('Found:', item.id);`);
+    lines.push(`  // 1. List objects`);
+    lines.push(`  const items = await ${ClassName}.list({ limit: 10, saveAs: '${cls.name}_items' });`);
+    lines.push(`  const item = items[0] ?? null;`);
+    lines.push(`  console.log('Loaded:', item?.id);`);
     lines.push(``);
     lines.push(`  // 2. Call instance method`);
-    lines.push(`  const summary = await item.summarize({ maxLength: 100 });`);
+    lines.push(`  if (item) {`);
+    lines.push(`    const summary = await item.summarize({ maxLength: 100 });`);
+    lines.push(`    console.log(summary);`);
+    lines.push(`  }`);
     lines.push(``);
     lines.push(`  // 3. Call static method`);
     lines.push(`  const results = await ${ClassName}.search({ query: 'test' });`);

package/dist/index.d.mts

@@ -88,6 +88,11 @@ interface ConnectOptions {
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
+    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
 }
 /**
  * A sandbox container
@@ -454,6 +459,47 @@ interface Prompt {
     options?: string[];
     defaultValue?: unknown;
 }
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+interface SessionHeapFieldValue {
+    name: string;
+    type: SessionHeapFieldType;
+    value: string | number | boolean | null;
+}
+interface SessionHeapEntry {
+    path: string;
+    className: string;
+    id: string;
+    label?: string | null;
+    description?: string | null;
+    prototypes: string[];
+    fields: SessionHeapFieldValue[];
+    relatedJobIds: string[];
+    source: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionHeapList {
+    name: string;
+    className: string;
+    paths: string[];
+    relatedJobIds: string[];
+    updatedAt: number;
+}
+interface SessionHeapVariable {
+    name: string;
+    kind: 'entry' | 'list' | 'scalar';
+    entryPath?: string;
+    listName?: string;
+    value?: string | number | boolean | null;
+    className?: string;
+    updatedAt: number;
+}
+interface SessionHeapSnapshot {
+    entriesByPath: Record<string, SessionHeapEntry>;
+    listsByName: Record<string, SessionHeapList>;
+    variablesByName: Record<string, SessionHeapVariable>;
+    updatedAt: number;
+}
 interface WSDisconnectInfo {
     code?: number;
     reason?: string;
@@ -858,7 +904,8 @@ declare class Session {
      * ```typescript
      * import { Author, Book, global_search } from './sandbox-tools';
      *
-     * const tolkien = await Author.find({ id: 'tolkien' });
+     * const authors = await Author.list({ limit: 10, saveAs: 'recent_authors' });
+     * const tolkien = await Author.get({ path: 'author_tolkien' });
      * const bio = await tolkien.get_bio({ detailed: true });
      * const books = await tolkien.get_books();
      * ```
@@ -974,6 +1021,13 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /**
+     * Return a plain JS snapshot of the synced session heap.
+     *
+     * The heap lives in the Automerge document, so this method does not perform
+     * any extra network roundtrip.
+     */
+    getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
     /**
      * Close the session and disconnect from the sandbox.
@@ -1357,6 +1411,13 @@ declare class Granular {
      * sandbox-scoped live catalog.
      */
     unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * Disconnect one sandbox-scoped effect host, or all of them when no sandbox is provided.
+     *
+     * This is primarily useful for long-lived helper processes such as generated
+     * `granular-effects.ts` scripts that need to shut down cleanly on SIGINT/SIGTERM.
+     */
+    disconnectEffects(sandboxNameOrId?: string): Promise<void>;
     /**
      * Unregister all effects for a sandbox.
      */
@@ -1427,4 +1488,4 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };

package/dist/index.d.ts

@@ -88,6 +88,11 @@ interface ConnectOptions {
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
+    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
 }
 /**
  * A sandbox container
@@ -454,6 +459,47 @@ interface Prompt {
     options?: string[];
     defaultValue?: unknown;
 }
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+interface SessionHeapFieldValue {
+    name: string;
+    type: SessionHeapFieldType;
+    value: string | number | boolean | null;
+}
+interface SessionHeapEntry {
+    path: string;
+    className: string;
+    id: string;
+    label?: string | null;
+    description?: string | null;
+    prototypes: string[];
+    fields: SessionHeapFieldValue[];
+    relatedJobIds: string[];
+    source: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionHeapList {
+    name: string;
+    className: string;
+    paths: string[];
+    relatedJobIds: string[];
+    updatedAt: number;
+}
+interface SessionHeapVariable {
+    name: string;
+    kind: 'entry' | 'list' | 'scalar';
+    entryPath?: string;
+    listName?: string;
+    value?: string | number | boolean | null;
+    className?: string;
+    updatedAt: number;
+}
+interface SessionHeapSnapshot {
+    entriesByPath: Record<string, SessionHeapEntry>;
+    listsByName: Record<string, SessionHeapList>;
+    variablesByName: Record<string, SessionHeapVariable>;
+    updatedAt: number;
+}
 interface WSDisconnectInfo {
     code?: number;
     reason?: string;
@@ -858,7 +904,8 @@ declare class Session {
      * ```typescript
      * import { Author, Book, global_search } from './sandbox-tools';
      *
-     * const tolkien = await Author.find({ id: 'tolkien' });
+     * const authors = await Author.list({ limit: 10, saveAs: 'recent_authors' });
+     * const tolkien = await Author.get({ path: 'author_tolkien' });
      * const bio = await tolkien.get_bio({ detailed: true });
      * const books = await tolkien.get_books();
      * ```
@@ -974,6 +1021,13 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /**
+     * Return a plain JS snapshot of the synced session heap.
+     *
+     * The heap lives in the Automerge document, so this method does not perform
+     * any extra network roundtrip.
+     */
+    getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
     /**
      * Close the session and disconnect from the sandbox.
@@ -1357,6 +1411,13 @@ declare class Granular {
      * sandbox-scoped live catalog.
      */
     unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * Disconnect one sandbox-scoped effect host, or all of them when no sandbox is provided.
+     *
+     * This is primarily useful for long-lived helper processes such as generated
+     * `granular-effects.ts` scripts that need to shut down cleanly on SIGINT/SIGTERM.
+     */
+    disconnectEffects(sandboxNameOrId?: string): Promise<void>;
     /**
      * Unregister all effects for a sandbox.
      */
@@ -1427,4 +1488,4 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };

package/dist/index.js

@@ -4577,7 +4577,8 @@ var Session = class {
    * ```typescript
    * import { Author, Book, global_search } from './sandbox-tools';
    *
-   * const tolkien = await Author.find({ id: 'tolkien' });
+   * const authors = await Author.list({ limit: 10, saveAs: 'recent_authors' });
+   * const tolkien = await Author.get({ path: 'author_tolkien' });
    * const bio = await tolkien.get_bio({ detailed: true });
    * const books = await tolkien.get_books();
    * ```
@@ -5089,7 +5090,7 @@ var JobImplementation = class {
 
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
-var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
 function readEnv(name) {
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env[name];
@@ -5176,6 +5177,26 @@ function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
   url.searchParams.set("clientId", clientId);
   return url.toString();
 }
+function createEmptyHeapSnapshot(now = Date.now()) {
+  return {
+    entriesByPath: {},
+    listsByName: {},
+    variablesByName: {},
+    updatedAt: now
+  };
+}
+function normalizeHeapSnapshot(raw) {
+  if (!raw || typeof raw !== "object") {
+    return createEmptyHeapSnapshot();
+  }
+  const heap = raw;
+  return {
+    entriesByPath: heap.entriesByPath && typeof heap.entriesByPath === "object" ? JSON.parse(JSON.stringify(heap.entriesByPath)) : {},
+    listsByName: heap.listsByName && typeof heap.listsByName === "object" ? JSON.parse(JSON.stringify(heap.listsByName)) : {},
+    variablesByName: heap.variablesByName && typeof heap.variablesByName === "object" ? JSON.parse(JSON.stringify(heap.variablesByName)) : {},
+    updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
+  };
+}
 var Environment = class _Environment extends Session {
   envData;
   _apiKey;
@@ -5206,6 +5227,16 @@ var Environment = class _Environment extends Session {
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  /**
+   * Return a plain JS snapshot of the synced session heap.
+   *
+   * The heap lives in the Automerge document, so this method does not perform
+   * any extra network roundtrip.
+   */
+  getHeap() {
+    const doc = this.document;
+    return normalizeHeapSnapshot(doc?.heap);
+  }
   getRuntimeBaseUrl() {
     try {
       const endpoint = new URL(this._apiEndpoint);
@@ -6067,7 +6098,8 @@ var Granular = class {
       method: "POST",
       body: JSON.stringify({
         environmentId: envData.environmentId,
-        clientId
+        clientId,
+        initialHeap: options.initialHeap
       })
     });
     const client = new WSClient({
@@ -6118,7 +6150,21 @@ var Granular = class {
     const effects = Array.from(this.getSandboxEffectMap(host.sandboxId).values()).map(
       (effect) => this.serializeEffect(effect)
     );
-    await host.wsClient.call("effects.publishCatalog", { effects });
+    const result = await host.wsClient.call("effects.publishCatalog", { effects });
+    const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
+    const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
+    if (acceptedCount === 0 && rejected.length > 0) {
+      const detail = rejected.map((entry) => `${entry.name || "unknown"}: ${entry.reason || "rejected"}`).join("; ");
+      throw new Error(
+        `Failed to publish live effects for sandbox ${host.sandboxId}: ${detail}`
+      );
+    }
+    if (rejected.length > 0) {
+      console.warn(
+        `[Granular] Some live effects were rejected for sandbox ${host.sandboxId}:`,
+        rejected
+      );
+    }
   }
   async syncSandboxEffectCatalog(sandboxId) {
     const host = await this.ensureSandboxEffectHost(sandboxId);
@@ -6284,6 +6330,22 @@ var Granular = class {
     }
     await this.syncSandboxEffectCatalog(sandboxId);
   }
+  /**
+   * Disconnect one sandbox-scoped effect host, or all of them when no sandbox is provided.
+   *
+   * This is primarily useful for long-lived helper processes such as generated
+   * `granular-effects.ts` scripts that need to shut down cleanly on SIGINT/SIGTERM.
+   */
+  async disconnectEffects(sandboxNameOrId) {
+    if (sandboxNameOrId) {
+      const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
+      this.disconnectSandboxEffectHost(sandbox.sandboxId);
+      return;
+    }
+    for (const sandboxId of Array.from(this.sandboxEffectHosts.keys())) {
+      this.disconnectSandboxEffectHost(sandboxId);
+    }
+  }
   /**
    * Unregister all effects for a sandbox.
    */