@granular-software/sdk 0.2.1 → 0.3.1

package/dist/adapters/anthropic.d.mts

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

package/dist/adapters/anthropic.d.ts

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

package/dist/adapters/openai.d.mts

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

package/dist/adapters/openai.d.ts

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

package/dist/cli/index.js

@@ -7249,24 +7249,16 @@ function logEffect(name: string, className: string | null, id: string | null, pa
 }
 
 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).');
+    const auth = process.env.GRANULAR_TOKEN ?? process.env.GRANULAR_API_KEY;
+    if (!auth) {
+        console.error('[Effects] Set GRANULAR_API_KEY or GRANULAR_TOKEN (e.g. from simulator "Copy CLI env").');
         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 }),
+        ...(auth.startsWith('eyJ') ? { token: auth } : { apiKey: auth }),
+        apiUrl: process.env.GRANULAR_API_URL ?? API_URL,
     });
 
     const userId = 'effects_user';
@@ -8049,7 +8041,7 @@ ${manifest.description}`);
   lines.push(`import { Granular } from '@granular-software/sdk';`);
   lines.push(`
 const granular = new Granular({`);
-  lines.push(`  apiKey: process.env.GRANULAR_API_KEY!,`);
+  lines.push(`  ...(process.env.GRANULAR_TOKEN ? { token: process.env.GRANULAR_TOKEN } : { apiKey: process.env.GRANULAR_API_KEY! }),`);
   lines.push(`});`);
   lines.push(`
 // 1. Record the user (creates or updates identity)`);

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as Automerge from '@automerge/automerge';
-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 { 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-CnX4jXYQ.mjs';
+export { a2 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.mjs';
 import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -107,6 +107,10 @@ declare class Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        graphContainerStatus?: {
+            lastKeepAliveAt: number;
+            status: 'warming' | 'hot' | 'unknown';
+        };
     }>;
     /**
      * Publish tools to the sandbox and register handlers for reverse-RPC.
@@ -245,21 +249,19 @@ declare class Session {
      */
     getDomain(): Promise<DomainState>;
     /**
-     * Get auto-generated TypeScript class declarations for the current domain.
-     *
-     * Returns typed declarations including:
-     * - Classes with readonly properties (from manifest)
-     * - `static find(query: { id: string })` for each class
-     * - Instance methods with typed input/output (from `publishTools` with `className`)
-     * - Static methods (from `publishTools` with `className` + `static: true`)
-     * - Relationship accessors (`get_books()`, `get_author()`, etc.)
-     * - Global tool functions (from `publishTools` without `className`)
-     *
-     * Pass this documentation to LLMs so they can write correct typed code
-     * that imports from `./sandbox-tools`.
-     *
-     * Falls back to generating markdown docs from the domain summary if
-     * the synthesis server is unavailable.
+     * Fetch a domain package part from the backend (no fallback).
+     */
+    private fetchDomainPart;
+    /**
+     * Get TypeScript class declarations for the current domain (for LLM/code gen).
+     */
+    getDomainTypes(): Promise<string>;
+    /**
+     * Get Markdown documentation for the current domain (human-readable).
+     */
+    getDomainDocs(): Promise<string>;
+    /**
+     * Get domain documentation for LLMs. Returns types (preferred) or fallback.
      */
     getDomainDocumentation(): Promise<string>;
     /**
@@ -281,7 +283,7 @@ declare class Session {
     off(event: string, handler: (data: unknown) => void): void;
     private setupToolInvokeHandler;
     private setupEventHandlers;
-    private emit;
+    protected emit(event: string, data: unknown): void;
     /**
      * Check for changes in the tool catalog and emit 'tools:changed' if needed
      */
@@ -320,6 +322,39 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    graphContainerStatus: {
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    } | null;
+    /**
+     * Check if the graph container is ready and warm.
+     *
+     * Sends a lightweight heartbeat RPC to the Session DO which internally
+     * pings the FalkorDB container. The response includes `graphContainerStatus`,
+     * which is stored locally and emitted as a `readiness` event.
+     *
+     * Use this method to proactively warm the graph container before any
+     * GraphQL query that requires it, or to poll the container's state in
+     * the background.
+     *
+     * @returns The current graph container status object
+     *
+     * @example
+     * ```typescript
+     * const status = await env.checkReadiness();
+     * console.log(status.status); // 'hot' | 'warming' | 'unknown'
+     *
+     * // Or listen for live updates
+     * env.on('readiness', (status) => {
+     *   console.log('Graph is now:', status.status);
+     * });
+     * ```
+     */
+    checkReadiness(): Promise<{
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    }>;
     /**
      * Convert a class name + real-world ID into a unique graph path.
      *

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as Automerge from '@automerge/automerge';
-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 { 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-CnX4jXYQ.js';
+export { a2 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.js';
 import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -107,6 +107,10 @@ declare class Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        graphContainerStatus?: {
+            lastKeepAliveAt: number;
+            status: 'warming' | 'hot' | 'unknown';
+        };
     }>;
     /**
      * Publish tools to the sandbox and register handlers for reverse-RPC.
@@ -245,21 +249,19 @@ declare class Session {
      */
     getDomain(): Promise<DomainState>;
     /**
-     * Get auto-generated TypeScript class declarations for the current domain.
-     *
-     * Returns typed declarations including:
-     * - Classes with readonly properties (from manifest)
-     * - `static find(query: { id: string })` for each class
-     * - Instance methods with typed input/output (from `publishTools` with `className`)
-     * - Static methods (from `publishTools` with `className` + `static: true`)
-     * - Relationship accessors (`get_books()`, `get_author()`, etc.)
-     * - Global tool functions (from `publishTools` without `className`)
-     *
-     * Pass this documentation to LLMs so they can write correct typed code
-     * that imports from `./sandbox-tools`.
-     *
-     * Falls back to generating markdown docs from the domain summary if
-     * the synthesis server is unavailable.
+     * Fetch a domain package part from the backend (no fallback).
+     */
+    private fetchDomainPart;
+    /**
+     * Get TypeScript class declarations for the current domain (for LLM/code gen).
+     */
+    getDomainTypes(): Promise<string>;
+    /**
+     * Get Markdown documentation for the current domain (human-readable).
+     */
+    getDomainDocs(): Promise<string>;
+    /**
+     * Get domain documentation for LLMs. Returns types (preferred) or fallback.
      */
     getDomainDocumentation(): Promise<string>;
     /**
@@ -281,7 +283,7 @@ declare class Session {
     off(event: string, handler: (data: unknown) => void): void;
     private setupToolInvokeHandler;
     private setupEventHandlers;
-    private emit;
+    protected emit(event: string, data: unknown): void;
     /**
      * Check for changes in the tool catalog and emit 'tools:changed' if needed
      */
@@ -320,6 +322,39 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    graphContainerStatus: {
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    } | null;
+    /**
+     * Check if the graph container is ready and warm.
+     *
+     * Sends a lightweight heartbeat RPC to the Session DO which internally
+     * pings the FalkorDB container. The response includes `graphContainerStatus`,
+     * which is stored locally and emitted as a `readiness` event.
+     *
+     * Use this method to proactively warm the graph container before any
+     * GraphQL query that requires it, or to poll the container's state in
+     * the background.
+     *
+     * @returns The current graph container status object
+     *
+     * @example
+     * ```typescript
+     * const status = await env.checkReadiness();
+     * console.log(status.status); // 'hot' | 'warming' | 'unknown'
+     *
+     * // Or listen for live updates
+     * env.on('readiness', (status) => {
+     *   console.log('Graph is now:', status.status);
+     * });
+     * ```
+     */
+    checkReadiness(): Promise<{
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    }>;
     /**
      * Convert a class name + real-world ID into a unique graph path.
      *