@jskit-ai/assistant-core 0.1.200 → 0.1.202

package/src/server/conversation/runtimeStateUpgrade.js

@@ -0,0 +1,125 @@
+const engines = new Set(["api", "claude", "codex", "opencode"]);
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+
+function invalid(message) {
+  throw Object.assign(new Error(message), { code: "conversation_runtime_upgrade_unavailable" });
+}
+
+export function hasUnfinishedConversationRewind(runtime) {
+  const pending = runtime?.replacement;
+  return pending?.reason === "rewind" || pending?.request?.reason === "rewind" ||
+    object(pending?.request) && Object.hasOwn(pending.request, "throughTurnId") ||
+    Array.isArray(pending?.supersededTurns) && pending.supersededTurns.length > 0;
+}
+
+function validateSegment(segment) {
+  if (!object(segment) || !engines.has(segment.engine) || typeof segment.segmentId !== "string" ||
+      !segment.segmentId || !object(segment.configuration) || !object(segment.seen) ||
+      Object.values(segment.seen).some(value => typeof value !== "string") ||
+      Object.hasOwn(segment, "preparedAt") && typeof segment.preparedAt !== "string") {
+    invalid("Conversation runtime has an unsupported segment. Inspect its saved state before upgrading.");
+  }
+  if (segment.engine !== "api" && !object(segment.binding)) {
+    invalid("A native conversation has no saved binding. Restore its exact identity before upgrading.");
+  }
+  if (segment.engine === "opencode" && segment.binding.sessionId &&
+      (typeof segment.binding.databasePath !== "string" || !segment.binding.databasePath)) {
+    invalid("This OpenCode conversation uses an older private database binding. A complete offline native-history upgrade is required before this metadata upgrade; its database was not changed.");
+  }
+}
+
+function nativeIdentity(segment) {
+  return segment.engine === "codex" ? segment.binding.threadId
+    : segment.engine === "claude" ? segment.binding.conversationId : segment.binding.sessionId;
+}
+
+function inspectRequest(request, segment, version, warnings) {
+  if (request === undefined) return;
+  if (!object(request) || typeof request.messageId !== "string" || !request.messageId ||
+      typeof request.text !== "string" || !Array.isArray(request.attachments) ||
+      typeof request.at !== "string") {
+    invalid("Conversation runtime has an unsupported pending request. Inspect it before upgrading.");
+  }
+  if (segment.engine === "api") return;
+  const threadId = nativeIdentity(segment);
+  if (version === 3 && !Object.hasOwn(request, "inspectionOnly")) {
+    if (typeof request.attempted !== "boolean" || request.attempted &&
+        (typeof threadId !== "string" || !threadId || request.threadId !== threadId || typeof request.message !== "string") ||
+        Object.hasOwn(request, "message") && (typeof request.message !== "string" || typeof request.displayMessage !== "string" ||
+          !Array.isArray(request.displayAttachments) || !Array.isArray(request.attachmentIds) || !object(request.seen)) ||
+        Object.hasOwn(request, "contextText") && (typeof request.contextText !== "string" || !Array.isArray(request.contextAttachments)) ||
+        Object.hasOwn(request, "attachmentManifest") && typeof request.attachmentManifest !== "string") {
+      invalid("A native delivery journal has an unsupported frozen prompt or identity. Inspect it before upgrading.");
+    }
+    return;
+  }
+  if (typeof threadId !== "string" || !threadId) {
+    invalid("A pending native request has no exact saved conversation identity. Resolve its delivery with the previous candidate before upgrading; it cannot be replayed safely.");
+  }
+  if (version === 3) {
+    if (request.inspectionOnly !== true || request.threadId !== threadId || Object.hasOwn(request, "message")) {
+      invalid("An inspection-only request conflicts with its saved native identity or prompt. Inspect it before upgrading.");
+    }
+    return;
+  }
+  if (["message", "displayMessage", "displayAttachments", "attachmentIds", "attempted", "threadId", "turnMetadata", "inspectionOnly",
+    "contextText", "contextAttachments", "attachmentManifest"]
+    .some(name => Object.hasOwn(request, name))) {
+    invalid("A version 2 pending request contains unknown native delivery fields. Inspect it before upgrading.");
+  }
+  // Version 2 saved authored content and a cursor, but never the rendered prompt.
+  // The existing exact binding is enough for receipt inspection, never replay.
+  request.inspectionOnly = true;
+  request.threadId = threadId;
+  warnings.push(`The retained ${segment.engine} request requires native receipt inspection. Its missing prompt was not reconstructed and will not be replayed.`);
+}
+
+/** Pure offline transform. The application owns enumeration, backups and publication. */
+export function upgradeConversationRuntimeState({ metadata, conversationLog }) {
+  if (!object(metadata) || !Array.isArray(conversationLog)) {
+    invalid("Conversation runtime upgrade requires metadata and the complete stored transcript.");
+  }
+  if (metadata.runtime === undefined) return { metadata, changed: false, warnings: [] };
+  const source = metadata.runtime;
+  if (!object(source) || ![2, 3].includes(source.version) || !Array.isArray(source.predecessors)) {
+    invalid("This conversation has an unsupported runtime version. Inspect its original format and provide an offline conversion before opening it.");
+  }
+  if (hasUnfinishedConversationRewind(source)) {
+    invalid("This conversation has an unfinished Undo operation from an earlier runtime. Inspect its saved native and local history offline before upgrading; no history was changed.");
+  }
+  if (source.version === 3 && (typeof source.lastEngine !== "string" || source.lastEngine && !engines.has(source.lastEngine))) {
+    invalid("Conversation runtime has an invalid last-delivered engine. Inspect it before upgrading.");
+  }
+  const runtime = structuredClone(source);
+  const warnings = [];
+  for (const segment of [...runtime.predecessors, runtime]) {
+    validateSegment(segment);
+    inspectRequest(segment.request, segment, source.version, warnings);
+  }
+  if (runtime.replacement !== undefined) {
+    const pending = runtime.replacement;
+    if (!object(pending) || !engines.has(pending.engine) || typeof pending.segmentId !== "string" ||
+        !pending.segmentId || !object(pending.configuration) ||
+        Object.hasOwn(pending, "preparedAt") && typeof pending.preparedAt !== "string") {
+      invalid("Conversation runtime has an unsupported unfinished replacement. Finish or inspect it before upgrading.");
+    }
+    if (pending.binding) {
+      validateSegment(pending);
+      inspectRequest(pending.submission, pending, source.version, warnings);
+    } else if (pending.submission !== undefined) {
+      invalid("An unfinished replacement has a request without its exact saved binding. Inspect it before upgrading.");
+    }
+  }
+  if (source.version === 3) return { metadata, changed: false, warnings: [] };
+  let lastEngine = "";
+  for (const turn of conversationLog) {
+    if (!object(turn) || !Array.isArray(turn.messages)) invalid("Conversation history has an unsupported turn. Inspect it before upgrading.");
+    const attribution = turn.metadata?.runtime;
+    if (!attribution || attribution.supersededBy || !turn.messages.some(message => ["user", "system"].includes(message.role))) continue;
+    if (!engines.has(attribution.engine)) invalid("An accepted conversation turn has an unknown engine. Inspect its attribution before upgrading.");
+    lastEngine = attribution.engine;
+  }
+  runtime.version = 3;
+  runtime.lastEngine = lastEngine;
+  return { metadata: { ...metadata, runtime }, changed: true, warnings };
+}

package/src/server/conversation/storage.js

@@ -0,0 +1,184 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const conversationMessageRoles = ["assistant", "commentary", "system", "thinking", "user"];
+
+export function createConversationOperationLease() {
+  let resolveIdle = () => null;
+  const idle = new Promise((resolve) => {
+    resolveIdle = resolve;
+  });
+  return {
+    idle,
+    operations: 0,
+    resolveIdle
+  };
+}
+
+export function beginConversationOperation(lease) {
+  lease.operations += 1;
+  return {
+    active: true
+  };
+}
+
+export function finishConversationOperation(lease, participant) {
+  participant.active = false;
+  lease.operations -= 1;
+  if (lease.operations === 0) {
+    lease.resolveIdle();
+  }
+}
+
+/** Nested native store operations share the host's current transaction. The
+ * supplied storage remains the only writer queue and commit/rollback owner.
+ */
+export function createReentrantConversationStorage(storage) {
+  if (typeof storage?.read !== "function" || typeof storage?.write !== "function") {
+    throw new TypeError("Conversation storage requires read(scope, callback) and write(scope, callback).");
+  }
+  const mutationContext = new AsyncLocalStorage();
+
+  function inherited(scope) {
+    const context = mutationContext.getStore();
+    return context?.scope === scope && context.participant?.active === true ? context : null;
+  }
+
+  async function participate(context, operation) {
+    const participant = beginConversationOperation(context.lease);
+    try {
+      return await mutationContext.run({ ...context, participant }, () => operation(context.transaction));
+    } finally {
+      finishConversationOperation(context.lease, participant);
+    }
+  }
+
+  return Object.freeze({
+    ...storage,
+    read(scope, operation) {
+      const context = inherited(scope);
+      return context ? participate(context, operation) : storage.read(scope, operation);
+    },
+    write(scope, operation) {
+      const context = inherited(scope);
+      if (context) return participate(context, operation);
+      return storage.write(scope, async transaction => {
+        const lease = createConversationOperationLease();
+        const participant = beginConversationOperation(lease);
+        try {
+          return await mutationContext.run({ scope, transaction, lease, participant }, () => operation(transaction));
+        } finally {
+          finishConversationOperation(lease, participant);
+          await lease.idle;
+        }
+      });
+    },
+    ...(typeof storage.deleteConversation === "function"
+      ? { deleteConversation: scope => storage.deleteConversation(scope) } : {})
+  });
+}
+
+function conversationMessageStorageKey({ role, at, messageId } = {}) {
+  const normalizedRole = String(role || "").trim();
+  if (!conversationMessageRoles.includes(normalizedRole)) return null;
+  const date = at instanceof Date ? at : new Date(at);
+  if (Number.isNaN(date.getTime())) return null;
+  const timestamp = date.toISOString().replace(/[-:]/gu, "").replace(".", "");
+  const normalizedMessageId = String(messageId || "").trim();
+  const idSuffix = normalizedMessageId ? `.${normalizedMessageId}` : "";
+  // The original transcript overwrote this same role/timestamp/id file. Its
+  // filesystem suffix restrictions do not apply to record-native message IDs.
+  return `${normalizedRole}.${timestamp}${idSuffix}.md`;
+}
+
+/** Transaction implementation for single-writer record adapters. This serializes
+ * one instance's writes; a database with multiple writers must also hold its own
+ * transaction/lock across readRecord and writeRecord, or implement read/write directly.
+ */
+export function createConversationStorage({ readRecord, writeRecord, deleteRecord }) {
+  const pending = new Map();
+
+  function key(scope) {
+    if (typeof scope !== "string" || !scope.trim()) throw new TypeError("Conversation scope must be a nonempty string.");
+    return scope;
+  }
+
+  function transaction(record) {
+    const turns = record.turns;
+    return {
+      async readMetadata() { return structuredClone(record.metadata); },
+      async writeMetadata(value) { record.metadata = structuredClone(value); },
+      async updateTurnMetadata(id, patch) {
+        const turn = turns.get(id);
+        if (!turn) throw new Error("The conversation turn does not exist.");
+        turn.metadata = { ...turn.metadata, ...structuredClone(patch) };
+      },
+      async listTurnIds() { return [...turns.keys()]; },
+      async nextTurnId() { return String(Math.max(0, ...[...turns.keys()].map(Number).filter(Number.isSafeInteger)) + 1).padStart(6, "0"); },
+      async hasMessage(id) {
+        return Boolean(id) && [...turns.values()].some((turn) => turn.messages.some((message) => message.messageId === id));
+      },
+      async readTurn(id) {
+        const turn = turns.get(id);
+        if (!turn) return null;
+        const find = (role) => turn.messages.find((message) => message.role === role) || null;
+        const thinking = turn.messages.filter((message) => message.role === "thinking");
+        const commentary = turn.messages.filter((message) => message.role === "commentary");
+        const activity = [...thinking, ...commentary].sort((a, b) => a.at.localeCompare(b.at));
+        const system = find("system"), user = find("user"), assistant = find("assistant");
+        return structuredClone({
+          turnId: id, user, assistant, thinking, commentary,
+          ...(system ? { system } : {}), ...(turn.metadata ? { metadata: turn.metadata } : {}),
+          messages: [system, user, ...activity, assistant].filter(Boolean)
+        });
+      },
+      async appendMessage(id, { turnMetadata, ...message }) {
+        const turn = turns.get(id) || { messages: [] };
+        if (turnMetadata) turn.metadata = structuredClone(turnMetadata);
+        const identity = conversationMessageStorageKey(message);
+        const existing = identity === null ? -1 : turn.messages.findIndex((previous) =>
+          conversationMessageStorageKey(previous) === identity);
+        if (existing < 0) turn.messages.push(structuredClone(message));
+        else turn.messages[existing] = structuredClone(message);
+        turns.set(id, turn);
+      },
+      async replaceAssistant(id, message) {
+        if (!id) throw new TypeError("Assistant replacement requires a turn id.");
+        const turn = turns.get(id) || { messages: [] };
+        const previous = turn.messages.find((entry) => entry.role === "assistant");
+        turn.messages = turn.messages.filter((entry) => entry.role !== "assistant");
+        turn.messages.push({ ...previous, ...structuredClone(message), at: previous?.at || message.at });
+        turns.set(id, turn);
+      }
+    };
+  }
+
+
+  async function write(scope, callback, remove = false) {
+    const id = key(scope);
+    const previous = pending.get(id) || Promise.resolve();
+    const operation = previous.then(async () => {
+      const draft = structuredClone(await readRecord(id));
+      const view = transaction(draft);
+      const result = await callback(view);
+      if (remove) await deleteRecord(id);
+      else await writeRecord(id, draft, view);
+      return result;
+    });
+    const settled = operation.then(() => undefined, () => undefined);
+    pending.set(id, settled);
+    try { return await operation; }
+    finally { if (pending.get(id) === settled) pending.delete(id); }
+  }
+
+  return Object.freeze({
+    write,
+    async read(scope, callback) {
+      const id = key(scope);
+      await pending.get(id);
+      return callback(transaction(structuredClone(await readRecord(id))));
+    },
+    async deleteConversation(scope) {
+      await write(scope, async () => {}, true);
+    }
+  });
+}

package/src/server/conversation/streams.js

@@ -11,7 +11,7 @@ export function createConversationStreams({ clock = () => new Date() } = {}) {
     };
   }
 
-  function update(scope, { turnId, messageId, role = "assistant", text, delta, at } = {}) {
+  function update(scope, { turnId, messageId, role = "assistant", text, delta, at, origin, nativeIdentity, outputId } = {}) {
     if (!turnId || !messageId || !["assistant", "commentary"].includes(role)) return null;
     let stream = streams.get(scope);
     if (!stream || stream.turnId !== turnId) {
@@ -22,12 +22,17 @@ export function createConversationStreams({ clock = () => new Date() } = {}) {
     const previous = stream.messages.get(messageId);
     const next = {
       messageId,
+      ...((previous?.outputId || outputId) ? { outputId: previous?.outputId || outputId } : {}),
+      // Native grouping is private even when its authored origin is known.
+      // Ordinary runtime output already carries the exact authored row identity.
+      ...(["user", "application"].includes(origin || previous?.origin)
+        ? { ...(!nativeIdentity ? { turnId } : {}), origin: origin || previous.origin } : {}),
       role: previous?.role || role,
       at: previous?.at || at || clock().toISOString(),
       text: typeof delta === "string" ? (previous?.text || "") + delta : (text ?? previous?.text ?? ""),
       status: "inProgress"
     };
-    if (previous?.text === next.text && previous.role === next.role) return null;
+    if (previous?.text === next.text && previous.role === next.role && previous.outputId === next.outputId) return null;
     stream.messages.set(messageId, next);
     revision += 1;
     return read(scope);

package/src/server/conversation/structuredOutput.js

@@ -0,0 +1,240 @@
+const OUTPUT_SCHEMA_MAX_BYTES = 64 * 1024;
+const OUTPUT_SCHEMA_MAX_DEPTH = 8;
+const OUTPUT_SCHEMA_MAX_PROPERTIES = 64;
+const OUTPUT_SCHEMA_MAX_ENUM_VALUES = 64;
+const OUTPUT_SCHEMA_MAX_ALTERNATIVES = 64;
+
+function isPlainRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// Original bounded native-helper schema contract. The host supplies its existing
+// error policy; native and API process ownership is outside this validator.
+export function validateConversationOutputSchema(outputSchema, {
+  maxOutputCharacters,
+  createError = (message, details) => Object.assign(new TypeError(message), { details })
+} = {}) {
+  if (!Number.isSafeInteger(maxOutputCharacters) || maxOutputCharacters < 1) {
+    throw new TypeError("Structured output requires a finite positive output limit.");
+  }
+  function assertOutputSchemaKeys(schema = {}, allowed = [], schemaPath = "$") {
+    const allowedKeys = new Set(["description", "title", "type", ...allowed]);
+    if (Object.keys(schema).some((key) => !allowedKeys.has(key))) {
+      throw createError(
+        `Helper output schema ${schemaPath} contains an unsupported keyword.`,
+        { field: "outputSchema" }
+      );
+    }
+  }
+
+  function strictOutputSchemaMaximumCharacters(schema = null, schemaPath = "$", depth = 0) {
+    if (!isPlainRecord(schema)) {
+      throw createError(
+        `Helper output schema ${schemaPath} must be an object.`,
+        { field: "outputSchema" }
+      );
+    }
+    if (depth > OUTPUT_SCHEMA_MAX_DEPTH) {
+      throw createError(
+        "Helper output schema is nested too deeply.",
+        { field: "outputSchema" }
+      );
+    }
+    if (Object.hasOwn(schema, "anyOf")) {
+      assertOutputSchemaKeys(schema, ["anyOf"], schemaPath);
+      if (depth === 0 || Object.hasOwn(schema, "type") || !Array.isArray(schema.anyOf) ||
+          schema.anyOf.length < 1 || schema.anyOf.length > OUTPUT_SCHEMA_MAX_ALTERNATIVES ||
+          schema.anyOf.some((alternative) => alternative?.type !== "object")) {
+        throw createError(
+          `Helper output schema ${schemaPath} requires bounded, closed object alternatives below its root.`,
+          { field: "outputSchema" }
+        );
+      }
+      return Math.max(...schema.anyOf.map((alternative, index) =>
+        strictOutputSchemaMaximumCharacters(alternative, `${schemaPath}.anyOf[${index}]`, depth + 1)));
+    }
+    if (typeof schema.type !== "string") {
+      throw createError(
+        `Helper output schema ${schemaPath} must declare one type.`,
+        { field: "outputSchema" }
+      );
+    }
+    if (schema.type === "object") {
+      assertOutputSchemaKeys(
+        schema,
+        ["additionalProperties", "properties", "required"],
+        schemaPath
+      );
+      if (schema.additionalProperties !== false || !isPlainRecord(schema.properties)) {
+        throw createError(
+          `Helper object schema ${schemaPath} must declare properties and reject additional properties.`,
+          { field: "outputSchema" }
+        );
+      }
+      const propertyNames = Object.keys(schema.properties);
+      const required = Array.isArray(schema.required) ? schema.required : [];
+      if (
+        propertyNames.length === 0 ||
+        propertyNames.length > OUTPUT_SCHEMA_MAX_PROPERTIES ||
+        propertyNames.some((name) => !name || name.length > 128) ||
+        required.length !== propertyNames.length ||
+        new Set(required).size !== required.length ||
+        propertyNames.some((name) => !required.includes(name))
+      ) {
+        throw createError(
+          `Helper object schema ${schemaPath} must require every declared property.`,
+          { field: "outputSchema" }
+        );
+      }
+      return propertyNames.reduce((total, name, index) => (
+        total +
+        (index === 0 ? 0 : 1) +
+        JSON.stringify(name).length +
+        1 +
+        strictOutputSchemaMaximumCharacters(schema.properties[name], `${schemaPath}.${name}`, depth + 1)
+      ), 2);
+    }
+    if (schema.type === "array") {
+      assertOutputSchemaKeys(schema, ["items", "maxItems", "minItems"], schemaPath);
+      if (!Number.isSafeInteger(schema.maxItems) || schema.maxItems < 0) {
+        throw createError(
+          `Helper array schema ${schemaPath} must have a finite maxItems value.`,
+          { field: "outputSchema" }
+        );
+      }
+      if (
+        schema.minItems !== undefined &&
+        (!Number.isSafeInteger(schema.minItems) || schema.minItems < 0 || schema.minItems > schema.maxItems)
+      ) {
+        throw createError(
+          `Helper array schema ${schemaPath} has an invalid minItems value.`,
+          { field: "outputSchema" }
+        );
+      }
+      const itemMaximum = strictOutputSchemaMaximumCharacters(schema.items, `${schemaPath}[]`, depth + 1);
+      const maximum = 2 + (schema.maxItems * itemMaximum) + Math.max(0, schema.maxItems - 1);
+      if (!Number.isSafeInteger(maximum)) {
+        throw createError(
+          "Helper output schema exceeds its finite bound.",
+          { field: "outputSchema" }
+        );
+      }
+      return maximum;
+    }
+    if (schema.type === "string") {
+      assertOutputSchemaKeys(schema, ["enum", "maxLength", "minLength"], schemaPath);
+      if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        if (
+          schema.enum.length > OUTPUT_SCHEMA_MAX_ENUM_VALUES ||
+          schema.enum.some((value) => typeof value !== "string")
+        ) {
+          throw createError(
+            `Helper string schema ${schemaPath} has an invalid enum.`,
+            { field: "outputSchema" }
+          );
+        }
+        return Math.max(...schema.enum.map((value) => JSON.stringify(value).length));
+      }
+      if (!Number.isSafeInteger(schema.maxLength) || schema.maxLength <= 0) {
+        throw createError(
+          `Helper string schema ${schemaPath} must have a finite positive maxLength.`,
+          { field: "outputSchema" }
+        );
+      }
+      if (
+        schema.minLength !== undefined &&
+        (!Number.isSafeInteger(schema.minLength) || schema.minLength < 0 || schema.minLength > schema.maxLength)
+      ) {
+        throw createError(
+          `Helper string schema ${schemaPath} has an invalid minLength value.`,
+          { field: "outputSchema" }
+        );
+      }
+      // JSON may encode each UTF-16 code unit as a six-character `\uXXXX` escape.
+      // Count that worst case so the schema can never admit raw JSON beyond the
+      // resolved response limit even when every string character needs escaping.
+      const maximum = (schema.maxLength * 6) + 2;
+      if (!Number.isSafeInteger(maximum)) {
+        throw createError(
+          "Helper output schema exceeds its finite bound.",
+          { field: "outputSchema" }
+        );
+      }
+      return maximum;
+    }
+    if (schema.type === "boolean" || schema.type === "null") {
+      assertOutputSchemaKeys(schema, [], schemaPath);
+      return 5;
+    }
+    throw createError(
+      `Helper output schema ${schemaPath} uses an unsupported type.`,
+      { field: "outputSchema" }
+    );
+  }
+
+  let schemaBytes = 0;
+  try {
+    schemaBytes = Buffer.byteLength(JSON.stringify(outputSchema), "utf8");
+  } catch {
+    throw createError(
+      "Helper output schema is not serializable.",
+      { field: "outputSchema" }
+    );
+  }
+  if (schemaBytes > OUTPUT_SCHEMA_MAX_BYTES) {
+    throw createError(
+      "Helper output schema exceeds its request limit.",
+      { field: "outputSchema" }
+    );
+  }
+  const maximumCharacters = strictOutputSchemaMaximumCharacters(outputSchema);
+  if (maximumCharacters > maxOutputCharacters) {
+    throw createError(
+      "Helper output schema can exceed the resolved output limit.",
+      {
+        maximumCharacters,
+        maxOutputCharacters
+      }
+    );
+  }
+  return outputSchema;
+}
+
+// Catalogue schemas carry validator metadata that is not part of the native
+// structured response contract. Keep validation keywords and field names intact.
+export function conversationOutputSchema(schema) {
+  const result = Object.fromEntries(Object.entries(schema).filter(([key]) =>
+    key !== "$schema" && key !== "x-json-rest-schema"));
+  if (schema.properties) result.properties = Object.fromEntries(Object.entries(schema.properties)
+    .map(([key, value]) => [key, conversationOutputSchema(value)]));
+  if (schema.items) result.items = conversationOutputSchema(schema.items);
+  if (schema.anyOf) result.anyOf = schema.anyOf.map(conversationOutputSchema);
+  return result;
+}
+
+// Validate the same finite schema subset used for native Helper responses before
+// allowing a structured reply to select an application operation.
+export function parseConversationOutput(text, schema) {
+  function matches(value, definition) {
+    if (definition.anyOf) return definition.anyOf.some((alternative) => matches(value, alternative));
+    if (definition.type === "object") {
+      return isPlainRecord(value) && Object.keys(value).every((key) => Object.hasOwn(definition.properties, key)) &&
+        definition.required.every((key) => Object.hasOwn(value, key)) &&
+        Object.entries(definition.properties).every(([key, field]) => matches(value[key], field));
+    }
+    if (definition.type === "array") return Array.isArray(value) && value.length <= definition.maxItems &&
+      value.length >= (definition.minItems || 0) && value.every((item) => matches(item, definition.items));
+    if (definition.type === "string") return typeof value === "string" &&
+      (definition.enum ? definition.enum.includes(value) : value.length <= definition.maxLength) &&
+      value.length >= (definition.minLength || 0);
+    if (definition.type === "boolean") return typeof value === "boolean";
+    return definition.type === "null" && value === null;
+  }
+  const value = JSON.parse(String(text || ""));
+  if (!matches(value, schema)) throw new TypeError("The assistant returned an invalid structured response.");
+  return value;
+}

package/src/server/conversation/systemPrompt.js

@@ -0,0 +1,54 @@
+/**
+ * One instruction binding per native conversation. The adapter owns delivery
+ * (native hooks, process configuration or a request's system field), not the
+ * application or its message history.
+ */
+export function createConversationSystemPrompt() {
+  let installed;
+  let generation = 0;
+  let pending = Promise.resolve();
+
+  function invalidate() {
+    generation += 1;
+    installed = undefined;
+  }
+
+  function isCurrent({ systemPrompt, contextIdentity } = {}) {
+    return Boolean(installed && installed.systemPrompt === systemPrompt && installed.contextIdentity === contextIdentity);
+  }
+
+  function ensure({ systemPrompt, contextIdentity, install, retained = true } = {}) {
+    if (typeof systemPrompt !== "string" || !systemPrompt.trim()) {
+      return Promise.reject(new TypeError("Conversation systemPrompt must be a non-empty string."));
+    }
+    if (typeof contextIdentity !== "string" || !contextIdentity) {
+      return Promise.reject(new TypeError("Conversation contextIdentity is required."));
+    }
+    if (typeof install !== "function") {
+      return Promise.reject(new TypeError("Conversation system prompt requires an installation adapter."));
+    }
+    const operation = pending.catch(() => {}).then(async () => {
+      const promptChanged = !installed || installed.systemPrompt !== systemPrompt;
+      const contextChanged = !installed || installed.contextIdentity !== contextIdentity;
+      if (retained && isCurrent({ systemPrompt, contextIdentity })) return installed.value;
+      const startedGeneration = generation;
+      let value;
+      try {
+        value = await install({ systemPrompt, promptChanged, contextChanged });
+      } catch (error) {
+        invalidate();
+        throw error;
+      }
+      // Do not let a caller start inference against an obsolete installation.
+      if (generation !== startedGeneration) {
+        throw new Error("Conversation context changed while installing its system prompt. Retry before sending.");
+      }
+      installed = { systemPrompt, contextIdentity, value };
+      return value;
+    });
+    pending = operation;
+    return operation;
+  }
+
+  return Object.freeze({ ensure, isCurrent, invalidate, whenIdle: () => pending });
+}