dsh-ptc-plus 0.2.3 → 0.3.1

package/internal/direct-surface-owner.js

@@ -6,11 +6,17 @@ import { projectProgramSdk } from './sdk-projection.js'
 import { EDIT_RUN_CODE } from './edit-transport-owner.js'
 import { RUN_CODE } from './runtime-bridge-owner.js'
 import { isRecord } from './record-utils.js'
+import { missingDescriptionPath } from './failure-reporting.js'
+import {
+  generatedRunCodeExecutionArguments,
+  generatedRunCodeDescriptionMeta,
+} from './run-code-description.js'
 
 const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL. Earlier top-level bindings remain available, so this call extends the current environment instead of creating a fresh one. Use `code` for the async-function body and `description` for its short UI summary. Successful image-bearing subtool results are attached after the cell.'
 const RUN_CODE_CODE_DESCRIPTION = 'Code for the next REPL cell, parsed as the body of an async TypeScript function.'
 const RUN_CODE_DESCRIPTION_DESCRIPTION = 'Short active-voice summary of what this cell does, 5-10 words (shown in the UI).'
 const CODE_TRANSPORT_INSTRUCTION = '`run_code` and `edit_run_code` are the only tools callable directly. Call every native tool declared by the SDK from inside a program.'
+const PTC_COLLAPSE_SECTION_NAMES = Object.freeze(['tools:ptc-only', 'tools:code-only'])
 
 function adaptRunCodeSchema(tool) {
   const parameters = tool.parameters
@@ -94,19 +100,21 @@ export function createCordisRecoveryPolicy(initiallyEnabled) {
 function presentationState(assembly) {
   const tools = Array.isArray(assembly?.tools) ? assembly.tools : []
   if (!tools.some(tool => tool?.name === RUN_CODE)) {
-    return { presentation: 'native', ownerProven: false }
+    return { presentation: 'native', ownerProven: false, collapseSectionName: undefined }
   }
-  const collapse = assembly?.sections?.find(section => section?.name === 'tools:code-only')
+  const collapse = PTC_COLLAPSE_SECTION_NAMES
+    .map(name => assembly?.sections?.find(section => section?.name === name))
+    .find(section => section !== undefined)
   if (collapse !== undefined) {
     const presentation = typeof collapse.text === 'string' && collapse.text.trim().length > 0
-      ? 'code'
+      ? 'ptc'
       : 'both'
-    return { presentation, ownerProven: true }
+    return { presentation, ownerProven: true, collapseSectionName: collapse.name }
   }
   const presentation = tools.every(tool => tool?.name === RUN_CODE || tool?.name === EDIT_RUN_CODE)
-    ? 'code'
+    ? 'ptc'
     : 'both'
-  return { presentation, ownerProven: false }
+  return { presentation, ownerProven: false, collapseSectionName: undefined }
 }
 
 async function* bindCallPolicies(source, policy, calls) {
@@ -144,6 +152,7 @@ export function createDirectSurfaceOwner({
   const sessions = new Map()
   const cordisRecovery = createCordisRecoveryPolicy(runtimeConfig.cordisToolsEnabled)
   let currentCanonicalizeToolCalls = canonicalizeToolCalls
+  let currentAutoDescribeRunCode = runtimeConfig.autoDescribeRunCode
   const tipConfig = {
     enabled: runtimeConfig.tipsEnabled,
     cooldownMessages: runtimeConfig.tipCooldownMessages,
@@ -184,9 +193,9 @@ export function createDirectSurfaceOwner({
     return undefined
   }
 
-  const rememberRequest = (id, signal, presentation, nativeSchemas) => {
+  const rememberRequest = (id, signal, presentation, nativeSchemas, autoDescribeRunCode) => {
     const owner = sessionOwner(id)
-    const request = { presentation, nativeSchemas, owner }
+    const request = { presentation, nativeSchemas, autoDescribeRunCode, owner }
     owner.latestRequest = request
     if (signal !== undefined) canonicalRequests.set(signal, request)
   }
@@ -208,21 +217,24 @@ export function createDirectSurfaceOwner({
   return Object.freeze({
     reconfigure(nextConfig) {
       currentCanonicalizeToolCalls = nextConfig.canonicalizeToolCalls
+      currentAutoDescribeRunCode = nextConfig.autoDescribeRunCode
       cordisRecovery.reconfigure(nextConfig.cordisToolsEnabled)
       tipConfig.enabled = nextConfig.tipsEnabled
       tipConfig.cooldownMessages = nextConfig.tipCooldownMessages
       tipConfig.escalationFailures = nextConfig.tipEscalationFailures
     },
     async assemble(initialAssembly, context, next) {
+      // Keep schema projection and later execution on one configuration snapshot.
+      const autoDescribeRunCode = currentAutoDescribeRunCode
       const agent = context?.agent
       const id = sessionId(agent)
       const initialState = presentationState(initialAssembly)
       let composition = compositions.get(agent)
       if (composition === undefined && id !== undefined
-        && (initialState.ownerProven || initialState.presentation === 'code')) {
+        && (initialState.ownerProven || initialState.presentation === 'ptc')) {
         composition = captureComposition(agent, id, initialState.presentation)
       }
-      if (composition?.presentation === 'code' && !editTransport.isInstalled(agent)) {
+      if (composition?.presentation === 'ptc' && !editTransport.isInstalled(agent)) {
         editTransport.ensureInstalled(agent)
       }
 
@@ -235,7 +247,7 @@ export function createDirectSurfaceOwner({
       if (composition === undefined && id !== undefined) {
         const state = initialState.ownerProven ? initialState : completedState
         composition = captureComposition(agent, id, state.presentation)
-        if (composition.presentation === 'code' && !editTransport.isInstalled(agent)) {
+        if (composition.presentation === 'ptc' && !editTransport.isInstalled(agent)) {
           editTransport.ensureInstalled(agent)
         }
       }
@@ -249,7 +261,7 @@ export function createDirectSurfaceOwner({
           throw new Error(`ptc-plus: ${presentation} agent composition assembled without run_code`)
         }
         if (id !== undefined) {
-          rememberRequest(id, requestSignal, 'native', new Map())
+          rememberRequest(id, requestSignal, 'native', new Map(), autoDescribeRunCode)
         }
         return assembly
       }
@@ -257,10 +269,10 @@ export function createDirectSurfaceOwner({
         throw new Error('ptc-plus: native agent composition assembled with run_code')
       }
       const sessionPtc = presentation !== 'native' && id !== undefined
-      const sessionCodeOnlyProjection = presentation === 'code' && id !== undefined
+      const sessionPtcProjection = presentation === 'ptc' && id !== undefined
       const runCode = tools.find(tool => tool?.name === RUN_CODE)
       let directTools = tools
-      if (sessionCodeOnlyProjection) {
+      if (sessionPtcProjection) {
         editTransport.ensureInstalled(agent)
         directTools = [adaptRunCodeSchema(runCode), editRunCodeSchema()]
       }
@@ -277,13 +289,13 @@ export function createDirectSurfaceOwner({
         : assembly.contexts
       const projectsSections = presentation !== 'native' && Array.isArray(assembly.sections)
         && assembly.sections.some(section => section?.name === 'tools:sdk'
-          || (sessionCodeOnlyProjection && section?.name === 'tools:code-only'))
+          || (sessionPtcProjection && section?.name === completedState.collapseSectionName))
       const sections = projectsSections
         ? assembly.sections.map(section => {
             if (section?.name === 'tools:sdk') {
               return { ...section, text: capabilitySdk(section.text) }
             }
-            if (sessionCodeOnlyProjection && section?.name === 'tools:code-only') {
+            if (sessionPtcProjection && section?.name === completedState.collapseSectionName) {
               return { ...section, text: CODE_TRANSPORT_INSTRUCTION }
             }
             return section
@@ -291,20 +303,22 @@ export function createDirectSurfaceOwner({
         : assembly.sections
 
       if (id !== undefined) {
-        const nativeSchemas = presentation === 'code'
+        const nativeSchemas = presentation === 'ptc'
           ? new Map(toolSchemasForAgent(agent)
             .filter(schema => typeof schema?.name === 'string'
               && schema.name !== RUN_CODE && schema.name !== EDIT_RUN_CODE)
             .map(schema => [schema.name, schema]))
           : new Map()
-        rememberRequest(id, requestSignal, presentation, nativeSchemas)
+        rememberRequest(id, requestSignal, presentation, nativeSchemas, autoDescribeRunCode)
       }
 
       return {
         ...assembly,
-        tools: sessionCodeOnlyProjection
+        tools: sessionPtcProjection
           ? directTools
-          : directTools.map(tool => tool?.name === RUN_CODE ? adaptRunCodeSchema(tool) : tool),
+          : directTools.map(tool => tool?.name === RUN_CODE
+            ? adaptRunCodeSchema(tool)
+            : tool),
         sections,
         contexts,
       }
@@ -313,7 +327,7 @@ export function createDirectSurfaceOwner({
       const optionSessionId = options.sessionId === undefined ? undefined : String(options.sessionId)
       const policy = requestPolicy(options?.signal, optionSessionId)
       if (policy === undefined || optionSessionId === undefined) return next()
-      const source = policy.presentation === 'code'
+      const source = policy.presentation === 'ptc'
         ? canonicalizeToolCallStream(next(), {
           tools: options.tools,
           nativeSchemas: currentCanonicalizeToolCalls ? policy.nativeSchemas : new Map(),
@@ -330,16 +344,56 @@ export function createDirectSurfaceOwner({
       const policy = executionPolicy(id, exec.callId)
         ?? requestPolicy(exec?.signal, id)
       if (exec.name === EDIT_RUN_CODE) {
-        return policy?.presentation === 'code'
+        return policy?.presentation === 'ptc'
           ? undefined
           : rejection(`tool ${EDIT_RUN_CODE} is not declared for this request`)
       }
       if (exec.name === RUN_CODE || exec.parent !== undefined) {
         return undefined
       }
-      if (policy?.presentation !== 'code') return undefined
+      if (policy?.presentation !== 'ptc') return undefined
       return rejection(`tool ${exec.name} is not a direct PTC tool; use run_code or edit_run_code directly, and call native tools from inside run_code`)
     },
+    executionArguments(exec) {
+      const id = sessionId(exec.agent)
+      const policy = executionPolicy(id, exec.callId)
+        ?? requestPolicy(exec?.signal, id)
+      const originalArguments = exec.arguments
+      if (exec.name !== RUN_CODE || exec.parent !== undefined
+        || policy?.autoDescribeRunCode !== true || policy.presentation === 'native'
+        || !isRecord(originalArguments) || Object.hasOwn(originalArguments, 'description')
+        || typeof originalArguments.code !== 'string') {
+        return originalArguments
+      }
+      return generatedRunCodeExecutionArguments(originalArguments)
+    },
+    argumentDiagnostic(exec, result) {
+      // DSH uses success-result identity to avoid re-running output projectors
+      // after this middleware's settlement scope has ended.
+      if (exec?.name !== RUN_CODE || result?.isError !== true) return result
+      const meta = generatedRunCodeDescriptionMeta(exec.arguments, result.meta)
+      const diagnosed = meta === result.meta
+        ? result
+        : { ...result, ...(meta === undefined ? {} : { meta }) }
+      const missingPath = missingDescriptionPath(diagnosed.error)
+      if (missingPath === undefined) return diagnosed
+      const id = sessionId(exec.agent)
+      const policy = executionPolicy(id, exec.callId)
+        ?? requestPolicy(exec?.signal, id)
+      const outer = missingPath === 'description'
+        && policy?.autoDescribeRunCode !== true
+        && !(isRecord(exec.arguments) && typeof exec.arguments.description === 'string')
+      const context = {
+        name: 'tools:ptc-plus-run-code-arguments',
+        text: outer
+          ? 'The run_code outer transport arguments are invalid at JSON path $.description. Add a sibling string `description` field to run_code; a description nested inside a native-tool argument does not satisfy this outer requirement.'
+          : `A nested native-tool argument is missing required property "${missingPath}". Add a string description at that path in the native-tool arguments; the outer run_code description does not satisfy this nested requirement.`,
+      }
+      return {
+        ...diagnosed,
+        additionalContexts: [...diagnosed.additionalContexts ?? [], context],
+      }
+    },
     handleResult(exec) {
       const id = sessionId(exec.agent)
       if (id === undefined || typeof exec.callId !== 'string') return

package/internal/edit-transport-owner.js

@@ -20,6 +20,10 @@ import {
 import { editTargetForCall, projectSessionLog } from './session-log-view.js'
 import { RUN_CODE } from './runtime-bridge-owner.js'
 import { isRecord } from './record-utils.js'
+import {
+  validatedReplMemorySnapshot,
+  withReplMemorySnapshot,
+} from './repl-memory-projection.js'
 
 export const EDIT_RUN_CODE = 'edit_run_code'
 
@@ -52,6 +56,7 @@ function derivedEditResult(inner) {
 export function createEditTransportOwner(ctx, {
   durableReplay,
   executeTentative,
+  presentationGeneration,
   sessionId,
   toolSchemasForAgent,
 }) {
@@ -91,7 +96,9 @@ export function createEditTransportOwner(ctx, {
     if (derived.recoveryBoundaries !== undefined) {
       meta[RECOVERY_BOUNDARY_KEY] = normalizeRecoveryBoundaries(derived.recoveryBoundaries)
     }
-    return meta
+    return derived.replMemory === undefined
+      ? meta
+      : withReplMemorySnapshot(meta, derived.replMemory, presentationGeneration)
   }
   definition.output = {
     schema: {
@@ -178,12 +185,14 @@ export function createEditTransportOwner(ctx, {
         && Object.hasOwn(inner.meta, RECOVERY_BOUNDARY_KEY)
         ? normalizeRecoveryBoundaries(inner.meta[RECOVERY_BOUNDARY_KEY])
         : undefined
+      const replMemory = validatedReplMemorySnapshot(inner?.meta, presentationGeneration)
       const value = derivedEditResult(inner)
       const derived = {
         targetCallSeq: target.callSeq,
         journal,
         rewrites,
         recoveryBoundaries,
+        replMemory,
         code: edited.code,
         description: edited.description,
       }

package/internal/failure-reporting.js

@@ -64,6 +64,21 @@ export function oneLineMessage(error) {
   return firstLine(messageOf(error), 'Unknown error').replace(/\s+\(\d+:\d+\)$/, '')
 }
 
+/** Return DSH's reported missing-description property path when it is actionable. */
+export function missingDescriptionPath(error) {
+  const violations = messageOf(error).matchAll(/missing required property ["']([^"']+)["']/g)
+  for (const match of violations) {
+    const path = match[1]
+    if (path === 'description' || path.endsWith('.description')) return path
+  }
+  return undefined
+}
+
+/** Identify DSH's stable missing-description validation fact without parsing arbitrary errors. */
+export function hasMissingDescriptionError(error) {
+  return missingDescriptionPath(error) !== undefined
+}
+
 /** Keep only the newest log entries so an output-limit error cannot flood the model. */
 export function limitLogs(logs) {
   let bytes = 0

package/internal/rejected-cell-editor.js

@@ -252,15 +252,29 @@ function assemble(source, replacements) {
   return changed ? { code: chunks.join('') } : { error: 'edits must change at least one matched fragment' }
 }
 
+function editRunCodeParameterBranch(operation, operationSchema) {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      [operation]: operationSchema,
+      [EXPECTED_TARGET_CALL_SEQ]: {
+        type: 'integer', minimum: 0,
+        description: 'Optional target precondition copied from a validated diagnostic. The edit is rejected if the captured cell has another call sequence.',
+      },
+    },
+    required: [operation],
+  }
+}
+
 export function editRunCodeSchema() {
   return {
     name: 'edit_run_code',
     description: 'Make a small exact or regular-expression change to the most recent eligible cell captured when this edit call is dispatched, then run the complete corrected cell. A successful edit becomes the next eligible cell. Use this only when replaying the whole cell is safe. If earlier code may already have caused an external effect, use a new run_code cell and its existing variables instead; this tool does not resume at the error location. Send exactly one atomic edits or regex_edits array, plus expected_target_call_seq only when a diagnostic supplies it to bind a validated repair to its rejected cell. Choose edits for a few unique literal fragments; choose regex_edits when one counted pattern covers repeated fragments. Every resolved range must be non-overlapping in the original cell.',
     parameters: {
       type: 'object',
-      additionalProperties: false,
-      properties: {
-        edits: {
+      oneOf: [
+        editRunCodeParameterBranch('edits', {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.exactEdits,
           description: 'Atomic exact replacements, all resolved against the original target cell.',
           items: {
@@ -271,8 +285,8 @@ export function editRunCodeSchema() {
             },
             required: ['old_string', 'new_string'],
           },
-        },
-        regex_edits: {
+        }),
+        editRunCodeParameterBranch('regex_edits', {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
           description: 'Atomic regular-expression replacements, all matched against the original target cell.',
           items: {
@@ -285,13 +299,8 @@ export function editRunCodeSchema() {
             },
             required: ['pattern', 'flags', 'replacement', 'expected_matches'],
           },
-        },
-        [EXPECTED_TARGET_CALL_SEQ]: {
-          type: 'integer', minimum: 0,
-          description: 'Optional target precondition copied from a validated diagnostic. The edit is rejected if the captured cell has another call sequence.',
-        },
-      },
-      oneOf: [{ required: ['edits'] }, { required: ['regex_edits'] }],
+        }),
+      ],
     },
   }
 }

package/internal/repl-memory-projection.js

@@ -0,0 +1,277 @@
+import { isRecord } from './record-utils.js'
+
+export const REPL_MEMORY_KEY = 'ptcPlusRepl'
+export const REPL_MEMORY_META_KEY = 'dshPtcPlusBindings'
+
+const BINDING_KINDS = new Set(['variable', 'function', 'class', 'import'])
+const MAX_BINDINGS = 128
+const MAX_BINDING_NAME_LENGTH = 128
+const MAX_DEFINITION_SOURCE_LENGTH = 1024
+const MAX_DEFINITION_SOURCE_TOTAL_LENGTH = 16 * 1024
+const MAX_PENDING_REPL_CALLS = 256
+const MAX_CALL_ID_LENGTH = 512
+const MAX_GENERATION_LENGTH = 128
+const SNAPSHOT_FIELDS = new Set(['available', 'entries', 'total', 'omitted'])
+const ENTRY_FIELDS = new Set(['name', 'kind', 'definition'])
+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 PENDING_CALL_FIELDS = new Set(['callId', 'seq'])
+const REPL_TOOL_NAMES = new Set(['run_code', 'edit_run_code'])
+const REPL_MEMORY_META_VERSION = 3
+
+function exactFields(value, fields) {
+  if (!isRecord(value)) return false
+  const keys = Reflect.ownKeys(value)
+  return keys.length === fields.size && keys.every(key => (
+    typeof key === 'string' && fields.has(key)
+    && Object.prototype.propertyIsEnumerable.call(value, key)
+  ))
+}
+
+const EMPTY_REPL_MEMORY = Object.freeze({
+  available: false,
+  entries: Object.freeze([]),
+  total: 0,
+  omitted: 0,
+})
+
+export function unavailableReplMemorySnapshot() {
+  return EMPTY_REPL_MEMORY
+}
+
+function normalizeGeneration(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_GENERATION_LENGTH) {
+    throw new Error('invalid dsh-ptc-plus REPL memory generation')
+  }
+  return value
+}
+
+function normalizeDefinition(value) {
+  if (!exactFields(value, DEFINITION_FIELDS)
+    || typeof value.source !== 'string' || value.source.length === 0
+    || value.source.length > MAX_DEFINITION_SOURCE_LENGTH
+    || !Number.isSafeInteger(value.line) || value.line < 1
+    || !Number.isSafeInteger(value.column) || value.column < 1) {
+    throw new Error('invalid dsh-ptc-plus REPL binding definition')
+  }
+  return Object.freeze({ source: value.source, line: value.line, column: value.column })
+}
+
+function normalizeBinding(value) {
+  if (!exactFields(value, ENTRY_FIELDS) || typeof value.name !== 'string'
+    || value.name.length === 0 || value.name.length > MAX_BINDING_NAME_LENGTH
+    || !BINDING_KINDS.has(value.kind)) {
+    throw new Error('invalid dsh-ptc-plus REPL memory binding')
+  }
+  return Object.freeze({
+    name: value.name,
+    kind: value.kind,
+    definition: normalizeDefinition(value.definition),
+  })
+}
+
+/** Produce bounded, value-independent presentation metadata from the live binding catalog. */
+export function createReplMemorySnapshot(bindings) {
+  const all = Array.isArray(bindings) ? bindings : []
+  const candidates = []
+  const names = new Set()
+  for (const binding of all) {
+    try {
+      const normalized = normalizeBinding(binding)
+      if (names.has(normalized.name)) continue
+      names.add(normalized.name)
+      candidates.push(normalized)
+    } catch {}
+  }
+  const entries = []
+  let sourceLength = 0
+  for (const binding of candidates) {
+    if (entries.length >= MAX_BINDINGS) break
+    if (sourceLength + binding.definition.source.length > MAX_DEFINITION_SOURCE_TOTAL_LENGTH) continue
+    entries.push(binding)
+    sourceLength += binding.definition.source.length
+  }
+  return Object.freeze({
+    available: true,
+    entries: Object.freeze(entries),
+    total: candidates.length,
+    omitted: candidates.length - entries.length,
+  })
+}
+
+/** Validate one complete session-projection value without accepting unknown fields. */
+export function normalizeReplMemorySnapshot(value) {
+  if (!exactFields(value, SNAPSHOT_FIELDS) || typeof value.available !== 'boolean'
+    || !Array.isArray(value.entries) || value.entries.length > MAX_BINDINGS
+    || !Number.isSafeInteger(value.total) || value.total < 0
+    || !Number.isSafeInteger(value.omitted) || value.omitted < 0
+    || value.total !== value.entries.length + value.omitted) {
+    throw new Error('invalid dsh-ptc-plus REPL memory snapshot')
+  }
+  if (!value.available && (value.total !== 0 || value.entries.length !== 0)) {
+    throw new Error('unavailable dsh-ptc-plus REPL memory snapshot must be empty')
+  }
+  const names = new Set()
+  let sourceLength = 0
+  const entries = value.entries.map((entry) => {
+    const normalized = normalizeBinding(entry)
+    if (names.has(normalized.name)) {
+      throw new Error('invalid dsh-ptc-plus REPL memory binding')
+    }
+    sourceLength += normalized.definition.source.length
+    if (sourceLength > MAX_DEFINITION_SOURCE_TOTAL_LENGTH) {
+      throw new Error('dsh-ptc-plus REPL binding definitions exceed the presentation budget')
+    }
+    names.add(normalized.name)
+    return normalized
+  })
+  return Object.freeze({
+    available: value.available,
+    entries: Object.freeze(entries),
+    total: value.total,
+    omitted: value.omitted,
+  })
+}
+
+function normalizeReplMemoryMetadata(value) {
+  if (!exactFields(value, MEMORY_META_FIELDS) || value.version !== REPL_MEMORY_META_VERSION) {
+    throw new Error('invalid dsh-ptc-plus REPL memory metadata')
+  }
+  return Object.freeze({
+    version: REPL_MEMORY_META_VERSION,
+    generation: normalizeGeneration(value.generation),
+    memory: normalizeReplMemorySnapshot(value.memory),
+  })
+}
+
+/** Read current-owner presentation metadata without affecting tool settlement. */
+export function validatedReplMemorySnapshot(meta, generation) {
+  if (!isRecord(meta) || !Object.hasOwn(meta, REPL_MEMORY_META_KEY)) return undefined
+  try {
+    const normalized = normalizeReplMemoryMetadata(meta[REPL_MEMORY_META_KEY])
+    return normalized.generation === normalizeGeneration(generation)
+      ? normalized.memory
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function projectionState(generation, memory, pendingReplCalls) {
+  return Object.freeze({
+    generation,
+    memory,
+    pendingReplCalls: pendingReplCalls === null
+      ? null
+      : Object.freeze(pendingReplCalls),
+  })
+}
+
+function emptyProjectionState(generation) {
+  return projectionState(normalizeGeneration(generation), EMPTY_REPL_MEMORY, [])
+}
+
+function normalizeProjectionState(value, generation) {
+  if (!exactFields(value, PROJECTION_STATE_FIELDS)) {
+    throw new Error('invalid dsh-ptc-plus REPL memory projection state')
+  }
+  const storedGeneration = normalizeGeneration(value.generation)
+  const currentGeneration = normalizeGeneration(generation)
+  if (storedGeneration !== currentGeneration) return emptyProjectionState(currentGeneration)
+  const memory = normalizeReplMemorySnapshot(value.memory)
+  if (value.pendingReplCalls === null) {
+    if (memory.available) {
+      throw new Error('untracked dsh-ptc-plus REPL calls require unavailable memory')
+    }
+    return projectionState(currentGeneration, memory, null)
+  }
+  if (!Array.isArray(value.pendingReplCalls)
+    || value.pendingReplCalls.length > MAX_PENDING_REPL_CALLS) {
+    throw new Error('invalid dsh-ptc-plus pending REPL calls')
+  }
+  let previousSeq
+  const callIds = new Set()
+  const pendingReplCalls = value.pendingReplCalls.map((pending) => {
+    if (!exactFields(pending, PENDING_CALL_FIELDS)
+      || typeof pending.callId !== 'string' || pending.callId.length === 0
+      || pending.callId.length > MAX_CALL_ID_LENGTH || callIds.has(pending.callId)
+      || !Number.isSafeInteger(pending.seq) || pending.seq < 0
+      || (previousSeq !== undefined && previousSeq >= pending.seq)) {
+      throw new Error('invalid dsh-ptc-plus pending REPL call')
+    }
+    callIds.add(pending.callId)
+    previousSeq = pending.seq
+    return Object.freeze({ callId: pending.callId, seq: pending.seq })
+  })
+  return projectionState(currentGeneration, memory, pendingReplCalls)
+}
+
+function eventCallId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= MAX_CALL_ID_LENGTH
+    ? value
+    : undefined
+}
+
+function trackReplCall(state, event) {
+  if (!REPL_TOOL_NAMES.has(event.data?.name)) return state
+  const seq = event.seq
+  const callId = eventCallId(event.data?.callId)
+  if (!Number.isSafeInteger(seq) || seq < 0 || callId === undefined) return state
+  const pending = state.pendingReplCalls
+  if (pending === null || pending.some(call => call.callId === callId || call.seq === seq)) return state
+  if (pending.length >= MAX_PENDING_REPL_CALLS) {
+    return projectionState(state.generation, EMPTY_REPL_MEMORY, null)
+  }
+  return projectionState(state.generation, state.memory, [
+    ...pending,
+    Object.freeze({ callId, seq }),
+  ].sort((left, right) => left.seq - right.seq))
+}
+
+function settleReplCall(state, event, generation) {
+  if (event.surfaceOp !== undefined && event.surfaceOp !== 'append') return state
+  const pending = state.pendingReplCalls
+  if (pending === null) return state
+  const callId = eventCallId(event.data?.message?.source?.callId)
+  if (callId === undefined) return state
+  const index = pending.findIndex(call => call.callId === callId)
+  if (index < 0) return state
+  const remaining = pending.filter((_call, pendingIndex) => pendingIndex !== index)
+  const memory = validatedReplMemorySnapshot(event.data?.meta, generation) ?? state.memory
+  return projectionState(state.generation, memory, remaining)
+}
+
+/** Merge the binding snapshot into private, model-invisible result presentation metadata. */
+export function withReplMemorySnapshot(meta, snapshot, generation) {
+  const base = isRecord(meta) ? { ...meta } : meta === undefined ? {} : { value: meta }
+  base[REPL_MEMORY_META_KEY] = normalizeReplMemoryMetadata({
+    version: REPL_MEMORY_META_VERSION,
+    generation: normalizeGeneration(generation),
+    memory: snapshot,
+  })
+  return base
+}
+
+/** Build the current runtime owner's value-independent session projection. */
+export function createReplMemoryProjection(generation) {
+  const currentGeneration = normalizeGeneration(generation)
+  return Object.freeze({
+    key: REPL_MEMORY_KEY,
+    stateVersion: 3,
+    stateSchema: Object.freeze({
+      parse: value => normalizeProjectionState(value, currentGeneration),
+    }),
+    init: () => emptyProjectionState(currentGeneration),
+    apply(state, event) {
+      if (event?.type === 'session/end-seed') return emptyProjectionState(currentGeneration)
+      if (event?.type === 'tool/call') return trackReplCall(state, event)
+      if (event?.type === 'tool/result') return settleReplCall(state, event, currentGeneration)
+      return state
+    },
+    wire: Object.freeze({
+      viewSchema: Object.freeze({ parse: normalizeReplMemorySnapshot }),
+      view: state => state.memory,
+    }),
+  })
+}

package/internal/run-code-description.js

@@ -0,0 +1,34 @@
+const GENERATED_RUN_CODE_DESCRIPTION = 'Execute the next TypeScript cell in this session'
+export const GENERATED_RUN_CODE_DESCRIPTION_KEY = 'dshPtcPlusRunCodeDescription'
+
+// Keep presentation provenance outside the canonical JSON argument graph.
+const generatedArguments = new WeakSet()
+
+export function markGeneratedRunCodeArguments(argumentsValue) {
+  if (argumentsValue !== null
+    && (typeof argumentsValue === 'object' || typeof argumentsValue === 'function')) {
+    generatedArguments.add(argumentsValue)
+  }
+  return argumentsValue
+}
+
+export function generatedRunCodeExecutionArguments(argumentsValue) {
+  markGeneratedRunCodeArguments(argumentsValue)
+  return markGeneratedRunCodeArguments({
+    ...argumentsValue,
+    description: GENERATED_RUN_CODE_DESCRIPTION,
+  })
+}
+
+export function generatedRunCodeDescriptionMeta(argumentsValue, meta) {
+  if (!generatedArguments.has(argumentsValue)) return meta
+  const base = meta !== null && typeof meta === 'object' && !Array.isArray(meta)
+    ? meta
+    : meta === undefined ? {} : { value: meta }
+  return {
+    ...base,
+    [GENERATED_RUN_CODE_DESCRIPTION_KEY]: GENERATED_RUN_CODE_DESCRIPTION,
+  }
+}
+
+export { GENERATED_RUN_CODE_DESCRIPTION }