@granular-software/sdk 0.4.30 → 0.4.31

package/README.md

@@ -66,9 +66,9 @@ import { Granular, type ManifestContent } from "@granular-software/sdk";
 const granular = new Granular({ apiKey: process.env.GRANULAR_API_KEY });
 
 // 1. Connect to the default dev environment for one of your app users
-const env = await granular.connect({
+const env = await granular.openEnvironment({
   ontology: "my-ontology",
-  environment: "dev",
+  tag: "dev",
   userId: "user_123",
   permissions: ["agent"],
   name: "Jane Doe", // optional
@@ -130,7 +130,7 @@ await env.recordObject({
 });
 
 // 4. Register live effect handlers for effects already declared in the ontology manifest
-await granular.registerEffects(env.sandboxId, [
+await granular.ontology(env.sandboxId).effects.registerMany([
   {
     name: "get_billing_summary",
     description: "Get billing summary for a customer",
@@ -167,7 +167,8 @@ await granular.registerEffects(env.sandboxId, [
 ]);
 
 // 6. Submit a job — the sandbox gets fully typed OOP classes!
-const job = await env.submitJob(`
+const session = await env.sessions.create();
+const job = await session.submitJob(`
   import { Customer } from './sandbox-tools';
 
   // list() discovers instances; get({ path }) hydrates a specific graph object
@@ -195,15 +196,15 @@ Effects must be declared ahead of time in the ontology version manifest with `wi
 ## Core Flow
 
 ```
-declare effects in the manifest → `granular build` creates or reuses a version → `connect({ ontology, environment, userId })` opens a named environment → `recordObject()` or `recordObjects()` → `registerEffects()` → `submitJob()`
+declare effects in the manifest → `granular build` creates or reuses a version → `openEnvironment({ ontology, tag, userId })` resolves the user's environment → `recordObject()` or `recordObjects()` → `granular.ontology(...).effects.registerMany()` → `environment.sessions.create()` → `session.submitJob()`
 ```
 
-1. **`connect()`** — Connect to an ontology environment for a given `userId`, returning an `Environment`
+1. **`openEnvironment()`** — Resolve or create an ontology environment for a given `userId`, returning an `Environment`
 2. **`recordUser()`** — Optional explicit user upsert when you want the returned `granularId`
 3. **`applyManifest()`** — Define your domain ontology (classes, properties, relationships)
 4. **`recordObject()` / `recordObjects()`** — Use `recordObject()` for one targeted upsert. Use `recordObjects()` for immediate multi-record writes with chunk progress.
-5. **`granular.registerEffects()`** — Register sandbox-scoped live handlers for effects declared in the ontology manifest
-6. **`submitJob()`** — Execute code in the sandbox that uses the auto-generated typed classes
+5. **`granular.ontology(...).effects.registerMany()`** — Register ontology-scoped live handlers for effects declared in the ontology manifest
+6. **`environment.sessions.create()` / `session.submitJob()`** — Open a live session and execute code against the sandbox runtime
 
 ## Defining the Domain Ontology
 
@@ -263,9 +264,9 @@ await env.applyManifest(manifest);
 After defining the ontology, connect as a user and populate it with data:
 
 ```typescript
-const env = await granular.connect({
+const env = await granular.openEnvironment({
   ontology: "library-app",
-  environment: "dev",
+  tag: "dev",
   userId: "user_123",
   permissions: ["agent"],
 });
@@ -307,10 +308,10 @@ For one-off writes, `recordObject(...)` is still the clearest choice. For large
 
 ## Effect Definitions
 
-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:
+Effects are declared in the manifest with `withEffect`, then their live handlers are registered at ontology scope. Effects can be **instance methods**, **static methods**, or **global functions**. Both `inputSchema` and `outputSchema` use JSON Schema:
 
 ```typescript
-await granular.registerEffects(env.sandboxId, [
+await granular.ontology(env.sandboxId).effects.registerMany([
   // Instance method: called as `tolkien.get_bio({ detailed: true })`
   // Handler receives (objectId, params)
   {
@@ -553,9 +554,9 @@ See [examples/](./examples/) for runnable code:
 
 Registers a user identity and their assigned permission profiles.
 
-### `granular.connect(options)`
+### `granular.openEnvironment(options)`
 
-Connects to an environment session for the specified user. Pass `ontology` and `environment` explicitly, for example `environment: 'dev'` or `environment: 'prod'`. Only pass `tagName` for advanced overrides.
+Resolves or creates an environment handle for the specified user. Pass `ontology` and a tag such as `tag: 'dev'` or `tag: 'prod'`.
 
 ### `environment.applyManifest(manifest)`
 
@@ -585,15 +586,15 @@ Returns relationship definitions for a given class.
 
 Lists related instances through a relationship.
 
-### `granular.registerEffects(sandboxId, effects)`
+### `granular.ontology(sandboxId).effects.registerMany(effects)`
 
-Registers sandbox-scoped live handlers for effects declared in the ontology manifest. Effects can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
+Registers ontology-scoped live handlers for effects declared in the ontology manifest. Effects can be instance methods (`className` set, `static` omitted), static methods (`static: true`), or global functions (no `className`).
 
-### `environment.submitJob(code)`
+### `environment.sessions.create(options?)` / `session.submitJob(code)`
 
-Submits code to be executed in the sandbox. The code imports typed classes from `./sandbox-tools`.
+Open a live runtime session for the environment, then submit code to the sandbox. The code imports typed classes from `./sandbox-tools`.
 
-### `environment.getDomainDocumentation()`
+### `session.getDomainDocumentation()`
 
 Get auto-generated TypeScript class declarations. Pass this to LLMs to help them write correct code.
 
@@ -601,7 +602,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)`
+### `session.on(event, handler)`
 
 Listen for events: `'effect:invoke'`, `'effect:result'`, `'job:status'`, `'stdout'`, etc. Legacy `'tool:*'` aliases still exist internally but are no longer the primary model.
 
@@ -616,3 +617,7 @@ Extract the real-world ID from a graph path by stripping the class prefix.
 ## License
 
 MIT
+
+## License
+
+MIT

package/dist/agent-evals.d.mts

@@ -1,4 +1,4 @@
-import { P as Prompt, e as Environment, c as SessionHeapSnapshot, b3 as ManifestContent, aB as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, z as CreateEnvironmentData, j as GranularOptions } from './client-BVvOMfln.mjs';
+import { P as Prompt, f as EnvironmentSession, c as SessionHeapSnapshot, b8 as ManifestContent, aG as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, J as CreateEnvironmentData, k as GranularOptions } from './client-CTH1hfwe.mjs';
 import { GeneratedJobCodeIssue, HarnessControllerBudgets } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -49,7 +49,7 @@ interface AgentEvalExpectations {
 }
 interface AgentEvalCheckContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
     request: string;
     responseText: string;
@@ -73,7 +73,7 @@ interface AgentEvalInspection {
 }
 interface AgentEvalSetupContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
 }
 interface AgentEvalSetup {
@@ -84,7 +84,7 @@ interface AgentEvalSetup {
 }
 interface AgentEvalPrepareContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
 }
 interface AgentEvalStep {
@@ -148,7 +148,7 @@ interface AgentEvalHarnessOptions {
     openEnvironment?: (input: {
         label: string;
         clientId: string;
-    }) => Promise<Environment>;
+    }) => Promise<EnvironmentSession>;
     generator: AgentEvalTurnGenerator;
     artifactBaseDir?: string;
     suiteName?: string;
@@ -159,7 +159,7 @@ interface AgentEvalHarnessOptions {
 }
 interface AgentEvalConversation {
     label: string;
-    environment: Environment;
+    environment: EnvironmentSession;
     history: AgentEvalHistoryEntry[];
     promptEvents: PendingPromptEvent[];
     artifactDir: string;
@@ -224,6 +224,7 @@ declare function runAgentEvalSuite(options: {
 }): Promise<AgentEvalSuiteResult>;
 declare function createAgentEvalHarness(options: AgentEvalHarnessOptions): {
     artifactDir: string;
+    granular: Granular;
     openConversation: (label: string) => Promise<AgentEvalConversation>;
     closeConversation: (conversation: AgentEvalConversation) => Promise<void>;
     runTurn: (input: {

package/dist/agent-evals.d.ts

@@ -1,4 +1,4 @@
-import { P as Prompt, e as Environment, c as SessionHeapSnapshot, b3 as ManifestContent, aB as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, z as CreateEnvironmentData, j as GranularOptions } from './client-BVvOMfln.js';
+import { P as Prompt, f as EnvironmentSession, c as SessionHeapSnapshot, b8 as ManifestContent, aG as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, J as CreateEnvironmentData, k as GranularOptions } from './client-CTH1hfwe.js';
 import { GeneratedJobCodeIssue, HarnessControllerBudgets } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -49,7 +49,7 @@ interface AgentEvalExpectations {
 }
 interface AgentEvalCheckContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
     request: string;
     responseText: string;
@@ -73,7 +73,7 @@ interface AgentEvalInspection {
 }
 interface AgentEvalSetupContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
 }
 interface AgentEvalSetup {
@@ -84,7 +84,7 @@ interface AgentEvalSetup {
 }
 interface AgentEvalPrepareContext {
     conversation: AgentEvalConversation;
-    environment: Environment;
+    environment: EnvironmentSession;
     turnDir: string;
 }
 interface AgentEvalStep {
@@ -148,7 +148,7 @@ interface AgentEvalHarnessOptions {
     openEnvironment?: (input: {
         label: string;
         clientId: string;
-    }) => Promise<Environment>;
+    }) => Promise<EnvironmentSession>;
     generator: AgentEvalTurnGenerator;
     artifactBaseDir?: string;
     suiteName?: string;
@@ -159,7 +159,7 @@ interface AgentEvalHarnessOptions {
 }
 interface AgentEvalConversation {
     label: string;
-    environment: Environment;
+    environment: EnvironmentSession;
     history: AgentEvalHistoryEntry[];
     promptEvents: PendingPromptEvent[];
     artifactDir: string;
@@ -224,6 +224,7 @@ declare function runAgentEvalSuite(options: {
 }): Promise<AgentEvalSuiteResult>;
 declare function createAgentEvalHarness(options: AgentEvalHarnessOptions): {
     artifactDir: string;
+    granular: Granular;
     openConversation: (label: string) => Promise<AgentEvalConversation>;
     closeConversation: (conversation: AgentEvalConversation) => Promise<void>;
     runTurn: (input: {