dsh-ptc-plus 0.4.8 → 0.5.0

package/internal/direct-surface-owner.js

@@ -3,7 +3,6 @@ import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { validateJsonSchemaValue } from '@deepseek-ai/dsh-tools'
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
 import { canonicalizeToolCallStream } from './tool-call-canonicalizer.js'
-import { editRunCodeSchema } from './rejected-cell-editor.js'
 import { sessionRuntimeContexts } from './runtime-contexts.js'
 import { projectProgramSdk } from './sdk-projection.js'
 import { EDIT_RUN_CODE } from './edit-transport-owner.js'
@@ -16,11 +15,12 @@ import {
 } from './run-code-description.js'
 import { userBindingsConfiguredContext } from './user-bindings.js'
 import { BINDING_AUTHORING_SDK } from './user-binding-authoring.js'
+import { executionPolicies } from './binding-update-policy.js'
 
-const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL, reusing earlier top-level bindings. Use `code` for the async-function body and `description` for its short UI summary. Successful image-bearing subtool results are attached after the cell.'
-const RUN_CODE_CODE_DESCRIPTION = 'Code for the next REPL cell, parsed as the body of an async TypeScript function.'
+const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL, reusing earlier top-level bindings. Use `code` for the cell and `description` for its short UI summary. Successful image-bearing subtool results are attached after the cell.'
+const RUN_CODE_CODE_DESCRIPTION = 'Code for the next PTC TypeScript cell, following the selected language conventions.'
 const RUN_CODE_DESCRIPTION_DESCRIPTION = 'Short active-voice summary of what this cell does, 5-10 words (shown in the UI).'
-const CODE_TRANSPORT_INSTRUCTION = '`run_code` and `edit_run_code` are the only tools callable directly. Call every native tool declared by the SDK from inside a program.'
+const CODE_TRANSPORT_INSTRUCTION = '`run_code` is the only tool callable directly. Call `tools.edit_run_code` and other SDK tools from inside a program. An accepted edit runs after the current cell finishes.'
 const PTC_COLLAPSE_SECTION_NAMES = Object.freeze(['tools:ptc-only', 'tools:code-only'])
 const INVALID_TOOL_JSON_FAILURE = Object.freeze({
   code: 'MALFORMED_RESPONSE',
@@ -53,19 +53,20 @@ function adaptRunCodeSchema(tool) {
   }
 }
 
-function capabilitySdk(nativeSdk, userBindingsEnabled) {
-  return `${projectProgramSdk(nativeSdk)}
+function capabilitySdk(nativeSdk, userBindingsEnabled, languageSemantics) {
+  return `${projectProgramSdk(nativeSdk, { languageSemantics })}
 
 ## PTC Plus program capabilities
 
-Discover program APIs without calling them. \`tree()\` lists namespaces and members; \`inspect()\` describes selected \`namespace.member\` symbols. \`find()\` matches case-insensitive symbols or contiguous words, separating CamelCase and punctuation. Use short queries such as \`"read"\`; if none match, shorten the query or check \`tree()\`. Missing metadata is unknown.
+Discover program APIs without calling them. \`search({query})\` retrieves whole indexed API descriptions by English/Chinese words; its UTF-8 JSON byte budget includes the envelope, with a continuation cursor and inspect references for oversized entries. \`tree()\` lists namespaces and members; \`find()\` matches case-insensitive symbols or contiguous words, separating CamelCase and punctuation; \`inspect()\` returns selected \`namespace.member\` symbols with an item-count budget. Missing metadata is unknown.
 
 \`\`\`ts
-declare class CapabilityExplorationError extends Error { readonly operation: "tree" | "find" | "inspect" }
+declare class CapabilityExplorationError extends Error { readonly operation: "tree" | "find" | "inspect" | "search" }
 declare const capabilities: {
   tree(): Promise<Array<{ namespace: string; members: string[] }>>
   find(query: string): Promise<Array<{ symbol: string; description?: string; completeness: string; effect: string; replay: string }>>
   inspect(args?: { symbols?: string[]; budget?: number }): Promise<{ symbols: unknown[]; omitted: number; unknown: string[]; budget: number }>
+  search(args: { query: string; budgetBytes?: number; limit?: number; cursor?: string }): Promise<{ matches: Array<{ symbol: string; owner: unknown; contract: unknown }>; oversized: Array<{ symbol: string; requiredBytes: number; inspect: { symbols: string[]; budget: number } }>; total: number; remaining: number; cursor: string | null; budgetBytes: number; usedBytes: number; unit: "utf8-json-bytes" }>
 }
 \`\`\`${userBindingsEnabled ? `\n${BINDING_AUTHORING_SDK}` : ''}`
 }
@@ -118,16 +119,8 @@ function presentationState(assembly) {
   const collapse = PTC_COLLAPSE_SECTION_NAMES
     .map(name => assembly?.sections?.find(section => section?.name === name))
     .find(section => section !== undefined)
-  if (collapse !== undefined) {
-    const presentation = typeof collapse.text === 'string' && collapse.text.trim().length > 0
-      ? 'ptc'
-      : 'both'
-    return { presentation, ownerProven: true, collapseSectionName: collapse.name }
-  }
-  const presentation = tools.every(tool => tool?.name === RUN_CODE || tool?.name === EDIT_RUN_CODE)
-    ? 'ptc'
-    : 'both'
-  return { presentation, ownerProven: false, collapseSectionName: undefined }
+  return { presentation: 'ptc', ownerProven: collapse !== undefined,
+    collapseSectionName: collapse?.name }
 }
 
 async function* bindCallPolicies(source, policy, calls) {
@@ -464,6 +457,8 @@ export function createDirectSurfaceOwner({
   toolSchemasForAgent,
   userBindingsForAgent = async () => undefined,
   setAgentPresentation = async () => {},
+  sessionLogView,
+  capabilityEnvironment,
 }) {
   // Composition is anchored to Agent identity because DSH selects presentation
   // once per composed agent. Request signals bind the exact assembly to stream
@@ -477,6 +472,7 @@ export function createDirectSurfaceOwner({
   let disposed = false
   let currentCanonicalizeToolCalls = canonicalizeToolCalls
   let currentAutoDescribeRunCode = runtimeConfig.autoDescribeRunCode
+  let currentLanguageSemantics = executionPolicies(runtimeConfig).languageSemantics
   const tipConfig = {
     enabled: runtimeConfig.tipsEnabled,
     cooldownMessages: runtimeConfig.tipCooldownMessages,
@@ -562,6 +558,7 @@ export function createDirectSurfaceOwner({
 
   return Object.freeze({
     reconfigure(nextConfig) {
+      currentLanguageSemantics = executionPolicies(nextConfig).languageSemantics
       currentCanonicalizeToolCalls = nextConfig.canonicalizeToolCalls
       currentAutoDescribeRunCode = nextConfig.autoDescribeRunCode
       cordisRecovery.reconfigure(nextConfig.cordisToolsEnabled)
@@ -570,8 +567,11 @@ export function createDirectSurfaceOwner({
       tipConfig.escalationFailures = nextConfig.tipEscalationFailures
     },
     async assemble(initialAssembly, context, next) {
+      // Settings observes Host-owned catalogs without preparing a session environment.
+      if (context?.ptcPlusCapabilityObservation === true) return next()
       // Keep schema projection and later execution on one configuration snapshot.
       const autoDescribeRunCode = currentAutoDescribeRunCode
+      const languageSemantics = currentLanguageSemantics
       const agent = context?.agent
       const id = sessionId(agent)
       const requestOwner = id === undefined ? undefined : sessionOwner(id)
@@ -624,16 +624,18 @@ export function createDirectSurfaceOwner({
       if (!isCurrent()) return assembly
       const sessionPtc = presentation !== 'native' && id !== undefined
       const sessionPtcProjection = presentation === 'ptc' && id !== undefined
+      if (sessionPtc) await capabilityEnvironment?.prepare(agent, assembly.sections)
       const userBindings = sessionPtc ? await userBindingsForAgent(agent) : undefined
       if (!isCurrent()) return assembly
       const runCode = tools.find(tool => tool?.name === RUN_CODE)
-      let directTools = tools
+      let directTools = sessionPtc ? capabilityEnvironment?.visibleSchemas(agent, tools) ?? tools : tools
       if (sessionPtcProjection) {
         editTransport.ensureInstalled(agent)
-        directTools = [adaptRunCodeSchema(runCode), editRunCodeSchema()]
+        directTools = [adaptRunCodeSchema(runCode)]
       }
       const runtimeContexts = sessionPtc
         ? sessionRuntimeContexts(agent, tipConfig, {
+          sessionLogView,
           cordisRecoveryRequired(view) {
             return cordisRecovery.required(agent, view)
           },
@@ -648,9 +650,10 @@ export function createDirectSurfaceOwner({
         && assembly.sections.some(section => section?.name === 'tools:sdk'
           || (sessionPtcProjection && section?.name === completedState.collapseSectionName))
       const sections = projectsSections
-        ? assembly.sections.map(section => {
+        ? (capabilityEnvironment?.projectSections(agent, assembly.sections) ?? assembly.sections).map(section => {
             if (section?.name === 'tools:sdk') {
-              return { ...section, text: capabilitySdk(section.text, userBindings !== undefined) }
+              return { ...section, text: capabilitySdk(capabilityEnvironment?.sdk(agent, section.text) ?? section.text,
+                userBindings !== undefined, languageSemantics) }
             }
             if (sessionPtcProjection && section?.name === completedState.collapseSectionName) {
               return { ...section, text: CODE_TRANSPORT_INSTRUCTION }
@@ -660,7 +663,7 @@ export function createDirectSurfaceOwner({
         : assembly.sections
       if (id !== undefined) {
         const nativeSchemas = presentation === 'ptc'
-          ? new Map(toolSchemasForAgent(agent)
+          ? new Map((capabilityEnvironment?.visibleSchemas(agent, toolSchemasForAgent(agent)) ?? toolSchemasForAgent(agent))
             .filter(schema => typeof schema?.name === 'string'
               && schema.name !== RUN_CODE && schema.name !== EDIT_RUN_CODE)
             .map(schema => [schema.name, schema]))
@@ -704,20 +707,17 @@ export function createDirectSurfaceOwner({
       return bindCallPolicies(recovered, policy, policy.owner.calls)
     },
     executionRejection(exec) {
-      if (exec.name === EDIT_RUN_CODE && exec.parent !== undefined) {
-        return rejection(`tool ${EDIT_RUN_CODE} is only callable directly in PTC mode; call native tools from inside run_code`)
-      }
       const policy = dispatchPolicy(exec)
       if (exec.name === EDIT_RUN_CODE) {
-        return policy?.presentation === 'ptc'
+        return exec.parent !== undefined
           ? undefined
-          : rejection(`tool ${EDIT_RUN_CODE} is not declared for this request`)
+          : rejection(`tool ${EDIT_RUN_CODE} must be called through tools.${EDIT_RUN_CODE} inside run_code`)
       }
       if (exec.name === RUN_CODE || exec.parent !== undefined) {
         return undefined
       }
       if (policy?.presentation !== 'ptc') return undefined
-      return rejection(`tool ${exec.name} is not a direct PTC tool; use run_code or edit_run_code directly, and call native tools from inside run_code`)
+      return rejection(`tool ${exec.name} is not a direct PTC tool; use run_code directly, and call SDK tools from inside run_code`)
     },
     executionArguments(exec) {
       const policy = dispatchPolicy(exec)

package/internal/dynamic-environment-runtime.js

@@ -54,7 +54,7 @@ const asBindings = value => {
 
 /** Native reference operations over compiler-proved lexical and object frames. */
 export function createDynamicEnvironmentRuntime({
-  importModule = (source, options) => import(source, options),
+  importModule: defaultImportModule = (source, options) => import(source, options),
   intrinsicEval = defaultIntrinsics.intrinsicEval, realmFunction = defaultIntrinsics.realmFunction, globalObject = defaultIntrinsics.globalObject,
   errors, reflect = defaultIntrinsics.reflect, object, interfaceOwner, resolveAmbient = programAmbientResolver,
 } = {}) {
@@ -173,7 +173,7 @@ export function createDynamicEnvironmentRuntime({
 
   function environment({ frames = [], varFrame = new internal.Map(), strict = false, origin, lexicalContext = {},
     getThis = () => globalObject, getNewTarget = () => undefined, allowNewTarget = false,
-    ambient = ambientReference, createVar, declareVars, nativeAwait = false } = {}) {
+    ambient = ambientReference, createVar, declareVars, nativeAwait = false, importModule = defaultImportModule } = {}) {
     varFrame = asBindings(varFrame)
     const capturedFrames = []
     for (let index = 0; index < frames.length; index++) {
@@ -268,19 +268,19 @@ export function createDynamicEnvironmentRuntime({
           internal.copyArray(captured, rootIndex, captured.length, combined)
           internal.copyArray(frames, boundary, frames.length, combined)
         }
-        return environment({ frames: combined,
+        return environment({ importModule, frames: combined,
           varFrame, strict: nextStrict, getThis, getNewTarget, allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin, lexicalContext })
       },
       awaitActivation() {
         const local = new internal.Map()
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'lexical', bindings: local }]), varFrame: local,
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'lexical', bindings: local }]), varFrame: local,
           strict, getThis, getNewTarget, allowNewTarget, ambient, nativeAwait: true, origin, lexicalContext })
       },
       activation(bindings, nextGetThis = getThis, nextGetNewTarget = getNewTarget, nextStrict = strict, ownFunction = true, selfBindings) {
         bindings = asBindings(bindings)
         const activationFrames = [{ kind: 'lexical', bindings }]
         if (selfBindings !== undefined) internal.appendArray(activationFrames, { kind: 'self', bindings: asBindings(selfBindings) })
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, activationFrames), varFrame: bindings,
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, activationFrames), varFrame: bindings,
           strict: nextStrict, getThis: nextGetThis, getNewTarget: nextGetNewTarget, allowNewTarget: ownFunction || allowNewTarget, ambient, origin,
           lexicalContext: ownFunction ? { privateReferences: lexicalContext.privateReferences } : lexicalContext })
       },
@@ -294,7 +294,7 @@ export function createDynamicEnvironmentRuntime({
           }
           const parameterFrames = [{ kind: 'lexical', bindings }]
           if (selfBindings !== undefined) internal.appendArray(parameterFrames, { kind: 'self', bindings: asBindings(selfBindings) })
-          selected = environment({ frames: internal.copyArray(frames, 0, frames.length, parameterFrames), varFrame: bindings,
+          selected = environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, parameterFrames), varFrame: bindings,
             strict: nextStrict, getThis: nextGetThis, getNewTarget: nextGetNewTarget, allowNewTarget: ownFunction || allowNewTarget, ambient, origin, lexicalContext })
           internal.weakMapSet(parameterEnvironments, key, selected)
         }
@@ -309,15 +309,15 @@ export function createDynamicEnvironmentRuntime({
         } })
         return nativeCalls.registerCallableSourceTarget(adapter, fn)
       },
-      context(options) { return environment({ frames, varFrame, strict: options.strict ?? strict,
+      context(options) { return environment({ importModule, frames, varFrame, strict: options.strict ?? strict,
         getThis: options.getThis ?? getThis, getNewTarget: options.getNewTarget ?? getNewTarget,
         allowNewTarget: options.allowNewTarget ?? allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin,
         lexicalContext: { ...lexicalContext, ...options } }) },
-      at(nextOrigin) { return environment({ frames, varFrame, strict, getThis, getNewTarget,
+      at(nextOrigin) { return environment({ importModule, frames, varFrame, strict, getThis, getNewTarget,
         allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin: nextOrigin, lexicalContext }) },
       withObject(value) {
         if (value === null || value === undefined) throw new errors.TypeError('Cannot convert undefined or null to object')
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'object', object: object(value) }]),
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'object', object: object(value) }]),
           varFrame, strict, getThis, getNewTarget, allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin, lexicalContext })
       },
       declareEvalVars(names) {