@granular-software/sdk 0.4.31 → 0.4.32

package/dist/cli/index.js

@@ -17779,7 +17779,11 @@ var WSClient = class {
       return null;
     }
     try {
-      const payloadRaw = this.decodeBase64Url(parts[1]);
+      const payloadSegment = parts[1];
+      if (!payloadSegment) {
+        return null;
+      }
+      const payloadRaw = this.decodeBase64Url(payloadSegment);
       const payload = JSON.parse(payloadRaw);
       if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
         return null;
@@ -18856,6 +18860,7 @@ import { ${allImports} } from "./sandbox-tools";
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
+    return () => this.off(event, handler);
   }
   /**
    * Unsubscribe from session events
@@ -19312,6 +19317,16 @@ var JobImplementation = class {
         handler(message);
       }
     }
+    return () => {
+      const handlers = this.eventListeners.get(event);
+      if (!handlers) {
+        return;
+      }
+      this.eventListeners.set(
+        event,
+        handlers.filter((current) => current !== handler)
+      );
+    };
   }
   replayAgentMessage(message) {
     this.captureAgentMessage(message);
@@ -20015,7 +20030,9 @@ var Environment = class {
       }
     );
     if (result.errors?.length) {
-      throw new Error(`defineRelationship failed: ${result.errors[0].message}`);
+      throw new Error(
+        `defineRelationship failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data.at.define_relationship;
   }
@@ -20051,7 +20068,9 @@ var Environment = class {
       { path: modelPath }
     );
     if (result.errors?.length) {
-      throw new Error(`getRelationships failed: ${result.errors[0].message}`);
+      throw new Error(
+        `getRelationships failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.model?.relationships || [];
   }
@@ -20090,7 +20109,7 @@ var Environment = class {
       { target: targetPath }
     );
     if (result.errors?.length) {
-      throw new Error(`attach failed: ${result.errors[0].message}`);
+      throw new Error(`attach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
   }
   /**
@@ -20125,7 +20144,7 @@ var Environment = class {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`detach failed: ${result.errors[0].message}`);
+      throw new Error(`detach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
   }
   /**
@@ -20152,7 +20171,9 @@ var Environment = class {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`listRelated failed: ${result.errors[0].message}`);
+      throw new Error(
+        `listRelated failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.at?.at?.list_related || [];
   }
@@ -20245,7 +20266,7 @@ var Environment = class {
   async _runGraphql(query, label) {
     const result = await this.graphql(query);
     if (result.errors?.length) {
-      throw new Error(`${label}: ${result.errors[0].message}`);
+      throw new Error(`${label}: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
     return result.data;
   }
@@ -20590,7 +20611,11 @@ var Environment = class {
    */
   async recordObject(options) {
     const results = await this.recordObjects([options]);
-    return results[0];
+    const result = results[0];
+    if (!result) {
+      throw new Error("recordObject: no result returned for record");
+    }
+    return result;
   }
   /**
    * Batch version of `recordObject()`.
@@ -20642,7 +20667,13 @@ var Environment = class {
             );
           }
           for (let index = 0; index < items.length; index += 1) {
-            results[plan.offset + index] = items[index];
+            const item = items[index];
+            if (!item) {
+              throw new Error(
+                `recordObjects: chunk ${plan.chunkIndex + 1} returned an empty result at index ${index}`
+              );
+            }
+            results[plan.offset + index] = item;
           }
           if (onChunk) {
             const info2 = {
@@ -22046,7 +22077,7 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find((environment2) => matchesEnvironmentName(environment2, environmentName));
+  const existing = environments.find((environment) => matchesEnvironmentName(environment, environmentName));
   if (existing) {
     return existing;
   }
@@ -22055,13 +22086,13 @@ async function resolveEnvironmentData(granular, options) {
       `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
-  const environment = await granular.openEnvironment({
+  const connection = await granular.connect({
     ontology: ontologyId,
-    tag: environmentName,
+    environment: environmentName,
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  return await granular.environments.get(environment.environmentId);
+  return await granular.environments.get(connection.environmentId);
 }
 async function listSessionsForEnvironment(granular, environmentId, status) {
   if (status === "all") {
@@ -22078,12 +22109,12 @@ async function listSessionsForEnvironment(granular, environmentId, status) {
 async function connectRuntime(options) {
   if (options.sessionId) {
     const { granular: granular2 } = createGranularClient();
-    const session3 = await granular2["connectSession"]({ sessionId: options.sessionId });
+    const environment2 = await granular2.connectSession({ sessionId: options.sessionId });
     return {
       granular: granular2,
-      environment: session3.environment,
-      session: session3,
-      ontologyId: session3.ontologyId || session3.sandboxId
+      environment: environment2,
+      session: environment2,
+      ontologyId: environment2.ontologyId || environment2.sandboxId
     };
   }
   const { granular, config } = createGranularClient();
@@ -22091,17 +22122,17 @@ async function connectRuntime(options) {
   if (!ontologyId) {
     throw new Error("No ontology configured. Run `granular init` first or pass `--ontology`.");
   }
-  const environment = await granular.openEnvironment({
+  const environmentHandle = await granular.connect({
     ontology: ontologyId,
-    tag: options.environment ?? "dev",
+    environment: options.environment ?? "dev",
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  const session2 = await environment.sessions.create();
+  const environment = await environmentHandle.createSession();
   return {
     granular,
     environment,
-    session: session2,
+    session: environment,
     ontologyId
   };
 }
@@ -22111,9 +22142,9 @@ async function withRuntimeConnection(options, callback) {
     return await callback(connection);
   } finally {
     try {
-      await connection.session.disconnect();
+      await connection.environment.disconnect();
     } catch {
-      connection.session.disconnectTransport();
+      connection.environment?.client?.disconnect?.();
     }
   }
 }
@@ -22150,14 +22181,14 @@ async function connectTestCommand(options) {
       userId: options.user,
       permissions: normalizePermissions(options.permissions)
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ok: true,
         ontologyId,
         sandboxId: environment.sandboxId,
         environmentId: environment.environmentId,
-        environment: environment.environment,
-        sessionId: session2.sessionId,
+        environment: environment.envName,
+        sessionId: environment.sessionId,
         subjectId: environment.subjectId,
         versionId: environment.versionId
       };
@@ -22203,12 +22234,12 @@ async function sessionHeapCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         environmentId: environment.environmentId,
-        heap: session2.getHeap()
+        heap: environment.getHeap()
       };
       if (!emitJson) {
         step("Session heap");
@@ -22231,12 +22262,12 @@ async function sessionDocCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         environmentId: environment.environmentId,
-        document: documentToJson(session2.document)
+        document: documentToJson(environment.document)
       };
       if (!emitJson) {
         step("Session document");
@@ -22261,18 +22292,18 @@ async function sessionCreateCommand(options) {
     permissions,
     createIfMissing: true
   });
-  const session2 = await granular.createSession({
+  const environment = await granular.createSession({
     environmentId: envData.environmentId
   });
   try {
     const payload = {
       ok: true,
       ontologyId: envData.sandboxId,
-      environmentId: session2.environmentId,
-      environment: session2.environment.environment,
-      sessionId: session2.sessionId,
-      subjectId: session2.subjectId,
-      versionId: session2.versionId
+      environmentId: environment.environmentId,
+      environment: environment.envName,
+      sessionId: environment.sessionId,
+      subjectId: environment.subjectId,
+      versionId: environment.versionId
     };
     if (emitJson) {
       console.log(JSON.stringify(payload, null, 2));
@@ -22291,9 +22322,9 @@ async function sessionCreateCommand(options) {
     console.log();
   } finally {
     try {
-      await session2.disconnect();
+      await environment.disconnect();
     } catch {
-      session2.disconnectTransport();
+      environment?.client?.disconnect?.();
     }
   }
 }
@@ -22418,12 +22449,12 @@ async function effectsListCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
-      const effects2 = sortEffects(session2.getEffects());
+    async ({ environment, ontologyId }) => {
+      const effects2 = sortEffects(environment.getEffects());
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         items: effects2
       };
       if (emitJson) {
@@ -22463,8 +22494,8 @@ async function effectsDiffCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
-      const effects2 = sortEffects(session2.getEffects());
+    async ({ environment, ontologyId }) => {
+      const effects2 = sortEffects(environment.getEffects());
       const declared = effects2.map((effect) => effect.name);
       const liveReady = effects2.filter((effect) => effect.ready).map((effect) => effect.name);
       const declaredOnly = effects2.filter((effect) => !effect.ready).map((effect) => effect.name);
@@ -22472,7 +22503,7 @@ async function effectsDiffCommand(options) {
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         summary: {
           declaredCount: declared.length,
           liveReadyCount: liveReady.length,

package/dist/{client-CTH1hfwe.d.mts → client-C2Gk641P.d.mts}

@@ -9,7 +9,7 @@ import { Doc } from '@automerge/automerge/slim';
  * Configuration for the Granular client
  */
 type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
-type EndpointMode = "auto" | "local" | "production";
+type EndpointMode = 'auto' | 'local' | 'production';
 interface GranularOptions {
     /** Your Granular API key (for service/CLI auth; use with GRANULAR_API_KEY) */
     apiKey?: string;
@@ -86,15 +86,16 @@ interface Subject {
     updatedAt: number;
 }
 /**
- * Options for opening or resolving an ontology environment for one user.
+ * Options for opening an ontology environment for one delegated subject.
  *
- * This does **not** open a session. Use `environment.sessions.create()` after
- * opening the environment when you need a live runtime connection.
+ * This does not open a live runtime session. Use
+ * `environment.sessions.create()` or `granular.createSession({ environmentId })`
+ * when you need a conversation/session with jobs, prompts, heap, and effects.
  */
 interface OpenEnvironmentOptions {
-    /** The ontology name or ID to open */
+    /** The ontology name or ID to open. */
     ontology: string;
-    /** Version channel to follow, typically `dev` or `prod` */
+    /** Version channel to follow, typically `dev` or `prod`. */
     tag?: string;
     /**
      * External user identifier from your app.
@@ -108,9 +109,9 @@ interface OpenEnvironmentOptions {
      * Exactly one of `userId`, `granularId`, or `user` should be provided.
      */
     granularId?: string;
-    /** Optional display name used when upserting the user */
+    /** Optional display name used when upserting the user. */
     name?: string;
-    /** Optional email used when upserting the user */
+    /** Optional email used when upserting the user. */
     email?: string;
     /**
      * Permission profile names or IDs to ensure before opening the environment.
@@ -124,14 +125,14 @@ interface OpenEnvironmentOptions {
      * the newest tag target instead of reusing the outdated one.
      */
     createFreshIfOutdated?: boolean;
-    /** Backwards-compatible user object returned from recordUser() */
+    /** Backwards-compatible user object returned from `recordUser()`. */
     user?: User;
 }
 /**
  * Deprecated compatibility alias for the legacy `connect()` entry point.
  *
- * `connect()` now resolves an environment handle and no longer opens a
- * runtime session automatically. Prefer `openEnvironment()` for new code.
+ * `connect()` now resolves an environment handle and no longer opens a runtime
+ * session automatically. Prefer `openEnvironment()` for new code.
  */
 interface ConnectOptions extends OpenEnvironmentOptions {
     /** @deprecated Legacy explicit environment slot name. Prefer `tag`. */
@@ -167,7 +168,7 @@ interface ConversationSessionInfo {
     environmentId: string;
     versionId?: string | null;
     docId: string;
-    status: "active" | "closed" | "expired";
+    status: 'active' | 'closed' | 'expired';
     createdAt: string;
     lastSeenAt: string;
     summary?: string | null;
@@ -275,7 +276,7 @@ interface AssignmentListResponse {
  * pin themselves to one immutable ontology version.
  */
 interface BuildPolicy {
-    mode: "tag" | "current" | "pinned";
+    mode: 'tag' | 'current' | 'pinned';
     buildId?: string;
     versionId?: string;
     tagId?: string;
@@ -286,7 +287,7 @@ interface VersionTag {
     tagId: string;
     sandboxId: string;
     name: string;
-    kind: "channel" | "release" | "system";
+    kind: 'channel' | 'release' | 'system';
     targetBuildId?: string | null;
     targetVersionId?: string | null;
     description?: string | null;
@@ -311,7 +312,7 @@ interface EnvironmentData {
     tag?: VersionTag | null;
     tracking?: BuildPolicy;
     buildPolicy: BuildPolicy;
-    updateState?: "up_to_date" | "update_available" | "upgrading" | "failed";
+    updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
     createdAt: number;
     updatedAt: number;
 }
@@ -360,7 +361,7 @@ interface Manifest {
 interface ManifestListResponse {
     items: Manifest[];
 }
-type BuildStatus = "queued" | "building" | "completed" | "failed" | "canceled";
+type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
 /**
  * An immutable ontology version derived from a specific manifest revision.
  *
@@ -395,8 +396,8 @@ interface BuildListResponse {
 }
 interface SemanticVersionDiffEntry {
     operationId: string;
-    kind: "create" | "update" | "relationship" | "effect" | "eventStream" | "unknown";
-    changeType: "added" | "removed" | "changed";
+    kind: 'create' | 'update' | 'relationship' | 'effect' | 'eventStream' | 'unknown';
+    changeType: 'added' | 'removed' | 'changed';
     label: string;
     additive: boolean;
     breaking: boolean;
@@ -458,7 +459,7 @@ interface ResolvedEffectBehaviors {
     reverse?: ResolvedEffectReverse;
     approvalRequired?: ResolvedEffectApprovalRequired;
 }
-type EffectInvocationMode = "execute" | "dryRun" | "reverse";
+type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
 interface EffectInvocationMetadata {
     mode?: EffectInvocationMode;
     reverseHandler?: string;
@@ -515,9 +516,9 @@ interface ToolSchema {
      * ```
      */
     outputSchema?: Record<string, unknown>;
-    stability?: "stable" | "experimental" | "deprecated";
+    stability?: 'stable' | 'experimental' | 'deprecated';
     provenance?: {
-        source: "mcp" | "custom";
+        source: 'mcp' | 'custom';
     };
     tags?: string[];
     /**
@@ -624,8 +625,8 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = "queued" | "running" | "awaitingTool" | "awaitingHuman" | "succeeded" | "failed" | "timeout" | "canceled";
-type JobFeedbackSentiment = "good" | "bad";
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
     toolName?: string;
@@ -637,7 +638,7 @@ interface JobFeedbackToolCall {
     durationMs?: number | null;
 }
 interface JobFeedbackMetadata {
-    source: "sdk";
+    source: 'sdk';
     status: JobStatus;
     code: string;
     domainRevision?: string;
@@ -671,7 +672,7 @@ interface JobFeedbackRecord {
     updatedAt: number;
 }
 /**
- * Persisted feedback rows listed at the environment level.
+ * Persisted feedback row listed at the environment level.
  */
 interface EnvironmentFeedbackRecord {
     feedbackId: string;
@@ -701,11 +702,11 @@ interface Job {
     /** Attach user feedback to this job and persist it with job/session metadata */
     leaveFeedback(input: JobFeedbackInput): Promise<JobFeedbackRecord>;
     /** Subscribe to job events */
-    on(event: string, handler: (data: unknown) => void): void;
+    on(event: string, handler: (data: unknown) => void): () => void;
 }
 interface Prompt {
     id: string;
-    type: "confirm" | "choice" | "input";
+    type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
     options?: Array<string | {
@@ -724,7 +725,7 @@ interface ConversationMessageShowRefs {
     variableNames?: string[];
 }
 interface ConversationMessageInput {
-    role: "user" | "assistant";
+    role: 'user' | 'assistant';
     content?: string;
     show?: ConversationMessageShowRefs;
     jobId?: string;
@@ -740,7 +741,7 @@ interface ConversationAppendResult {
 }
 interface SessionTranscriptEntry {
     id: string;
-    role: "user" | "assistant";
+    role: 'user' | 'assistant';
     content: string;
     timestamp: number;
     jobId?: string;
@@ -751,9 +752,9 @@ interface SessionTranscriptEntry {
     error?: string;
     show?: ConversationMessageShowRefs;
     historyContent?: string;
-    source: "conversation" | "job_code" | "job_result" | "job_prompt" | "job_agent_message";
+    source: 'conversation' | 'job_code' | 'job_result' | 'job_prompt' | 'job_agent_message';
 }
-type SessionHeapFieldType = "string" | "number" | "boolean" | "null" | "unknown";
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {
     name: string;
     type: SessionHeapFieldType;
@@ -781,7 +782,7 @@ interface SessionHeapList {
 }
 interface SessionHeapVariable {
     name: string;
-    kind: "entry" | "list" | "scalar";
+    kind: 'entry' | 'list' | 'scalar';
     entryPath?: string;
     listName?: string;
     value?: string | number | boolean | null;
@@ -818,13 +819,13 @@ interface WSClientOptions {
     onReconnectError?: (info: WSReconnectErrorInfo) => void;
 }
 interface RPCRequest {
-    type: "rpc";
+    type: 'rpc';
     method: string;
     params: unknown;
     id: string;
 }
 interface RPCResponse {
-    type: "rpc_result" | "rpc_error";
+    type: 'rpc_result' | 'rpc_error';
     id: string;
     result?: unknown;
     error?: {
@@ -834,12 +835,12 @@ interface RPCResponse {
     };
 }
 interface SyncMessage {
-    type: "sync";
+    type: 'sync';
     message?: string | number[] | Uint8Array;
     data?: number[];
 }
 interface RPCRequestFromServer {
-    type: "rpc";
+    type: 'rpc';
     method: string;
     params: unknown;
     id: string;
@@ -883,7 +884,7 @@ interface RelationshipInfo {
     /** The foreign model type */
     foreign_model: ModelRef;
     /** Computed relationship kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" */
-    relationship_kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many";
+    relationship_kind: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
 }
 /**
  * Options for defining a relationship between two model types
@@ -982,8 +983,8 @@ interface RecordObjectsOptions {
      */
     onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
 }
-type RecordImportStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
-type RecordImportItemStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
+type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 interface RecordImportStats {
     totalRecords: number;
     queuedRecords: number;
@@ -1048,14 +1049,10 @@ interface ManifestPropertySpec {
     required?: boolean;
     note?: string | string[];
     enum?: string[] | ManifestEnumRuleSpec;
-    searchable?: boolean | {
-        enabled?: boolean;
-        phonetic?: boolean;
-    };
     filterBy?: boolean | string[] | ManifestFilterBySpec;
     validate?: ManifestValidationRuleSpec[];
 }
-type ManifestValidationOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "true" | "false" | "regex" | "contains" | "not_contains" | "starts_with" | "ends_with";
+type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
 interface ManifestEnumRuleSpec {
     values: string[];
     message?: string;
@@ -1144,7 +1141,7 @@ interface ManifestEffectDeclaration {
     isStatic?: boolean;
     inputSchema: ManifestEffectSchema;
     outputSchema?: ManifestEffectSchema;
-    stability?: "stable" | "experimental" | "deprecated";
+    stability?: 'stable' | 'experimental' | 'deprecated';
     tags?: string[];
     metamodels?: ManifestEffectMetamodelSpec;
 }
@@ -1205,7 +1202,7 @@ interface ManifestImport {
 }
 interface ManifestVolume {
     name: string;
-    scope: "sandbox" | "build" | "user";
+    scope: 'sandbox' | 'build' | 'user';
     imports?: ManifestImport[];
     operations: ManifestOperation[];
 }
@@ -1248,7 +1245,7 @@ interface StreamEvent {
     environmentId: string;
     sessionId?: string;
     subjectId?: string;
-    source: "sandbox" | "api";
+    source: 'sandbox' | 'api';
     isAcked: boolean;
     createdAt: number;
 }
@@ -1480,7 +1477,7 @@ declare class Session {
     /**
      * Subscribe to session events
      */
-    on(event: string, handler: (data: unknown) => void): void;
+    on(event: string, handler: (data: unknown) => void): () => void;
     /**
      * Unsubscribe from session events
      */