dsh-ptc-plus 0.2.1

package/internal/cordis-tools-owner.js

@@ -0,0 +1,363 @@
+import * as CordisTools from '@deepseek-ai/dsh-tool-cordis'
+import * as CordisSkillFilesystem from '@deepseek-ai/dsh-skill-filesystem'
+import { dirname, isAbsolute, join } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { RUN_CODE } from './runtime-bridge-owner.js'
+
+const CORDIS_PRESET_ID = 'cordis'
+const CORDIS_SKILL_NAME = 'cordis-plugin-development'
+const CORDIS_SKILL_PROVIDER = 'ptc-plus-cordis'
+
+function requireFiberServices(agent, fiber, owner) {
+  if (typeof agent?.ctx?.get !== 'function') {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH agent Context.get API')
+  }
+  if (fiber.inject === null || typeof fiber.inject !== 'object' || Array.isArray(fiber.inject)) {
+    throw new Error(`ptc-plus: DSH Context.plugin did not expose resolved ${owner} service dependencies`)
+  }
+  const missing = Object.keys(fiber.inject).filter(service => agent.ctx.get(service) === undefined)
+  if (missing.length > 0) {
+    throw new Error(
+      `ptc-plus: cordisToolsEnabled requires DSH services: ${missing.join(', ')}`,
+    )
+  }
+}
+
+function requireCompanionServices(agent) {
+  if (typeof agent?.ctx?.get !== 'function') {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH agent Context.get API')
+  }
+  const agentPresets = agent.ctx.get('agentPresets')
+  if (typeof agentPresets?.resolve !== 'function') {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH agentPresets.resolve API')
+  }
+  const skills = agent.ctx.get('skills')
+  if (typeof skills?.list !== 'function' || typeof skills?.get !== 'function') {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH skills list/get APIs')
+  }
+  if (agent.ctx.tools?.get?.('skill', agent) === undefined) {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH skill tool in the PTC agent scope')
+  }
+  return { agentPresets, skills }
+}
+
+async function companionSkillDirectory(agentPresets) {
+  const preset = await agentPresets.resolve(CORDIS_PRESET_ID)
+  if (typeof preset?.path !== 'string' || !isAbsolute(preset.path)) {
+    throw new Error('ptc-plus: DSH cordis preset did not expose an absolute composition path')
+  }
+  if (typeof preset.broken === 'string' && preset.broken.length > 0) {
+    throw new Error(`ptc-plus: DSH cordis preset is unavailable: ${preset.broken}`)
+  }
+  return join(dirname(preset.path), 'skills')
+}
+
+async function requireCompanionSkill(agent, skills) {
+  const lookup = {
+    cwd: agent.session?.header?.cwd,
+    scope: agent,
+  }
+  const summary = (await skills.list(lookup)).find(skill => skill?.name === CORDIS_SKILL_NAME)
+  if (summary?.provider !== CORDIS_SKILL_PROVIDER
+    || summary.invocation?.modelInvocable !== true) {
+    throw new Error(`ptc-plus: official Cordis companion Skill ${JSON.stringify(CORDIS_SKILL_NAME)} is not model-invocable`)
+  }
+  const skill = await skills.get(CORDIS_SKILL_NAME, lookup)
+  if (skill?.provider !== CORDIS_SKILL_PROVIDER
+    || skill.invocation?.modelInvocable !== true
+    || typeof skill.content !== 'string'
+    || skill.content.length === 0) {
+    throw new Error(`ptc-plus: official Cordis companion Skill ${JSON.stringify(CORDIS_SKILL_NAME)} is not loadable`)
+  }
+}
+
+function createCordisInspectLeases(ctx) {
+  let cordisInspect
+  const requireCordisInspect = () => {
+    if (typeof ctx?.get !== 'function') {
+      throw new Error('ptc-plus: cordisToolsEnabled requires the DSH Context.get API')
+    }
+    cordisInspect ??= ctx.get('cordisInspect')
+    if (typeof cordisInspect?.register !== 'function') {
+      throw new Error('ptc-plus: cordisToolsEnabled requires the DSH cordisInspect.register API')
+    }
+    return cordisInspect
+  }
+  const providers = new Map()
+
+  const register = (registration) => {
+    const id = registration?.manifest?.id
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new Error('ptc-plus: Cordis inspect registration requires a non-empty manifest id')
+    }
+    let provider = providers.get(id)
+    if (provider === undefined) {
+      const registrations = new Set([registration])
+      const delegated = {
+        ...registration,
+        query(...args) {
+          const current = registrations.values().next().value
+          return Reflect.apply(current.query, current, args)
+        },
+      }
+      provider = {
+        manifest: registration.manifest,
+        registrations,
+        dispose: requireCordisInspect().register(delegated),
+      }
+      if (typeof provider.dispose !== 'function') {
+        throw new Error(`ptc-plus: Cordis inspect provider "${id}" did not return a disposer`)
+      }
+      providers.set(id, provider)
+    } else {
+      if (!isDeepStrictEqual(provider.manifest, registration.manifest)) {
+        throw new Error(`ptc-plus: Cordis inspect provider "${id}" changed its manifest across agent scopes`)
+      }
+      provider.registrations.add(registration)
+    }
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      provider.registrations.delete(registration)
+      if (provider.registrations.size > 0) return
+      providers.delete(id)
+      provider.dispose()
+    }
+  }
+
+  const facade = new Proxy({}, {
+    get(_target, property) {
+      if (property === 'register') return register
+      const target = requireCordisInspect()
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+
+  return Object.freeze({
+    plugin(cordisPlugin) {
+      return {
+        ...cordisPlugin,
+        apply(pluginCtx, config) {
+          if (typeof pluginCtx?.extend !== 'function') {
+            throw new Error('ptc-plus: cordisToolsEnabled requires the DSH Context.extend API')
+          }
+          return cordisPlugin.apply(pluginCtx.extend({ cordisInspect: facade }), config)
+        },
+      }
+    },
+    dispose() {
+      const failures = []
+      for (const provider of providers.values()) {
+        try {
+          provider.dispose()
+        } catch (error) {
+          failures.push(error)
+        }
+      }
+      providers.clear()
+      if (failures.length > 0) {
+        throw new AggregateError(failures, 'ptc-plus Cordis inspect lease disposal failed')
+      }
+    },
+  })
+}
+
+/** Own the official Cordis tool and companion Skill fibers in PTC agent scopes. */
+export function createCordisToolsOwner(
+  ctx,
+  cordisPlugin = CordisTools,
+  skillFilesystemPlugin = CordisSkillFilesystem,
+) {
+  if (typeof ctx?.agents?.list !== 'function') {
+    throw new Error('ptc-plus: cordisToolsEnabled requires the DSH agents.list API')
+  }
+  const mounts = new Map()
+  const pending = new Set()
+  const cordisInspectLeases = createCordisInspectLeases(ctx)
+  const scopedCordisPlugin = cordisInspectLeases.plugin(cordisPlugin)
+  let disposed = false
+
+  const leafErrors = error => error instanceof AggregateError
+    ? error.errors.flatMap(leafErrors)
+    : [error]
+  const activationCleanupError = (activationError, cleanupError) => new AggregateError(
+    [...new Set([...leafErrors(activationError), ...leafErrors(cleanupError)])],
+    'ptc-plus: Cordis activation and cleanup failed',
+    { cause: activationError },
+  )
+
+  const disposeMount = (agent, mount) => {
+    mount.disposed = true
+    if (mount.disposal === undefined) {
+      mount.disposal = (async () => {
+        const failures = []
+        for (const fiber of [...mount.fibers].reverse()) {
+          try {
+            await fiber.dispose()
+          } catch (error) {
+            failures.push(error)
+          }
+        }
+        if (failures.length > 0) {
+          throw new AggregateError(failures, 'ptc-plus Cordis agent mount disposal failed')
+        }
+      })()
+    }
+    return mount.disposal.then(() => {
+      if (mounts.get(agent) === mount) mounts.delete(agent)
+    })
+  }
+
+  const disposeAgent = async (agent) => {
+    pending.delete(agent)
+    const mount = mounts.get(agent)
+    if (mount === undefined) return
+    await disposeMount(agent, mount)
+  }
+
+  const installAgent = (agent) => {
+    if (disposed) return Promise.resolve()
+    const mounted = mounts.get(agent)
+    if (mounted !== undefined) return mounted.activation
+    if (agent?.ctx?.tools?.get?.(RUN_CODE, agent) === undefined) {
+      pending.add(agent)
+      return Promise.resolve()
+    }
+    pending.delete(agent)
+    if (typeof agent.ctx.plugin !== 'function') {
+      throw new Error('ptc-plus: cordisToolsEnabled requires the DSH agent Context.plugin API')
+    }
+    const mount = {
+      fibers: [],
+      activation: undefined,
+      disposal: undefined,
+      activated: false,
+      disposed: false,
+    }
+    mounts.set(agent, mount)
+    mount.activation = Promise.resolve().then(async () => {
+      const { agentPresets, skills } = requireCompanionServices(agent)
+      const skillDirectory = await companionSkillDirectory(agentPresets)
+      if (mount.disposed) return
+
+      const skillFiber = agent.ctx.plugin(skillFilesystemPlugin, {
+        providerName: CORDIS_SKILL_PROVIDER,
+        includeDefaultRoots: false,
+        customSkillDirs: [skillDirectory],
+      })
+      if (typeof skillFiber?.dispose !== 'function') {
+        throw new Error('ptc-plus: DSH Context.plugin did not return a disposable Cordis Skill fiber')
+      }
+      mount.fibers.push(skillFiber)
+      requireFiberServices(agent, skillFiber, 'Cordis Skill')
+      await Promise.resolve(skillFiber)
+      if (mount.disposed) return
+
+      const cordisFiber = agent.ctx.plugin(scopedCordisPlugin)
+      if (typeof cordisFiber?.dispose !== 'function') {
+        throw new Error('ptc-plus: DSH Context.plugin did not return a disposable Cordis tool fiber')
+      }
+      mount.fibers.push(cordisFiber)
+      requireFiberServices(agent, cordisFiber, 'Cordis tool')
+      await Promise.resolve(cordisFiber)
+      if (mount.disposed) return
+
+      await requireCompanionSkill(agent, skills)
+      if (mount.disposed) return
+      mount.activated = true
+    }).catch(async error => {
+      if (!mount.disposed) {
+        try {
+          await disposeMount(agent, mount)
+        } catch (cleanupError) {
+          throw activationCleanupError(error, cleanupError)
+        }
+      }
+      throw error
+    })
+    return mount.activation
+  }
+
+  const promptAssembly = async (_assembly, context, next) => {
+    const agent = context?.scope
+    if (agent === undefined || mounts.get(agent)?.activated === true) return next()
+    await installAgent(agent)
+    if (disposed || mounts.get(agent)?.activated !== true) return next()
+    if (typeof ctx.systemPrompt?.assemble !== 'function') {
+      throw new Error('ptc-plus: cordisToolsEnabled requires the DSH systemPrompt.assemble API')
+    }
+    return ctx.systemPrompt.assemble(context)
+  }
+  const retryPending = () => {
+    if (disposed || pending.size === 0) return
+    queueMicrotask(() => {
+      if (disposed) return
+      for (const agent of [...pending]) {
+        void Promise.resolve().then(() => installAgent(agent)).catch(error => {
+          pending.delete(agent)
+          ctx.logger?.warn?.('ptc-plus: deferred Cordis activation failed', error)
+        })
+      }
+    })
+  }
+  let stopCreated
+  let stopDisposed
+  let stopPromptAssembly
+  let stopToolsChange
+  let initialActivations
+  try {
+    stopPromptAssembly = ctx.on('system-prompt/assemble', promptAssembly, { prepend: true })
+    stopCreated = ctx.on('agent/created', ({ agent }) => installAgent(agent))
+    stopDisposed = ctx.on('agent/disposed', ({ agent }) => disposeAgent(agent))
+    stopToolsChange = ctx.on('tools/change', retryPending)
+    initialActivations = ctx.agents.list().map(installAgent)
+  } catch (error) {
+    stopToolsChange?.()
+    stopDisposed?.()
+    stopCreated?.()
+    stopPromptAssembly?.()
+    for (const [agent, mount] of mounts) {
+      void mount.activation?.catch(() => {})
+      void disposeMount(agent, mount)
+    }
+    cordisInspectLeases.dispose()
+    throw error
+  }
+
+  let disposal
+  const dispose = () => {
+    if (disposal !== undefined) return disposal
+    disposed = true
+    stopToolsChange()
+    stopDisposed()
+    stopCreated()
+    stopPromptAssembly()
+    pending.clear()
+    const owned = [...mounts.entries()]
+    const attempts = owned.map(([agent, mount]) => disposeMount(agent, mount))
+    disposal = Promise.allSettled(attempts).then(results => {
+      const failures = results.filter(result => result.status === 'rejected').map(result => result.reason)
+      try {
+        cordisInspectLeases.dispose()
+      } catch (error) {
+        failures.push(error)
+      }
+      if (failures.length > 0) throw new AggregateError(failures, 'ptc-plus Cordis disposal failed')
+    })
+    return disposal
+  }
+  const ready = Promise.all(initialActivations).then(() => undefined).catch(async error => {
+    try {
+      await dispose()
+    } catch (cleanupError) {
+      throw activationCleanupError(error, cleanupError)
+    }
+    throw error
+  })
+  return Object.freeze({
+    ready,
+    dispose,
+  })
+}

package/internal/diagnostic.js

@@ -0,0 +1,133 @@
+import { codeFrameColumns } from '@babel/code-frame'
+import { assertOwnFields, isRecord } from './record-utils.js'
+
+const DIAGNOSTIC_FIELDS = new Set([
+  'code', 'severity', 'phase', 'message', 'stateEffect', 'dispatchState',
+  'source', 'cause', 'help',
+])
+const SOURCE_FIELDS = new Set(['cell', 'start', 'end'])
+const POSITION_FIELDS = new Set(['line', 'column'])
+const CAUSE_FIELDS = new Set(['code', 'message'])
+const SEVERITIES = new Set(['error', 'warning', 'note'])
+const PHASES = new Set(['parse', 'preflight', 'execute', 'tool-dispatch', 'replay', 'recover'])
+const STATE_EFFECTS = new Set(['unchanged', 'partially-applied', 'rolled-back', 'unknown'])
+const DISPATCH_STATES = new Set(['not-dispatched', 'dispatched', 'completed', 'unknown'])
+
+function isLine(value) {
+  return typeof value === 'string' && value.length > 0 && !/[\r\n]/.test(value)
+}
+
+function normalizePosition(value, label) {
+  if (!isRecord(value) || !Number.isSafeInteger(value.line) || value.line < 1
+    || !Number.isSafeInteger(value.column) || value.column < 1) {
+    throw new Error(`invalid diagnostic ${label}`)
+  }
+  assertOwnFields(value, POSITION_FIELDS, `diagnostic ${label}`)
+  return Object.freeze({ line: value.line, column: value.column })
+}
+
+function normalizeCause(value, depth) {
+  if (depth > 16) throw new Error('diagnostic cause chain is too deep')
+  if (!isRecord(value)) throw new Error('invalid diagnostic cause')
+  if (!Object.hasOwn(value, 'severity')) {
+    assertOwnFields(value, CAUSE_FIELDS, 'diagnostic cause')
+    if (value.code !== undefined && !isLine(value.code)) {
+      throw new Error('invalid diagnostic cause code')
+    }
+    if (!isLine(value.message)) {
+      throw new Error('invalid diagnostic cause message')
+    }
+    return Object.freeze({
+      ...(value.code === undefined ? {} : { code: value.code }),
+      message: value.message,
+    })
+  }
+  return normalizeDiagnostic(value, depth + 1)
+}
+
+export function normalizeDiagnostic(value, depth = 0) {
+  if (!isRecord(value)) throw new Error('invalid dsh-ptc-plus diagnostic')
+  assertOwnFields(value, DIAGNOSTIC_FIELDS, 'dsh-ptc-plus diagnostic')
+  if (typeof value.code !== 'string' || !/^[A-Z][A-Z0-9-]{2,31}$/.test(value.code)) {
+    throw new Error('invalid dsh-ptc-plus diagnostic code')
+  }
+  if (!SEVERITIES.has(value.severity) || !PHASES.has(value.phase)
+    || !STATE_EFFECTS.has(value.stateEffect) || !isLine(value.message)) {
+    throw new Error('invalid dsh-ptc-plus diagnostic')
+  }
+  if (value.dispatchState !== undefined && !DISPATCH_STATES.has(value.dispatchState)) {
+    throw new Error('invalid dsh-ptc-plus diagnostic dispatch state')
+  }
+  let source
+  if (value.source !== undefined) {
+    if (!isRecord(value.source) || !isLine(value.source.cell)) {
+      throw new Error('invalid dsh-ptc-plus diagnostic source')
+    }
+    assertOwnFields(value.source, SOURCE_FIELDS, 'diagnostic source')
+    source = {
+      cell: value.source.cell,
+      start: normalizePosition(value.source.start, 'source start'),
+      ...(value.source.end === undefined ? {} : { end: normalizePosition(value.source.end, 'source end') }),
+    }
+    if (source.end !== undefined && (source.end.line < source.start.line
+      || (source.end.line === source.start.line && source.end.column < source.start.column))) {
+      throw new Error('diagnostic source end precedes its start')
+    }
+    Object.freeze(source)
+  }
+  let cause
+  if (value.cause !== undefined) cause = normalizeCause(value.cause, depth)
+  let help
+  if (value.help !== undefined) {
+    if (!Array.isArray(value.help) || value.help.length > 3
+      || value.help.some(item => !isLine(item))) {
+      throw new Error('invalid dsh-ptc-plus diagnostic help')
+    }
+    help = Object.freeze([...value.help])
+  }
+  return Object.freeze({
+    code: value.code,
+    severity: value.severity,
+    phase: value.phase,
+    message: value.message,
+    stateEffect: value.stateEffect,
+    ...(value.dispatchState === undefined ? {} : { dispatchState: value.dispatchState }),
+    ...(source === undefined ? {} : { source }),
+    ...(cause === undefined ? {} : { cause }),
+    ...(help === undefined ? {} : { help }),
+  })
+}
+
+export function diagnostic(value) {
+  return normalizeDiagnostic(value)
+}
+
+function causeText(cause) {
+  if (cause === undefined) return undefined
+  if (cause.code === undefined) return `cause: ${cause.message}`
+  return `cause: ${cause.code}: ${cause.message}`
+}
+
+/** Render a diagnostic without ANSI escapes or model-side parsing conventions. */
+export function renderDiagnostic(value, sourceText = undefined) {
+  const normalized = normalizeDiagnostic(value)
+  const lines = [`${normalized.severity}[${normalized.code}]: ${normalized.message}`]
+  if (normalized.source !== undefined) {
+    const { source } = normalized
+    lines.push(` --> ${source.cell}:${source.start.line}:${source.start.column}`)
+    if (typeof sourceText === 'string') {
+      const frame = codeFrameColumns(sourceText, {
+        start: source.start,
+        ...(source.end === undefined ? {} : { end: source.end }),
+      }, { highlightCode: false, linesAbove: 0, linesBelow: 0 })
+      if (frame.length > 0) lines.push(frame)
+    }
+  }
+  lines.push(`phase: ${normalized.phase}`)
+  if (normalized.dispatchState !== undefined) lines.push(`dispatch: ${normalized.dispatchState}`)
+  lines.push(`state: ${normalized.stateEffect}`)
+  const cause = causeText(normalized.cause)
+  if (cause !== undefined) lines.push(cause)
+  for (const help of normalized.help ?? []) lines.push(`help: ${help}`)
+  return lines.join('\n')
+}