@granular-software/sdk 0.4.32 → 0.4.34

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. |
@@ -19413,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();
@@ -19421,6 +19956,50 @@ function computeEffectKey(effect) {
   }
   return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
 }
+function computeEffectVersionSelectorSpecificity(selector) {
+  if (!selector || selector.mode === "all") {
+    return 0;
+  }
+  if (selector.mode === "exact") {
+    return 2;
+  }
+  return 1;
+}
+function matchesEffectVersionSelector(selector, buildVersionNumber) {
+  if (!selector || selector.mode === "all") {
+    return true;
+  }
+  if (typeof buildVersionNumber !== "number" || !Number.isFinite(buildVersionNumber)) {
+    return false;
+  }
+  if (selector.mode === "exact") {
+    return buildVersionNumber === selector.versionNumber;
+  }
+  if (selector.mode === "before") {
+    return buildVersionNumber < selector.versionNumber;
+  }
+  return buildVersionNumber > selector.versionNumber;
+}
+function selectRegisteredEffect(effectMap, effectKey, buildVersionNumber) {
+  let bestEffect;
+  let bestSpecificity = Number.NEGATIVE_INFINITY;
+  for (const effect of effectMap.values()) {
+    if (computeEffectKey(effect) !== effectKey) {
+      continue;
+    }
+    if (!matchesEffectVersionSelector(effect.versionSelector, buildVersionNumber)) {
+      continue;
+    }
+    const specificity = computeEffectVersionSelectorSpecificity(
+      effect.versionSelector
+    );
+    if (!bestEffect || specificity > bestSpecificity) {
+      bestEffect = effect;
+      bestSpecificity = specificity;
+    }
+  }
+  return bestEffect;
+}
 function normalizeEffectBehaviors(value) {
   return normalizeEffectBehaviorSummary(
     value
@@ -19441,9 +20020,17 @@ function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
     return void 0;
   }
   if (reverseHandler.includes(":")) {
-    return effectMap.get(reverseHandler);
+    return selectRegisteredEffect(
+      effectMap,
+      reverseHandler,
+      request.context?.buildVersionNumber
+    );
   }
-  const directMatch = effectMap.get(reverseHandler);
+  const directMatch = selectRegisteredEffect(
+    effectMap,
+    reverseHandler,
+    request.context?.buildVersionNumber
+  );
   if (directMatch) {
     return directMatch;
   }
@@ -19458,7 +20045,11 @@ function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
     })
   ];
   for (const candidateKey of candidateKeys) {
-    const candidate = effectMap.get(candidateKey);
+    const candidate = selectRegisteredEffect(
+      effectMap,
+      candidateKey,
+      request.context?.buildVersionNumber
+    );
     if (candidate) {
       return candidate;
     }
@@ -19494,7 +20085,11 @@ function resolveHandlerForMode(effectMap, effect, request) {
   return { effect, mode, handler: effect.handler };
 }
 async function invokeRegisteredEffect(effectMap, request) {
-  const effect = effectMap.get(request.effectKey);
+  const effect = selectRegisteredEffect(
+    effectMap,
+    request.effectKey,
+    request.context?.buildVersionNumber
+  );
   if (!effect) {
     throw new Error(`Effect handler not found: ${request.effectKey}`);
   }
@@ -19615,6 +20210,17 @@ function computeEffectKey2(effect) {
   }
   return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
 }
+function computeEffectVersionSelectorKey(selector) {
+  if (!selector || selector.mode === "all") {
+    return "all";
+  }
+  return `${selector.mode}:${selector.versionNumber}`;
+}
+function computeEffectRegistrationKey(effect) {
+  return `${computeEffectKey2(effect)}@${computeEffectVersionSelectorKey(
+    effect.versionSelector
+  )}`;
+}
 function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
   const url = new URL(apiUrl);
   if (url.pathname.endsWith("/granular/ws/connect")) {
@@ -20109,7 +20715,9 @@ var Environment = class {
       { target: targetPath }
     );
     if (result.errors?.length) {
-      throw new Error(`attach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
+      throw new Error(
+        `attach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
   }
   /**
@@ -20144,7 +20752,9 @@ var Environment = class {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`detach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
+      throw new Error(
+        `detach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
   }
   /**
@@ -20266,7 +20876,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 ?? "Unknown GraphQL error"}`);
+      throw new Error(
+        `${label}: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data;
   }
@@ -20801,6 +21413,9 @@ var EnvironmentSession = class extends Session {
   get envName() {
     return this.environment.envName;
   }
+  get tag() {
+    return this.environment.tag;
+  }
   get versionId() {
     return this.environment.versionId;
   }
@@ -20820,12 +21435,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);
   }
@@ -20968,7 +21742,7 @@ var Granular = class _Granular {
   onUnexpectedClose;
   onReconnectError;
   debugHttp = process.env.GRANULAR_DEBUG_HTTP === "1";
-  /** Sandbox-level effect registry: sandboxId → (effectKey → ToolWithHandler) */
+  /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
   /** Live sandbox-scoped effect hosts keyed by sandboxId */
   sandboxEffectHosts = /* @__PURE__ */ new Map();
@@ -21387,7 +22161,8 @@ var Granular = class _Granular {
       provenance: effect.provenance || { source: "custom" },
       tags: effect.tags,
       className: effect.className,
-      static: effect.static
+      static: effect.static,
+      versionSelector: effect.versionSelector
     };
   }
   async publishSandboxEffectCatalog(host) {
@@ -21575,7 +22350,10 @@ var Granular = class _Granular {
   async registerEffect(sandboxNameOrId, effect) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    this.getSandboxEffectMap(sandboxId).set(computeEffectKey2(effect), effect);
+    this.getSandboxEffectMap(sandboxId).set(
+      computeEffectRegistrationKey(effect),
+      effect
+    );
     await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
@@ -21588,7 +22366,7 @@ var Granular = class _Granular {
     const sandboxId = sandbox.sandboxId;
     const map = this.getSandboxEffectMap(sandboxId);
     for (const effect of effects2) {
-      map.set(computeEffectKey2(effect), effect);
+      map.set(computeEffectRegistrationKey(effect), effect);
     }
     await this.syncSandboxEffectCatalog(sandboxId);
   }
@@ -21606,7 +22384,7 @@ var Granular = class _Granular {
       return;
     }
     const nextEntries = Array.from(currentMap.entries()).filter(
-      ([effectKey, effect]) => effectKey !== name && effect.name !== name
+      ([, effect]) => computeEffectKey2(effect) !== name && effect.name !== name
     );
     if (nextEntries.length === currentMap.size) {
       return;
@@ -22053,14 +22831,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;
     }
@@ -22068,7 +22850,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) {
@@ -22077,7 +22860,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((environment) => matchesEnvironmentName(environment, environmentName));
+  const existing = environments.find(
+    (environment) => matchesEnvironmentName(environment, environmentName)
+  );
   if (existing) {
     return existing;
   }
@@ -22109,7 +22894,9 @@ async function listSessionsForEnvironment(granular, environmentId, status) {
 async function connectRuntime(options) {
   if (options.sessionId) {
     const { granular: granular2 } = createGranularClient();
-    const environment2 = await granular2.connectSession({ sessionId: options.sessionId });
+    const environment2 = await granular2.connectSession({
+      sessionId: options.sessionId
+    });
     return {
       granular: granular2,
       environment: environment2,
@@ -22120,7 +22907,9 @@ async function connectRuntime(options) {
   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 environmentHandle = await granular.connect({
     ontology: ontologyId,
@@ -22171,13 +22960,14 @@ 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)
     },
@@ -22187,7 +22977,7 @@ async function connectTestCommand(options) {
         ontologyId,
         sandboxId: environment.sandboxId,
         environmentId: environment.environmentId,
-        environment: environment.envName,
+        environment: environment.tag || requestedEnvironment,
         sessionId: environment.sessionId,
         subjectId: environment.subjectId,
         versionId: environment.versionId
@@ -22200,7 +22990,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,
@@ -22267,7 +23057,9 @@ async function sessionDocCommand(options) {
         ontologyId,
         sessionId: environment.sessionId,
         environmentId: environment.environmentId,
-        document: documentToJson(environment.document)
+        document: documentToJson(
+          environment.document
+        )
       };
       if (!emitJson) {
         step("Session document");
@@ -22279,6 +23071,7 @@ async function sessionDocCommand(options) {
 }
 async function sessionCreateCommand(options) {
   const emitJson = options.json === true;
+  const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
   }
@@ -22286,7 +23079,7 @@ 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,
@@ -22300,7 +23093,7 @@ async function sessionCreateCommand(options) {
       ok: true,
       ontologyId: envData.sandboxId,
       environmentId: environment.environmentId,
-      environment: environment.envName,
+      environment: environment.tag || envData.tag?.name || envData.buildPolicy.tagName || requestedEnvironment,
       sessionId: environment.sessionId,
       subjectId: environment.subjectId,
       versionId: environment.versionId
@@ -22313,7 +23106,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,
@@ -22331,21 +23124,26 @@ async function sessionCreateCommand(options) {
 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
   };