@granular-software/sdk 0.4.48 → 0.4.50

package/dist/agent-evals.mjs

@@ -4019,6 +4019,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":
@@ -4764,6 +4767,9 @@ function resolvePromptAnswer(prompt, answer) {
 
 // src/session.ts
 var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
+function toPascalCase(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([
@@ -5326,9 +5332,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(toPascalCase);
       const globalNames = (globalTools || []).map((t) => t.name);
       const importLines = [
         ...classNames.map(
@@ -5342,7 +5346,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 = toPascalCase(className);
         docs2 += `## ${TsName}
 
 `;
@@ -5563,6 +5567,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;
@@ -6329,6 +6336,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;
@@ -6345,9 +6374,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, fallback = "") {
   if (typeof value === "string") {
@@ -6367,12 +6418,139 @@ function stringifyTranscriptValue(value, fallback = "") {
     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 path2 = asString(issue.path);
+      const message = trimString(issue.message);
+      return `${code}${path2 ? ` at ${path2}` : ""}${message ? ` (${message})` : ""}`;
+    }).join("; ")}`;
+  }
+  const error = trimString(validation.error) || trimString(validation.reason) || trimString(validation.message);
+  return error ? `validation=${error}` : 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 error = trimString(execution.error);
+  const pieces = [
+    awaiting ? `awaiting=${awaiting}` : null,
+    pendingTransition ? `pendingTransition=${pendingTransition}` : null,
+    approvalTarget ? `approvalTarget=${approvalTarget}` : null,
+    error ? `executionError=${error}` : 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;
@@ -6384,6 +6562,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,
@@ -6392,8 +6576,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"
   };
 }
@@ -6436,7 +6619,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) => {
@@ -6467,14 +6650,14 @@ ${reply}`,
         timestamp,
         jobId,
         show,
-        historyContent: buildArtifactHistory(show),
+        historyContent: buildArtifactHistory(show, artifactsById),
         source: "job_agent_message"
       });
     }
     return entries;
   });
 }
-function buildJobFallbackEntries(jobId, job, sessionHeap) {
+function buildJobFallbackEntries(jobId, job, sessionHeap, artifactsById) {
   const timestamp = asNumber(job.finishedAt) || asNumber(job.startedAt) || asNumber(job.submittedAt) || 0;
   const resultPreview = stringifyTranscriptValue(
     job.result,
@@ -6512,7 +6695,7 @@ ${responseText}`,
       timestamp,
       jobId,
       show,
-      historyContent: buildArtifactHistory(show),
+      historyContent: buildArtifactHistory(show, artifactsById),
       source: "job_result"
     });
   }
@@ -6566,10 +6749,11 @@ function buildJobCodeEntry(jobId, job) {
 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))
   );
@@ -6596,7 +6780,8 @@ function buildSessionTranscript(input) {
     if (!assistantConversationJobIds.has(jobId)) {
       const agentEntries = normalizeAgentMessageEntries(
         jobId,
-        job.agentMessages
+        job.agentMessages,
+        artifactsById
       );
       if (agentEntries.length > 0) {
         transcript.push(...agentEntries);
@@ -6605,7 +6790,8 @@ function buildSessionTranscript(input) {
           ...buildJobFallbackEntries(
             jobId,
             job,
-            sessionHeap
+            sessionHeap,
+            artifactsById
           )
         );
       }
@@ -10771,16 +10957,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),
@@ -10847,6 +11124,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(),
@@ -10877,6 +11164,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(),
@@ -11104,9 +11392,10 @@ 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 toPascalCase(value) {
+function toPascalCase2(value) {
   return value.split(/[_:\-\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
 function normalizeNotesInput(input) {
@@ -11164,29 +11453,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 {
@@ -11245,13 +11565,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({
@@ -11273,6 +11601,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 }`.'
       }
     ]
   },
@@ -11392,7 +11724,10 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
         ...methodIR,
         docs: [
           ...methodIR.docs,
-          ...buildEffectBehaviorDocs(methodSummary.effectBehaviors)
+          ...buildEffectBehaviorDocs(
+            methodSummary.effectBehaviors,
+            methodSummary.creates
+          )
         ]
       };
     }
@@ -11633,15 +11968,50 @@ function toRecordSearchResult(className, node) {
       return [];
     }
   ) : [];
+  const graphPathId = extractRecordIdFromGraphPath(path2, 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, path2)) {
+    return null;
+  }
+  const fallbackLabel = displayLabelFromFields(fields);
+  const label = rawLabel && !isPlaceholderRecordLabel(rawLabel, id, path2) ? rawLabel : fallbackLabel || rawLabel || id;
   return {
     path: path2,
     className,
-    id: extractRecordIdFromGraphPath(path2, className),
-    label: typeof node.label === "string" && node.label.trim() ? node.label : extractRecordIdFromGraphPath(path2, className),
+    id,
+    label,
     description: typeof node.description === "string" && node.description.trim() ? node.description : null,
     fields
   };
 }
+function isPlaceholderRecordLabel(label, id, path2) {
+  const normalizedLabel = normalizeGraphPathSegment(label);
+  return normalizedLabel === normalizeGraphPathSegment(id) || normalizedLabel === normalizeGraphPathSegment(path2);
+}
+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();
 }
@@ -12541,15 +12911,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
     );
@@ -12563,7 +12965,7 @@ function normalizeStateMachines(values) {
   }).filter((machine) => machine.name.length > 0);
 }
 function stateTypeName(className, machineName) {
-  return `${toPascalCase(className)}${toPascalCase(machineName)}`;
+  return `${toPascalCase2(className)}${toPascalCase2(machineName)}`;
 }
 function transitionTypeName(className, machineName) {
   return `${stateTypeName(className, machineName)}Transition`;
@@ -12571,6 +12973,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();
@@ -12584,6 +12995,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)
     });
   }
@@ -12595,6 +13008,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 || []) {
@@ -12605,12 +13056,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 || []) {
@@ -12622,7 +13074,7 @@ function buildStateMachineModelMutations(modelPath, machines) {
           transition.name
         )}, from: ${JSON.stringify(transition.from)}, to: ${JSON.stringify(
           transition.to
-        )}) { name } } } }`
+        )}${transitionMetadataGraphqlArgs(transition)}) { name } } } }`
       });
     }
   }
@@ -12649,7 +13101,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.`],
@@ -12672,7 +13124,7 @@ function buildMachineMethods(classSummary, machine) {
       ],
       static: false,
       params: [{ name: "target", type: stateName }],
-      returnType: `Promise<${toPascalCase(classSummary.name)}>`,
+      returnType: `Promise<${toPascalCase2(classSummary.name)}>`,
       runtime: {
         kind: "state_machine",
         machineName: machine.name,
@@ -12745,6 +13197,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 {
@@ -12767,8 +13312,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!
       }
 
@@ -12785,6 +13330,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
       type StateMachineSnapshotMutation {
         snapshot: StateMachineSnapshot!
         activate_transition(name: String!): StateMachineSnapshotMutation!
+        observe_state(state: String!, force: Boolean, source: String): StateMachineSnapshotMutation!
       }
 
       type StateMachine {
@@ -12804,6 +13350,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
 
       type StateMachineState {
         name: String!
+        label: String
+        description: String
         is_final: Boolean!
       }
 
@@ -12811,6 +13359,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 {
@@ -12863,23 +13419,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;
@@ -12898,16 +13478,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,
@@ -12974,6 +13575,14 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             name
             from { name }
             to { name }
+            label
+            description
+            action_json
+            assignee_json
+            requirements_json
+            permission_json
+            risk
+            expected_outcome_json
           }
         }`
       ]
@@ -13227,6 +13836,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;
@@ -13257,8 +13886,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(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  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));
@@ -13270,6 +13911,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) {
@@ -13507,11 +14165,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
@@ -13590,6 +14342,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);
   }
@@ -14414,10 +15210,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
       )
     );
@@ -14425,8 +15222,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) {
@@ -14497,12 +15294,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
@@ -14610,11 +15408,7 @@ var EnvironmentSession = class extends Session {
   }
   buildSessionDataUrl(path2, 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)}${path2}${queryString ? `?${queryString}` : ""}`;
   }
@@ -14697,9 +15491,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(
@@ -14780,13 +15673,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 },
@@ -14800,6 +15696,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({
@@ -14876,6 +15787,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);
   }
@@ -15703,15 +16620,43 @@ var Granular = class _Granular {
     const effects = Array.from(
       this.getSandboxEffectMap(host.sandboxId).values()
     ).map((effect) => this.serializeEffect(effect));
-    const result = await withTimeout(
-      host.wsClient.call("effects.publishCatalog", {
-        effects
-      }),
-      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(effects, 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 (error) {
+      if (!isUnsupportedEffectCatalogMutation(error)) {
+        throw error;
+      }
+      const result = await withTimeout(
+        host.wsClient.call("effects.publishCatalog", {
+          effects
+        }),
+        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"}`
@@ -16937,6 +17882,7 @@ var HARNESS_V3_FRONTEND_ACTIONS_MODULE = "@granular/actions/frontend";
 var HARNESS_V3_CSV_MODULE = "@granular/utils/csv";
 var HARNESS_V3_XLSX_MODULE = "@granular/utils/xlsx";
 var LEGACY_SANDBOX_TOOLS_MODULE_PATTERN = "\\.\\/sandbox-tools(?:\\.js)?";
+var HARNESS_V3_RUNTIME_MODULE_PATTERN = "@granular/(?:agent|session|domain(?:/[A-Za-z_$][\\w$]*)?|actions/(?:backend|frontend)|utils/(?:csv|xlsx))";
 function hasNamedModuleImport(source, moduleName, name) {
   const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -16995,6 +17941,15 @@ function reviewGeneratedJobCode(code, _options = {}) {
       message: "Generated code must use static top-level ESM imports from the Harness v3 runtime modules. Do not use dynamic import(...)."
     });
   }
+  if (new RegExp(
+    `import\\s+\\*\\s+as\\s+[A-Za-z_$][\\w$]*\\s+from\\s*['"]${HARNESS_V3_RUNTIME_MODULE_PATTERN}['"]`
+  ).test(normalized)) {
+    issues.push({
+      code: "runtime_namespace_import",
+      severity: "error",
+      message: 'Generated code must use named imports from Harness runtime modules. Do not use namespace imports such as `import * as agent from "@granular/agent"`; use `import { replyToUser, artifacts } from "@granular/agent"`.'
+    });
+  }
   if (/\bprocess\.exit\s*\(/.test(normalized)) {
     issues.push({
       code: "process_exit",
@@ -18014,6 +18969,31 @@ function buildGranularAgentHeapBlock(heapSummary) {
     entries: {}
   });
 }
+function buildGranularAgentManualActionMemorySummary(input) {
+  const maxItems = Math.max(1, Math.min(12, input.maxItems ?? 8));
+  const suggestions = (input.suggestions || []).filter((suggestion) => suggestion?.actionKey).slice(0, maxItems).map((suggestion) => ({
+    actionKey: suggestion.actionKey,
+    label: suggestion.label || null,
+    targetClassName: suggestion.targetClassName || null,
+    count: typeof suggestion.count === "number" && Number.isFinite(suggestion.count) ? suggestion.count : null,
+    subjectCount: typeof suggestion.subjectCount === "number" && Number.isFinite(suggestion.subjectCount) ? suggestion.subjectCount : null,
+    successCount: typeof suggestion.successCount === "number" && Number.isFinite(suggestion.successCount) ? suggestion.successCount : null,
+    failureCount: typeof suggestion.failureCount === "number" && Number.isFinite(suggestion.failureCount) ? suggestion.failureCount : null,
+    lastOccurredAt: typeof suggestion.lastOccurredAt === "number" && Number.isFinite(suggestion.lastOccurredAt) ? suggestion.lastOccurredAt : null,
+    sampleTargetIds: Array.isArray(suggestion.sampleTargetIds) ? suggestion.sampleTargetIds.filter(
+      (id) => typeof id === "string" && id.trim().length > 0
+    ).slice(0, 6) : []
+  }));
+  return [
+    renderConstBlock("manualActionMemory", {
+      suggestions
+    }),
+    "Use manualActionMemory only as behavioral context for likely next actions. Ground the current target and validate permissions before creating or running prepared actions."
+  ].join("\n");
+}
+function buildGranularAgentManualActionBlock(manualActionSummary) {
+  return manualActionSummary?.trim() || buildGranularAgentManualActionMemorySummary({ suggestions: [] });
+}
 function projectSessionFileSummary(liveDoc) {
   const files = asRecord4(liveDoc?.files);
   const byId = asRecord4(files?.byId) || {};
@@ -18045,8 +19025,12 @@ function buildGranularAgentFileBlock(fileSummary) {
 function extractRuntimeContractExports(domainBlock) {
   const classes = /* @__PURE__ */ new Set();
   const actions = /* @__PURE__ */ new Set();
-  const classPattern = /export\s+declare\s+(?:const|class)\s+([A-Za-z_$][\w$]*)/g;
-  for (const match of domainBlock.matchAll(classPattern)) {
+  const classConstPattern = /export\s+declare\s+const\s+([A-Za-z_$][\w$]*)\s*:\s*EntityClass\b/g;
+  for (const match of domainBlock.matchAll(classConstPattern)) {
+    classes.add(match[1]);
+  }
+  const classDeclPattern = /export\s+declare\s+class\s+([A-Za-z_$][\w$]*)\b/g;
+  for (const match of domainBlock.matchAll(classDeclPattern)) {
     classes.add(match[1]);
   }
   const actionPattern = /export\s+declare\s+function\s+([A-Za-z_$][\w$]*)/g;
@@ -18551,6 +19535,9 @@ function buildGranularAgentSystemPrompt(input) {
   });
   const referentBlock = buildGranularAgentReferentBlock(input.referentSummary);
   const loopBlock = buildGranularAgentLoopBlock(input.loopSummary);
+  const manualActionBlock = buildGranularAgentManualActionBlock(
+    input.manualActionSummary
+  );
   const knownFactsBlock = renderConstBlock(
     "knownFacts",
     buildKnownFactsFromCheckpoint(input.checkpoint)
@@ -18564,16 +19551,15 @@ function buildGranularAgentSystemPrompt(input) {
 - \`replyToUser(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
   - For long-running or multi-step jobs, send several short \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
   - Write \`replyToUser(...)\` content in a friendly, readable product-assistant style: concrete, concise, and natural. Avoid robotic status dumps, raw implementation names, and unexplained IDs unless the ID helps the user.
-  - When \`replyToUser(...)\` mentions a grounded record that should remain clickable/referable, wrap only the visible record label in a self-closing inline reference tag: \`<granular-object class="class_name" id="stable_id_or_path" label="Visible label" />\`. Use the actual class name and stable id/path from the runtime record or effect result; do not invent ids, field names, or snake/camel-case aliases that are not present in the type declarations or returned object.
-  - Treat \`showObjects(...)\` as the UI display call for user-visible records, not as a general storage helper. Do not wrap records under an \`items\` key.
-  - When records should remain reusable for follow-ups, first save the runtime record or ordered record array with \`await groundedObjects.save("stable_selection_name", value)\`, then display that saved selection exactly once with \`showObjects({ variableNames: ["stable_selection_name"] })\`.
-  - \`groundedObjects.save(...)\` only accepts scalar values, runtime records/sandbox instances, or arrays of runtime records/sandbox instances from one class. Do not save plain action/effect result objects or arrays of JSON summaries returned by actions. If an action returns ids/paths for records that should remain referable or displayed as records, fetch the matching runtime records first with the generated class \`.get(...)\`/query API, then save/display those fetched records. If the action returned only structured summaries, answer from those summaries with \`replyToUser(...)\`.
-  - Do not use \`showObjects({ entries: [...] })\` or \`showObjects({ saveAs, entries })\` as a shortcut for ordered pages, queues, search results, or ranked lists; those forms can create duplicate or poorly labelled displays. Save the selection with \`groundedObjects.save(...)\` and display it via \`variableNames\` instead.
-  - Use \`entryPaths\` only for a few already-known individual records and \`listNames\` only for a host-created list that you intentionally want to show. Do not display both an entry/list selection and a heap variable for the same records.
+  - When \`replyToUser(...)\` mentions a grounded record that should remain clickable/referable, wrap only the visible record label in a self-closing inline reference tag using the actual class name and id/path.
+  - Treat \`showObjects(...)\` as the UI display call for user-visible records. When records should remain reusable for follow-ups, first save the runtime record or ordered record array with \`await groundedObjects.save("stable_selection_name", value)\`, then display it once with \`showObjects({ variableNames: ["stable_selection_name"] })\`.
+  - \`groundedObjects.save(...)\` only accepts scalar values, session files, runtime records/sandbox instances, or arrays of runtime records/sandbox instances from one class. Do not save plain action/effect result objects; fetch affected records first or answer from summaries with \`replyToUser(...)\`.
+  - Do not use \`showObjects({ entries: [...] })\` or \`showObjects({ saveAs, entries })\`. Save ordered pages, queues, search results, or ranked lists with \`groundedObjects.save(...)\`, then call \`showObjects({ variableNames: [...] })\` once.
+  - Use \`showAgentResponse({ reply, show: [record, action] })\` when one assistant message should combine text, grounded records, files, prepared actions, or action suggestions. The \`action\` can be a state handle such as \`record.lifecycle.approved\` or an action handle such as \`record.lifecycle.approved.reach()\`.
+  - Do not use deprecated side-channel helpers such as \`agent_text_message(...)\`, \`agent_heap_objects(...)\`, or \`agent_message(...)\` unless the generated types expose no Harness v3 helper alternative.
   - When the user asks to show, list, display, open, or "show them" for records you found, call \`showObjects(...)\`; do not answer only with a count or text summary.
   - For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with \`replyToUser(...)\` only. Do not call \`showObjects(...)\`, \`saveAs\`, or \`groundedObjects.save(...)\` unless the user also asked to see records or a later requested action needs a reusable record selection.
-  - Any job that identifies a specific record in the visible answer must also display that grounded record with \`showObjects(...)\` when the user should see/open it, or save it with \`groundedObjects.save(...)\` when it is only needed for follow-up resolution.
-  - For ordered record slices, pages, queues, search results, or ranked lists, save the slice with \`groundedObjects.save(...)\` and then call \`showObjects({ variableNames: [...] })\` once. Use a stable name that preserves the slice identity and ordering so later references such as "the second item" or "back on the first slice" resolve to the correct earlier slice, not merely the most recent record.
+  - Use stable saved list names that preserve identity and ordering so later references such as "the second item" or "back on the first slice" resolve to the correct earlier slice, not merely the most recent record.
   - Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit agent message calls.` : `- Every job that answers the user must emit \`replyToUser(...)\` from \`@granular/agent\`.
 - \`replyToUser(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
 - For long-running or multi-step jobs, send several short \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
@@ -18584,7 +19570,7 @@ function buildGranularAgentSystemPrompt(input) {
 - When using code, assistant text must be empty or one brief summary.
 - Code must be plain runnable JavaScript with top-level await.
 - Use [Runtime Imports] as the authoritative module map. Import only listed module exports.
-- Use static top-level imports such as \`import { Foo } from "@granular/domain/Foo"; import { replyToUser } from "@granular/agent";\`. Do not use dynamic imports for runtime modules.
+- Use static top-level named imports such as \`import { Foo } from "@granular/domain/Foo"; import { replyToUser, artifacts } from "@granular/agent";\`. Do not use dynamic imports or namespace imports like \`import * as agent from "@granular/agent"\` for runtime modules.
 - Read and write session files through the virtual filesystem modules listed in [Runtime Imports]. Input files are mounted under \`/session/input\`; files written under \`/session/output\` are persisted as agent-created session files.
 - Do not ask the user to provide virtual filesystem paths. Users attach or mention files by name in the UI; resolve the right file from \`sessionFileManifest.files\` or the current attachment context, then use its provided path internally.
 - The \`sessionFileManifest\` block is prompt context, not an imported module or runtime variable. For dynamic file lookup, import \`files\` from \`@granular/session\` and match \`filename\` to a returned file's \`path\`.
@@ -18647,6 +19633,7 @@ ${workflowRules}
 High-priority execution rules:
 - Treat a human reference as something to ground, not as missing data. When the user names or describes a record, group, queue, parent, relationship, or prior result and asks to inspect, decide, update, schedule, approve, send, or otherwise act on session data, run a code job to ground it before asking the user for more details.
 - For a human-described primary anchor, a no-match answer is only justified after more than one distinct grounding attempt, such as owner/container grounding, relationship traversal, exact id/path lookup, or shorter target-local search. Before the primary no-match return, retry that same anchor with fewer text constraints or a distinct grounding strategy; do not stop after one zero-result list/find/page call.
+- If the latest user wording names an entity type that has an importable class, ground that class first. A previously installed parent class or related action method is not a substitute; after zero results in one class, pivot to the latest named importable class before reporting no match.
 - A confirmation requirement is not a reason to stay text-only. Do all safe read-only grounding and availability/status checks first, then call \`userInteraction.askConfirmation(...)\` or \`userInteraction.askChoice(...)\` before the mutation.
 - In any code branch where a requested action or mutation has multiple possible targets, import \`userInteraction\` from \`@granular/session\` and use \`await userInteraction.askChoice(...)\` in that branch. This includes ambiguity discovered after a query returns several records. A branch that only shows candidates, asks in text, and returns leaves the requested action unfinished.
 - Before any mutation, know whether the target is one record or several. A singular phrase like "the item" is not proof of uniqueness after a query finds multiple matching records. If the user did not give an exact identifier or explicit selection criterion, call \`userInteraction.askChoice({ options, ... })\` with grounded choices; do not choose by age, amount, priority, order, or convenience on your own. Resolve the target before any yes/no confirmation.
@@ -18690,7 +19677,7 @@ Intent resolution:
 - For follow-up words like "other", "another", or "remaining" after the user selected one candidate from a previous choice, resolve within the active contrast from that choice and the user's answer. Exclude the selected item, preserve descriptors such as larger, smaller, next, older, different, or same status, and do not take the first leftover from a wider saved list when the contrast narrows the intended set.
 - Before any mutation, prove the target resolves to exactly one grounded record. If the request describes a set, category, relationship, prior result group, or other non-unique scope, gather the candidate records first; when more than one candidate remains, ask the user to choose before calling the action.
 - For ambiguous choice prompts before a mutation, every option that describes a different candidate must carry a distinct grounded record value/path. After the answer, do not fall back to the first candidate if matching fails; ask again or stop without mutating.
-- The [State] constants and [Runtime Imports] map are prompt context, not runtime variables. Never reference \`runtimeImports\`, \`savedData\`, \`sessionFileManifest\`, \`recentReferences\`, \`workflowContext\`, \`workflowState\`, or \`capabilities\` as variables in generated code. When using a recent reference or file path, copy its path string into code and fetch/read it with the relevant runtime API.
+- The [State] constants and [Runtime Imports] map are prompt context, not runtime variables. Never reference \`runtimeImports\`, \`savedData\`, \`manualActionMemory\`, \`sessionFileManifest\`, \`recentReferences\`, \`workflowContext\`, \`workflowState\`, or \`capabilities\` as variables in generated code. When using a recent reference, manual-action pattern, or file path, copy concrete ids/values into code and fetch/read it with the relevant runtime API.
 - Never write placeholder grounding code such as \`const path = null\`, \`const groundedPath = ""\`, or \`const recordPath = ""\`. If no saved reference is available, delete that branch entirely and execute the fallback lookup directly.
 - Never call \`.get({ path: "" })\`; an empty path is not a saved reference.
 - For ordinal references to earlier pages, slices, lists, or ranked results, use the saved list/recent references first. If no saved list is available, rerun the exact same ordered query and select the ordinal index from its returned \`items\`; never invent a record path from a label or ordinal.
@@ -18817,20 +19804,10 @@ Ask the user when:
 - the target is unique but the requested action is unclear
 
 Relationship filters:
-- One-record relationships use \`is\`.
-- Multi-record relationships use \`some\`.
-- Never guess relationship cardinality from wording. Check the generated TypeScript filter type for the field before writing a relationship filter; if you are not sure, use declared relationship getters from already grounded records instead of a relationship filter.
-- If a relationship filter type or field is one-record/singular, never use \`some\` on that field. Match by \`id\`, \`path\`, or \`is\`, or fetch the related record and continue through declared getters when you need to traverse farther.
-- Do not invent nested operators under relationship fields. A one-record relationship filter accepts only its documented operators such as \`id\`, \`path\`, \`is\`, \`null\`, and \`not_null\`; deeper conditions must go under \`is\` or be handled by fetching records and following getters.
-- Never use \`some\` on one-record fields. If the generated TypeScript type says \`OneRelationFilter\`, valid operators are \`id\`, \`path\`, \`is\`, \`null\`, and \`not_null\`; \`some\` is invalid.
-- Use \`some\` only when the generated TypeScript type says \`ManyRelationFilter\`.
-- For a singular relationship that points to an intermediate record, nested filters still use \`is\` at the singular hop. Do not use \`some\` because the nested condition names another related record.
-- Use \`{ relationship: { id: "record_id" } }\` or \`{ relationship: { path: "class_record_id" } }\` when matching a known related record.
-- When you already fetched the related record, use \`{ relationship: { path: record._graphPath } }\` or \`{ relationship: { id: record.id } }\`; do not wrap a known id/path under \`is\`.
-- The path used in a relationship filter must be the path of the relationship target. For same-queue follow-ups from an item/batch/ticket, fetch that item's related unit/site/depot first and use the related unit/site/depot path; do not use the item path as a unit/site/depot path.
-- Use \`{ relationship: { is: { field: { equal_to: value } } } }\` only for nested field filters. Never put \`id\` or \`path\` inside \`is\`.
-- Do not write \`{ relationship: { some: ... } }\` unless the generated filter type for that exact relationship says it is a many/collection relationship. For one-record, parent, owner, or many-to-one relationships, use \`path\`, \`id\`, \`is\`, or getter traversal.
-- Do not pass a full record instance into a filter; if you already fetched a record, filter by its id or path instead.
+- Use the generated filter type as the authority: \`OneRelationFilter\` supports \`id\`, \`path\`, \`is\`, \`null\`, \`not_null\`; \`ManyRelationFilter\` supports those plus \`some\`.
+- Use \`id\` or \`path\` for a known related record; use \`is\` or \`some\` only for nested target-field filters.
+- Relationship paths must belong to the relationship target type. If you have a parent/container/item of another type, fetch the declared related record first and filter with that related record's id/path.
+- Never pass a full record instance into a filter. Use its id/path or a declared relationship getter.
 ${domainSections.docs ? `
 Domain notes:
 ${domainSections.docs}
@@ -18841,6 +19818,23 @@ ${actionIndex}
 - Global backend actions are executable functions exported by \`@granular/actions/backend\`; import each backend action you call, e.g. \`import { some_action } from "@granular/actions/backend"; await some_action(...)\`. Frontend actions are exported by \`@granular/actions/frontend\` when the action index marks them as frontend actions.
 - Actions listed under "Record-level" are instance methods. First fetch or find the specific record, then call the action on that instance, e.g. \`const item = await Item.get({ path }); await item.action_name(...)\`.
 - Actions listed under "Class-level" are class/static methods. Call them on the imported class, e.g. \`await Item.action_name(...)\`.
+- State-machine handles are the preferred workflow surface. For an existing record, use \`record.lifecycle.targetState\`; for a not-yet-created record, use class-level handles such as \`SpendRequest.lifecycle.policy_review\` only to prepare a provisional new-record action flow.
+- For pure field-collection requests, target the class-level entry state handle; for submit/review requests, target the nearest requested later state.
+- Choose the nearest target state that matches the user's words. Do not aim at a later state just because it is reachable.
+- For grounded stateful records, choose the target state handle from the user's requested outcome and handle docs. Use \`plan()\`, \`blockers()\`, or \`permissions()\` to explain reachability, missing requirements, stale state, and who can run the action; do not derive workflow meaning or adjacent actions from raw \`record.status\` or \`current().state\`.
+- Before opening a stateful action, call \`const plan = await handle.plan()\`. If the plan or opened artifact shows blockers, stale state, missing relationships, permissions, or no reachable path, explain those structured results and display the record/artifact. Do not skip to a later state or build your own status ladder.
+- Use typed plan fields and helpers directly. For visible blocker text, use the declared blocker-formatting helper when available instead of hand-written object casts.
+- A suggestion is a recommendation button: \`await stateHandle.suggest(message)\`. A prepared action is the editable form the user can review/run: \`const action = stateHandle.reach(); const prepared = await action.open()\`.
+- Use suggestions when the user asks "what can I do next?", asks for options, or gives an unclear intent. Prefer 2 to 5 concrete suggestions and keep text short.
+- Open a prepared action when the user asks for one clear action. Prefill only values grounded in the user request, conversation, files, selected records, or fresh reads. Leave unknown fields empty; do not invent them.
+- When a grounded related/context record can satisfy the prepared action through declared relationships, use those relationships to fill required relationship inputs before opening or updating the action. If a required relationship remains empty, continue through declared relationship chains from the grounded object when the next hop can fill that slot. Do not only save the context record in memory while leaving derivable relationship slots blank.
+- A derived intermediate relationship is not enough when another required relationship is still reachable from it. For example, if a team gives a cost center and the action also requires a budget, traverse the cost center's declared budget relationship before opening the action.
+- If the user says they have a document/work item/event but no matching record is found, check for a declared class-level new-record state/action handle or importable backend create/preparation action for that named class before giving up. Use grounded required fields to open the prepared action or call the create/preparation action; if required values are still missing and no prepared action can collect them, ask only for those values. Do not claim the record already exists.
+- Do not ask for confirmation before opening a prepared action. The prepared action is itself reviewable. Use \`userInteraction.askConfirmation\` only when the user explicitly asks for yes/no approval, the selected action is ambiguous after grounding, or the domain/runtime asks for confirmation.
+- If the action cannot continue because of missing input, stale state, missing relationships, related-state requirements, or permissions, keep/show the prepared action at that blocker and explain the next needed person, record, or value. Do not skip workflow steps or target a later state.
+- Reuse an already-open prepared action for the same target/action when available: update it, show it again, or explain what is still needed instead of creating a duplicate.
+- If an open prepared action needs edits, prefer the returned record helper: \`const prepared = await action.open(); await prepared.updateInputs({ inputValues, relationships });\`. Use \`artifacts.updateInputs(id, patch)\` only when you only have an id.
+- Use \`await prepared.show()\` or \`await actions.show(prepared)\` only to display an already-created prepared action again.
 - The action index is the visibility contract. If an action is listed for a class, call it directly on fetched/listed instances of that class; do not use \`typeof record.action_name === "function"\` as a discovery gate. If an action is not listed, do not call it.
 - Never call a record-level action as \`Class.action_name(...)\`; that method will not exist.
 - For action inputs, use the exact property names from the generated TypeScript method signature or the input schema shown in the action list. Do not invent synonym fields for required inputs.
@@ -18871,6 +19865,8 @@ ${loopBlock}
 
 ${knownFactsBlock}
 
+${manualActionBlock}
+
 [Request]
 ${input.request?.trim() || "Use the latest user message in the conversation."}`;
 }
@@ -19621,6 +20617,8 @@ function modelOutputInstruction() {
     'Do not use "action":"reply" to say a record is not grounded yet; if the request names or describes a domain record, use "action":"job" and ground it from session state, relationships, searches, or visible read-only actions first.',
     'Before claiming you lack access, inspect the visible action list. If a visible read-only search, lookup, list, guidance, note, policy, or knowledge action can satisfy a "check", "find", "look up", or "whether we have guidance" request, choose "action":"job" and call it.',
     "Generated code must not report no matches for the primary human-described anchor after a single zero-result list/find/page call. Before that primary no-match return, retry the primary anchor with fewer text constraints or a distinct fallback such as owner/container grounding, relationship traversal, exact-id/path lookup, or shorter target-local search.",
+    "If the latest request names an importable entity type, generated code must ground that class first; a previously installed parent class or related action method is not a substitute. After zero results in one class, pivot to the latest named importable class before reporting no match.",
+    "When the user says they have a document/work item/event but no matching record exists yet, generated code must check the visible class-level new-record/create/preparation surface before returning no-match; if required create inputs are still missing and no prepared action can collect them, ask only for those inputs.",
     'Use "action":"job" when the next step should run code or mutate workflow state.',
     'When action is "job", include runnable code in "code" and emit the "code" field before any non-empty "reply" field so generated code comments can stream as progress.',
     "Generated job code must use plain ASCII punctuation in string literals and comments. Do not use curly quotes, smart apostrophes, en dashes, em dashes, or other typographic punctuation in code.",
@@ -19690,7 +20688,12 @@ function createOpenAIChatTurnGenerator(options) {
 
 ${modelOutputInstruction()}`
       },
-      ...input.history,
+      ...input.history.map(
+        (message) => ({
+          role: message.role,
+          content: message.content
+        })
+      ),
       { role: "user", content: input.request }
     ];
     const payload = {
@@ -19709,11 +20712,12 @@ ${modelOutputInstruction()}`
         let usage = null;
         let requestId = null;
         if (input.onTextDelta || input.onReplyDelta || input.onCodeDelta) {
-          const stream = await client.chat.completions.create({
+          const streamPayload = {
             ...payload,
             stream: true,
             stream_options: { include_usage: true }
-          });
+          };
+          const stream = await client.chat.completions.create(streamPayload);
           let streamedReply = "";
           let streamedCode = "";
           const emitReplyDelta = async () => {
@@ -19739,7 +20743,8 @@ ${modelOutputInstruction()}`
             await input.onCodeDelta(delta);
           };
           for await (const event of stream) {
-            requestId = requestId || event.id || event._request_id || null;
+            const eventRecord = event;
+            requestId = requestId || event.id || (typeof eventRecord._request_id === "string" ? eventRecord._request_id : null);
             usage = event.usage || usage;
             const delta = event.choices?.[0]?.delta?.content;
             const deltaText = typeof delta === "string" ? delta : Array.isArray(delta) ? delta.map((part) => asRecord6(part)?.text || "").join("") : "";
@@ -19753,14 +20758,13 @@ ${modelOutputInstruction()}`
           await emitCodeDelta();
           raw = { streamed: true, model, usage, request_id: requestId };
         } else {
-          const completion = await client.chat.completions.create(
-            payload
-          );
+          const completion = await client.chat.completions.create(payload);
+          const completionRecord = completion;
           raw = completion;
           usage = completion.usage;
-          requestId = (typeof completion.id === "string" ? completion.id : null) || (typeof completion._request_id === "string" ? completion._request_id : null);
+          requestId = (typeof completion.id === "string" ? completion.id : null) || (typeof completionRecord._request_id === "string" ? completionRecord._request_id : null);
           const content = asRecord6(
-            asRecord6(completion.choices?.[0])?.message
+            asRecord6(completion.choices[0])?.message
           )?.content;
           text = typeof content === "string" ? content : Array.isArray(content) ? content.map((part) => asRecord6(part)?.text || "").join("") : "";
         }
@@ -20097,6 +21101,9 @@ async function generateTurnWithRepair(generator, input) {
       "",
       "The previous generated job code failed preflight review against [Runtime Imports] and the runtime contract.",
       "Return a corrected JSON object. Keep the user's requested behavior, but fix every issue below before execution.",
+      "If an issue says workflow path, blockers, permissions, or readiness were derived from raw status fields, remove the status/current-state ladder. Pick the declared state handle that matches the user's requested outcome, call plan()/blockers()/permissions() first, then open/show that handle or explain its structured blockers.",
+      "If an issue says an unsafe type assertion was used, remove the cast and use declared fields or typed helpers directly. For state plans, use plan.blockers, plan.permissions, plan.steps, plan.summary, or blocker-formatting helpers without hand-written object casts.",
+      "If the previous code stopped after no matching record for a user-supplied document/work item, preserve the lookup but check declared new-record/create/preparation surfaces next. Import the backend action module if needed, or ask only for missing required create inputs when no prepared action can collect them.",
       "",
       "Preflight issues:",
       ...issues.map((issue) => `- ${issue.code}: ${issue.message}`),