dsh-ptc-plus 0.2.1

package/internal/direct-surface-owner.js

@@ -0,0 +1,326 @@
+/** Own PTC direct presentation, prompt projection, and stream normalization. */
+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'
+import { RUN_CODE } from './runtime-bridge-owner.js'
+import { isRecord } from './record-utils.js'
+
+const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL. Earlier top-level bindings remain available, so this call extends the current environment instead of creating a fresh one. 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_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.'
+
+function adaptRunCodeSchema(tool) {
+  const parameters = tool.parameters
+  const properties = isRecord(parameters) ? parameters.properties : undefined
+  const code = isRecord(properties) ? properties.code : undefined
+  const description = isRecord(properties) ? properties.description : undefined
+  if (!isRecord(parameters) || parameters.type !== 'object' || !isRecord(properties)
+    || !isRecord(code) || code.type !== 'string'
+    || !isRecord(description) || description.type !== 'string') {
+    throw new Error('ptc-plus: incompatible run_code schema; expected object parameters with string code and description properties')
+  }
+  return {
+    ...tool,
+    description: RUN_CODE_TOOL_DESCRIPTION,
+    parameters: {
+      ...parameters,
+      properties: {
+        ...properties,
+        code: { ...code, description: RUN_CODE_CODE_DESCRIPTION },
+        description: { ...description, description: RUN_CODE_DESCRIPTION_DESCRIPTION },
+      },
+    },
+  }
+}
+
+function capabilitySdk(nativeSdk) {
+  return `${projectProgramSdk(nativeSdk)}
+
+## PTC Plus program capabilities
+
+\`\`\`ts
+declare class CapabilityExplorationError extends Error { readonly operation: "tree" | "find" | "inspect" }
+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 }>
+}
+\`\`\``
+}
+
+function rejection(message) {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: message }],
+    error: { message },
+  }
+}
+
+function presentationState(assembly) {
+  const tools = Array.isArray(assembly?.tools) ? assembly.tools : []
+  if (!tools.some(tool => tool?.name === RUN_CODE)) {
+    return { presentation: 'native', ownerProven: false }
+  }
+  const collapse = assembly?.sections?.find(section => section?.name === 'tools:code-only')
+  if (collapse !== undefined) {
+    const presentation = typeof collapse.text === 'string' && collapse.text.trim().length > 0
+      ? 'code'
+      : 'both'
+    return { presentation, ownerProven: true }
+  }
+  const presentation = tools.every(tool => tool?.name === RUN_CODE || tool?.name === EDIT_RUN_CODE)
+    ? 'code'
+    : 'both'
+  return { presentation, ownerProven: false }
+}
+
+async function* bindCallPolicies(source, policy, calls) {
+  const pending = new Map()
+  for await (const chunk of source) {
+    if (chunk?.type === 'tool-call-delta'
+      && typeof chunk.id === 'string' && chunk.id.length > 0) {
+      pending.set(chunk.index, chunk.id)
+    } else if (chunk?.type === 'block-end' && chunk.block?.type === 'tool-call') {
+      const callId = chunk.block.id
+      if (typeof callId === 'string' && callId.length > 0) calls.set(callId, policy)
+      pending.delete(chunk.index)
+    } else if (chunk?.type === 'finish') {
+      for (const callId of pending.values()) calls.set(callId, policy)
+      pending.clear()
+    }
+    yield chunk
+  }
+}
+
+export function createDirectSurfaceOwner({
+  editTransport,
+  runtimeConfig,
+  canonicalizeToolCalls,
+  sessionId,
+  toolSchemasForAgent,
+}) {
+  // Composition is anchored to Agent identity because DSH selects presentation
+  // once per composed agent. Request signals bind the exact assembly to stream
+  // execution, while session identity is the fallback for hosts that replace a
+  // signal between those stages. Calls retain the resolved request policy by id
+  // so a later assembly cannot reinterpret an in-flight dispatch.
+  const compositions = new Map()
+  const canonicalRequests = new WeakMap()
+  const sessions = new Map()
+  let currentCanonicalizeToolCalls = canonicalizeToolCalls
+  const tipConfig = {
+    enabled: runtimeConfig.tipsEnabled,
+    cooldownMessages: runtimeConfig.tipCooldownMessages,
+    escalationFailures: runtimeConfig.tipEscalationFailures,
+  }
+
+  const sessionOwner = (id) => {
+    let owner = sessions.get(id)
+    if (owner === undefined) {
+      owner = { active: true, calls: new Map(), id, latestRequest: undefined }
+      sessions.set(id, owner)
+    }
+    return owner
+  }
+
+  const clearSession = (id) => {
+    const owner = sessions.get(id)
+    if (owner !== undefined) owner.active = false
+    sessions.delete(id)
+  }
+
+  const requestPolicy = (signal, id) => {
+    if (signal !== null && typeof signal === 'object') {
+      const request = canonicalRequests.get(signal)
+      return request?.owner.active === true && (id === undefined || request.owner.id === id)
+        ? request
+        : undefined
+    }
+    return id === undefined ? undefined : sessions.get(id)?.latestRequest
+  }
+
+  const executionPolicy = (id, callId) => {
+    if (id === undefined) return undefined
+    const owner = sessions.get(id)
+    if (typeof callId === 'string' && owner?.calls.has(callId)) {
+      return owner.calls.get(callId)
+    }
+    return undefined
+  }
+
+  const rememberRequest = (id, signal, presentation, nativeSchemas) => {
+    const owner = sessionOwner(id)
+    const request = { presentation, nativeSchemas, owner }
+    owner.latestRequest = request
+    if (signal !== undefined) canonicalRequests.set(signal, request)
+  }
+
+  const captureComposition = (agent, id, presentation) => {
+    let composition = compositions.get(agent)
+    if (composition !== undefined) return composition
+    composition = { presentation, sessionId: id }
+    compositions.set(agent, composition)
+    return composition
+  }
+
+  const clearCompositionsForSession = (id) => {
+    for (const [agent, composition] of compositions) {
+      if (composition.sessionId === id) compositions.delete(agent)
+    }
+  }
+
+  return Object.freeze({
+    reconfigure(nextConfig) {
+      currentCanonicalizeToolCalls = nextConfig.canonicalizeToolCalls
+      tipConfig.enabled = nextConfig.tipsEnabled
+      tipConfig.cooldownMessages = nextConfig.tipCooldownMessages
+      tipConfig.escalationFailures = nextConfig.tipEscalationFailures
+    },
+    async assemble(initialAssembly, context, next) {
+      const agent = context?.agent
+      const id = sessionId(agent)
+      const initialState = presentationState(initialAssembly)
+      let composition = compositions.get(agent)
+      if (composition === undefined && id !== undefined
+        && (initialState.ownerProven || initialState.presentation === 'code')) {
+        composition = captureComposition(agent, id, initialState.presentation)
+      }
+      if (composition?.presentation === 'code' && !editTransport.isInstalled(agent)) {
+        editTransport.ensureInstalled(agent)
+      }
+
+      const assembly = await next()
+      const tools = assembly.tools
+      if (!Array.isArray(tools)) {
+        throw new Error('ptc-plus: incompatible prompt assembly; expected a tools array')
+      }
+      const completedState = presentationState(assembly)
+      if (composition === undefined && id !== undefined) {
+        const state = initialState.ownerProven ? initialState : completedState
+        composition = captureComposition(agent, id, state.presentation)
+        if (composition.presentation === 'code' && !editTransport.isInstalled(agent)) {
+          editTransport.ensureInstalled(agent)
+        }
+      }
+      const presentation = composition?.presentation
+        ?? (initialState.ownerProven ? initialState.presentation : completedState.presentation)
+      const requestSignal = context?.signal !== null && typeof context?.signal === 'object'
+        ? context.signal
+        : undefined
+      if (!tools.some(tool => tool?.name === RUN_CODE)) {
+        if (presentation !== 'native') {
+          throw new Error(`ptc-plus: ${presentation} agent composition assembled without run_code`)
+        }
+        if (id !== undefined) {
+          rememberRequest(id, requestSignal, 'native', new Map())
+        }
+        return assembly
+      }
+      if (presentation === 'native') {
+        throw new Error('ptc-plus: native agent composition assembled with run_code')
+      }
+      const sessionPtc = presentation !== 'native' && id !== undefined
+      const sessionCodeOnlyProjection = presentation === 'code' && id !== undefined
+      const runCode = tools.find(tool => tool?.name === RUN_CODE)
+      let directTools = tools
+      if (sessionCodeOnlyProjection) {
+        editTransport.ensureInstalled(agent)
+        directTools = [adaptRunCodeSchema(runCode), editRunCodeSchema()]
+      }
+      const runtimeContexts = sessionPtc
+        ? sessionRuntimeContexts(agent, tipConfig)
+        : { contexts: [] }
+      const contexts = sessionPtc && Array.isArray(assembly.contexts)
+        && runtimeContexts.contexts.length > 0
+        ? [...assembly.contexts, ...runtimeContexts.contexts]
+        : assembly.contexts
+      const projectsSections = presentation !== 'native' && Array.isArray(assembly.sections)
+        && assembly.sections.some(section => section?.name === 'tools:sdk'
+          || (sessionCodeOnlyProjection && section?.name === 'tools:code-only'))
+      const sections = projectsSections
+        ? assembly.sections.map(section => {
+            if (section?.name === 'tools:sdk') {
+              return { ...section, text: capabilitySdk(section.text) }
+            }
+            if (sessionCodeOnlyProjection && section?.name === 'tools:code-only') {
+              return { ...section, text: CODE_TRANSPORT_INSTRUCTION }
+            }
+            return section
+          })
+        : assembly.sections
+
+      if (id !== undefined) {
+        const nativeSchemas = presentation === 'code'
+          ? new Map(toolSchemasForAgent(agent)
+            .filter(schema => typeof schema?.name === 'string'
+              && schema.name !== RUN_CODE && schema.name !== EDIT_RUN_CODE)
+            .map(schema => [schema.name, schema]))
+          : new Map()
+        rememberRequest(id, requestSignal, presentation, nativeSchemas)
+      }
+
+      return {
+        ...assembly,
+        tools: sessionCodeOnlyProjection
+          ? directTools
+          : directTools.map(tool => tool?.name === RUN_CODE ? adaptRunCodeSchema(tool) : tool),
+        sections,
+        contexts,
+      }
+    },
+    stream(options, next) {
+      const optionSessionId = options.sessionId === undefined ? undefined : String(options.sessionId)
+      const policy = requestPolicy(options?.signal, optionSessionId)
+      if (policy === undefined || optionSessionId === undefined) return next()
+      const source = policy.presentation === 'code'
+        ? canonicalizeToolCallStream(next(), {
+          tools: options.tools,
+          nativeSchemas: currentCanonicalizeToolCalls ? policy.nativeSchemas : new Map(),
+          editToolName: EDIT_RUN_CODE,
+        })
+        : next()
+      return bindCallPolicies(source, 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 id = sessionId(exec.agent)
+      const policy = executionPolicy(id, exec.callId)
+        ?? requestPolicy(exec?.signal, id)
+      if (exec.name === EDIT_RUN_CODE) {
+        return policy?.presentation === 'code'
+          ? undefined
+          : rejection(`tool ${EDIT_RUN_CODE} is not declared for this request`)
+      }
+      if (exec.name === RUN_CODE || exec.parent !== undefined) {
+        return undefined
+      }
+      if (policy?.presentation !== 'code') 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`)
+    },
+    handleResult(exec) {
+      const id = sessionId(exec.agent)
+      if (id === undefined || typeof exec.callId !== 'string') return
+      sessions.get(id)?.calls.delete(exec.callId)
+    },
+    disposeAgent(agent) {
+      const id = sessionId(agent)
+      compositions.delete(agent)
+      if (id !== undefined) clearSession(id)
+    },
+    disposeSession(session) {
+      const id = String(session.id)
+      clearCompositionsForSession(id)
+      clearSession(id)
+    },
+    dispose() {
+      compositions.clear()
+      for (const owner of sessions.values()) owner.active = false
+      sessions.clear()
+    },
+  })
+}

package/internal/edit-transport-owner.js

@@ -0,0 +1,287 @@
+/** Own the scoped edit tool, target claims, derived metadata, and paired disposers. */
+import {
+  DERIVED_RUN_KEY,
+  EDIT_TARGET_KEY,
+  JOURNAL_KEY,
+  RECOVERY_BOUNDARY_KEY,
+  REWRITES_KEY,
+  derivedEditResultsEqual,
+  liveToolCallSeq,
+  normalizeJournal,
+  normalizeRecoveryBoundaries,
+  normalizeRewrites,
+  validatedRewrites,
+} from './session-journal.js'
+import { editRejectedCell, editRunCodeSchema } from './rejected-cell-editor.js'
+import { editTargetForCall, projectSessionLog } from './session-log-view.js'
+import { RUN_CODE } from './runtime-bridge-owner.js'
+import { isRecord } from './record-utils.js'
+
+export const EDIT_RUN_CODE = 'edit_run_code'
+
+function unavailableDerivedResult(inner) {
+  if (inner?.isError !== true) {
+    throw new Error('ptc-plus: derived run_code result did not contain a valid execution journal')
+  }
+  return {
+    edited: false,
+    error: inner.error?.message ?? 'derived run_code did not enter the runtime',
+    logs: [],
+  }
+}
+
+function derivedEditResult(inner) {
+  const result = {
+    edited: true,
+    logs: Array.isArray(inner?.value?.logs) ? inner.value.logs : [],
+  }
+  if (inner?.isError === true) {
+    result.error = inner.error?.message ?? 'derived run_code execution failed'
+  } else if (inner?.value !== undefined && !isRecord(inner.value)) {
+    result.value = inner.value
+  } else if (inner?.value?.result !== undefined) {
+    result.value = inner.value.result
+  }
+  return result
+}
+
+export function createEditTransportOwner(ctx, {
+  durableReplay,
+  executeTentative,
+  sessionId,
+  toolSchemasForAgent,
+}) {
+  let currentDurableReplay = durableReplay
+  const editExecutionMetadata = new WeakMap()
+  const editClaims = new Map()
+  const pendingSettlements = new Map()
+  const installedScopes = new Map()
+
+  const releaseClaim = (id, targetCallSeq) => {
+    const claims = editClaims.get(id)
+    claims?.delete(targetCallSeq)
+    if (claims?.size === 0) editClaims.delete(id)
+  }
+
+  const discardSettlements = (id) => {
+    for (const [exec, pending] of pendingSettlements) {
+      if (id !== undefined && pending.id !== id) continue
+      pendingSettlements.delete(exec)
+      pending.finalize(false)
+    }
+  }
+
+  const definition = editRunCodeSchema()
+  const derivedMetadata = (derived) => {
+    const meta = {
+      [JOURNAL_KEY]: normalizeJournal(derived.journal),
+      [EDIT_TARGET_KEY]: { targetCallSeq: derived.targetCallSeq },
+      [DERIVED_RUN_KEY]: {
+        code: derived.code,
+        description: derived.description,
+      },
+    }
+    if (derived.rewrites !== undefined) {
+      meta[REWRITES_KEY] = normalizeRewrites(derived.rewrites)
+    }
+    if (derived.recoveryBoundaries !== undefined) {
+      meta[RECOVERY_BOUNDARY_KEY] = normalizeRecoveryBoundaries(derived.recoveryBoundaries)
+    }
+    return meta
+  }
+  definition.output = {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        edited: { type: 'boolean' },
+        reason: { type: 'string' },
+        error: { type: 'string' },
+        value: {},
+        logs: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['edited'],
+    },
+    render: (_args, value) => [{ type: 'text', text: JSON.stringify(value ?? {}) }],
+    presentationMeta: (args) => {
+      const meta = {}
+      if (!isRecord(args)) return meta
+      const derived = editExecutionMetadata.get(args)
+      if (derived === undefined) return meta
+      return derivedMetadata(derived)
+    },
+  }
+  definition.execute = async (args, exec) => {
+    const agent = exec?.agent
+    const callId = typeof exec?.callId === 'string' ? exec.callId : undefined
+    const persistedTargetCallSeq = liveToolCallSeq(agent?.session, callId, EDIT_RUN_CODE)
+    if (persistedTargetCallSeq === undefined && projectSessionLog(agent).editableRun !== undefined) {
+      throw new Error('ptc-plus: edit_run_code requires a unique persisted tool/call event')
+    }
+    const target = persistedTargetCallSeq === undefined
+      ? undefined
+      : editTargetForCall(agent, callId, persistedTargetCallSeq)
+    if (target?.source === undefined || target.callSeq === undefined) {
+      return { edited: false, reason: 'no run_code cell is currently eligible for safe editing' }
+    }
+    const edited = editRejectedCell(args, target.source)
+    if (!edited.edited) return edited
+    if (typeof ctx.tools.execute !== 'function') {
+      throw new Error('ptc-plus: DSH tools.execute is required for derived edit execution')
+    }
+    const persistedCallSeq = currentDurableReplay ? persistedTargetCallSeq : undefined
+    const id = sessionId(agent)
+    let claims = editClaims.get(id)
+    if (claims === undefined) {
+      claims = new Map()
+      editClaims.set(id, claims)
+    } else {
+      for (const [callSeq, phase] of claims) {
+        if (phase === 'settled' && callSeq !== target.callSeq) claims.delete(callSeq)
+      }
+    }
+    if (claims.has(target.callSeq)) {
+      return { edited: false, reason: 'the current edit target already has a derived execution' }
+    }
+    claims.set(target.callSeq, 'executing')
+    let retainClaim = false
+    let finalizeTentative
+    try {
+      const dispatch = () => ctx.tools.execute({
+        callId: `${String(exec.callId)}:derived`,
+        name: RUN_CODE,
+        arguments: { code: edited.code, description: edited.description },
+        agent,
+        signal: exec.signal,
+      })
+      const tentative = await executeTentative(persistedCallSeq, dispatch)
+      const inner = tentative.result
+      finalizeTentative = tentative.finalize
+      const journalValue = isRecord(inner?.meta) && Object.hasOwn(inner.meta, JOURNAL_KEY)
+        ? inner.meta[JOURNAL_KEY]
+        : undefined
+      const journal = journalValue === undefined ? undefined : normalizeJournal(journalValue)
+      if (journal === undefined || journal.status === 'noop') return unavailableDerivedResult(inner)
+      const rewrites = validatedRewrites(inner.meta)
+      const recoveryBoundaries = isRecord(inner?.meta)
+        && Object.hasOwn(inner.meta, RECOVERY_BOUNDARY_KEY)
+        ? normalizeRecoveryBoundaries(inner.meta[RECOVERY_BOUNDARY_KEY])
+        : undefined
+      const value = derivedEditResult(inner)
+      const derived = {
+        targetCallSeq: target.callSeq,
+        journal,
+        rewrites,
+        recoveryBoundaries,
+        code: edited.code,
+        description: edited.description,
+      }
+      editExecutionMetadata.set(args, derived)
+      claims.set(target.callSeq, 'settled')
+      pendingSettlements.set(exec, {
+        id,
+        targetCallSeq: target.callSeq,
+        expectedMeta: derivedMetadata(derived),
+        finalize: finalizeTentative,
+      })
+      finalizeTentative = undefined
+      retainClaim = true
+      return value
+    } finally {
+      finalizeTentative?.(false)
+      if (!retainClaim) releaseClaim(id, target.callSeq)
+    }
+  }
+
+  const uninstall = (agent) => {
+    const installed = installedScopes.get(agent)
+    if (installed === undefined) return
+    installedScopes.delete(agent)
+    installed.dispose()
+  }
+
+  return Object.freeze({
+    definition,
+    reconfigure(nextConfig) {
+      currentDurableReplay = nextConfig.durableReplay
+    },
+    isInstalled(agent) {
+      return installedScopes.has(agent)
+    },
+    ensureInstalled(agent) {
+      const installed = installedScopes.get(agent)
+      if (installed !== undefined) return installed.definition
+      const liveSchemas = typeof toolSchemasForAgent === 'function'
+        ? toolSchemasForAgent(agent)
+        : []
+      if (Array.isArray(liveSchemas)
+        && liveSchemas.some(schema => schema?.name === EDIT_RUN_CODE)) {
+        throw new Error('ptc-plus: cannot install edit_run_code; the agent scope already owns that tool name')
+      }
+      const scopedTools = agent?.ctx?.tools
+      if (typeof scopedTools?.register !== 'function' || typeof scopedTools.presentAs !== 'function') {
+        throw new Error('ptc-plus: DSH agent-scoped tools.register and tools.presentAs are required to expose edit_run_code')
+      }
+      const disposeRegistration = scopedTools.register(definition)
+      if (typeof disposeRegistration !== 'function') {
+        throw new Error('ptc-plus: DSH tools.register did not return a disposer')
+      }
+      let disposePresentation
+      try {
+        disposePresentation = scopedTools.presentAs('both')
+        if (typeof disposePresentation !== 'function') {
+          throw new Error('ptc-plus: DSH tools.presentAs did not return a disposer')
+        }
+      } catch (error) {
+        disposeRegistration()
+        throw error
+      }
+      let active = true
+      const dispose = () => {
+        if (!active) return
+        active = false
+        disposePresentation()
+        disposeRegistration()
+      }
+      installedScopes.set(agent, { definition, dispose, sessionId: sessionId(agent) })
+      return definition
+    },
+    handleResult(exec, result) {
+      const pending = pendingSettlements.get(exec)
+      pendingSettlements.delete(exec)
+      if (pending === undefined) return
+      const persisted = derivedEditResultsEqual(
+        result?.meta,
+        pending.expectedMeta,
+        pending.targetCallSeq,
+      )
+      pending.finalize(persisted)
+      if (persisted) return
+      releaseClaim(pending.id, pending.targetCallSeq)
+    },
+    disposeAgent(agent) {
+      uninstall(agent)
+      const id = sessionId(agent)
+      if (id !== undefined) {
+        discardSettlements(id)
+        editClaims.delete(id)
+      }
+    },
+    disposeSession(session) {
+      const id = String(session.id)
+      for (const [agent, installed] of installedScopes) {
+        if (installed.sessionId !== id) continue
+        installedScopes.delete(agent)
+        installed.dispose()
+      }
+      discardSettlements(id)
+      editClaims.delete(id)
+    },
+    dispose() {
+      discardSettlements()
+      editClaims.clear()
+      for (const installed of installedScopes.values()) installed.dispose()
+      installedScopes.clear()
+    },
+  })
+}