dsh-ptc-plus 0.5.1 → 0.5.3

package/internal/recovery-tips.js

@@ -1,11 +1,22 @@
 import { PTC_STATE_NAMES, recoveryTipIdentity } from './runtime-messages.js'
+import {
+  PROMPT_SLOT_IDS, TIP_BODY, TIP_BODY_PLATFORM_DETAILED, TIP_BODY_REPEATED_BINDING,
+  TIP_BODY_REPEATED_BINDING_CAPABILITY, TIP_DETAIL_BINDING, TIP_DETAIL_CAPABILITY,
+  TIP_PREFIX_PLATFORM_COMMAND, TIP_PREFIX_REPEATED_BINDING,
+} from './prompt-text.js'
 
 const PLATFORM_CAUSE_CODES = new Set(['EACCES', 'EINVAL', 'ENOTDIR', 'ENOENT', 'UNKNOWN'])
 const TIP_CONTEXT_PREFIX = 'tools:ptc-plus-tip/'
 const PLATFORM_FACTS = '`return { platform: process.platform, arch: process.arch, node: process.version, cwd: process.cwd(), execPath: process.execPath }`'
+/**
+ * The delivered prefixes, one slot per trigger kind.
+ *
+ * Tip identity comes from the notice name, so a prefix carries no recognizer
+ * contract; both are read-only registry literals so their bytes are accounted.
+ */
 const TIP_PREFIXES = Object.freeze({
-  'repeated-binding-failure': 'The same binding failure has recurred.',
-  'platform-command-failure': 'An executable, shell, or path failed in the current execution world.',
+  'repeated-binding-failure': TIP_PREFIX_REPEATED_BINDING,
+  'platform-command-failure': TIP_PREFIX_PLATFORM_COMMAND,
 })
 
 // TODO(dsh-tips-api): replace this local provider with an adapter after dsh-tips publishes a stable facts and decision interface.
@@ -91,18 +102,46 @@ function tipCandidate(view) {
   return undefined
 }
 
-function renderTip(id, detailed, candidate = {}) {
+const TIP_BODY_SLOTS = Object.freeze({
+  platform: PROMPT_SLOT_IDS.tipBodyPlatform,
+  platformDetailed: PROMPT_SLOT_IDS.tipBodyPlatformDetailed,
+  repeatedBinding: PROMPT_SLOT_IDS.tipBodyRepeatedBinding,
+  repeatedBindingCapability: PROMPT_SLOT_IDS.tipBodyRepeatedBindingCapability,
+})
+
+const TIP_DETAIL_SLOTS = Object.freeze({
+  binding: PROMPT_SLOT_IDS.tipDetailBinding,
+  capability: PROMPT_SLOT_IDS.tipDetailCapability,
+})
+
+const TIP_PREFIX_SLOTS = Object.freeze({
+  'repeated-binding-failure': PROMPT_SLOT_IDS.tipPrefixRepeatedBinding,
+  'platform-command-failure': PROMPT_SLOT_IDS.tipPrefixPlatformCommand,
+})
+
+/**
+ * Every delivered tip body reads its own registry slot; escalation only decides
+ * whether the `{detail}` hole carries its sentence, and which of the two registered
+ * detail slots fills it. Prefix and detail slots are read-only, so a customised body
+ * cannot move tip identity or escalation.
+ */
+function renderTip(id, detailed, candidate = {}, prompt) {
+  const body = (slotId, fallback) => prompt?.text(slotId) ?? fallback
+  const prefix = body(TIP_PREFIX_SLOTS[id], TIP_PREFIXES[id])
   if (id === 'platform-command-failure') {
-    return detailed
-      ? `${TIP_PREFIXES[id]} Re-check the active execution world and the actual executable before retrying. First inspect bounded runtime facts with ${PLATFORM_FACTS}; use the result to choose the executable and path. Use direct argv for a normal executable; use a shell only when its syntax or resolution is required. Windows, WSL, POSIX, and package shims have different paths and launch rules. Do not dump process.env.`
-      : `${TIP_PREFIXES[id]} Inspect bounded runtime facts with ${PLATFORM_FACTS}, then choose the executable and path in the current execution world. Use direct argv or a shell only when required; do not assume Windows, WSL, POSIX, or one shell. Do not dump process.env.`
+    const template = detailed
+      ? body(TIP_BODY_SLOTS.platformDetailed, TIP_BODY_PLATFORM_DETAILED)
+      : body(TIP_BODY_SLOTS.platform, TIP_BODY)
+    return `${prefix} ${template.replace('{platformFacts}', PLATFORM_FACTS)}`
   }
   if (!candidate.capability) {
-    return `${TIP_PREFIXES[id]} Inspect the visible cell source and results for the local name, scope, initialization, or declaration conflict. Correct that expression before continuing; capability discovery does not list session-local variables.${detailed ? ' Earlier statements may have run; use current expression evidence without assuming a failed declaration initialized its binding.' : ''}`
+    const template = body(TIP_BODY_SLOTS.repeatedBinding, TIP_BODY_REPEATED_BINDING)
+    const detail = detailed ? body(TIP_DETAIL_SLOTS.binding, TIP_DETAIL_BINDING) : ''
+    return `${prefix} ${template.replace('{detail}', detail)}`
   }
-  return detailed
-    ? `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`. Do not invent hidden bindings or repeat the same failing expression.`
-    : `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`.`
+  const template = body(TIP_BODY_SLOTS.repeatedBindingCapability, TIP_BODY_REPEATED_BINDING_CAPABILITY)
+  const detail = detailed ? body(TIP_DETAIL_SLOTS.capability, TIP_DETAIL_CAPABILITY) : ''
+  return `${prefix} ${template.replace('{detail}', detail)}`
 }
 
 export function latestRecoveryTip(view, config) {
@@ -117,6 +156,6 @@ export function latestRecoveryTip(view, config) {
   if (!Number.isSafeInteger(ordinal)) return undefined
   return {
     name: `${TIP_CONTEXT_PREFIX}${candidate.id}/${ordinal}`,
-    text: renderTip(candidate.id, (lastTip?.unresolved ?? 0) >= config.escalationFailures, candidate),
+    text: renderTip(candidate.id, (lastTip?.unresolved ?? 0) >= config.escalationFailures, candidate, config.prompt),
   }
 }

package/internal/rejected-cell-editor.js

@@ -1,3 +1,4 @@
+import { EDIT_RUN_CODE_DESCRIPTION } from './prompt-text.js'
 import { runInNewContext } from 'node:vm'
 
 const DEFAULT_REGEX_TIMEOUT_MS = 100
@@ -252,10 +253,10 @@ function assemble(source, replacements) {
   return changed ? { code: chunks.join('') } : { error: 'edits must change at least one matched fragment' }
 }
 
-export function editRunCodeSchema() {
+export function editRunCodeSchema(description = EDIT_RUN_CODE_DESCRIPTION) {
   return {
     name: 'edit_run_code',
-    description: 'Call this from within a run_code cell. It accepts an edit of the most recent eligible cell captured at nested dispatch and returns { accepted, scheduled, target_call_seq } when scheduled. The corrected cell runs after the current run_code cell releases its worker; its result is reported with that cell, and a successful edit becomes the next target. This reruns the entire target cell, including prior effects; use it after pre-execution rejection or when repeating those effects is safe under the called API\'s retry rules. Otherwise continue in a new run_code cell using retained values. A diagnostic may supply a localized correction; use it when it matches your intent and preserve its expected_target_call_seq. Send exactly one edits or regex_edits array: edits replaces unique literal fragments; regex_edits replaces a counted set of pattern matches. All ranges must be non-overlapping in the original cell. Regex replacements use JavaScript $1/$<name> captures, not \\1.',
+    description,
     parameters: {
       type: 'object',
       additionalProperties: false,

package/internal/repl-memory-projection.js

@@ -23,6 +23,7 @@ const COUNTED_ENTRY_FIELDS = new Set([...ENTRY_FIELDS, 'reuseCount'])
 const DEFINITION_FIELDS = new Set(['source', 'line', 'column'])
 const MEMORY_META_FIELDS = new Set(['version', 'generation', 'memory'])
 const PROJECTION_STATE_FIELDS = new Set(['generation', 'memory', 'pendingReplCalls'])
+const VIEW_FIELDS = new Set(['runtime', 'memory'])
 const PENDING_CALL_FIELDS = new Set(['callId', 'seq'])
 const REPL_MEMORY_META_VERSION = 5
 
@@ -205,6 +206,24 @@ export function normalizeReplMemorySnapshot(value) {
   })
 }
 
+/**
+ * One runtime's own observation of its environment, together with the owner that
+ * produced it.
+ *
+ * A panel shows an observation, not "the current state". Two questions then have
+ * to stay separate, and only the owner answers them: a projection refresh inside
+ * one runtime keeps the inventory valid (freshness), while a snapshot from a
+ * previous runtime can no longer be confirmed (provenance). Carrying the owner
+ * in the view lets a reader decide by data instead of by object identity.
+ */
+export function normalizeReplMemoryView(value) {
+  if (!exactFields(value, VIEW_FIELDS)) throw new Error('invalid dsh-ptc-plus REPL memory view')
+  return Object.freeze({
+    runtime: normalizeGeneration(value.runtime),
+    memory: normalizeReplMemorySnapshot(value.memory),
+  })
+}
+
 /** Reuse fields are version 5 additions; an older metadata version cannot own them. */
 function countedMemory(memory) {
   return memory?.reuseTotal !== undefined
@@ -349,8 +368,8 @@ export function createReplMemoryProjection(generation) {
       return state
     },
     wire: Object.freeze({
-      viewSchema: Object.freeze({ parse: normalizeReplMemorySnapshot }),
-      view: state => state.memory,
+      viewSchema: Object.freeze({ parse: normalizeReplMemoryView }),
+      view: state => Object.freeze({ runtime: state.generation, memory: state.memory }),
     }),
   })
 }

package/internal/runtime-bridge-owner.js

@@ -24,6 +24,8 @@ import {
   toolCapabilityMetadata,
 } from './program-bindings.js'
 import { deepFreeze } from './record-utils.js'
+import { adaptRunCodeSchema } from './direct-surface-owner.js'
+import { hostTransportDefinition, isBatchSubmission } from './host-tool-sdk.js'
 import { REPL_MEMORY_META_KEY, withReplMemorySnapshot } from './repl-memory-projection.js'
 import { withUserBindingDraftCapability } from './user-binding-draft-projection.js'
 import { POST_EDIT_KEY } from './session-journal-schema.js'
@@ -160,6 +162,7 @@ export function createRuntimeBridgeOwner({
   userBindingDraftForAgent,
   bindingSubmissionForAgent,
   capabilityEnvironment,
+  readPromptText = () => undefined,
 }) {
   const scope = new AsyncLocalStorage()
   const childScope = new AsyncLocalStorage()
@@ -185,6 +188,8 @@ export function createRuntimeBridgeOwner({
   })
   let currentConfig = sessions.config
   const patchedDefinitions = new Map()
+  /** The host descriptors this attachment replaced on each definition's slots. */
+  const slotPatches = new Map()
   const pending = new WeakMap()
   const nativeRunCodeHandoffs = new Set()
   let active = true
@@ -393,14 +398,94 @@ export function createRuntimeBridgeOwner({
     return { request: { ...request, bindings: projected }, release }
   }
 
+/**
+ * Write one editable run_code slot onto the host's definition.
+ *
+ * A host may publish the slot as writable data or as a getter-only accessor over
+ * its own text, and strict-mode assignment throws on the latter. An owned property
+ * definition reaches both shapes, so the plugin never fails silently to deliver the
+ * text it was asked to deliver.
+ * @param {object} definition - the host's live run_code definition.
+ * @param {string} key - the definition field being replaced.
+ * @param {unknown} value - the text the plugin owns.
+ * @returns {boolean} whether the field now holds that value.
+ */
+function writeSlot(definition, key, value) {
+  const own = Object.getOwnPropertyDescriptor(definition, key)
+  try {
+    Object.defineProperty(definition, key, {
+      configurable: own?.configurable ?? true,
+      enumerable: own?.enumerable ?? true,
+      writable: true,
+      value,
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Put one slot back to the descriptor the host published before this plugin. */
+function restoreSlot(definition, key, descriptor) {
+  try {
+    if (descriptor === undefined) delete definition[key]
+    else Object.defineProperty(definition, key, descriptor)
+  } catch {
+    // A host that made the slot non-configurable after the plugin replaced it keeps
+    // the last written text; the restore cannot be forced, and the caller that
+    // rewrote it owns the consequence.
+  }
+}
+
+/**
+ * The editable run_code slots have to reach whichever definition the host lets this
+ * plugin own. Two writes, one decision: if the host's parameter texts cannot be
+ * replaced, the definition keeps all of its own text rather than half of ours. The
+ * descriptors the write replaced are recorded once, so re-applying the current
+ * prompt document on every request can never mistake the plugin's own text for the
+ * host's, and disposal can restore what the host still publishes.
+ */
+function applyEditableSlots(definition, promptText, slotPatches) {
+  if (promptText === undefined) return
+  let adapted
+  try {
+    adapted = adaptRunCodeSchema(definition, promptText)
+  } catch {
+    return
+  }
+  const recorded = slotPatches.get(definition)
+  if (recorded !== undefined) {
+    // Re-applied on every request: the descriptors recorded by the first write are
+    // the ones disposal restores, so a later application can never mistake the
+    // plugin's own text for the host's. A slot the host has since made unreplaceable
+    // keeps the text this attachment already delivered.
+    writeSlot(definition, 'parameters', adapted.parameters)
+    writeSlot(definition, 'description', adapted.description)
+    return
+  }
+  const ownParameters = Object.getOwnPropertyDescriptor(definition, 'parameters')
+  const ownDescription = Object.getOwnPropertyDescriptor(definition, 'description')
+  if (!writeSlot(definition, 'parameters', adapted.parameters)) return
+  if (!writeSlot(definition, 'description', adapted.description)) {
+    restoreSlot(definition, 'parameters', ownParameters)
+    return
+  }
+  slotPatches.set(definition, new Map([['parameters', ownParameters], ['description', ownDescription]]))
+}
+
   const patchRunCodeDefinition = (agent) => {
-    const definition = ctx.tools.get(RUN_CODE, agent)
+    const definition = hostTransportDefinition(ctx.tools, agent, RUN_CODE)
     if (definition === undefined) {
       throw new Error('ptc-plus: run_code definition is unavailable for the owning session')
     }
     if (definition.output === undefined) {
       throw new Error('ptc-plus: run_code definition has no output projection')
     }
+    // A host that declares its own model-facing tools never hands this plugin a
+    // tools array to adapt, so the editable prompt slots reach the model only on
+    // the definition the executor projects. Re-applied on every request, because
+    // the prompt document can change while the definition stays the same object.
+    applyEditableSlots(definition, readPromptText(), slotPatches)
     if (patchedDefinitions.has(definition)) return
     const output = definition.output
     const ownPresentationMeta = Object.getOwnPropertyDescriptor(output, 'presentationMeta')
@@ -463,10 +548,10 @@ export function createRuntimeBridgeOwner({
       // nested success. Capture its canonical value before policy; the private
       // relation is admitted only if policy retains that same frozen value.
       if (current?.deferredSettlement?.current === current && derived !== undefined
-        && current.exec === exec && exec.token !== undefined && exec.parent !== undefined
+        && current.exec === exec && exec.token !== undefined
         && current.id === sessionId(exec.agent) && derived.agent === exec.agent
-        && derived.callId === exec.callId && derived.rootCallId === exec.rootCallId
-        && derived.parent === exec.parent && deepEqualJson(derived.arguments, exec.arguments)
+        && isDerivedExecution(derived, exec)
+        && deepEqualJson(derived.arguments, exec.arguments)
         && current.presentationMetaCalls === undefined && result.isError === false
         && result.value !== null && typeof result.value === 'object'
         && Object.isFrozen(result.value) && result.meta?.[JOURNAL_KEY] === undefined
@@ -610,13 +695,30 @@ export function createRuntimeBridgeOwner({
 
   const releaseSeam = seam.installExecute(patchedRun)
 
+  /**
+   * Whether this execution is the derived execution the edit transport submitted.
+   *
+   * A registry host runs the very object the plugin built, so the call id, the root
+   * call and the parent token it carries all prove the relation. The batch contract
+   * assigns its own identity instead: the parent token is the host's own and the
+   * root call is whichever call that host treats as direct. What survives there is
+   * the call id this plugin chose, which the host matched the batch result back to,
+   * together with the dispatch record; the derived source is compared beside it.
+   */
+  const isDerivedExecution = (derived, exec) => {
+    if (derived === null || typeof derived !== 'object' || exec === null || typeof exec !== 'object') return false
+    if (derived.callId !== exec.callId) return false
+    if (isBatchSubmission(derived)) return true
+    return exec.parent !== undefined
+      && derived.rootCallId === exec.rootCallId && derived.parent === exec.parent
+  }
+
   const ownedDerivedScope = (exec, executionArguments = exec.arguments) => {
     const inherited = scope.getStore()
     const derived = inherited?.derivedExecution
     if (inherited?.deferredSettlement === undefined
       || inherited.id !== sessionId(exec.agent) || derived?.agent !== exec.agent
-      || derived.callId !== exec.callId || derived.rootCallId !== exec.rootCallId
-      || derived.parent !== exec.parent || exec.name !== RUN_CODE
+      || !isDerivedExecution(derived, exec) || exec.name !== RUN_CODE
       || !deepEqualJson(derived.arguments, executionArguments)) return undefined
     return inherited
   }
@@ -800,8 +902,7 @@ export function createRuntimeBridgeOwner({
       const derived = current.derivedExecution
       const privateMetadata = projection !== undefined && projection.exec === exec
         && deferred.current === current && current.exec === exec && current.id === id
-        && derived?.agent === exec.agent && derived.callId === exec.callId
-        && derived.rootCallId === exec.rootCallId && derived.parent === exec.parent
+        && derived?.agent === exec.agent && isDerivedExecution(derived, exec)
         && deepEqualJson(derived.arguments, exec.arguments)
         && projection.token === exec.token && projection.value === result?.value
         && result.isError === false && deepEqualJson(projection.meta, result.meta)
@@ -831,7 +932,7 @@ export function createRuntimeBridgeOwner({
         && deepEqualJson(meta?.[POST_EDIT_KEY], current.postEdit.provenance))
     },
     disposeAgent(agent) {
-      return sessions.disposeSession(sessionId(agent) ?? String(agent.id))
+      return sessions.disposeAgent(sessionId(agent) ?? String(agent.id))
     },
     disposeSession(session) {
       return sessions.disposeSession(String(session.id))
@@ -868,6 +969,10 @@ export function createRuntimeBridgeOwner({
         }
       }
       patchedDefinitions.clear()
+      for (const [definition, recorded] of slotPatches) {
+        for (const [key, descriptor] of recorded) restoreSlot(definition, key, descriptor)
+      }
+      slotPatches.clear()
       try {
         await sessions.dispose()
       } catch (error) {

package/internal/runtime-config.js

@@ -1,4 +1,5 @@
 import { capabilityPolicyForConfig } from './capability-policy.js'
+import { validatePromptTextDocument } from './prompt-text.js'
 import {
   CONFIG_DEFAULTS,
   CONFIG_FIELDS,
@@ -117,6 +118,7 @@ export function resolveConfig(config = {}) {
   }
   for (const field of CONFIG_FIELDS) assertField(field, resolved[field.key])
   validateCapabilityProfiles(JSON.parse(resolved.capabilityProfiles))
+  validatePromptTextDocument(resolved.promptText)
   for (const [key, array] of [['capabilityBaseline', true], ['capabilityOverrides', false]]) {
     let value
     try { value = JSON.parse(resolved[key]) } catch { throw new TypeError(`ptc-plus: ${key} must contain valid JSON`) }

package/internal/runtime-contexts.js

@@ -1,4 +1,5 @@
 import { latestRecoveryTip, runtimeHistoryForView } from './recovery-tips.js'
+import { HOT_CELL_DROPPED, HOT_CELL_DROPPED_EN } from './projection-retention.js'
 import { foldSurface, deriveEventMessage, snapshotSessionEvent } from '@deepseek-ai/dsh-session'
 import { currentSessionMessageProjections } from '@deepseek-ai/dsh-session-format-catalog/message-projections'
 import { readSessionLog } from './session-events.js'
@@ -75,6 +76,12 @@ export async function handBackRuntimeSessions(ctx, owners) {
 function continuationFeedback(view) {
   const run = view.latestRun
   const rewrites = run?.rewrites
+  if (run === undefined && view.hotCellDropped === true) {
+    // The newest cell lost its payload to the retention budget. Silence here reads as
+    // "nothing to advise", which is indistinguishable from a healthy session; tell the
+    // model that the evidence was removed rather than absent.
+    return `${HOT_CELL_DROPPED} / ${HOT_CELL_DROPPED_EN} Inspect the tool result of the dropped cell before continuing; do not replay it automatically.`
+  }
   if (rewrites === undefined || rewrites.length === 0 || run.journal !== undefined) return undefined
   const descriptions = rewrites.map(rewrite => rewrite.description).join('; ')
   const details = descriptions.length <= 2048 ? descriptions
@@ -100,7 +107,7 @@ export function sessionRuntimeContexts(agent, tipConfig, options = {}) {
 }
 
 /** Project messages without treating an uncommitted proposal as delivery. */
-export function projectRuntimeMessages(view, contexts, pending = []) {
+export function projectRuntimeMessages(view, contexts, pending = [], options) {
   if (view.visibleRuntimeMessages === undefined) return []
   const sections = contexts.filter(context => PTC_STATE_NAMES.includes(context.name) && context.name !== PTC_BINDING_CATALOG)
   const catalog = contexts.find(context => context.name === PTC_BINDING_CATALOG)
@@ -114,7 +121,7 @@ export function projectRuntimeMessages(view, contexts, pending = []) {
     ?? (pendingAggregate ?? legacy?.sections)?.filter(section => PTC_STATE_NAMES.includes(section.name))
   const hadState = history.hadState
   const messages = []
-  const proposed = pending.map(readRuntimeMessage).filter(record => record !== undefined)
+  const proposed = pending.map(record => readRuntimeMessage(record)).filter(record => record !== undefined)
   const pendingState = proposed.filter(record => record.form === 'snapshot').at(-1)
   const previous = pendingState?.sections ?? retained
   if ((sections.length > 0 || (previous !== undefined && previous.length > 0) || (previous === undefined && hadState))
@@ -126,7 +133,7 @@ export function projectRuntimeMessages(view, contexts, pending = []) {
   const hadCatalog = history.hadCatalog
   if ((catalog !== undefined || previousCatalog !== undefined || hadCatalog)
     && JSON.stringify(previousCatalog?.sections) !== JSON.stringify(catalog === undefined ? [] : [catalog])) {
-    messages.push(runtimeBindingCatalogMessage(catalog))
+    messages.push(runtimeBindingCatalogMessage(catalog, options))
   }
   for (const tip of contexts.filter(context => context.name.startsWith('tools:ptc-plus-tip/'))) {
     if (proposed.some(record => record.form === 'notice' && record.name === tip.name)) continue
@@ -137,7 +144,7 @@ export function projectRuntimeMessages(view, contexts, pending = []) {
 }
 
 /** Passive message delivery follows the actual public assembly and accepted step. */
-export function createRuntimeMessageOwner(contextsForRequest, sessionLogView = projectSessionLog, activeForRequest, sessionQuery) {
+export function createRuntimeMessageOwner(contextsForRequest, sessionLogView = projectSessionLog, activeForRequest, sessionQuery, promptForRequest) {
   const requests = new WeakMap()
   const disposedAgents = new WeakSet()
   let disposed = false
@@ -162,7 +169,9 @@ export function createRuntimeMessageOwner(contextsForRequest, sessionLogView = p
       if (disposed || decision.kind !== 'enter' || payload.signal?.aborted === true
         || request?.allowed !== true || request.context.signal !== payload.signal) return decision
       const view = sessionLogView(payload.agent)
-      const messages = projectRuntimeMessages(view, contextsForRequest(request.context), decision.messages)
+      const resolved = promptForRequest === undefined ? undefined : promptForRequest(request.context)
+      const messages = projectRuntimeMessages(view, contextsForRequest(request.context), decision.messages,
+        resolved === undefined ? undefined : { prompt: resolved })
       if (activeForRequest !== undefined) {
         const log = await readSessionLog(payload.agent.session, sessionQuery, payload.signal)
         const availability = projectRuntimeAvailability([

package/internal/runtime-messages.js

@@ -1,6 +1,11 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import {
+  CATALOG_PREFIX, EMPTY_CATALOG, LEGACY_STATE_PREFIX, PREVIOUS_EMPTY_CATALOG, PREVIOUS_STATE_PREFIX,
+  PROMPT_SLOT_IDS, PROMPT_TEXT_DEFAULT, STATE_PREFIX, resolvePromptText,
+} from './prompt-text.js'
 
 import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+import { BINDING_ADOPTION_FORM, readBindingAdoption } from './binding-adoption.js'
 
 export const PTC_DELIVERY_CONTEXT = 'tools:ptc-plus-message-delivery'
 export const PTC_BINDING_CATALOG = 'tools:ptc-plus-user-binding-defaults'
@@ -13,16 +18,12 @@ export const PTC_STATE_NAMES = Object.freeze([
 ])
 const MAX_STATE_CODE_UNITS = 65536
 const MAX_NOTICE_CODE_UNITS = 8192
-const LEGACY_STATE_PREFIX = 'PTC Plus current state. This replaces only earlier PTC state snapshots and PTC sections in historical aggregate snapshots; it does not replace tasks, Skill instructions, tool results, or other producers.'
-const PREVIOUS_STATE_PREFIX = 'PTC Plus runtime recovery state. This replaces only earlier PTC state snapshots and PTC sections in historical aggregate snapshots; it does not replace the global binding API catalog, tasks, Skill instructions, tool results, or other producers.'
+
 const PREVIOUS_CATALOG_PREFIXES = [
   'Global binding API catalog (PTC Plus). Only a later global binding API catalog replaces this catalog. Host runtime-context snapshots and PTC recovery snapshots do not withdraw it. This describes configured APIs, not successful initialization or current runtime values.',
   'Global binding API catalog (PTC Plus). Replaces earlier binding catalogs only; remains applicable until the next binding catalog.',
 ]
-const STATE_PREFIX = 'PTC Plus recovery status. Replaces earlier PTC recovery status, including PTC state in runtime-context snapshots. Global binding APIs are unchanged.'
-const CATALOG_PREFIX = 'Global binding API reference for run_code (replaces the previous global binding reference):'
-const EMPTY_CATALOG = 'No entries documented.'
-const PREVIOUS_EMPTY_CATALOG = 'No global binding API documentation is currently configured. Earlier binding catalogs no longer apply.'
+
 const AVAILABILITY_TEXT = Object.freeze({
   active: 'PTC Plus is the current continuous-computation provider. Follow its current tool schemas and capability plan; earlier withdrawals do not restore old computation state.',
   disabled: 'PTC Plus is disabled. Earlier PTC Plus continuous-computation instructions, capability plans, discovery instructions, calling-contract disclosures and global binding references no longer describe the current runtime. Use the current Host tools and contracts. Historical computations and effects remain historical; no old PTC Plus heap has been restored. Tasks, Skill instructions, other producers and tool results are unchanged.',
@@ -56,10 +57,13 @@ export function projectRuntimeAvailability(messages, active, computationDeclared
   const last = messages.map(readRuntimeAvailability).filter(Boolean).at(-1)
   if (active) return last && last !== 'active' ? runtimeAvailabilityMessage('active') : undefined
   if (last === 'disabled' || last === 'unloaded') return undefined
-  const declared = computationDeclared || last === 'active' || messages.some(message => isPtcMessageSource(message?.source)
-    && (['capability-navigation', 'capability-descriptions', 'capability-contracts'].includes(message.source.form)
-      || message.source.form === 'capability-plan' && message.source.snapshot?.plan?.enabled === true
-      || readRuntimeMessage(message)?.form === 'catalog' && readRuntimeMessage(message).sections.length > 0))
+  const declared = computationDeclared || last === 'active' || messages.some(message => {
+    const recognized = isPtcMessageSource(message?.source) ? readRuntimeMessage(message) : undefined
+    return isPtcMessageSource(message?.source)
+      && (['capability-navigation', 'capability-descriptions', 'capability-contracts'].includes(message.source.form)
+        || message.source.form === 'capability-plan' && message.source.snapshot?.plan?.enabled === true
+        || recognized?.form === 'catalog' && recognized.sections.length > 0)
+  })
   return declared ? runtimeAvailabilityMessage('disabled') : undefined
 }
 
@@ -92,6 +96,18 @@ function stateText(sections, prefix = STATE_PREFIX) {
     : sections.map(section => section.text).join('\n\n')}`
 }
 
+/**
+ * Historical emptiness wording a recorded catalog may carry.
+ *
+ * These are code-owned constants, not the resolved document: a session record
+ * written by an older build must stay readable after today's sentence changes,
+ * and recognizing it must never depend on the user's current override.
+ */
+const HISTORICAL_EMPTY_CATALOGS = Object.freeze([EMPTY_CATALOG, PREVIOUS_EMPTY_CATALOG])
+
+/** The resolved document a producer used. Recognition never depends on its text. */
+const promptOf = prompt => prompt ?? resolvePromptText(PROMPT_TEXT_DEFAULT)
+
 /** Recognize only bounded, formed PTC records, never authoring tasks or Skills. */
 export function readRuntimeMessage(message) {
   const source = message?.source
@@ -101,6 +117,10 @@ export function readRuntimeMessage(message) {
   const text = message.content[0].text
   const availability = readRuntimeAvailability(message)
   if (availability !== undefined) return { form: 'runtime-availability', state: availability }
+  // A session's binding adoption is recorded as one of its own messages, so the
+  // log is its only owner and replay reconstructs it without process memory.
+  const adoption = readBindingAdoption(message)
+  if (adoption !== undefined) return { form: BINDING_ADOPTION_FORM, declined: [...adoption.declined] }
   if (source.form === 'snapshot') {
     const sections = stateSections(source.sections)
     if (sections !== undefined && [STATE_PREFIX, PREVIOUS_STATE_PREFIX, LEGACY_STATE_PREFIX]
@@ -112,7 +132,12 @@ export function readRuntimeMessage(message) {
     if (prefix === undefined) return undefined
     const body = text.slice(prefix.length + 2)
     if (body.length > 0 && body.length <= MAX_STATE_CODE_UNITS) {
-      const empty = body === (prefix === CATALOG_PREFIX ? EMPTY_CATALOG : PREVIOUS_EMPTY_CATALOG)
+      // Emptiness is a property of the record (`source.empty`), so live delivery
+      // and log replay agree even when the empty sentence is customized. Records
+      // written before that flag existed are matched against the code-owned
+      // historical wording, never against the current resolved text.
+      const empty = source.empty === true
+        || (source.empty === undefined && HISTORICAL_EMPTY_CATALOGS.includes(body))
       return { form: 'catalog', sections: stateSections(empty ? [] : [{ name: PTC_BINDING_CATALOG, text: body }]) }
     }
   } else if (source.form === 'notice' && recoveryTipIdentity(source.summary) !== undefined
@@ -123,15 +148,23 @@ export function readRuntimeMessage(message) {
 }
 
 /** One literal configuration document, independent of runtime recovery state. */
-export function runtimeBindingCatalogMessage(context) {
+export function runtimeBindingCatalogMessage(context, options) {
+  const resolved = promptOf(options?.prompt)
+  const catalogPrefix = resolved.text(PROMPT_SLOT_IDS.catalogPrefix)
+  const emptyCatalog = resolved.text(PROMPT_SLOT_IDS.catalogEmpty)
+  // Emptiness travels in `source.empty`, so a catalog body may legitimately equal
+  // the code-owned empty wording; comparing the text would abort the whole step for
+  // a deliverable catalog. Only the shape is rejected here.
   if (context !== undefined && (context?.name !== PTC_BINDING_CATALOG
     || typeof context.text !== 'string' || context.text.length === 0
-    || context.text.length > MAX_STATE_CODE_UNITS || context.text === EMPTY_CATALOG || context.text === PREVIOUS_EMPTY_CATALOG)) {
+    || context.text.length > MAX_STATE_CODE_UNITS)) {
     throw new Error('invalid PTC binding catalog')
   }
   return createUserMessage({
-    source: { kind: PTC_MESSAGE_SOURCE_KIND, form: 'catalog' },
-    content: [{ type: 'text', text: `${CATALOG_PREFIX}\n\n${context?.text ?? EMPTY_CATALOG}` }],
+    // `empty` records the fact itself, so replay recognizes an empty catalog from
+    // the record instead of comparing it against today's sentence.
+    source: { kind: PTC_MESSAGE_SOURCE_KIND, form: 'catalog', empty: context === undefined },
+    content: [{ type: 'text', text: `${catalogPrefix}\n\n${context?.text ?? emptyCatalog}` }],
   })
 }