@granular-software/sdk 0.4.47 → 0.4.48

package/dist/cli/index.js

@@ -5434,7 +5434,9 @@ function resolveEndpointMode(explicitMode) {
   if (explicit === "local" || explicit === "production") {
     return explicit;
   }
-  const envMode = normalizeMode(readEnv("GRANULAR_ENDPOINT_MODE") || readEnv("GRANULAR_ENV"));
+  const envMode = normalizeMode(
+    readEnv("GRANULAR_ENDPOINT_MODE") || readEnv("GRANULAR_ENV")
+  );
   if (envMode === "local" || envMode === "production") {
     return envMode;
   }
@@ -7639,7 +7641,11 @@ function ensureBuiltinPermissionFiles() {
   for (const profile of getBuiltinPermissionProfiles()) {
     const filePath = path3__namespace.join(permissionsDir, `${profile.name}.json`);
     if (!fs__namespace.existsSync(filePath)) {
-      fs__namespace.writeFileSync(filePath, JSON.stringify(profile, null, 2) + "\n", "utf-8");
+      fs__namespace.writeFileSync(
+        filePath,
+        JSON.stringify(profile, null, 2) + "\n",
+        "utf-8"
+      );
     }
   }
 }
@@ -7708,7 +7714,10 @@ function loadApiUrl() {
   if (process.env.GRANULAR_API_URL) return process.env.GRANULAR_API_URL;
   const modeOverride = process.env.GRANULAR_ENDPOINT_MODE;
   if (modeOverride === "local" || modeOverride === "production" || modeOverride === "prod") {
-    return resolveApiUrl(void 0, modeOverride === "prod" ? "production" : modeOverride);
+    return resolveApiUrl(
+      void 0,
+      modeOverride === "prod" ? "production" : modeOverride
+    );
   }
   const rc = readRcFile();
   if (rc.apiUrl) return rc.apiUrl;
@@ -7797,9 +7806,9 @@ var ApiClient = class {
     const response = await fetch(url, {
       ...options,
       headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
+        Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
-        "Connection": "close",
+        Connection: "close",
         ...options.headers
       }
     });
@@ -7908,10 +7917,13 @@ var ApiClient = class {
     }));
   }
   async moveTag(tagId, targetBuildId) {
-    const moved = await this.request(`/control/tags/${tagId}/move`, {
-      method: "POST",
-      body: JSON.stringify({ targetBuildId })
-    });
+    const moved = await this.request(
+      `/control/tags/${tagId}/move`,
+      {
+        method: "POST",
+        body: JSON.stringify({ targetBuildId })
+      }
+    );
     return {
       ...moved,
       targetVersionId: moved.targetVersionId ?? moved.targetBuildId ?? null
@@ -7921,14 +7933,20 @@ var ApiClient = class {
     return this.moveTag(tagId, targetVersionId);
   }
   async promoteToProd(buildId) {
-    return this.request(`/control/builds/${buildId}/promote`, {
-      method: "POST"
-    });
+    return this.request(
+      `/control/builds/${buildId}/promote`,
+      {
+        method: "POST"
+      }
+    );
   }
   async promoteVersionToProd(versionId) {
-    return this.request(`/control/versions/${versionId}/promote`, {
-      method: "POST"
-    });
+    return this.request(
+      `/control/versions/${versionId}/promote`,
+      {
+        method: "POST"
+      }
+    );
   }
   async getBuildDiff(buildId, againstBuildId) {
     const query = againstBuildId ? `?against=${encodeURIComponent(againstBuildId)}` : "";
@@ -7969,10 +7987,14 @@ var ApiClient = class {
       schemaVersion: 1,
       name: data.name
     };
-    const result = await this.syncPermissionProfileSources(sandboxId, [profile]);
+    const result = await this.syncPermissionProfileSources(sandboxId, [
+      profile
+    ]);
     const synced = result.items?.find((item) => item.name === data.name) || result.items?.[0];
     if (!synced) {
-      throw new Error(`Permission profile source sync did not return ${data.name}`);
+      throw new Error(
+        `Permission profile source sync did not return ${data.name}`
+      );
     }
     return synced;
   }
@@ -7989,22 +8011,19 @@ var ApiClient = class {
     });
   }
   async syncPermissionProfileSources(sandboxId, profiles) {
-    return this.request(
-      `/control/sandboxes/${sandboxId}/permission-profile-sources`,
-      {
-        method: "PUT",
-        body: JSON.stringify({ profiles })
-      }
-    );
+    return this.request(`/control/sandboxes/${sandboxId}/permission-profile-sources`, {
+      method: "PUT",
+      body: JSON.stringify({ profiles })
+    });
   }
   async getVersionPolicies(versionId) {
-    return this.request(`/control/ontology-versions/${versionId}/policies`);
-  }
-  async getVersionPermissionProfiles(versionId) {
     return this.request(
-      `/control/ontology-versions/${versionId}/permission-profiles`
+      `/control/ontology-versions/${versionId}/policies`
     );
   }
+  async getVersionPermissionProfiles(versionId) {
+    return this.request(`/control/ontology-versions/${versionId}/permission-profiles`);
+  }
   async evaluateVersionPolicy(versionId, request) {
     return this.request(`/control/builds/${versionId}/policies/evaluate`, {
       method: "POST",
@@ -8094,7 +8113,9 @@ function generateHilbertPath(order = 4, size = 128, radius = 51) {
     const [sqX, sqY] = squareToSquircle(normX, normY);
     points.push([center + sqX * radius, center + sqY * radius]);
   }
-  return points.map(([x, y], i) => `${i === 0 ? "M" : "L"} ${x.toFixed(3)} ${y.toFixed(3)}`).join(" ");
+  return points.map(
+    ([x, y], i) => `${i === 0 ? "M" : "L"} ${x.toFixed(3)} ${y.toFixed(3)}`
+  ).join(" ");
 }
 function renderLogoSvg() {
   const squirclePath = generateSquirclePath();
@@ -8294,7 +8315,11 @@ async function loginWithBrowser(options) {
       const timeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        reject(new Error(`Timed out after ${Math.round(timeoutMs / 1e3)}s waiting for browser authentication.`));
+        reject(
+          new Error(
+            `Timed out after ${Math.round(timeoutMs / 1e3)}s waiting for browser authentication.`
+          )
+        );
       }, timeoutMs);
       server.on("request", (req, res) => {
         const url = new URL(req.url || "/", `http://${CALLBACK_HOST}`);
@@ -8309,7 +8334,13 @@ async function loginWithBrowser(options) {
         if (!returnedState || returnedState !== state) {
           res.statusCode = 400;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
-          res.end(renderHtmlPage("Granular login failed", "State mismatch. Please close this window and retry.", "error"));
+          res.end(
+            renderHtmlPage(
+              "Granular login failed",
+              "State mismatch. Please close this window and retry.",
+              "error"
+            )
+          );
           if (!settled) {
             settled = true;
             clearTimeout(timeout);
@@ -8337,7 +8368,13 @@ async function loginWithBrowser(options) {
         if (!apiKey2) {
           res.statusCode = 400;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
-          res.end(renderHtmlPage("Granular login failed", "No API key was returned. Please retry.", "error"));
+          res.end(
+            renderHtmlPage(
+              "Granular login failed",
+              "No API key was returned. Please retry.",
+              "error"
+            )
+          );
           if (!settled) {
             settled = true;
             clearTimeout(timeout);
@@ -8347,7 +8384,13 @@ async function loginWithBrowser(options) {
         }
         res.statusCode = 200;
         res.setHeader("Content-Type", "text/html; charset=utf-8");
-        res.end(renderHtmlPage("Granular login complete", "Authentication succeeded. You can close this window.", "success"));
+        res.end(
+          renderHtmlPage(
+            "Granular login complete",
+            "Authentication succeeded. You can close this window.",
+            "success"
+          )
+        );
         if (!settled) {
           settled = true;
           clearTimeout(timeout);
@@ -9741,7 +9784,9 @@ function table(headers, rows) {
   }
 }
 function hint(command, description) {
-  console.log(`  ${brand.muted("$")} ${brand.secondary(command)}  ${brand.muted(description)}`);
+  console.log(
+    `  ${brand.muted("$")} ${brand.secondary(command)}  ${brand.muted(description)}`
+  );
 }
 function nextSteps(steps) {
   console.log();
@@ -9875,7 +9920,7 @@ The rest of this guide assumes these terms.
 | **Build run** | The CI-style compilation process. \`granular build\` creates or reuses the ontology version, then runs a build for it. |
 | **Environment** | Return value of \`granular.openEnvironment({ ontology, tag, userId, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`recordObjects\`, \`graphql\`, and \`sessions.create()\`. |
 | **Session** | Live runtime connection opened from an environment with \`environment.sessions.create()\` or \`environment.sessions.connect()\`. Job, prompt, and streaming APIs live here. |
-| **Job** | Code string passed to \`session.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
+| **Job** | Code string passed to \`session.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to Harness v3 imports such as \`@granular/domain/<Class>\` and \`@granular/actions/backend\`. |
 | **Effect** | Declared with \`withEffect\`; **handler** registered in **your** process with \`granular.ontology(sandboxId).effects.registerMany(...)\`. Jobs invoke effects; handlers do IO outside Granular. |
 | **Class** | Entity **kind** in the domain (e.g. \`book\`) with \`has\` fields in the manifest. |
 | **Record / object** | One **instance**: \`className\`, \`id\`, \`fields\`, \`relationships\`. Use \`recordObject\` for one upsert, \`recordObjects\` for several immediate upserts, and record-import APIs for async bulk loads. |
@@ -9900,7 +9945,7 @@ function manifestGuideEndToEndSection() {
 | 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. Use \`recordObject\` for one targeted write. Use \`recordObjects\` for one synchronous multi-record write with chunking (default 100 rows/request), retries, and optional \`onChunkComplete\` / \`concurrency\` progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
 | 6 | \`const session = await environment.sessions.create();\` then \`session.submitJob(\`\u2026\`)\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
-**Accuracy tip:** After changing the manifest, always **re-build** before assuming generated types, \`./sandbox-tools\` names, or effect signatures match the file on disk.`;
+**Accuracy tip:** After changing the manifest, always **re-build** before assuming generated Harness v3 imports, generated types, or effect signatures match the file on disk.`;
 }
 function sandboxDocMainConceptsSection() {
   return `## Main concepts (recap)
@@ -9914,7 +9959,7 @@ function sandboxDocMainConceptsSection() {
 | **Build run** | Compilation run that validates and materializes a version. |
 | **Environment** | \`openEnvironment()\` result \u2014 **record**, **recordObjects**, **graphql**, and **session lifecycle** for this sandbox. |
 | **Session** | Live runtime connection created from an environment; job and prompt APIs live here. |
-| **Job** | \`session.submitJob(...)\` code using \`./sandbox-tools\`. |
+| **Job** | \`session.submitJob(...)\` code using Harness v3 runtime imports. |
 | **Effect** | Declared in manifest; **handler** in your process. |
 
 **Full product + manifest how-to:** [docs/granular-manifest.md](docs/granular-manifest.md).`;
@@ -14126,6 +14171,9 @@ external_exports.object({
       mode: external_exports.string().optional()
     }).strict()
   ]).optional(),
+  access: external_exports.enum(["read", "write", "ui"]).optional(),
+  effectKind: external_exports.enum(["read", "write", "ui"]).optional(),
+  sideEffect: external_exports.enum(["read", "write", "ui", "readonly", "read_only"]).optional(),
   policies: PoliciesSchema.optional()
 }).strict();
 
@@ -14585,7 +14633,12 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
                 description
               })
             );
-            return { model, kind: "dry_run", enabled: finalEnabled, description };
+            return {
+              model,
+              kind: "dry_run",
+              enabled: finalEnabled,
+              description
+            };
           },
           set_reverse: async (ant, { handler, description }) => {
             const model = await run(
@@ -14631,7 +14684,10 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
     applyToMethodIR(methodIR, methodSummary) {
       return {
         ...methodIR,
-        docs: [...methodIR.docs, ...buildEffectBehaviorDocs(methodSummary.effectBehaviors)]
+        docs: [
+          ...methodIR.docs,
+          ...buildEffectBehaviorDocs(methodSummary.effectBehaviors)
+        ]
       };
     }
   }
@@ -14895,7 +14951,9 @@ var filterByMetamodelPackage = defineMetamodelPackage({
 
 // ../metamodel-note/src/index.ts
 function noteTexts(values) {
-  return (values || []).map((item) => item?.text).filter((value) => typeof value === "string" && value.length > 0);
+  return (values || []).map((item) => item?.text).filter(
+    (value) => typeof value === "string" && value.length > 0
+  );
 }
 function buildNoteMutations(targetPath, notes) {
   return normalizeNotesInput(notes).map((note) => ({
@@ -14925,7 +14983,10 @@ var noteMetamodelPackage = defineMetamodelPackage({
   id: "note",
   docs: {
     fieldRows: [
-      { key: "note", description: "Advisory text attached to a field. Accepts a string or string array." }
+      {
+        key: "note",
+        description: "Advisory text attached to a field. Accepts a string or string array."
+      }
     ],
     modelRows: [
       { key: "note", description: "Advisory text on the class/model itself." }
@@ -15065,7 +15126,9 @@ function buildRequiredFieldMutations(fieldPath, required) {
 var requiredMetamodelPackage = defineMetamodelPackage({
   id: "required",
   docs: {
-    fieldRows: [{ key: "required", description: "Marks the field as required." }]
+    fieldRows: [
+      { key: "required", description: "Marks the field as required." }
+    ]
   },
   graphql: {
     typeDefs: [
@@ -15123,7 +15186,10 @@ var requiredMetamodelPackage = defineMetamodelPackage({
       if (!propertySummary.required) return propertyIR;
       return {
         ...propertyIR,
-        docs: [...propertyIR.docs, propertySummary.required.message || "Required."]
+        docs: [
+          ...propertyIR.docs,
+          propertySummary.required.message || "Required."
+        ]
       };
     }
   }
@@ -15274,7 +15340,10 @@ function normalizeStateDefinitions(machine) {
   const states = /* @__PURE__ */ new Map();
   for (const rawState of machine.states || []) {
     if (typeof rawState === "string") {
-      states.set(rawState, { name: rawState, isFinal: finalStates.has(rawState) });
+      states.set(rawState, {
+        name: rawState,
+        isFinal: finalStates.has(rawState)
+      });
       continue;
     }
     states.set(rawState.name, {
@@ -15362,7 +15431,9 @@ function buildMachineMethods(classSummary, machine) {
     },
     {
       name: `reach_${machine.name}`,
-      docs: [`Reach a ${docsPrefix} state through the shortest allowed transition path.`],
+      docs: [
+        `Reach a ${docsPrefix} state through the shortest allowed transition path.`
+      ],
       static: false,
       params: [{ name: "target", type: stateName }],
       returnType: `Promise<${toPascalCase2(classSummary.name)}>`,
@@ -15422,7 +15493,9 @@ function buildMachineMethods(classSummary, machine) {
     },
     {
       name: `paths_to_${machine.name}`,
-      docs: [`List shortest transition paths from the current ${docsPrefix} state to a target state.`],
+      docs: [
+        `List shortest transition paths from the current ${docsPrefix} state to a target state.`
+      ],
       static: false,
       params: [{ name: "target", type: stateName }],
       returnType: `Promise<Array<{ states: ${stateName}[]; transitions: ${transitionName}[] }>>`,
@@ -15555,22 +15628,39 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           name: (value) => value.name,
           state_machine: async (value) => await run(value.target.state_machine(value.name)),
           add_state: async (value, { name, is_final }) => {
-            await run(value.target.add_state_machine_state(value.name, name, is_final ?? false));
+            await run(
+              value.target.add_state_machine_state(
+                value.name,
+                name,
+                is_final ?? false
+              )
+            );
             return value;
           },
           add_transition: async (value, { name, from, to }) => {
-            await run(value.target.add_state_machine_transition(value.name, name, from, to));
+            await run(
+              value.target.add_state_machine_transition(
+                value.name,
+                name,
+                from,
+                to
+              )
+            );
             return value;
           },
           activate_transition: async (value, { name }) => {
-            await run(value.target.activate_state_machine_transition(value.name, name));
+            await run(
+              value.target.activate_state_machine_transition(value.name, name)
+            );
             return value;
           }
         },
         StateMachineSnapshotMutation: {
           snapshot: async (value) => await run(value.target.state_machine(value.name)),
           activate_transition: async (value, { name }) => {
-            await run(value.target.activate_state_machine_transition(value.name, name));
+            await run(
+              value.target.activate_state_machine_transition(value.name, name)
+            );
             return value;
           }
         },
@@ -15601,7 +15691,11 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           reachable_states: (value) => value.reachable_states,
           is_final: (value) => value.is_final,
           history: (value) => value.history,
-          paths_to: async (value, { state }) => await stateMachines.pathsToState(value.model.target || value.model, value.name, state)
+          paths_to: async (value, { state }) => await stateMachines.pathsToState(
+            value.model.target || value.model,
+            value.name,
+            state
+          )
         },
         StateMachine: {
           name: (value) => value.name,
@@ -15614,8 +15708,16 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           reachable_states: (value) => value.reachable_states,
           is_final: (value) => value.is_final,
           history: (value) => value.history,
-          paths_to: async (value, { state }) => await stateMachines.pathsToState(value.model.target || value.model, value.name, state),
-          instances_in_state: async (value, { state }) => await stateMachines.instancesInState(value.model.target || value.model, value.name, state)
+          paths_to: async (value, { state }) => await stateMachines.pathsToState(
+            value.model.target || value.model,
+            value.name,
+            state
+          ),
+          instances_in_state: async (value, { state }) => await stateMachines.instancesInState(
+            value.model.target || value.model,
+            value.name,
+            state
+          )
         }
       };
     }
@@ -15659,9 +15761,12 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
 // ../metamodel-validation-rule/src/index.ts
 function describeRule(rule) {
   if (rule.message) return rule.message;
-  if (rule.stringValue !== void 0) return `${rule.operator} ${JSON.stringify(rule.stringValue)}`;
-  if (rule.numberValue !== void 0) return `${rule.operator} ${rule.numberValue}`;
-  if (rule.booleanValue !== void 0) return `${rule.operator} ${String(rule.booleanValue)}`;
+  if (rule.stringValue !== void 0)
+    return `${rule.operator} ${JSON.stringify(rule.stringValue)}`;
+  if (rule.numberValue !== void 0)
+    return `${rule.operator} ${rule.numberValue}`;
+  if (rule.booleanValue !== void 0)
+    return `${rule.operator} ${String(rule.booleanValue)}`;
   return rule.operator;
 }
 function normalizeRule(rule) {
@@ -15787,10 +15892,14 @@ var validationRuleMetamodelPackage = defineMetamodelPackage({
   },
   summary: {
     selections: {
-      propertyFields: [`validation_rules { operator string_value number_value boolean_value message }`]
+      propertyFields: [
+        `validation_rules { operator string_value number_value boolean_value message }`
+      ]
     },
     readPropertySummary(rawProperty) {
-      const rules = Array.isArray(rawProperty.validation_rules) ? rawProperty.validation_rules.map(normalizeRule).filter((rule) => Boolean(rule)) : [];
+      const rules = Array.isArray(rawProperty.validation_rules) ? rawProperty.validation_rules.map(normalizeRule).filter(
+        (rule) => Boolean(rule)
+      ) : [];
       return {
         validationRules: rules
       };
@@ -16323,7 +16432,7 @@ ${effectMetamodelTable}
 
 | API | Purpose |
 |-----|---------|
-| \`submitJob(code)\` | Run code in the sandbox; import from \`./sandbox-tools\`. |
+| \`submitJob(code)\` | Run code in the sandbox; import generated classes from \`@granular/domain/<Class>\` and actions from \`@granular/actions/backend\` or \`@granular/actions/frontend\`. |
 | \`answerPrompt(...)\`, \`appendMessage(...)\` | Human-in-the-loop and conversation APIs. |
 | \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
 | \`getEffects()\` / \`getTools()\`, \`session.on("effects:changed", ...)\` | Effect catalog and live updates. |
@@ -16656,7 +16765,7 @@ function generateSandboxAgentDoc(manifest, meta) {
     "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.ontology('" + meta.sandboxId + "').effects.registerMany([...])` in your host process (see `granular-effects.ts` in starter projects)."
   );
   lines.push(
-    "3. **Invoke** from sandbox code via `./sandbox-tools` inside `submitJob`; the handler you registered runs in your process and the result returns to the job."
+    "3. **Invoke** from sandbox code via Harness v3 runtime imports inside `submitJob`; the handler you registered runs in your process and the result returns to the job."
   );
   lines.push("");
   lines.push(
@@ -16713,7 +16822,7 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("## `submitJob` / sandbox code");
   lines.push("");
   lines.push(
-    "Jobs run in the sandbox with generated classes from `./sandbox-tools`. Class names are PascalCase."
+    "Jobs run in the sandbox with generated classes from `@granular/domain/<Class>` and global backend actions from `@granular/actions/backend`. Class names are PascalCase."
   );
   lines.push("");
   const pascalImports = classes.map((c) => toPascalCase(c.name));
@@ -16723,13 +16832,20 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("```typescript");
   lines.push(`const session = await env.sessions.create();
 const job = await session.submitJob(\``);
-  const importList = [...pascalImports, ...effectNames].filter(
-    (v, i, a) => a.indexOf(v) === i
-  );
-  if (importList.length > 0) {
-    lines.push(`  import { ${importList.join(", ")} } from './sandbox-tools';`);
+  if (pascalImports.length > 0) {
+    for (const name of pascalImports) {
+      lines.push(`  import { ${name} } from "@granular/domain/${name}";`);
+    }
+  }
+  if (effectNames.length > 0) {
+    lines.push(
+      `  import { ${effectNames.join(", ")} } from "@granular/actions/backend";`
+    );
+  }
+  if (pascalImports.length === 0 && effectNames.length === 0) {
+    lines.push(`  // import generated classes from @granular/domain/<Class>`);
   } else {
-    lines.push(`  // import generated classes/tools from './sandbox-tools'`);
+    lines.push(`  // import user-facing helpers from @granular/agent when needed`);
   }
   lines.push("");
   if (classes.length > 0) {
@@ -16817,7 +16933,10 @@ const job = await session.submitJob(\``);
   lines.push("");
   return lines.join("\n");
 }
-var MANIFEST_GUIDE_RELATIVE = path3__namespace.join("docs", "granular-manifest.md");
+var MANIFEST_GUIDE_RELATIVE = path3__namespace.join(
+  "docs",
+  "granular-manifest.md"
+);
 var SANDBOX_DOC_FILENAME = "GRANULAR_SANDBOX.md";
 function getAgentsMdPath(projectRoot) {
   return path3__namespace.join(projectRoot, "AGENTS.md");
@@ -16839,7 +16958,9 @@ function writeManifestGuideFile(projectRoot, projectName) {
 }
 function writeAgentsMdFile(projectRoot) {
   const agentsPath = getAgentsMdPath(projectRoot);
-  const block = generateGranularAgentsBlock({ manifestGuidePath: MANIFEST_GUIDE_RELATIVE.replace(/\\/g, "/") });
+  const block = generateGranularAgentsBlock({
+    manifestGuidePath: MANIFEST_GUIDE_RELATIVE.replace(/\\/g, "/")
+  });
   const previous = fs__namespace.existsSync(agentsPath) ? fs__namespace.readFileSync(agentsPath, "utf-8") : "";
   const merged = mergeGranularAgentsBlock(previous, block);
   fs__namespace.writeFileSync(agentsPath, merged, "utf-8");
@@ -18077,7 +18198,10 @@ async function initCommand(projectName, options) {
 }
 var DEFAULT_LOCAL_API_KEY2 = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function promptSecret(question) {
-  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
   return new Promise((resolve2) => {
     rl.question(`  ${question}: `, (answer) => {
       rl.close();
@@ -18089,7 +18213,10 @@ function waitForEnter2(message) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     return Promise.resolve();
   }
-  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
   return new Promise((resolve2) => {
     rl.question(`  ${message}`, () => {
       rl.close();
@@ -18119,14 +18246,20 @@ async function loginCommand(options = {}) {
       apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY2;
       info("Using local Granular API key for localhost development.");
     } else if (options.manual) {
-      dim("Get your API key at https://app.granular.software/w/default/api-keys");
+      dim(
+        "Get your API key at https://app.granular.software/w/default/api-keys"
+      );
       console.log();
       apiKey = await promptSecret("Enter your API key");
     } else {
       const timeoutMs = options.timeout && options.timeout > 0 ? options.timeout * 1e3 : void 0;
-      await waitForEnter2("Press Enter to open the login page in your browser...");
+      await waitForEnter2(
+        "Press Enter to open the login page in your browser..."
+      );
       console.log();
-      const waiting = spinner("Opening browser and waiting for authentication...");
+      const waiting = spinner(
+        "Opening browser and waiting for authentication..."
+      );
       try {
         apiKey = await loginWithBrowser({
           authBaseUrl: loadAuthUrl(),
@@ -18144,7 +18277,9 @@ async function loginCommand(options = {}) {
         waiting.succeed("  Browser authentication completed.");
       } catch (err) {
         waiting.fail(`  Browser authentication failed: ${err.message}`);
-        dim("Retry with `granular login --manual` to paste an API key directly.");
+        dim(
+          "Retry with `granular login --manual` to paste an API key directly."
+        );
         process.exit(1);
       }
     }
@@ -18154,7 +18289,9 @@ async function loginCommand(options = {}) {
     process.exit(1);
   }
   if (!apiKey.startsWith("sk_") && !apiKey.startsWith("gn_sk_")) {
-    warn("API key does not look like a recognized Granular/WorkOS key. Continuing anyway...");
+    warn(
+      "API key does not look like a recognized Granular/WorkOS key. Continuing anyway..."
+    );
   }
   const spinner2 = spinner("Validating...");
   const api = new ApiClient(apiKey, apiUrl);
@@ -18171,12 +18308,7 @@ async function loginCommand(options = {}) {
   console.log();
 }
 function cleanPermissionProfile(profile) {
-  const {
-    source,
-    sourcePath,
-    defaultsOwnerName,
-    ...rest
-  } = profile;
+  const { source, sourcePath, defaultsOwnerName, ...rest } = profile;
   return rest;
 }
 function writePermissionProfileFiles(profiles) {
@@ -18221,14 +18353,16 @@ async function pullCommand(versionId) {
     writeManifestFile(project);
     spin.text = "  Downloading permission profile files...";
     const profileVersions = await api.getVersionPermissionProfiles(versionId);
-    const pulledProfiles = (profileVersions.items || []).map((item) => item.profile).filter((profile) => Boolean(profile?.name));
+    const pulledProfiles = (profileVersions.items || []).map((item) => item.profile).filter(
+      (profile) => Boolean(profile?.name)
+    );
     const writtenProfiles = writePermissionProfileFiles(pulledProfiles);
     spin.succeed("  Manifest pulled successfully.");
     console.log();
     keyValue({
       "Manifest ID": full.manifestId,
       "Source Version": versionId,
-      "Version": targetVersionLabel,
+      Version: targetVersionLabel,
       "Written to": "granular.json",
       "Permission profiles": writtenProfiles.length > 0 ? writtenProfiles.join(", ") : "none"
     });
@@ -18263,32 +18397,51 @@ async function buildCommand() {
     }
     process.exit(1);
   }
-  const syncingProfiles = spinner(`Syncing ${permissionProfiles.length} permission profile file(s)...`);
+  const syncingProfiles = spinner(
+    `Syncing ${permissionProfiles.length} permission profile file(s)...`
+  );
   try {
-    const result = await api.syncPermissionProfileSources(config.sandboxId, permissionProfiles);
-    syncingProfiles.succeed(`  Permission profiles synced: ${brand.secondary(result.digest)}`);
+    const result = await api.syncPermissionProfileSources(
+      config.sandboxId,
+      permissionProfiles
+    );
+    syncingProfiles.succeed(
+      `  Permission profiles synced: ${brand.secondary(result.digest)}`
+    );
   } catch (err) {
-    syncingProfiles.fail(`  Failed to sync permission profiles: ${err.message}`);
+    syncingProfiles.fail(
+      `  Failed to sync permission profiles: ${err.message}`
+    );
     process.exit(1);
   }
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
   let uploadedManifest;
   try {
     uploadedManifest = await api.uploadManifest(config.sandboxId, manifest);
-    uploading.succeed(`  Manifest uploaded: ${brand.secondary(uploadedManifest.manifestId)}`);
+    uploading.succeed(
+      `  Manifest uploaded: ${brand.secondary(uploadedManifest.manifestId)}`
+    );
   } catch (err) {
     uploading.fail(`  Failed to upload manifest: ${err.message}`);
     process.exit(1);
   }
-  const building = spinner("Creating or reusing ontology version from manifest...");
+  const building = spinner(
+    "Creating or reusing ontology version from manifest..."
+  );
   try {
-    const version2 = await api.createVersion(config.sandboxId, uploadedManifest.manifestId);
+    const version2 = await api.createVersion(
+      config.sandboxId,
+      uploadedManifest.manifestId
+    );
     building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
     const startTime = Date.now();
-    const completed = await api.waitForVersionBuild(version2.buildId, (status) => {
-      const elapsed = Math.round((Date.now() - startTime) / 1e3);
-      building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
-    });
+    const completed = await api.waitForVersionBuild(
+      version2.buildId,
+      (status) => {
+        const elapsed = Math.round((Date.now() - startTime) / 1e3);
+        building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
+      }
+    );
     const totalTime = Math.round((Date.now() - startTime) / 1e3);
     building.succeed(`  Version ready in ${totalTime}s`);
     const [tags, diff] = await Promise.all([
@@ -18308,11 +18461,11 @@ async function buildCommand() {
       "Version ID": completed.buildId,
       "Version Number": completed.versionNumber != null ? String(completed.versionNumber) : "N/A",
       "Build Run": completed.buildRunId || completed.latestBuildRunId || "N/A",
-      "Manifest": uploadedManifest.manifestId,
-      "Result": completed.createdNewVersion ? "new version created" : "existing version reused, new build run recorded",
+      Manifest: uploadedManifest.manifestId,
+      Result: completed.createdNewVersion ? "new version created" : "existing version reused, new build run recorded",
       "Dev Tag": devTag?.targetVersionId === completed.buildId || devTag?.targetBuildId === completed.buildId ? "updated to this version" : devTag?.targetVersionId || devTag?.targetBuildId || "not set",
       "Prod Tag": prodTag?.targetVersionId || prodTag?.targetBuildId || "not set",
-      "Duration": `${totalTime}s`,
+      Duration: `${totalTime}s`,
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
     if (diff?.diff?.summary) {
@@ -18325,7 +18478,9 @@ async function buildCommand() {
       });
     }
     console.log();
-    info("Common path: keep working in your dev environment while dev follows the newest successful version. Prod only changes when you promote it.");
+    info(
+      "Common path: keep working in your dev environment while dev follows the newest successful version. Prod only changes when you promote it."
+    );
     console.log();
   } catch (err) {
     building.fail(`  Build failed: ${err.message}`);
@@ -18342,7 +18497,10 @@ async function deployCommand(options = {}) {
     process.exit(1);
   }
   const api = new ApiClient(config.apiKey, config.apiUrl);
-  step(options.prod ? "Deploy to dev and prod" : "Deploy to dev", `Sandbox ${config.sandboxId}`);
+  step(
+    options.prod ? "Deploy to dev and prod" : "Deploy to dev",
+    `Sandbox ${config.sandboxId}`
+  );
   console.log();
   const manifest = config.project.manifest;
   const permissionProfiles = readPermissionProfileFiles();
@@ -18356,19 +18514,30 @@ async function deployCommand(options = {}) {
     for (const error2 of localPolicyValidation.errors) error(`  ${error2}`);
     process.exit(1);
   }
-  const syncingProfiles = spinner(`Syncing ${permissionProfiles.length} permission profile file(s)...`);
+  const syncingProfiles = spinner(
+    `Syncing ${permissionProfiles.length} permission profile file(s)...`
+  );
   try {
-    const result = await api.syncPermissionProfileSources(config.sandboxId, permissionProfiles);
-    syncingProfiles.succeed(`  Permission profiles synced: ${brand.secondary(result.digest)}`);
+    const result = await api.syncPermissionProfileSources(
+      config.sandboxId,
+      permissionProfiles
+    );
+    syncingProfiles.succeed(
+      `  Permission profiles synced: ${brand.secondary(result.digest)}`
+    );
   } catch (err) {
-    syncingProfiles.fail(`  Failed to sync permission profiles: ${err.message}`);
+    syncingProfiles.fail(
+      `  Failed to sync permission profiles: ${err.message}`
+    );
     process.exit(1);
   }
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
   let uploadedManifest;
   try {
     uploadedManifest = await api.uploadManifest(config.sandboxId, manifest);
-    uploading.succeed(`  Manifest uploaded: ${brand.secondary(uploadedManifest.manifestId)}`);
+    uploading.succeed(
+      `  Manifest uploaded: ${brand.secondary(uploadedManifest.manifestId)}`
+    );
   } catch (err) {
     uploading.fail(`  Failed to upload manifest: ${err.message}`);
     process.exit(1);
@@ -18381,7 +18550,9 @@ async function deployCommand(options = {}) {
     ]);
     const devTag = tags.find((tag2) => tag2.name === "dev");
     const prodTag = tags.find((tag2) => tag2.name === "prod");
-    const existingVersion = versions.find((version2) => version2.manifestDigest === uploadedManifest.digest) || null;
+    const existingVersion = versions.find(
+      (version2) => version2.manifestDigest === uploadedManifest.digest
+    ) || null;
     const existingVersionId = existingVersion?.buildId || null;
     const devVersionId = devTag?.targetVersionId || devTag?.targetBuildId || null;
     const reuseDevPromotion = Boolean(
@@ -18391,9 +18562,14 @@ async function deployCommand(options = {}) {
     let totalTime = 0;
     let deployedToDev = false;
     if (reuseDevPromotion) {
-      building.succeed(`  Current manifest already matches ${brand.secondary(existingVersionId)} on dev.`);
+      building.succeed(
+        `  Current manifest already matches ${brand.secondary(existingVersionId)} on dev.`
+      );
     } else {
-      const version2 = await api.createVersion(config.sandboxId, uploadedManifest.manifestId);
+      const version2 = await api.createVersion(
+        config.sandboxId,
+        uploadedManifest.manifestId
+      );
       const startTime = Date.now();
       building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
       completed = await api.waitForVersionBuild(version2.buildId, (status) => {
@@ -18402,7 +18578,9 @@ async function deployCommand(options = {}) {
       });
       totalTime = Math.round((Date.now() - startTime) / 1e3);
       deployedToDev = true;
-      building.succeed(`  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`);
+      building.succeed(
+        `  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`
+      );
     }
     if (!completed) {
       throw new Error("Could not resolve the current ontology version.");
@@ -18410,7 +18588,9 @@ async function deployCommand(options = {}) {
     if (options.prod) {
       const promoting = spinner("Promoting prod...");
       await api.promoteVersionToProd(completed.buildId);
-      promoting.succeed(`  Prod now points to ${brand.secondary(completed.buildId)}`);
+      promoting.succeed(
+        `  Prod now points to ${brand.secondary(completed.buildId)}`
+      );
     }
     writeSandboxAgentDocFile(getProjectRoot(), manifest, {
       sandboxId: config.sandboxId,
@@ -18422,18 +18602,20 @@ async function deployCommand(options = {}) {
     success(`Deployed ${brand.bold(manifest.name)} successfully!`);
     console.log();
     keyValue({
-      "Version": completed.buildId,
+      Version: completed.buildId,
       "Version Number": completed.versionNumber != null ? String(completed.versionNumber) : "N/A",
       "Build Run": completed.buildRunId || completed.latestBuildRunId || "N/A",
-      "Manifest": uploadedManifest.manifestId,
+      Manifest: uploadedManifest.manifestId,
       "Dev Tag": completed.buildId,
       "Prod Tag": options.prod ? completed.buildId : prodTag?.targetVersionId || prodTag?.targetBuildId || "unchanged",
-      "Release": options.prod ? deployedToDev ? "dev and prod now point to this version" : "prod promoted to the version already on dev" : "dev updated to this version",
+      Release: options.prod ? deployedToDev ? "dev and prod now point to this version" : "prod promoted to the version already on dev" : "dev updated to this version",
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
     console.log();
     if (options.prod) {
-      info("Existing prod environments keep their current version until they are transitioned.");
+      info(
+        "Existing prod environments keep their current version until they are transitioned."
+      );
       console.log();
     }
   } catch (err) {
@@ -18445,7 +18627,9 @@ async function deployCommand(options = {}) {
 // src/cli/commands/status.ts
 function summarizeLocalManifest(project) {
   const manifest = project.manifest;
-  const classCount = manifest.volumes.flatMap((volume) => volume.operations).filter((operation) => operation.create && !operation.defineRelationship).length;
+  const classCount = manifest.volumes.flatMap((volume) => volume.operations).filter(
+    (operation) => operation.create && !operation.defineRelationship
+  ).length;
   const relationshipCount = manifest.volumes.flatMap((volume) => volume.operations).filter((operation) => operation.defineRelationship).length;
   return {
     name: manifest.name,
@@ -18515,8 +18699,8 @@ async function statusCommand(options = {}) {
     console.log();
     keyValue({
       "Sandbox ID": sandbox.sandboxId,
-      "Name": sandbox.name,
-      "Created": sandbox.createdAt
+      Name: sandbox.name,
+      Created: sandbox.createdAt
     });
     console.log();
     keyValue({
@@ -18557,9 +18741,9 @@ async function statusCommand(options = {}) {
       step("Local Manifest", `granular.json`);
       console.log();
       keyValue({
-        "Name": payload.localManifest.name,
-        "Classes": payload.localManifest.classCount,
-        "Relationships": payload.localManifest.relationshipCount
+        Name: payload.localManifest.name,
+        Classes: payload.localManifest.classCount,
+        Relationships: payload.localManifest.relationshipCount
       });
     }
     if (options.verbose) {
@@ -18580,7 +18764,10 @@ async function statusCommand(options = {}) {
   }
 }
 function prompt2(question, defaultValue) {
-  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline__namespace.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
   const suffix = defaultValue ? ` ${brand.muted(`(${defaultValue})`)}` : "";
   return new Promise((resolve2) => {
     rl.question(`  ${question}${suffix}: `, (answer) => {
@@ -18616,7 +18803,10 @@ async function addClassCommand(name) {
     const fieldName = await prompt2("Field name (leave empty to finish)");
     if (!fieldName) break;
     const fieldType = await prompt2("Type", "string");
-    const description = await prompt2("Description", `${fieldName} of the ${name}`);
+    const description = await prompt2(
+      "Description",
+      `${fieldName} of the ${name}`
+    );
     fields[fieldName] = {
       type: fieldType,
       description
@@ -18635,9 +18825,7 @@ async function addClassCommand(name) {
     manifest.volumes.push({
       name: "schema",
       scope: "sandbox",
-      imports: [
-        { alias: "@std", name: "standard_modules", label: "prod" }
-      ],
+      imports: [{ alias: "@std", name: "standard_modules", label: "prod" }],
       operations: []
     });
   }
@@ -18647,7 +18835,10 @@ async function addClassCommand(name) {
   success(`Class ${brand.bold(name)} added to granular.json`);
   dim(`${Object.keys(fields).length} field(s) defined`);
   nextSteps([
-    { command: `granular add field ${name} <field>`, description: "Add more fields" },
+    {
+      command: `granular add field ${name} <field>`,
+      description: "Add more fields"
+    },
     { command: "granular add relation", description: "Define a relationship" },
     { command: "granular build", description: "Build your changes" }
   ]);
@@ -18672,14 +18863,19 @@ async function addFieldCommand(className, fieldName) {
     process.exit(1);
   }
   const fieldType = await prompt2("Type", "string");
-  const description = await prompt2("Description", `${fieldName} of the ${className}`);
+  const description = await prompt2(
+    "Description",
+    `${fieldName} of the ${className}`
+  );
   if (!classOp.has) classOp.has = {};
   classOp.has[fieldName] = {
     type: fieldType,
     description
   };
   writeManifestFile(project);
-  success(`Field ${brand.bold(fieldName)} (${fieldType}) added to ${brand.bold(className)}`);
+  success(
+    `Field ${brand.bold(fieldName)} (${fieldType}) added to ${brand.bold(className)}`
+  );
   nextSteps([
     { command: "granular build", description: "Build your changes" }
   ]);
@@ -18708,10 +18904,19 @@ async function addRelationCommand() {
     error(`Class "${right}" not found.`);
     process.exit(1);
   }
-  const leftSubmodel = await prompt2(`${left}'s reference to ${right} (plural)`, `${right}s`);
+  const leftSubmodel = await prompt2(
+    `${left}'s reference to ${right} (plural)`,
+    `${right}s`
+  );
   const rightSubmodel = await prompt2(`${right}'s reference to ${left}`, left);
-  const leftIsMany = await confirm2(`Can a ${left} have multiple ${leftSubmodel}?`, true);
-  const rightIsMany = await confirm2(`Can a ${right} have multiple ${rightSubmodel}?`, false);
+  const leftIsMany = await confirm2(
+    `Can a ${left} have multiple ${leftSubmodel}?`,
+    true
+  );
+  const rightIsMany = await confirm2(
+    `Can a ${right} have multiple ${rightSubmodel}?`,
+    false
+  );
   const operation = {
     defineRelationship: {
       left,
@@ -18725,8 +18930,12 @@ async function addRelationCommand() {
   manifest.volumes[0].operations.push(operation);
   writeManifestFile(project);
   console.log();
-  success(`Relationship defined: ${brand.bold(left)} \u2194 ${brand.bold(right)}`);
-  dim(`${left}.${leftSubmodel} (${leftIsMany ? "many" : "one"}) \u2194 ${right}.${rightSubmodel} (${rightIsMany ? "many" : "one"})`);
+  success(
+    `Relationship defined: ${brand.bold(left)} \u2194 ${brand.bold(right)}`
+  );
+  dim(
+    `${left}.${leftSubmodel} (${leftIsMany ? "many" : "one"}) \u2194 ${right}.${rightSubmodel} (${rightIsMany ? "many" : "one"})`
+  );
   nextSteps([
     { command: "granular build", description: "Build your changes" }
   ]);
@@ -18760,7 +18969,7 @@ async function whoamiCommand() {
     try {
       const sandbox = await api.getSandbox(rc.sandboxId);
       keyValue({
-        "Sandbox": sandbox.name || sandbox.sandboxId,
+        Sandbox: sandbox.name || sandbox.sandboxId,
         "Sandbox ID": sandbox.sandboxId,
         "API URL": config.apiUrl
       });
@@ -18802,16 +19011,24 @@ async function devCommand() {
         return;
       }
       const spin = spinner("Uploading manifest...");
-      const uploaded = await api.uploadManifest(config.sandboxId, project.manifest);
+      const uploaded = await api.uploadManifest(
+        config.sandboxId,
+        project.manifest
+      );
       spin.text = "  Building...";
-      const build = await api.triggerBuild(config.sandboxId, uploaded.manifestId);
+      const build = await api.triggerBuild(
+        config.sandboxId,
+        uploaded.manifestId
+      );
       const startTime = Date.now();
       const completed = await api.waitForBuild(build.buildId, (status) => {
         const elapsed = Math.round((Date.now() - startTime) / 1e3);
         spin.text = `  Building... ${brand.muted(`${status} (${elapsed}s)`)}`;
       });
       const totalTime = Math.round((Date.now() - startTime) / 1e3);
-      spin.succeed(`  Build completed in ${totalTime}s \u2014 ${brand.secondary(completed.buildId)}`);
+      spin.succeed(
+        `  Build completed in ${totalTime}s \u2014 ${brand.secondary(completed.buildId)}`
+      );
       writeSandboxAgentDocFile(getProjectRoot(), project.manifest, {
         sandboxId: config.sandboxId,
         apiUrl: config.apiUrl,
@@ -18860,7 +19077,9 @@ async function documentCommand() {
     buildPending: true
   });
   spinner2.succeed(`Generated ${brand.bold("GRANULAR_SANDBOX.md")}`);
-  info("This file lists classes, relationships, and effects from granular.json. After a successful build, run again or use `granular build` to fill in manifest and build ids.");
+  info(
+    "This file lists classes, relationships, and effects from granular.json. After a successful build, run again or use `granular build` to fill in manifest and build ids."
+  );
 }
 var SIMULATOR_BASE = "https://app.granular.software/simulator";
 function openUrl(url) {
@@ -18871,7 +19090,9 @@ function openUrl(url) {
 async function simulateCommand(sandboxIdArg, options) {
   const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
   if (!sandboxId) {
-    error("No ontology ID. Run from a project with `granular init` or pass one explicitly: granular simulate <ontology-id>");
+    error(
+      "No ontology ID. Run from a project with `granular init` or pass one explicitly: granular simulate <ontology-id>"
+    );
     process.exit(1);
   }
   const params = new URLSearchParams({
@@ -18909,6 +19130,7 @@ var DEBUG_WS = process.env.GRANULAR_DEBUG_WS === "1";
 var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
 var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
+var HARNESS_RUN_RPC_TIMEOUT_MS = 6e5;
 var DEFAULT_RECONNECT_DELAY_MS = 3e3;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
 function debugWs(...args) {
@@ -18925,6 +19147,8 @@ function rpcTimeoutMsForMethod(method) {
     case "effects.publishCatalog":
     case "effects.refresh":
       return EFFECT_CONTROL_RPC_TIMEOUT_MS;
+    case "harness.run":
+      return HARNESS_RUN_RPC_TIMEOUT_MS;
     default:
       return DEFAULT_RPC_TIMEOUT_MS;
   }
@@ -19590,7 +19814,9 @@ function scorePromptChoiceMatch(answer, answerTokens, option) {
   const choice = normalizePromptChoiceOption(option);
   const { value, label } = choice;
   const description = choice.description || "";
-  const haystack = normalizePromptText([value, label, description].filter(Boolean).join(" "));
+  const haystack = normalizePromptText(
+    [value, label, description].filter(Boolean).join(" ")
+  );
   if (!haystack) return { score: 0, resolvedValue: value || label || null };
   let score = 0;
   if (value && normalizePromptText(value) === answer) score += 12;
@@ -19600,7 +19826,8 @@ function scorePromptChoiceMatch(answer, answerTokens, option) {
   for (const token of answerTokens) {
     if (value && normalizePromptText(value).includes(token)) score += 10;
     if (label && normalizePromptText(label).includes(token)) score += 8;
-    if (description && normalizePromptText(description).includes(token)) score += 5;
+    if (description && normalizePromptText(description).includes(token))
+      score += 5;
   }
   return { score, resolvedValue: value || label || null };
 }
@@ -19610,7 +19837,8 @@ function normalizePromptType(raw) {
   const promptType = typeof raw?.promptType === "string" ? raw.promptType : null;
   if (type === "confirm" || type === "choice" || type === "input") return type;
   if (kind === "confirm" || kind === "choice" || kind === "input") return kind;
-  if (promptType === "confirm" || promptType === "choice" || promptType === "input") return promptType;
+  if (promptType === "confirm" || promptType === "choice" || promptType === "input")
+    return promptType;
   return "input";
 }
 function normalizePrompt(rawValue) {
@@ -19626,7 +19854,9 @@ function normalizePrompt(rawValue) {
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
     options: Array.isArray(source.options) ? source.options.map(
-      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(option) : option
+      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(
+        option
+      ) : option
     ) : void 0,
     defaultValue: source.defaultValue,
     placeholder: typeof source.placeholder === "string" ? source.placeholder : void 0,
@@ -19638,13 +19868,17 @@ function resolvePromptAnswer(prompt3, answer) {
   if (!prompt3) return answer;
   if (prompt3.type === "confirm") {
     if (typeof answer === "boolean") return answer;
-    if (typeof answer === "string") return /^(yes|y|true|confirm|ok)/i.test(answer.trim());
+    if (typeof answer === "string")
+      return /^(yes|y|true|confirm|ok)/i.test(answer.trim());
     return Boolean(answer);
   }
   if (prompt3.type === "choice" && Array.isArray(prompt3.options) && typeof answer === "string") {
     const normalized = normalizePromptText(answer);
     const tokens = extractPromptTokens(answer);
-    let best = { score: -1, resolvedValue: null };
+    let best = {
+      score: -1,
+      resolvedValue: null
+    };
     for (const option of prompt3.options) {
       const scored = scorePromptChoiceMatch(normalized, tokens, option);
       if (scored.score > best.score) best = scored;
@@ -19820,9 +20054,11 @@ var Session = class {
   /**
    * Submit a job to execute code in the sandbox.
    *
-   * The code can import typed classes from `./sandbox-tools`:
+   * The code can import typed classes from Harness v3 runtime modules:
    * ```typescript
-   * import { Author, Book, global_search } from './sandbox-tools';
+   * import { Author } from "@granular/domain/Author";
+   * import { Book } from "@granular/domain/Book";
+   * import { global_search } from "@granular/actions/backend";
    *
    * const totalAuthors = await Author.count();
    * const firstAuthorsPage = await Author.page({ page: 1, perPage: 10, saveAs: 'recent_authors' });
@@ -19900,7 +20136,11 @@ var Session = class {
     const resolvedAnswer = resolvePromptAnswer(prompt3, answer);
     this.promptCache.delete(promptId);
     this.hiddenPromptIds.add(promptId);
-    this.emit("prompt", { id: promptId, status: "answered" });
+    this.emit("prompt:answered", {
+      ...prompt3 || { id: promptId },
+      id: promptId,
+      status: "answered"
+    });
     try {
       const response = await this.client.call("prompt.answer", {
         promptId,
@@ -20211,14 +20451,19 @@ var Session = class {
     const tools = summary.tools || [];
     if (classes && Object.keys(classes).length > 0) {
       let docs2 = "# Domain Documentation\n\n";
-      docs2 += "Import classes and tools from `./sandbox-tools`:\n\n";
+      docs2 += "Import concrete classes from `@granular/domain/<Class>` and global backend actions from `@granular/actions/backend`:\n\n";
       const classNames = Object.keys(classes).map(
         (c) => c.charAt(0).toUpperCase() + c.slice(1)
       );
       const globalNames = (globalTools || []).map((t) => t.name);
-      const allImports = [...classNames, ...globalNames].join(", ");
+      const importLines = [
+        ...classNames.map(
+          (name) => `import { ${name} } from "@granular/domain/${name}";`
+        ),
+        globalNames.length > 0 ? `import { ${globalNames.join(", ")} } from "@granular/actions/backend";` : null
+      ].filter(Boolean);
       docs2 += `\`\`\`typescript
-import { ${allImports} } from "./sandbox-tools";
+${importLines.join("\n") || "// No generated domain imports available."}
 \`\`\`
 
 `;
@@ -20282,10 +20527,13 @@ import { ${allImports} } from "./sandbox-tools";
       return "No effects available in this domain.";
     }
     let docs = "# Available Effects\n\n";
-    docs += "Import effects from `./sandbox-tools` and call them with await:\n\n";
-    docs += '```typescript\nimport { tools } from "./sandbox-tools";\n\n';
+    docs += "Import global backend actions from `@granular/actions/backend` and call them with await:\n\n";
+    docs += `\`\`\`typescript
+import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
+
+`;
     docs += "// Example:\n";
-    docs += `const result = await tools.${tools[0]?.name || "example"}(input);
+    docs += `const result = await ${tools[0]?.name || "example"}(input);
 `;
     docs += "```\n\n";
     for (const tool of tools) {
@@ -20416,7 +20664,7 @@ import { ${allImports} } from "./sandbox-tools";
       const prompt3 = normalizePrompt(payload);
       if (!prompt3) return;
       if (this.hiddenPromptIds.has(prompt3.id)) {
-        this.emit("prompt", { ...prompt3, status: "answered" });
+        this.emit("prompt:answered", { ...prompt3, status: "answered" });
         return;
       }
       this.promptCache.set(prompt3.id, prompt3);
@@ -20435,9 +20683,16 @@ import { ${allImports} } from "./sandbox-tools";
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
+    this.client.on("harness.ui_status", (data) => {
+      this.emit("harness:ui_status", data);
+    });
+    this.client.on("harness.model_stream", (data) => {
+      this.emit("harness:model_stream", data);
+    });
     this.client.on("job.agent_message", (data) => {
       const normalized = normalizeJobAgentMessageEnvelope(data);
       if (!normalized) return;
+      this.emit("job:agent_message", normalized);
       if (this.jobsMap.has(normalized.jobId)) return;
       const pending = this.pendingAgentMessagesByJobId.get(normalized.jobId) || [];
       if (normalized.message.messageId && pending.some(
@@ -20587,6 +20842,7 @@ function normalizeJobAgentMessageEnvelope(data) {
       kind: d.kind === "artifacts" ? "artifacts" : "text",
       reply: typeof d.reply === "string" ? d.reply : "",
       show: d.show,
+      actions: Array.isArray(d.actions) ? d.actions : void 0,
       timestamp: d.timestamp || Date.now()
     }
   };
@@ -21598,7 +21854,9 @@ function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
   return void 0;
 }
 function resolveHandlerForMode(effectMap, effect, request) {
-  const behaviors = normalizeEffectBehaviors(request.context?.behaviors || effect.metamodels || void 0);
+  const behaviors = normalizeEffectBehaviors(
+    request.context?.behaviors || effect.metamodels || void 0
+  );
   const mode = resolveInvocationMode(request.context);
   if (mode === "dryRun") {
     if (effect.dryRunHandler) {
@@ -21613,7 +21871,12 @@ function resolveHandlerForMode(effectMap, effect, request) {
     if (effect.reverseHandler) {
       return { effect, mode, handler: effect.reverseHandler };
     }
-    const reverseEffect = resolveReverseEffect(effectMap, effect, request, behaviors);
+    const reverseEffect = resolveReverseEffect(
+      effectMap,
+      effect,
+      request,
+      behaviors
+    );
     if (reverseEffect) {
       return {
         effect: reverseEffect,
@@ -21621,7 +21884,9 @@ function resolveHandlerForMode(effectMap, effect, request) {
         handler: reverseEffect.reverseHandler || reverseEffect.handler
       };
     }
-    throw new Error(`Reverse execution is not supported for ${request.effectKey}`);
+    throw new Error(
+      `Reverse execution is not supported for ${request.effectKey}`
+    );
   }
   return { effect, mode, handler: effect.handler };
 }
@@ -21637,7 +21902,9 @@ async function invokeRegisteredEffect(effectMap, request) {
   const resolved = resolveHandlerForMode(effectMap, effect, request);
   const context = {
     ...request.context || {},
-    behaviors: normalizeEffectBehaviors(request.context?.behaviors || effect.metamodels || void 0),
+    behaviors: normalizeEffectBehaviors(
+      request.context?.behaviors || effect.metamodels || void 0
+    ),
     invocation: {
       mode: resolved.mode,
       sourceEffectKey: request.effectKey,
@@ -21799,7 +22066,7 @@ function isRetryableRecordObjectsError(error2) {
 }
 function isRetryableEffectRegistrationError(error2) {
   const message = error2 instanceof Error ? error2.message : String(error2);
-  return /timed out|websocket disconnected|websocket not connected|rpc timeout|worker restarted mid-request|network connection lost|bad gateway|gateway timeout|too many requests|(?:control plane|granular|graphql) api error \((?:429|500|502|503|504)\)/i.test(
+  return /timed out|websocket disconnected|websocket not connected|rpc timeout|rpc error: internal error; reference|worker restarted mid-request|network connection lost|bad gateway|gateway timeout|too many requests|(?:control plane|granular|graphql) api error \((?:429|500|502|503|504)\)/i.test(
     message
   );
 }
@@ -22033,19 +22300,19 @@ function computeEffectRegistrationKey(effect) {
 function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId, effectHostUrl) {
   const overrideUrl = effectHostUrl || process.env.GRANULAR_EFFECT_HOST_URL || process.env.EFFECT_HOST_URL;
   const api = new URL(apiUrl);
-  const localRuntimeBase = process.env.RUNTIME_ORCHESTRATOR_URL || (isLocalControlUrl(apiUrl) ? `${api.protocol}//${api.hostname}:8791` : "");
+  const localRuntimeBase = process.env.RUNTIME_ORCHESTRATOR_URL || "";
   const url = new URL(overrideUrl || localRuntimeBase || apiUrl);
   if (url.protocol === "https:") {
     url.protocol = "wss:";
   } else if (url.protocol === "http:") {
     url.protocol = "ws:";
   }
-  if (!overrideUrl && isLocalControlUrl(apiUrl) && api.pathname.endsWith("/granular")) {
-    url.pathname = "/granular/orchestrator/effects/connect";
+  if (!overrideUrl && isLocalControlUrl(apiUrl) && !localRuntimeBase && api.pathname.endsWith("/granular")) {
+    url.pathname = "/granular/effects/connect";
   } else if (url.pathname.endsWith("/granular/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/granular")) {
-    url.pathname = isLocalControlUrl(url.toString()) ? "/granular/orchestrator/effects/connect" : `${url.pathname.replace(/\/$/, "")}/effects/connect`;
+    url.pathname = localRuntimeBase && isLocalControlUrl(url.toString()) ? "/granular/orchestrator/effects/connect" : `${url.pathname.replace(/\/$/, "")}/effects/connect`;
   } else if (url.pathname.endsWith("/v2/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/v2/ws")) {
@@ -22226,7 +22493,15 @@ var Environment = class _Environment {
       create: async (options) => this.createSession(options),
       connect: async (sessionId, options) => this.connectSession(sessionId, options),
       reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
-      close: async (sessionId, session2) => this.closeSession(sessionId, session2)
+      close: async (sessionId, session2) => this.closeSession(sessionId, session2),
+      state: async (options) => this.getUserEnvironmentState(options),
+      markRead: async (options) => this.markUserEnvironmentSessionsRead(options)
+    };
+  }
+  get userEnvironmentState() {
+    return {
+      get: async (options) => this.getUserEnvironmentState(options),
+      markRead: async (options) => this.markUserEnvironmentSessionsRead(options)
     };
   }
   get data() {
@@ -22267,6 +22542,18 @@ var Environment = class _Environment {
     }
     return status === "closed" ? this.granular.listClosedSessions({ environmentId: this.environmentId }) : this.granular.listOpenSessions({ environmentId: this.environmentId });
   }
+  async getUserEnvironmentState(options = {}) {
+    return this.granular.getUserEnvironmentState({
+      ...options,
+      environmentId: this.environmentId
+    });
+  }
+  async markUserEnvironmentSessionsRead(options) {
+    return this.granular.markUserEnvironmentSessionsRead({
+      ...options,
+      environmentId: this.environmentId
+    });
+  }
   async createSession(options) {
     return this.granular.createSession({
       environmentId: this.environmentId,
@@ -22277,7 +22564,9 @@ var Environment = class _Environment {
   async connectSession(sessionId, options) {
     const session2 = await this.granular["connectSession"]({
       sessionId,
-      clientId: options?.clientId
+      clientId: options?.clientId,
+      maxReconnectAttempts: options?.maxReconnectAttempts,
+      reconnectDelayMs: options?.reconnectDelayMs
     });
     if (session2.environmentId !== this.environmentId) {
       await session2.disconnect().catch(() => {
@@ -24072,6 +24361,39 @@ var Granular = class _Granular {
   async listClosedSessions(filters) {
     return this.listSessionsForEnvironment(filters.environmentId, "closed");
   }
+  async getUserEnvironmentState(options) {
+    const query = new URLSearchParams({
+      environmentId: options.environmentId
+    });
+    if (options.sessionScope) {
+      query.set("sessionScope", options.sessionScope);
+    }
+    if (options.status) {
+      query.set("status", options.status);
+    }
+    if (typeof options.limit === "number") {
+      query.set("limit", String(options.limit));
+    }
+    if (typeof options.offset === "number") {
+      query.set("offset", String(options.offset));
+    }
+    const state = await this.request(
+      `/sdk/user-environment-state?${query.toString()}`
+    );
+    return this.normalizeUserEnvironmentState(state);
+  }
+  async markUserEnvironmentSessionsRead(options) {
+    const result = await this.request("/sdk/user-environment-state/read", {
+      method: "POST",
+      body: JSON.stringify({
+        environmentId: options.environmentId,
+        sessionId: options.sessionId,
+        sessionIds: options.sessionIds,
+        readAt: options.readAt
+      })
+    });
+    return result.readAtBySessionId || {};
+  }
   async listSessionsForEnvironment(environmentId, status) {
     const query = new URLSearchParams({ environmentId, status });
     const res = await this.request(
@@ -24102,6 +24424,24 @@ var Granular = class _Granular {
       toolCallCount: typeof row.toolCallCount === "number" ? row.toolCallCount : void 0
     };
   }
+  normalizeUserEnvironmentState(state) {
+    return {
+      ...state,
+      sessions: Array.isArray(state.sessions) ? state.sessions.map((item) => ({
+        ...item,
+        session: this.normalizeConversationSession(
+          item.session
+        )
+      })) : [],
+      attention: {
+        prompts: Array.isArray(state.attention?.prompts) ? state.attention.prompts : [],
+        count: typeof state.attention?.count === "number" ? state.attention.count : 0,
+        activePrompt: state.attention?.activePrompt || null
+      },
+      unreadCount: typeof state.unreadCount === "number" ? state.unreadCount : 0,
+      readAtBySessionId: state.readAtBySessionId || {}
+    };
+  }
   static coerceIsoDate(value) {
     if (value instanceof Date) {
       return value.toISOString();
@@ -24144,7 +24484,10 @@ var Granular = class _Granular {
     });
     const envData = await this.environments.get(minted.environmentId);
     const environment = this.bindEnvironmentHandle(envData);
-    return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, minted, {
+      maxReconnectAttempts: options.maxReconnectAttempts,
+      reconnectDelayMs: options.reconnectDelayMs
+    });
   }
   async recordOpenAIUsageSpend(usage, context, options) {
     return recordOpenAIUsageSpend({
@@ -24295,13 +24638,15 @@ var Granular = class _Granular {
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
     return new Environment(this, envData, this.apiKey, graphqlEndpoint);
   }
-  async bindWebSocketEnvironmentSession(environment, clientId, session2) {
+  async bindWebSocketEnvironmentSession(environment, clientId, session2, transportOptions = {}) {
     const client = new WSClient({
       url: session2.wsUrl,
       sessionId: session2.sessionId,
       token: session2.token,
       tokenProvider: this.tokenProvider,
       WebSocketCtor: this.WebSocketCtor,
+      maxReconnectAttempts: transportOptions.maxReconnectAttempts,
+      reconnectDelayMs: transportOptions.reconnectDelayMs,
       onUnexpectedClose: this.onUnexpectedClose,
       onReconnectError: this.onReconnectError
     });
@@ -24668,7 +25013,10 @@ var Granular = class _Granular {
     try {
       const sandbox = await this.sandboxes.get(nameOrId);
       return sandbox;
-    } catch {
+    } catch (error2) {
+      if (nameOrId.startsWith("sbx_")) {
+        throw error2;
+      }
       const sandboxes = await this.sandboxes.list();
       const existing = sandboxes.items.find((s) => s.name === nameOrId);
       if (existing) {
@@ -25774,7 +26122,7 @@ async function graphqlCommand(options) {
         "Ontology ID": payload.ontologyId,
         "Environment ID": payload.environmentId,
         "Session ID": payload.sessionId,
-        "OK": payload.ok ? "yes" : "no"
+        OK: payload.ok ? "yes" : "no"
       });
       console.log();
       console.log(JSON.stringify(result, null, 2));
@@ -25785,7 +26133,9 @@ async function graphqlCommand(options) {
 
 // src/cli/commands/effects.ts
 function sortEffects(effects2) {
-  return [...effects2].sort((left, right) => left.name.localeCompare(right.name));
+  return [...effects2].sort(
+    (left, right) => left.name.localeCompare(right.name)
+  );
 }
 async function effectsListCommand(options) {
   const emitJson = options.json === true;
@@ -25896,7 +26246,10 @@ async function effectsDiffCommand(options) {
 // src/cli/commands/job.ts
 async function jobRunCommand(options) {
   const emitJson = options.json === true;
-  const code = readJobCodeFromOptions({ file: options.file, inline: options.inline });
+  const code = readJobCodeFromOptions({
+    file: options.file,
+    inline: options.inline
+  });
   if (!emitJson) {
     printHeader();
   }
@@ -25951,7 +26304,7 @@ async function jobRunCommand(options) {
         "Environment ID": payload.environmentId,
         "Session ID": payload.sessionId,
         "Job ID": payload.jobId,
-        "Status": payload.status
+        Status: payload.status
       });
       console.log();
       console.log(JSON.stringify(result, null, 2));
@@ -26100,7 +26453,9 @@ async function versionCurrentCommand(options) {
     ]);
     const current = resolveCurrentVersion(builds, tags);
     if (!current) {
-      throw new Error("No versions exist for this ontology yet. Run `granular build` first.");
+      throw new Error(
+        "No versions exist for this ontology yet. Run `granular build` first."
+      );
     }
     const payload = {
       ontologyId: config.sandboxId,
@@ -26120,9 +26475,12 @@ async function versionCurrentCommand(options) {
     console.log();
     keyValue({
       "Ontology ID": payload.ontologyId,
-      "Current version": formatVersionLabel(payload.versionId, payload.versionNumber),
-      "Status": payload.status,
-      "Created": payload.createdAt,
+      "Current version": formatVersionLabel(
+        payload.versionId,
+        payload.versionNumber
+      ),
+      Status: payload.status,
+      Created: payload.createdAt,
       "Dev tag": payload.devVersionId || "not set",
       "Prod tag": payload.prodVersionId || "not set"
     });
@@ -26164,7 +26522,7 @@ async function versionDiffCommand(versionId, againstVersionId, options) {
     spin?.succeed("  Version diff ready.");
     console.log();
     keyValue({
-      "Version": formatVersionLabel(version2.buildId, version2.versionNumber),
+      Version: formatVersionLabel(version2.buildId, version2.versionNumber),
       "Compared against": baseVersion ? formatVersionLabel(baseVersion.buildId, baseVersion.versionNumber) : diffResult.againstVersionId || "previous version",
       "Added operations": summary.added,
       "Changed operations": summary.changed,
@@ -26255,17 +26613,21 @@ async function tagMoveCommand(tagName, versionId) {
     spin.succeed(`  ${tagName} now points to ${versionId}.`);
     console.log();
     keyValue({
-      "Tag": moved.name,
+      Tag: moved.name,
       "Previous version": previousVersionId || "not set",
       "Current version": moved.targetVersionId || moved.targetBuildId || "not set",
-      "Protected": moved.protected ? "yes" : "no"
+      Protected: moved.protected ? "yes" : "no"
     });
     console.log();
     if (moved.name === "prod") {
-      info("Existing prod environments keep their current version until they are transitioned.");
+      info(
+        "Existing prod environments keep their current version until they are transitioned."
+      );
       console.log();
     } else if (moved.name === "dev") {
-      info("dev is usually automatic. You only need to move it manually for exceptional release workflows.");
+      info(
+        "dev is usually automatic. You only need to move it manually for exceptional release workflows."
+      );
       console.log();
     }
   } catch (err) {