@granular-software/sdk 0.4.25 → 0.4.27

package/dist/index.js

@@ -4610,6 +4610,22 @@ var Session = class {
       }
     };
   }
+  stringifyConversationValue(value) {
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "boolean") {
+      return value ? "Confirmed" : "Canceled";
+    }
+    if (value === void 0) {
+      return "";
+    }
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
   // --- Public API ---
   get document() {
     return this.client.doc;
@@ -4760,6 +4776,20 @@ var Session = class {
       answer: resolvedAnswer,
       value: resolvedAnswer
     });
+    try {
+      const content = this.stringifyConversationValue(resolvedAnswer);
+      if (content.trim()) {
+        await this.appendConversationMessage({
+          role: "user",
+          content,
+          promptId
+        });
+      }
+    } catch {
+    }
+  }
+  async appendConversationMessage(input) {
+    return this.client.call("conversation.append", input);
   }
   /**
    * Get the current list of available effects.
@@ -4899,9 +4929,24 @@ var Session = class {
    * Get domain documentation for LLMs. Returns types (preferred) or fallback.
    */
   async getDomainDocumentation() {
-    const types = await this.getDomainTypes();
-    if (types && (types.includes("export declare class") || types.includes("export async function"))) {
-      return types;
+    const [types, docs] = await Promise.all([
+      this.getDomainTypes(),
+      this.getDomainDocs()
+    ]);
+    const normalizedTypes = types.trim();
+    const normalizedDocs = docs.trim();
+    if (normalizedTypes && (normalizedTypes.includes("export declare class") || normalizedTypes.includes("export async function"))) {
+      if (!normalizedDocs) {
+        return normalizedTypes;
+      }
+      return [
+        normalizedTypes,
+        "Generated usage notes from ./sandbox-tools docs:",
+        normalizedDocs
+      ].join("\n\n");
+    }
+    if (normalizedDocs) {
+      return normalizedDocs;
     }
     const summary = await this.getDomain();
     return this.generateFallbackDocs(summary);
@@ -9711,10 +9756,15 @@ external_exports.union([
     scalarType: external_exports.string().optional()
   }).strict()
 ]);
+external_exports.union([
+  external_exports.boolean(),
+  external_exports.object({
+    enabled: external_exports.boolean().optional(),
+    phonetic: external_exports.boolean().optional()
+  }).strict()
+]);
 external_exports.object({
-  operator: external_exports.enum(
-    [...VALIDATION_RULE_OPERATORS]
-  ),
+  operator: external_exports.enum([...VALIDATION_RULE_OPERATORS]),
   stringValue: external_exports.string().optional(),
   numberValue: external_exports.number().optional(),
   booleanValue: external_exports.boolean().optional(),
@@ -9807,12 +9857,18 @@ function collectMetamodelSummarySelections(packages) {
   const propertyFields = [];
   const methodFields = [];
   for (const metamodelPackage of packages) {
-    pushUnique(classFields, metamodelPackage.summary.selections?.classFields || []);
+    pushUnique(
+      classFields,
+      metamodelPackage.summary.selections?.classFields || []
+    );
     pushUnique(
       propertyFields,
       metamodelPackage.summary.selections?.propertyFields || []
     );
-    pushUnique(methodFields, metamodelPackage.summary.selections?.methodFields || []);
+    pushUnique(
+      methodFields,
+      metamodelPackage.summary.selections?.methodFields || []
+    );
   }
   return {
     classFields: unique(classFields),
@@ -9900,7 +9956,11 @@ function createMetamodelRegistry(metamodelPackages) {
       return collectMetamodelSummarySelections(packages);
     },
     applyClassSummaryReaders(rawClass, classSummary) {
-      return applyMetamodelSummaryReadersToClass(packages, rawClass, classSummary);
+      return applyMetamodelSummaryReadersToClass(
+        packages,
+        rawClass,
+        classSummary
+      );
     },
     applyPropertySummaryReaders(rawProperty, propertySummary) {
       return applyMetamodelSummaryReadersToProperty(
@@ -9910,7 +9970,11 @@ function createMetamodelRegistry(metamodelPackages) {
       );
     },
     applyMethodSummaryReaders(rawMethod, methodSummary) {
-      return applyMetamodelSummaryReadersToMethod(packages, rawMethod, methodSummary);
+      return applyMetamodelSummaryReadersToMethod(
+        packages,
+        rawMethod,
+        methodSummary
+      );
     },
     applyClassIR(classIR, classSummary) {
       return applyMetamodelClassIR(packages, classIR, classSummary);
@@ -9958,6 +10022,10 @@ function mergeClassSummaryPatch(target, patch) {
 }
 function mergePropertySummaryPatch(target, patch) {
   pushUnique(target.notes, patch.notes || []);
+  if (patch.searchable !== void 0) target.searchable = patch.searchable;
+  if (patch.searchablePhonetic !== void 0) {
+    target.searchablePhonetic = patch.searchablePhonetic;
+  }
   if (patch.required !== void 0) target.required = patch.required;
   if (patch.enumRule !== void 0) target.enumRule = patch.enumRule;
   if (patch.filterBy !== void 0) target.filterBy = patch.filterBy;
@@ -9969,9 +10037,11 @@ function mergeMethodSummaryPatch(target, patch) {
   if (patch.effectKey !== void 0) target.effectKey = patch.effectKey;
   if (patch.description !== void 0) target.description = patch.description;
   if (patch.inputSchema !== void 0) target.inputSchema = patch.inputSchema;
-  if (patch.outputSchema !== void 0) target.outputSchema = patch.outputSchema;
+  if (patch.outputSchema !== void 0)
+    target.outputSchema = patch.outputSchema;
   if (patch.metamodels !== void 0) target.metamodels = patch.metamodels;
-  if (patch.effectBehaviors !== void 0) target.effectBehaviors = patch.effectBehaviors;
+  if (patch.effectBehaviors !== void 0)
+    target.effectBehaviors = patch.effectBehaviors;
   if (patch.static !== void 0) target.static = patch.static;
 }
 function toPascalCase(value) {
@@ -10477,12 +10547,20 @@ function defaultFilterOperators(scalarType) {
   switch ((scalarType || "").toLowerCase()) {
     case "number":
     case "date":
-      return ["equal_to", "greater_than", "less_than", "not_null"];
+      return [
+        "equal_to",
+        "greater_than",
+        "greater_than_or_equal_to",
+        "less_than",
+        "less_than_or_equal_to",
+        "not_null"
+      ];
     case "boolean":
-      return ["equal_to", "not_null"];
+      return ["equal_to", "true", "false", "not_null"];
     default:
       return [
         "equal_to",
+        "in",
         "contains",
         "not_contains",
         "starts_with",
@@ -10491,16 +10569,26 @@ function defaultFilterOperators(scalarType) {
       ];
   }
 }
+function supportsDefaultFilterBy(scalarType) {
+  return ["string", "number", "boolean", "date"].includes(
+    String(scalarType || "").toLowerCase()
+  );
+}
 function normalizeFilterByInput(filterBy, scalarType) {
-  if (!filterBy) return null;
+  if (filterBy === false) return null;
+  if (filterBy === void 0) {
+    if (!supportsDefaultFilterBy(scalarType)) return null;
+    return { operators: defaultFilterOperators(scalarType), scalarType };
+  }
   if (filterBy === true) {
-    return { operators: defaultFilterOperators(scalarType) };
+    return { operators: defaultFilterOperators(scalarType), scalarType };
   }
   if (Array.isArray(filterBy)) {
-    return { operators: filterBy };
+    return { operators: filterBy, scalarType };
   }
   return {
-    operators: filterBy.operators
+    operators: filterBy.operators,
+    scalarType: filterBy.scalarType || scalarType
   };
 }
 function buildFilterByFieldMutations(fieldPath, filterBy, scalarType) {
@@ -10511,7 +10599,7 @@ function buildFilterByFieldMutations(fieldPath, filterBy, scalarType) {
       label: `set filterBy on ${fieldPath}`,
       query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_filter_by(operators: ${JSON.stringify(
         normalized.operators
-      )}) { operators } } }`
+      )}${normalized.scalarType ? `, scalar_type: ${JSON.stringify(normalized.scalarType)}` : ""}) { operators } } }`
     }
   ];
 }
@@ -10521,7 +10609,7 @@ var filterByMetamodelPackage = defineMetamodelPackage({
     fieldRows: [
       {
         key: "filterBy",
-        description: "Exposes filter operators for generated query surfaces. Accepts `true`, an operator array, or `{ operators, scalarType }`."
+        description: "Exposes filter operators for generated query surfaces. Scalar fields are filterable by default; set `filterBy: false` to opt out, or override with `true`, an operator array, or `{ operators, scalarType }`."
       }
     ]
   },
@@ -10785,6 +10873,123 @@ var requiredMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// ../metamodel-searchable/src/index.ts
+function supportsDefaultSearchable(scalarType) {
+  return String(scalarType || "").toLowerCase() === "string";
+}
+function normalizeSearchableInput(searchable, scalarType) {
+  if (!supportsDefaultSearchable(scalarType)) return null;
+  if (typeof searchable === "boolean" || searchable === void 0) {
+    return {
+      enabled: searchable !== false,
+      phonetic: false
+    };
+  }
+  const enabled = searchable.enabled !== false;
+  return {
+    enabled,
+    phonetic: enabled && searchable.phonetic === true
+  };
+}
+function buildSearchableFieldMutations(fieldPath, searchable, scalarType) {
+  const normalized = normalizeSearchableInput(searchable, scalarType);
+  if (normalized === null) return [];
+  return [
+    {
+      label: `set searchable on ${fieldPath}`,
+      query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_searchable(enabled: ${normalized.enabled}, phonetic: ${normalized.phonetic}) { enabled phonetic } } }`
+    }
+  ];
+}
+var searchableMetamodelPackage = defineMetamodelPackage({
+  id: "searchable",
+  docs: {
+    fieldRows: [
+      {
+        key: "searchable",
+        description: "Controls full-text search exposure for string fields. String fields are searchable by default; set `searchable: false` to opt out, or use `searchable: { phonetic: true }` to keep the field searchable while enabling FalkorDB phonetic matching for class-wide search."
+      }
+    ]
+  },
+  graphql: {
+    typeDefs: [
+      `
+      type SearchableMetamodel {
+        model: Model!
+        enabled: Boolean!
+        phonetic: Boolean!
+      }
+
+      extend type Model {
+        searchable: SearchableMetamodel
+      }
+
+      extend type ModelMutation {
+        set_searchable(enabled: Boolean!, phonetic: Boolean): SearchableMetamodel
+      }
+      `
+    ],
+    createResolvers({ run }) {
+      return {
+        SearchableMetamodel: {
+          model: (value) => value.model,
+          enabled: (value) => value.enabled !== false,
+          phonetic: (value) => value.phonetic === true
+        },
+        Model: {
+          searchable: async (ant) => await run(ant.searchable())
+        },
+        ModelMutation: {
+          set_searchable: async (ant, { enabled, phonetic }) => {
+            return {
+              model: await run(ant.set_searchable(enabled, phonetic === true)),
+              enabled,
+              phonetic: phonetic === true
+            };
+          }
+        }
+      };
+    }
+  },
+  manifest: {
+    buildFieldMutations(fieldPath, spec) {
+      return buildSearchableFieldMutations(
+        fieldPath,
+        spec.searchable,
+        spec.type
+      );
+    }
+  },
+  summary: {
+    selections: {
+      propertyFields: [`searchable { enabled phonetic }`]
+    },
+    readPropertySummary(rawProperty) {
+      if (typeof rawProperty.searchable?.enabled !== "boolean") {
+        return {};
+      }
+      return {
+        searchable: rawProperty.searchable.enabled,
+        searchablePhonetic: rawProperty.searchable.phonetic === true
+      };
+    }
+  },
+  domain: {
+    applyToPropertyIR(propertyIR, propertySummary) {
+      if (String(propertySummary.type || "").toLowerCase() !== "string" || propertySummary.searchable === false) {
+        return propertyIR;
+      }
+      return {
+        ...propertyIR,
+        docs: [
+          ...propertyIR.docs,
+          propertySummary.searchablePhonetic ? "Searchable via `search` using FalkorDB full-text query syntax with phonetic matching enabled." : "Searchable via `search` using FalkorDB full-text query syntax."
+        ]
+      };
+    }
+  }
+});
+
 // ../metamodel-state-machine/src/index.ts
 function normalizeStateMachines(values) {
   return (values || []).map((machine) => {
@@ -11365,6 +11570,7 @@ var DEFAULT_METAMODEL_PACKAGES = [
   requiredMetamodelPackage,
   enumMetamodelPackage,
   filterByMetamodelPackage,
+  searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
   effectBehaviorsMetamodelPackage
@@ -14784,6 +14990,306 @@ function resolveJobPresentation({
   };
 }
 
+// src/session-transcript.ts
+var EMPTY_HEAP = {
+  entriesByPath: {},
+  listsByName: {},
+  variablesByName: {}};
+function asRecord4(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function asArray2(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 = asRecord4(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, fallback = "") {
+  if (typeof value === "string") {
+    return value.trim() || fallback;
+  }
+  if (typeof value === "boolean") {
+    return value ? "Confirmed" : "Canceled";
+  }
+  if (value === void 0) {
+    return fallback;
+  }
+  try {
+    const json = JSON.stringify(value, null, 2);
+    if (!json || json === "undefined") return fallback;
+    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 = asRecord4(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 = asRecord4(rawPrompts) || {};
+  return Object.values(promptsById).map((value) => asRecord4(value)).filter((value) => Boolean(value)).sort(
+    (left, right) => (asNumber(left.openedAt) || asNumber(left.answeredAt) || 0) - (asNumber(right.openedAt) || asNumber(right.answeredAt) || 0)
+  ).flatMap((prompt) => {
+    const promptId = asString(prompt.promptId);
+    if (!promptId || conversationPromptIds.has(promptId)) return [];
+    const title = trimString(prompt.title);
+    const message = trimString(prompt.message);
+    const assistantContent = message || title || "Input required";
+    const openedAt = asNumber(prompt.openedAt) || 0;
+    const answeredAt = asNumber(prompt.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(prompt, "answer")) {
+      entries.push({
+        id: `prompt:${promptId}:user`,
+        role: "user",
+        content: stringifyTranscriptValue(prompt.answer, ""),
+        timestamp: answeredAt,
+        jobId,
+        promptId,
+        source: "job_prompt"
+      });
+    }
+    return entries;
+  });
+}
+function normalizeAgentMessageEntries(jobId, rawMessages) {
+  return asArray2(rawMessages).map((value) => asRecord4(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, job, sessionHeap) {
+  const timestamp = asNumber(job.finishedAt) || asNumber(job.startedAt) || asNumber(job.submittedAt) || 0;
+  const resultPreview = stringifyTranscriptValue(
+    job.result,
+    "No job result recorded."
+  );
+  const presentation = resolveJobPresentation({
+    jobId,
+    result: job.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(job.error)) {
+    entries.push({
+      id: `job:${jobId}:result-error`,
+      role: "assistant",
+      content: trimString(job.error),
+      timestamp,
+      jobId,
+      historyContent: `[Assistant reply]
+${trimString(job.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, job) {
+  const code = trimString(job.source);
+  if (!code) return null;
+  const jobStatus = asString(job.status);
+  const error = jobStatus === "failed" || jobStatus === "canceled" || jobStatus === "timeout" ? trimString(job.error) || `Job ${jobStatus}` : void 0;
+  return {
+    id: `job:${jobId}:code`,
+    role: "assistant",
+    content: "",
+    timestamp: asNumber(job.submittedAt) || asNumber(job.startedAt) || asNumber(job.finishedAt) || 0,
+    jobId,
+    code,
+    jobStatus,
+    jobResultPreview: stringifyTranscriptValue(job.result, "No job result recorded."),
+    error,
+    source: "job_code"
+  };
+}
+function buildSessionTranscript(input) {
+  const liveDoc = input.liveDoc || null;
+  const sessionHeap = input.sessionHeap || EMPTY_HEAP;
+  const transcript = [];
+  const conversationMessages = asArray2(asRecord4(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 = asRecord4(asRecord4(liveDoc?.jobs)?.byId) || {};
+  const jobs = Object.values(jobsById).map((value) => asRecord4(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 job of jobs) {
+    const jobId = asString(job.jobId);
+    if (!jobId) continue;
+    const codeEntry = buildJobCodeEntry(jobId, job);
+    if (codeEntry) {
+      transcript.push(codeEntry);
+    }
+    transcript.push(
+      ...normalizePromptEntries(jobId, job.prompts, conversationPromptIds)
+    );
+    if (!assistantConversationJobIds.has(jobId)) {
+      const agentEntries = normalizeAgentMessageEntries(jobId, job.agentMessages);
+      if (agentEntries.length > 0) {
+        transcript.push(...agentEntries);
+      } else {
+        transcript.push(
+          ...buildJobFallbackEntries(
+            jobId,
+            job,
+            sessionHeap
+          )
+        );
+      }
+    }
+  }
+  return transcript.sort((left, right) => {
+    if (left.timestamp !== right.timestamp) {
+      return left.timestamp - right.timestamp;
+    }
+    return left.id.localeCompare(right.id);
+  });
+}
+
 exports.Environment = Environment;
 exports.Granular = Granular;
 exports.Session = Session;
@@ -14797,6 +15303,7 @@ exports.buildGranularAgentSessionBlock = buildGranularAgentSessionBlock;
 exports.buildGranularAgentSystemPrompt = buildGranularAgentSystemPrompt;
 exports.buildGranularAgentToolBlock = buildGranularAgentToolBlock;
 exports.buildGranularAgentWorkflowBlock = buildGranularAgentWorkflowBlock;
+exports.buildSessionTranscript = buildSessionTranscript;
 exports.createHarnessVerifierSnapshot = createHarnessVerifierSnapshot;
 exports.evaluateContinuation = evaluateContinuation;
 exports.extractPromptTokens = extractPromptTokens;