DeepSeek Harness Series (10): Building a Complete dsh Plugin — From Requirements to Production

// packages/workspace-context/src/index.ts

// Plugin name: unique identifier in the Cordis dependency tree
export const name = 'workspace-context'

// Declare service dependencies.
// Cordis ensures these services are ready before calling apply.
// If a service is unavailable, the plugin suspends (no crash — just waits).
export const inject = ['tools', 'systemPrompt']

// Plugin entry point.
// ctx is the private Cordis context for this plugin.
// Everything registered through ctx (tools, prompt sections, event listeners)
// is bound to this context's lifecycle — automatically disposed when the plugin unloads.
export function apply(ctx: Context): void {
  // All registration goes here
}

// Inject workspace information into the system prompt
ctx.systemPrompt.section({
  name: 'workspace-context:cwd',
  // Place this section after Agent instructions, before user-facing prompts
  order: ctx.systemPrompt.getSectionOrder('context:workspace'),
  // Dynamic text: re-evaluated every time the system prompt is assembled.
  // If the working directory changes mid-session, the next request gets the fresh value.
  text: (context) => {
    const cwd = context.agent?.session?.header?.cwd
    if (!cwd) return ''  // No cwd available — inject nothing
    return [
      '## Workspace',
      `Current working directory: ${cwd}`,
      'All relative file paths are resolved from this directory.',
    ].join('\n')
  },
})

import { defineTool } from '@deepseek-ai/dsh-tools'
import { readdir, stat } from 'node:fs/promises'
import { join } from 'node:path'

ctx.tools.register(defineTool({
  name: 'get_workspace_info',
  description: 'Get information about the current workspace: directory listing and file sizes.',

  parameters: {
    path: {
      type: 'string',
      description: 'Relative path within the workspace. Defaults to workspace root.',
    },
  },

  output: {
    schema: {
      // Strict mode: additionalProperties: false prevents unexpected fields from the model
      type: 'object',
      additionalProperties: false,
      properties: {
        path: { type: 'string' },
        entries: {
          type: 'array',
          items: {
            type: 'object',
            additionalProperties: false,
            properties: {
              name: { type: 'string' },
              type: { type: 'string', enum: ['file', 'directory'] },
              size: { type: 'number' },
            },
          },
        },
      },
    },
    // render converts the structured return value into model-readable text.
    // Separating 'structured data' from 'what the model sees' is a core dsh design principle.
    render: (_args, value) => {
      const v = value as {
        path: string
        entries: Array<{ name: string; type: string; size: number }>
      }
      const lines = [`Directory: ${v.path}`, '']
      for (const entry of v.entries) {
        const sizeStr = entry.type === 'file' ? ` (${entry.size} bytes)` : '/'
        lines.push(`  ${entry.name}${sizeStr}`)
      }
      return [{ type: 'text', text: lines.join('\n') }]
    },
  },

  // Read-only operation. Doesn't modify any state.
  // Safe to run in parallel with other tools.
  isConcurrencySafe: () => true,

  async execute(args, exec) {
    // Pull cwd from the session header; fall back to process.cwd() if absent
    const cwd = exec.agent?.session?.header?.cwd ?? process.cwd()
    const targetPath = args.path ? join(cwd, args.path) : cwd

    const entries = await readdir(targetPath, { withFileTypes: true })
    const result = await Promise.all(
      entries.map(async (entry) => {
        const fullPath = join(targetPath, entry.name)
        // Only call stat on files (to get size) — directories don't need it
        const stats = entry.isFile() ? await stat(fullPath) : null
        return {
          name: entry.name,
          type: entry.isDirectory() ? 'directory' : 'file',
          size: stats?.size ?? 0,
        }
      })
    )

    return {
      path: targetPath,
      // Directories first, then files; alphabetical within each group
      entries: result.sort((a, b) => {
        if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
        return a.name.localeCompare(b.name)
      }),
    }
  },
}))

// Intercept tool calls whose names contain 'delete' or 'rm'.
// Returning { kind: 'ask' } pauses execution and waits for user confirmation.
// Returning { kind: 'deny' } rejects the call immediately — the tool never runs.
ctx.on('tools/pre-execute', async (exec, next) => {
  const isDangerous = exec.name.includes('delete') || exec.name.includes('rm')

  // Not dangerous: let it through, continue the execution chain
  if (!isDangerous) return next()

  // Dangerous: require confirmation.
  // If no approval service is configured in the Bundle,
  // 'ask' automatically degrades to 'deny'.
  return {
    kind: 'ask',
    reason: `About to run: ${exec.name}(${exec.arguments})`,
  }
})

// Wrap every tool execution to measure elapsed time.
// tools/execute is a middleware hook — every tool call passes through it.
ctx.on('tools/execute', async (exec, next) => {
  const start = performance.now()

  // Call next() to run the actual tool implementation
  const result = await next()

  const elapsed = Math.round(performance.now() - start)

  // result.isError is the standardized error flag.
  // Here we log to console; in a real project, route to ctx.sessionTelemetry.
  console.log(`[${exec.name}] ${result.isError ? 'ERROR' : 'OK'} ${elapsed}ms`)

  // Must return result — otherwise the tool's return value is lost
  return result
})

// Listen to session/event and print a summary when each Turn ends
ctx.on('session/event', (session, event) => {
  if (event.type !== 'turn/end') return

  // reason.kind is why the Turn ended:
  // 'complete'    — normal completion (model decided the task is done)
  // 'error'       — something went wrong
  // 'interrupted' — user interrupted
  // 'max-turns'   — hit the max turn count limit
  const reason = event.data.reason.kind
  const turnNum = event.data.turn

  console.log(`[Turn ${turnNum}] ${reason}`)
})

// packages/workspace-context/src/index.ts
// workspace-context plugin: workspace awareness + tool + permission interception + observability

import { defineTool } from '@deepseek-ai/dsh-tools'
import { readdir, stat } from 'node:fs/promises'
import { join } from 'node:path'

// ── Plugin metadata ────────────────────────────────────────────
export const name = 'workspace-context'

// Declare service dependencies
// tools:        tool registry
// systemPrompt: system prompt section manager
export const inject = ['tools', 'systemPrompt']

// ── Plugin entry point ─────────────────────────────────────────
export function apply(ctx: Context): void {

  // ── 1. Inject a System Prompt Section ─────────────────────────
  ctx.systemPrompt.section({
    name: 'workspace-context:cwd',
    order: ctx.systemPrompt.getSectionOrder('context:workspace'),
    text: (context) => {
      const cwd = context.agent?.session?.header?.cwd
      if (!cwd) return ''
      return [
        '## Workspace',
        `Current working directory: ${cwd}`,
        'All relative file paths are resolved from this directory.',
      ].join('\n')
    },
  })

  // ── 2. Register the get_workspace_info tool ────────────────────
  ctx.tools.register(defineTool({
    name: 'get_workspace_info',
    description: 'Get information about the current workspace: directory listing and file sizes.',
    parameters: {
      path: {
        type: 'string',
        description: 'Relative path within the workspace. Defaults to workspace root.',
      },
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          path: { type: 'string' },
          entries: {
            type: 'array',
            items: {
              type: 'object',
              additionalProperties: false,
              properties: {
                name: { type: 'string' },
                type: { type: 'string', enum: ['file', 'directory'] },
                size: { type: 'number' },
              },
            },
          },
        },
      },
      render: (_args, value) => {
        const v = value as {
          path: string
          entries: Array<{ name: string; type: string; size: number }>
        }
        const lines = [`Directory: ${v.path}`, '']
        for (const entry of v.entries) {
          const sizeStr = entry.type === 'file' ? ` (${entry.size} bytes)` : '/'
          lines.push(`  ${entry.name}${sizeStr}`)
        }
        return [{ type: 'text', text: lines.join('\n') }]
      },
    },
    isConcurrencySafe: () => true,
    async execute(args, exec) {
      const cwd = exec.agent?.session?.header?.cwd ?? process.cwd()
      const targetPath = args.path ? join(cwd, args.path) : cwd
      const entries = await readdir(targetPath, { withFileTypes: true })
      const result = await Promise.all(
        entries.map(async (entry) => {
          const fullPath = join(targetPath, entry.name)
          const stats = entry.isFile() ? await stat(fullPath) : null
          return {
            name: entry.name,
            type: entry.isDirectory() ? 'directory' : 'file',
            size: stats?.size ?? 0,
          }
        })
      )
      return {
        path: targetPath,
        entries: result.sort((a, b) => {
          if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
          return a.name.localeCompare(b.name)
        }),
      }
    },
  }))

  // ── 3. Permission interception: require confirmation for dangerous tools ──
  ctx.on('tools/pre-execute', async (exec, next) => {
    const isDangerous = exec.name.includes('delete') || exec.name.includes('rm')
    if (!isDangerous) return next()
    return {
      kind: 'ask',
      reason: `About to run: ${exec.name}(${exec.arguments})`,
    }
  })

  // ── 4. Execution time metering ─────────────────────────────────
  ctx.on('tools/execute', async (exec, next) => {
    const start = performance.now()
    const result = await next()
    const elapsed = Math.round(performance.now() - start)
    console.log(`[${exec.name}] ${result.isError ? 'ERROR' : 'OK'} ${elapsed}ms`)
    return result
  })

  // ── 5. Session Turn summary observation ───────────────────────
  ctx.on('session/event', (session, event) => {
    if (event.type !== 'turn/end') return
    const reason = event.data.reason.kind
    const turnNum = event.data.turn
    console.log(`[Turn ${turnNum}] ${reason}`)
  })

  // ── Note ───────────────────────────────────────────────────────
  // No cleanup code anywhere in this file.
  // Every registration made through ctx (tools.register, systemPrompt.section, ctx.on)
  // is tracked by Cordis and automatically disposed when the plugin unloads.
}

// bundle.ts (pseudocode: Bundle configuration file)
import workspaceContext from './packages/workspace-context/src/index.ts'

export default defineBundle([
  // Core service providers must be listed before the plugins that depend on them.
  // workspace-context declares inject: ['tools', 'systemPrompt'],
  // so both providers must appear before it.
  coreToolsPlugin,          // provides the tools service
  systemPromptPlugin,       // provides the systemPrompt service

  workspaceContext,         // our plugin

  // Other business plugins...
])