dsh-ptc-plus 0.4.10 → 0.5.1

package/internal/kernel-worker.js

@@ -8,13 +8,13 @@ import { USER_BINDING_TRANSFORM, LEGACY_USER_BINDING_TRANSFORM } from './module-
 import { isAbsolute, resolve } from 'node:path'
 import repl from 'node:repl'
 import { PassThrough, Writable } from 'node:stream'
-import { pathToFileURL } from 'node:url'
+import { pathToFileURL } from './module-runtime-platform.js'
 import { MessageChannel, parentPort, workerData } from 'node:worker_threads'
 import { synchronizeBuiltinEsmExports } from './builtin-esm-sync.js'
 import { createPrivateAsyncLocalStorage } from './async-local-storage-intrinsics.js'
 import { createExceptionOriginScope, errorDetails, messageOf, programBindingError } from './failure-reporting.js'
 import { DURABLE_IMPORTS, FORBIDDEN_IMPORTS } from './module-policy.js'
-import { decodeValue, encodeValue } from './value-wire.js'
+import { decodeValue, encodeValue, encodeValueAtBoundary, valueEncodingFailure } from './value-wire.js'
 import { LEGACY_USER_BINDINGS_REUSE_POLICY, LIVE_USER_BINDINGS_SHADOW_POLICY, normalizeUserBindingNames } from './session-journal-schema.js'
 import { installWorkerCwdVirtualization } from './worker-cwd-virtualization.js'
 import {
@@ -114,6 +114,15 @@ const output = new PassThrough()
 output.resume()
 const evaluationScope = createPrivateAsyncLocalStorage()
 const sessionCwd = typeof workerData?.cwd === 'string' ? workerData.cwd : undefined
+// The module source base is fixed when a cell starts; the operation directory
+// follows the Session's working directory while the cell runs, so a confirmed
+// `tools.working_directory` change rebases the rest of the cell exactly as the
+// Host tools, which resolve at call time, already do.
+let executionCwd = sessionCwd
+let cellOperationCwd = sessionCwd
+const resolveModuleFilename = resolve
+const isAbsoluteDirectory = isAbsolute
+const nativeCreateRequire = createRequire
 if (sessionCwd !== undefined && !isAbsolute(sessionCwd)) {
   throw new Error(`ptc-plus session cwd must be absolute, got ${jsonStringify(sessionCwd)}`)
 }
@@ -145,7 +154,7 @@ const completionObserver = createCellCompletionObserver(runInWorkerReplRealm('Fu
 let replModuleRealm
 const statefulRoots = createStatefulRootRuntime({
   refresh: name => refreshLegacyPublication(name),
-  importModule: (source, options) => managedModuleImport(replParent, source, options, replModuleRealm),
+  importModule: moduleImportFor(),
   errors: runInWorkerReplRealm('({ ReferenceError, TypeError })'),
   dynamicIntrinsics: runInWorkerReplRealm('({intrinsicEval:eval,realmFunction:Function,globalObject:globalThis,errors:{ReferenceError,TypeError,SyntaxError},reflect:Reflect,object:Object})'),
   readAmbient: name => runInWorkerReplRealm(name),
@@ -169,7 +178,7 @@ const statefulRoots = createStatefulRootRuntime({
 const nativeRootDynamic = createNativeRootDynamic({
   logicalReference: (name, writable) => statefulRoots.legacyReference(name, writable),
   intrinsics: runInWorkerReplRealm('({intrinsicEval:eval,realmFunction:Function,globalObject:globalThis,errors:{ReferenceError,TypeError,SyntaxError},reflect:Reflect,object:Object})'),
-  importModule: (source, options) => managedModuleImport(replParent, source, options, replModuleRealm),
+  importModule: moduleImportFor(),
   read: name => runInWorkerReplRealm(name),
   typeOf: name => runInWorkerReplRealm(`typeof ${name}`),
   write(name, value, strict) {
@@ -181,11 +190,11 @@ const nativeRootDynamic = createNativeRootDynamic({
 let valueObserver
 const REPL_IMPORT_CANARY = 'data:text/javascript,export default 1'
 let replParent
-const sessionReplParent = sessionCwd === undefined ? undefined : pathToFileURL(resolve(sessionCwd, 'repl')).href
-const staticAdapterParents = new Set()
+const cellModuleParent = () => executionCwd === undefined ? replParent : pathToFileURL(resolveModuleFilename(executionCwd, 'repl')).href
+const staticAdapterParents = new Map()
 const userBindingModuleParents = new Map()
 const userModuleCompilation = createUserModuleCompilationHooks({
-  transformForParent: parent => (parent === replParent || parent === sessionReplParent) && activeExecution !== undefined
+  transformForParent: parent => (parent === replParent || parent === cellModuleParent()) && activeExecution !== undefined
     ? activeExecution.moduleTransform : undefined,
 })
 registerHooks({
@@ -193,10 +202,11 @@ registerHooks({
     if (specifier === REPL_IMPORT_CANARY && replParent === undefined) replParent = context.parentURL
     return userModuleCompilation.resolve(specifier, context, (source, resolvedContext) => {
       const userBindingParent = mapGet(userBindingModuleParents, resolvedContext.parentURL)
+      const adapterParent = mapGet(staticAdapterParents, resolvedContext.parentURL)
       return nextResolve(source, userBindingParent !== undefined
         ? { ...resolvedContext, parentURL: userBindingParent }
-        : resolvedContext.parentURL === replParent || setHas(staticAdapterParents, resolvedContext.parentURL)
-          ? { ...resolvedContext, parentURL: sessionReplParent ?? replParent }
+        : adapterParent !== undefined
+          ? { ...resolvedContext, parentURL: adapterParent }
           : resolvedContext)
     })
   },
@@ -356,23 +366,53 @@ installWorkerCwdVirtualization(sessionCwd, originalRequire, reason => {
     return
   }
   markVolatile(reason)
-})
+}, () => cellOperationCwd)
 synchronizeBuiltinEsmExports()
-const providedRequire = sessionReplParent === undefined ? originalRequire : createRequire(sessionReplParent)
-function selectProvidedRequire(args) {
-  const specifier = args[0]
-  if (setHas(FORBIDDEN_IMPORTS, specifier)) throw new Error(`module ${specifier} is forbidden because it exposes kernel control`)
-  if (!setHas(DURABLE_IMPORTS, specifier)) markVolatile(`require(${jsonStringify(specifier)})`)
-  return managedRequire(activeExecution?.languageSemantics === 'legacy-v1' ? replParent : sessionReplParent ?? replParent,
-    activeExecution?.languageSemantics === 'legacy-v1' ? originalRequire : providedRequire)
+function recordCellModuleResolution(transform) {
+  // An escaped loader retains its source generation. Native resolution still
+  // selects the URL; the module compiler owns adaptation before its first load.
+  return (parent, source, attributes, resolution) => userModuleCompilation.recordResolution(
+    parent, source, attributes, resolution, transform)
 }
-defineWorkerRealmProperty(WORKER_REALM_MUTATION.STABLE, 'cell module metadata', context, 'require', {
-  configurable: true,
-  value: new Proxy(providedRequire, {
-    apply: (_, receiver, args) => privateReflect.apply(selectProvidedRequire(args), receiver, args),
-    construct: (_, args, newTarget) => privateReflect.construct(selectProvidedRequire(args), args, newTarget),
-  }),
-})
+
+function moduleImportFor(parent, recordResolution) {
+  return (source, options) => managedModuleImport(parent ?? replParent, source, options, replModuleRealm, recordResolution)
+}
+
+function cellImportModuleFor(parent, transform) {
+  return moduleImportFor(parent, recordCellModuleResolution(transform))
+}
+
+function providedRequireFor(parent, legacy, transform, explicitCwd) {
+  const recordResolution = recordCellModuleResolution(transform)
+  const nativeRequire = legacy || !explicitCwd ? originalRequire : nativeCreateRequire(parent)
+  const select = args => {
+    const specifier = args[0]
+    if (setHas(FORBIDDEN_IMPORTS, specifier)) throw new Error(`module ${specifier} is forbidden because it exposes kernel control`)
+    if (!setHas(DURABLE_IMPORTS, specifier)) markVolatile(`require(${jsonStringify(specifier)})`)
+    return managedRequire(legacy ? replParent : parent ?? replParent, legacy ? originalRequire : nativeRequire, recordResolution)
+  }
+  return new Proxy(nativeRequire, {
+    apply: (_, receiver, args) => privateReflect.apply(select(args), receiver, args),
+    construct: (_, args, newTarget) => privateReflect.construct(select(args), args, newTarget),
+  })
+}
+let providedRequireParent = cellModuleParent()
+let providedRequireLegacy = false
+let providedRequireTransform
+let providedRequireExplicitCwd
+function installProvidedRequire(parent, legacy = false, transform, explicitCwd = executionCwd !== undefined) {
+  defineWorkerRealmProperty(WORKER_REALM_MUTATION.STABLE, 'cell module metadata', context, 'require', {
+    configurable: true,
+    value: providedRequireFor(parent, legacy, transform, explicitCwd),
+  })
+  providedRequireParent = parent
+  providedRequireLegacy = legacy
+  providedRequireTransform = transform
+  providedRequireExplicitCwd = explicitCwd
+}
+installProvidedRequire(providedRequireParent)
+
 function evaluate(program, completionSignal, asyncCompletion = false) {
   return new ControlPromise((resolve, reject) => {
     let settled = false
@@ -483,14 +523,16 @@ function staticAdapterSource(load) {
 }
 
 async function loadStaticModule(load) {
+  const parent = cellModuleParent()
+  const importModule = cellImportModuleFor(parent, activeExecution?.moduleTransform)
   if (load.operation === 'native-dynamic') return { namespace: nativeRootDynamic.environment(load.callableSources,
     load.awaitRoot === true, filterArray(load.logicalRoots, name => statefulRoots.has(name)
-      && rootBindingStorage(name, moduleRuntimeIntrinsics.includes(load.nativeLexicals, name)) !== 'lexical'), load.writableRoots) }
+      && rootBindingStorage(name, moduleRuntimeIntrinsics.includes(load.nativeLexicals, name)) !== 'lexical'), load.writableRoots, importModule) }
   if (load.operation === 'import') {
-    return { namespace: (source, options) => managedModuleImport(replParent, source, options, replModuleRealm) }
+    return { namespace: importModule }
   }
   const adapter = `data:text/javascript,${encodeURIComponent(staticAdapterSource(load))}#${++nextStaticAdapterId}`
-  setAdd(staticAdapterParents, adapter)
+  mapSet(staticAdapterParents, adapter, cellModuleParent())
   userModuleCompilation.mark(adapter, { compiled: true,
     transform: activeExecution?.moduleTransform })
   try {
@@ -499,7 +541,7 @@ async function loadStaticModule(load) {
     const namespace = readModuleImport(adapter, load.source, null, () => completion.value.namespace, load.options?.with)
     return { namespace }
   } finally {
-    setDelete(staticAdapterParents, adapter)
+    mapDelete(staticAdapterParents, adapter)
   }
 }
 
@@ -510,6 +552,18 @@ function hasExecutionLease(runId) {
 // BoundError is the error class installed by this cell's wrapper, not a name
 // looked up later: the cell can replace or delete the context binding while a
 // call is pending, and the call must keep its submitted error identity.
+// A confirmed Session directory change rebases the rest of the cell: Host tools
+// resolve against the session service at call time, and this worker's relative
+// operations now resolve against the same directory. The cell's module source
+// base (imports, import.meta, provided require) stays fixed at its start.
+function adoptConfirmedCellDirectory(call, value) {
+  if (call.global !== 'tools' || call.member !== 'working_directory') return
+  if (activeRun !== call.runId) return
+  const cwd = value?.cwd
+  if (typeof cwd !== 'string' || cwd.length === 0 || !isAbsoluteDirectory(cwd)) return
+  cellOperationCwd = cwd
+}
+
 function callHost(runId, global, member, args, BoundError) {
   if (!hasExecutionLease(runId)) {
     return promiseReject(programBindingError('lease', 'PTC execution lease expired'))
@@ -528,11 +582,11 @@ function callHost(runId, global, member, args, BoundError) {
   const settled = new ControlPromise(resolve => {
     moduleRuntimeIntrinsics.Reflect.apply(moduleRuntimeIntrinsics.promiseThen, result, [resolve, resolve])
   })
-  mapSet(pending, id, { ...settle, runId, valueLimits, settled, member, BoundError })
+  mapSet(pending, id, { ...settle, runId, valueLimits, settled, global, member, BoundError })
   try {
     channel.postMessage({
       type: 'call', runId, id, global, member,
-      args: encodeValue(args, valueLimits),
+      args: encodeValueAtBoundary(args, valueLimits, 'parameter'),
     })
   } catch (error) {
     mapDelete(pending, id)
@@ -1213,7 +1267,7 @@ async function closeExecution(execution) {
 }
 
 function failureOutcome(error, phase, program) {
-  if (phase === 'encode') return { invalidOutput: messageOf(error) }
+  if (phase === 'encode') return { invalidOutput: messageOf(error), valueFailure: valueEncodingFailure(error) }
   const failure = error instanceof StaticImportFailure ? error.error : error
   // The V8 frame is reported in the executed text; validate it there so an
   // out-of-range frame is an explicit absence instead of a mapped position.
@@ -1225,6 +1279,7 @@ function failureOutcome(error, phase, program) {
   return {
     error: detail.message,
     errorName: detail.name,
+    valueFailure: valueEncodingFailure(failure),
     ...(detail.toolName === undefined ? {} : { toolName: detail.toolName }),
     ...(error instanceof StaticImportFailure ? { moduleLoadFailed: true } : {}),
     ...(position === undefined ? {} : { position }),
@@ -1306,6 +1361,18 @@ async function sendCompletion(message, execution, userBindings, committedRedecla
 
 async function runCell(message) {
   if (activeExecution !== undefined) throw new Error('kernel received overlapping cells')
+  if (message.cwd !== undefined && (typeof message.cwd !== 'string' || !isAbsoluteDirectory(message.cwd))) {
+    throw new Error('ptc-plus cell cwd must be absolute')
+  }
+  executionCwd = message.cwd ?? sessionCwd
+  cellOperationCwd = executionCwd
+  const parent = cellModuleParent()
+  const legacyRequire = message.languageSemantics === 'legacy-v1'
+  const explicitCwd = executionCwd !== undefined
+  if (parent !== providedRequireParent || legacyRequire !== providedRequireLegacy || message.moduleTransform !== providedRequireTransform
+    || explicitCwd !== providedRequireExplicitCwd) {
+    installProvidedRequire(parent, legacyRequire, message.moduleTransform, explicitCwd)
+  }
   await writeOutputFence(nativeStdoutWrite, outputFenceMarker(message.outputFence, 'stdout', 'start'))
   await writeOutputFence(nativeStderrWrite, outputFenceMarker(message.outputFence, 'stderr', 'start'))
   await new ControlPromise(resolve => {
@@ -1368,6 +1435,7 @@ async function runCell(message) {
             context, message.rootRuntimeName, {
             configurable: true,
             value: statefulRoots.begin({ ...message.rootBindings,
+              importModule: cellImportModuleFor(parent, message.moduleTransform),
               legacyLexicals,
               legacyWritable,
               legacyObjects: filterArray(legacyWritable, name => mapGet(legacyStorage, name) !== 'lexical'),
@@ -1486,7 +1554,11 @@ channel.on('message', (message) => {
     if (call === undefined || call.runId !== message.runId) return
     mapDelete(pending, message.id)
     try {
-      if (message.ok) call.resolve(decodeValue(message.value, call.valueLimits))
+      if (message.ok) {
+        const value = decodeValue(message.value, call.valueLimits)
+        adoptConfirmedCellDirectory(call, value)
+        call.resolve(value)
+      }
       else if (call.BoundError === undefined) {
         const error = new Error(message.error)
         if (message.cause !== undefined) error.ptcCause = message.cause

package/internal/native-root-dynamic.js

@@ -6,26 +6,25 @@ const { Map, Set, mapGet, mapSet, mapHas, mapDelete, setHas, setAdd, appendArray
 /** Native storage and catalog-proved logical roots share a captured legacy view. */
 export function createNativeRootDynamic({ intrinsics, importModule, read, write, typeOf, remove, logicalReference }) {
   const interfaceOwner = {}
-  const runtime = createDynamicEnvironmentRuntime({ ...intrinsics, importModule, interfaceOwner }).installIntrinsics()
   const descriptor = name => ({ kind: 'var', get: () => read(name),
     set: (value, strict) => write(name, value, strict), delete: () => remove(name), typeof: () => typeOf(name) })
-  const environment = runtime.environment({
-    ambient(name, strict) {
-      return runtime.reference(name, descriptor(name), undefined, strict)
-    },
-    declareVars: runtime.declareGlobals,
-    createVar: descriptor,
-  })
-  runtime.setRootEnvironment(() => environment)
   return {
-    environment(callableSources, awaitRoot = false, logicalRoots = [], writableRoots = []) {
+    environment(callableSources, awaitRoot = false, logicalRoots = [], writableRoots = [], cellImportModule = importModule) {
       if (logicalRoots.length === 0) {
-        runtime.registerSources(callableSources)
-        return awaitRoot ? environment.awaitActivation() : environment
+        const cellRuntime = createDynamicEnvironmentRuntime({ ...intrinsics,
+          importModule: cellImportModule, interfaceOwner }).installIntrinsics()
+        const captured = cellRuntime.environment({
+          ambient: (name, strict) => cellRuntime.reference(name, descriptor(name), undefined, strict),
+          declareVars: cellRuntime.declareGlobals,
+          createVar: descriptor,
+        })
+        cellRuntime.setRootEnvironment(() => captured)
+        cellRuntime.registerSources(callableSources)
+        return awaitRoot ? captured.awaitActivation() : captured
       }
       // Each captured legacy environment keeps its own root view. Installing a
       // later bridge must not change escaped eval/Function calls from old cells.
-      const bridgedRuntime = createDynamicEnvironmentRuntime({ ...intrinsics, importModule, interfaceOwner }).installIntrinsics()
+      const bridgedRuntime = createDynamicEnvironmentRuntime({ ...intrinsics, importModule: cellImportModule, interfaceOwner }).installIntrinsics()
       const writable = new Set()
       for (let index = 0; index < writableRoots.length; index++) setAdd(writable, writableRoots[index])
       const bindings = new Map(), varFrame = new Map(), roots = new Map()

package/internal/official-repl-priority.js

@@ -0,0 +1,51 @@
+/**
+ * Official persistent-REPL priority.
+ *
+ * The official `persistent-in-memory` execution mode is a live provider
+ * capability, not a release fact: a provider reports `programFormat` `'repl'`
+ * exactly when it retains a REPL per state owner. While the user selects the
+ * official REPL priority and that provider is live, the plugin yields PTC
+ * session execution to the official implementation and installs no session
+ * runtime: `run_code`, its descriptors and its guidance stay official. The
+ * decision is re-evaluated on every configuration change and host source
+ * change, so either side can take over without restarting the host.
+ */
+
+/**
+ * Decide whether this configuration yields PTC session execution to the
+ * official provider.
+ * @param {object} config - resolved plugin configuration.
+ * @param {object} provider - the live provider surface registered for the seam.
+ * @returns {boolean} true when the official persistent REPL owns execution.
+ */
+export function defersToOfficialRepl(config, provider) {
+  if (config?.officialReplPriority !== true) return false
+  try {
+    return provider?.programFormat === 'repl'
+  } catch {
+    // An unreadable capability descriptor cannot prove official ownership;
+    // the plugin keeps its execution responsibility instead of guessing.
+    return false
+  }
+}
+
+/**
+ * Runtime record for an attachment that yields execution to the official
+ * provider. It owns no execution resources: the official provider releases
+ * anything it retained through its own lifecycle, and the plugin's settings,
+ * storage and UI owners remain available so the user can switch back.
+ */
+export function createDeferredRuntime() {
+  return Object.freeze({
+    cancelCordisActivation() {
+      // No Cordis companion is installed while execution is deferred.
+    },
+    contextsForRequest: () => [],
+    async reconfigure() {
+      // This attachment has no owners to reconfigure.
+    },
+    async dispose() {
+      // Nothing is owned here; disposal returns immediately.
+    },
+  })
+}

package/internal/program-bindings.js

@@ -1,5 +1,19 @@
 /** Deterministic capability metadata derived from the current DSH tool view. */
 import { record, text } from './record-utils.js'
+import { createHash } from 'node:crypto'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
+
+/** Derive SDK contracts from the public, scope-qualified tool registry. */
+export function toolSdkSchemas(tools, scope) {
+  return tools.schemas(scope).filter(schema => schema.name !== 'run_code').map(schema => {
+    const definition = tools.get(schema.name, scope)
+    const output = snapshotJsonValue(definition?.output?.schema)
+    if (output === undefined) {
+      throw new TypeError(`ptc-plus: tool "${schema.name}" output schema must be lossless JSON before SDK projection`)
+    }
+    return { ...schema, output }
+  })
+}
 
 const COMPLETENESS = new Set(['complete', 'bounded', 'incremental', 'open-world', 'unknown'])
 const SOURCE_KINDS = new Set(['authored', 'runtime', 'tests', 'docs'])
@@ -185,3 +199,179 @@ export function capabilityInspect(metadata, symbols = undefined, budget = 50) {
     budget,
   }
 }
+
+const SEARCH_DEFAULT_BYTES = 16_384
+const SEARCH_MIN_BYTES = 512
+const SEARCH_STOP_WORDS = new Set('a an and are as at be by can could do for from how i in is it me of on or please that the this to use using with would you 我 帮 帮我 请 的 了 和 与 在 如何 怎么 可以'.split(' '))
+const SEARCH_SEGMENTER = new Intl.Segmenter('zh', { granularity: 'word' })
+
+function taskTerms(value) {
+  const separated = value.normalize('NFKC')
+    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1 $2')
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1 $2')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+  return [...new Set([...SEARCH_SEGMENTER.segment(separated)]
+    .filter(part => part.isWordLike && !SEARCH_STOP_WORDS.has(part.segment))
+    .map(part => part.segment))]
+}
+
+function searchKeywords(value) {
+  if (value === undefined) return ''
+  if (typeof value === 'string') return value
+  if (Array.isArray(value) && value.every(item => typeof item === 'string')) return value.join(' ')
+  throw new TypeError('ptc-plus: capability search keywords must be a string or string array')
+}
+
+// Search budgets measure JSON, so non-JSON metadata cannot be silently converted or dropped.
+function searchJson(value) {
+  const ancestors = new Set()
+  const visit = (item) => {
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return
+    if (typeof item === 'number' && Number.isFinite(item)) return
+    if (typeof item !== 'object') throw new TypeError('ptc-plus: capability search metadata must be lossless JSON data')
+    if (ancestors.has(item)) throw new TypeError('ptc-plus: capability search metadata must be lossless JSON data')
+    const prototype = Object.getPrototypeOf(item)
+    if (prototype !== (Array.isArray(item) ? Array.prototype : Object.prototype) && prototype !== null) {
+      throw new TypeError('ptc-plus: capability search metadata must be lossless JSON data')
+    }
+    ancestors.add(item)
+    for (const key of Reflect.ownKeys(item)) {
+      if (Array.isArray(item) && key === 'length') continue
+      const descriptor = Object.getOwnPropertyDescriptor(item, key)
+      if (typeof key !== 'string' || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+        throw new TypeError('ptc-plus: capability search metadata must be lossless JSON data')
+      }
+      visit(descriptor.value)
+    }
+    if (Array.isArray(item) && (Object.keys(item).length !== item.length
+      || Object.keys(item).some(key => !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= item.length))) {
+      throw new TypeError('ptc-plus: capability search metadata must be lossless JSON data')
+    }
+    ancestors.delete(item)
+  }
+  visit(value)
+  return JSON.stringify(value, (_key, item) => item !== null && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item)
+}
+
+function searchDigest(value) {
+  return createHash('sha256').update(value).digest('base64url')
+}
+
+function measuredSearchPage(value) {
+  value.usedBytes = 0
+  let bytes = Buffer.byteLength(JSON.stringify(value), 'utf8')
+  while (value.usedBytes !== bytes) {
+    value.usedBytes = bytes
+    bytes = Buffer.byteLength(JSON.stringify(value), 'utf8')
+  }
+  return value
+}
+
+/** Derive one request-local lexical index from owner metadata; never owns invocation. */
+export function createCapabilitySearcher(metadata) {
+  const seen = new Set()
+  const snapshot = JSON.parse(searchJson(metadata))
+  const catalog = metadataEntries(snapshot).flatMap((entry) => {
+    const { members, ...owner } = entry
+    return members.map((member) => {
+      const symbol = `${entry.namespace}.${member.name}`
+      if (seen.has(symbol)) throw new TypeError(`ptc-plus: capability search has ambiguous symbol ${symbol}`)
+      seen.add(symbol)
+      const value = metadataSnapshot(JSON.parse(searchJson({ symbol, owner, contract: member })), 'capability search metadata')
+      const names = new Set(taskTerms(symbol))
+      const terms = new Set(taskTerms([
+        symbol, member.description ?? '', owner.description ?? '',
+        searchKeywords(member.keywords), searchKeywords(owner.keywords),
+      ].join(' ')))
+      return { value, names, terms }
+    })
+  }).sort((left, right) => left.value.symbol < right.value.symbol ? -1 : left.value.symbol > right.value.symbol ? 1 : 0)
+  const catalogId = searchDigest(JSON.stringify(catalog.map(item => item.value)))
+
+  return (args) => {
+    const params = record(args, 'capability search arguments')
+    const allowed = new Set(['query', 'budgetBytes', 'limit', 'cursor'])
+    if (Reflect.ownKeys(params).some(key => typeof key !== 'string' || !allowed.has(key)
+      || !Object.prototype.propertyIsEnumerable.call(params, key))) {
+      throw new TypeError('ptc-plus: capability search has an unknown argument')
+    }
+    const query = text(params.query, 'capability search query').normalize('NFKC').trim().toLowerCase()
+    const queryTerms = taskTerms(params.query)
+    const budgetBytes = params.budgetBytes === undefined ? SEARCH_DEFAULT_BYTES : params.budgetBytes
+    const limit = params.limit === undefined ? 10 : params.limit
+    if (!Number.isSafeInteger(budgetBytes) || budgetBytes < SEARCH_MIN_BYTES) {
+      throw new TypeError(`ptc-plus: capability search budgetBytes must be an integer of at least ${SEARCH_MIN_BYTES}`)
+    }
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('ptc-plus: capability search limit must be a positive integer')
+    const queryId = searchDigest(JSON.stringify({ query, terms: queryTerms }))
+    const ranked = catalog.flatMap((candidate) => {
+      const { symbol, owner, contract } = candidate.value
+      const coverage = queryTerms.filter(term => candidate.terms.has(term)).length
+      const nameCoverage = queryTerms.filter(term => candidate.names.has(term)).length
+      const rank = symbol.normalize('NFKC').toLowerCase() === query ? 0
+        : owner.namespace.normalize('NFKC').toLowerCase() === query ? 1
+        : contract.name.normalize('NFKC').toLowerCase() === query ? 2
+        : coverage === 0 ? undefined
+        : nameCoverage === queryTerms.length ? 3
+        : coverage === queryTerms.length ? 4 : 5
+      return rank === undefined ? [] : [{ ...candidate, rank, coverage, nameCoverage }]
+    }).sort((left, right) => left.rank - right.rank || right.coverage - left.coverage
+      || right.nameCoverage - left.nameCoverage
+      || (left.value.symbol < right.value.symbol ? -1 : left.value.symbol > right.value.symbol ? 1 : 0))
+
+    let offset = 0
+    if (params.cursor !== undefined) {
+      if (typeof params.cursor !== 'string' || !/^[A-Za-z0-9_-]+$/.test(params.cursor)) {
+        throw new TypeError('ptc-plus: capability search cursor is invalid')
+      }
+      let cursor
+      try { cursor = JSON.parse(Buffer.from(params.cursor, 'base64url').toString('utf8')) } catch {
+        throw new TypeError('ptc-plus: capability search cursor is invalid')
+      }
+      if (cursor?.version !== 1 || cursor.catalog !== catalogId || cursor.query !== queryId
+        || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset >= ranked.length
+        || Buffer.from(JSON.stringify(cursor)).toString('base64url') !== params.cursor) {
+        throw new TypeError('ptc-plus: capability search cursor is invalid or catalog/query changed')
+      }
+      offset = cursor.offset
+    }
+
+    const page = (matches, oversized, next) => measuredSearchPage({
+      matches, oversized, total: ranked.length, remaining: ranked.length - next,
+      cursor: next < ranked.length ? Buffer.from(JSON.stringify({
+        version: 1, catalog: catalogId, query: queryId, offset: next,
+      })).toString('base64url') : null,
+      budgetBytes, unit: 'utf8-json-bytes', usedBytes: 0,
+    })
+    let result = page([], [], offset)
+    for (let next = offset; next < ranked.length && next - offset < limit; next += 1) {
+      const candidate = ranked[next].value
+      const expanded = page([...result.matches, candidate], result.oversized, next + 1)
+      if (expanded.usedBytes <= budgetBytes) {
+        result = expanded
+        continue
+      }
+      const alone = page([candidate], [], next + 1)
+      if (alone.usedBytes <= budgetBytes) break
+      const omitted = {
+        symbol: candidate.symbol, requiredBytes: alone.usedBytes,
+        inspect: { symbols: [candidate.symbol], budget: 1 },
+      }
+      const bounded = page(result.matches, [...result.oversized, omitted], next + 1)
+      if (bounded.usedBytes > budgetBytes) {
+        if (next === offset) throw new RangeError(`ptc-plus: capability search needs at least ${bounded.usedBytes} budgetBytes for its continuation and inspect reference`)
+        break
+      }
+      result = bounded
+    }
+    if (result.usedBytes > budgetBytes) throw new RangeError(`ptc-plus: capability search needs at least ${result.usedBytes} budgetBytes for its continuation`)
+    return result
+  }
+}
+
+/** Return whole owner contracts within a UTF-8 JSON byte budget, including the envelope. */
+export function capabilitySearch(metadata, args) {
+  return createCapabilitySearcher(metadata)(args)
+}

package/internal/recovery-tips.js

@@ -2,6 +2,7 @@ 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/'
+const PLATFORM_FACTS = '`return { platform: process.platform, arch: process.arch, node: process.version, cwd: process.cwd(), execPath: process.execPath }`'
 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.',
@@ -93,8 +94,8 @@ function tipCandidate(view) {
 function renderTip(id, detailed, candidate = {}) {
   if (id === 'platform-command-failure') {
     return detailed
-      ? `${TIP_PREFIXES[id]} Re-check the active execution world and the actual executable before retrying. 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.`
-      : `${TIP_PREFIXES[id]} Inspect the executable or path in the current execution world and choose direct argv or a shell only when required; do not assume Windows, WSL, POSIX, or one shell.`
+      ? `${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.`
   }
   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.' : ''}`

package/internal/rejected-cell-editor.js

@@ -255,39 +255,39 @@ function assemble(source, replacements) {
 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.',
+    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.',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
         edits: {
-          type: 'array', minItems: 1, maxItems: EDIT_LIMITS.exactEdits,
+          type: 'array',
           description: 'Atomic exact replacements, all resolved against the original target cell.',
           items: {
             type: 'object', additionalProperties: false,
             properties: {
-              old_string: { type: 'string', minLength: 1, description: 'Exact text in the target cell. It must occur exactly once.' },
+              old_string: { type: 'string', description: 'Nonempty exact text in the target cell. It must occur exactly once.' },
               new_string: { type: 'string', description: 'Literal replacement text. Use an empty string to delete the match.' },
             },
             required: ['old_string', 'new_string'],
           },
         },
         regex_edits: {
-          type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
+          type: 'array',
           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: {
             type: 'object', additionalProperties: false,
             properties: {
-              pattern: { type: 'string', minLength: 1, description: 'JavaScript regular-expression source without delimiters or flags (for example \\d+px, not /\\d+px/). Zero-length matches are rejected.' },
-              flags: { type: 'string', pattern: '^(?!.*(.).*\\1)[gimsu]*$', description: 'Unique JavaScript g, i, m, s, or u flags. Global matching is always applied.' },
+              pattern: { type: 'string', description: 'Nonempty JavaScript regular-expression source without delimiters or flags (for example \\d+px, not /\\d+px/). Zero-length matches are rejected.' },
+              flags: { type: 'string', description: 'Unique JavaScript g, i, m, s, or u flags. Global matching is always applied.' },
               replacement: { type: 'string', description: 'JavaScript replacement template. Reference captures as $1, $2, ... or $<name> (for example "<$1>" inserts capture 1); backslash escapes such as \\1 are NOT capture references and stay literal text; write a literal dollar sign as $$.' },
-              expected_matches: { type: 'integer', minimum: 1, maximum: EDIT_LIMITS.regexMatches, description: 'Exact match count required before any replacement is applied.' },
+              expected_matches: { type: 'integer', description: 'Positive exact match count required before any replacement is applied.' },
             },
             required: ['pattern', 'flags', 'replacement', 'expected_matches'],
           },
         },
         [EXPECTED_TARGET_CALL_SEQ]: {
-          type: 'integer', minimum: 0,
+          type: 'integer',
           description: 'Optional target precondition copied from a validated diagnostic. The edit is rejected if the captured cell has another call sequence.',
         },
       },