@granular-software/sdk 0.4.49 → 0.4.51

package/dist/cli/index.js

@@ -60,11 +60,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
   }
   return to;
 };
@@ -8889,7 +8889,7 @@ createChalk({ level: stderrColor ? stderrColor.level : 0 });
 var source_default = chalk;
 
 // ../../node_modules/mimic-function/index.js
-var copyProperty = (to, from, property, ignoreNonConfigurable) => {
+var copyProperty = (to, from2, property, ignoreNonConfigurable) => {
   if (property === "length" || property === "prototype") {
     return;
   }
@@ -8897,7 +8897,7 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
     return;
   }
   const toDescriptor = Object.getOwnPropertyDescriptor(to, property);
-  const fromDescriptor = Object.getOwnPropertyDescriptor(from, property);
+  const fromDescriptor = Object.getOwnPropertyDescriptor(from2, property);
   if (!canCopyProperty(toDescriptor, fromDescriptor) && ignoreNonConfigurable) {
     return;
   }
@@ -8906,8 +8906,8 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
 var canCopyProperty = function(toDescriptor, fromDescriptor) {
   return toDescriptor === void 0 || toDescriptor.configurable || toDescriptor.writable === fromDescriptor.writable && toDescriptor.enumerable === fromDescriptor.enumerable && toDescriptor.configurable === fromDescriptor.configurable && (toDescriptor.writable || toDescriptor.value === fromDescriptor.value);
 };
-var changePrototype = (to, from) => {
-  const fromPrototype = Object.getPrototypeOf(from);
+var changePrototype = (to, from2) => {
+  const fromPrototype = Object.getPrototypeOf(from2);
   if (fromPrototype === Object.getPrototypeOf(to)) {
     return;
   }
@@ -8917,20 +8917,20 @@ var wrappedToString = (withName, fromBody) => `/* Wrapped ${withName}*/
 ${fromBody}`;
 var toStringDescriptor = Object.getOwnPropertyDescriptor(Function.prototype, "toString");
 var toStringName = Object.getOwnPropertyDescriptor(Function.prototype.toString, "name");
-var changeToString = (to, from, name) => {
+var changeToString = (to, from2, name) => {
   const withName = name === "" ? "" : `with ${name.trim()}() `;
-  const newToString = wrappedToString.bind(null, withName, from.toString());
+  const newToString = wrappedToString.bind(null, withName, from2.toString());
   Object.defineProperty(newToString, "name", toStringName);
   const { writable, enumerable, configurable } = toStringDescriptor;
   Object.defineProperty(to, "toString", { value: newToString, writable, enumerable, configurable });
 };
-function mimicFunction(to, from, { ignoreNonConfigurable = false } = {}) {
+function mimicFunction(to, from2, { ignoreNonConfigurable = false } = {}) {
   const { name } = to;
-  for (const property of Reflect.ownKeys(from)) {
-    copyProperty(to, from, property, ignoreNonConfigurable);
+  for (const property of Reflect.ownKeys(from2)) {
+    copyProperty(to, from2, property, ignoreNonConfigurable);
   }
-  changePrototype(to, from);
-  changeToString(to, from, name);
+  changePrototype(to, from2);
+  changeToString(to, from2, name);
   return to;
 }
 
@@ -9880,7 +9880,7 @@ function relationshipEdgesForClass(className, rels) {
   return edges;
 }
 function toPascalCase(name) {
-  return name.charAt(0).toUpperCase() + name.slice(1);
+  return name.split(/[_:\-\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
 
 // src/cli/agent-docs/concept-blocks.ts
@@ -14065,16 +14065,107 @@ var StateMachineStateSchema = external_exports.union([
   external_exports.string(),
   external_exports.object({
     name: external_exports.string().min(1),
+    label: external_exports.string().optional(),
+    description: external_exports.string().optional(),
     isFinal: external_exports.boolean().optional()
   }).strict()
 ]);
+var StateTransitionInputBindingSchema = external_exports.lazy(
+  () => external_exports.union([
+    external_exports.null(),
+    external_exports.string(),
+    external_exports.number(),
+    external_exports.boolean(),
+    external_exports.array(StateTransitionInputBindingSchema),
+    external_exports.object({
+      const: external_exports.unknown()
+    }).strict(),
+    external_exports.object({
+      from: external_exports.literal("object"),
+      path: external_exports.string().min(1),
+      editable: external_exports.boolean().optional()
+    }).strict(),
+    external_exports.object({
+      from: external_exports.literal("field"),
+      name: external_exports.string().min(1),
+      editable: external_exports.boolean().optional()
+    }).strict(),
+    external_exports.object({
+      from: external_exports.literal("relationship"),
+      name: external_exports.string().min(1),
+      path: external_exports.string().min(1).optional(),
+      many: external_exports.boolean().optional(),
+      editable: external_exports.boolean().optional()
+    }).strict(),
+    external_exports.object({
+      from: external_exports.literal("session"),
+      path: external_exports.string().min(1),
+      editable: external_exports.boolean().optional()
+    }).strict(),
+    external_exports.object({
+      from: external_exports.literal("actor"),
+      path: external_exports.string().min(1),
+      editable: external_exports.boolean().optional()
+    }).strict(),
+    external_exports.record(external_exports.string(), StateTransitionInputBindingSchema)
+  ])
+);
+var StateTransitionActionSchema = external_exports.object({
+  effect: external_exports.string().min(1),
+  input: external_exports.record(external_exports.string(), StateTransitionInputBindingSchema).optional()
+}).strict();
+var StateTransitionAssigneeSchema = external_exports.object({
+  kind: external_exports.string().min(1),
+  from: StateTransitionInputBindingSchema.optional(),
+  role: external_exports.string().optional(),
+  label: external_exports.string().optional()
+}).strict();
+var StateTransitionRelatedStateRequirementSchema = external_exports.object({
+  relationship: external_exports.string().min(1),
+  machine: external_exports.string().min(1),
+  state: external_exports.string().min(1),
+  className: external_exports.string().min(1).optional(),
+  label: external_exports.string().optional(),
+  mode: external_exports.enum(["every", "some", "any"]).optional()
+}).strict();
+var StateTransitionRequirementsSchema = external_exports.object({
+  fields: external_exports.array(external_exports.string().min(1)).optional(),
+  relationships: external_exports.array(external_exports.string().min(1)).optional(),
+  relatedStates: external_exports.array(StateTransitionRelatedStateRequirementSchema).optional()
+}).strict();
+var StateTransitionPermissionSchema = external_exports.union([
+  external_exports.string().min(1),
+  external_exports.object({
+    profile: external_exports.string().min(1).optional(),
+    profileId: external_exports.string().min(1).optional(),
+    label: external_exports.string().optional(),
+    reason: external_exports.string().optional()
+  }).strict()
+]);
+var StateTransitionExpectedOutcomeSchema = external_exports.union([
+  external_exports.string().min(1),
+  external_exports.object({
+    machine: external_exports.string().min(1).optional(),
+    state: external_exports.string().min(1),
+    summary: external_exports.string().optional()
+  }).strict()
+]);
 var StateMachineTransitionSchema = external_exports.object({
   name: external_exports.string().min(1),
   from: external_exports.string().min(1),
-  to: external_exports.string().min(1)
+  to: external_exports.string().min(1),
+  label: external_exports.string().optional(),
+  description: external_exports.string().optional(),
+  action: StateTransitionActionSchema.optional(),
+  assignee: StateTransitionAssigneeSchema.optional(),
+  requirements: StateTransitionRequirementsSchema.optional(),
+  permission: StateTransitionPermissionSchema.optional(),
+  risk: external_exports.enum(["low", "medium", "high"]).optional(),
+  expectedOutcome: StateTransitionExpectedOutcomeSchema.optional()
 }).strict();
 external_exports.object({
   name: external_exports.string().min(1),
+  stateField: external_exports.string().min(1).optional(),
   entryState: external_exports.string().min(1),
   states: external_exports.array(StateMachineStateSchema).min(1),
   transitions: external_exports.array(StateMachineTransitionSchema),
@@ -14141,6 +14232,16 @@ var PoliciesSchema = external_exports.object({
   confirmWhen: external_exports.array(PolicyRuleSchema).optional(),
   denyWhen: external_exports.array(PolicyRuleSchema).optional()
 }).strict();
+var CreatesSchema = external_exports.union([
+  external_exports.string().min(1),
+  external_exports.object({
+    className: external_exports.string().min(1),
+    idPath: external_exports.string().min(1).optional(),
+    pathPath: external_exports.string().min(1).optional(),
+    statePath: external_exports.string().min(1).optional(),
+    classStateHandle: external_exports.boolean().optional()
+  }).strict()
+]);
 external_exports.object({
   postCondition: external_exports.union([
     external_exports.string(),
@@ -14171,6 +14272,7 @@ external_exports.object({
       mode: external_exports.string().optional()
     }).strict()
   ]).optional(),
+  creates: CreatesSchema.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(),
@@ -14398,6 +14500,7 @@ function mergeMethodSummaryPatch(target, patch) {
   if (patch.metamodels !== void 0) target.metamodels = patch.metamodels;
   if (patch.effectBehaviors !== void 0)
     target.effectBehaviors = patch.effectBehaviors;
+  if (patch.creates !== void 0) target.creates = patch.creates;
   if (patch.static !== void 0) target.static = patch.static;
 }
 function toPascalCase2(value) {
@@ -14458,29 +14561,60 @@ function normalizeEffectBehaviorSummary(metamodels) {
   }
   return Object.keys(result).length > 0 ? result : null;
 }
-function buildEffectBehaviorDocs(effectBehaviors) {
-  if (!effectBehaviors) {
-    return [];
+function normalizeCreationSummary(metamodels) {
+  if (!isObject(metamodels)) return null;
+  let raw = metamodels.creates;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith('"')) {
+      try {
+        raw = JSON.parse(trimmed);
+      } catch {
+        return { className: trimmed };
+      }
+    } else {
+      return { className: trimmed };
+    }
+  }
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return { className: raw.trim() };
   }
+  if (!isObject(raw)) return null;
+  const className = typeof raw.className === "string" && raw.className.trim() ? raw.className.trim() : "";
+  if (!className) return null;
+  return {
+    className,
+    ...typeof raw.idPath === "string" && raw.idPath.trim() ? { idPath: raw.idPath.trim() } : {},
+    ...typeof raw.pathPath === "string" && raw.pathPath.trim() ? { pathPath: raw.pathPath.trim() } : {},
+    ...typeof raw.statePath === "string" && raw.statePath.trim() ? { statePath: raw.statePath.trim() } : {},
+    ...typeof raw.classStateHandle === "boolean" ? { classStateHandle: raw.classStateHandle } : {}
+  };
+}
+function buildEffectBehaviorDocs(effectBehaviors, creates) {
   const docs = [];
-  if (effectBehaviors.approvalRequired?.required) {
+  if (creates) {
+    docs.push(
+      `Creation method: creates ${creates.className}. The agent may use generated class-level new-record action methods for this class.`
+    );
+  }
+  if (effectBehaviors?.approvalRequired?.required) {
     docs.push(
       effectBehaviors.approvalRequired.reason ? `Approval required: ${effectBehaviors.approvalRequired.reason}.` : "Approval required before execution."
     );
   }
-  if (effectBehaviors.postCondition) {
+  if (effectBehaviors?.postCondition) {
     docs.push(`Post-condition: ${effectBehaviors.postCondition.condition}.`);
     if (effectBehaviors.postCondition.description) {
       docs.push(effectBehaviors.postCondition.description);
     }
   }
-  if (effectBehaviors.dryRun?.enabled) {
+  if (effectBehaviors?.dryRun?.enabled) {
     docs.push("Supports dry run.");
     if (effectBehaviors.dryRun.description) {
       docs.push(effectBehaviors.dryRun.description);
     }
   }
-  if (effectBehaviors.reverse) {
+  if (effectBehaviors?.reverse) {
     if (effectBehaviors.reverse.handler) {
       docs.push(`Reverse handler: ${effectBehaviors.reverse.handler}.`);
     } else {
@@ -14539,13 +14673,21 @@ function buildEffectBehaviorMutations(toolPath, spec) {
       query: `mutation { at(path: ${JSON.stringify(toolPath)}) { set_approval_required(${args}) { kind } } }`
     });
   }
+  if (spec.creates !== void 0) {
+    mutations.push({
+      label: `set creates on ${toolPath}`,
+      query: `mutation { at(path: ${JSON.stringify(toolPath)}) { create_submodel(subpath: "creates", label: "creates") { set_string_value(value: ${JSON.stringify(
+        JSON.stringify(spec.creates)
+      )}) { done } } } }`
+    });
+  }
   return mutations;
 }
 function readMethodEffectBehaviors(rawMethod) {
+  const metamodels = isObject(rawMethod.metamodels) ? rawMethod.metamodels : null;
   return {
-    effectBehaviors: normalizeEffectBehaviorSummary(
-      isObject(rawMethod.metamodels) ? rawMethod.metamodels : null
-    )
+    effectBehaviors: normalizeEffectBehaviorSummary(metamodels),
+    creates: normalizeCreationSummary(metamodels)
   };
 }
 var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
@@ -14567,6 +14709,10 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
       {
         key: "approvalRequired",
         description: "Boolean or `{ required, reason, mode }`."
+      },
+      {
+        key: "creates",
+        description: 'Marks a static method as an allowed creator for a class. Use `creates: "class_name"` or `{ className, idPath, pathPath, statePath, classStateHandle }`.'
       }
     ]
   },
@@ -14686,7 +14832,10 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
         ...methodIR,
         docs: [
           ...methodIR.docs,
-          ...buildEffectBehaviorDocs(methodSummary.effectBehaviors)
+          ...buildEffectBehaviorDocs(
+            methodSummary.effectBehaviors,
+            methodSummary.creates
+          )
         ]
       };
     }
@@ -15305,15 +15454,47 @@ var searchableMetamodelPackage = defineMetamodelPackage({
 
 // ../metamodel-state-machine/src/index.ts
 function normalizeStateMachines(values) {
+  const parseJsonRecord = (value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return value;
+    }
+    if (typeof value !== "string" || !value.trim()) return null;
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+  const parseJsonValue = (value) => {
+    if (value === null || typeof value === "undefined") return null;
+    if (typeof value !== "string") return value;
+    if (!value.trim()) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  };
   return (values || []).map((machine) => {
     const states = (machine?.states || []).map((state) => ({
       name: String(state?.name || ""),
-      isFinal: Boolean(state?.is_final)
+      label: typeof state?.label === "string" ? state.label : null,
+      description: typeof state?.description === "string" ? state.description : null,
+      isFinal: Boolean(state?.is_final ?? state?.isFinal)
     })).filter((state) => state.name.length > 0);
     const transitions = (machine?.transitions || []).map((transition) => ({
       name: String(transition?.name || ""),
       from: String(transition?.from?.name || ""),
-      to: String(transition?.to?.name || "")
+      to: String(transition?.to?.name || ""),
+      label: typeof transition?.label === "string" ? transition.label : null,
+      description: typeof transition?.description === "string" ? transition.description : null,
+      action: parseJsonRecord(transition?.action) || parseJsonRecord(transition?.action_json),
+      assignee: parseJsonRecord(transition?.assignee) || parseJsonRecord(transition?.assignee_json),
+      requirements: parseJsonRecord(transition?.requirements) || parseJsonRecord(transition?.requirements_json),
+      permission: parseJsonValue(transition?.permission) ?? parseJsonValue(transition?.permission_json),
+      risk: transition?.risk === "low" || transition?.risk === "medium" || transition?.risk === "high" ? transition.risk : null,
+      expectedOutcome: parseJsonValue(transition?.expectedOutcome) ?? parseJsonValue(transition?.expected_outcome_json)
     })).filter(
       (transition) => transition.name.length > 0 && transition.from.length > 0 && transition.to.length > 0
     );
@@ -15335,6 +15516,15 @@ function transitionTypeName(className, machineName) {
 function pathTypeName(className, machineName) {
   return `${stateTypeName(className, machineName)}Path`;
 }
+function methodToken(value) {
+  const token = String(value || "").trim().replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  return token || "state";
+}
+function transitionActionsForMachine(machine) {
+  return Object.fromEntries(
+    (machine.transitions || []).filter((transition) => transition.action?.effect).map((transition) => [transition.name, transition.action])
+  );
+}
 function normalizeStateDefinitions(machine) {
   const finalStates = new Set(machine.finalStates || []);
   const states = /* @__PURE__ */ new Map();
@@ -15348,6 +15538,8 @@ function normalizeStateDefinitions(machine) {
     }
     states.set(rawState.name, {
       name: rawState.name,
+      label: rawState.label,
+      description: rawState.description,
       isFinal: Boolean(rawState.isFinal) || finalStates.has(rawState.name)
     });
   }
@@ -15359,6 +15551,44 @@ function normalizeStateDefinitions(machine) {
   }
   return [...states.values()];
 }
+function transitionMetadataGraphqlArgs(transition) {
+  const args = [];
+  if (typeof transition.label === "string") {
+    args.push(`label: ${JSON.stringify(transition.label)}`);
+  }
+  if (typeof transition.description === "string") {
+    args.push(`description: ${JSON.stringify(transition.description)}`);
+  }
+  if (transition.action) {
+    args.push(
+      `action_json: ${JSON.stringify(JSON.stringify(transition.action))}`
+    );
+  }
+  if (transition.assignee) {
+    args.push(
+      `assignee_json: ${JSON.stringify(JSON.stringify(transition.assignee))}`
+    );
+  }
+  if (transition.requirements) {
+    args.push(
+      `requirements_json: ${JSON.stringify(JSON.stringify(transition.requirements))}`
+    );
+  }
+  if (transition.permission) {
+    args.push(
+      `permission_json: ${JSON.stringify(JSON.stringify(transition.permission))}`
+    );
+  }
+  if (transition.risk) {
+    args.push(`risk: ${JSON.stringify(transition.risk)}`);
+  }
+  if (transition.expectedOutcome) {
+    args.push(
+      `expected_outcome_json: ${JSON.stringify(JSON.stringify(transition.expectedOutcome))}`
+    );
+  }
+  return args.length > 0 ? `, ${args.join(", ")}` : "";
+}
 function buildStateMachineModelMutations(modelPath, machines) {
   const mutations = [];
   for (const machine of machines || []) {
@@ -15369,12 +15599,13 @@ function buildStateMachineModelMutations(modelPath, machines) {
       )}, entry_state: ${JSON.stringify(machine.entryState)}) { name } } }`
     });
     for (const state of normalizeStateDefinitions(machine)) {
-      if (state.name === machine.entryState && !state.isFinal) continue;
+      if (state.name === machine.entryState && !state.isFinal && !state.label && !state.description)
+        continue;
       mutations.push({
         label: `add state ${state.name} on ${modelPath}.${machine.name}`,
         query: `mutation { at(path: ${JSON.stringify(modelPath)}) { state_machine(name: ${JSON.stringify(
           machine.name
-        )}) { add_state(name: ${JSON.stringify(state.name)}, is_final: ${state.isFinal}) { name } } } }`
+        )}) { add_state(name: ${JSON.stringify(state.name)}, is_final: ${state.isFinal}, label: ${JSON.stringify(state.label || null)}, description: ${JSON.stringify(state.description || null)}) { name } } } }`
       });
     }
     for (const transition of machine.transitions || []) {
@@ -15386,18 +15617,27 @@ function buildStateMachineModelMutations(modelPath, machines) {
           transition.name
         )}, from: ${JSON.stringify(transition.from)}, to: ${JSON.stringify(
           transition.to
-        )}) { name } } } }`
+        )}${transitionMetadataGraphqlArgs(transition)}) { name } } } }`
       });
     }
   }
   return mutations;
 }
 function buildMachineTypes(classSummary, machine) {
+  const stateGlossary = machine.states.map((state) => {
+    const label = state.label && state.label !== state.name ? state.label : null;
+    const meaning = [label, state.description].filter(Boolean).join(" \u2014 ");
+    const finalMarker = state.isFinal ? " Final state." : "";
+    return `${state.name}${meaning ? `: ${meaning}` : "."}${finalMarker}`;
+  });
   return [
     {
       kind: "union",
       name: stateTypeName(classSummary.name, machine.name),
-      docs: [`Allowed states for ${classSummary.name}.${machine.name}.`],
+      docs: [
+        `Allowed states for ${classSummary.name}.${machine.name}.`,
+        ...stateGlossary
+      ],
       members: machine.states.map((state) => state.name)
     },
     {
@@ -15413,7 +15653,7 @@ function buildMachineMethods(classSummary, machine) {
   const transitionName = transitionTypeName(classSummary.name, machine.name);
   pathTypeName(classSummary.name, machine.name);
   const docsPrefix = `${classSummary.name}.${machine.name}`;
-  return [
+  const methods = [
     {
       name: `get_${machine.name}`,
       docs: [`Get the current ${docsPrefix} state.`],
@@ -15509,6 +15749,99 @@ function buildMachineMethods(classSummary, machine) {
       }
     }
   ];
+  const creationMethods = (classSummary.methods || []).filter(
+    (method) => method.static === true && Boolean(method.creates) && method.creates?.className === classSummary.name && typeof method.effectKey === "string" && method.effectKey.length > 0
+  );
+  for (const state of machine.states) {
+    const stateNameValue = typeof state === "string" ? state : String(state?.name || "");
+    if (!stateNameValue) continue;
+    const token = methodToken(stateNameValue);
+    methods.push(
+      {
+        name: `reach_${machine.name}_to_${token}`,
+        docs: [`Reach ${docsPrefix} state ${stateNameValue}.`],
+        static: false,
+        params: [],
+        returnType: `Promise<${toPascalCase2(classSummary.name)}>`,
+        runtime: {
+          kind: "state_machine",
+          machineName: machine.name,
+          className: classSummary.name,
+          stateTypeName: stateName,
+          transitionTypeName: transitionName,
+          operation: "reach",
+          targetState: stateNameValue,
+          transitionActions: transitionActionsForMachine(machine)
+        }
+      },
+      {
+        name: `prepare_${machine.name}_to_${token}`,
+        docs: [
+          `Prepare a reviewable artifact that can move ${docsPrefix} to ${stateNameValue}.`
+        ],
+        static: false,
+        params: [],
+        returnType: "Promise<SessionArtifactRecord>",
+        runtime: {
+          kind: "state_machine",
+          machineName: machine.name,
+          className: classSummary.name,
+          stateTypeName: stateName,
+          transitionTypeName: transitionName,
+          operation: "prepare_reach",
+          targetState: stateNameValue,
+          transitionActions: transitionActionsForMachine(machine)
+        }
+      }
+    );
+    for (const creationMethod of creationMethods) {
+      const creationRuntime = {
+        kind: "state_machine",
+        machineName: machine.name,
+        className: classSummary.name,
+        stateTypeName: stateName,
+        transitionTypeName: transitionName,
+        operation: "prepare_create_reach",
+        targetState: stateNameValue,
+        transitionActions: transitionActionsForMachine(machine),
+        creation: {
+          methodName: creationMethod.name,
+          effectKey: creationMethod.effectKey || creationMethod.name,
+          inputSchema: creationMethod.inputSchema,
+          outputSchema: creationMethod.outputSchema,
+          creates: creationMethod.creates
+        }
+      };
+      const viaName = `prepare_${machine.name}_to_${token}_via_${methodToken(creationMethod.name)}`;
+      methods.push({
+        name: viaName,
+        docs: [
+          `Prepare a reviewable artifact that will create a new ${classSummary.name} through ${creationMethod.name}, then move ${docsPrefix} to ${stateNameValue}.`
+        ],
+        static: true,
+        params: [
+          { name: "input", type: "Record<string, any>", optional: true }
+        ],
+        returnType: "Promise<SessionArtifactRecord>",
+        runtime: creationRuntime
+      });
+      if (creationMethods.length === 1) {
+        methods.push({
+          name: `prepare_${machine.name}_to_${token}`,
+          docs: [
+            `Prepare a reviewable artifact that will create a new ${classSummary.name}, then move ${docsPrefix} to ${stateNameValue}.`
+          ],
+          static: true,
+          params: [
+            { name: "input", type: "Record<string, any>", optional: true }
+          ],
+          returnType: "Promise<SessionArtifactRecord>",
+          runtime: creationRuntime
+        });
+      }
+    }
+  }
+  return methods;
 }
 function readStateMachineSummaries(rawClass) {
   return {
@@ -15531,8 +15864,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
       type StateMachineMutation {
         name: String!
         state_machine: StateMachine!
-        add_state(name: String!, is_final: Boolean): StateMachineMutation!
-        add_transition(name: String!, from: String!, to: String!): StateMachineMutation!
+        add_state(name: String!, is_final: Boolean, label: String, description: String): StateMachineMutation!
+        add_transition(name: String!, from: String!, to: String!, label: String, description: String, action_json: String, assignee_json: String, requirements_json: String, permission_json: String, risk: String, expected_outcome_json: String): StateMachineMutation!
         activate_transition(name: String!): StateMachineMutation!
       }
 
@@ -15549,6 +15882,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
       type StateMachineSnapshotMutation {
         snapshot: StateMachineSnapshot!
         activate_transition(name: String!): StateMachineSnapshotMutation!
+        observe_state(state: String!, force: Boolean, source: String): StateMachineSnapshotMutation!
       }
 
       type StateMachine {
@@ -15568,6 +15902,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
 
       type StateMachineState {
         name: String!
+        label: String
+        description: String
         is_final: Boolean!
       }
 
@@ -15575,6 +15911,14 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         name: String!
         from: StateMachineState!
         to: StateMachineState!
+        label: String
+        description: String
+        action_json: String
+        assignee_json: String
+        requirements_json: String
+        permission_json: String
+        risk: String
+        expected_outcome_json: String
       }
 
       type StateMachinePath {
@@ -15627,23 +15971,47 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         StateMachineMutation: {
           name: (value) => value.name,
           state_machine: async (value) => await run(value.target.state_machine(value.name)),
-          add_state: async (value, { name, is_final }) => {
+          add_state: async (value, { name, is_final, label, description }) => {
             await run(
               value.target.add_state_machine_state(
                 value.name,
                 name,
-                is_final ?? false
+                is_final ?? false,
+                label,
+                description
               )
             );
             return value;
           },
-          add_transition: async (value, { name, from, to }) => {
+          add_transition: async (value, {
+            name,
+            from: from2,
+            to,
+            label,
+            description,
+            action_json,
+            assignee_json,
+            requirements_json,
+            permission_json,
+            risk,
+            expected_outcome_json
+          }) => {
             await run(
               value.target.add_state_machine_transition(
                 value.name,
                 name,
-                from,
-                to
+                from2,
+                to,
+                {
+                  label,
+                  description,
+                  actionJson: action_json,
+                  assigneeJson: assignee_json,
+                  requirementsJson: requirements_json,
+                  permissionJson: permission_json,
+                  risk,
+                  expectedOutcomeJson: expected_outcome_json
+                }
               )
             );
             return value;
@@ -15662,16 +16030,37 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
               value.target.activate_state_machine_transition(value.name, name)
             );
             return value;
+          },
+          observe_state: async (value, { state, force, source }) => {
+            await run(
+              value.target.observe_state_machine_state(
+                value.name,
+                state,
+                force === true,
+                source
+              )
+            );
+            return value;
           }
         },
         StateMachineState: {
           name: (value) => value.name,
+          label: (value) => value.label || null,
+          description: (value) => value.description || null,
           is_final: (value) => value.is_final
         },
         StateMachineTransition: {
           name: (value) => value.name,
           from: (value) => value.from_state || { name: value.from, is_final: false },
-          to: (value) => value.to_state || { name: value.to, is_final: false }
+          to: (value) => value.to_state || { name: value.to, is_final: false },
+          label: (value) => value.label || null,
+          description: (value) => value.description || null,
+          action_json: (value) => value.action_json || null,
+          assignee_json: (value) => value.assignee_json || null,
+          requirements_json: (value) => value.requirements_json || null,
+          permission_json: (value) => value.permission_json || null,
+          risk: (value) => value.risk || null,
+          expected_outcome_json: (value) => value.expected_outcome_json || null
         },
         StateMachinePath: {
           states: (value) => value.states,
@@ -15738,6 +16127,14 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             name
             from { name }
             to { name }
+            label
+            description
+            action_json
+            assignee_json
+            requirements_json
+            permission_json
+            risk
+            expected_outcome_json
           }
         }`
       ]
@@ -16426,7 +16823,7 @@ ${effectMetamodelTable}
 | \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImport\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge, returning an \`importId\` is enough up front, and background processing is acceptable. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
-| \`sessions.list()\`, \`sessions.create()\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Session lifecycle for this environment. |
+| \`sessions.list({ status?, sessionScope?, limit?, offset? })\`, \`sessions.create({ sessionScope? })\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Scoped, bounded session history and lifecycle for this environment. |
 
 ### \`Session\` (live runtime connection)
 
@@ -16474,7 +16871,7 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 | \`granular simulate\` | Open simulator in browser. |
 | \`granular simulate --print-url\` | Print a deep-linkable simulator URL without opening the browser. |
 | \`granular connect test --json\` | Verify auth and environment connectivity with a real session. |
-| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. |
+| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. \`session list\` defaults to 25 rows; use \`--session-scope\`, \`--subject-id\`, \`--limit\`, and \`--offset\` for deterministic paging. |
 | \`granular graphql --query '...' --json\` | Run a GraphQL query or mutation against the live graph. |
 | \`granular effects list/diff --json\` | Inspect declared versus live ready effects. |
 | \`granular job run --file ./job.ts --json\` | Execute a real runtime job from the terminal or CI. |
@@ -17154,8 +17551,8 @@ Use this for command execution, environment setup, and shipping flows.
 | \`granular graphql --query '...' --json\` | Query the live graph through the environment GraphQL API |
 | \`granular effects list --json\` | Inspect declared and live effects for an environment |
 | \`granular effects diff --json\` | Compare declared effects to live ready handlers |
-| \`granular session create --json\` | Create a fresh session for an environment |
-| \`granular session list --json\` | List indexed sessions for an environment |
+| \`granular session create --session-scope <scope> --json\` | Create a fresh, application-scoped session for an environment |
+| \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` | List one bounded page of indexed sessions |
 | \`granular session heap --json\` | Inspect session heap |
 | \`granular session doc --json\` | Inspect the Automerge-backed session document |
 | \`granular job run --file ./job.ts\` | Execute a real job against the ontology runtime |
@@ -17238,8 +17635,8 @@ Use this for runtime debugging after the ontology builds but behavior does not m
 
 | Goal | Preferred path |
 | --- | --- |
-| Create or rotate a session | \`granular session create --json\` |
-| List known sessions | \`granular session list --json\` |
+| Create or rotate a session | \`granular session create --session-scope <scope> --json\` |
+| List known sessions | \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` |
 | Inspect heap | \`granular session heap --json\` |
 | Inspect full document | \`granular session doc --json\` |
 | Verify connectivity | \`granular connect test\` |
@@ -19145,6 +19542,9 @@ function rpcTimeoutMsForMethod(method) {
       return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
     case "client.heartbeat":
     case "effects.publishCatalog":
+    case "effects.resetCatalog":
+    case "effects.addCatalog":
+    case "effects.removeCatalog":
     case "effects.refresh":
       return EFFECT_CONTROL_RPC_TIMEOUT_MS;
     case "harness.run":
@@ -19169,16 +19569,37 @@ var WSClient = class {
   tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
   reconnectAttempts = 0;
+  connectPromise = null;
+  connectionEpoch = 0;
+  cancelConnectAttempt = null;
   options;
   constructor(options) {
     this.options = options;
     this.url = options.url;
     this.sessionId = options.sessionId;
     this.token = options.token;
+    if (options.initialDocumentSnapshot) {
+      this.seedDocumentSnapshot(options.initialDocumentSnapshot);
+    }
   }
   get currentSessionId() {
     return this.sessionId;
   }
+  seedDocumentSnapshot(document) {
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+      return;
+    }
+    try {
+      this.doc = document instanceof Uint8Array ? Automerge__namespace.load(document) : Automerge__namespace.from(document);
+      this.syncState = Automerge__namespace.initSyncState();
+      this.emit("sync", this.doc);
+    } catch (error2) {
+      console.warn("[Granular] Failed to seed cached session document", error2);
+    }
+  }
+  saveDocumentSnapshot() {
+    return Automerge__namespace.save(this.doc);
+  }
   clearTokenRefreshTimer() {
     if (this.tokenRefreshTimer) {
       clearTimeout(this.tokenRefreshTimer);
@@ -19288,8 +19709,23 @@ var WSClient = class {
    * Connect to the WebSocket server
    * @returns {Promise<void>} Resolves when connection is open
    */
-  async connect() {
+  async connect(options = {}) {
+    if (this.ws?.readyState === READY_STATE_OPEN) return;
+    if (this.connectPromise) return this.connectPromise;
+    const connectPromise = this.connectAttempt(options.signal);
+    this.connectPromise = connectPromise;
+    try {
+      await connectPromise;
+    } finally {
+      if (this.connectPromise === connectPromise) {
+        this.connectPromise = null;
+      }
+    }
+  }
+  async connectAttempt(signal) {
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     const token = await this.resolveTokenForConnect();
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     this.isExplicitlyDisconnected = false;
     this.scheduleTokenRefresh();
     if (this.reconnectTimer) {
@@ -19301,7 +19737,7 @@ var WSClient = class {
       try {
         const wsModule = await import('ws');
         WebSocketClass = wsModule.default || wsModule;
-      } catch (e) {
+      } catch {
       }
     }
     if (!WebSocketClass) {
@@ -19309,83 +19745,97 @@ var WSClient = class {
         'No WebSocket implementation found. If using Node.js, please install "ws" and pass the constructor to the SDK options: { WebSocketCtor: WebSocket }.'
       );
     }
+    const epoch = ++this.connectionEpoch;
+    const wsUrl = new URL(this.url);
+    wsUrl.searchParams.set("sessionId", this.sessionId);
+    wsUrl.searchParams.set("token", token);
+    const socket = new WebSocketClass(wsUrl.toString());
+    this.ws = socket;
     return new Promise((resolve2, reject) => {
-      try {
-        const wsUrl = new URL(this.url);
-        wsUrl.searchParams.set("sessionId", this.sessionId);
-        wsUrl.searchParams.set("token", token);
-        this.ws = new WebSocketClass(wsUrl.toString());
-        if (!this.ws) throw new Error("Failed to create WebSocket");
-        const socket = this.ws;
-        if (typeof socket.on === "function") {
-          socket.on("open", () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          });
-          socket.on("message", (data) => {
-            try {
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          });
-          socket.on("error", (error2) => {
-            this.emit("error", error2);
-            if (socket.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          });
-          socket.on("close", (code, reason) => {
-            this.handleDisconnect({
-              code,
-              reason: this.normalizeReason(reason),
-              // ws does not provide wasClean on Node-style close callback
-              wasClean: code === 1e3
-            });
-          });
+      let settled = false;
+      const isCurrent = () => this.connectionEpoch === epoch && this.ws === socket;
+      const finish = (error2) => {
+        if (settled) return;
+        settled = true;
+        if (this.cancelConnectAttempt === handleAbort) {
+          this.cancelConnectAttempt = null;
+        }
+        signal?.removeEventListener("abort", handleAbort);
+        if (error2) {
+          reject(error2 instanceof Error ? error2 : new Error(String(error2)));
         } else {
-          this.ws.onopen = () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          };
-          this.ws.onmessage = (event) => {
-            try {
-              const data = event.data;
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          };
-          this.ws.onerror = (event) => {
-            const error2 = new Error("WebSocket error");
-            error2.event = event;
-            this.emit("error", error2);
-            if (this.ws?.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          };
-          this.ws.onclose = (event) => {
-            this.handleDisconnect({
-              code: event.code,
-              reason: event.reason,
-              wasClean: event.wasClean
-            });
-          };
+          resolve2();
         }
-      } catch (error2) {
-        reject(error2);
+      };
+      const closeStaleSocket = () => {
+        try {
+          socket.close(1e3, "Stale connection attempt");
+        } catch {
+        }
+      };
+      const handleAbort = () => {
+        if (isCurrent()) {
+          this.connectionEpoch += 1;
+          this.ws = null;
+        }
+        closeStaleSocket();
+        finish(new Error("WebSocket connect aborted"));
+      };
+      this.cancelConnectAttempt = handleAbort;
+      const handleOpen = () => {
+        if (!isCurrent()) {
+          closeStaleSocket();
+          return;
+        }
+        this.reconnectAttempts = 0;
+        this.emit("open", {});
+        finish();
+      };
+      const handleMessage = (data) => {
+        if (!isCurrent()) return;
+        try {
+          const text = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
+          this.handleMessage(JSON.parse(text));
+        } catch (error2) {
+          console.error("[Granular] Failed to parse message:", error2);
+        }
+      };
+      const handleError = (error2) => {
+        if (!isCurrent()) return;
+        const typedError = error2 instanceof Error ? error2 : new Error("WebSocket error");
+        this.emit("error", typedError);
+        if (socket.readyState !== READY_STATE_OPEN) finish(typedError);
+      };
+      const handleClose = (close) => {
+        if (!isCurrent()) return;
+        if (!settled) {
+          finish(
+            new Error(
+              `WebSocket closed before ready${close.code ? ` (code=${close.code})` : ""}`
+            )
+          );
+        }
+        this.handleDisconnect({
+          code: close.code,
+          reason: this.normalizeReason(close.reason),
+          wasClean: close.wasClean
+        });
+      };
+      signal?.addEventListener("abort", handleAbort, { once: true });
+      const nodeSocket = socket;
+      if (typeof nodeSocket.on === "function") {
+        nodeSocket.on("open", handleOpen);
+        nodeSocket.on("message", handleMessage);
+        nodeSocket.on("error", handleError);
+        nodeSocket.on(
+          "close",
+          (code, reason) => handleClose({ code, reason, wasClean: code === 1e3 })
+        );
+      } else {
+        socket.onopen = handleOpen;
+        socket.onmessage = (event) => handleMessage(event.data);
+        socket.onerror = handleError;
+        socket.onclose = (event) => handleClose(event);
       }
     });
   }
@@ -19403,9 +19853,58 @@ var WSClient = class {
     return void 0;
   }
   rejectPending(error2) {
-    this.messageQueue.forEach((pending) => pending.reject(error2));
+    this.messageQueue.forEach((pending) => {
+      clearTimeout(pending.timeout);
+      pending.reject(error2);
+    });
     this.messageQueue = [];
   }
+  emitReconnectErrorMessage(error2) {
+    const reconnectInfo = {
+      error: error2,
+      sessionId: this.sessionId,
+      timestamp: Date.now()
+    };
+    this.emit("reconnect_error", reconnectInfo);
+    if (this.options.onReconnectError) {
+      try {
+        this.options.onReconnectError(reconnectInfo);
+      } catch (callbackError) {
+        console.error(
+          "[Granular] onReconnectError callback failed:",
+          callbackError
+        );
+      }
+    }
+  }
+  scheduleReconnectAttempt() {
+    if (this.isExplicitlyDisconnected || this.reconnectTimer) return null;
+    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
+    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    if (this.reconnectAttempts >= maxReconnectAttempts) {
+      this.emitReconnectErrorMessage(
+        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`
+      );
+      return null;
+    }
+    this.reconnectAttempts += 1;
+    const reconnectDelayMs = Math.min(
+      3e4,
+      baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      console.log("[Granular] Attempting reconnect...");
+      this.connect().catch((error2) => {
+        console.error("[Granular] Reconnect failed:", error2);
+        this.emitReconnectErrorMessage(
+          error2 instanceof Error ? error2.message : String(error2)
+        );
+        this.scheduleReconnectAttempt();
+      });
+    }, reconnectDelayMs);
+    return reconnectDelayMs;
+  }
   buildDisconnectError(info2) {
     const details = [
       info2.code !== void 0 ? `code=${info2.code}` : void 0,
@@ -19415,8 +19914,6 @@ var WSClient = class {
     return new Error(`WebSocket disconnected${suffix}`);
   }
   handleDisconnect(close = {}) {
-    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
-    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
     const unexpected = !this.isExplicitlyDisconnected;
     const info2 = {
       code: close.code,
@@ -19436,32 +19933,9 @@ var WSClient = class {
       const disconnectError = this.buildDisconnectError(info2);
       this.rejectPending(disconnectError);
       this.emit("disconnect", info2);
-      if (this.reconnectAttempts >= maxReconnectAttempts) {
-        const reconnectInfo = {
-          error: `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
-          sessionId: this.sessionId,
-          timestamp: Date.now()
-        };
-        this.emit("reconnect_error", reconnectInfo);
-        if (this.options.onReconnectError) {
-          try {
-            this.options.onReconnectError(reconnectInfo);
-          } catch (callbackError) {
-            console.error(
-              "[Granular] onReconnectError callback failed:",
-              callbackError
-            );
-          }
-        }
-        return;
-      }
-      this.reconnectAttempts += 1;
-      const reconnectDelayMs = Math.min(
-        3e4,
-        baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
-      );
-      info2.reconnectScheduled = true;
-      info2.reconnectDelayMs = reconnectDelayMs;
+      const reconnectDelayMs = this.scheduleReconnectAttempt();
+      info2.reconnectScheduled = reconnectDelayMs !== null;
+      if (reconnectDelayMs !== null) info2.reconnectDelayMs = reconnectDelayMs;
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info2);
@@ -19472,28 +19946,6 @@ var WSClient = class {
           );
         }
       }
-      this.reconnectTimer = setTimeout(() => {
-        console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((error2) => {
-          console.error("[Granular] Reconnect failed:", error2);
-          const reconnectInfo = {
-            error: error2 instanceof Error ? error2.message : String(error2),
-            sessionId: this.sessionId,
-            timestamp: Date.now()
-          };
-          this.emit("reconnect_error", reconnectInfo);
-          if (this.options.onReconnectError) {
-            try {
-              this.options.onReconnectError(reconnectInfo);
-            } catch (callbackError) {
-              console.error(
-                "[Granular] onReconnectError callback failed:",
-                callbackError
-              );
-            }
-          }
-        });
-      }, reconnectDelayMs);
     }
   }
   handleMessage(message) {
@@ -19604,6 +20056,7 @@ var WSClient = class {
       const response = message;
       const pending = this.messageQueue.find((q) => q.id === response.id);
       if (pending) {
+        clearTimeout(pending.timeout);
         if (response.type === "rpc_error") {
           pending.reject(
             new Error(
@@ -19649,16 +20102,22 @@ var WSClient = class {
       id
     };
     return new Promise((resolve2, reject) => {
-      this.messageQueue.push({ resolve: resolve2, reject, id });
-      this.ws.send(JSON.stringify(request));
       const timeoutMs = rpcTimeoutMsForMethod(method);
-      setTimeout(() => {
+      const timeout = setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
           this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
           reject(new Error(`RPC timeout: ${method}`));
         }
       }, timeoutMs);
+      this.messageQueue.push({ resolve: resolve2, reject, id, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (error2) {
+        clearTimeout(timeout);
+        this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+        reject(error2 instanceof Error ? error2 : new Error(String(error2)));
+      }
     });
   }
   async handleIncomingRpc(request) {
@@ -19744,15 +20203,18 @@ var WSClient = class {
   /**
    * Disconnect the WebSocket and clear state
    */
-  disconnect() {
+  disconnect(options = {}) {
     this.isExplicitlyDisconnected = true;
+    this.cancelConnectAttempt?.();
+    this.cancelConnectAttempt = null;
+    this.connectionEpoch += 1;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
     this.clearTokenRefreshTimer();
     if (this.ws) {
-      this.ws.close(1e3, "Client disconnect");
+      this.ws.close(1e3, options.reason || "Client disconnect");
       this.ws = null;
     }
     this.rejectPending(new Error("Client explicitly disconnected"));
@@ -19848,8 +20310,12 @@ function normalizePrompt(rawValue) {
   const source = promptRecord || raw;
   const id = typeof source.id === "string" ? source.id : typeof raw.id === "string" ? raw.id : typeof raw.promptId === "string" ? raw.promptId : "";
   if (!id) return null;
+  const jobId = typeof source.jobId === "string" && source.jobId.trim() ? source.jobId.trim() : typeof raw.jobId === "string" && raw.jobId.trim() ? raw.jobId.trim() : void 0;
+  const turnId = typeof source.turnId === "string" && source.turnId.trim() ? source.turnId.trim() : typeof raw.turnId === "string" && raw.turnId.trim() ? raw.turnId.trim() : void 0;
   return {
     id,
+    ...jobId ? { jobId } : {},
+    ...turnId ? { turnId } : {},
     type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
@@ -19890,6 +20356,9 @@ function resolvePromptAnswer(prompt3, answer) {
 
 // src/session.ts
 var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
+function toPascalCase3(value) {
+  return value.split(/[_:\-\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
 function withPromptTranscriptTimeout(promise) {
   let timeout = null;
   return Promise.race([
@@ -19933,6 +20402,9 @@ var Session = class {
     this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
+    this.currentDomainRevision = this.extractDomainRevisionFromDoc(
+      this.client.doc
+    );
   }
   extractDomainRevisionFromDoc(doc) {
     const domain = doc?.domain;
@@ -20452,9 +20924,7 @@ var Session = class {
     if (classes && Object.keys(classes).length > 0) {
       let docs2 = "# Domain Documentation\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 classNames = Object.keys(classes).map(toPascalCase3);
       const globalNames = (globalTools || []).map((t) => t.name);
       const importLines = [
         ...classNames.map(
@@ -20468,7 +20938,7 @@ ${importLines.join("\n") || "// No generated domain imports available."}
 
 `;
       for (const [className, cls] of Object.entries(classes)) {
-        const TsName = className.charAt(0).toUpperCase() + className.slice(1);
+        const TsName = toPascalCase3(className);
         docs2 += `## ${TsName}
 
 `;
@@ -20840,6 +21310,7 @@ function normalizeJobAgentMessageEnvelope(data) {
   }
   return {
     jobId: d.jobId,
+    ...typeof d.turnId === "string" && d.turnId.trim() ? { turnId: d.turnId.trim() } : {},
     message: {
       messageId: d.messageId,
       kind: d.kind === "artifacts" ? "artifacts" : "text",
@@ -21458,6 +21929,28 @@ function asString(value) {
 function trimString(value) {
   return typeof value === "string" ? value.trim() : "";
 }
+function compactJson(value, maxLength = 320) {
+  if (value === void 0 || value === null) return void 0;
+  try {
+    const json = JSON.stringify(value);
+    if (!json || json === "undefined") return void 0;
+    return json.length > maxLength ? `${json.slice(0, maxLength)}...` : json;
+  } catch {
+    return String(value);
+  }
+}
+function artifactRecordsById(liveDoc) {
+  const artifacts = asRecord3(liveDoc?.artifacts);
+  const byId = asRecord3(artifacts?.byId) || {};
+  return Object.fromEntries(
+    Object.entries(byId).map(([artifactId, value]) => {
+      const record = asRecord3(value);
+      return record ? [artifactId, record] : null;
+    }).filter(
+      (entry) => Boolean(entry)
+    )
+  );
+}
 function normalizeShowRefs(value) {
   const record = asRecord3(value);
   if (!record) return void 0;
@@ -21474,9 +21967,106 @@ function normalizeShowRefs(value) {
     entryPaths: normalizeRefs(record.entryPaths),
     listNames: normalizeRefs(record.listNames),
     variableNames: normalizeRefs(record.variableNames),
-    fileIds: normalizeRefs(record.fileIds)
+    fileIds: normalizeRefs(record.fileIds),
+    sessionArtifactIds: normalizeRefs(record.sessionArtifactIds),
+    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions),
+    tables: Array.isArray(record.tables) ? record.tables.filter(
+      (table2) => Boolean(
+        table2 && typeof table2 === "object" && !Array.isArray(table2) && Array.isArray(table2.columns) && Array.isArray(table2.rows)
+      )
+    ) : void 0
   };
-  return show.entryPaths || show.listNames || show.variableNames || show.fileIds ? show : void 0;
+  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions || show.tables ? show : void 0;
+}
+function normalizeActionSuggestions(value) {
+  if (!Array.isArray(value)) return void 0;
+  const suggestions = [];
+  for (const item of value) {
+    const record = asRecord3(item);
+    if (!record) continue;
+    const label = trimString(record.label);
+    if (!label) continue;
+    const suggestionId = trimString(record.suggestionId) || trimString(record.id) || label;
+    suggestions.push({
+      suggestionId,
+      label,
+      ...typeof record.description === "string" ? { description: record.description } : {},
+      ...asRecord3(record.artifact) ? { artifact: asRecord3(record.artifact) } : {},
+      ...asRecord3(record.target) ? { target: asRecord3(record.target) } : {},
+      ...asRecord3(record.metadata) ? { metadata: asRecord3(record.metadata) } : {}
+    });
+  }
+  return suggestions.length ? suggestions : void 0;
+}
+var TRANSCRIPT_MESSAGE_PART_LIMIT = 128;
+var TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT = 2e5;
+var TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT = 1e3;
+var TRANSCRIPT_MESSAGE_ACTION_LIMIT = 64;
+function normalizeConversationMessageActions(value) {
+  if (!Array.isArray(value) || value.length === 0) return void 0;
+  const actions = [];
+  for (const item of value.slice(0, TRANSCRIPT_MESSAGE_ACTION_LIMIT)) {
+    const record = asRecord3(item);
+    const kind = record?.kind;
+    const label = trimString(record?.label ?? record?.title);
+    const status = record?.status;
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      continue;
+    }
+    actions.push({
+      kind,
+      label,
+      ...status === "done" || status === "queued" || status === "failed" ? { status } : {}
+    });
+  }
+  return actions.length ? actions : void 0;
+}
+function normalizeConversationMessageParts(value, canonicalContent, canonicalActions) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > TRANSCRIPT_MESSAGE_PART_LIMIT) {
+    return void 0;
+  }
+  const parts = [];
+  const canonicalActionsById = new Map(
+    (canonicalActions || []).map((action) => [
+      `${action.kind}:${action.label}`,
+      action
+    ])
+  );
+  const seenActionIds = /* @__PURE__ */ new Set();
+  let textLength = 0;
+  for (const item of value) {
+    const record = asRecord3(item);
+    if (!record) return void 0;
+    if (record.type === "text") {
+      if (typeof record.text !== "string" || record.text.length === 0) {
+        return void 0;
+      }
+      textLength += record.text.length;
+      if (textLength > TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT) return void 0;
+      parts.push({ type: "text", text: record.text });
+      continue;
+    }
+    if (record.type !== "action") return void 0;
+    const action = asRecord3(record.action);
+    const kind = action?.kind;
+    const label = trimString(action?.label);
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      return void 0;
+    }
+    const actionId = `${kind}:${label}`;
+    const canonicalAction = canonicalActionsById.get(actionId);
+    if (!canonicalAction) return void 0;
+    if (seenActionIds.has(actionId)) continue;
+    seenActionIds.add(actionId);
+    parts.push({
+      type: "action",
+      action: canonicalAction
+    });
+  }
+  const orderedText = parts.filter(
+    (part) => part.type === "text"
+  ).map((part) => part.text).join("");
+  return orderedText === canonicalContent ? parts : void 0;
 }
 function stringifyTranscriptValue(value, fallback2 = "") {
   if (typeof value === "string") {
@@ -21496,12 +22086,139 @@ function stringifyTranscriptValue(value, fallback2 = "") {
     return String(value);
   }
 }
-function buildArtifactHistory(show) {
+function latestInputEditSummary(metadata) {
+  const lastInputEdit = asRecord3(metadata.lastInputEdit);
+  if (!lastInputEdit) return null;
+  const source = asString(lastInputEdit.source) || "unknown";
+  const actor = asString(lastInputEdit.actorSubjectId) || asString(lastInputEdit.actorPermissionProfileName) || asString(lastInputEdit.jobId) || null;
+  const inputKeys = Array.isArray(lastInputEdit.changedInputKeys) ? lastInputEdit.changedInputKeys.filter(
+    (key) => typeof key === "string" && key.trim().length > 0
+  ).slice(0, 6) : [];
+  const relationshipKeys = Array.isArray(lastInputEdit.changedRelationshipKeys) ? lastInputEdit.changedRelationshipKeys.filter(
+    (key) => typeof key === "string" && key.trim().length > 0
+  ).slice(0, 6) : [];
+  const changed = [
+    inputKeys.length ? `inputs=${inputKeys.join(",")}` : null,
+    relationshipKeys.length ? `relationships=${relationshipKeys.join(",")}` : null
+  ].filter(Boolean);
+  return `lastEdit=${source}${actor ? ` by ${actor}` : ""}${changed.length ? ` (${changed.join("; ")})` : ""}`;
+}
+function artifactIssueSummary(record) {
+  const validation = asRecord3(record.validation);
+  if (!validation) return null;
+  const issues = Array.isArray(validation.issues) ? validation.issues.map((issue) => asRecord3(issue)).filter((issue) => Boolean(issue)).slice(0, 3) : [];
+  if (issues.length > 0) {
+    return `issues=${issues.map((issue) => {
+      const code = asString(issue.code) || asString(issue.kind) || "issue";
+      const path7 = asString(issue.path);
+      const message = trimString(issue.message);
+      return `${code}${path7 ? ` at ${path7}` : ""}${message ? ` (${message})` : ""}`;
+    }).join("; ")}`;
+  }
+  const error2 = trimString(validation.error) || trimString(validation.reason) || trimString(validation.message);
+  return error2 ? `validation=${error2}` : null;
+}
+function artifactExecutionSummary(metadata) {
+  const execution = asRecord3(metadata.execution);
+  if (!execution) return null;
+  const result = asRecord3(execution.result);
+  const awaiting = asString(result?.awaiting) || asString(execution.awaiting);
+  const pendingTransition = asString(result?.pendingTransition) || asString(execution.pendingTransition);
+  const approval = asRecord3(result?.approval) || asRecord3(execution.approval);
+  const approvalTarget = asString(approval?.permissionProfileName) || asString(approval?.permissionProfileId) || asString(approval?.assigneeSubjectId);
+  const error2 = trimString(execution.error);
+  const pieces = [
+    awaiting ? `awaiting=${awaiting}` : null,
+    pendingTransition ? `pendingTransition=${pendingTransition}` : null,
+    approvalTarget ? `approvalTarget=${approvalTarget}` : null,
+    error2 ? `executionError=${error2}` : null
+  ].filter(Boolean);
+  return pieces.length ? pieces.join("; ") : null;
+}
+function artifactStatePathSummary(metadata) {
+  const statePlan = asRecord3(metadata.statePlan);
+  if (!statePlan) return null;
+  const machineName = asString(statePlan.machineName);
+  const targetState = asString(statePlan.targetState);
+  const objectPath = asString(statePlan.objectPath);
+  const approvedTransitions = Array.isArray(statePlan.approvedTransitions) ? statePlan.approvedTransitions.length : 0;
+  const approvalDecisions = Array.isArray(statePlan.approvalDecisions) ? statePlan.approvalDecisions.length : 0;
+  const pieces = [
+    machineName || targetState ? `statePath=${machineName || "state_machine"}${targetState ? ` -> ${targetState}` : ""}` : null,
+    objectPath ? `objectPath=${objectPath}` : null,
+    approvedTransitions ? `approvedTransitions=${approvedTransitions}` : null,
+    approvalDecisions ? `approvalDecisions=${approvalDecisions}` : null
+  ].filter(Boolean);
+  return pieces.length ? pieces.join("; ") : null;
+}
+function artifactSummaryLine(artifactId, record) {
+  if (!record) return `- ${artifactId}: unavailable in session artifact store`;
+  const label = trimString(record.label) || artifactId;
+  const kind = asString(record.kind) || "artifact";
+  const status = asString(record.status) || "unknown";
+  const createdByJobId = asString(record.createdByJobId);
+  const target = asRecord3(record.target);
+  const metadata = asRecord3(record.metadata) || {};
+  const subArtifactIds = Array.isArray(record.subArtifactIds) ? record.subArtifactIds.filter(
+    (id) => typeof id === "string" && id.trim().length > 0
+  ).slice(0, 8) : [];
+  const relationships = compactJson(record.relationships, 220);
+  const pieces = [
+    `kind=${kind}`,
+    `status=${status}`,
+    createdByJobId ? `createdByJob=${createdByJobId}` : null,
+    target ? `target=${asString(target.className) || "record"}:${asString(target.id) || "unknown"}${asString(target.label) ? ` (${asString(target.label)})` : ""}` : null,
+    artifactStatePathSummary(metadata),
+    artifactExecutionSummary(metadata),
+    artifactIssueSummary(record),
+    latestInputEditSummary(metadata),
+    subArtifactIds.length ? `subArtifacts=${subArtifactIds.join(",")}` : null,
+    relationships ? `relationships=${relationships}` : null
+  ].filter(Boolean);
+  return `- ${artifactId}: ${label}${pieces.length ? `; ${pieces.join("; ")}` : ""}`;
+}
+function buildArtifactHistory(show, artifactsById) {
   if (!show) return void 0;
-  return `[Agent message]
+  const artifactIds = show.sessionArtifactIds || [];
+  const actionSuggestions = show.actionSuggestions || [];
+  if (artifactIds.length === 0 && actionSuggestions.length === 0) {
+    return `[Agent message]
 ${stringifyTranscriptValue({ show }, "")}`;
+  }
+  const lines = artifactIds.slice(0, 8).map(
+    (artifactId) => artifactSummaryLine(artifactId, artifactsById?.[artifactId])
+  );
+  if (artifactIds.length > 8) {
+    lines.push(`- ${artifactIds.length - 8} more artifacts omitted`);
+  }
+  if (actionSuggestions.length > 0) {
+    if (artifactIds.length > 0) lines.push("[Agent suggested actions]");
+    for (const suggestion of actionSuggestions.slice(0, 8)) {
+      lines.push(
+        `- ${suggestion.label}${suggestion.description ? `; ${suggestion.description}` : ""}`
+      );
+    }
+    if (actionSuggestions.length > 8) {
+      lines.push(`- ${actionSuggestions.length - 8} more suggestions omitted`);
+    }
+  }
+  const otherRefs = {
+    entryPaths: show.entryPaths,
+    listNames: show.listNames,
+    variableNames: show.variableNames,
+    fileIds: show.fileIds
+  };
+  const hasOtherRefs = Object.values(otherRefs).some(
+    (value) => Array.isArray(value) && value.length > 0
+  );
+  const title = artifactIds.length > 0 ? "[Agent displayed session artifacts]" : "[Agent suggested actions]";
+  return [
+    title,
+    ...lines,
+    hasOtherRefs ? `Other shown refs: ${stringifyTranscriptValue(otherRefs, "")}` : null
+  ].filter(Boolean).join("\n");
 }
-function normalizeConversationMessage(raw) {
+function normalizeConversationMessage(raw, artifactsById) {
   const record = asRecord3(raw);
   if (!record) return null;
   const role = record.role === "user" ? "user" : record.role === "assistant" ? "assistant" : null;
@@ -21509,10 +22226,18 @@ function normalizeConversationMessage(raw) {
   const content = trimString(
     record.content ?? record.reply ?? record.message ?? record.text
   );
+  const actions = role === "assistant" ? normalizeConversationMessageActions(record.actions) : void 0;
+  const parts = role === "assistant" ? normalizeConversationMessageParts(record.parts, content, actions) : void 0;
   const show = normalizeShowRefs(record.show);
   const id = asString(record.id) || crypto.randomUUID();
   const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
-  if (!content && !show) return null;
+  if (!content && !show && !actions?.length) return null;
+  const artifactHistory = buildArtifactHistory(show, artifactsById);
+  const historyContent = role === "assistant" ? content && artifactHistory ? `[Assistant reply]
+${content}
+
+${artifactHistory}` : content ? `[Assistant reply]
+${content}` : artifactHistory : void 0;
   return {
     id,
     role,
@@ -21521,8 +22246,9 @@ function normalizeConversationMessage(raw) {
     jobId: asString(record.jobId),
     promptId: asString(record.promptId),
     show,
-    historyContent: role === "assistant" ? content ? `[Assistant reply]
-${content}` : buildArtifactHistory(show) : void 0,
+    actions,
+    parts,
+    historyContent,
     source: "conversation"
   };
 }
@@ -21565,7 +22291,7 @@ ${assistantContent}`,
     return entries;
   });
 }
-function normalizeAgentMessageEntries(jobId, rawMessages) {
+function normalizeAgentMessageEntries(jobId, rawMessages, artifactsById) {
   return asArray(rawMessages).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
     (left, right) => (asNumber(left.timestamp) || asNumber(left.ts) || 0) - (asNumber(right.timestamp) || asNumber(right.ts) || 0)
   ).flatMap((message) => {
@@ -21596,14 +22322,14 @@ ${reply}`,
         timestamp,
         jobId,
         show,
-        historyContent: buildArtifactHistory(show),
+        historyContent: buildArtifactHistory(show, artifactsById),
         source: "job_agent_message"
       });
     }
     return entries;
   });
 }
-function buildJobFallbackEntries(jobId, job2, sessionHeap) {
+function buildJobFallbackEntries(jobId, job2, sessionHeap, artifactsById) {
   const timestamp = asNumber(job2.finishedAt) || asNumber(job2.startedAt) || asNumber(job2.submittedAt) || 0;
   const resultPreview = stringifyTranscriptValue(
     job2.result,
@@ -21641,7 +22367,7 @@ ${responseText}`,
       timestamp,
       jobId,
       show,
-      historyContent: buildArtifactHistory(show),
+      historyContent: buildArtifactHistory(show, artifactsById),
       source: "job_result"
     });
   }
@@ -21695,10 +22421,11 @@ function buildJobCodeEntry(jobId, job2) {
 function buildSessionTranscript(input) {
   const liveDoc = input.liveDoc || null;
   const sessionHeap = input.sessionHeap || EMPTY_HEAP;
+  const artifactsById = artifactRecordsById(liveDoc);
   const transcript = [];
   const conversationMessages = asArray(
     asRecord3(liveDoc?.conversation)?.messages
-  ).map((message) => normalizeConversationMessage(message)).filter((message) => Boolean(message));
+  ).map((message) => normalizeConversationMessage(message, artifactsById)).filter((message) => Boolean(message));
   const conversationPromptIds = new Set(
     conversationMessages.map((message) => message.promptId).filter((promptId) => Boolean(promptId))
   );
@@ -21725,7 +22452,8 @@ function buildSessionTranscript(input) {
     if (!assistantConversationJobIds.has(jobId)) {
       const agentEntries = normalizeAgentMessageEntries(
         jobId,
-        job2.agentMessages
+        job2.agentMessages,
+        artifactsById
       );
       if (agentEntries.length > 0) {
         transcript.push(...agentEntries);
@@ -21734,7 +22462,8 @@ function buildSessionTranscript(input) {
           ...buildJobFallbackEntries(
             jobId,
             job2,
-            sessionHeap
+            sessionHeap,
+            artifactsById
           )
         );
       }
@@ -21982,15 +22711,50 @@ function toRecordSearchResult(className, node) {
       return [];
     }
   ) : [];
+  const graphPathId = extractRecordIdFromGraphPath(path7, className);
+  const realIdField = fields.find(
+    (field) => normalizeGraphPathSegment(field.name) === "real_id" && typeof field.value === "string" && field.value.trim()
+  );
+  const id = typeof realIdField?.value === "string" ? realIdField.value.trim() : graphPathId;
+  const rawLabel = typeof node.label === "string" && node.label.trim() ? node.label : "";
+  if (fields.length === 0 && rawLabel && isPlaceholderRecordLabel(rawLabel, graphPathId, path7)) {
+    return null;
+  }
+  const fallbackLabel = displayLabelFromFields(fields);
+  const label = rawLabel && !isPlaceholderRecordLabel(rawLabel, id, path7) ? rawLabel : fallbackLabel || rawLabel || id;
   return {
     path: path7,
     className,
-    id: extractRecordIdFromGraphPath(path7, className),
-    label: typeof node.label === "string" && node.label.trim() ? node.label : extractRecordIdFromGraphPath(path7, className),
+    id,
+    label,
     description: typeof node.description === "string" && node.description.trim() ? node.description : null,
     fields
   };
 }
+function isPlaceholderRecordLabel(label, id, path7) {
+  const normalizedLabel = normalizeGraphPathSegment(label);
+  return normalizedLabel === normalizeGraphPathSegment(id) || normalizedLabel === normalizeGraphPathSegment(path7);
+}
+function displayLabelFromFields(fields) {
+  const preferredFieldNames = [
+    "name",
+    "title",
+    "label",
+    "display_name",
+    "file_name",
+    "number",
+    "code"
+  ];
+  for (const preferred of preferredFieldNames) {
+    const match = fields.find(
+      (field) => normalizeGraphPathSegment(field.name) === preferred && typeof field.value === "string" && field.value.trim()
+    );
+    if (typeof match?.value === "string") {
+      return match.value.trim();
+    }
+  }
+  return null;
+}
 function normalizeRecordSearchText(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
 }
@@ -22132,7 +22896,12 @@ async function recordOpenAIUsageSpend(options) {
   const metadata = {
     ...options.metadata || {},
     ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
-    usageContext: context
+    usageContext: context,
+    pricingContextTier: options.usage.pricingContextTier,
+    cacheWritePricePerMillionMicros: options.usage.cacheWritePricePerMillionMicros,
+    cacheWriteTokens: options.usage.cacheWriteTokens,
+    cacheWriteCostMicros: options.usage.cacheWriteCostMicros,
+    longContextThresholdTokens: options.usage.longContextThresholdTokens
   };
   const response = await fetch(
     `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
@@ -22203,6 +22972,18 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 }
 
 // src/client.ts
+var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
+var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
+var MAX_CONVERSATION_SESSION_LIST_OFFSET = 1e5;
+function boundedSessionListInteger(value, name, fallback2, minimum, maximum) {
+  if (value === void 0) return fallback2;
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new RangeError(
+      `Session list ${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return value;
+}
 var STANDARD_MODULES_OPERATIONS = [
   {
     create: "entity",
@@ -22239,6 +23020,26 @@ var STANDARD_MODULES_OPERATIONS = [
 var BUILTIN_MODULES = {
   standard_modules: STANDARD_MODULES_OPERATIONS
 };
+function stateNameFromMethodName(methodName) {
+  const raw = methodName.startsWith("to") ? methodName.slice(2) : methodName;
+  return raw.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+function appendQueryOptions(searchParams, query) {
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === null || typeof value === "undefined" || value === "") {
+      continue;
+    }
+    if (value instanceof Date) {
+      searchParams.set(key, value.toISOString());
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > 0) searchParams.set(key, value.join(","));
+      continue;
+    }
+    searchParams.set(key, String(value));
+  }
+}
 var DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE = 100;
 var MAX_RECORD_OBJECTS_CONCURRENCY = 16;
 var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT = 3;
@@ -22269,8 +23070,20 @@ function bodyInitFromSessionFileUpload(body) {
   return body;
 }
 var EFFECT_CATALOG_SYNC_TIMEOUT_MS = 12e4;
+var EFFECT_CATALOG_SYNC_BATCH_SIZE = 20;
 var EFFECT_CATALOG_SYNC_RETRY_COUNT = 3;
 var EFFECT_CATALOG_SYNC_RETRY_DELAY_MS = 1e3;
+function chunkItems(items, batchSize) {
+  const chunks = [];
+  for (let offset = 0; offset < items.length; offset += batchSize) {
+    chunks.push(items.slice(offset, offset + batchSize));
+  }
+  return chunks;
+}
+function isUnsupportedEffectCatalogMutation(error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return message.includes("Unknown RPC method: effects.resetCatalog") || message.includes("Unknown RPC method: effects.addCatalog") || message.includes("Method not found: effects.resetCatalog") || message.includes("Method not found: effects.addCatalog");
+}
 function planRecordObjectsChunks(records, batchSize) {
   const total = records.length;
   const size = Math.max(1, Math.min(batchSize, total));
@@ -22282,6 +23095,23 @@ function planRecordObjectsChunks(records, batchSize) {
   }
   return plans;
 }
+function preserveRecordObjectRealId(record) {
+  const realId = record.id.trim();
+  if (!realId) {
+    return record;
+  }
+  const fields = record.fields || {};
+  if (typeof fields.real_id === "string" && fields.real_id.trim()) {
+    return record;
+  }
+  return {
+    ...record,
+    fields: {
+      ...fields,
+      real_id: realId
+    }
+  };
+}
 function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
   if (!attachedClass) {
@@ -22492,7 +23322,7 @@ var Environment = class _Environment {
   }
   get sessions() {
     return {
-      list: async (options) => this.listSessions(options?.status || "active"),
+      list: async (options = {}) => this.listSessions(options),
       create: async (options) => this.createSession(options),
       connect: async (sessionId, options) => this.connectSession(sessionId, options),
       reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
@@ -22519,11 +23349,105 @@ var Environment = class _Environment {
       getAwaitingCount: async () => this.getAwaitingRecordCount()
     };
   }
+  /**
+   * Mirror product-owned workflow state into Granular without making Granular
+   * own the customer application's state machine.
+   */
+  async recordState(input) {
+    const { machine, state, ...target } = input;
+    if (!machine.trim()) {
+      throw new Error("State update requires a machine name");
+    }
+    if (!state.trim()) {
+      throw new Error("State update requires a state");
+    }
+    return this.recordObject({
+      className: target.className,
+      id: target.id,
+      ...target.label ? { label: target.label } : {},
+      ...target.fields ? { fields: target.fields } : {},
+      ...target.relationships ? { relationships: target.relationships } : {},
+      states: {
+        [machine.trim()]: {
+          state: state.trim(),
+          ...target.source ? { source: target.source } : {},
+          ...target.cause ? { cause: target.cause } : {},
+          ...target.actorId ? { actorId: target.actorId } : {},
+          ...target.observedAt !== void 0 ? { observedAt: target.observedAt } : {},
+          ...target.force !== void 0 ? { force: target.force } : {},
+          ...target.metadata ? { metadata: target.metadata } : {}
+        }
+      }
+    });
+  }
+  /**
+   * Mirror product-owned workflow state into Granular without making Granular
+   * own the customer application's state machine.
+   *
+   * Example:
+   * `await env.recordState({ className: "spend_request", id, machine: "lifecycle", state: "policy_review", source: "customer_backend" })`
+   */
+  state(target) {
+    const observe = async (machineName, stateName, input = {}) => {
+      const observedState = input.observedState || input.state || stateName;
+      if (!observedState) {
+        throw new Error("State observation requires a target state");
+      }
+      return this.recordState({
+        ...target,
+        machine: machineName,
+        state: observedState,
+        ...input.source ? { source: input.source } : {},
+        ...input.cause ? { cause: input.cause } : {},
+        ...input.actorId ? { actorId: input.actorId } : {},
+        ...input.observedAt !== void 0 ? { observedAt: input.observedAt } : {},
+        ...input.force !== void 0 ? { force: input.force } : {},
+        ...input.metadata ? { metadata: input.metadata } : {}
+      });
+    };
+    return new Proxy(
+      {},
+      {
+        get: (_target, machineProperty) => {
+          if (typeof machineProperty !== "string") return void 0;
+          return new Proxy(
+            {},
+            {
+              get: (_machineTarget, stateProperty) => {
+                if (stateProperty === "to") {
+                  return (stateName, input) => observe(machineProperty, stateName, input || {});
+                }
+                if (typeof stateProperty !== "string") return void 0;
+                return (input) => observe(
+                  machineProperty,
+                  stateNameFromMethodName(stateProperty),
+                  input || {}
+                );
+              }
+            }
+          );
+        }
+      }
+    );
+  }
   get feedback() {
     return {
       list: async () => this.listFeedback()
     };
   }
+  get manualActions() {
+    return {
+      record: (input) => this.recordManualAction(input),
+      list: (options = {}) => this.listManualActions(options),
+      suggest: (options = {}) => this.suggestManualActions(options)
+    };
+  }
+  get artifactApprovals() {
+    return {
+      list: (options = {}) => this.listArtifactApprovals(options),
+      decide: (approvalTaskId, input) => this.decideArtifactApproval(approvalTaskId, input)
+    };
+  }
   /**
    * Sessionless environments do not own a live transport, so disconnecting the
    * environment handle itself is a no-op. This keeps the public surface
@@ -22533,17 +23457,12 @@ var Environment = class _Environment {
    */
   async disconnect() {
   }
-  async listSessions(status = "active") {
-    if (status === "all") {
-      const [active, closed] = await Promise.all([
-        this.granular.listOpenSessions({ environmentId: this.environmentId }),
-        this.granular.listClosedSessions({ environmentId: this.environmentId })
-      ]);
-      return [...active, ...closed].sort(
-        (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
-      );
-    }
-    return status === "closed" ? this.granular.listClosedSessions({ environmentId: this.environmentId }) : this.granular.listOpenSessions({ environmentId: this.environmentId });
+  async listSessions(optionsOrStatus = {}) {
+    const options = typeof optionsOrStatus === "string" ? { status: optionsOrStatus } : optionsOrStatus;
+    return this.granular.listSessions({
+      ...options,
+      environmentId: this.environmentId
+    });
   }
   async getUserEnvironmentState(options = {}) {
     return this.granular.getUserEnvironmentState({
@@ -22561,6 +23480,7 @@ var Environment = class _Environment {
     return this.granular.createSession({
       environmentId: this.environmentId,
       clientId: options?.clientId,
+      sessionScope: options?.sessionScope,
       initialHeap: options?.initialHeap
     });
   }
@@ -22602,6 +23522,50 @@ var Environment = class _Environment {
     const response = await this.controlPlaneRequest(`/control/environments/${this.environmentId}/feedback`);
     return Array.isArray(response.items) ? response.items : [];
   }
+  async recordManualAction(input) {
+    const body = {
+      ...input,
+      ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+    };
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/manual-actions`,
+      {
+        method: "POST",
+        body: JSON.stringify(body)
+      }
+    );
+  }
+  async listManualActions(options = {}) {
+    const query = new URLSearchParams();
+    appendQueryOptions(query, options);
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return this.controlPlaneRequest(`/control/environments/${this.environmentId}/manual-actions${suffix}`);
+  }
+  async suggestManualActions(options = {}) {
+    const query = new URLSearchParams();
+    appendQueryOptions(query, options);
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/manual-actions/suggestions${suffix}`
+    );
+  }
+  async listArtifactApprovals(options = {}) {
+    const query = new URLSearchParams();
+    appendQueryOptions(query, options);
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/artifact-approvals${suffix}`
+    );
+  }
+  async decideArtifactApproval(approvalTaskId, input) {
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/artifact-approvals/${encodeURIComponent(approvalTaskId)}/decide`,
+      {
+        method: "POST",
+        body: JSON.stringify(input)
+      }
+    );
+  }
   getRuntimeBaseUrl() {
     return deriveRuntimeBaseUrl(this._apiEndpoint);
   }
@@ -23426,10 +24390,11 @@ var Environment = class _Environment {
     if (!Array.isArray(records) || records.length === 0) {
       return [];
     }
+    const recordsToWrite = records.map(preserveRecordObjectRealId);
     const batchSize = Math.max(
       1,
       Math.min(
-        records.length,
+        recordsToWrite.length,
         options?.batchSize ?? DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE
       )
     );
@@ -23437,8 +24402,8 @@ var Environment = class _Environment {
       MAX_RECORD_OBJECTS_CONCURRENCY,
       Math.max(1, options?.concurrency ?? 1)
     );
-    const plans = planRecordObjectsChunks(records, batchSize);
-    const total = records.length;
+    const plans = planRecordObjectsChunks(recordsToWrite, batchSize);
+    const total = recordsToWrite.length;
     const results = new Array(total);
     const onChunk = options?.onChunkComplete;
     for (let waveStart = 0; waveStart < plans.length; waveStart += concurrency) {
@@ -23509,12 +24474,13 @@ var Environment = class _Environment {
    * synchronous upserts and fine-grained chunk progress via **`onChunkComplete`**.
    */
   async enqueueRecordImport(records, options = {}) {
+    const recordsToImport = records.map(preserveRecordObjectRealId);
     return this.controlPlaneRequest(
       `/control/environments/${this.environmentId}/record-imports`,
       {
         method: "POST",
         body: JSON.stringify({
-          records,
+          records: recordsToImport,
           batchSize: options.batchSize,
           setupRunId: options.setupRunId,
           writeMode: options.writeMode
@@ -23622,11 +24588,7 @@ var EnvironmentSession = class extends Session {
   }
   buildSessionDataUrl(path7, query) {
     const searchParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(query || {})) {
-      if (value !== null && typeof value !== "undefined" && value !== "") {
-        searchParams.set(key, String(value));
-      }
-    }
+    appendQueryOptions(searchParams, query);
     const queryString = searchParams.toString();
     return `${this.environment.runtimeBaseUrl}${this.sessionDataRoutePrefix}/${encodeURIComponent(this.sessionId)}${path7}${queryString ? `?${queryString}` : ""}`;
   }
@@ -23709,9 +24671,108 @@ var EnvironmentSession = class extends Session {
       ),
       get: (jobId) => this.sessionDataRequest(
         `/jobs/${encodeURIComponent(jobId)}`
+      ),
+      latest: async (options = {}) => {
+        const page = await this.sessionDataRequest("/jobs", {
+          status: options.status || "all",
+          latest: true,
+          limit: 1
+        });
+        return page.items[0] || null;
+      }
+    };
+  }
+  get artifacts() {
+    return {
+      list: (options = {}) => {
+        const queryOptions = { ...options };
+        if (options.target) {
+          queryOptions.targetClassName = options.target.className;
+          queryOptions.targetId = options.target.id;
+          delete queryOptions.target;
+        }
+        return this.sessionDataRequest("/artifacts", queryOptions);
+      },
+      listForLatestJob: (options = {}) => this.artifacts.list({
+        ...options,
+        latestJob: true
+      }),
+      get: (artifactId) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}`
+      ),
+      create: (artifact) => this.sessionDataRequest(
+        "/artifacts",
+        void 0,
+        {
+          method: "POST",
+          body: artifact
+        }
+      ),
+      updateInputs: (artifactId, patch) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}`,
+        void 0,
+        {
+          method: "PATCH",
+          body: patch
+        }
+      ),
+      validate: (artifactId) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/validate`,
+        void 0,
+        { method: "POST" }
+      ),
+      execute: (artifactId, options) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/execute`,
+        void 0,
+        { method: "POST", body: options }
+      ),
+      approve: (artifactId, options) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/approve`,
+        void 0,
+        { method: "POST", body: options }
+      ),
+      cancel: (artifactId) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/cancel`,
+        void 0,
+        { method: "POST" }
       )
     };
   }
+  get manualActions() {
+    const useDelegatedBrowserRoute = this.sessionDataRoutePrefix === "/sdk/browser-sessions";
+    return {
+      record: (input) => useDelegatedBrowserRoute ? this.sessionDataRequest(
+        "/manual-actions",
+        void 0,
+        {
+          method: "POST",
+          body: { ...input, sessionId: this.sessionId }
+        }
+      ) : this.environment.manualActions.record({
+        ...input,
+        sessionId: this.sessionId
+      }),
+      list: (options = {}) => useDelegatedBrowserRoute ? this.sessionDataRequest("/manual-actions", { ...options, sessionId: this.sessionId }) : this.environment.manualActions.list({
+        ...options,
+        sessionId: this.sessionId
+      }),
+      suggest: (options = {}) => useDelegatedBrowserRoute ? this.sessionDataRequest(
+        "/manual-actions/suggestions",
+        options
+      ) : this.environment.manualActions.suggest(options)
+    };
+  }
+  get artifactApprovals() {
+    const useDelegatedBrowserRoute = this.sessionDataRoutePrefix === "/sdk/browser-sessions";
+    return {
+      list: (options = {}) => useDelegatedBrowserRoute ? this.sessionDataRequest("/artifact-approvals", options) : this.environment.artifactApprovals.list(options),
+      decide: (approvalTaskId, input) => useDelegatedBrowserRoute ? this.sessionDataRequest(
+        `/artifact-approvals/${encodeURIComponent(approvalTaskId)}/decide`,
+        void 0,
+        { method: "POST", body: input }
+      ) : this.environment.artifactApprovals.decide(approvalTaskId, input)
+    };
+  }
   get files() {
     return {
       list: (options = {}) => this.sessionDataRequest(
@@ -23792,13 +24853,16 @@ var EnvironmentSession = class extends Session {
   get transcript() {
     return {
       list: async (options = {}) => {
-        const [messages, jobs, entries, lists] = await Promise.all([
+        const [messages, jobs, entries, lists, artifacts] = await Promise.all([
           this.collectAllSessionItems(this.messages.list),
           this.collectAllSessionItems(
             (pageOptions) => this.jobs.list({ ...pageOptions, status: "all" })
           ),
           this.collectAllSessionItems(this.heap.entries.list),
-          this.collectAllSessionItems(this.heap.lists.list)
+          this.collectAllSessionItems(this.heap.lists.list),
+          this.collectAllSessionItems(
+            (pageOptions) => this.artifacts.list({ ...pageOptions, status: "all" })
+          )
         ]);
         const liveDoc = {
           conversation: { messages },
@@ -23812,6 +24876,21 @@ var EnvironmentSession = class extends Session {
                 (entry) => Boolean(entry)
               )
             )
+          },
+          artifacts: {
+            byId: Object.fromEntries(
+              artifacts.map((artifact) => {
+                return artifact?.artifactId ? [
+                  artifact.artifactId,
+                  artifact
+                ] : null;
+              }).filter(
+                (entry) => Boolean(entry)
+              )
+            ),
+            order: artifacts.map((artifact) => artifact?.artifactId).filter(
+              (artifactId) => Boolean(artifactId)
+            )
           }
         };
         const heap = normalizeHeapSnapshot({
@@ -23888,6 +24967,12 @@ var EnvironmentSession = class extends Session {
   async recordObject(options) {
     return this.environment.recordObject(options);
   }
+  async recordState(input) {
+    return this.environment.recordState(input);
+  }
+  state(target) {
+    return this.environment.state(target);
+  }
   async recordObjects(records, options) {
     return this.environment.recordObjects(records, options);
   }
@@ -23958,7 +25043,7 @@ var EnvironmentSession = class extends Session {
    * Close only the socket transport without sending `client.goodbye`.
    */
   disconnectTransport() {
-    this.client.disconnect();
+    this.client.disconnect({ reason: "Transport detach" });
   }
   /**
    * Backwards-compatible alias for `disconnect()`.
@@ -24353,16 +25438,71 @@ var Granular = class _Granular {
     };
   }
   /**
-   * List active (open) sessions for an environment — each session is one agent conversation thread.
+   * List indexed sessions using ownership filters and bounded pagination.
+   */
+  async listSessions(options) {
+    const environmentId = options.environmentId?.trim();
+    const sandboxId = options.sandboxId?.trim();
+    const subjectId = options.subjectId?.trim();
+    if (!environmentId && !sandboxId && !subjectId) {
+      throw new Error(
+        "listSessions() requires environmentId, sandboxId, or subjectId so history cannot be scanned accidentally."
+      );
+    }
+    const status = options.status || "active";
+    const allowedStatuses = /* @__PURE__ */ new Set([
+      "active",
+      "closed",
+      "expired",
+      "failed",
+      "timeout",
+      "all"
+    ]);
+    if (!allowedStatuses.has(status)) {
+      throw new Error(`Unsupported session status: ${String(status)}`);
+    }
+    const limit = boundedSessionListInteger(
+      options.limit,
+      "limit",
+      DEFAULT_CONVERSATION_SESSION_LIST_LIMIT,
+      1,
+      MAX_CONVERSATION_SESSION_LIST_LIMIT
+    );
+    const offset = boundedSessionListInteger(
+      options.offset,
+      "offset",
+      0,
+      0,
+      MAX_CONVERSATION_SESSION_LIST_OFFSET
+    );
+    const query = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset)
+    });
+    if (environmentId) query.set("environmentId", environmentId);
+    if (sandboxId) query.set("sandboxId", sandboxId);
+    if (subjectId) query.set("userId", subjectId);
+    if (options.sessionScope?.trim()) {
+      query.set("sessionScope", options.sessionScope.trim());
+    }
+    if (status !== "all") query.set("status", status);
+    const res = await this.request(
+      `/control/sessions?${query.toString()}`
+    );
+    const items = Array.isArray(res.items) ? res.items : [];
+    return items.map((row) => this.normalizeConversationSession(row));
+  }
+  /**
+   * List active (open) sessions for an environment.
    */
   async listOpenSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "active");
+    return this.listSessions({ ...filters, status: "active" });
   }
   /**
    * List closed sessions for an environment (conversations that have disconnected).
    */
   async listClosedSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "closed");
+    return this.listSessions({ ...filters, status: "closed" });
   }
   async getUserEnvironmentState(options) {
     const query = new URLSearchParams({
@@ -24397,14 +25537,6 @@ var Granular = class _Granular {
     });
     return result.readAtBySessionId || {};
   }
-  async listSessionsForEnvironment(environmentId, status) {
-    const query = new URLSearchParams({ environmentId, status });
-    const res = await this.request(
-      `/control/sessions?${query.toString()}`
-    );
-    const items = Array.isArray(res.items) ? res.items : [];
-    return items.map((row) => this.normalizeConversationSession(row));
-  }
   normalizeConversationSession(row) {
     const sessionId = String(row.sessionId ?? row.session_id ?? "");
     const environmentId = String(row.environmentId ?? row.environment_id ?? "");
@@ -24463,6 +25595,7 @@ var Granular = class _Granular {
    */
   async createSession(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const sessionScope = options.sessionScope?.trim() || void 0;
     await this.activateEnvironment(options.environmentId);
     const envData = await this.environments.get(options.environmentId);
     const environment = this.bindEnvironmentHandle(envData);
@@ -24471,6 +25604,8 @@ var Granular = class _Granular {
       body: JSON.stringify({
         environmentId: options.environmentId,
         clientId,
+        sessionScope,
+        capabilities: sessionScope ? { sessionScope } : void 0,
         initialHeap: options.initialHeap
       })
     });
@@ -24715,15 +25850,43 @@ var Granular = class _Granular {
     const effects2 = Array.from(
       this.getSandboxEffectMap(host.sandboxId).values()
     ).map((effect) => this.serializeEffect(effect));
-    const result = await withTimeout(
-      host.wsClient.call("effects.publishCatalog", {
-        effects: effects2
-      }),
-      EFFECT_CATALOG_SYNC_TIMEOUT_MS,
-      `effects.publishCatalog for sandbox ${host.sandboxId}`
-    );
-    const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
-    const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
+    let acceptedCount = 0;
+    const rejected = [];
+    try {
+      await withTimeout(
+        host.wsClient.call("effects.resetCatalog", {}),
+        EFFECT_CATALOG_SYNC_TIMEOUT_MS,
+        `effects.resetCatalog for sandbox ${host.sandboxId}`
+      );
+      for (const batch of chunkItems(effects2, EFFECT_CATALOG_SYNC_BATCH_SIZE)) {
+        const result = await withTimeout(
+          host.wsClient.call("effects.addCatalog", {
+            effects: batch
+          }),
+          EFFECT_CATALOG_SYNC_TIMEOUT_MS,
+          `effects.addCatalog for sandbox ${host.sandboxId}`
+        );
+        acceptedCount += typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
+        if (Array.isArray(result?.rejected)) {
+          rejected.push(...result.rejected);
+        }
+      }
+    } catch (error2) {
+      if (!isUnsupportedEffectCatalogMutation(error2)) {
+        throw error2;
+      }
+      const result = await withTimeout(
+        host.wsClient.call("effects.publishCatalog", {
+          effects: effects2
+        }),
+        EFFECT_CATALOG_SYNC_TIMEOUT_MS,
+        `effects.publishCatalog for sandbox ${host.sandboxId}`
+      );
+      acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
+      if (Array.isArray(result?.rejected)) {
+        rejected.push(...result.rejected);
+      }
+    }
     if (acceptedCount === 0 && rejected.length > 0) {
       const detail = rejected.map(
         (entry) => `${entry.name || "unknown"}: ${entry.reason || "rejected"}`
@@ -25764,15 +26927,22 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find(
-    (environment) => matchesEnvironmentName(environment, environmentName)
+  const matchingEnvironments = environments.filter(
+    (environment) => matchesEnvironmentName(environment, environmentName) && (!options.subjectId || environment.subjectId === options.subjectId)
   );
+  if (matchingEnvironments.length > 1) {
+    throw new Error(
+      `Environment slot \`${environmentName}\` matches ${matchingEnvironments.length} subject environments. Pass --environment-id or --subject-id so session history cannot resolve to an arbitrary user.`
+    );
+  }
+  const existing = matchingEnvironments[0];
   if (existing) {
     return existing;
   }
   if (!options.createIfMissing) {
+    const subjectSuffix = options.subjectId ? ` for subject \`${options.subjectId}\`` : "";
     throw new Error(
-      `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
+      `No environment named \`${environmentName}\`${subjectSuffix} found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
   const connection = await granular.connect({
@@ -25783,17 +26953,15 @@ async function resolveEnvironmentData(granular, options) {
   });
   return await granular.environments.get(connection.environmentId);
 }
-async function listSessionsForEnvironment(granular, environmentId, status) {
-  if (status === "all") {
-    const [active, closed] = await Promise.all([
-      granular.listOpenSessions({ environmentId }),
-      granular.listClosedSessions({ environmentId })
-    ]);
-    return [...active, ...closed].sort((left, right) => {
-      return Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt);
-    });
-  }
-  return status === "closed" ? granular.listClosedSessions({ environmentId }) : granular.listOpenSessions({ environmentId });
+async function listSessionsForEnvironment(granular, environmentId, options) {
+  return granular.listSessions({
+    environmentId,
+    status: options.status,
+    sessionScope: options.sessionScope,
+    subjectId: options.subjectId,
+    limit: options.limit,
+    offset: options.offset
+  });
 }
 async function connectRuntime(options) {
   if (options.sessionId) {
@@ -25906,6 +27074,19 @@ async function connectTestCommand(options) {
 }
 
 // src/cli/commands/session.ts
+function parseSessionListInteger(value, name) {
+  const fallback2 = name === "limit" ? 25 : 0;
+  const minimum = name === "limit" ? 1 : 0;
+  const maximum = name === "limit" ? 500 : 1e5;
+  if (value === void 0 || value === "") return fallback2;
+  const parsed = typeof value === "number" ? value : Number.parseInt(value.trim(), 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== String(value).trim() || parsed < minimum || parsed > maximum) {
+    throw new Error(
+      `--${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return parsed;
+}
 function printValue(value, emitJson) {
   const json = JSON.stringify(value, null, 2);
   if (emitJson) {
@@ -25990,7 +27171,8 @@ async function sessionCreateCommand(options) {
     createIfMissing: true
   });
   const environment = await granular.createSession({
-    environmentId: envData.environmentId
+    environmentId: envData.environmentId,
+    sessionScope: options.sessionScope
   });
   try {
     const payload = {
@@ -25999,6 +27181,7 @@ async function sessionCreateCommand(options) {
       environmentId: environment.environmentId,
       environment: environment.tag || envData.tag?.name || envData.buildPolicy.tagName || requestedEnvironment,
       sessionId: environment.sessionId,
+      sessionScope: options.sessionScope?.trim() || null,
       subjectId: environment.subjectId,
       versionId: environment.versionId
     };
@@ -26013,6 +27196,7 @@ async function sessionCreateCommand(options) {
       Environment: payload.environment,
       "Environment ID": payload.environmentId,
       "Session ID": payload.sessionId,
+      "Session scope": payload.sessionScope || "unscoped",
       "Subject ID": payload.subjectId,
       "Version ID": payload.versionId
     });
@@ -26028,6 +27212,21 @@ async function sessionCreateCommand(options) {
 async function sessionListCommand(options) {
   const emitJson = options.json === true;
   const status = options.status ?? "active";
+  const allowedStatuses = /* @__PURE__ */ new Set([
+    "active",
+    "closed",
+    "expired",
+    "failed",
+    "timeout",
+    "all"
+  ]);
+  if (!allowedStatuses.has(status)) {
+    throw new Error(
+      "--status must be one of active, closed, expired, failed, timeout, or all."
+    );
+  }
+  const limit = parseSessionListInteger(options.limit, "limit");
+  const offset = parseSessionListInteger(options.offset, "offset");
   const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
@@ -26037,18 +27236,33 @@ async function sessionListCommand(options) {
     ontology: options.ontology,
     environment: requestedEnvironment,
     environmentId: options.environmentId,
+    subjectId: options.subjectId,
     createIfMissing: false
   });
   const items = await listSessionsForEnvironment(
     granular,
     environmentData.environmentId,
-    status
+    {
+      status,
+      sessionScope: options.sessionScope?.trim() || void 0,
+      subjectId: options.subjectId?.trim() || void 0,
+      limit,
+      offset
+    }
   );
   const payload = {
     ontologyId: environmentData.sandboxId,
     environmentId: environmentData.environmentId,
     environment: environmentData.tag?.name || environmentData.buildPolicy.tagName || requestedEnvironment,
     status,
+    sessionScope: options.sessionScope?.trim() || null,
+    page: {
+      limit,
+      offset,
+      returned: items.length,
+      mayHaveMore: items.length === limit,
+      nextOffset: items.length === limit ? offset + items.length : null
+    },
     items
   };
   if (emitJson) {
@@ -26071,6 +27285,9 @@ async function sessionListCommand(options) {
       item.lastSeenAt
     ])
   );
+  info(
+    `Showing ${items.length} session${items.length === 1 ? "" : "s"} from offset ${offset}.` + (items.length === limit ? ` Use --offset ${offset + items.length} for the next page.` : "")
+  );
   console.log();
 }
 
@@ -26977,6 +28194,9 @@ session.command("create").description(
   "--permissions <list>",
   "Comma-separated permission profile to ensure when a named environment needs to be created",
   "allow-all"
+).option(
+  "--session-scope <scope>",
+  "Application-owned history scope to persist on the new session"
 ).option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
@@ -26987,7 +28207,7 @@ session.command("create").description(
     }
   }
 );
-session.command("list").description("List indexed sessions for an environment").option(
+session.command("list").description("List one bounded page of indexed sessions for an environment").option(
   "--ontology <ontologyId>",
   "Override the ontology id from .granularrc"
 ).option(
@@ -26997,11 +28217,17 @@ session.command("list").description("List indexed sessions for an environment").
 ).option(
   "--environment-id <environmentId>",
   "List sessions for this exact environment id"
+).option(
+  "--subject-id <subjectId>",
+  "Resolve and constrain history to this internal Granular subject id"
+).option(
+  "--session-scope <scope>",
+  "Return only sessions owned by this application history scope"
 ).option(
   "--status <status>",
-  "Session status filter: active|closed|all",
+  "Session status: active|closed|expired|failed|timeout|all",
   "active"
-).option("--json", "Print machine-readable JSON").action(
+).option("--limit <count>", "Rows to return (1-500)", "25").option("--offset <count>", "Rows to skip (0-100000)", "0").option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
       await sessionListCommand(options);