@granular-software/sdk 0.4.36 → 0.4.37

package/dist/{client-Cq8onk2D.d.mts → client-eE9nTfvp.d.mts}

@@ -1,3 +1,4 @@
+import { PermissionProfileFile } from '@granular-software/policy-engine';
 import * as Automerge from '@automerge/automerge';
 import { Doc } from '@automerge/automerge/slim';
 
@@ -5,6 +6,7 @@ import { Doc } from '@automerge/automerge/slim';
  * @module @granular-software/sdk/types
  * Type definitions for the Granular SDK
  */
+
 /**
  * Configuration for the Granular client
  */
@@ -19,6 +21,8 @@ interface GranularOptions {
     tokenProvider?: AccessTokenProvider;
     /** Optional API URL (for on-prem or testing) */
     apiUrl?: string;
+    /** Optional live effect-host WebSocket/base URL override (for local/on-prem routing) */
+    effectHostUrl?: string;
     /** Optional endpoint mode when apiUrl is not explicitly provided */
     endpointMode?: EndpointMode;
     /** Optional WebSocket constructor (for Node.js environments) */
@@ -141,7 +145,11 @@ interface ConnectOptions extends OpenEnvironmentOptions {
     tagName?: string;
     /** @deprecated Ignored by `connect()` now that it no longer opens sessions. */
     clientId?: string;
-    /** @deprecated Ignored by `connect()` now that it no longer opens sessions. */
+    /**
+     * @deprecated Ignored by `connect()` now that it no longer opens sessions.
+     * Uses application record identity: class name plus the record id from the
+     * customer's own system. Granular resolves the internal graph path.
+     */
     initialHeap?: Array<{
         className: string;
         id: string;
@@ -153,7 +161,11 @@ interface ConnectOptions extends OpenEnvironmentOptions {
 interface CreateSessionOptions {
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. */
     clientId?: string;
-    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    /**
+     * Optional session heap seed. Each item uses application record identity:
+     * class name plus the record id from the customer's own system. Granular
+     * resolves and hydrates the corresponding internal graph record on connect.
+     */
     initialHeap?: Array<{
         className: string;
         id: string;
@@ -234,7 +246,9 @@ interface PermissionProfile {
     permissionProfileId: string;
     sandboxId: string;
     name: string;
-    rules: PermissionRules;
+    description?: string;
+    rules?: PermissionProfileFile;
+    profile?: PermissionProfileFile;
     createdAt: number;
     updatedAt: number;
 }
@@ -243,7 +257,7 @@ interface PermissionProfile {
  */
 interface CreatePermissionProfileData {
     name: string;
-    rules: PermissionRules;
+    rules: PermissionProfileFile;
 }
 /**
  * List response for permission profiles
@@ -865,6 +879,24 @@ interface SessionHeapSnapshot {
     variablesByName: Record<string, SessionHeapVariable>;
     updatedAt: number;
 }
+interface RecordSearchResult {
+    path: string;
+    className: string;
+    id: string;
+    label: string;
+    description?: string | null;
+    fields: SessionHeapFieldValue[];
+}
+interface RecordSearchOptions {
+    limit?: number;
+    offset?: number;
+    classNames?: string[];
+}
+interface RecordMentionInput {
+    className: string;
+    id?: string;
+    path?: string;
+}
 interface SessionDocumentResult {
     sessionState: Record<string, unknown> | null;
     document: Record<string, unknown> | null;
@@ -1070,6 +1102,12 @@ interface RecordObjectsOptions {
      */
     onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
 }
+type RecordImportWriteMode = "adaptive" | "batched" | "per_record" | "parallel_5";
+interface RecordImportOptions {
+    batchSize?: number;
+    setupRunId?: string;
+    writeMode?: RecordImportWriteMode;
+}
 type RecordImportStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
 type RecordImportItemStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
 interface RecordImportStats {
@@ -1124,6 +1162,17 @@ interface EnvironmentRecordImportSummary extends RecordImportStats {
     updatedAt: number;
 }
 type EnvironmentSetupTriggerReason = "new_environment" | "fresh_after_version_update";
+interface RunEnvironmentImporterOptions {
+    /**
+     * Ontology name/id used to resolve the registered importer. Defaults to the
+     * environment sandbox id.
+     */
+    ontology?: string;
+    /**
+     * Reason recorded on the setup run. Defaults to `new_environment`.
+     */
+    reason?: EnvironmentSetupTriggerReason;
+}
 type EnvironmentSetupLifecycleStatus = "running" | "completed" | "failed";
 interface EnvironmentSetupSummary extends RecordImportStats {
     setupRunId: string;
@@ -1144,6 +1193,7 @@ interface EnvironmentSetupSummary extends RecordImportStats {
 }
 interface EnvironmentImporterImportOptions {
     batchSize?: number;
+    writeMode?: RecordImportWriteMode;
 }
 interface EnvironmentImporter {
     environmentId: string;
@@ -1469,6 +1519,8 @@ declare class Session {
     private lastKnownTools;
     /** Last seen live prompts, keyed by prompt id, for answer normalization */
     private promptCache;
+    /** Prompt ids locally answered before the document sync catches up. */
+    private hiddenPromptIds;
     constructor(client: WSClient, clientId?: string);
     private extractDomainRevisionFromDoc;
     private buildLegacyEffectContext;
@@ -1534,7 +1586,11 @@ declare class Session {
      * `effect.invoke` RPC back to the sandbox effect host, where the registered handlers
      * execute locally and return the result to the sandbox.
      */
-    submitJob(code: string, domainRevision?: string): Promise<Job>;
+    submitJob(code: string, domainRevisionOrOptions?: string | {
+        domainRevision?: string;
+        metadata?: Record<string, unknown>;
+        agent?: Record<string, unknown>;
+    }): Promise<Job>;
     /**
      * Register a handler for a specific tool.
      * @param isInstance - If true, handler will receive (id, params) for instance method dispatch.
@@ -1550,6 +1606,14 @@ declare class Session {
      * Consolidates effect declarations and live availability for the session.
      */
     getEffects(): EffectInfo[];
+    /**
+     * Return the currently open prompt payloads known to this session.
+     *
+     * These come from live `prompt` / `prompt.request` websocket events and
+     * preserve the exact shape used by `answerPrompt(...)`.
+     */
+    getPrompts(): Prompt[];
+    getHiddenPromptIds(): string[];
     /**
      * Backwards-compatible alias for `getEffects()`.
      */
@@ -1707,24 +1771,20 @@ declare class Environment {
     listFeedback(): Promise<EnvironmentFeedbackRecord[]>;
     private getRuntimeBaseUrl;
     private controlPlaneRequest;
+    private static normalizeGraphPathSegment;
     /**
-     * Convert a class name + real-world ID into a unique graph path.
-     *
-     * Two objects of *different* classes may share the same real-world ID,
-     * so the graph path must incorporate the class to guarantee uniqueness.
-     *
-     * Format: `{className}_{id}` — deterministic, human-readable.
+     * Convert a class name + application record ID into Granular's graph path.
      *
-     * **Convention**: class names should be simple identifiers without
-     * underscores (e.g. `author`, `book`).  This ensures the prefix is
-     * unambiguously parseable by `extractIdFromGraphPath`.
+     * This mirrors the record-write path normalization used by the control plane.
+     * Keep the original customer/system ID in `real_id`; graph paths are stable
+     * internal addresses, not the source of truth for business identity.
      */
     static toGraphPath(className: string, id: string): string;
     /**
-     * Extract the real-world ID from a graph path, given the class name.
+     * Best-effort extraction of an ID-like suffix from a graph path.
      *
-     * Strips the `{className}_` prefix. Returns the raw path if the
-     * expected prefix is not found.
+     * Prefer the record's `real_id` field whenever exact customer/system IDs
+     * matter, because graph path normalization is intentionally lossy.
      */
     static extractIdFromGraphPath(graphPath: string, className: string): string;
     /**
@@ -1752,6 +1812,7 @@ declare class Environment {
      * ```
      */
     graphql<T = any>(query: string, variables?: Record<string, any>): Promise<GraphQLResult<T>>;
+    searchRecords(query: string, options?: RecordSearchOptions): Promise<RecordSearchResult[]>;
     /**
      * Define a relationship between two model types.
      *
@@ -1961,10 +2022,7 @@ declare class Environment {
      * need every row committed before the HTTP call returns. Use **`recordObjects`** when you need
      * synchronous upserts and fine-grained chunk progress via **`onChunkComplete`**.
      */
-    enqueueRecordImport(records: RecordObjectOptions[], options?: {
-        batchSize?: number;
-        setupRunId?: string;
-    }): Promise<RecordImport>;
+    enqueueRecordImport(records: RecordObjectOptions[], options?: RecordImportOptions): Promise<RecordImport>;
     /**
      * List queued or completed record imports for this environment.
      */
@@ -1996,12 +2054,15 @@ declare class Environment {
  */
 declare class EnvironmentSession extends Session {
     readonly environment: Environment;
+    private readonly sessionDataRoutePrefix;
     /** The last known graph container status, updated by checkReadiness() or on heartbeat */
     graphContainerStatus: {
         lastKeepAliveAt: number;
         status: "warming" | "hot" | "unknown";
     } | null;
-    constructor(client: WSClient, environment: Environment, clientId: string);
+    constructor(client: WSClient, environment: Environment, clientId: string, options?: {
+        sessionDataRoutePrefix?: string;
+    });
     get environmentId(): string;
     get sandboxId(): string;
     get ontologyId(): string;
@@ -2059,11 +2120,21 @@ declare class EnvironmentSession extends Session {
             list: (options?: SessionCollectionListOptions) => Promise<SessionCollectionListResult<SessionHeapList>>;
             get: (name: string) => Promise<SessionHeapList>;
         };
+        variables: {
+            list: (options?: SessionCollectionListOptions) => Promise<SessionCollectionListResult<SessionHeapVariable>>;
+            get: (name: string) => Promise<SessionHeapVariable>;
+            delete: (name: string) => Promise<{
+                deleted: boolean;
+                name: string;
+            }>;
+        };
     };
     get transcript(): {
         list: (options?: SessionCollectionListOptions) => Promise<SessionCollectionListResult<SessionTranscriptEntry>>;
     };
     graphql<T = any>(query: string, variables?: Record<string, any>): Promise<GraphQLResult<T>>;
+    searchRecords(query: string, options?: RecordSearchOptions): Promise<RecordSearchResult[]>;
+    mentionRecord(input: RecordMentionInput): Promise<SessionHeapEntry>;
     defineRelationship(options: DefineRelationshipOptions): Promise<RelationshipInfo>;
     getRelationships(modelPath: string): Promise<RelationshipInfo[]>;
     attach(modelPath: string, submodelPath: string, targetPath: string): Promise<void>;
@@ -2075,9 +2146,7 @@ declare class EnvironmentSession extends Session {
     }>;
     recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
     recordObjects(records: RecordObjectOptions[], options?: RecordObjectsOptions): Promise<RecordObjectResult[]>;
-    enqueueRecordImport(records: RecordObjectOptions[], options?: {
-        batchSize?: number;
-    }): Promise<RecordImport>;
+    enqueueRecordImport(records: RecordObjectOptions[], options?: RecordImportOptions): Promise<RecordImport>;
     listRecordImports(status?: RecordImportStatus): Promise<RecordImport[]>;
     getRecordImportSummary(): Promise<EnvironmentRecordImportSummary>;
     getAwaitingRecordCount(): Promise<number>;
@@ -2132,6 +2201,7 @@ declare class Granular {
     private WebSocketCtor?;
     private onUnexpectedClose?;
     private onReconnectError?;
+    private effectHostUrl?;
     private debugHttp;
     /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
     private sandboxEffects;
@@ -2205,6 +2275,16 @@ declare class Granular {
      * `connect()` no longer opens a runtime session automatically.
      */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * Run a registered environment importer against an environment that was
+     * opened outside this SDK instance, for example by a delegated browser flow.
+     *
+     * This uses the same setup-run and queued record-import plumbing as
+     * `openEnvironment()`: importer stages, expected object counts, and queued
+     * import counters remain visible through `environment.setup` and
+     * `getRecordImportSummary()`.
+     */
+    runEnvironmentImporterForEnvironment(environmentId: string, options?: RunEnvironmentImporterOptions): Promise<EnvironmentSetupSummary | null>;
     private resolveRequestedTag;
     private buildManagedEnvironmentName;
     private matchesTagTrackedEnvironment;
@@ -2254,6 +2334,7 @@ declare class Granular {
     }): Promise<EnvironmentSession>;
     private resolveEnvironmentImporter;
     private maybeRunEnvironmentImporter;
+    private runEnvironmentImporter;
     private bindEnvironmentHandle;
     private bindWebSocketEnvironmentSession;
     private activateEnvironment;
@@ -2305,7 +2386,7 @@ declare class Granular {
     /**
      * Ensure a permission profile exists for a sandbox, creating it if needed.
      * If profileName matches an existing profile name, returns its ID.
-     * Otherwise, creates a new profile with default allow-all rules.
+     * Otherwise, creates a v1 source-profile file shape with an allow default.
      */
     private ensurePermissionProfile;
     /**
@@ -2329,7 +2410,7 @@ declare class Granular {
         list: (sandboxId: string) => Promise<PermissionProfile[]>;
         get: (sandboxId: string, profileId: string) => Promise<PermissionProfile>;
         create: (sandboxId: string, data: CreatePermissionProfileData) => Promise<PermissionProfile>;
-        delete: (sandboxId: string, profileId: string) => Promise<DeleteResponse>;
+        delete: (_sandboxId: string, _profileId: string) => Promise<DeleteResponse>;
     };
     /**
      * Environment management
@@ -2399,4 +2480,4 @@ declare class Granular {
     private request;
 }
 
-export { type SemanticVersionDiff as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type VersionTag as F, Granular as G, type EnvironmentData as H, type InstanceToolHandler as I, type CreateEnvironmentData as J, type EnvironmentListResponse as K, type Manifest as L, type ManifestEffectMetamodelSpec as M, type ManifestListResponse as N, OntologyHandle as O, type Prompt as P, type BuildStatus as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type Build as X, type Version as Y, type BuildListResponse as Z, type SemanticVersionDiffEntry as _, type EffectHandlerContext as a, type EnvironmentImporterImportOptions as a$, type ResolvedEffectPostCondition as a0, type ResolvedEffectDryRun as a1, type ResolvedEffectReverse as a2, type ResolvedEffectApprovalRequired as a3, type EffectInvocationMode as a4, type EffectInvocationMetadata as a5, type EffectSchema as a6, type EffectWithHandler as a7, type PublishEffectsResult as a8, type EffectVersionSelector as a9, type SessionJobListOptions as aA, type SessionCollectionListResult as aB, type WSDisconnectInfo as aC, type WSReconnectErrorInfo as aD, type WSClientOptions as aE, type RPCRequest as aF, type RPCResponse as aG, type SyncMessage as aH, type RPCRequestFromServer as aI, type ToolInvokeParams as aJ, type ToolResultParams as aK, type ModelRef as aL, type RelationshipInfo as aM, type DefineRelationshipOptions as aN, type RecordObjectOptions as aO, type RecordObjectResult as aP, type RecordObjectsChunkInfo as aQ, type RecordObjectsOptions as aR, type RecordImportStatus as aS, type RecordImportItemStatus as aT, type RecordImportStats as aU, type RecordImportItem as aV, type RecordImport as aW, type EnvironmentRecordImportSummary as aX, type EnvironmentSetupTriggerReason as aY, type EnvironmentSetupLifecycleStatus as aZ, type EnvironmentSetupSummary as a_, type ToolInfo as aa, type EffectInfo as ab, type ToolsChangedEvent as ac, type EffectsChangedEvent as ad, type EffectHandler as ae, type InstanceEffectHandler as af, type JobStatus as ag, type JobFeedbackSentiment as ah, type JobFeedbackToolCall as ai, type JobFeedbackMetadata as aj, type JobFeedbackInput as ak, type JobFeedbackRecord as al, type EnvironmentFeedbackRecord as am, type JobSubmitResult as an, type Job as ao, type ConversationMessageShowRefs as ap, type ConversationMessageInput as aq, type ConversationAppendResult as ar, type SessionConversationMessage as as, type SessionTimelineEvent as at, type SessionJobRecord as au, type SessionHeapFieldType as av, type SessionHeapFieldValue as aw, type SessionHeapVariable as ax, type SessionDocumentResult as ay, type SessionCollectionListOptions as az, type SessionHeapList as b, type EnvironmentImporter as b0, type ManifestPropertySpec as b1, type ManifestValidationOperator as b2, type ManifestEnumRuleSpec as b3, type ManifestFilterBySpec as b4, type ManifestValidationRuleSpec as b5, type ManifestStateMachineStateSpec as b6, type ManifestStateMachineTransitionSpec as b7, type ManifestStateMachineSpec as b8, type ManifestPostConditionSpec as b9, type ManifestDryRunSpec as ba, type ManifestReverseSpec as bb, type ManifestApprovalRequiredSpec as bc, type ManifestRelationshipDef as bd, type ManifestEffectSchema as be, type ManifestEffectDeclaration as bf, type ManifestEventTypeDef as bg, type ManifestEventStreamDef as bh, type ManifestOperation as bi, type ManifestImport as bj, type ManifestVolume as bk, type ManifestContent as bl, type GraphQLResult as bm, type APIError as bn, type DeleteResponse as bo, type StreamEvent as bp, type StreamSubscription as bq, type StreamStats as br, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, EnvironmentSession as f, Session as g, type ToolSchema as h, type PublishToolsResult as i, type ToolHandler as j, type GranularOptions as k, type GranularAuth as l, type RecordUserOptions as m, type Subject as n, type OpenEnvironmentOptions as o, type CreateSessionOptions as p, type ConversationSessionInfo as q, type Sandbox as r, type CreateSandboxData as s, type SandboxListResponse as t, type PermissionRules as u, type PermissionProfile as v, type CreatePermissionProfileData as w, type PermissionProfileListResponse as x, type Assignment as y, type AssignmentListResponse as z };
+export { type SemanticVersionDiff as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type VersionTag as F, Granular as G, type EnvironmentData as H, type InstanceToolHandler as I, type CreateEnvironmentData as J, type EnvironmentListResponse as K, type Manifest as L, type ManifestEffectMetamodelSpec as M, type ManifestListResponse as N, OntologyHandle as O, type Prompt as P, type BuildStatus as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type Build as X, type Version as Y, type BuildListResponse as Z, type SemanticVersionDiffEntry as _, type EffectHandlerContext as a, type RecordImport as a$, type ResolvedEffectPostCondition as a0, type ResolvedEffectDryRun as a1, type ResolvedEffectReverse as a2, type ResolvedEffectApprovalRequired as a3, type EffectInvocationMode as a4, type EffectInvocationMetadata as a5, type EffectSchema as a6, type EffectWithHandler as a7, type PublishEffectsResult as a8, type EffectVersionSelector as a9, type RecordMentionInput as aA, type SessionDocumentResult as aB, type SessionCollectionListOptions as aC, type SessionJobListOptions as aD, type SessionCollectionListResult as aE, type WSDisconnectInfo as aF, type WSReconnectErrorInfo as aG, type WSClientOptions as aH, type RPCRequest as aI, type RPCResponse as aJ, type SyncMessage as aK, type RPCRequestFromServer as aL, type ToolInvokeParams as aM, type ToolResultParams as aN, type ModelRef as aO, type RelationshipInfo as aP, type DefineRelationshipOptions as aQ, type RecordObjectOptions as aR, type RecordObjectResult as aS, type RecordObjectsChunkInfo as aT, type RecordObjectsOptions as aU, type RecordImportWriteMode as aV, type RecordImportOptions as aW, type RecordImportStatus as aX, type RecordImportItemStatus as aY, type RecordImportStats as aZ, type RecordImportItem as a_, type ToolInfo as aa, type EffectInfo as ab, type ToolsChangedEvent as ac, type EffectsChangedEvent as ad, type EffectHandler as ae, type InstanceEffectHandler as af, type JobStatus as ag, type JobFeedbackSentiment as ah, type JobFeedbackToolCall as ai, type JobFeedbackMetadata as aj, type JobFeedbackInput as ak, type JobFeedbackRecord as al, type EnvironmentFeedbackRecord as am, type JobSubmitResult as an, type Job as ao, type ConversationMessageShowRefs as ap, type ConversationMessageInput as aq, type ConversationAppendResult as ar, type SessionConversationMessage as as, type SessionTimelineEvent as at, type SessionJobRecord as au, type SessionHeapFieldType as av, type SessionHeapFieldValue as aw, type SessionHeapVariable as ax, type RecordSearchResult as ay, type RecordSearchOptions as az, type SessionHeapList as b, type EnvironmentRecordImportSummary as b0, type EnvironmentSetupTriggerReason as b1, type RunEnvironmentImporterOptions as b2, type EnvironmentSetupLifecycleStatus as b3, type EnvironmentSetupSummary as b4, type EnvironmentImporterImportOptions as b5, type EnvironmentImporter as b6, type ManifestPropertySpec as b7, type ManifestValidationOperator as b8, type ManifestEnumRuleSpec as b9, type ManifestFilterBySpec as ba, type ManifestValidationRuleSpec as bb, type ManifestStateMachineStateSpec as bc, type ManifestStateMachineTransitionSpec as bd, type ManifestStateMachineSpec as be, type ManifestPostConditionSpec as bf, type ManifestDryRunSpec as bg, type ManifestReverseSpec as bh, type ManifestApprovalRequiredSpec as bi, type ManifestRelationshipDef as bj, type ManifestEffectSchema as bk, type ManifestEffectDeclaration as bl, type ManifestEventTypeDef as bm, type ManifestEventStreamDef as bn, type ManifestOperation as bo, type ManifestImport as bp, type ManifestVolume as bq, type ManifestContent as br, type GraphQLResult as bs, type APIError as bt, type DeleteResponse as bu, type StreamEvent as bv, type StreamSubscription as bw, type StreamStats as bx, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, EnvironmentSession as f, Session as g, type ToolSchema as h, type PublishToolsResult as i, type ToolHandler as j, type GranularOptions as k, type GranularAuth as l, type RecordUserOptions as m, type Subject as n, type OpenEnvironmentOptions as o, type CreateSessionOptions as p, type ConversationSessionInfo as q, type Sandbox as r, type CreateSandboxData as s, type SandboxListResponse as t, type PermissionRules as u, type PermissionProfile as v, type CreatePermissionProfileData as w, type PermissionProfileListResponse as x, type Assignment as y, type AssignmentListResponse as z };