@granular-software/sdk 0.3.4 → 0.4.2

package/README.md

@@ -27,6 +27,26 @@ bun add @granular-software/sdk
 npm install @granular-software/sdk
 ```
 
+## Endpoint Modes
+
+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`
+
+Overrides:
+
+- SDK option: `endpointMode: 'local' | 'production'`
+- SDK option: `apiUrl: 'ws://... | wss://...'` (highest priority)
+- Env: `GRANULAR_ENDPOINT_MODE=local|production`
+- Env: `GRANULAR_API_URL=...` (highest priority)
+
+CLI overrides:
+
+- `granular --local <command>`
+- `granular --prod <command>`
+- `granular --env local|production <command>`
+
 ## Quick Start
 
 ```typescript
@@ -92,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',
@@ -114,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' };
     },
   },
@@ -143,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
@@ -229,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)
   {
@@ -256,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' };
     },
   },
@@ -277,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}`] };
     },
   },
@@ -296,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}`] };
     },
   },
@@ -450,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`.
@@ -463,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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.js';
+import { T as ToolWithHandler } from '../types-C0AVRsVR.js';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/cli/index.js

@@ -5384,6 +5384,57 @@ var {
 
 // src/cli/config.ts
 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 LOCAL_AUTH_URL = "http://localhost:3000";
+var PRODUCTION_AUTH_URL = "https://app.granular.software";
+function readEnv(name) {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[name];
+}
+function normalizeMode(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "local") return "local";
+  if (normalized === "prod" || normalized === "production") return "production";
+  if (normalized === "auto") return "auto";
+  return void 0;
+}
+function isTruthy(value) {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function resolveEndpointMode(explicitMode) {
+  const explicit = normalizeMode(explicitMode);
+  if (explicit === "local" || explicit === "production") {
+    return explicit;
+  }
+  const envMode = normalizeMode(readEnv("GRANULAR_ENDPOINT_MODE") || readEnv("GRANULAR_ENV"));
+  if (envMode === "local" || envMode === "production") {
+    return envMode;
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_LOCAL_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_LOCAL"))) {
+    return "local";
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_PRODUCTION_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_PROD"))) {
+    return "production";
+  }
+  return readEnv("NODE_ENV") === "development" ? "local" : "production";
+}
+function resolveApiUrl(explicitApiUrl, mode) {
+  return resolveEndpointMode(mode) === "local" ? LOCAL_API_URL : PRODUCTION_API_URL;
+}
+function resolveAuthUrl(explicitAuthUrl, mode) {
+  if (explicitAuthUrl) {
+    return explicitAuthUrl;
+  }
+  return resolveEndpointMode(mode) === "local" ? LOCAL_AUTH_URL : PRODUCTION_AUTH_URL;
+}
+
+// src/cli/config.ts
 var MANIFEST_FILE = "granular.json";
 var RC_FILE = ".granularrc";
 var ENV_LOCAL_FILE = ".env.local";
@@ -5453,16 +5504,17 @@ function loadApiKey() {
   return void 0;
 }
 function loadApiUrl() {
+  if (process.env.GRANULAR_API_URL) return process.env.GRANULAR_API_URL;
+  const modeOverride = process.env.GRANULAR_ENDPOINT_MODE;
+  if (modeOverride === "local" || modeOverride === "production" || modeOverride === "prod") {
+    return resolveApiUrl(void 0, modeOverride === "prod" ? "production" : modeOverride);
+  }
   const rc = readRcFile();
   if (rc.apiUrl) return rc.apiUrl;
-  if (process.env.GRANULAR_API_URL) return process.env.GRANULAR_API_URL;
-  return "https://cf-api-gateway.arthur6084.workers.dev/granular";
+  return resolveApiUrl();
 }
 function loadAuthUrl() {
-  if (process.env.GRANULAR_AUTH_URL) {
-    return process.env.GRANULAR_AUTH_URL;
-  }
-  return "https://app.granular.software";
+  return resolveAuthUrl(process.env.GRANULAR_AUTH_URL);
 }
 function saveApiKey(apiKey) {
   const envLocalPath = getEnvLocalPath();
@@ -5500,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,
@@ -5539,7 +5689,8 @@ function createDefaultManifest(name) {
               leftIsMany: true,
               rightIsMany: true
             }
-          }
+          },
+          ...createDefaultEffectOperations(classNames)
         ]
       }]
     }
@@ -5710,7 +5861,7 @@ var ApiClient = class {
       return await this.createPermissionProfile(sandboxId, {
         name: "default",
         rules: {
-          tools: { allow: ["*"] },
+          effects: { allow: ["*"] },
           resources: { allow: ["*"] }
         }
       });
@@ -7611,37 +7762,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(() => {});
 }
 
@@ -7806,6 +7932,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) => {
@@ -7831,6 +7958,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();
@@ -7842,7 +7972,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");
@@ -8396,7 +8529,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`);
@@ -8512,11 +8645,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}`);
@@ -8526,8 +8659,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(`  },`);
@@ -8539,17 +8673,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(`  },`);
@@ -8623,6 +8759,28 @@ async function simulateCommand(sandboxIdArg) {
 var VERSION = "0.2.0";
 var program2 = new Command();
 program2.name("granular").description("Build and deploy AI sandboxes from code").version(VERSION, "-v, --version");
+program2.option("--local", "Use local endpoints (localhost)").option("--prod", "Use production endpoints").option("--env <target>", "Endpoint target: local|production");
+program2.hook("preAction", () => {
+  const opts = program2.opts();
+  const normalizedEnv = opts.env?.trim().toLowerCase();
+  if (opts.local && opts.prod) {
+    error("Cannot use --local and --prod at the same time.");
+    process.exit(1);
+  }
+  if (normalizedEnv && !["local", "production", "prod"].includes(normalizedEnv)) {
+    error('Invalid --env value. Use "local" or "production".');
+    process.exit(1);
+  }
+  let mode;
+  if (opts.local || normalizedEnv === "local") {
+    mode = "local";
+  } else if (opts.prod || normalizedEnv === "production" || normalizedEnv === "prod") {
+    mode = "production";
+  }
+  if (mode) {
+    process.env.GRANULAR_ENDPOINT_MODE = mode;
+  }
+});
 program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").action(async (projectName, opts) => {
   try {
     await initCommand(projectName, { skipBuild: opts.skipBuild });