dsh-ptc-plus 0.4.8 → 0.5.0

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

@@ -1,34 +1,66 @@
-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/'
+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.',
 })
 
 // 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
 }
@@ -62,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.' : ''}`
@@ -79,14 +111,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

@@ -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.',
         },
       },

package/internal/repl-observation-interest.js

@@ -12,6 +12,11 @@ export function createReplObservationInterest(ctx, initiallyEnabled, observe = a
     for (const watcher of [...watchers]) watcher.release()
     for (const controller of inspections) controller.abort()
   }
+  const releaseEvents = typeof ctx.on === 'function' ? ctx.effect(() => ctx.on('session/event', session => {
+    for (const watcher of [...watchers]) {
+      if (watcher.sessionId === session.id) watcher.changed()
+    }
+  }), 'ptc-plus: model source observation changes') : undefined
   const handler = async (endpoint, payload, signal) => {
     if (!enabled || !['watch', 'observe'].includes(endpoint) || typeof payload?.sessionId !== 'string'
       || payload.sessionId.length === 0 || payload.sessionId.length > 256
@@ -32,11 +37,13 @@ export function createReplObservationInterest(ctx, initiallyEnabled, observe = a
       }
     }
     return new Promise(resolve => {
-      const watcher = { sessionId: payload.sessionId, release() {
+      const finish = value => {
         signal.removeEventListener('abort', watcher.release)
         watchers.delete(watcher)
-        resolve({ ok: true, value: null })
-      } }
+        resolve({ ok: true, value })
+      }
+      const watcher = { sessionId: payload.sessionId,
+        release: () => finish(null), changed: () => finish({ changed: true }) }
       watchers.add(watcher)
       signal.addEventListener('abort', watcher.release, { once: true })
       if (signal.aborted) watcher.release()
@@ -62,6 +69,7 @@ export function createReplObservationInterest(ctx, initiallyEnabled, observe = a
     async dispose() {
       enabled = false
       clear()
+      await releaseEvents?.()
       for (const release of [...registrations]) await release()
       if (typeof injection === 'function') await injection()
       else await injection?.dispose?.()

package/internal/rpc-contract.js

@@ -17,6 +17,7 @@ const resultSchema = Schema.union([
 export const RPC_CONTRACTS = Object.freeze({
   bindings: Object.freeze({ service: 'ptcPlusBindings' }),
   repl: Object.freeze({ service: 'ptcPlusRepl' }),
+  capabilities: Object.freeze({ service: 'ptcPlusCapabilities' }),
 })
 
 export function rpcDescriptor({ service }) {