@granular-software/sdk 0.4.1 → 0.4.3

package/README.md

@@ -32,7 +32,7 @@ npm install @granular-software/sdk
 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:
 
@@ -112,8 +112,8 @@ await env.recordObject({
   fields: { name: 'Acme Corp', email: 'billing@acme.com', tier: 'enterprise' },
 });
 
-// 5. Publish tools with typed input AND output schemas
-await env.publishTools([
+// 5. Register live effect handlers for effects already declared in the build manifest
+await granular.registerEffects(env.sandboxId, [
   {
     name: 'get_billing_summary',
     description: 'Get billing summary for a customer',
@@ -134,8 +134,9 @@ await env.publishTools([
       },
       required: ['total', 'invoices'],
     },
-    handler: async (customerId: string, params: any) => {
+    handler: async (customerId: string, params: any, ctx: any) => {
       // customerId comes from `this.id` in sandbox code
+      console.log('Running for subject:', ctx.user.subjectId);
       return { total: 4250.00, invoices: 3, period: params?.period || 'current' };
     },
   },
@@ -163,17 +164,19 @@ const job = await env.submitJob(`
 const result = await job.result;
 ```
 
+Effects must be declared ahead of time in the sandbox build manifest with `withEffect`. Live registration only makes already-declared effects available at runtime.
+
 ## Core Flow
 
 ```
-recordUser() → connect() → applyManifest() → recordObject() → publishTools() → submitJob()
+declare effects in build manifest → connect() → recordObject() → registerEffects() → submitJob()
 ```
 
 1. **`recordUser()`** — Register a user and their permission profiles
 2. **`connect()`** — Connect to a sandbox, returning an `Environment`
 3. **`applyManifest()`** — Define your domain ontology (classes, properties, relationships)
 4. **`recordObject()`** — Create/update instances of your classes with fields and relationships
-5. **`publishTools()`** — Publish tool schemas (with `inputSchema` + `outputSchema`) and register local handlers
+5. **`granular.registerEffects()`** — Register sandbox-scoped live handlers for effects declared in the build manifest
 6. **`submitJob()`** — Execute code in the sandbox that uses the auto-generated typed classes
 
 ## Defining the Domain Ontology
@@ -249,12 +252,12 @@ const lotr = await env.recordObject({
 
 > **Cross-class ID uniqueness**: Two objects of different classes can share the same real-world ID (e.g., an `author` "tolkien" and a `publisher` "tolkien"). The SDK derives unique graph paths internally (`author_tolkien`, `publisher_tolkien`) so they never collide.
 
-## Tool Definitions
+## Effect Definitions
 
-Tools can be **instance methods**, **static methods**, or **global functions**. Both `inputSchema` and `outputSchema` use JSON Schema:
+Effects are declared in the manifest with `withEffect`, then their live handlers are registered at sandbox scope. Effects can be **instance methods**, **static methods**, or **global functions**. Both `inputSchema` and `outputSchema` use JSON Schema:
 
 ```typescript
-await env.publishTools([
+await granular.registerEffects(env.sandboxId, [
   // Instance method: called as `tolkien.get_bio({ detailed: true })`
   // Handler receives (objectId, params)
   {
@@ -276,7 +279,7 @@ await env.publishTools([
       },
       required: ['bio'],
     },
-    handler: async (id: string, params: any) => {
+    handler: async (id: string, params: any, ctx: any) => {
       return { bio: `Biography of ${id}`, source: 'database' };
     },
   },
@@ -297,7 +300,7 @@ await env.publishTools([
       type: 'object',
       properties: { results: { type: 'array' } },
     },
-    handler: async (params: any) => {
+    handler: async (params: any, ctx: any) => {
       return { results: [`Found: ${params.query}`] };
     },
   },
@@ -316,7 +319,7 @@ await env.publishTools([
       type: 'object',
       properties: { results: { type: 'array' } },
     },
-    handler: async (params: any) => {
+    handler: async (params: any, ctx: any) => {
       return { results: [`Result for: ${params.query}`] };
     },
   },
@@ -470,8 +473,8 @@ Returns relationship definitions for a given class.
 ### `environment.listRelated(modelPath, submodelPath)`
 Lists related instances through a relationship.
 
-### `environment.publishTools(tools)`
-Publishes tool schemas (with `inputSchema` + `outputSchema`) and registers handlers locally. Tools can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
+### `granular.registerEffects(sandboxId, effects)`
+Registers sandbox-scoped live handlers for effects declared in the sandbox build manifest. Effects can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
 
 ### `environment.submitJob(code)`
 Submits code to be executed in the sandbox. The code imports typed classes from `./sandbox-tools`.
@@ -483,7 +486,7 @@ Get auto-generated TypeScript class declarations. Pass this to LLMs to help them
 Execute a GraphQL query against the environment's graph. Authenticated automatically.
 
 ### `environment.on(event, handler)`
-Listen for events: `'tool:invoke'`, `'tool:result'`, `'job:status'`, `'stdout'`, etc.
+Listen for events: `'effect:invoke'`, `'effect:result'`, `'job:status'`, `'stdout'`, etc. Legacy `'tool:*'` aliases still exist internally but are no longer the primary model.
 
 ### `Environment.toGraphPath(className, id)`
 Convert a class name + real-world ID to a unique graph path (`{className}_{id}`).

package/dist/adapters/anthropic.d.mts

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

package/dist/adapters/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-BOPsFZYi.js';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.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-BOPsFZYi.mjs';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.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-BOPsFZYi.js';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.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-BOPsFZYi.mjs';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.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-BOPsFZYi.js';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.js';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/openai.d.mts

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

package/dist/adapters/openai.d.ts

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

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) {
@@ -5552,7 +5552,105 @@ function ensureGitignore() {
     fs__namespace.writeFileSync(gitignorePath, content + section, "utf-8");
   }
 }
+function createDefaultEffectOperations(classNames) {
+  const operations = classNames.flatMap((className) => {
+    const searchName = `search_${className}s`;
+    return [
+      {
+        withEffect: {
+          name: "get_info",
+          description: `Get details of a ${className} by ID`,
+          attachedClass: className,
+          isStatic: false,
+          inputSchema: {
+            type: "object",
+            properties: {
+              include_related: { type: "boolean", description: "Include related items" }
+            }
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              name: { type: "string" },
+              related: { type: "array", items: { type: "object" } }
+            }
+          }
+        }
+      },
+      {
+        withEffect: {
+          name: searchName,
+          description: `Search ${className}s by keyword`,
+          attachedClass: className,
+          isStatic: true,
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "Search keyword" },
+              limit: { type: "number", description: "Max results" }
+            },
+            required: ["query"]
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string" },
+              results: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    name: { type: "string" }
+                  }
+                }
+              },
+              total: { type: "number" }
+            }
+          }
+        }
+      }
+    ];
+  });
+  operations.push({
+    withEffect: {
+      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"]
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          types: { type: "array", items: { type: "string" } },
+          matches: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                type: { type: "string" },
+                id: { type: "string" },
+                label: { type: "string" },
+                snippet: { type: "string" }
+              }
+            }
+          },
+          total: { type: "number" }
+        }
+      }
+    }
+  });
+  return operations;
+}
 function createDefaultManifest(name) {
+  const classNames = ["note", "tag"];
   return {
     manifest: {
       schemaVersion: 2,
@@ -5591,7 +5689,8 @@ function createDefaultManifest(name) {
               leftIsMany: true,
               rightIsMany: true
             }
-          }
+          },
+          ...createDefaultEffectOperations(classNames)
         ]
       }]
     }
@@ -5676,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");
@@ -5762,7 +5864,7 @@ var ApiClient = class {
       return await this.createPermissionProfile(sandboxId, {
         name: "default",
         rules: {
-          tools: { allow: ["*"] },
+          effects: { allow: ["*"] },
           resources: { allow: ["*"] }
         }
       });
@@ -7663,37 +7765,12 @@ async function main() {
         apiUrl: process.env.GRANULAR_API_URL ?? API_URL,
     });
 
-    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...');
+    log(\`Registering live effects for sandbox \${SANDBOX_ID}\`);
     ${mockDataBlock}
 
-    await env.publishEffects(${effectsArray});
+    await granular.registerEffects(SANDBOX_ID, ${effectsArray});
 
-    log('Effects published. Process kept alive for simulator. Press Ctrl+C to exit.');
+    log('Effects registered. Process kept alive for simulator. Press Ctrl+C to exit.');
     await new Promise(() => {});
 }
 
@@ -7773,9 +7850,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.");
@@ -7858,6 +7937,7 @@ async function initCommand(projectName, options) {
   hint("granular simulate", "opens app.granular.software/simulator for this sandbox");
   console.log();
 }
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function promptSecret(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -7883,6 +7963,9 @@ function maskApiKey(apiKey) {
   if (apiKey.length < 10) return `${apiKey}...`;
   return `${apiKey.substring(0, 10)}...`;
 }
+function isLocalApiUrl(apiUrl) {
+  return apiUrl.startsWith("ws://localhost:") || apiUrl.startsWith("wss://localhost:") || apiUrl.startsWith("ws://127.0.0.1:") || apiUrl.startsWith("wss://127.0.0.1:") || apiUrl.startsWith("http://localhost:") || apiUrl.startsWith("https://localhost:") || apiUrl.startsWith("http://127.0.0.1:") || apiUrl.startsWith("https://127.0.0.1:");
+}
 async function loginCommand(options = {}) {
   printHeader();
   const existing = loadApiKey();
@@ -7894,7 +7977,10 @@ async function loginCommand(options = {}) {
   const apiUrl = loadApiUrl();
   let apiKey = options.apiKey?.trim();
   if (!apiKey) {
-    if (options.manual) {
+    if (!options.manual && isLocalApiUrl(apiUrl)) {
+      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY;
+      info("Using local Granular API key for localhost development.");
+    } else if (options.manual) {
       dim("Get your API key at https://app.granular.software/w/default/api-keys");
       console.log();
       apiKey = await promptSecret("Enter your API key");
@@ -7934,9 +8020,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);
@@ -8448,7 +8536,7 @@ ${manifest.description}`);
   lines.push(`- [Integration Guide](#integration-guide)`);
   lines.push(`  - [1. Initialize & Connect](#1-initialize--connect)`);
   lines.push(`  - [2. Record Objects](#2-record-objects)`);
-  lines.push(`  - [3. Publish Tools](#3-publish-tools)`);
+  lines.push(`  - [3. Declare And Register Effects](#3-declare-and-register-effects)`);
   lines.push(`  - [4. Submit Jobs](#4-submit-jobs)`);
   lines.push(`
 ## Getting Started`);
@@ -8564,11 +8652,11 @@ console.log('Connected to:', env.environmentId);`);
     lines.push(`*(No classes defined in manifest)*`);
   }
   lines.push(`
-### 3. Publish Tools`);
-  lines.push(`Define tools that your agent can use properly typed.`);
+### 3. Declare And Register Effects`);
+  lines.push(`Declare effects in your manifest with \`withEffect\`, then register live handlers at sandbox scope.`);
   lines.push(`
 \`\`\`typescript`);
-  lines.push(`await env.publishTools([`);
+  lines.push(`await granular.registerEffects('your-sandbox-id', [`);
   if (classes.length > 0) {
     const cls = classes[0];
     lines.push(`  // Instance method on ${cls.name}`);
@@ -8578,8 +8666,9 @@ console.log('Connected to:', env.environmentId);`);
     lines.push(`    className: '${cls.name}',`);
     lines.push(`    inputSchema: { type: 'object', properties: { maxLength: { type: 'number' } } },`);
     lines.push(`    outputSchema: { type: 'object', properties: { summary: { type: 'string' } }, required: ['summary'] },`);
-    lines.push(`    handler: async (id, params) => {`);
+    lines.push(`    handler: async (id, params, ctx) => {`);
     lines.push(`      // 'id' is the real-world ID of the ${cls.name}`);
+    lines.push(`      console.log('Invoked for user', ctx.user.subjectId);`);
     lines.push(`      return { summary: \`Summary for \${id}\` };`);
     lines.push(`    },`);
     lines.push(`  },`);
@@ -8591,17 +8680,19 @@ console.log('Connected to:', env.environmentId);`);
     lines.push(`    static: true,`);
     lines.push(`    inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },`);
     lines.push(`    outputSchema: { type: 'object', properties: { ids: { type: 'array' } }, required: ['ids'] },`);
-    lines.push(`    handler: async (params) => {`);
+    lines.push(`    handler: async (params, ctx) => {`);
+    lines.push(`      console.log('Invoked for user', ctx.user.subjectId);`);
     lines.push(`      return { ids: [] };`);
     lines.push(`    },`);
     lines.push(`  },`);
   }
-  lines.push(`  // Global tool`);
+  lines.push(`  // Global effect`);
   lines.push(`  {`);
   lines.push(`    name: 'notify',`);
   lines.push(`    description: 'Send notification',`);
   lines.push(`    inputSchema: { type: 'object', properties: { msg: { type: 'string' } }, required: ['msg'] },`);
-  lines.push(`    handler: async (params) => {`);
+  lines.push(`    handler: async (params, ctx) => {`);
+  lines.push(`      console.log('Invoked for user', ctx.user.subjectId);`);
   lines.push(`      console.log('Notification:', params.msg);`);
   lines.push(`    },`);
   lines.push(`  },`);