@granular-software/sdk 0.4.12 → 0.4.13

package/dist/index.mjs

@@ -1,4 +1,6 @@
 import * as Automerge from '@automerge/automerge';
+import { normalizeEffectBehaviorSummary } from '@granular-software/metamodel-effect-behaviors';
+import { DEFAULT_METAMODEL_PACKAGES } from '@granular-software/metamodel-preset-default';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -5383,6 +5385,123 @@ function resolveApiUrl(explicitApiUrl, mode) {
   }
   return resolveEndpointMode(mode) === "local" ? LOCAL_API_URL : PRODUCTION_API_URL;
 }
+function computeEffectKey(effect) {
+  const attachedClass = effect.className?.trim();
+  if (!attachedClass) {
+    return `global:${effect.name}`;
+  }
+  return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
+}
+function normalizeEffectBehaviors(value) {
+  return normalizeEffectBehaviorSummary(
+    value
+  ) || {};
+}
+function resolveInvocationMode(context) {
+  const mode = context?.invocation?.mode;
+  if (mode === "dryRun" || mode === "reverse") {
+    return mode;
+  }
+  return "execute";
+}
+function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
+  const explicitReverseHandler = request.context?.invocation?.reverseHandler?.trim();
+  const configuredReverseHandler = behaviors.reverse?.handler?.trim();
+  const reverseHandler = explicitReverseHandler || configuredReverseHandler;
+  if (!reverseHandler) {
+    return void 0;
+  }
+  if (reverseHandler.includes(":")) {
+    return effectMap.get(reverseHandler);
+  }
+  const directMatch = effectMap.get(reverseHandler);
+  if (directMatch) {
+    return directMatch;
+  }
+  const candidateKeys = [
+    computeEffectKey({
+      name: reverseHandler,
+      className: currentEffect.className,
+      static: currentEffect.static
+    }),
+    computeEffectKey({
+      name: reverseHandler
+    })
+  ];
+  for (const candidateKey of candidateKeys) {
+    const candidate = effectMap.get(candidateKey);
+    if (candidate) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function resolveHandlerForMode(effectMap, effect, request) {
+  const behaviors = normalizeEffectBehaviors(request.context?.behaviors || effect.metamodels || void 0);
+  const mode = resolveInvocationMode(request.context);
+  if (mode === "dryRun") {
+    if (effect.dryRunHandler) {
+      return { effect, mode, handler: effect.dryRunHandler };
+    }
+    if (behaviors.dryRun?.enabled) {
+      return { effect, mode, handler: effect.handler };
+    }
+    throw new Error(`Dry run is not supported for ${request.effectKey}`);
+  }
+  if (mode === "reverse") {
+    if (effect.reverseHandler) {
+      return { effect, mode, handler: effect.reverseHandler };
+    }
+    const reverseEffect = resolveReverseEffect(effectMap, effect, request, behaviors);
+    if (reverseEffect) {
+      return {
+        effect: reverseEffect,
+        mode,
+        handler: reverseEffect.reverseHandler || reverseEffect.handler
+      };
+    }
+    throw new Error(`Reverse execution is not supported for ${request.effectKey}`);
+  }
+  return { effect, mode, handler: effect.handler };
+}
+async function invokeRegisteredEffect(effectMap, request) {
+  const effect = effectMap.get(request.effectKey);
+  if (!effect) {
+    throw new Error(`Effect handler not found: ${request.effectKey}`);
+  }
+  const resolved = resolveHandlerForMode(effectMap, effect, request);
+  const context = {
+    ...request.context || {},
+    behaviors: normalizeEffectBehaviors(request.context?.behaviors || effect.metamodels || void 0),
+    invocation: {
+      mode: resolved.mode,
+      sourceEffectKey: request.effectKey,
+      sourceEffectName: request.effectName,
+      ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {}
+    }
+  };
+  if (resolved.effect.className && !resolved.effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
+    const { _objectId, ...rest } = request.input;
+    return resolved.handler(_objectId, rest, context);
+  }
+  return resolved.handler(request.input, context);
+}
+function buildFieldMetamodelMutations(fieldPath, spec) {
+  return DEFAULT_METAMODEL_PACKAGES.flatMap(
+    (pkg) => pkg.manifest?.buildFieldMutations?.(fieldPath, spec) || []
+  );
+}
+function buildModelMetamodelMutations(modelPath, spec) {
+  return DEFAULT_METAMODEL_PACKAGES.flatMap(
+    (pkg) => pkg.manifest?.buildModelMutations?.(modelPath, spec) || []
+  );
+}
+function buildEffectMetamodelMutations(toolPath, spec) {
+  if (!spec) return [];
+  return DEFAULT_METAMODEL_PACKAGES.flatMap(
+    (pkg) => pkg.manifest?.buildEffectMutations?.(toolPath, spec) || []
+  );
+}
 
 // src/client.ts
 var STANDARD_MODULES_OPERATIONS = [
@@ -5398,7 +5517,7 @@ var STANDARD_MODULES_OPERATIONS = [
 var BUILTIN_MODULES = {
   "standard_modules": STANDARD_MODULES_OPERATIONS
 };
-function computeEffectKey(effect) {
+function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
   if (!attachedClass) {
     return `global:${effect.name}`;
@@ -5975,6 +6094,87 @@ var Environment = class extends Session {
     }
     return ref;
   }
+  async _runGraphql(query, label) {
+    const result = await this.graphql(query);
+    if (result.errors?.length) {
+      throw new Error(`${label}: ${result.errors[0].message}`);
+    }
+    return result.data;
+  }
+  async _applyFieldMetamodels(fieldPath, spec) {
+    for (const mutation of buildFieldMetamodelMutations(fieldPath, spec)) {
+      await this._runGraphql(mutation.query, mutation.label);
+    }
+  }
+  async _applyModelMetamodels(modelPath, op) {
+    for (const mutation of buildModelMetamodelMutations(modelPath, op)) {
+      await this._runGraphql(mutation.query, mutation.label);
+    }
+  }
+  async _ensureWorkspaceToolsRoot() {
+    await this._runGraphql(
+      `mutation { create_model(path: "workspace", label: "workspace") { model { path } } }`,
+      "ensure workspace"
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    await this._runGraphql(
+      `mutation { at(path: "workspace") { create_submodel(subpath: "tools", label: "Tools") { model { path } } } }`,
+      "ensure workspace:tools"
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    await this._runGraphql(
+      `mutation { at(path: "workspace:tools") { create_submodel(subpath: "declared", label: "Declared") { model { path } } } }`,
+      "ensure workspace:tools:declared"
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+  }
+  async _storeEffectSchemas(toolPath, effect) {
+    await this._runGraphql(
+      `mutation { at(path: ${JSON.stringify(toolPath)}) { create_submodel(subpath: "inputSchema", label: "inputSchema") { set_string_value(value: ${JSON.stringify(JSON.stringify(effect.inputSchema))}) { done } } } }`,
+      `store inputSchema on ${toolPath}`
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    if (effect.outputSchema) {
+      await this._runGraphql(
+        `mutation { at(path: ${JSON.stringify(toolPath)}) { create_submodel(subpath: "outputSchema", label: "outputSchema") { set_string_value(value: ${JSON.stringify(JSON.stringify(effect.outputSchema))}) { done } } } }`,
+        `store outputSchema on ${toolPath}`
+      ).catch((error) => {
+        if (!error.message.includes("already exists")) throw error;
+      });
+    }
+  }
+  async _applyEffectMetamodels(toolPath, metamodels) {
+    for (const mutation of buildEffectMetamodelMutations(toolPath, metamodels)) {
+      await this._runGraphql(mutation.query, mutation.label);
+    }
+  }
+  async _applyEffectDeclaration(effect, aliasMap) {
+    let containerPath = "workspace:tools:declared";
+    if (effect.attachedClass) {
+      containerPath = this._resolveAlias(effect.attachedClass, aliasMap);
+    } else {
+      await this._ensureWorkspaceToolsRoot();
+    }
+    await this._runGraphql(
+      `mutation { at(path: ${JSON.stringify(containerPath)}) { create_submodel(subpath: ${JSON.stringify(effect.name)}, label: ${JSON.stringify(effect.name)}) { model { path } } } }`,
+      `create effect model ${containerPath}:${effect.name}`
+    ).catch((error) => {
+      if (!error.message.includes("already exists")) throw error;
+    });
+    const toolPath = `${containerPath}:${effect.name}`;
+    if (effect.description) {
+      await this._runGraphql(
+        `mutation { at(path: ${JSON.stringify(toolPath)}) { set_description(description: ${JSON.stringify(effect.description)}) { done } } }`,
+        `set effect description on ${toolPath}`
+      );
+    }
+    await this._storeEffectSchemas(toolPath, effect);
+    await this._applyEffectMetamodels(toolPath, effect.metamodels);
+  }
   /**
    * Apply a single manifest operation via GraphQL
    */
@@ -5997,24 +6197,32 @@ var Environment = class extends Session {
       const extendsRef = op.extends ? this._resolveAlias(op.extends, aliasMap) : void 0;
       const instanceOfRef = op.instanceOf ? this._resolveAlias(op.instanceOf, aliasMap) : void 0;
       if (extendsRef) {
-        await this.graphql(
-          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`
+        await this._runGraphql(
+          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`,
+          `create model ${op.create}`
         );
-        await this.graphql(
-          `mutation { at(path: "${op.create}") { add_superclass(superclass: "${extendsRef}") { model { path } } } }`
+        await this._runGraphql(
+          `mutation { at(path: "${op.create}") { add_superclass(superclass: "${extendsRef}") { model { path } } } }`,
+          `add superclass ${extendsRef} to ${op.create}`
         );
       } else if (instanceOfRef) {
-        await this.graphql(
-          `mutation { at(path: "${instanceOfRef}") { instantiate(path: "${op.create}", label: "${label}") { model { path } } } }`
+        await this._runGraphql(
+          `mutation { at(path: "${instanceOfRef}") { instantiate(path: "${op.create}", label: "${label}") { model { path } } } }`,
+          `instantiate ${op.create} from ${instanceOfRef}`
         );
       } else {
-        await this.graphql(
-          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`
+        await this._runGraphql(
+          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`,
+          `create model ${op.create}`
         );
       }
       if (op.has) {
         await this._applyFields(op.create, op.has);
       }
+      await this._applyModelMetamodels(op.create, op);
+      if (op.withEffect) {
+        await this._applyEffectDeclaration(op.withEffect, aliasMap);
+      }
       return;
     }
     if (op.on) {
@@ -6022,8 +6230,15 @@ var Environment = class extends Session {
       if (op.has) {
         await this._applyFields(target, op.has);
       }
+      await this._applyModelMetamodels(target, op);
+      if (op.withEffect) {
+        await this._applyEffectDeclaration(op.withEffect, aliasMap);
+      }
       return;
     }
+    if (op.withEffect) {
+      await this._applyEffectDeclaration(op.withEffect, aliasMap);
+    }
   }
   /**
    * Apply field definitions (has) to a model via GraphQL
@@ -6031,81 +6246,91 @@ var Environment = class extends Session {
   async _applyFields(modelPath, fields) {
     for (const [fieldName, spec] of Object.entries(fields)) {
       const fieldLabel = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
-      await this.graphql(
+      await this._runGraphql(
         `mutation {
-                    at(path: "${modelPath}") {
-                        create_submodel(subpath: "${fieldName}", label: "${fieldLabel}") {
+                    at(path: ${JSON.stringify(modelPath)}) {
+                        create_submodel(subpath: ${JSON.stringify(fieldName)}, label: ${JSON.stringify(fieldLabel)}) {
                             model { path }
                         }
                     }
-                }`
-      );
+                }`,
+        `create field ${modelPath}.${fieldName}`
+      ).catch((error) => {
+        if (!error.message.includes("already exists")) throw error;
+      });
       if (spec.type) {
-        await this.graphql(
+        await this._runGraphql(
           `mutation {
-                        at(path: "${modelPath}") {
-                            at(submodel: "${fieldName}") {
-                                add_prototype(prototype: "${spec.type}") { done }
+                        at(path: ${JSON.stringify(modelPath)}) {
+                            at(submodel: ${JSON.stringify(fieldName)}) {
+                                add_prototype(prototype: ${JSON.stringify(spec.type)}) { done }
                             }
                         }
-                    }`
+                    }`,
+          `set prototype on ${modelPath}:${fieldName}`
         );
       }
       if (spec.description) {
-        await this.graphql(
+        await this._runGraphql(
           `mutation {
-                        at(path: "${modelPath}") {
-                            at(submodel: "${fieldName}") {
-                                set_description(description: "${spec.description}") { done }
+                        at(path: ${JSON.stringify(modelPath)}) {
+                            at(submodel: ${JSON.stringify(fieldName)}) {
+                                set_description(description: ${JSON.stringify(spec.description)}) { done }
                             }
                         }
-                    }`
+                    }`,
+          `set description on ${modelPath}:${fieldName}`
         );
       }
       if (spec.value !== void 0 && spec.value !== null) {
         if (typeof spec.value === "string") {
-          await this.graphql(
+          await this._runGraphql(
             `mutation {
-                            at(path: "${modelPath}") {
-                                at(submodel: "${fieldName}") {
-                                    set_string_value(value: "${spec.value}") { done }
+                            at(path: ${JSON.stringify(modelPath)}) {
+                                at(submodel: ${JSON.stringify(fieldName)}) {
+                                    set_string_value(value: ${JSON.stringify(spec.value)}) { done }
                                 }
                             }
-                        }`
+                        }`,
+            `set string value on ${modelPath}:${fieldName}`
           );
         } else if (typeof spec.value === "number") {
-          await this.graphql(
+          await this._runGraphql(
             `mutation {
-                            at(path: "${modelPath}") {
-                                at(submodel: "${fieldName}") {
+                            at(path: ${JSON.stringify(modelPath)}) {
+                                at(submodel: ${JSON.stringify(fieldName)}) {
                                     set_number_value(value: ${spec.value}) { done }
                                 }
                             }
-                        }`
+                        }`,
+            `set number value on ${modelPath}:${fieldName}`
           );
         } else if (typeof spec.value === "boolean") {
-          await this.graphql(
+          await this._runGraphql(
             `mutation {
-                            at(path: "${modelPath}") {
-                                at(submodel: "${fieldName}") {
+                            at(path: ${JSON.stringify(modelPath)}) {
+                                at(submodel: ${JSON.stringify(fieldName)}) {
                                     set_boolean_value(value: ${spec.value}) { done }
                                 }
                             }
-                        }`
+                        }`,
+            `set boolean value on ${modelPath}:${fieldName}`
           );
         }
       }
       if (spec.ref) {
-        await this.graphql(
+        await this._runGraphql(
           `mutation {
-                        at(path: "${modelPath}") {
-                            at(submodel: "${fieldName}") {
-                                set_reference(reference: "${spec.ref}") { done }
+                        at(path: ${JSON.stringify(modelPath)}) {
+                            at(submodel: ${JSON.stringify(fieldName)}) {
+                                set_reference(reference: ${JSON.stringify(spec.ref)}) { done }
                             }
                         }
-                    }`
+                    }`,
+          `set reference on ${modelPath}:${fieldName}`
         );
       }
+      await this._applyFieldMetamodels(`${modelPath}:${fieldName}`, spec);
       if (spec.has) {
         await this._applyFields(`${modelPath}:${fieldName}`, spec.has);
       }
@@ -6445,7 +6670,7 @@ var Granular = class {
   }
   serializeEffect(effect) {
     return {
-      effectKey: computeEffectKey(effect),
+      effectKey: computeEffectKey2(effect),
       name: effect.name,
       description: effect.description,
       inputSchema: effect.inputSchema,
@@ -6481,23 +6706,54 @@ var Granular = class {
     const host = await this.ensureSandboxEffectHost(sandboxId);
     await this.publishSandboxEffectCatalog(host);
   }
-  startEffectHostHeartbeat(host) {
-    if (host.heartbeatTimer) {
-      clearInterval(host.heartbeatTimer);
+  recoverEffectHost(host, error) {
+    if (host.recovering) {
+      return;
+    }
+    if (this.sandboxEffectHosts.get(host.sandboxId) !== host) {
+      return;
     }
-    host.wsClient.call("client.heartbeat", {}).catch((error) => {
+    host.recovering = true;
+    this.stopEffectHostHeartbeat(host);
+    this.sandboxEffectHosts.delete(host.sandboxId);
+    try {
+      host.wsClient.disconnect();
+    } catch (disconnectError) {
       console.warn(
-        `[Granular] Initial effect host heartbeat failed for sandbox ${host.sandboxId}:`,
-        error
+        `[Granular] Failed to disconnect stale effect host for sandbox ${host.sandboxId}:`,
+        disconnectError
       );
+    }
+    void this.ensureSandboxEffectHost(host.sandboxId).catch((reconnectError) => {
+      console.error(
+        `[Granular] Failed to recover effect host for sandbox ${host.sandboxId} after heartbeat failure:`,
+        reconnectError
+      );
+      console.error("[Granular] Original heartbeat failure:", error);
     });
-    host.heartbeatTimer = setInterval(() => {
+  }
+  startEffectHostHeartbeat(host) {
+    if (host.heartbeatTimer) {
+      clearInterval(host.heartbeatTimer);
+    }
+    host.heartbeatInFlight = false;
+    const sendHeartbeat = (failureLabel, recoverOnFailure) => {
+      if (host.heartbeatInFlight || host.recovering) {
+        return;
+      }
+      host.heartbeatInFlight = true;
       host.wsClient.call("client.heartbeat", {}).catch((error) => {
-        console.warn(
-          `[Granular] Effect host heartbeat failed for sandbox ${host.sandboxId}:`,
-          error
-        );
+        console.warn(`${failureLabel} ${host.sandboxId}:`, error);
+        if (recoverOnFailure) {
+          this.recoverEffectHost(host, error);
+        }
+      }).finally(() => {
+        host.heartbeatInFlight = false;
       });
+    };
+    sendHeartbeat("[Granular] Initial effect host heartbeat failed for sandbox", false);
+    host.heartbeatTimer = setInterval(() => {
+      sendHeartbeat("[Granular] Effect host heartbeat failed for sandbox", true);
     }, 1e4);
   }
   stopEffectHostHeartbeat(host) {
@@ -6506,6 +6762,7 @@ var Granular = class {
     }
     clearInterval(host.heartbeatTimer);
     host.heartbeatTimer = null;
+    host.heartbeatInFlight = false;
   }
   async synchronizeEffectHost(host) {
     await host.wsClient.call("client.hello", {
@@ -6541,19 +6798,13 @@ var Granular = class {
         effectClientId,
         clientId,
         wsClient,
-        heartbeatTimer: null
+        heartbeatTimer: null,
+        heartbeatInFlight: false,
+        recovering: false
       };
       wsClient.registerRpcHandler("effect.invoke", async (params) => {
         const request = params;
-        const effect = this.getSandboxEffectMap(sandboxId).get(request.effectKey);
-        if (!effect) {
-          throw new Error(`Effect handler not found: ${request.effectKey}`);
-        }
-        if (effect.className && !effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
-          const { _objectId, ...rest } = request.input;
-          return effect.handler(_objectId, rest, request.context);
-        }
-        return effect.handler(request.input, request.context);
+        return invokeRegisteredEffect(this.getSandboxEffectMap(sandboxId), request);
       });
       wsClient.on("open", () => {
         void this.synchronizeEffectHost(host).catch((error) => {
@@ -6596,7 +6847,7 @@ var Granular = class {
   async registerEffect(sandboxNameOrId, effect) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    this.getSandboxEffectMap(sandboxId).set(computeEffectKey(effect), effect);
+    this.getSandboxEffectMap(sandboxId).set(computeEffectKey2(effect), effect);
     await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
@@ -6609,7 +6860,7 @@ var Granular = class {
     const sandboxId = sandbox.sandboxId;
     const map = this.getSandboxEffectMap(sandboxId);
     for (const effect of effects) {
-      map.set(computeEffectKey(effect), effect);
+      map.set(computeEffectKey2(effect), effect);
     }
     await this.syncSandboxEffectCatalog(sandboxId);
   }
@@ -6886,6 +7137,6 @@ var Granular = class {
   }
 };
 
-export { Environment, Granular, Session, WSClient };
+export { Environment, Granular, Session, WSClient, invokeRegisteredEffect, normalizeEffectBehaviors };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map