@granular-software/sdk 0.4.31 → 0.4.33

package/dist/cli/index.js

@@ -15222,7 +15222,8 @@ ${effectMetamodelTable}
 | \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
 | \`getEffects()\` / \`getTools()\`, \`session.on("effects:changed", ...)\` | Effect catalog and live updates. |
 | \`checkReadiness()\`, \`on('readiness', ...)\` | Runtime readiness. |
-| \`getHeap()\` | Session state snapshot (advanced). |
+| \`document\`, \`getHeap()\` | Current live session state from the WebSocket. |
+| \`messages.list()\`, \`timeline.list()\`, \`jobs.list/get()\`, \`heap.entries.list/get()\`, \`heap.lists.list/get()\`, \`transcript.list()\` | Durable session history and saved artifacts. |
 | \`disconnect()\` | Close the live runtime session. |
 | \`rpc(method, params)\` | Low-level session RPC (advanced). |
 | \`disconnect()\` | End the session. |
@@ -17779,7 +17780,11 @@ var WSClient = class {
       return null;
     }
     try {
-      const payloadRaw = this.decodeBase64Url(parts[1]);
+      const payloadSegment = parts[1];
+      if (!payloadSegment) {
+        return null;
+      }
+      const payloadRaw = this.decodeBase64Url(payloadSegment);
       const payload = JSON.parse(payloadRaw);
       if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
         return null;
@@ -18856,6 +18861,7 @@ import { ${allImports} } from "./sandbox-tools";
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
+    return () => this.off(event, handler);
   }
   /**
    * Unsubscribe from session events
@@ -19312,6 +19318,16 @@ var JobImplementation = class {
         handler(message);
       }
     }
+    return () => {
+      const handlers = this.eventListeners.get(event);
+      if (!handlers) {
+        return;
+      }
+      this.eventListeners.set(
+        event,
+        handlers.filter((current) => current !== handler)
+      );
+    };
   }
   replayAgentMessage(message) {
     this.captureAgentMessage(message);
@@ -19398,6 +19414,540 @@ var JobImplementation = class {
   }
 };
 
+// src/job-presentation.ts
+var RESPONSE_KEYS = [
+  "reply",
+  "response",
+  "text",
+  "message",
+  "summary",
+  "answer"
+];
+var ENTRY_KEY_CANDIDATES = ["entryPath", "path"];
+var ENTRY_ARRAY_KEY_CANDIDATES = ["entryPaths", "paths"];
+var LIST_KEY_CANDIDATES = ["listName"];
+var LIST_ARRAY_KEY_CANDIDATES = ["listNames"];
+var VARIABLE_KEY_CANDIDATES = ["variableName"];
+var VARIABLE_ARRAY_KEY_CANDIDATES = ["variableNames"];
+var UI_CONTAINER_KEYS = ["show", "display", "present", "ui"];
+function asRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function normalizeText(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return null;
+  }
+  return trimmed;
+}
+function humanTextFromStdout(stdout) {
+  for (const line of [...stdout].reverse()) {
+    const normalized = normalizeText(line);
+    if (!normalized) continue;
+    if (/^[A-Z_]+:/.test(normalized)) continue;
+    return normalized;
+  }
+  return null;
+}
+function pushString(target, value) {
+  if (typeof value === "string" && value.trim()) {
+    target.add(value.trim());
+  }
+}
+function pushStringArray(target, value) {
+  if (!Array.isArray(value)) return;
+  for (const item of value) {
+    pushString(target, item);
+  }
+}
+function collectReferencesFromRecord(record, refs) {
+  for (const key of ENTRY_KEY_CANDIDATES)
+    pushString(refs.entryPaths, record[key]);
+  for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.entryPaths, record[key]);
+  for (const key of LIST_KEY_CANDIDATES)
+    pushString(refs.listNames, record[key]);
+  for (const key of LIST_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.listNames, record[key]);
+  for (const key of VARIABLE_KEY_CANDIDATES)
+    pushString(refs.variableNames, record[key]);
+  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.variableNames, record[key]);
+}
+function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || value === void 0 || depth > 4 || seen.has(value))
+    return;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (heap.entriesByPath?.[trimmed]) refs.entryPaths.add(trimmed);
+    if (heap.listsByName?.[trimmed]) refs.listNames.add(trimmed);
+    if (heap.variablesByName?.[trimmed]) refs.variableNames.add(trimmed);
+    return;
+  }
+  if (Array.isArray(value)) {
+    seen.add(value);
+    for (const item of value.slice(0, 24)) {
+      scanForHeapReferences(item, heap, refs, depth + 1, seen);
+    }
+    return;
+  }
+  const record = asRecord2(value);
+  if (!record) return;
+  seen.add(value);
+  collectReferencesFromRecord(record, refs);
+  for (const key of UI_CONTAINER_KEYS) {
+    const nested = asRecord2(record[key]);
+    if (nested) collectReferencesFromRecord(nested, refs);
+  }
+  for (const nested of Object.values(record).slice(0, 24)) {
+    scanForHeapReferences(nested, heap, refs, depth + 1, seen);
+  }
+}
+function resolveVariablesToReferences(variableNames, heap, refs) {
+  for (const variableName of variableNames) {
+    const variable = heap.variablesByName?.[variableName];
+    if (!variable) continue;
+    if (variable.kind === "entry" && variable.entryPath) {
+      refs.entryPaths.add(variable.entryPath);
+    }
+    if (variable.kind === "list" && variable.listName) {
+      refs.listNames.add(variable.listName);
+    }
+  }
+}
+function sortEntries(entries) {
+  return [...entries].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+function sortLists(lists) {
+  return [...lists].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+function dedupeEntries(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const entry of entries) {
+    if (!entry?.path || seen.has(entry.path)) continue;
+    seen.add(entry.path);
+    result.push(entry);
+  }
+  return result;
+}
+function dedupeLists(lists) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const list of lists) {
+    if (!list?.name || seen.has(list.name)) continue;
+    seen.add(list.name);
+    result.push(list);
+  }
+  return result;
+}
+function extractResponseText(result, stdout) {
+  const directText = normalizeText(result);
+  if (directText) return directText;
+  const record = asRecord2(result);
+  if (record) {
+    for (const key of RESPONSE_KEYS) {
+      const normalized = normalizeText(record[key]);
+      if (normalized) return normalized;
+    }
+    for (const containerKey of UI_CONTAINER_KEYS) {
+      const nested = asRecord2(record[containerKey]);
+      if (!nested) continue;
+      for (const key of RESPONSE_KEYS) {
+        const normalized = normalizeText(nested[key]);
+        if (normalized) return normalized;
+      }
+    }
+  }
+  return humanTextFromStdout(stdout);
+}
+function fallbackResponseText(entries, lists) {
+  if (entries.length > 0) {
+    return entries.length === 1 ? "I found one relevant record." : `I found ${entries.length} relevant records.`;
+  }
+  if (lists.length > 0) {
+    const emptyOnly = lists.every((list) => (list.paths || []).length === 0);
+    if (emptyOnly) {
+      return lists.length === 1 ? "I saved one empty result set." : `I saved ${lists.length} empty result sets.`;
+    }
+    return lists.length === 1 ? "I saved one result set." : `I saved ${lists.length} result sets.`;
+  }
+  return null;
+}
+function getJobRelatedEntries(heap, jobId) {
+  return sortEntries(
+    Object.values(heap.entriesByPath || {}).filter(
+      (entry) => entry.relatedJobIds?.includes(jobId)
+    )
+  );
+}
+function getJobRelatedLists(heap, jobId) {
+  return sortLists(
+    Object.values(heap.listsByName || {}).filter(
+      (list) => list.relatedJobIds?.includes(jobId)
+    )
+  );
+}
+function entriesFromLists(lists, heap) {
+  const entries = [];
+  for (const list of lists) {
+    for (const path6 of list.paths || []) {
+      const entry = heap.entriesByPath?.[path6];
+      if (entry) entries.push(entry);
+    }
+  }
+  return entries;
+}
+function resolveJobPresentation({
+  jobId,
+  result,
+  stdout = [],
+  sessionHeap,
+  allowExplicitArtifacts = true
+}) {
+  const refs = {
+    entryPaths: /* @__PURE__ */ new Set(),
+    listNames: /* @__PURE__ */ new Set(),
+    variableNames: /* @__PURE__ */ new Set()
+  };
+  if (allowExplicitArtifacts) {
+    scanForHeapReferences(result, sessionHeap, refs);
+    resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
+  }
+  const referencedLists = sortLists(
+    [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
+  );
+  const referencedEntries = sortEntries(
+    [...refs.entryPaths].map((path6) => sessionHeap.entriesByPath?.[path6]).filter((entry) => Boolean(entry))
+  );
+  const jobLists = getJobRelatedLists(sessionHeap, jobId);
+  const jobEntries = getJobRelatedEntries(sessionHeap, jobId);
+  const changedEntries = dedupeEntries([
+    ...jobEntries,
+    ...entriesFromLists(jobLists, sessionHeap)
+  ]);
+  const explicitLists = dedupeLists(referencedLists);
+  const explicitEntries = dedupeEntries([
+    ...referencedEntries,
+    ...entriesFromLists(referencedLists, sessionHeap)
+  ]);
+  const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
+  const lists = hasExplicitArtifacts ? explicitLists : jobLists;
+  const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
+  const responseText = extractResponseText(result, stdout) || fallbackResponseText(entries, lists);
+  return {
+    responseText,
+    entries,
+    lists,
+    changedEntries,
+    changedLists: jobLists,
+    hasExplicitArtifacts
+  };
+}
+
+// src/session-transcript.ts
+var EMPTY_HEAP = {
+  entriesByPath: {},
+  listsByName: {},
+  variablesByName: {}};
+function asRecord3(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function trimString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function normalizeShowRefs(value) {
+  const record = asRecord3(value);
+  if (!record) return void 0;
+  const normalizeRefs = (input) => {
+    if (!Array.isArray(input)) return void 0;
+    const refs = Array.from(
+      new Set(
+        input.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean)
+      )
+    );
+    return refs.length > 0 ? refs : void 0;
+  };
+  const show = {
+    entryPaths: normalizeRefs(record.entryPaths),
+    listNames: normalizeRefs(record.listNames),
+    variableNames: normalizeRefs(record.variableNames)
+  };
+  return show.entryPaths || show.listNames || show.variableNames ? show : void 0;
+}
+function stringifyTranscriptValue(value, fallback2 = "") {
+  if (typeof value === "string") {
+    return value.trim() || fallback2;
+  }
+  if (typeof value === "boolean") {
+    return value ? "Confirmed" : "Canceled";
+  }
+  if (value === void 0) {
+    return fallback2;
+  }
+  try {
+    const json = JSON.stringify(value, null, 2);
+    if (!json || json === "undefined") return fallback2;
+    return json.length > 2e3 ? `${json.slice(0, 2e3)}...` : json;
+  } catch {
+    return String(value);
+  }
+}
+function buildArtifactHistory(show) {
+  if (!show) return void 0;
+  return `[Agent message]
+${stringifyTranscriptValue({ show }, "")}`;
+}
+function normalizeConversationMessage(raw) {
+  const record = asRecord3(raw);
+  if (!record) return null;
+  const role = record.role === "user" ? "user" : record.role === "assistant" ? "assistant" : null;
+  if (!role) return null;
+  const content = trimString(
+    record.content ?? record.reply ?? record.message ?? record.text
+  );
+  const show = normalizeShowRefs(record.show);
+  const id = asString(record.id) || crypto.randomUUID();
+  const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
+  if (!content && !show) return null;
+  return {
+    id,
+    role,
+    content,
+    timestamp,
+    jobId: asString(record.jobId),
+    promptId: asString(record.promptId),
+    show,
+    historyContent: role === "assistant" ? content ? `[Assistant reply]
+${content}` : buildArtifactHistory(show) : void 0,
+    source: "conversation"
+  };
+}
+function normalizePromptEntries(jobId, rawPrompts, conversationPromptIds) {
+  const promptsById = asRecord3(rawPrompts) || {};
+  return Object.values(promptsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
+    (left, right) => (asNumber(left.openedAt) || asNumber(left.answeredAt) || 0) - (asNumber(right.openedAt) || asNumber(right.answeredAt) || 0)
+  ).flatMap((prompt3) => {
+    const promptId = asString(prompt3.promptId);
+    if (!promptId || conversationPromptIds.has(promptId)) return [];
+    const title = trimString(prompt3.title);
+    const message = trimString(prompt3.message);
+    const assistantContent = message || title || "Input required";
+    const openedAt = asNumber(prompt3.openedAt) || 0;
+    const answeredAt = asNumber(prompt3.answeredAt) || openedAt;
+    const entries = [
+      {
+        id: `prompt:${promptId}:assistant`,
+        role: "assistant",
+        content: assistantContent,
+        timestamp: openedAt,
+        jobId,
+        promptId,
+        historyContent: `[Assistant reply]
+${assistantContent}`,
+        source: "job_prompt"
+      }
+    ];
+    if (Object.prototype.hasOwnProperty.call(prompt3, "answer")) {
+      entries.push({
+        id: `prompt:${promptId}:user`,
+        role: "user",
+        content: stringifyTranscriptValue(prompt3.answer, ""),
+        timestamp: answeredAt,
+        jobId,
+        promptId,
+        source: "job_prompt"
+      });
+    }
+    return entries;
+  });
+}
+function normalizeAgentMessageEntries(jobId, rawMessages) {
+  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) => {
+    const messageId = asString(message.messageId) || asString(message.id) || crypto.randomUUID();
+    const timestamp = asNumber(message.timestamp) || asNumber(message.ts) || 0;
+    const reply = trimString(
+      message.reply ?? message.message ?? message.text ?? message.content
+    );
+    const show = normalizeShowRefs(message.show);
+    const entries = [];
+    if (reply) {
+      entries.push({
+        id: `agent:${messageId}:text`,
+        role: "assistant",
+        content: reply,
+        timestamp,
+        jobId,
+        historyContent: `[Assistant reply]
+${reply}`,
+        source: "job_agent_message"
+      });
+    }
+    if (show) {
+      entries.push({
+        id: `agent:${messageId}:artifacts`,
+        role: "assistant",
+        content: "",
+        timestamp,
+        jobId,
+        show,
+        historyContent: buildArtifactHistory(show),
+        source: "job_agent_message"
+      });
+    }
+    return entries;
+  });
+}
+function buildJobFallbackEntries(jobId, job2, sessionHeap) {
+  const timestamp = asNumber(job2.finishedAt) || asNumber(job2.startedAt) || asNumber(job2.submittedAt) || 0;
+  const resultPreview = stringifyTranscriptValue(
+    job2.result,
+    "No job result recorded."
+  );
+  const presentation = resolveJobPresentation({
+    jobId,
+    result: job2.result,
+    stdout: [],
+    sessionHeap
+  });
+  const entries = [];
+  const responseText = presentation.responseText || "";
+  if (responseText) {
+    entries.push({
+      id: `job:${jobId}:result-text`,
+      role: "assistant",
+      content: responseText,
+      timestamp,
+      jobId,
+      historyContent: `[Assistant reply]
+${responseText}`,
+      source: "job_result"
+    });
+  }
+  const show = {
+    entryPaths: presentation.entries.map((entry) => entry.path),
+    listNames: presentation.lists.map((list) => list.name)
+  };
+  if (show.entryPaths && show.entryPaths.length > 0 || show.listNames && show.listNames.length > 0) {
+    entries.push({
+      id: `job:${jobId}:result-artifacts`,
+      role: "assistant",
+      content: "",
+      timestamp,
+      jobId,
+      show,
+      historyContent: buildArtifactHistory(show),
+      source: "job_result"
+    });
+  }
+  if (entries.length === 0 && trimString(job2.error)) {
+    entries.push({
+      id: `job:${jobId}:result-error`,
+      role: "assistant",
+      content: trimString(job2.error),
+      timestamp,
+      jobId,
+      historyContent: `[Assistant reply]
+${trimString(job2.error)}`,
+      source: "job_result"
+    });
+  }
+  if (entries.length === 0 && resultPreview && resultPreview !== "No job result recorded.") {
+    entries.push({
+      id: `job:${jobId}:result-preview`,
+      role: "assistant",
+      content: resultPreview,
+      timestamp,
+      jobId,
+      historyContent: `[Assistant reply]
+${resultPreview}`,
+      source: "job_result"
+    });
+  }
+  return entries;
+}
+function buildJobCodeEntry(jobId, job2) {
+  const code = trimString(job2.source);
+  if (!code) return null;
+  const jobStatus = asString(job2.status);
+  const error2 = jobStatus === "failed" || jobStatus === "canceled" || jobStatus === "timeout" ? trimString(job2.error) || `Job ${jobStatus}` : void 0;
+  return {
+    id: `job:${jobId}:code`,
+    role: "assistant",
+    content: "",
+    timestamp: asNumber(job2.submittedAt) || asNumber(job2.startedAt) || asNumber(job2.finishedAt) || 0,
+    jobId,
+    code,
+    jobStatus,
+    jobResultPreview: stringifyTranscriptValue(job2.result, "No job result recorded."),
+    error: error2,
+    source: "job_code"
+  };
+}
+function buildSessionTranscript(input) {
+  const liveDoc = input.liveDoc || null;
+  const sessionHeap = input.sessionHeap || EMPTY_HEAP;
+  const transcript = [];
+  const conversationMessages = asArray(asRecord3(liveDoc?.conversation)?.messages).map((message) => normalizeConversationMessage(message)).filter((message) => Boolean(message));
+  const conversationPromptIds = new Set(
+    conversationMessages.map((message) => message.promptId).filter((promptId) => Boolean(promptId))
+  );
+  const assistantConversationJobIds = new Set(
+    conversationMessages.filter((message) => message.role === "assistant" && Boolean(message.jobId)).map((message) => message.jobId)
+  );
+  transcript.push(...conversationMessages);
+  const jobsById = asRecord3(asRecord3(liveDoc?.jobs)?.byId) || {};
+  const jobs = Object.values(jobsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
+    (left, right) => (asNumber(left.submittedAt) || asNumber(left.startedAt) || asNumber(left.finishedAt) || 0) - (asNumber(right.submittedAt) || asNumber(right.startedAt) || asNumber(right.finishedAt) || 0)
+  );
+  for (const job2 of jobs) {
+    const jobId = asString(job2.jobId);
+    if (!jobId) continue;
+    const codeEntry = buildJobCodeEntry(jobId, job2);
+    if (codeEntry) {
+      transcript.push(codeEntry);
+    }
+    transcript.push(
+      ...normalizePromptEntries(jobId, job2.prompts, conversationPromptIds)
+    );
+    if (!assistantConversationJobIds.has(jobId)) {
+      const agentEntries = normalizeAgentMessageEntries(jobId, job2.agentMessages);
+      if (agentEntries.length > 0) {
+        transcript.push(...agentEntries);
+      } else {
+        transcript.push(
+          ...buildJobFallbackEntries(
+            jobId,
+            job2,
+            sessionHeap
+          )
+        );
+      }
+    }
+  }
+  return transcript.sort((left, right) => {
+    if (left.timestamp !== right.timestamp) {
+      return left.timestamp - right.timestamp;
+    }
+    return left.id.localeCompare(right.id);
+  });
+}
+
 // src/effect-runtime.ts
 function computeEffectKey(effect) {
   const attachedClass = effect.className?.trim();
@@ -20015,7 +20565,9 @@ var Environment = class {
       }
     );
     if (result.errors?.length) {
-      throw new Error(`defineRelationship failed: ${result.errors[0].message}`);
+      throw new Error(
+        `defineRelationship failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data.at.define_relationship;
   }
@@ -20051,7 +20603,9 @@ var Environment = class {
       { path: modelPath }
     );
     if (result.errors?.length) {
-      throw new Error(`getRelationships failed: ${result.errors[0].message}`);
+      throw new Error(
+        `getRelationships failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.model?.relationships || [];
   }
@@ -20090,7 +20644,9 @@ var Environment = class {
       { target: targetPath }
     );
     if (result.errors?.length) {
-      throw new Error(`attach failed: ${result.errors[0].message}`);
+      throw new Error(
+        `attach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
   }
   /**
@@ -20125,7 +20681,9 @@ var Environment = class {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`detach failed: ${result.errors[0].message}`);
+      throw new Error(
+        `detach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
   }
   /**
@@ -20152,7 +20710,9 @@ var Environment = class {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`listRelated failed: ${result.errors[0].message}`);
+      throw new Error(
+        `listRelated failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.at?.at?.list_related || [];
   }
@@ -20245,7 +20805,9 @@ var Environment = class {
   async _runGraphql(query, label) {
     const result = await this.graphql(query);
     if (result.errors?.length) {
-      throw new Error(`${label}: ${result.errors[0].message}`);
+      throw new Error(
+        `${label}: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data;
   }
@@ -20590,7 +21152,11 @@ var Environment = class {
    */
   async recordObject(options) {
     const results = await this.recordObjects([options]);
-    return results[0];
+    const result = results[0];
+    if (!result) {
+      throw new Error("recordObject: no result returned for record");
+    }
+    return result;
   }
   /**
    * Batch version of `recordObject()`.
@@ -20642,7 +21208,13 @@ var Environment = class {
             );
           }
           for (let index = 0; index < items.length; index += 1) {
-            results[plan.offset + index] = items[index];
+            const item = items[index];
+            if (!item) {
+              throw new Error(
+                `recordObjects: chunk ${plan.chunkIndex + 1} returned an empty result at index ${index}`
+              );
+            }
+            results[plan.offset + index] = item;
           }
           if (onChunk) {
             const info2 = {
@@ -20770,6 +21342,9 @@ var EnvironmentSession = class extends Session {
   get envName() {
     return this.environment.envName;
   }
+  get tag() {
+    return this.environment.tag;
+  }
   get versionId() {
     return this.environment.versionId;
   }
@@ -20789,12 +21364,171 @@ var EnvironmentSession = class extends Session {
     return this.environment.feedback;
   }
   /**
-   * Return a plain JS snapshot of the synced session heap.
+   * Return a plain JS copy of the synced session heap.
    */
   getHeap() {
     const doc = this.document;
     return normalizeHeapSnapshot(doc?.heap);
   }
+  async sessionDataRequest(path6, 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));
+      }
+    }
+    const queryString = searchParams.toString();
+    const response = await fetch(
+      `${this.environment.runtimeBaseUrl}/orchestrator/ws/sessions/${encodeURIComponent(this.sessionId)}${path6}${queryString ? `?${queryString}` : ""}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${this.environment.authToken}`,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Session data API Error (${response.status}): ${errorText}`
+      );
+    }
+    return response.json();
+  }
+  async collectAllSessionItems(listPage) {
+    const items = [];
+    let cursor = null;
+    do {
+      const page = await listPage({ limit: 500, cursor });
+      items.push(...page.items);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return items;
+  }
+  /**
+   * Fetch the live session document from the runtime DO.
+   *
+   * For history and saved artifacts, prefer the collection APIs on
+   * `messages`, `timeline`, `jobs`, and `heap`.
+   */
+  async getDocument() {
+    return this.sessionDataRequest("/document");
+  }
+  get messages() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/messages",
+        options
+      )
+    };
+  }
+  get timeline() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/timeline",
+        options
+      )
+    };
+  }
+  get jobs() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/jobs",
+        options
+      ),
+      get: (jobId) => this.sessionDataRequest(
+        `/jobs/${encodeURIComponent(jobId)}`
+      )
+    };
+  }
+  get heap() {
+    return {
+      entries: {
+        list: (options = {}) => this.sessionDataRequest(
+          "/heap/entries",
+          options
+        ),
+        get: (path6) => this.sessionDataRequest(
+          `/heap/entries/${encodeURIComponent(path6)}`
+        )
+      },
+      lists: {
+        list: (options = {}) => this.sessionDataRequest(
+          "/heap/lists",
+          options
+        ),
+        get: (name) => this.sessionDataRequest(
+          `/heap/lists/${encodeURIComponent(name)}`
+        )
+      }
+    };
+  }
+  get transcript() {
+    return {
+      list: async (options = {}) => {
+        const [messages, jobs, entries, lists] = 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)
+        ]);
+        const liveDoc = {
+          conversation: { messages },
+          jobs: {
+            byId: Object.fromEntries(
+              jobs.map((job2) => {
+                const record = job2 && typeof job2 === "object" ? job2 : null;
+                const id = typeof record?.jobId === "string" ? record.jobId : typeof record?.id === "string" ? record.id : null;
+                return id ? [id, record] : null;
+              }).filter(
+                (entry) => Boolean(entry)
+              )
+            )
+          }
+        };
+        const heap = normalizeHeapSnapshot({
+          entriesByPath: Object.fromEntries(
+            entries.map((entry) => {
+              return entry?.path ? [
+                entry.path,
+                entry
+              ] : null;
+            }).filter(
+              (entry) => Boolean(entry)
+            )
+          ),
+          listsByName: Object.fromEntries(
+            lists.map((list) => {
+              return list?.name ? [list.name, list] : null;
+            }).filter(
+              (entry) => Boolean(entry)
+            )
+          ),
+          variablesByName: this.getHeap().variablesByName,
+          updatedAt: Date.now()
+        });
+        const allItems = buildSessionTranscript({
+          liveDoc,
+          sessionHeap: heap
+        });
+        const limit = Math.max(
+          1,
+          Math.min(500, Math.floor(options.limit ?? 100))
+        );
+        const offset = typeof options.cursor === "string" ? Number.parseInt(options.cursor, 10) || 0 : 0;
+        const items = allItems.slice(offset, offset + limit);
+        const nextOffset = offset + items.length;
+        return {
+          items,
+          nextCursor: nextOffset < allItems.length ? String(nextOffset) : null,
+          totalCount: allItems.length
+        };
+      }
+    };
+  }
   async graphql(query, variables) {
     return this.environment.graphql(query, variables);
   }
@@ -22022,14 +22756,18 @@ async function resolveOntologyId(granular, ontology) {
   const { config } = createGranularClient();
   const requestedOntology = ontology ?? config.sandboxId;
   if (!requestedOntology) {
-    throw new Error("No ontology configured. Run `granular init` first or pass `--ontology`.");
+    throw new Error(
+      "No ontology configured. Run `granular init` first or pass `--ontology`."
+    );
   }
   try {
     const sandbox = await granular.sandboxes.get(requestedOntology);
     return sandbox.sandboxId;
   } catch {
     const sandboxes = await granular.sandboxes.list();
-    const existing = sandboxes.items.find((item) => item.name === requestedOntology);
+    const existing = sandboxes.items.find(
+      (item) => item.name === requestedOntology
+    );
     if (existing) {
       return existing.sandboxId;
     }
@@ -22037,7 +22775,8 @@ async function resolveOntologyId(granular, ontology) {
   throw new Error(`Ontology not found: ${requestedOntology}`);
 }
 function matchesEnvironmentName(environment, requested) {
-  return environment.environment === requested || environment.envName === requested;
+  const managedPrefix = `__sdk__${requested}__`;
+  return environment.environment === requested || environment.envName === requested || environment.environment?.startsWith(managedPrefix) || environment.envName?.startsWith(managedPrefix) || environment.tag?.name === requested || environment.buildPolicy?.tagName === requested || environment.tracking?.tagName === requested;
 }
 async function resolveEnvironmentData(granular, options) {
   if (options.environmentId) {
@@ -22046,7 +22785,9 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find((environment2) => matchesEnvironmentName(environment2, environmentName));
+  const existing = environments.find(
+    (environment) => matchesEnvironmentName(environment, environmentName)
+  );
   if (existing) {
     return existing;
   }
@@ -22055,13 +22796,13 @@ async function resolveEnvironmentData(granular, options) {
       `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
-  const environment = await granular.openEnvironment({
+  const connection = await granular.connect({
     ontology: ontologyId,
-    tag: environmentName,
+    environment: environmentName,
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  return await granular.environments.get(environment.environmentId);
+  return await granular.environments.get(connection.environmentId);
 }
 async function listSessionsForEnvironment(granular, environmentId, status) {
   if (status === "all") {
@@ -22078,30 +22819,34 @@ async function listSessionsForEnvironment(granular, environmentId, status) {
 async function connectRuntime(options) {
   if (options.sessionId) {
     const { granular: granular2 } = createGranularClient();
-    const session3 = await granular2["connectSession"]({ sessionId: options.sessionId });
+    const environment2 = await granular2.connectSession({
+      sessionId: options.sessionId
+    });
     return {
       granular: granular2,
-      environment: session3.environment,
-      session: session3,
-      ontologyId: session3.ontologyId || session3.sandboxId
+      environment: environment2,
+      session: environment2,
+      ontologyId: environment2.ontologyId || environment2.sandboxId
     };
   }
   const { granular, config } = createGranularClient();
   const ontologyId = options.ontology ?? config.sandboxId;
   if (!ontologyId) {
-    throw new Error("No ontology configured. Run `granular init` first or pass `--ontology`.");
+    throw new Error(
+      "No ontology configured. Run `granular init` first or pass `--ontology`."
+    );
   }
-  const environment = await granular.openEnvironment({
+  const environmentHandle = await granular.connect({
     ontology: ontologyId,
-    tag: options.environment ?? "dev",
+    environment: options.environment ?? "dev",
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  const session2 = await environment.sessions.create();
+  const environment = await environmentHandle.createSession();
   return {
     granular,
     environment,
-    session: session2,
+    session: environment,
     ontologyId
   };
 }
@@ -22111,9 +22856,9 @@ async function withRuntimeConnection(options, callback) {
     return await callback(connection);
   } finally {
     try {
-      await connection.session.disconnect();
+      await connection.environment.disconnect();
     } catch {
-      connection.session.disconnectTransport();
+      connection.environment?.client?.disconnect?.();
     }
   }
 }
@@ -22140,24 +22885,25 @@ function readJobCodeFromOptions(options) {
 // src/cli/commands/connect.ts
 async function connectTestCommand(options) {
   const emitJson = options.json === true;
+  const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
   }
   await withRuntimeConnection(
     {
       ontology: options.ontology,
-      environment: options.environment ?? "dev",
+      environment: requestedEnvironment,
       userId: options.user,
       permissions: normalizePermissions(options.permissions)
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ok: true,
         ontologyId,
         sandboxId: environment.sandboxId,
         environmentId: environment.environmentId,
-        environment: environment.environment,
-        sessionId: session2.sessionId,
+        environment: environment.tag || requestedEnvironment,
+        sessionId: environment.sessionId,
         subjectId: environment.subjectId,
         versionId: environment.versionId
       };
@@ -22169,7 +22915,7 @@ async function connectTestCommand(options) {
       console.log();
       keyValue({
         "Ontology ID": payload.ontologyId,
-        "Environment": payload.environment,
+        Environment: payload.environment,
         "Environment ID": payload.environmentId,
         "Session ID": payload.sessionId,
         "Subject ID": payload.subjectId,
@@ -22203,12 +22949,12 @@ async function sessionHeapCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         environmentId: environment.environmentId,
-        heap: session2.getHeap()
+        heap: environment.getHeap()
       };
       if (!emitJson) {
         step("Session heap");
@@ -22231,12 +22977,14 @@ async function sessionDocCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
+    async ({ environment, ontologyId }) => {
       const payload = {
         ontologyId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         environmentId: environment.environmentId,
-        document: documentToJson(session2.document)
+        document: documentToJson(
+          environment.document
+        )
       };
       if (!emitJson) {
         step("Session document");
@@ -22248,6 +22996,7 @@ async function sessionDocCommand(options) {
 }
 async function sessionCreateCommand(options) {
   const emitJson = options.json === true;
+  const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
   }
@@ -22255,24 +23004,24 @@ async function sessionCreateCommand(options) {
   const permissions = normalizePermissions(options.permissions);
   const envData = await resolveEnvironmentData(granular, {
     ontology: options.ontology,
-    environment: options.environment ?? "dev",
+    environment: requestedEnvironment,
     environmentId: options.environmentId,
     userId: options.user,
     permissions,
     createIfMissing: true
   });
-  const session2 = await granular.createSession({
+  const environment = await granular.createSession({
     environmentId: envData.environmentId
   });
   try {
     const payload = {
       ok: true,
       ontologyId: envData.sandboxId,
-      environmentId: session2.environmentId,
-      environment: session2.environment.environment,
-      sessionId: session2.sessionId,
-      subjectId: session2.subjectId,
-      versionId: session2.versionId
+      environmentId: environment.environmentId,
+      environment: environment.tag || envData.tag?.name || envData.buildPolicy.tagName || requestedEnvironment,
+      sessionId: environment.sessionId,
+      subjectId: environment.subjectId,
+      versionId: environment.versionId
     };
     if (emitJson) {
       console.log(JSON.stringify(payload, null, 2));
@@ -22282,7 +23031,7 @@ async function sessionCreateCommand(options) {
     console.log();
     keyValue({
       "Ontology ID": payload.ontologyId,
-      "Environment": payload.environment,
+      Environment: payload.environment,
       "Environment ID": payload.environmentId,
       "Session ID": payload.sessionId,
       "Subject ID": payload.subjectId,
@@ -22291,30 +23040,35 @@ async function sessionCreateCommand(options) {
     console.log();
   } finally {
     try {
-      await session2.disconnect();
+      await environment.disconnect();
     } catch {
-      session2.disconnectTransport();
+      environment?.client?.disconnect?.();
     }
   }
 }
 async function sessionListCommand(options) {
   const emitJson = options.json === true;
   const status = options.status ?? "active";
+  const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
   }
   const { granular } = createGranularClient();
   const environmentData = await resolveEnvironmentData(granular, {
     ontology: options.ontology,
-    environment: options.environment ?? "dev",
+    environment: requestedEnvironment,
     environmentId: options.environmentId,
     createIfMissing: false
   });
-  const items = await listSessionsForEnvironment(granular, environmentData.environmentId, status);
+  const items = await listSessionsForEnvironment(
+    granular,
+    environmentData.environmentId,
+    status
+  );
   const payload = {
     ontologyId: environmentData.sandboxId,
     environmentId: environmentData.environmentId,
-    environment: environmentData.environment ?? environmentData.envName,
+    environment: environmentData.tag?.name || environmentData.buildPolicy.tagName || requestedEnvironment,
     status,
     items
   };
@@ -22418,12 +23172,12 @@ async function effectsListCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
-      const effects2 = sortEffects(session2.getEffects());
+    async ({ environment, ontologyId }) => {
+      const effects2 = sortEffects(environment.getEffects());
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         items: effects2
       };
       if (emitJson) {
@@ -22463,8 +23217,8 @@ async function effectsDiffCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, session: session2, ontologyId }) => {
-      const effects2 = sortEffects(session2.getEffects());
+    async ({ environment, ontologyId }) => {
+      const effects2 = sortEffects(environment.getEffects());
       const declared = effects2.map((effect) => effect.name);
       const liveReady = effects2.filter((effect) => effect.ready).map((effect) => effect.name);
       const declaredOnly = effects2.filter((effect) => !effect.ready).map((effect) => effect.name);
@@ -22472,7 +23226,7 @@ async function effectsDiffCommand(options) {
       const payload = {
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: session2.sessionId,
+        sessionId: environment.sessionId,
         summary: {
           declaredCount: declared.length,
           liveReadyCount: liveReady.length,