dsh-ptc-plus 0.2.3 → 0.3.1

package/internal/runtime-bridge-owner.js

@@ -19,6 +19,8 @@ import {
   toolCapabilityMetadata,
 } from './program-bindings.js'
 import { deepFreeze } from './record-utils.js'
+import { withReplMemorySnapshot } from './repl-memory-projection.js'
+import { generatedRunCodeDescriptionMeta } from './run-code-description.js'
 
 export const RUN_CODE = 'run_code'
 
@@ -123,6 +125,7 @@ export function createRuntimeBridgeOwner({
   ctx,
   sessionConfig,
   maxNestedRunCodeDepth,
+  presentationGeneration,
   sessionId,
   toolSchemasForAgent,
 }) {
@@ -247,7 +250,7 @@ export function createRuntimeBridgeOwner({
     return { request: { ...request, bindings: projected }, release }
   }
 
-  const patchResultMetadata = (agent) => {
+  const patchRunCodeDefinition = (agent) => {
     const definition = ctx.tools.get(RUN_CODE, agent)
     if (definition === undefined) {
       throw new Error('ptc-plus: run_code definition is unavailable for the owning session')
@@ -257,28 +260,65 @@ export function createRuntimeBridgeOwner({
     }
     if (patchedDefinitions.has(definition)) return
     const output = definition.output
-    const original = output.presentationMeta
-    const patched = (args, value) => {
-      if (!active) return original === undefined ? undefined : original(args, value)
-      const base = original === undefined ? undefined : original(args, value)
+    const originalPresentationMeta = output.presentationMeta
+    const patchedPresentationMeta = (args, value) => {
+      if (!active) {
+        return originalPresentationMeta === undefined
+          ? undefined
+          : originalPresentationMeta(args, value)
+      }
+      const base = originalPresentationMeta === undefined
+        ? undefined
+        : originalPresentationMeta(args, value)
       const current = scope.getStore()
       const settlement = current?.settlement
-      if (settlement === undefined) return base
+      if (settlement === undefined) return generatedRunCodeDescriptionMeta(args, base)
       let meta = withJournal(base, settlement.journal)
       if (settlement.recoveryBoundaries !== undefined) {
         meta = withRecoveryBoundaries(meta, settlement.recoveryBoundaries)
       }
-      return settlement.rewrites === undefined ? meta : withRewrites(meta, settlement.rewrites)
+      if (settlement.rewrites !== undefined) meta = withRewrites(meta, settlement.rewrites)
+      meta = generatedRunCodeDescriptionMeta(args, meta)
+      return withReplMemorySnapshot(meta, settlement.replMemory, presentationGeneration)
     }
+    const ownExecute = Object.getOwnPropertyDescriptor(definition, 'execute')
+    const originalExecute = definition.execute
+    const patchedExecute = typeof originalExecute !== 'function'
+      ? undefined
+      : function (args, exec) {
+          const executionArguments = scope.getStore()?.executionArguments ?? args
+          return originalExecute.call(this, executionArguments, exec)
+        }
+    let presentationPatched = false
     try {
       Object.defineProperty(output, 'presentationMeta', {
         configurable: true,
         enumerable: true,
         writable: true,
-        value: patched,
+        value: patchedPresentationMeta,
+      })
+      presentationPatched = true
+      if (patchedExecute !== undefined) {
+        Object.defineProperty(definition, 'execute', {
+          configurable: true,
+          enumerable: ownExecute?.enumerable ?? true,
+          writable: true,
+          value: patchedExecute,
+        })
+      }
+      patchedDefinitions.set(definition, {
+        definition,
+        output,
+        originalPresentationMeta,
+        patchedPresentationMeta,
+        ownExecute,
+        patchedExecute,
       })
-      patchedDefinitions.set(definition, { output, original, patched })
     } catch (error) {
+      if (presentationPatched && output.presentationMeta === patchedPresentationMeta) {
+        if (originalPresentationMeta === undefined) delete output.presentationMeta
+        else output.presentationMeta = originalPresentationMeta
+      }
       throw new Error(`ptc-plus: cannot attach the session journal to run_code results: ${error.message}`)
     }
   }
@@ -333,11 +373,11 @@ export function createRuntimeBridgeOwner({
         throw error
       }
     },
-    handleExecute(exec, next) {
+    handleExecute(exec, next, executionArguments = exec.arguments) {
       if (exec.parent !== undefined) return scope.run(undefined, next)
       const id = sessionId(exec.agent)
       if (id === undefined) return next()
-      patchResultMetadata(exec.agent)
+      patchRunCodeDefinition(exec.agent)
       const inherited = scope.getStore()
       const persistedCallSeq = inherited?.persistedCallSeq
       const current = {
@@ -349,6 +389,7 @@ export function createRuntimeBridgeOwner({
           : { deferredSettlement: inherited.deferredSettlement }),
         session: exec.agent?.session,
         agent: exec.agent,
+        executionArguments,
       }
       if (current.deferredSettlement !== undefined) {
         current.deferredSettlement.current = current
@@ -363,6 +404,7 @@ export function createRuntimeBridgeOwner({
             meta = withRecoveryBoundaries(meta, settlement.recoveryBoundaries)
           }
           if (settlement.rewrites !== undefined) meta = withRewrites(meta, settlement.rewrites)
+          meta = withReplMemorySnapshot(meta, settlement.replMemory, presentationGeneration)
           return { ...result, meta }
         }
         return result
@@ -405,10 +447,16 @@ export function createRuntimeBridgeOwner({
         if (ownRun === undefined) delete runtime.run
         else Object.defineProperty(runtime, 'run', ownRun)
       }
-      for (const { output, original, patched } of patchedDefinitions.values()) {
-        if (output.presentationMeta !== patched) continue
-        if (original === undefined) delete output.presentationMeta
-        else output.presentationMeta = original
+      for (const patched of patchedDefinitions.values()) {
+        if (patched.output.presentationMeta === patched.patchedPresentationMeta) {
+          if (patched.originalPresentationMeta === undefined) delete patched.output.presentationMeta
+          else patched.output.presentationMeta = patched.originalPresentationMeta
+        }
+        if (patched.patchedExecute !== undefined
+          && patched.definition.execute === patched.patchedExecute) {
+          if (patched.ownExecute === undefined) delete patched.definition.execute
+          else Object.defineProperty(patched.definition, 'execute', patched.ownExecute)
+        }
       }
       patchedDefinitions.clear()
       await sessions.dispose()

package/internal/runtime-config.js

@@ -18,6 +18,8 @@ const BUDGET_KEYS = Object.freeze([
 
 /** Boolean runtime behavior switches. */
 const BOOLEAN_KEYS = Object.freeze([
+  'enhancedToolView',
+  'autoDescribeRunCode',
   'cordisToolsEnabled',
   'canonicalizeToolCalls',
   'looseTopLevelRedeclarations',

package/internal/session-cell-executor.js

@@ -12,6 +12,7 @@ import {
   LONG_CELL_CODE_UNITS,
   markBindingFailure,
   messageOf,
+  missingDescriptionPath,
   oneLineMessage,
   safeProperty,
 } from './failure-reporting.js'
@@ -128,7 +129,11 @@ function exceptionDiagnostic({
   declared,
   longCellFailure = false,
 }) {
-  const message = firstLine(error.message, 'Unknown exception')
+  const missingPath = error.name === 'ToolCallError' ? missingDescriptionPath(error) : undefined
+  const missingDescription = missingPath !== undefined
+  const message = missingDescription
+    ? `nested native tool arguments are missing required \`description\` at JSON path $.${missingPath} (${error.toolName ?? 'unknown tool'}); this does not satisfy the outer run_code transport`
+    : firstLine(error.message, 'Unknown exception')
   const rawName = typeof error.name === 'string' && error.name.length > 0
     ? error.name
     /* c8 ignore next */
@@ -147,7 +152,9 @@ function exceptionDiagnostic({
     ...(cause === undefined ? {} : { cause }),
     ...(source === undefined ? {} : { source }),
     help: [
-      'inspect existing bindings and retry only the failing expression',
+      ...(missingDescription
+        ? ['add a string `description` property to the nested native-tool argument object']
+        : ['inspect existing bindings and retry only the failing expression']),
       ...(error.name === 'ToolCallError'
         && typeof error.toolName === 'string'
         && error.toolName.startsWith('cordis_')
@@ -496,7 +503,7 @@ export class SessionCellExecutor {
       })
       active.appliedBindingCatalog = message.moduleLoadFailed === true
         ? active.priorBindingCatalog
-        : active.priorBindingCatalog.advance(active.prepared)
+        : active.priorBindingCatalog.advance(active.prepared, active.request.program)
       const recordedFailure = active.replay?.diagnostics?.find(item => item.code === 'PTC-X001')
       const failure = recordedFailure?.message === actualFailure.message ? recordedFailure : actualFailure
       const error = {
@@ -525,7 +532,10 @@ export class SessionCellExecutor {
         hasValue: message.hasValue,
         ...(message.hasValue ? { value } : {}),
       }
-      active.appliedBindingCatalog = active.priorBindingCatalog.advance(active.prepared)
+      active.appliedBindingCatalog = active.priorBindingCatalog.advance(
+        active.prepared,
+        active.request.program,
+      )
       if (active.replay?.completion?.kind === 'return'
         && (active.replay.completion.hasValue !== message.hasValue
           || (message.hasValue && !valueWiresEqual(active.replay.completion.value, value, active.valueLimits)))) {

package/internal/session-events.js

@@ -0,0 +1,7 @@
+/** Read the immutable session log across current and legacy DSH session APIs. */
+export function sessionEvents(session) {
+  if (typeof session?.snapshotEvents === 'function') {
+    return session.snapshotEvents()
+  }
+  return session?.events
+}

package/internal/session-journal.js

@@ -1,6 +1,7 @@
 import { decodeValue, encodeValue, normalizeValueWire } from './value-wire.js'
 import { normalizeDiagnostic } from './diagnostic.js'
 import { assertOwnFields, isRecord } from './record-utils.js'
+import { sessionEvents } from './session-events.js'
 
 export const JOURNAL_KEY = 'dshPtcPlus'
 export const EDIT_TARGET_KEY = 'dshPtcPlusEdit'
@@ -365,7 +366,7 @@ export function migrateRecoveryBoundaryEvents(events) {
 
 /** Resolve the persisted event identity for one named tool call being dispatched. */
 export function liveToolCallSeq(session, callId, toolName) {
-  const events = session?.events
+  const events = sessionEvents(session)
   if (!Array.isArray(events) || typeof callId !== 'string' || callId.length === 0
     || typeof toolName !== 'string' || toolName.length === 0) return undefined
 
@@ -741,7 +742,7 @@ export function foldSessionTimeline(events) {
 
 /** Fold the session log into the last exactly replayable frontier. */
 export function recoverJournal(session, currentCallSeq, options = {}) {
-  const events = session?.events
+  const events = sessionEvents(session)
   if (!Array.isArray(events)) {
     return { nodes: [], head: undefined, checkpoints: new Map(), volatileSuffix: [], available: true }
   }

package/internal/session-log-view.js

@@ -1,6 +1,7 @@
 import {
   foldSessionTimeline,
 } from './session-journal.js'
+import { sessionEvents } from './session-events.js'
 
 const SYSTEM_PROMPT_PLUGIN = '@deepseek-ai/dsh-system-prompt'
 
@@ -43,7 +44,7 @@ function cordisTranscriptFacts(timeline) {
 
 /** Project session events into immutable facts consumed by prompt presentation. */
 export function projectSessionLog(agent, requestedEdit) {
-  const events = agent?.session?.events
+  const events = sessionEvents(agent?.session)
   if (!Array.isArray(events)) {
     return Object.freeze({
       openTurn: false,

package/internal/session-runtime.js

@@ -13,6 +13,10 @@ import { resolveConfig } from './runtime-config.js'
 import { WorkerClient } from './worker-client.js'
 import { BindingCatalog, durabilityState, transitionDurability } from './session-state.js'
 import { SessionCellExecutor } from './session-cell-executor.js'
+import {
+  createReplMemorySnapshot,
+  unavailableReplMemorySnapshot,
+} from './repl-memory-projection.js'
 
 const WORKER_URL = new URL('./kernel-worker.js', import.meta.url)
 function recoveryDiagnostic(count) {
@@ -300,14 +304,14 @@ class SessionKernel {
           callSeq: request.callSeq,
           program: request.program,
           bindingCatalog: active.appliedBindingCatalog
-            ?? active.priorBindingCatalog.advance(prepared),
+            ?? active.priorBindingCatalog.advance(prepared, request.program),
           worker,
         })
       }
     }
     if (replay !== undefined && !terminate) {
       this.bindingCatalog = active.appliedBindingCatalog
-        ?? active.priorBindingCatalog.advance(prepared)
+        ?? active.priorBindingCatalog.advance(prepared, request.program)
     }
     this.active = undefined
     if (terminate) void this.client.reset(worker)
@@ -353,6 +357,18 @@ class SessionKernel {
     }
   }
 
+  replMemoryFor(journal) {
+    const tentative = this.tentatives.get(journal)
+    if (journal.status === 'discarded'
+      || journal.operations.some(operation => operation.action === 'restore')) {
+      return unavailableReplMemorySnapshot()
+    }
+    if (tentative === undefined) {
+      return createReplMemorySnapshot(this.bindingCatalog.snapshot())
+    }
+    return createReplMemorySnapshot(tentative.bindingCatalog.snapshot())
+  }
+
   finishStateOperations(operations, index, worker) {
     const transition = reduceStateOperations(this.history, operations, index)
     this.history.head = transition.head
@@ -487,6 +503,7 @@ export class SessionRuntime {
       journal,
       kernel,
       sessionId,
+      replMemory: kernel.replMemoryFor(journal),
       ...(result.recoveryBoundaries === undefined
         ? {}
         : { recoveryBoundaries: result.recoveryBoundaries }),

package/internal/session-state.js

@@ -19,11 +19,23 @@ export function transitionDurability(state, transition) {
 
 export class BindingCatalog {
   #known
+  #kinds
+  #definitions
   #imports
   #namespaces
 
-  constructor(known = new Set(), imports = new Map(), namespaces = new Set()) {
+  constructor(
+    known = new Set(),
+    imports = new Map(),
+    namespaces = new Set(),
+    kinds = new Map(),
+    definitions = new Map(),
+  ) {
     this.#known = new Set(known)
+    this.#kinds = new Map([...this.#known].map(name => [name, kinds.get(name) ?? 'variable']))
+    this.#definitions = new Map([...this.#known]
+      .filter(name => definitions.has(name))
+      .map(name => [name, definitions.get(name)]))
     this.#imports = new Map(imports)
     this.#namespaces = new Set(namespaces)
     Object.freeze(this)
@@ -37,9 +49,76 @@ export class BindingCatalog {
     }
   }
 
-  advance(prepared) {
+  advance(prepared, source = undefined) {
     const known = new Set(this.#known)
-    for (const name of prepared.declared) known.add(name)
-    return new BindingCatalog(known, prepared.imports, prepared.importNamespaces)
+    const kinds = new Map(this.#kinds)
+    const definitions = new Map(this.#definitions)
+    const touched = new Set()
+    const extractDefinition = sourceDefinitionExtractor(source)
+    for (const declaration of prepared.declarations ?? []) {
+      if (typeof declaration?.name !== 'string') continue
+      touched.add(declaration.name)
+      kinds.set(declaration.name, declaration.kind ?? 'variable')
+      const definition = extractDefinition(declaration.definitionSpan)
+      if (definition !== undefined) definitions.set(declaration.name, definition)
+    }
+    for (const name of prepared.declared) touched.add(name)
+    for (const name of touched) {
+      known.delete(name)
+      known.add(name)
+    }
+    return new BindingCatalog(known, prepared.imports, prepared.importNamespaces, kinds, definitions)
+  }
+
+  snapshot() {
+    return [...this.#known].reverse()
+      .filter(name => !this.#namespaces.has(name))
+      .map(name => ({
+        name,
+        kind: this.#kinds.get(name) ?? 'variable',
+        ...(this.#definitions.has(name) ? { definition: this.#definitions.get(name) } : {}),
+      }))
+  }
+}
+
+const MAX_DEFINITION_SOURCE_LENGTH = 1024
+
+function lineOffsets(source) {
+  const offsets = [0]
+  for (let index = 0; index < source.length; index += 1) {
+    if (source.charCodeAt(index) === 10) offsets.push(index + 1)
+  }
+  return offsets
+}
+
+function offsetAt(offsets, sourceLength, position) {
+  if (position === null || typeof position !== 'object'
+    || !Number.isSafeInteger(position.line) || position.line < 1
+    || !Number.isSafeInteger(position.column) || position.column < 1
+    || position.line > offsets.length) return undefined
+  const lineStart = offsets[position.line - 1]
+  const lineEnd = position.line < offsets.length ? offsets[position.line] - 1 : sourceLength
+  const offset = lineStart + position.column - 1
+  return offset <= lineEnd ? offset : undefined
+}
+
+function sourceDefinitionExtractor(source) {
+  const offsets = typeof source === 'string' ? lineOffsets(source) : undefined
+  const extracted = new Map()
+  return span => {
+    if (offsets === undefined || span === null || typeof span !== 'object') return undefined
+    const start = offsetAt(offsets, source.length, span)
+    const end = offsetAt(offsets, source.length, span.end)
+    if (start === undefined || end === undefined || end <= start) return undefined
+    const key = `${start}:${end}`
+    if (extracted.has(key)) return extracted.get(key)
+    const length = end - start
+    const bounded = length <= MAX_DEFINITION_SOURCE_LENGTH
+      ? source.slice(start, end)
+      : `${source.slice(start, start + MAX_DEFINITION_SOURCE_LENGTH - 3)}...`
+    if (bounded.length === 0) return undefined
+    const definition = Object.freeze({ source: bounded, line: span.line, column: span.column })
+    extracted.set(key, definition)
+    return definition
   }
 }

package/internal/settings-compat.js

@@ -0,0 +1,31 @@
+/** Install an optional settings section across current and legacy DSH settings APIs. */
+export function installSettingsSectionCompat({
+  ctx,
+  settingsModule,
+  namespace,
+  schema,
+  entry,
+  hooks,
+  onProvider,
+}) {
+  ctx.inject(['settings'], settingsContext => {
+    const provider = settingsContext.settings
+    onProvider(provider)
+    if (typeof provider?.installSection === 'function') {
+      provider.installSection(ctx, namespace, schema, entry, hooks)
+      return
+    }
+    if (typeof settingsModule?.installSettingsSection !== 'function') {
+      throw new Error('ptc-plus: incompatible settings service; expected installSection or installSettingsSection')
+    }
+    const mountedOwner = new Proxy(ctx, {
+      get(target, property) {
+        if (property === 'inject') {
+          return (_services, attach) => attach(settingsContext)
+        }
+        return Reflect.get(target, property, target)
+      },
+    })
+    settingsModule.installSettingsSection(mountedOwner, namespace, schema, entry, hooks)
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ptc-plus",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "A session-bound agent-native REPL for DeepSeek Harness PTC mode.",
   "type": "module",
   "main": "./index.js",
@@ -15,17 +15,23 @@
     "src",
     "internal",
     "docs",
-    "assets/dsh-ptc-plus-banner.webp",
-    "assets/ptc-plus-repair.png",
-    "assets/ptc-plus-settings.png",
+    "assets/dsh-ptc-plus-banner-en.webp",
+    "assets/dsh-ptc-plus-banner-zh.webp",
+    "assets/ptc-plus-repair-zh.png",
+    "assets/ptc-plus-repair-en.png",
+    "assets/ptc-plus-settings-en.png",
+    "assets/ptc-plus-settings-zh.png",
     "cordis.patch.yml",
     "README.md",
-    "README.zh.md",
+    "README.en.md",
     "LICENSE"
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
+  "allowScripts": {
+    "esbuild": false
+  },
   "dependencies": {
     "@babel/code-frame": "^7.29.7",
     "@babel/parser": "^7.29.0",
@@ -34,10 +40,10 @@
     "acorn": "^8.15.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-settings": "next",
-    "@deepseek-ai/dsh-skill-filesystem": "next",
-    "@deepseek-ai/dsh-tool-cordis": "next",
-    "@deepseek-ai/dsh-tools": "next"
+    "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/dsh-skill-filesystem": "*",
+    "@deepseek-ai/dsh-tool-cordis": "*",
+    "@deepseek-ai/dsh-tools": "*"
   },
   "scripts": {
     "build": "node scripts/client-bundle.mjs build",
@@ -82,6 +88,7 @@
       ],
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-settings-plugins",
         "@deepseek-ai/dsh-client-connection",
@@ -90,10 +97,10 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-settings": "next",
-    "@deepseek-ai/dsh-skill-filesystem": "next",
-    "@deepseek-ai/dsh-tool-cordis": "next",
-    "@deepseek-ai/dsh-tools": "next",
+    "@deepseek-ai/dsh-settings": "alpha",
+    "@deepseek-ai/dsh-skill-filesystem": "alpha",
+    "@deepseek-ai/dsh-tool-cordis": "alpha",
+    "@deepseek-ai/dsh-tools": "alpha",
     "esbuild": "0.28.2",
     "yaml": "^2.9.0"
   }