dsh-ptc-plus 0.5.0 → 0.5.2

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/runtime-bridge-owner.js

@@ -587,9 +587,10 @@ export function createRuntimeBridgeOwner({
               valueText = '; value omitted from preview'
             }
           }
+          const targetDescription = pendingEdit.targetDescription ?? `run_code call ${pendingEdit.targetCallSeq}`
           const status = outcome.edited
-            ? `edit_run_code settled${outcome.error === undefined ? '' : ' with execution error'}`
-            : 'edit_run_code did not execute the accepted revision'
+            ? `edit_run_code settled${outcome.error === undefined ? '' : ' with execution error'} (target ${targetDescription})`
+            : `edit_run_code did not execute the accepted revision (target ${targetDescription})`
           const detail = [
             ...(hasRenderedContent || !Array.isArray(outcome.logs) ? [] : outcome.logs),
             ...(!hasRenderedContent && typeof outcome.error === 'string' ? [outcome.error] : []),
@@ -625,9 +626,9 @@ export function createRuntimeBridgeOwner({
     const inherited = scope.getStore()
     const ownsDerived = ownedDerivedScope(exec) !== undefined
     if ((exec.parent !== undefined && !ownsDerived) || id === undefined
-      || inherited?.submission?.sessionId === id) return operation()
+      || (inherited?.exec === exec && inherited.submission?.sessionId === id)) return operation()
     const submission = sessions.beginSubmission({ id }, exec.signal)
-    const composite = inherited?.deferredSettlement !== undefined && inherited.id === id
+    const composite = ownsDerived
       ? {
           persistedCallSeq: inherited.persistedCallSeq,
           sourceCallSeq: inherited.sourceCallSeq,
@@ -637,9 +638,11 @@ export function createRuntimeBridgeOwner({
         }
       : {}
     try {
-      // Derived edits retain their proved source under a fresh admission for
-      // the same session. Delegated agents own a fresh log and no child handoff.
-      return await scope.run({ ...composite, submission }, () => childScope.run(undefined, operation))
+      // Only reentry for this exact execution shares admission. Background
+      // continuations can inherit a settled execution's asynchronous context.
+      // Only proved derived edits retain composite source and settlement under
+      // a fresh admission; other roots own a fresh log and no child handoff.
+      return await scope.run({ ...composite, exec, submission }, () => childScope.run(undefined, operation))
     } finally {
       sessions.releaseSubmission(submission)
     }
@@ -828,7 +831,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))

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,4 +1,8 @@
 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'
 
@@ -13,16 +17,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 +56,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 +95,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
@@ -112,7 +127,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 +143,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}` }],
   })
 }
 

package/internal/sdk-projection.js

@@ -10,7 +10,7 @@ export function projectProgramSdk(nativeSdk, { languageSemantics = 'legacy-v1' }
   const fence = nativeSdk.indexOf(TYPESCRIPT_FENCE)
   if (fence < 0) return nativeSdk
   return nativeSdk.slice(0, fence).replace(
-    '`code` — the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped)',
-    '`code` — a PTC Plus TypeScript cell (runtime `enum` and namespaces are supported; type annotations are advisory)',
+    'the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped)',
+    'a PTC Plus TypeScript cell (runtime `enum` and namespaces are supported; type annotations are advisory)',
   ) + nativeSdk.slice(fence)
 }

package/internal/session-cell-executor.js

@@ -26,9 +26,11 @@ import {
 import { assertStateName, LIVE_USER_BINDINGS_REUSE_POLICY } from './session-journal.js'
 import { LIVE_USER_BINDINGS_SHADOW_POLICY, normalizeUserBindingNames } from './session-journal-schema.js'
 import { PreflightError, prepareProgram } from './compiler-service.js'
+import { UNANSWERED_SAMPLE_CODE } from './isolated-worker.js'
 import { executionPolicies } from './binding-update-policy.js'
+import { resultEnvelopeText, resolvePromptTextConfig, rewriteDescriptions } from './prompt-text.js'
 import { createReplMemorySnapshot } from './repl-memory-projection.js'
-import { ModuleRewriteError } from './cell-error.js'
+import { CellAdmissionBlocked, ModuleRewriteError } from './cell-error.js'
 import { mapSourcePosition } from './source-position-map.js'
 import { durabilityState, transitionDurability } from './session-state.js'
 import { dynamicBindingOrigin } from './dynamic-binding-evidence.js'
@@ -38,7 +40,6 @@ import {
   selectUserBindingsSnapshot,
 } from './user-bindings.js'
 
-const OUTPUT_LIMIT_MESSAGE = bytes => `output exceeded ${bytes} bytes; this cell was discarded and the worker reset. Only bindings in the verified recovery frontier can be restored. External effects may already have occurred and are not undone. For future cells, bound console output and return a smaller value; do not assume this cell's values remain available.`
 
 function earlyResult(kind, message) {
   return { logs: [], error: { kind, message } }
@@ -94,7 +95,7 @@ function parseDiagnostic(error, source, position, repair) {
         : ['this cell was not executed; correct the reported syntax and retry only this cell with run_code']
       : [
           `this cell was not executed; validated syntax repair: append ${JSON.stringify(repair.delimiter)} at the end of this cell`,
-          `when this correction matches your intent and tools.edit_run_code is available in the program SDK, use ${repair.invocation} inside a new run_code cell with its target guard; the accepted edit runs the complete corrected cell after that new cell finishes; validation proves syntax/preflight acceptance, not intended behavior; otherwise submit corrected source in run_code`,
+          `when this correction matches your intent, tools.edit_run_code can apply it to call_seq ${repair.targetCallSeq} (same anchor with ${JSON.stringify(repair.delimiter)} appended); the accepted edit reruns the corrected cell after this one, otherwise submit corrected source in run_code`,
         ],
   })
 }
@@ -366,6 +367,35 @@ function stateArguments(value) {
 export class SessionCellExecutor {
   constructor(kernel) {
     this.kernel = kernel
+    this.pendingRestore = undefined
+  }
+
+  /**
+   * Install recorded values into the worker without running any program.
+   *
+   * Recovery restores a cell the journal recorded as volatile from the values
+   * that cell produced. Sending its source instead would redispatch whatever
+   * ambient source made it volatile, so this path carries values only: the
+   * worker commits each one as a declaration and reports the names it could
+   * not install. A missing worker is reported the same way rather than thrown,
+   * because the caller has to tell the model which bindings it lost.
+   */
+  async restoreBindings(values, config = this.kernel.config) {
+    const kernel = this.kernel
+    const failedAll = reason => values.map(entry => ({ name: entry.name, reason }))
+    if (kernel.disposed) return { restored: [], failed: failedAll('session kernel disposed') }
+    if (kernel.client.worker === undefined) return { restored: [], failed: failedAll('no live worker') }
+    const id = ++kernel.sequence
+    const valueLimits = kernel.valueLimits(config)
+    return new Promise(resolve => {
+      this.pendingRestore = { id, resolve }
+      try {
+        kernel.client.post({ type: 'restore', id, values, valueLimits })
+      } catch (error) {
+        this.pendingRestore = undefined
+        resolve({ restored: [], failed: failedAll(error instanceof Error ? error.message : String(error)) })
+      }
+    })
   }
 
   async executeCell(request, replayRecord = undefined, config = this.kernel.config) {
@@ -380,6 +410,24 @@ export class SessionCellExecutor {
       kernel.completeJournal(request.journal, 'noop', result)
       return result
     }
+    // A restore-only request installs recorded values: it must not compile or run
+    // the node's program. Preparing it first could reject source that is dead by
+    // definition — the node is not on the path to the head, so it may reference
+    // bindings a recorded rewind ended — and a rejected preparation is what made
+    // the off-path repair install nothing. The catalog advances from the recorded
+    // names instead, so later cells still compile against them.
+    if (request.restoreValues !== undefined) {
+      try {
+        await kernel.prepareWorker()
+        await kernel.ensureWorker(config.maxOldGenerationSizeMb)
+      } catch (error) {
+        if (error instanceof CellAdmissionBlocked) throw error
+        return earlyResult('worker-exit', messageOf(error))
+      }
+      const outcome = await this.restoreBindings(request.restoreValues, config)
+      kernel.bindingCatalog = kernel.bindingCatalog.restore(outcome.restored)
+      return { logs: [], restored: outcome.restored, failed: outcome.failed }
+    }
 
     let userBindings
     const userBindingsShadowPolicy = replayRecord?.userBindingsShadowPolicy ?? LIVE_USER_BINDINGS_SHADOW_POLICY
@@ -425,6 +473,7 @@ export class SessionCellExecutor {
     const moduleDirectory = executionCwd ?? process.cwd()
     const moduleFilename = resolve(moduleDirectory, 'repl')
     const prepareCell = program => prepareProgram(program, {
+      rewriteDescriptions: rewriteDescriptions(resolvePromptTextConfig(config)),
       knownBindings: catalog.knownBindings,
       bindingPolicy,
       languageSemantics,
@@ -483,8 +532,12 @@ export class SessionCellExecutor {
     let worker
     try {
       await kernel.prepareWorker()
-      worker = await kernel.client.ensure(config.maxOldGenerationSizeMb)
+      worker = await kernel.ensureWorker(config.maxOldGenerationSizeMb)
     } catch (error) {
+      // An admission block is the kernel's own lifecycle fact, so the kernel
+      // settles the cell: it must not be read as a failure of recorded history
+      // or of this source.
+      if (error instanceof CellAdmissionBlocked) throw error
       const result = earlyResult('worker-exit', messageOf(error))
       kernel.completeJournal(request.journal, 'discarded', result)
       kernel.rollbackToDurable()
@@ -510,6 +563,7 @@ export class SessionCellExecutor {
       const active = {
         id,
         started: false,
+        dispatched: false,
         request: { ...request, bindings: bindings.namespaces },
         finish: resolve,
         computeTimer: undefined,
@@ -561,23 +615,57 @@ export class SessionCellExecutor {
         // cache. Work that completed before this request must not be charged to
         // the new cell, and work after the sample must remain counted.
         active.wallTimer = setTimeout(() => {
+          // A cell that never reached the runtime has executed nothing, so this
+          // failure cannot discard an earlier settlement or justify rebuilding the
+          // worker on its own; SessionRuntime owns how many such cells it keeps.
+          if (active.dispatched !== true) {
+            kernel.abandonCell(active, earlyResult(
+              'budget-unavailable',
+              `wall-clock ceiling reached (${config.maxWallMs}ms) before this cell was dispatched; no code from it ran; retry the cell or raise maxWallMs`,
+            ))
+            return
+          }
           active.resolve(earlyResult('timeout', `wall-clock ceiling reached (${config.maxWallMs}ms); split long-running work into smaller cells`), true)
         }, config.maxWallMs)
         active.budgetsReady = (async () => {
           let started
           try {
+            // How long this environment may wait for an answer belongs to the
+            // cell's configuration; the transport reads its bound per request.
+            if (Number.isSafeInteger(config.sampleBoundMs) && config.sampleBoundMs > 0) {
+              worker.sampleBoundMs = config.sampleBoundMs
+            }
             started = await worker.sampleUtilization()
           } catch (error) {
-            // No fresh baseline means this request cannot be measured. Use the
-            // existing worker-exit route instead of pretending the last cache
-            // sample is this request's starting point.
-            active.resolve(earlyResult('worker-exit', messageOf(error)), true)
+            // No fresh baseline means this request cannot be measured: the
+            // helper's periodic cache may predate work that already finished, so
+            // it is not a substitute start point. A helper that is still trusted
+            // has not failed, and no frame was dispatched yet, so the unmeasured
+            // cell settles without execution. Only a helper the transport reports
+            // as lost takes the worker-exit route.
+            if (safeProperty(error, 'code') === UNANSWERED_SAMPLE_CODE) {
+              kernel.abandonCell(active, earlyResult(
+                'budget-unavailable',
+                `${messageOf(error)}; this cell was not dispatched and no code from it ran; retry the cell`,
+              ))
+            } else {
+              active.resolve(earlyResult('worker-exit', messageOf(error)), true)
+            }
             return
           }
           if (active.settled) return
           active.computeTimer = setInterval(() => {
             if (active.settled) return
             if (worker.performance.eventLoopUtilization(started).active > config.computeMs) {
+              // Nothing from this cell was dispatched, so an exhausted budget
+              // measures earlier work on this worker, not this cell's source.
+              if (active.dispatched !== true) {
+                kernel.abandonCell(active, earlyResult(
+                  'budget-unavailable',
+                  `compute budget exhausted (${config.computeMs}ms event-loop active) before this cell was dispatched; no code from this cell ran; a callback from earlier work may still be blocking the worker; retry the cell or restart the session`,
+                ))
+                return
+              }
               active.resolve(earlyResult('timeout', `compute budget exhausted (${config.computeMs}ms event-loop active, including synchronous blocking); this measure does not establish CPU use or the specific cause. Use asynchronous waiting for long waits, or a DSH-owned managed job if available. This cell was discarded and the worker reset; external effects or processes may continue.`), true)
             }
           }, Math.min(100, config.computeMs))
@@ -604,6 +692,12 @@ export class SessionCellExecutor {
             returnSignal: prepared.returnSignal,
             asyncCompletion: prepared.asyncCompletion,
             commitSignal: prepared.commitSignal,
+            // Compile-time evidence that a binding's initializer is a bounded
+            // object literal. Nothing records from it yet; settlement will use
+            // it to decide whether a value can be captured without walking it.
+            declarationEvidence: prepared.declarations
+              .filter(declaration => declaration.boundedLiteral !== undefined)
+              .map(declaration => [declaration.name, declaration.boundedLiteral]),
             maxOutputBytes: config.maxOutputBytes,
             valueLimits,
             durability,
@@ -624,6 +718,9 @@ export class SessionCellExecutor {
               ...request.bindingDescriptors.reservedNames,
             ])],
           })
+          // The run frame is with the worker now, so a later failure may have
+          // executed this cell's source and cannot settle as an unmeasured cell.
+          active.dispatched = true
         } catch (error) {
           active.resolve(earlyResult('worker-exit', messageOf(error)), true)
         }
@@ -689,7 +786,7 @@ export class SessionCellExecutor {
         throw new Error(`cannot save a durable REPL state from a volatile segment; volatile reason: ${active.durability.reason ?? 'replayability is unproved'}. This save rejection leaves live bindings usable in the current worker; continue computation from them. It does not undo external effects.`)
       }
       active.control.names.add(name)
-      active.journal.operations.push({ action, name })
+      active.journal.operations.push({ action, name, kind: 'checkpoint' })
       return { action, name, saved: true }
     }
     if (action === 'delete') {
@@ -703,6 +800,18 @@ export class SessionCellExecutor {
   }
 
   onMessage(message) {
+    if (message?.type === 'restored') {
+      const pending = this.pendingRestore
+      if (pending === undefined || pending.id !== message.id) return
+      this.pendingRestore = undefined
+      const restored = Array.isArray(message.restored) ? message.restored.filter(name => typeof name === 'string') : []
+      const failed = Array.isArray(message.failed)
+        ? message.failed.filter(entry => entry !== null && typeof entry === 'object' && typeof entry.name === 'string')
+          .map(entry => ({ name: entry.name, reason: typeof entry.reason === 'string' ? entry.reason : 'the worker did not report a reason' }))
+        : []
+      pending.resolve({ restored, failed })
+      return
+    }
     if (message?.type === 'observation-started') {
       const kernel = this.kernel
       const observation = kernel.workerObservation
@@ -759,7 +868,7 @@ export class SessionCellExecutor {
     const logs = Array.isArray(message.logs) && message.logs.every(log => typeof log === 'string') ? message.logs : []
     active.resolve({
         logs: limitLogs(logs),
-        error: { kind: 'output-limit', message: OUTPUT_LIMIT_MESSAGE(active.config.maxOutputBytes) },
+        error: { kind: 'output-limit', message: resultEnvelopeText(resolvePromptTextConfig(active.config), active.config.maxOutputBytes) },
     }, true)
   }
 
@@ -791,6 +900,18 @@ export class SessionCellExecutor {
         reason: typeof message.volatileReason === 'string' ? message.volatileReason : undefined,
       })
     }
+    // The worker sends the values this settlement produced, durable or volatile, so
+    // the journal can keep them; recovery installs them instead of re-running the
+    // cell when its replay path does not reach it. A value the worker could not
+    // transfer arrives in `unrecorded` and is named in the record.
+    const recorded = message.bindingValues ?? message.volatileBindingValues
+    if (recorded !== undefined && typeof recorded === 'object'
+      && Array.isArray(recorded.values) && Array.isArray(recorded.unrecorded)
+      && recorded.values.every(entry => entry !== null && typeof entry === 'object'
+        && typeof entry.name === 'string' && entry.wire !== undefined)
+      && recorded.unrecorded.every(name => typeof name === 'string')) {
+      active.bindingValues = recorded
+    }
     if (active.replay !== undefined && active.durability.status !== 'durable') {
       active.resolve({ logs, error: { kind: 'recovery', message: 'durable history requested a volatile capability during replay' } }, true)
       return
@@ -851,7 +972,7 @@ export class SessionCellExecutor {
     if (bytes > active.config.maxOutputBytes) {
       active.resolve({
         logs: limitLogs(logs),
-        error: { kind: 'output-limit', message: OUTPUT_LIMIT_MESSAGE(active.config.maxOutputBytes) },
+        error: { kind: 'output-limit', message: resultEnvelopeText(resolvePromptTextConfig(active.config), active.config.maxOutputBytes) },
       }, true)
       return
     }