Add abstract service interface packages

@deepseek-ai/dsh-llm: provider-neutral content-block vocabulary
(merge-extensible maps), raw StreamChunk protocol, ToolSchema,
abstract LlmAdapter, LlmService adapter registry, BlockAssembler.

@deepseek-ai/dsh-session: event-sourced Session (append-only log,
deriveMessages; context/steering render as tagged envelopes),
SessionStore, session/event + awaited session/flush durability seam.

@deepseek-ai/dsh-system-prompt: ordered sections + tool-schema
providers; assemble() through the system-prompt/assemble waterfall.
Tool schemas are part of the assembly by design.

@deepseek-ai/dsh-tools: tool registry feeding schemas into the
assembly; execute() through the tools/execute waterfall (the single
sandbox/permission/hook seam).

@deepseek-ai/dsh-agent: Agent interface (send/steer/inject/abort,
spawn/fork TODO seams), AgentRegistry, and the full agent/* event
taxonomy so plugins never depend on the concrete loop.

packages/tools/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@deepseek-ai/dsh-tools",
+  "description": "Tool registry and execution pipeline for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/tools/src/index.ts

@@ -0,0 +1,117 @@
+import { Context, Service } from 'cordis'
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+declare module 'cordis' {
+  interface Context {
+    tools: ToolRegistry
+  }
+
+  interface Events {
+    /**
+     * Waterfall around every tool execution — the single seam where sandbox,
+     * permission, hook, and plan-mode plugins wrap or veto a call. Listeners
+     * receive `(exec, next)`: call `next()` to proceed (possibly around your
+     * own logic), or return a ToolExecutionResult without calling `next()`
+     * to short-circuit (veto).
+     */
+    'tools/execute'(this: ToolRegistry, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
+    /** A tool was registered or unregistered. */
+    'tools/change'(): void
+  }
+}
+
+// TODO(review): revisit these shapes when the first real tools and
+// sandbox/permission plugins land (e.g. a concurrency-safety hint for
+// parallel execution — Claude Code partitions read-only tools; phase 1
+// executes sequentially).
+
+/** A registered tool: its schema plus the execution function. */
+export interface ToolDefinition extends ToolSchema {
+  execute(args: unknown, exec: ToolExecution): Promise<ContentBlock[]>
+}
+
+/** One pending tool call, as it flows through the execution waterfall. */
+export interface ToolExecution {
+  callId: string
+  name: string
+  /** Parsed JSON arguments (unknown — tools validate their own input). */
+  arguments: unknown
+  /** The agent on whose behalf the call runs (set by the agent loop). */
+  agent?: Agent
+  signal?: AbortSignal
+}
+
+/** The outcome of one tool call. */
+export interface ToolExecutionResult {
+  callId: string
+  content: ContentBlock[]
+  isError: boolean
+}
+
+/**
+ * Tool registry (`ctx.tools`): tool plugins register definitions; the agent
+ * loop executes calls through the `tools/execute` waterfall. The registry
+ * contributes its schemas into the system-prompt assembly.
+ */
+export class ToolRegistry extends Service {
+  static inject = ['systemPrompt']
+
+  private store = new Map<string, ToolDefinition>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'tools')
+    ctx.systemPrompt.tools(() => this.schemas())
+  }
+
+  /** Register a tool. Disposed with the calling fiber. */
+  register(definition: ToolDefinition): () => void {
+    return this.ctx.effect(() => {
+      if (this.store.has(definition.name)) {
+        throw new Error(`tool "${definition.name}" is already registered`)
+      }
+      this.store.set(definition.name, definition)
+      this.ctx.emit('tools/change')
+      return () => {
+        this.store.delete(definition.name)
+        this.ctx.emit('tools/change')
+      }
+    }, 'tools.register()')
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.store.get(name)
+  }
+
+  /** Schemas of all registered tools (without the execute functions). */
+  schemas(): ToolSchema[] {
+    return [...this.store.values()].map(({ execute, ...schema }) => schema)
+  }
+
+  /** Execute one tool call through the `tools/execute` waterfall. */
+  execute(exec: ToolExecution): Promise<ToolExecutionResult> {
+    return this.ctx.waterfall(this, 'tools/execute', exec, async (): Promise<ToolExecutionResult> => {
+      const tool = this.store.get(exec.name)
+      if (!tool) {
+        return {
+          callId: exec.callId,
+          content: [{ type: 'text', text: `Error: unknown tool "${exec.name}"` }],
+          isError: true,
+        }
+      }
+      try {
+        const content = await tool.execute(exec.arguments, exec)
+        return { callId: exec.callId, content, isError: false }
+      } catch (error: any) {
+        return {
+          callId: exec.callId,
+          content: [{ type: 'text', text: `Error: ${error?.message ?? error}` }],
+          isError: true,
+        }
+      }
+    })
+  }
+}
+
+export default ToolRegistry

packages/tools/tests/tools.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+const echoTool = {
+  name: 'echo',
+  description: 'echo arguments back',
+  parameters: { type: 'object', properties: { text: { type: 'string' } } },
+  async execute(args: any) {
+    return [{ type: 'text' as const, text: String(args?.text ?? '') }]
+  },
+}
+
+describe('ToolRegistry', () => {
+  it('registers tools, exposes schemas, and feeds the system-prompt assembly', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+
+    expect(ctx.tools.schemas()).toEqual([{
+      name: 'echo',
+      description: 'echo arguments back',
+      parameters: { type: 'object', properties: { text: { type: 'string' } } },
+    }])
+    // schemas() result must not leak execute
+    expect((ctx.tools.schemas()[0] as any).execute).toBeUndefined()
+
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.tools.map(t => t.name)).toEqual(['echo'])
+  })
+
+  it('executes a tool and returns its content', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    const result = await ctx.tools.execute({ callId: 'c1', name: 'echo', arguments: { text: 'hi' } })
+    expect(result).toEqual({ callId: 'c1', content: [{ type: 'text', text: 'hi' }], isError: false })
+  })
+
+  it('returns isError results for unknown tools and throwing tools', async () => {
+    const ctx = await setup()
+    ctx.tools.register({
+      ...echoTool,
+      name: 'boom',
+      async execute() {
+        throw new Error('exploded')
+      },
+    })
+
+    const unknown = await ctx.tools.execute({ callId: 'c1', name: 'nope', arguments: {} })
+    expect(unknown.isError).toBe(true)
+
+    const thrown = await ctx.tools.execute({ callId: 'c2', name: 'boom', arguments: {} })
+    expect(thrown.isError).toBe(true)
+    expect(thrown.content[0]).toMatchObject({ text: 'Error: exploded' })
+  })
+
+  it('lets tools/execute waterfall listeners veto a call (permission pattern)', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+
+    ctx.on('tools/execute', async (exec, next): Promise<ToolExecutionResult> => {
+      if (exec.name === 'echo') {
+        return {
+          callId: exec.callId,
+          content: [{ type: 'text', text: 'denied by policy' }],
+          isError: true,
+        }
+      }
+      return next()
+    })
+
+    const result = await ctx.tools.execute({ callId: 'c1', name: 'echo', arguments: { text: 'hi' } })
+    expect(result.isError).toBe(true)
+    expect(result.content[0]).toMatchObject({ text: 'denied by policy' })
+  })
+
+  it('composes multiple tools/execute listeners (sandbox-wrap pattern)', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+
+    const order: string[] = []
+    ctx.on('tools/execute', async (exec, next) => {
+      order.push('first:before')
+      const result = await next()
+      order.push('first:after')
+      return result
+    })
+    ctx.on('tools/execute', async (exec, next) => {
+      order.push('second:before')
+      const result = await next()
+      order.push('second:after')
+      return result
+    })
+
+    const result = await ctx.tools.execute({ callId: 'c1', name: 'echo', arguments: { text: 'x' } })
+    expect(result.isError).toBe(false)
+    expect(order).toEqual(['first:before', 'second:before', 'second:after', 'first:after'])
+  })
+
+  it('rejects duplicate names and unregisters on fiber dispose (HMR safety)', async () => {
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+    expect(() => ctx.tools.register(echoTool)).toThrow('already registered')
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.tools.register({ ...echoTool, name: 'scoped' })
+    }, { inject: ['tools'] }))
+    expect(ctx.tools.schemas().map(t => t.name)).toEqual(['echo', 'scoped'])
+
+    await fiber.dispose()
+    expect(ctx.tools.schemas().map(t => t.name)).toEqual(['echo'])
+  })
+})

packages/tools/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../vendor/cosmokit" },
+    { "path": "../../vendor/cordis" },
+    { "path": "../llm" },
+    { "path": "../system-prompt" },
+    { "path": "../agent" }
+  ]
+}