chainlesschain 0.166.47 → 0.166.56

package/src/lib/context-memory-kernel/provider-context.js

@@ -12,6 +12,9 @@ import {
   messagesToContextItems,
 } from "./message-adapter.js";
 
+export const SEMANTIC_CANDIDATE_REQUEST_SCHEMA =
+  "chainlesschain.context-memory-semantic-candidate-request/v1";
+
 function defaultAdmissions(sessionId, options) {
   const candidates = [
     { scope: "session", scopeId: sessionId },
@@ -32,6 +35,57 @@ function defaultAdmissions(sessionId, options) {
   });
 }
 
+function semanticCandidateProvider(options) {
+  const provider = options.contextMemorySemanticCandidateProvider;
+  if (provider == null) return null;
+  if (typeof provider !== "function") {
+    throw new TypeError(
+      "contextMemorySemanticCandidateProvider must be a function",
+    );
+  }
+  return provider;
+}
+
+/**
+ * Ask a host-owned semantic index for opaque record identifiers. The host sees
+ * the query and admission boundary but never receives canonical record content;
+ * the kernel later validates every returned revision/digest and applies its
+ * lifecycle, scope, expiry, and sink filters before ranking.
+ */
+async function resolveSemanticCandidates({
+  provider,
+  sessionId,
+  query,
+  sink,
+  scopeAdmissions,
+  limit,
+}) {
+  if (!provider) return undefined;
+  const candidates = await provider(
+    Object.freeze({
+      schema: SEMANTIC_CANDIDATE_REQUEST_SCHEMA,
+      sessionId,
+      query,
+      sink,
+      scopeAdmissions: Object.freeze(
+        scopeAdmissions.map((entry) => Object.freeze({ ...entry })),
+      ),
+      limit,
+      maxCandidates: 1000,
+    }),
+  );
+  if (!Array.isArray(candidates)) {
+    throw new TypeError(
+      "contextMemorySemanticCandidateProvider must resolve to an array",
+    );
+  }
+  return candidates.map((candidate) =>
+    candidate && typeof candidate === "object" && !Array.isArray(candidate)
+      ? Object.freeze({ ...candidate })
+      : candidate,
+  );
+}
+
 function toolDefinitionsToContextItems(definitionsInput, { sessionId, sink }) {
   const definitions = Array.isArray(definitionsInput) ? definitionsInput : [];
   return definitions.map((definition, index) => {
@@ -130,6 +184,7 @@ export async function prepareCanonicalProviderContext(
     };
   }
 
+  const candidateProvider = semanticCandidateProvider(options);
   const sink = String(options.contextMemorySink || `provider.${provider}`);
   const scopeAdmissions = defaultAdmissions(sessionId, options);
   const lastUser = [...messages]
@@ -139,18 +194,28 @@ export async function prepareCanonicalProviderContext(
     typeof lastUser?.content === "string" && lastUser.content.trim()
       ? lastUser.content.trim().slice(0, 32 * 1024)
       : "*";
+  const recallLimit = Math.max(
+    1,
+    Math.min(32, Number(options.contextMemoryRecallLimit) || 12),
+  );
+  const semanticCandidates = await resolveSemanticCandidates({
+    provider: candidateProvider,
+    sessionId,
+    query,
+    sink,
+    scopeAdmissions,
+    limit: recallLimit,
+  });
   const recall = await runtime.kernel.recallMemory({
     query,
     sink,
     scopeAdmissions,
-    limit: Math.max(
-      1,
-      Math.min(32, Number(options.contextMemoryRecallLimit) || 12),
-    ),
+    limit: recallLimit,
     tokenBudget: Math.max(
       1,
       Math.min(32_768, Number(options.contextMemoryRecallTokens) || 4096),
     ),
+    ...(semanticCandidates === undefined ? {} : { semanticCandidates }),
   });
   const messageItems = messagesToContextItems(messages, {
     sessionId,

package/src/lib/deferred-question-context.js

@@ -1,6 +1,17 @@
+import { normalizeInteractionBinding } from "./interaction-binding.js";
+
 const MAX_DEFERRED_ANSWERS_PER_CALL = 8;
 const MAX_DEFERRED_ANSWER_CHARS = 16_384;
 const MAX_DEFERRED_QUESTION_CHARS = 2_048;
+const MAX_DEFERRED_QUESTIONS = 32;
+const MAX_DEFERRED_OPTIONS = 32;
+
+export const DEFERRED_QUESTION_EVENTS = Object.freeze({
+  REQUESTED: "deferred_question_requested",
+  RESOLVED: "deferred_question_resolved",
+  CONSUMED: "deferred_question_consumed",
+  EXPIRED: "deferred_question_expired",
+});
 
 function boundedText(value, maxChars) {
   let text;
@@ -18,6 +29,145 @@ function boundedText(value, maxChars) {
   return `${text.slice(0, maxChars)}\n[truncated]`;
 }
 
+function cloneJson(value, fallback = null) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return fallback;
+  }
+}
+
+function normalizeBinding(value, sessionId = null) {
+  const binding = normalizeInteractionBinding(value);
+  if (
+    !Number.isSafeInteger(binding.sequence) ||
+    binding.sequence <= 0 ||
+    binding.sessionId == null ||
+    (sessionId != null && String(binding.sessionId) !== String(sessionId))
+  ) {
+    return null;
+  }
+  return binding;
+}
+
+function sameBinding(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function normalizeDeferredQuestionRequest(value, sessionId = null) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const questionId = String(value.questionId || value.requestId || "").trim();
+  const binding = normalizeBinding(value.binding, sessionId);
+  if (!questionId || questionId.length > 160 || !binding) return null;
+  return Object.freeze({
+    questionId,
+    question: boundedText(value.question || "", MAX_DEFERRED_QUESTION_CHARS),
+    options: Array.isArray(value.options)
+      ? cloneJson(value.options.slice(0, MAX_DEFERRED_OPTIONS), [])
+      : null,
+    multiSelect: value.multiSelect === true,
+    purpose: value.purpose === "preference" ? "preference" : "information",
+    binding,
+    requestedRevision: Number.isSafeInteger(
+      value.requestedRevision ?? value.contextRevision,
+    )
+      ? (value.requestedRevision ?? value.contextRevision)
+      : null,
+  });
+}
+
+export function normalizeDeferredQuestionAnswer(value, sessionId = null) {
+  const request = normalizeDeferredQuestionRequest(value, sessionId);
+  if (!request) return null;
+  return Object.freeze({
+    ...request,
+    answer: boundedText(value.answer, MAX_DEFERRED_ANSWER_CHARS),
+    resolvedRevision: Number.isSafeInteger(value.resolvedRevision)
+      ? value.resolvedRevision
+      : null,
+  });
+}
+
+function upsertBounded(map, key, value) {
+  map.delete(key);
+  map.set(key, value);
+  while (map.size > MAX_DEFERRED_QUESTIONS) {
+    map.delete(map.keys().next().value);
+  }
+}
+
+export function createDeferredQuestionEventReducer({ sessionId = null } = {}) {
+  const pending = new Map();
+  const answers = new Map();
+  let maxSequence = 0;
+  return {
+    accept(event) {
+      const data = event?.data || {};
+      if (event?.type === DEFERRED_QUESTION_EVENTS.REQUESTED) {
+        const record = normalizeDeferredQuestionRequest(data, sessionId);
+        if (
+          !record ||
+          pending.has(record.questionId) ||
+          answers.has(record.questionId) ||
+          record.binding.sequence <= maxSequence
+        ) {
+          return;
+        }
+        maxSequence = Math.max(maxSequence, record.binding.sequence);
+        upsertBounded(pending, record.questionId, record);
+        answers.delete(record.questionId);
+        return;
+      }
+      if (event?.type === DEFERRED_QUESTION_EVENTS.RESOLVED) {
+        const record = normalizeDeferredQuestionAnswer(data, sessionId);
+        const requested = record && pending.get(record.questionId);
+        if (
+          !record ||
+          !requested ||
+          !sameBinding(requested.binding, record.binding)
+        ) {
+          return;
+        }
+        pending.delete(record.questionId);
+        upsertBounded(answers, record.questionId, record);
+        return;
+      }
+      if (
+        event?.type === DEFERRED_QUESTION_EVENTS.CONSUMED ||
+        event?.type === DEFERRED_QUESTION_EVENTS.EXPIRED
+      ) {
+        const ids = Array.isArray(data.questionIds)
+          ? data.questionIds
+          : [data.questionId || data.requestId];
+        for (const value of ids) {
+          const questionId = String(value || "").trim();
+          if (!questionId) continue;
+          pending.delete(questionId);
+          answers.delete(questionId);
+        }
+      }
+    },
+    finish() {
+      return Object.freeze({
+        pendingQuestions: Object.freeze(
+          [...pending.values()].map((entry) => Object.freeze({ ...entry })),
+        ),
+        answers: Object.freeze(
+          [...answers.values()].map((entry) => Object.freeze({ ...entry })),
+        ),
+        maxSequence,
+      });
+    },
+  };
+}
+
+export function reduceDeferredQuestionEvents(events, options = {}) {
+  const reducer = createDeferredQuestionEventReducer(options);
+  for (const event of Array.isArray(events) ? events : [])
+    reducer.accept(event);
+  return reducer.finish();
+}
+
 /**
  * Session-scoped inbox for answers to non-blocking, informational questions.
  * Answers are consumed once as transient user context; they are never persisted
@@ -75,15 +225,21 @@ export class DeferredQuestionContext {
 
   prepareCall({ currentRevision = null } = {}) {
     if (this._answers.length === 0) return null;
-    const answers = this._answers.splice(0, MAX_DEFERRED_ANSWERS_PER_CALL);
+    const answers = this._answers.slice(0, MAX_DEFERRED_ANSWERS_PER_CALL);
     if (this._onConsumed) {
       try {
-        this._onConsumed(answers.map((entry) => entry.questionId));
+        if (
+          this._onConsumed(answers.map((entry) => entry.questionId)) === false
+        ) {
+          return null;
+        }
       } catch {
-        // Context delivery is authoritative for this process. A persistence
-        // callback failure must not duplicate user context in the same run.
+        // Do not inject context unless its one-shot consumption is durably
+        // acknowledged. A later call can retry without duplicating the answer.
+        return null;
       }
     }
+    this._answers.splice(0, answers.length);
     const revision = Number.isSafeInteger(currentRevision)
       ? currentRevision
       : null;