@granular-software/sdk 0.4.48 → 0.4.50

package/dist/cli/index.js

@@ -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,7 +15617,7 @@ function buildStateMachineModelMutations(modelPath, machines) {
           transition.name
         )}, from: ${JSON.stringify(transition.from)}, to: ${JSON.stringify(
           transition.to
-        )}) { name } } } }`
+        )}${transitionMetadataGraphqlArgs(transition)}) { name } } } }`
       });
     }
   }
@@ -15413,7 +15644,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 +15740,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 +15855,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 +15873,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 +15893,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
 
       type StateMachineState {
         name: String!
+        label: String
+        description: String
         is_final: Boolean!
       }
 
@@ -15575,6 +15902,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 +15962,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,
+            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
+                to,
+                {
+                  label,
+                  description,
+                  actionJson: action_json,
+                  assigneeJson: assignee_json,
+                  requirementsJson: requirements_json,
+                  permissionJson: permission_json,
+                  risk,
+                  expectedOutcomeJson: expected_outcome_json
+                }
               )
             );
             return value;
@@ -15662,16 +16021,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 +16118,14 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             name
             from { name }
             to { name }
+            label
+            description
+            action_json
+            assignee_json
+            requirements_json
+            permission_json
+            risk
+            expected_outcome_json
           }
         }`
       ]
@@ -19145,6 +19533,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":
@@ -19890,6 +20281,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([
@@ -20452,9 +20846,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 +20860,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}
 
 `;
@@ -20689,6 +21081,9 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     this.client.on("harness.model_stream", (data) => {
       this.emit("harness:model_stream", data);
     });
+    this.client.on("harness.text_response.delta", (data) => {
+      this.emit("harness:text_response_delta", data);
+    });
     this.client.on("job.agent_message", (data) => {
       const normalized = normalizeJobAgentMessageEnvelope(data);
       if (!normalized) return;
@@ -21455,6 +21850,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;
@@ -21471,9 +21888,31 @@ 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)
   };
-  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 : 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;
 }
 function stringifyTranscriptValue(value, fallback2 = "") {
   if (typeof value === "string") {
@@ -21493,12 +21932,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;
@@ -21510,6 +22076,12 @@ function normalizeConversationMessage(raw) {
   const id = asString(record.id) || crypto.randomUUID();
   const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
   if (!content && !show) 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,
@@ -21518,8 +22090,7 @@ function normalizeConversationMessage(raw) {
     jobId: asString(record.jobId),
     promptId: asString(record.promptId),
     show,
-    historyContent: role === "assistant" ? content ? `[Assistant reply]
-${content}` : buildArtifactHistory(show) : void 0,
+    historyContent,
     source: "conversation"
   };
 }
@@ -21562,7 +22133,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) => {
@@ -21593,14 +22164,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,
@@ -21638,7 +22209,7 @@ ${responseText}`,
       timestamp,
       jobId,
       show,
-      historyContent: buildArtifactHistory(show),
+      historyContent: buildArtifactHistory(show, artifactsById),
       source: "job_result"
     });
   }
@@ -21692,10 +22263,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))
   );
@@ -21722,7 +22294,8 @@ function buildSessionTranscript(input) {
     if (!assistantConversationJobIds.has(jobId)) {
       const agentEntries = normalizeAgentMessageEntries(
         jobId,
-        job2.agentMessages
+        job2.agentMessages,
+        artifactsById
       );
       if (agentEntries.length > 0) {
         transcript.push(...agentEntries);
@@ -21731,7 +22304,8 @@ function buildSessionTranscript(input) {
           ...buildJobFallbackEntries(
             jobId,
             job2,
-            sessionHeap
+            sessionHeap,
+            artifactsById
           )
         );
       }
@@ -21979,15 +22553,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();
 }
@@ -22236,6 +22845,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;
@@ -22266,8 +22895,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));
@@ -22279,6 +22920,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) {
@@ -22516,11 +23174,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
@@ -22599,6 +23351,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);
   }
@@ -23423,10 +24219,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
       )
     );
@@ -23434,8 +24231,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) {
@@ -23506,12 +24303,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
@@ -23619,11 +24417,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}` : ""}`;
   }
@@ -23706,9 +24500,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(
@@ -23789,13 +24682,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 },
@@ -23809,6 +24705,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({
@@ -23885,6 +24796,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);
   }
@@ -24712,15 +25629,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"}`