dsh-ptc-plus 0.4.3 → 0.4.10

package/internal/execution-seam-compat.js

@@ -1,39 +1,11 @@
-/**
- * Own how PTC Plus attaches to the host's program-execution seam.
- *
- * DSH registers one execution seam per generation. The current release
- * registers `ctx.ptcRuntime` (`@deepseek-ai/dsh-ptc-runtime`); the preceding one
- * registered `ctx.codeRuntime` (`@deepseek-ai/dsh-code-runtime`). Both run one
- * model-written program against host async bindings. They differ in the service
- * name, in the call shape (`resolve(request)` then `run(spec)` against a single
- * `run(request)`), and in the capability descriptors a provider publishes.
- * Which seam is live is decided by the registered service, never by a version
- * string, so a deployment on either generation obtains the same behavior.
- *
- * PTC Plus replaces the execution of session cells with its own persistent
- * REPL. The object DSH describes to the model is therefore the plugin's
- * execution, not the wrapped provider's, so `takeOver()` answers the
- * descriptors the plugin can honor and withholds the ones it cannot. The REPL
- * runs every cell in one long-lived worker rather than a fresh process per
- * call, applies the session's configured budgets rather than a per-call host
- * deadline, and performs no file confinement. DSH gates `timeoutMs` on
- * `timeout` and resolves or escalates file policy on `sandboxMode`, so
- * withholding those descriptors keeps DSH's authority decisions with DSH
- * instead of having this plugin accept an input it would then ignore.
- *
- * A seam-neutral request carries exactly `program`, `bindings`, and `signal`:
- * the fields PTC Plus consumes. A resolved spec's directory, deadline, and
- * authority describe the provider whose execution was replaced, and are neither
- * forwarded to the session kernel nor re-derived here.
- */
-
 /** Cordis service name registered by the current DSH generation. */
 export const EXECUTION_SEAM_SERVICE = 'ptcRuntime'
 
-/** Cordis service name registered by the preceding DSH generation. */
+/** Historical request-only service name, retained with fixture evidence. */
 export const LEGACY_EXECUTION_SEAM_SERVICE = 'codeRuntime'
 
 const SEAM_SERVICES = Object.freeze([EXECUTION_SEAM_SERVICE, LEGACY_EXECUTION_SEAM_SERVICE])
+const PLUGIN_EXECUTION_SEAM = Symbol.for('dsh-ptc-plus.execution-seam')
 
 /**
  * How long the plugin waits for the host's execution seam before it reports the
@@ -48,34 +20,12 @@ const SEAM_SERVICES = Object.freeze([EXECUTION_SEAM_SERVICE, LEGACY_EXECUTION_SE
  */
 const SEAM_ATTACHMENT_TIMEOUT_MS = 30_000
 
-/**
- * Descriptors the plugin replaces with the capabilities of its own execution.
- * `executionInstructions` describes the wrapped provider's program model, which
- * no longer applies; `timeout` and `sandboxMode` gate host inputs the plugin
- * cannot honor. Withdrawal is unconditional because the rule is a property of
- * the plugin's execution, not of a generation: the preceding generation's
- * contract defines none of these members and nothing in its install closure
- * reads them, so withdrawing there is inert, while a provider that published
- * them stays unable to outlive the takeover.
- */
-const WITHHELD_DESCRIPTORS = Object.freeze(['executionInstructions', 'sandboxMode', 'timeout'])
-
 /** Read a registered service without declaring an injection requirement. */
 function readService(ctx, name) {
   if (typeof ctx?.get === 'function') return ctx.get(name)
   return ctx?.[name]
 }
 
-function descriptorsMatch(left, right) {
-  if (left === undefined || right === undefined) return left === right
-  return left.value === right.value
-    && left.get === right.get
-    && left.set === right.set
-    && left.writable === right.writable
-    && left.enumerable === right.enumerable
-    && left.configurable === right.configurable
-}
-
 /**
  * Build the seam handle for one live execution service.
  * @param {object} service - the registered `ctx.ptcRuntime` or `ctx.codeRuntime`.
@@ -85,6 +35,7 @@ export function createExecutionSeam(service, serviceName) {
   if (service === null || typeof service !== 'object') {
     throw new TypeError(`ptc-plus: ${serviceName} must be an execution service object`)
   }
+  if (typeof service[PLUGIN_EXECUTION_SEAM] === 'function') return service[PLUGIN_EXECUTION_SEAM]()
   const current = serviceName === EXECUTION_SEAM_SERVICE
   const upstreamRun = service.run
   if (typeof upstreamRun !== 'function') {
@@ -95,82 +46,87 @@ export function createExecutionSeam(service, serviceName) {
     throw new TypeError('ptc-plus: ptcRuntime.resolve must be a function')
   }
   let installed
-  return Object.freeze({
+  const sourceListeners = new Set()
+  let available = true
+  const requireAvailable = () => {
+    if (!available) throw new Error(`ptc-plus: original ${serviceName} generation is unavailable`)
+  }
+  const requireCompatible = () => {
+    requireAvailable()
+    if (installed !== undefined && service.language !== installed.language) {
+      throw new Error(`ptc-plus: current original language ${JSON.stringify(service.language)} is incompatible with the active ${JSON.stringify(installed.language)} runtime`)
+    }
+  }
+  const provider = Object.freeze({
+    get language() { requireCompatible(); return service.language },
+    get isolation() { requireCompatible(); return installed === undefined ? service.isolation : 'worker-thread' },
+    get executionInstructions() { requireCompatible(); return installed === undefined ? service.executionInstructions ?? '' : '' },
+    get sandboxMode() { requireCompatible(); return installed === undefined ? service.sandboxMode : undefined },
+    get timeout() { requireCompatible(); return installed === undefined ? service.timeout : undefined },
+    resolve(request) {
+      requireCompatible()
+      return current ? upstreamResolve.call(service, request) : request
+    },
+    run(input) {
+      requireCompatible()
+      return installed === undefined ? upstreamRun.call(service, input) : installed.execute(input)
+    },
+    [PLUGIN_EXECUTION_SEAM]() { return seam },
+  })
+  const seam = Object.freeze({
     serviceName,
-    language: service.language,
+    get language() { requireAvailable(); return service.language },
+    provider,
+    get active() { return installed !== undefined && service.language === installed.language },
+    onSourceChange(listener) {
+      sourceListeners.add(listener)
+      return () => sourceListeners.delete(listener)
+    },
+    sourceChanged() {
+      return Promise.all([...sourceListeners].map(listener => listener())).then(() => undefined)
+    },
     /**
      * Run one program through the provider this plugin wraps. The current
      * generation resolves the request before running it, exactly as its own
      * consumer does; the preceding generation accepts the request directly.
      */
     invokeUpstream(request) {
+      requireCompatible()
       return current
         ? upstreamRun.call(service, upstreamResolve.call(service, request))
         : upstreamRun.call(service, request)
     },
-    /**
-     * Install the plugin's execution entry, and its capability descriptors, on
-     * the live service. Only one takeover is live at a time.
-     * @param {(request: object) => Promise<object>} execute - the plugin's entry.
-     * @returns {() => void} restores every descriptor this call replaced.
-     */
-    takeOver(execute) {
-      if (installed !== undefined) throw new Error('ptc-plus: execution seam already taken over')
-      const saved = new Map()
-      const written = new Map()
-      const requested = new Map()
-      requested.set('run', {
-        configurable: true,
-        writable: true,
-        value: current
-          ? spec => execute({
-              program: spec.program,
-              bindings: spec.bindings,
-              signal: spec.signal,
-            })
-          : request => execute(request),
-      })
-      for (const name of WITHHELD_DESCRIPTORS) {
-        requested.set(name, { configurable: true, value: name === 'executionInstructions' ? '' : undefined })
-      }
-      const extensible = Object.isExtensible(service)
-      for (const [name, descriptor] of requested) {
-        const previous = Object.getOwnPropertyDescriptor(service, name)
-        saved.set(name, previous)
-        const next = { enumerable: previous?.enumerable ?? false, ...descriptor }
-        requested.set(name, next)
-        const probe = {}
-        if (previous !== undefined) Object.defineProperty(probe, name, previous)
-        if (!extensible) Object.preventExtensions(probe)
-        Object.defineProperty(probe, name, next)
-      }
-      try {
-        for (const [name, descriptor] of requested) {
-          Object.defineProperty(service, name, descriptor)
-          written.set(name, Object.getOwnPropertyDescriptor(service, name))
-        }
-      } catch (error) {
-        for (const name of [...written.keys()].reverse()) {
-          if (!descriptorsMatch(Object.getOwnPropertyDescriptor(service, name), written.get(name))) continue
-          const descriptor = saved.get(name)
-          if (descriptor === undefined) delete service[name]
-          else Object.defineProperty(service, name, descriptor)
-        }
-        throw error
-      }
+    runUpstream(spec) {
+      requireCompatible()
+      return upstreamRun.call(service, spec)
+    },
+    installExecute(execute) {
+      requireAvailable()
+      if (typeof execute !== 'function') throw new TypeError('ptc-plus: execution entry must be a function')
+      if (installed !== undefined) throw new Error('ptc-plus: execution seam already installed')
+      const entry = { execute, language: service.language }
+      installed = entry
       const restore = () => {
-        if (installed !== restore) return
+        if (installed !== entry) return
         installed = undefined
-        for (const [name, descriptor] of saved) {
-          if (!descriptorsMatch(Object.getOwnPropertyDescriptor(service, name), written.get(name))) continue
-          if (descriptor === undefined) delete service[name]
-          else Object.defineProperty(service, name, descriptor)
-        }
       }
-      installed = restore
       return restore
     },
+    retire() {
+      available = false
+      installed = undefined
+      sourceListeners.clear()
+    },
   })
+  return seam
+}
+
+function registeredExecutionSeam(service, serviceName) {
+  const seam = createExecutionSeam(service, serviceName)
+  if (typeof service[PLUGIN_EXECUTION_SEAM] !== 'function') {
+    throw new Error(`ptc-plus: ${serviceName} requires the public execution-provider bundle composition`)
+  }
+  return seam
 }
 
 /**
@@ -259,7 +215,7 @@ export function installExecutionSeam(ctx, {
         entry = { name, scope }
         live = entry
         registerLifecycle(entry, name, scope)
-        const attached = attach(scope, createExecutionSeam(scope?.[name] ?? readService(ctx, name), name))
+        const attached = attach(scope, registeredExecutionSeam(scope?.[name] ?? readService(ctx, name), name))
         entry.attached = attached
         return attached
       })
@@ -292,7 +248,7 @@ export function installExecutionSeam(ctx, {
     const entry = { name, scope }
     live = entry
     try {
-      entry.attached = attach(scope, createExecutionSeam(scope?.[name] ?? readService(ctx, name), name))
+      entry.attached = attach(scope, registeredExecutionSeam(scope?.[name] ?? readService(ctx, name), name))
     } catch (error) {
       live = undefined
       throw error

package/internal/isolated-worker.js

@@ -15,6 +15,17 @@ const ISOLATED_STOP_MS = 5000
 /** Bound on the helper's output pipes really ending after its process exited. */
 const ISOLATED_OUTPUT_MS = 5000
 
+export function isolatedWorkerEntry(entry) {
+  if (!(entry instanceof URL) && (typeof entry !== 'string' || entry.length === 0)) {
+    throw new TypeError('isolated worker entry must be a URL or a non-empty string filename')
+  }
+  return entry instanceof URL
+    ? entry.href
+    : entry.slice(0, 5).toLowerCase() === 'file:'
+      ? new URL(entry).href
+      : pathToFileURL(resolve(entry)).href
+}
+
 /**
  * A worker-shaped transport whose worker lives in a killable helper process.
  *
@@ -29,17 +40,10 @@ export class IsolatedWorker extends EventEmitter {
     super()
     // The entry follows the worker constructor's contract: a URL or a string
     // filename. Anything else fails here, before a helper process exists.
-    if (!(entry instanceof URL) && (typeof entry !== 'string' || entry.length === 0)) {
-      throw new TypeError('isolated worker entry must be a URL or a non-empty string filename')
-    }
     // The init message crosses advanced IPC, which cannot rebuild a URL object, so
     // the boundary normalizes it to one absolute file URL string. A path follows
     // the worker constructor's rule: resolved from the current working directory.
-    const entrySpec = entry instanceof URL
-      ? entry.href
-      : entry.slice(0, 5).toLowerCase() === 'file:'
-        ? new URL(entry).href
-        : pathToFileURL(resolve(entry)).href
+    const entrySpec = isolatedWorkerEntry(entry)
     this.stdout = new PassThrough()
     this.stderr = new PassThrough()
     this.protocol = protocol

package/internal/recovery-tips.js

@@ -1,4 +1,4 @@
-import { recoveryTipIdentity } from './runtime-messages.js'
+import { PTC_STATE_NAMES, recoveryTipIdentity } from './runtime-messages.js'
 
 const PLATFORM_CAUSE_CODES = new Set(['EACCES', 'EINVAL', 'ENOTDIR', 'ENOENT', 'UNKNOWN'])
 const TIP_CONTEXT_PREFIX = 'tools:ptc-plus-tip/'
@@ -8,27 +8,58 @@ const TIP_PREFIXES = Object.freeze({
 })
 
 // TODO(dsh-tips-api): replace this local provider with an adapter after dsh-tips publishes a stable facts and decision interface.
-function tipHistory(view) {
-  const active = new Map()
-  const seen = new Set()
-  const history = []
+export function createRuntimeHistory() {
+  return { seenNames: {}, tips: {}, hadState: false, hadCatalog: false }
+}
+
+export function advanceRuntimeHistory(previous, { sections = [], notice, snapshot = false, catalog = false,
+  index, contextStep, lastSuccessfulRunIndex, resetSuccess = false }) {
+  let next = previous
+  const revise = () => {
+    if (next === previous) next = { ...previous, tips: { ...previous.tips }, seenNames: { ...previous.seenNames } }
+  }
+  if (resetSuccess) {
+    revise()
+    for (const [id, tip] of Object.entries(next.tips)) next.tips[id] = { ...tip, unresolved: 0 }
+    for (const [name, deliveredIndex] of Object.entries(next.seenNames)) {
+      const identity = recoveryTipIdentity(name)
+      if (deliveredIndex > (lastSuccessfulRunIndex ?? -1)) next.tips[identity.id].unresolved += 1
+    }
+  }
+  const hadState = snapshot || sections.some(section => PTC_STATE_NAMES.includes(section.name))
+  if ((hadState && !next.hadState) || (catalog && !next.hadCatalog)) {
+    revise()
+    next.hadState ||= hadState
+    next.hadCatalog ||= catalog
+  }
+  for (const name of [...sections.map(section => section.name), ...(notice === undefined ? [] : [notice])]) {
+    const identity = recoveryTipIdentity(name)
+    if (identity === undefined || Object.hasOwn(next.seenNames, name)) continue
+    revise()
+    next.seenNames[name] = index
+    const earlier = next.tips[identity.id]
+    next.tips[identity.id] = {
+      highestOrdinal: Math.max(earlier?.highestOrdinal ?? 0, identity.ordinal),
+      contextStep,
+      unresolved: (earlier?.unresolved ?? 0) + (index > (lastSuccessfulRunIndex ?? -1) ? 1 : 0),
+    }
+  }
+  return next
+}
+
+export function runtimeHistoryForView(view) {
+  if (view.runtimeHistory !== undefined) return view.runtimeHistory
+  let history = createRuntimeHistory()
+  history.hadState = view.ptcMessages?.some(record => record.form === 'snapshot') === true
+  history.hadCatalog = view.ptcMessages?.some(record => record.form === 'catalog') === true
   const snapshots = [
-    ...view.systemPromptSnapshots,
+    ...(view.systemPromptSnapshots ?? []),
     ...(view.ptcMessages ?? []).filter(record => record.form === 'notice').map(record => ({
       ...record, sections: [{ name: record.name, text: record.text }],
     })),
   ].sort((left, right) => left.index - right.index)
   for (const snapshot of snapshots) {
-    const next = new Map(snapshot.sections.map(section => [section.name, section.text]))
-    for (const [name] of next) {
-      if (active.has(name) || seen.has(name)) continue
-      const identity = recoveryTipIdentity(name)
-      if (identity === undefined) continue
-      seen.add(name)
-      history.push({ ...identity, index: snapshot.index, contextStep: snapshot.contextStep })
-    }
-    active.clear()
-    for (const entry of next) active.set(...entry)
+    history = advanceRuntimeHistory(history, { ...snapshot, lastSuccessfulRunIndex: view.lastSuccessfulRunIndex })
   }
   return history
 }
@@ -79,14 +110,12 @@ export function latestRecoveryTip(view, config) {
   if (candidate === undefined) return undefined
   // Cooldown, escalation, and ordinal are per trigger kind: one kind's tip must
   // not suppress a different kind.
-  const matching = tipHistory(view).filter(item => item.id === candidate.id)
-  const lastTip = matching.at(-1)
+  const lastTip = runtimeHistoryForView(view).tips[candidate.id]
   if (lastTip !== undefined && view.contextStep - lastTip.contextStep < config.cooldownMessages) return undefined
-  const unresolved = matching.filter(item => item.index > (view.lastSuccessfulRunIndex ?? -1))
-  const ordinal = matching.reduce((highest, item) => Math.max(highest, item.ordinal), 0) + 1
+  const ordinal = (lastTip?.highestOrdinal ?? 0) + 1
   if (!Number.isSafeInteger(ordinal)) return undefined
   return {
     name: `${TIP_CONTEXT_PREFIX}${candidate.id}/${ordinal}`,
-    text: renderTip(candidate.id, unresolved.length >= config.escalationFailures, candidate),
+    text: renderTip(candidate.id, (lastTip?.unresolved ?? 0) >= config.escalationFailures, candidate),
   }
 }

package/internal/rejected-cell-editor.js

@@ -252,29 +252,15 @@ 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: 'Edit the most recent eligible cell captured at dispatch and run the complete corrected cell. A successful edit becomes the next target. This reruns the entire 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.',
     parameters: {
       type: 'object',
-      oneOf: [
-        editRunCodeParameterBranch('edits', {
+      additionalProperties: false,
+      properties: {
+        edits: {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.exactEdits,
           description: 'Atomic exact replacements, all resolved against the original target cell.',
           items: {
@@ -285,8 +271,8 @@ export function editRunCodeSchema() {
             },
             required: ['old_string', 'new_string'],
           },
-        }),
-        editRunCodeParameterBranch('regex_edits', {
+        },
+        regex_edits: {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
           description: 'Atomic regular-expression replacements, all matched against the original target cell with JavaScript pattern and replacement semantics; each replacement is a JavaScript template (see replacement).',
           items: {
@@ -299,8 +285,12 @@ 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.',
+        },
+      },
     },
   }
 }