@anionex/dsh-vision-toolkit 0.1.5

package/src/exposure.ts

@@ -0,0 +1,227 @@
+/**
+ * Agent-scoped progressive exposure for the model-facing visual tools.
+ * Runtime readiness is global, while tool schemas enter only an Agent that has
+ * loaded the matching Skill; administrative diagnostics stay on the Web seam.
+ * @module dsh-vision-toolkit/exposure
+ */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { VISION_TOOLS_SKILL_CONTENT, VISION_TOOLS_SKILL_NAME } from './skill.ts'
+
+/** Small bootstrap tool retained only until the current Agent gains visual tools. */
+export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate'
+
+interface AgentExposure {
+  active: boolean
+  hideActivation?: () => void
+  toolDisposers: Array<() => void>
+  toolNames: string[]
+}
+
+/** Result returned by the one-shot activation transport. */
+export interface VisionToolkitActivationResult {
+  activated: boolean
+  tools: string[]
+}
+
+function renderJson(_args: unknown, value: unknown): ContentBlock[] {
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isVisionSkillArguments(value: unknown): boolean {
+  return isRecord(value) && value.name === VISION_TOOLS_SKILL_NAME
+}
+
+function nativeSkillCall(raw: string): boolean {
+  try {
+    return isVisionSkillArguments(JSON.parse(raw))
+  } catch {
+    return false
+  }
+}
+
+function containsBundledSkillContent(blocks: readonly unknown[]): boolean {
+  return blocks.some(block => isRecord(block)
+    && block.type === 'text'
+    && typeof block.text === 'string'
+    && block.text.includes(VISION_TOOLS_SKILL_CONTENT))
+}
+
+function isBundledSkillResult(value: unknown): boolean {
+  return isRecord(value)
+    && value.name === VISION_TOOLS_SKILL_NAME
+    && value.content === VISION_TOOLS_SKILL_CONTENT
+}
+
+/** Whether durable history proves that this Session loaded the bundled Skill. */
+function hasLoadedVisionSkill(session: Session): boolean {
+  const nativeCalls = new Set<string>()
+  for (const event of session.events) {
+    if (event.type === 'user/message') {
+      const source = event.data.source
+      if (source.kind === 'skill-invocation'
+        && source.name === VISION_TOOLS_SKILL_NAME
+        && containsBundledSkillContent(event.data.content)) return true
+      continue
+    }
+    if (event.type === 'tool/call') {
+      if (event.data.name === 'skill' && nativeSkillCall(event.data.arguments)) {
+        nativeCalls.add(String(event.data.callId))
+      }
+      continue
+    }
+    if (event.type === 'tool/result') {
+      const [block] = event.data.message.content
+      if (block?.type === 'tool-result'
+        && block.isError !== true
+        && nativeCalls.has(String(block.toolCallId))
+        && containsBundledSkillContent(block.content)) return true
+      continue
+    }
+    if (event.type === 'tool/code-dispatch'
+      && event.data.name === 'skill'
+      && event.data.isError === false
+      && isVisionSkillArguments(event.data.arguments)
+      && containsBundledSkillContent(event.data.content)) return true
+  }
+  return false
+}
+
+/**
+ * Owns one progressive-exposure generation for a ready Vision Toolkit runtime.
+ * The bootstrap tool is global; visual definitions are created and registered
+ * in an Agent scope only after the Skill load is durable or just succeeded.
+ */
+export class VisionToolExposure {
+  readonly activationTool: ToolDefinition
+  private readonly states = new Map<Agent, AgentExposure>()
+  private installed = false
+
+  /**
+   * @param ctx - Plugin context with Tool and Agent registries.
+   * @param createTools - Fresh definitions bound to the current runtime generation.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly createTools: () => ToolDefinition[],
+  ) {
+    this.activationTool = defineTool({
+      name: VISION_TOOLKIT_ACTIVATE,
+      description: `Activate the independent Vision Toolkit execution tools for this Agent after loading the ${VISION_TOOLS_SKILL_NAME} Skill. `
+        + 'The Skill tool normally activates them automatically; call this once only after a direct Skill invocation when the visual tools are still absent. This activation tool disappears after success.',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            activated: { type: 'boolean', required: true },
+            tools: { type: 'array', items: { type: 'string' }, required: true },
+          },
+        },
+        render: renderJson,
+      },
+      execute: (_args, exec): Promise<VisionToolkitActivationResult> => {
+        if (exec.agent === undefined) {
+          throw new Error(`${VISION_TOOLKIT_ACTIVATE}: an Agent Session is required`)
+        }
+        if (!hasLoadedVisionSkill(exec.agent.session)) {
+          throw new Error(`${VISION_TOOLKIT_ACTIVATE}: load the ${VISION_TOOLS_SKILL_NAME} Skill first`)
+        }
+        return Promise.resolve(this.activate(exec.agent))
+      },
+      presentCall: () => ({ card: 'generic', title: 'Activate vision tools', kind: 'execute' }),
+    })
+  }
+
+  /** Install lifecycle listeners and adopt Agents that already exist. */
+  install(): () => void {
+    if (this.installed) throw new Error('dsh-vision-toolkit: progressive exposure is already installed')
+    this.installed = true
+    const listeners = [
+      this.ctx.on('agent/created', ({ agent }) => { this.attach(agent) }),
+      this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent) }),
+      this.ctx.on('tools/result', (exec, result) => {
+        if (result.isError === false
+          && exec.name === 'skill'
+          && exec.agent !== undefined
+          && isVisionSkillArguments(exec.arguments)
+          && isBundledSkillResult(result.value)) {
+          this.activate(exec.agent)
+        }
+        return undefined
+      }),
+    ]
+    try {
+      for (const agent of this.ctx.agents.list()) this.attach(agent)
+    } catch (error) {
+      for (const dispose of listeners.reverse()) dispose()
+      this.disposeStates()
+      this.installed = false
+      throw error
+    }
+    return () => {
+      if (!this.installed) return
+      this.installed = false
+      for (const dispose of listeners.reverse()) dispose()
+      this.disposeStates()
+    }
+  }
+
+  private attach(agent: Agent): void {
+    if (this.states.has(agent)) return
+    this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] })
+    if (hasLoadedVisionSkill(agent.session)) this.activate(agent)
+  }
+
+  private activate(agent: Agent): VisionToolkitActivationResult {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    /* v8 ignore next -- attach() synchronously creates this exact entry. */
+    if (state === undefined) throw new Error(`dsh-vision-toolkit: Agent ${String(agent.id)} has no exposure state`)
+    if (state.active) return { activated: false, tools: [...state.toolNames] }
+
+    const definitions = this.createTools()
+    const toolDisposers: Array<() => void> = []
+    let hideActivation: (() => void) | undefined
+    try {
+      for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
+      hideActivation = agent.ctx.tools.restrict({ deny: [VISION_TOOLKIT_ACTIVATE] })
+    } catch (error) {
+      hideActivation?.()
+      for (const dispose of toolDisposers.reverse()) dispose()
+      throw error
+    }
+
+    state.active = true
+    state.hideActivation = hideActivation
+    state.toolDisposers = toolDisposers
+    state.toolNames = definitions.map(definition => definition.name)
+    return { activated: true, tools: [...state.toolNames] }
+  }
+
+  private detach(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined) return
+    this.states.delete(agent)
+    this.disposeState(state)
+  }
+
+  private disposeStates(): void {
+    for (const state of this.states.values()) this.disposeState(state)
+    this.states.clear()
+  }
+
+  private disposeState(state: AgentExposure): void {
+    state.hideActivation?.()
+    for (const dispose of state.toolDisposers.reverse()) dispose()
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @anionex/dsh-vision-toolkit — DSH Vision Toolkit profile bundle.
+ *
+ * Plugin lifecycle follows the documented readiness chain: verify the pinned
+ * upstream checkout, publish the vision-tools Skill and its one-shot bootstrap,
+ * then mount the execution tools only in Agents that load that Skill. Any
+ * failure leaves no model capability behind, and disposal unregisters every
+ * global and Agent-scoped contribution the plugin mounted.
+ * @module @anionex/dsh-vision-toolkit
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-settings'
+import { ArtifactAccessController, prepareArtifactAccessKey } from './artifact-access.ts'
+import {
+  Config,
+  VISION_TOOLKIT_SETTINGS_NAMESPACE,
+  resolveConfig,
+  type VisionToolkitConfig,
+} from './config.ts'
+import { VisionToolExposure } from './exposure.ts'
+import { VisionToolkitRuntimeManager } from './runtime-manager.ts'
+import { VISION_TOOLS_SKILL } from './skill.ts'
+import { createVisionTools } from './tools.ts'
+import { PLUGIN_VERSION } from './version.ts'
+import { installVisionToolkitWeb, VisionToolkitWebBackend } from './web.ts'
+import { PastedImageBackend } from './paste-images.ts'
+
+export const name = '@anionex/dsh-vision-toolkit'
+
+export { Config }
+
+export const inject = ['tools', 'credentials', 'skills', 'subprocess', 'settings', 'agents', 'sessions']
+
+/** Plugin entry: validate configuration synchronously, then mount asynchronously. */
+export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Promise<() => void> {
+  // Registration itself rejects an invalid stored section before any runtime
+  // or Tool becomes visible. The custom Web editor preflights runtime changes
+  // before persistence; hand-edited settings still fail loud here or retain
+  // the last serving generation when changed live.
+  const settings = ctx.settings.register(VISION_TOOLKIT_SETTINGS_NAMESPACE, Config, {
+    base: config,
+    applies: 'live',
+    validate: (value) => { resolveConfig(value) },
+  })
+  const manager = new VisionToolkitRuntimeManager(ctx)
+  const artifacts = new ArtifactAccessController(await prepareArtifactAccessKey())
+  const lifecycle = new AbortController()
+  const disposers: Array<() => void> = []
+  let operationalDisposers: { activationTool: () => void; exposure: () => void; skill: () => void } | undefined
+
+  const ensureOperational = (): void => {
+    if (!manager.ready || operationalDisposers !== undefined) return
+    const exposure = new VisionToolExposure(ctx, () => createVisionTools(
+      () => manager.current(),
+      value => artifacts.presentationMeta(value),
+      lifecycle.signal,
+    ))
+    let activationTool: (() => void) | undefined
+    let exposureDisposer: (() => void) | undefined
+    let skill: (() => void) | undefined
+    try {
+      activationTool = ctx.tools.register(exposure.activationTool)
+      skill = ctx.skills.register(VISION_TOOLS_SKILL)
+      exposureDisposer = exposure.install()
+      operationalDisposers = { activationTool, exposure: exposureDisposer, skill }
+      const info = manager.current().upstreamVersion
+      ctx.logger.info(
+        'dsh-vision-toolkit %s ready (upstream %s @ %s, checkout %s)',
+        PLUGIN_VERSION,
+        info.version,
+        info.commit,
+        info.path,
+      )
+    } catch (error) {
+      exposureDisposer?.()
+      if (skill !== undefined) skill()
+      activationTool?.()
+      throw error
+    }
+  }
+
+  try {
+    await manager.initialize(settings.get())
+    ensureOperational()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    ctx.logger.error(
+      'dsh-vision-toolkit %s: runtime not ready; the vision-tools skill, activation bootstrap, and Agent-scoped visual tools are NOT registered. Settings remain available for repair. %s',
+      PLUGIN_VERSION,
+      message,
+    )
+  }
+
+  const backend = new VisionToolkitWebBackend(ctx, manager, artifacts, ensureOperational)
+  const pastedImages = new PastedImageBackend(ctx, {
+    maxImageBytes: () => manager.status().activeConfig?.maxImageBytes ?? resolveConfig(settings.get()).maxImageBytes,
+  })
+  installVisionToolkitWeb(ctx, backend, artifacts, pastedImages)
+  disposers.push(settings.watch(async (next) => {
+    try {
+      await manager.reconfigure(next)
+      ensureOperational()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      ctx.logger.error('dsh-vision-toolkit: keeping the previous runtime after a refused Settings generation. %s', message)
+    }
+  }))
+
+  return () => {
+    lifecycle.abort()
+    if (operationalDisposers !== undefined) {
+      operationalDisposers.exposure()
+      operationalDisposers.activationTool()
+      operationalDisposers.skill()
+      operationalDisposers = undefined
+    }
+    for (const dispose of disposers.reverse()) dispose()
+  }
+}

package/src/paste-images.ts

@@ -0,0 +1,234 @@
+/** Workspace-local storage for images pasted into the DSH Web composer. */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-session'
+import { sameOriginPost } from './web-request.ts'
+
+/** Exact route used by the browser paste integration. */
+export const PASTE_IMAGES_ROUTE = '/_dsh/vision-toolkit/paste-images'
+
+const MAX_NAME_BYTES = 180
+
+interface PasteImageResponse {
+  ok: true
+  value: { absolutePath: string; filename: string; bytes: number }
+}
+
+interface PasteImageFailure {
+  ok: false
+  error: { code: string; message: string }
+}
+
+type PasteImageResult = PasteImageResponse | PasteImageFailure
+
+function responseJson(res: ServerResponse, status: number, body: PasteImageResult): void {
+  const bytes = Buffer.from(JSON.stringify(body))
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  res.setHeader('Content-Length', String(bytes.length))
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'")
+  res.writeHead(status)
+  res.end(bytes)
+}
+
+function requestError(res: ServerResponse, status: number, code: string, message: string): void {
+  responseJson(res, status, { ok: false, error: { code, message } })
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function singleQuery(url: URL, key: string): string {
+  const values = url.searchParams.getAll(key)
+  if (values.length !== 1 || values[0] === undefined || values[0] === '') {
+    throw new TypeError(`${key} is required exactly once`)
+  }
+  return values[0]
+}
+
+function declaredSize(url: URL): number {
+  const value = Number(singleQuery(url, 'size'))
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError('size must be a positive safe integer')
+  return value
+}
+
+function imageMediaType(req: IncomingMessage): string {
+  const value = req.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase()
+  if (value === undefined || !value.startsWith('image/')) throw new TypeError('Content-Type must be image/*')
+  return value
+}
+
+function extensionFor(mediaType: string): string {
+  switch (mediaType) {
+    case 'image/jpeg': return '.jpg'
+    case 'image/png': return '.png'
+    case 'image/gif': return '.gif'
+    case 'image/webp': return '.webp'
+    case 'image/bmp': return '.bmp'
+    case 'image/tiff': return '.tiff'
+    case 'image/avif': return '.avif'
+    case 'image/heic': return '.heic'
+    case 'image/heif': return '.heif'
+    case 'image/svg+xml': return '.svg'
+    default: return '.img'
+  }
+}
+
+/** Convert an untrusted browser label into one portable leaf filename. */
+export function safePastedImageName(raw: string, mediaType: string): string {
+  const leaf = basename(raw.replaceAll('\\', '/')).normalize('NFC')
+  let cleaned = leaf
+    .replace(/[<>:"|?*\u0000-\u001f/\\]/gu, '_')
+    .replace(/\s+/gu, ' ')
+    .replace(/^\.+/u, '')
+    .trim()
+    .replace(/[. ]+$/u, '')
+  if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(cleaned)) cleaned = `_${cleaned}`
+  const fallback = `clipboard-image${extensionFor(mediaType)}`
+  const candidate = cleaned === '' || cleaned === '.' || cleaned === '..' ? fallback : cleaned
+  if (Buffer.byteLength(candidate) <= MAX_NAME_BYTES) return candidate
+  const extension = extname(candidate).slice(0, 20)
+  const budget = Math.max(1, MAX_NAME_BYTES - Buffer.byteLength(extension))
+  let stem = candidate.slice(0, Math.max(1, candidate.length - extension.length))
+  while (Buffer.byteLength(stem) > budget) stem = stem.slice(0, -1)
+  return `${stem}${extension}`
+}
+
+/** Reject a resolved path that is not rooted below the expected directory. */
+export function ensurePathInside(root: string, target: string): void {
+  const rel = relative(root, target)
+  if (rel !== '' && (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))) {
+    throw new Error(`resolved pasted-image path escapes its workspace root: ${target}`)
+  }
+}
+
+interface PasteRoot {
+  writeRoot: string
+  visibleRoot: string
+}
+
+async function ensureManagedDirectory(workspace: string, path: string): Promise<string> {
+  try {
+    await mkdir(path, { mode: 0o700 })
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error
+  }
+  const entry = await lstat(path)
+  if (entry.isSymbolicLink()) {
+    throw new Error(`resolved pasted-image path escapes its workspace root: symbolic link ${path}`)
+  }
+  if (!entry.isDirectory()) throw new Error(`pasted-image path is not a directory: ${path}`)
+  const canonical = await realpath(path)
+  ensurePathInside(workspace, canonical)
+  return canonical
+}
+
+async function sessionPasteRoot(ctx: Context, sessionId: string): Promise<PasteRoot> {
+  const session = ctx.sessions.get(sessionId as never)
+  if (session === undefined) throw new Error(`live Session not found: ${sessionId}`)
+  const cwd = session.header.cwd
+  if (cwd === undefined || !isAbsolute(cwd)) throw new Error(`Session has no absolute workspace: ${sessionId}`)
+
+  const visibleWorkspace = resolve(cwd)
+  const workspace = await realpath(visibleWorkspace)
+  const pluginRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
+  await ensureManagedDirectory(workspace, pluginRoot)
+  const temporaryRoot = join(pluginRoot, 'tmp')
+  await ensureManagedDirectory(workspace, temporaryRoot)
+  const requestedRoot = join(temporaryRoot, 'pasted-images')
+  const root = await ensureManagedDirectory(workspace, requestedRoot)
+
+  const sessionKey = createHash('sha256').update(sessionId).digest('hex').slice(0, 20)
+  const requestedSessionRoot = join(requestedRoot, sessionKey)
+  const sessionRoot = await ensureManagedDirectory(root, requestedSessionRoot)
+  ensurePathInside(root, sessionRoot)
+  return { writeRoot: sessionRoot, visibleRoot: requestedSessionRoot }
+}
+
+async function writeImage(
+  req: IncomingMessage,
+  directory: string,
+  filename: string,
+  expectedBytes: number,
+  maxBytes: number,
+): Promise<string> {
+  if (expectedBytes > maxBytes) throw new RangeError(`image exceeds the ${maxBytes}-byte paste limit`)
+  const id = randomUUID()
+  const finalPath = join(directory, `${id}-${filename}`)
+  const stagingPath = join(directory, `.${id}.partial`)
+  ensurePathInside(directory, finalPath)
+  ensurePathInside(directory, stagingPath)
+
+  const handle = await open(stagingPath, 'wx', 0o600)
+  let received = 0
+  try {
+    for await (const chunk of req) {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      received += bytes.length
+      if (received > expectedBytes || received > maxBytes) throw new RangeError('pasted image body exceeds its declared size')
+      await handle.write(bytes)
+    }
+    if (received !== expectedBytes) {
+      throw new Error(`pasted image body size mismatch: expected ${expectedBytes}, received ${received}`)
+    }
+    await handle.sync()
+    await handle.close()
+    await rename(stagingPath, finalPath)
+    return finalPath
+  } catch (error) {
+    await handle.close().catch(() => {})
+    await rm(stagingPath, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+/** Runtime limit face kept separate for focused backend tests. */
+export interface PasteImageRuntime {
+  maxImageBytes(): number
+}
+
+/** Same-origin, live-Session-bound image upload endpoint. */
+export class PastedImageBackend {
+  constructor(
+    private readonly ctx: Context,
+    private readonly runtime: PasteImageRuntime,
+  ) {}
+
+  async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (req.method !== 'POST') {
+      res.setHeader('Allow', 'POST')
+      requestError(res, 405, 'method-not-allowed', 'Use POST')
+      return
+    }
+    if (!sameOriginPost(req)) {
+      requestError(res, 403, 'origin-rejected', 'The request must originate from this DSH Web application')
+      return
+    }
+
+    try {
+      const url = new URL(req.url ?? PASTE_IMAGES_ROUTE, 'http://dsh.internal')
+      const sessionId = singleQuery(url, 'sessionId')
+      const size = declaredSize(url)
+      const mediaType = imageMediaType(req)
+      const filename = safePastedImageName(singleQuery(url, 'name'), mediaType)
+      const contentLength = req.headers['content-length']
+      if (contentLength !== undefined && Number(contentLength) !== size) {
+        throw new TypeError('Content-Length does not match the declared size')
+      }
+      const directory = await sessionPasteRoot(this.ctx, sessionId)
+      const writtenPath = await writeImage(req, directory.writeRoot, filename, size, this.runtime.maxImageBytes())
+      const absolutePath = join(directory.visibleRoot, basename(writtenPath))
+      responseJson(res, 201, { ok: true, value: { absolutePath, filename, bytes: size } })
+    } catch (error) {
+      const status = error instanceof RangeError ? 413 : 400
+      this.ctx.logger.warn('dsh-vision-toolkit pasted image rejected: %s', message(error))
+      requestError(res, status, 'paste-image-rejected', message(error))
+    }
+  }
+}