@granular-software/sdk 0.1.0

package/README.md

@@ -0,0 +1,476 @@
+# @granular-software/sdk
+
+The official TypeScript SDK for Granular.
+
+**Build AI-powered domain models with secure, isolated execution.** Granular lets you define ontologies (classes, relationships), attach tools to them, and run AI-generated code that operates on typed domain objects — all in a sandboxed environment with per-user permissions.
+
+## Features
+
+- 🏗️ **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
+- 🔒 **Secure Execution** — Run AI-generated code in isolated sandboxes
+- 👥 **User Permissions** — Control what each user can access
+- 🔌 **Framework Adapters** — Helpers for OpenAI, LangChain, Anthropic, Mastra
+- ⚡ **Real-time** — WebSocket-based streaming and events
+- ↩️ **Reverse RPC** — Sandbox code calls tools that execute on your server
+
+## Documentation
+
+Full documentation: [docs.granular.dev](https://docs.granular.dev)
+
+## Installation
+
+```bash
+bun add @granular-software/sdk
+# or
+npm install @granular-software/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Granular, type ManifestContent } from '@granular-software/sdk';
+
+const granular = new Granular({ apiKey: process.env.GRANULAR_API_KEY });
+
+// 1. Record user with permissions
+const user = await granular.recordUser({
+  userId: 'user_123',
+  permissions: ['agent'],
+});
+
+// 2. Connect to sandbox
+const env = await granular.connect({ sandbox: 'my-sandbox', user });
+
+// 3. Define your domain ontology
+const manifest: ManifestContent = {
+  schemaVersion: 2,
+  name: 'my-app',
+  volumes: [{
+    name: 'schema',
+    scope: 'sandbox',
+    imports: [{ alias: '@std', name: 'standard_modules', label: 'prod' }],
+    operations: [
+      // Define classes with typed properties
+      {
+        create: 'customer',
+        extends: '@std/class',
+        has: {
+          name:  { type: 'string', description: 'Customer name' },
+          email: { type: 'string', description: 'Email address' },
+          tier:  { type: 'string', description: 'Subscription tier' },
+        },
+      },
+      {
+        create: 'order',
+        extends: '@std/class',
+        has: {
+          total:  { type: 'number', description: 'Order total' },
+          status: { type: 'string', description: 'Order status' },
+        },
+      },
+      // Define relationships
+      {
+        defineRelationship: {
+          left: 'customer', right: 'order',
+          leftSubmodel: 'orders', rightSubmodel: 'customer',
+          leftIsMany: true, rightIsMany: false,
+        },
+      },
+    ],
+  }],
+};
+
+await env.applyManifest(manifest);
+
+// 4. Record object instances
+await env.recordObject({
+  className: 'customer',
+  id: 'cust_42',
+  label: 'Acme Corp',
+  fields: { name: 'Acme Corp', email: 'billing@acme.com', tier: 'enterprise' },
+});
+
+// 5. Publish tools with typed input AND output schemas
+await env.publishTools([
+  {
+    name: 'get_billing_summary',
+    description: 'Get billing summary for a customer',
+    className: 'customer',           // Attached to Customer class
+    // static omitted → instance method (receives object ID automatically)
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period: { type: 'string', description: 'Billing period (e.g. "2024-Q1")' },
+      },
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        total:    { type: 'number', description: 'Total billed amount' },
+        invoices: { type: 'number', description: 'Number of invoices' },
+        period:   { type: 'string', description: 'The billing period' },
+      },
+      required: ['total', 'invoices'],
+    },
+    handler: async (customerId: string, params: any) => {
+      // customerId comes from `this.id` in sandbox code
+      return { total: 4250.00, invoices: 3, period: params?.period || 'current' };
+    },
+  },
+]);
+
+// 6. Submit a job — the sandbox gets fully typed OOP classes!
+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' });
+  console.log(acme.name);   // "Acme Corp"
+  console.log(acme.email);  // "billing@acme.com"
+
+  // Instance method — typed input AND output
+  const billing = await acme.get_billing_summary({ period: '2024-Q1' });
+  // billing.total, billing.invoices, billing.period are all typed
+
+  // Navigate relationships
+  const orders = await acme.get_orders();
+
+  return { customer: acme.name, billing, orderCount: orders.length };
+`);
+
+const result = await job.result;
+```
+
+## Core Flow
+
+```
+recordUser() → connect() → applyManifest() → recordObject() → publishTools() → 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
+6. **`submitJob()`** — Execute code in the sandbox that uses the auto-generated typed classes
+
+## Defining the Domain Ontology
+
+Use `applyManifest()` to declare classes, typed properties, and relationships:
+
+```typescript
+const manifest: ManifestContent = {
+  schemaVersion: 2,
+  name: 'library-app',
+  volumes: [{
+    name: 'schema',
+    scope: 'sandbox',
+    imports: [{ alias: '@std', name: 'standard_modules', label: 'prod' }],
+    operations: [
+      // Classes with typed properties
+      {
+        create: 'author',
+        extends: '@std/class',
+        has: {
+          name:       { type: 'string',  description: 'Author full name' },
+          birth_year: { type: 'number',  description: 'Year of birth' },
+        },
+      },
+      {
+        create: 'book',
+        extends: '@std/class',
+        has: {
+          title:          { type: 'string', description: 'Book title' },
+          isbn:           { type: 'string', description: 'ISBN number' },
+          published_year: { type: 'number', description: 'Year published' },
+        },
+      },
+
+      // Relationships (bidirectional, with cardinality)
+      {
+        defineRelationship: {
+          left: 'author',  right: 'book',
+          leftSubmodel: 'books',  rightSubmodel: 'author',
+          leftIsMany: true,       rightIsMany: false,
+          // → author.books (one-to-many), book.author (many-to-one)
+        },
+      },
+    ],
+  }],
+};
+
+await env.applyManifest(manifest);
+```
+
+## Recording Object Instances
+
+After defining the ontology, populate it with data:
+
+```typescript
+const tolkien = await env.recordObject({
+  className: 'author',
+  id: 'tolkien',               // Real-world ID (unique per class)
+  label: 'J.R.R. Tolkien',
+  fields: { name: 'J.R.R. Tolkien', birth_year: 1892 },
+});
+// tolkien.path → 'author_tolkien' (internal graph path, unique globally)
+// tolkien.id   → 'tolkien'        (real-world ID)
+
+const lotr = await env.recordObject({
+  className: 'book',
+  id: 'lotr',
+  label: 'The Lord of the Rings',
+  fields: { title: 'The Lord of the Rings', isbn: '978-0-618-64015-7', published_year: 1954 },
+  relationships: { author: 'tolkien' },  // Real-world ID — SDK resolves it automatically
+});
+```
+
+> **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
+
+Tools can be **instance methods**, **static methods**, or **global functions**. Both `inputSchema` and `outputSchema` use JSON Schema:
+
+```typescript
+await env.publishTools([
+  // Instance method: called as `tolkien.get_bio({ detailed: true })`
+  // Handler receives (objectId, params)
+  {
+    name: 'get_bio',
+    description: 'Get biography of an author',
+    className: 'author',              // Attached to Author class
+    // static: false (default)        // Instance method
+    inputSchema: {
+      type: 'object',
+      properties: {
+        detailed: { type: 'boolean', description: 'Include full details' },
+      },
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        bio:    { type: 'string',  description: 'The biography text' },
+        source: { type: 'string',  description: 'Source of the bio' },
+      },
+      required: ['bio'],
+    },
+    handler: async (id: string, params: any) => {
+      return { bio: `Biography of ${id}`, source: 'database' };
+    },
+  },
+
+  // Static method: called as `Author.search({ query: 'tolkien' })`
+  // Handler receives (params) — no object ID
+  {
+    name: 'search',
+    description: 'Search for authors',
+    className: 'author',
+    static: true,
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    },
+    outputSchema: {
+      type: 'object',
+      properties: { results: { type: 'array' } },
+    },
+    handler: async (params: any) => {
+      return { results: [`Found: ${params.query}`] };
+    },
+  },
+
+  // Global tool: called as `global_search({ query: 'rings' })`
+  // No className → standalone exported function
+  {
+    name: 'global_search',
+    description: 'Search across everything',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    },
+    outputSchema: {
+      type: 'object',
+      properties: { results: { type: 'array' } },
+    },
+    handler: async (params: any) => {
+      return { results: [`Result for: ${params.query}`] };
+    },
+  },
+]);
+```
+
+## Domain Synthesis (Auto-Generated Types)
+
+After applying the manifest and publishing tools, the sandbox gets **auto-generated TypeScript classes** in `./sandbox-tools`:
+
+```typescript
+// What the sandbox sees (auto-generated):
+export declare class Author {
+  readonly id: string;
+  readonly name: string;
+  readonly birth_year: number;
+
+  constructor(id: string, fields?: Record<string, any>);
+
+  /** Find an Author by ID */
+  static find(query: { id: string }): Promise<Author | null>;
+
+  /** Get biography of an author */
+  get_bio(input?: { detailed?: boolean }): Promise<{ bio: string; source?: string }>;
+
+  /** Search for authors (static) */
+  static search(input: { query: string }): Promise<{ results?: any[] }>;
+
+  /** Navigate to books (one_to_many) */
+  get_books(): Promise<Book[]>;
+}
+
+export declare class Book {
+  readonly id: string;
+  readonly title: string;
+  readonly isbn: string;
+  readonly published_year: number;
+
+  static find(query: { id: string }): Promise<Book | null>;
+
+  /** Navigate to author (many_to_one) */
+  get_author(): Promise<Author | null>;
+}
+
+/** Search across everything */
+export declare function global_search(input: { query: string }): Promise<{ results?: any[] }>;
+```
+
+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' });
+console.log(tolkien.name);              // "J.R.R. Tolkien"
+
+const bio = await tolkien.get_bio({ detailed: true });
+console.log(bio.bio);                   // typed as string
+
+const books = await tolkien.get_books();
+for (const book of books) {
+  console.log(book.title, book.isbn);   // typed properties
+}
+
+const results = await Author.search({ query: 'tolkien' });
+const globalResults = await global_search({ query: 'rings' });
+```
+
+## GraphQL API
+
+Every environment has a built-in GraphQL API for direct graph queries:
+
+```typescript
+// Authenticated automatically with your API key
+const result = await env.graphql(
+  `query { model(path: "author") { path label submodels { path label } } }`
+);
+
+// The endpoint is also available as a URL
+console.log(env.apiEndpoint);
+```
+
+## Framework Adapters
+
+Adapters provide two modes of integration:
+
+### Option A: Codegen Tool (Recommended)
+
+Pass a **single tool** to the LLM that executes code in the sandbox. The LLM receives the typed class documentation and writes code against it:
+
+```typescript
+import { createCodegenTool, executeCodegenToolCall } from '@granular-software/sdk/openai';
+
+// Get auto-generated TypeScript class declarations
+const docs = await environment.getDomainDocumentation();
+
+// Create a single "codegen" tool for the LLM
+const codegenTool = createCodegenTool(docs);
+
+// Pass to OpenAI — the LLM writes typed code using Author, Book, etc.
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [...],
+  tools: [codegenTool],
+});
+
+// Execute the code the LLM generates
+const result = await executeCodegenToolCall(toolCall, environment);
+```
+
+### Option B: Schema Conversion (Legacy)
+
+Convert tool schemas for compatibility:
+
+```typescript
+import { toOpenAITools } from '@granular-software/sdk/openai';
+import { toAnthropicTools } from '@granular-software/sdk/anthropic';
+import { fromLangChainTools } from '@granular-software/sdk/langchain';
+
+const openaiTools = toOpenAITools(myGranularTools);
+```
+
+## Examples
+
+See [examples/](./examples/) for runnable code:
+
+- **[basic.ts](./examples/basic.ts)** — Ontology + class-based tools + domain synthesis + job execution
+- **[management.ts](./examples/management.ts)** — Sandbox, permission profiles, and user management
+- **[adapter-openai.ts](./examples/adapter-openai.ts)** — OpenAI integration with codegen tool
+- **[adapter-anthropic.ts](./examples/adapter-anthropic.ts)** — Anthropic/Claude integration
+- **[adapter-langchain.ts](./examples/adapter-langchain.ts)** — LangChain integration
+- **[interactive.ts](./examples/interactive.ts)** — Human-in-the-loop prompts
+
+## API Reference
+
+### `granular.recordUser(options)`
+Registers a user identity and their assigned permission profiles.
+
+### `granular.connect(options)`
+Connects to a sandbox session for the specified user.
+
+### `environment.applyManifest(manifest)`
+Defines domain ontology: classes (with typed properties), and relationships (with cardinality).
+
+### `environment.recordObject(options)`
+Creates or updates a class instance with fields and relationships. Returns `{ path, id, created }`.
+
+### `environment.getRelationships(modelPath)`
+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`).
+
+### `environment.submitJob(code)`
+Submits code to be executed in the sandbox. The code imports typed classes from `./sandbox-tools`.
+
+### `environment.getDomainDocumentation()`
+Get auto-generated TypeScript class declarations. Pass this to LLMs to help them write correct code.
+
+### `environment.graphql(query, variables?)`
+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.
+
+### `Environment.toGraphPath(className, id)`
+Convert a class name + real-world ID to a unique graph path (`{className}_{id}`).
+
+### `Environment.extractIdFromGraphPath(graphPath, className)`
+Extract the real-world ID from a graph path by stripping the class prefix.
+
+## License
+
+MIT

package/dist/adapters/anthropic.d.mts

@@ -0,0 +1,64 @@
+import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+
+/**
+ * Anthropic tool_use block from message response
+ */
+interface AnthropicToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+}
+/**
+ * Anthropic tool definition
+ */
+interface AnthropicToolDefinition {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/**
+ * Helper to convert Granular tools to Anthropic tool definitions
+ *
+ * @param tools - Array of Granular tools
+ * @returns Array of Anthropic tool definitions
+ */
+declare function toAnthropicTools(tools: ToolWithHandler[]): AnthropicToolDefinition[];
+/**
+ * Helper to convert Anthropic tool calls to job code for Granular
+ *
+ * @param contentBlocks - Array of content blocks from Anthropic response
+ * @param customImports - Optional imports to add to top of job
+ * @returns generated job code, or null if no tool uses found
+ */
+declare function toolUsesToJobCode(contentBlocks: Array<{
+    type: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+}>, customImports?: string): string | null;
+/**
+ * Create a single "codegen tool" for LLM consumption.
+ *
+ * Instead of passing N individual tools to the LLM, this returns a single
+ * tool that accepts TypeScript code. The LLM writes code that uses the
+ * available tools, and the code is executed in the sandbox.
+ *
+ * @param domainDocumentation - Documentation of available tools (from environment.getDomainDocumentation())
+ * @returns A single Anthropic tool definition
+ */
+declare function createCodegenTool(domainDocumentation: string): AnthropicToolDefinition;
+/**
+ * Helper to execute a codegen tool use block.
+ *
+ * @param toolUse - The tool_use block from the Anthropic response
+ * @param environment - The connected Granular environment
+ * @returns The job result
+ */
+declare function executeCodegenToolUse(toolUse: AnthropicToolUseBlock, environment: {
+    submitJob: (code: string) => Promise<{
+        result: Promise<unknown>;
+    }>;
+}): Promise<unknown>;
+
+export { type AnthropicToolDefinition, type AnthropicToolUseBlock, createCodegenTool, executeCodegenToolUse, toAnthropicTools, toolUsesToJobCode };

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,64 @@
+import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+
+/**
+ * Anthropic tool_use block from message response
+ */
+interface AnthropicToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+}
+/**
+ * Anthropic tool definition
+ */
+interface AnthropicToolDefinition {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/**
+ * Helper to convert Granular tools to Anthropic tool definitions
+ *
+ * @param tools - Array of Granular tools
+ * @returns Array of Anthropic tool definitions
+ */
+declare function toAnthropicTools(tools: ToolWithHandler[]): AnthropicToolDefinition[];
+/**
+ * Helper to convert Anthropic tool calls to job code for Granular
+ *
+ * @param contentBlocks - Array of content blocks from Anthropic response
+ * @param customImports - Optional imports to add to top of job
+ * @returns generated job code, or null if no tool uses found
+ */
+declare function toolUsesToJobCode(contentBlocks: Array<{
+    type: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+}>, customImports?: string): string | null;
+/**
+ * Create a single "codegen tool" for LLM consumption.
+ *
+ * Instead of passing N individual tools to the LLM, this returns a single
+ * tool that accepts TypeScript code. The LLM writes code that uses the
+ * available tools, and the code is executed in the sandbox.
+ *
+ * @param domainDocumentation - Documentation of available tools (from environment.getDomainDocumentation())
+ * @returns A single Anthropic tool definition
+ */
+declare function createCodegenTool(domainDocumentation: string): AnthropicToolDefinition;
+/**
+ * Helper to execute a codegen tool use block.
+ *
+ * @param toolUse - The tool_use block from the Anthropic response
+ * @param environment - The connected Granular environment
+ * @returns The job result
+ */
+declare function executeCodegenToolUse(toolUse: AnthropicToolUseBlock, environment: {
+    submitJob: (code: string) => Promise<{
+        result: Promise<unknown>;
+    }>;
+}): Promise<unknown>;
+
+export { type AnthropicToolDefinition, type AnthropicToolUseBlock, createCodegenTool, executeCodegenToolUse, toAnthropicTools, toolUsesToJobCode };

package/dist/adapters/anthropic.js

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/adapters/anthropic.ts
+function toAnthropicTools(tools) {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema
+  }));
+}
+function toolUsesToJobCode(contentBlocks, customImports = "") {
+  const toolUses = contentBlocks.filter((b) => b.type === "tool_use");
+  if (toolUses.length === 0) {
+    return null;
+  }
+  let code = `
+        import { tools } from './sandbox-tools';
+        ${customImports}
+        const results = [];
+    `;
+  toolUses.forEach((use) => {
+    code += `
+        try {
+            const result_${use.id.replace(/-/g, "_")} = await tools.${use.name}(${JSON.stringify(use.input)});
+            results.push({ 
+                type: 'tool_result',
+                tool_use_id: "${use.id}", 
+                content: result_${use.id.replace(/-/g, "_")} 
+            });
+        } catch (error) {
+           results.push({ 
+                type: 'tool_result',
+                tool_use_id: "${use.id}", 
+                content: String(error),
+                is_error: true
+            });
+        }
+        `;
+  });
+  code += `return results;`;
+  return code;
+}
+function createCodegenTool(domainDocumentation) {
+  return {
+    name: "execute_sandbox_code",
+    description: `Execute TypeScript code in a secure sandbox environment. The code can use the following tools by importing from "./sandbox-tools":
+
+${domainDocumentation}
+
+Write complete, executable TypeScript code. Use async/await for tool calls. Return results at the end.`,
+    input_schema: {
+      type: "object",
+      properties: {
+        code: {
+          type: "string",
+          description: 'TypeScript code to execute. Must import tools from "./sandbox-tools" and use await for all tool calls.'
+        }
+      },
+      required: ["code"]
+    }
+  };
+}
+async function executeCodegenToolUse(toolUse, environment) {
+  if (toolUse.name !== "execute_sandbox_code") {
+    throw new Error(`Unknown tool: ${toolUse.name}`);
+  }
+  const input = toolUse.input;
+  const job = await environment.submitJob(input.code);
+  return job.result;
+}
+
+exports.createCodegenTool = createCodegenTool;
+exports.executeCodegenToolUse = executeCodegenToolUse;
+exports.toAnthropicTools = toAnthropicTools;
+exports.toolUsesToJobCode = toolUsesToJobCode;
+//# sourceMappingURL=anthropic.js.map
+//# sourceMappingURL=anthropic.js.map

package/dist/adapters/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":";;;AA2BO,SAAS,iBAAiB,KAAA,EAAqD;AAClF,EAAA,OAAO,KAAA,CAAM,IAAI,CAAA,IAAA,MAAS;AAAA,IACtB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,aAAa,IAAA,CAAK,WAAA;AAAA,IAClB,cAAc,IAAA,CAAK;AAAA,GACvB,CAAE,CAAA;AACN;AASO,SAAS,iBAAA,CAAkB,aAAA,EAAqF,aAAA,GAAgB,EAAA,EAAmB;AACtJ,EAAA,MAAM,WAAW,aAAA,CAAc,MAAA,CAAO,CAAA,CAAA,KAAK,CAAA,CAAE,SAAS,UAAU,CAAA;AAEhE,EAAA,IAAI,QAAA,CAAS,WAAW,CAAA,EAAG;AACvB,IAAA,OAAO,IAAA;AAAA,EACX;AAEA,EAAA,IAAI,IAAA,GAAO;AAAA;AAAA,QAAA,EAEL,aAAa;AAAA;AAAA,IAAA,CAAA;AAInB,EAAA,QAAA,CAAS,OAAA,CAAQ,CAAC,GAAA,KAAQ;AACtB,IAAA,IAAA,IAAQ;AAAA;AAAA,yBAAA,EAEW,GAAA,CAAI,EAAA,CAAG,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAC,CAAA,eAAA,EAAkB,GAAA,CAAI,IAAI,CAAA,CAAA,EAAI,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,KAAK,CAAC,CAAA;AAAA;AAAA;AAAA,8BAAA,EAG3E,IAAI,EAAE,CAAA;AAAA,gCAAA,EACJ,GAAA,CAAI,EAAA,CAAG,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAC,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8BAAA,EAK3B,IAAI,EAAE,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAAA,CAAA;AAAA,EAMlC,CAAC,CAAA;AAED,EAAA,IAAA,IAAQ,CAAA,eAAA,CAAA;AACR,EAAA,OAAO,IAAA;AACX;AAYO,SAAS,kBAAkB,mBAAA,EAAsD;AACpF,EAAA,OAAO;AAAA,IACH,IAAA,EAAM,sBAAA;AAAA,IACN,WAAA,EAAa,CAAA;;AAAA,EAEnB,mBAAmB;;AAAA,sGAAA,CAAA;AAAA,IAGb,YAAA,EAAc;AAAA,MACV,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACR,IAAA,EAAM;AAAA,UACF,IAAA,EAAM,QAAA;AAAA,UACN,WAAA,EAAa;AAAA;AACjB,OACJ;AAAA,MACA,QAAA,EAAU,CAAC,MAAM;AAAA;AACrB,GACJ;AACJ;AASA,eAAsB,qBAAA,CAClB,SACA,WAAA,EACgB;AAChB,EAAA,IAAI,OAAA,CAAQ,SAAS,sBAAA,EAAwB;AACzC,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,cAAA,EAAiB,OAAA,CAAQ,IAAI,CAAA,CAAE,CAAA;AAAA,EACnD;AAEA,EAAA,MAAM,QAAQ,OAAA,CAAQ,KAAA;AACtB,EAAA,MAAM,GAAA,GAAM,MAAM,WAAA,CAAY,SAAA,CAAU,MAAM,IAAI,CAAA;AAClD,EAAA,OAAO,GAAA,CAAI,MAAA;AACf","file":"anthropic.js","sourcesContent":["import type { ToolWithHandler } from '../types';\n\n/**\n * Anthropic tool_use block from message response\n */\nexport interface AnthropicToolUseBlock {\n    type: 'tool_use';\n    id: string;\n    name: string;\n    input: unknown;\n}\n\n/**\n * Anthropic tool definition\n */\nexport interface AnthropicToolDefinition {\n    name: string;\n    description?: string;\n    input_schema: Record<string, unknown>;\n}\n\n/**\n * Helper to convert Granular tools to Anthropic tool definitions\n * \n * @param tools - Array of Granular tools\n * @returns Array of Anthropic tool definitions\n */\nexport function toAnthropicTools(tools: ToolWithHandler[]): AnthropicToolDefinition[] {\n    return tools.map(tool => ({\n        name: tool.name,\n        description: tool.description,\n        input_schema: tool.inputSchema,\n    }));\n}\n\n/**\n * Helper to convert Anthropic tool calls to job code for Granular\n * \n * @param contentBlocks - Array of content blocks from Anthropic response\n * @param customImports - Optional imports to add to top of job\n * @returns generated job code, or null if no tool uses found\n */\nexport function toolUsesToJobCode(contentBlocks: Array<{ type: string; id?: string; name?: string; input?: unknown }>, customImports = ''): string | null {\n    const toolUses = contentBlocks.filter(b => b.type === 'tool_use') as AnthropicToolUseBlock[];\n\n    if (toolUses.length === 0) {\n        return null;\n    }\n\n    let code = `\n        import { tools } from './sandbox-tools';\n        ${customImports}\n        const results = [];\n    `;\n\n    toolUses.forEach((use) => {\n        code += `\n        try {\n            const result_${use.id.replace(/-/g, '_')} = await tools.${use.name}(${JSON.stringify(use.input)});\n            results.push({ \n                type: 'tool_result',\n                tool_use_id: \"${use.id}\", \n                content: result_${use.id.replace(/-/g, '_')} \n            });\n        } catch (error) {\n           results.push({ \n                type: 'tool_result',\n                tool_use_id: \"${use.id}\", \n                content: String(error),\n                is_error: true\n            });\n        }\n        `;\n    });\n\n    code += `return results;`;\n    return code;\n}\n\n/**\n * Create a single \"codegen tool\" for LLM consumption.\n * \n * Instead of passing N individual tools to the LLM, this returns a single\n * tool that accepts TypeScript code. The LLM writes code that uses the\n * available tools, and the code is executed in the sandbox.\n * \n * @param domainDocumentation - Documentation of available tools (from environment.getDomainDocumentation())\n * @returns A single Anthropic tool definition\n */\nexport function createCodegenTool(domainDocumentation: string): AnthropicToolDefinition {\n    return {\n        name: 'execute_sandbox_code',\n        description: `Execute TypeScript code in a secure sandbox environment. The code can use the following tools by importing from \"./sandbox-tools\":\n\n${domainDocumentation}\n\nWrite complete, executable TypeScript code. Use async/await for tool calls. Return results at the end.`,\n        input_schema: {\n            type: 'object',\n            properties: {\n                code: {\n                    type: 'string',\n                    description: 'TypeScript code to execute. Must import tools from \"./sandbox-tools\" and use await for all tool calls.',\n                },\n            },\n            required: ['code'],\n        },\n    };\n}\n\n/**\n * Helper to execute a codegen tool use block.\n * \n * @param toolUse - The tool_use block from the Anthropic response\n * @param environment - The connected Granular environment\n * @returns The job result\n */\nexport async function executeCodegenToolUse(\n    toolUse: AnthropicToolUseBlock,\n    environment: { submitJob: (code: string) => Promise<{ result: Promise<unknown> }> }\n): Promise<unknown> {\n    if (toolUse.name !== 'execute_sandbox_code') {\n        throw new Error(`Unknown tool: ${toolUse.name}`);\n    }\n\n    const input = toolUse.input as { code: string };\n    const job = await environment.submitJob(input.code);\n    return job.result;\n}\n"]}