Merge remote-tracking branch 'origin/master' into feat/adr0016-type-build-check

packages/core/system-prompt/README.md

@@ -0,0 +1,37 @@
+# dsh-system-prompt
+
+System prompt assembly registry. Plugins contribute ordered text sections and tool-schema providers; the agent loop calls `assemble()` once per step.
+
+## Service: `SystemPrompt` (ctx key: `systemPrompt`)
+
+### Public API
+
+- `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. Disposed with the calling fiber.
+- `ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void` Contribute tool schemas (evaluated at each assembly). Disposed with the calling fiber.
+- `ctx.systemPrompt.assemble(): Promise<PromptAssembly>` Assemble the current prompt. Runs through the `system-prompt/assemble` waterfall.
+
+### Events
+
+| Event | Mode | Purpose |
+|---|---|---|
+| `system-prompt/assemble` | waterfall | Mutate/extend the assembly before it reaches the model |
+| `system-prompt/change` | emit | A section or tool provider was registered or unregistered |
+
+### Key types
+
+- `PromptSection` — `{ name, order, text: string | (() => string) }`. Sections are concatenated in ascending `order`.
+- `PromptAssembly` — `{ sections: PromptSection[], tools: ToolSchema[] }`. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.
+- `renderPrompt(assembly)` — joins section texts with blank lines.
+
+Merge-extensible: plugins can declare extra fields on `PromptAssembly` via declaration merging.
+
+### Extension points
+
+- Section providers: AGENTS.md reader, cwd notifier, persona config, etc.
+- Tool schema providers: `ToolRegistry` registers itself as a tool provider automatically.
+- The `system-prompt/assemble` waterfall: mutate or replace the assembly (system-prompt configurability, dynamic tool filtering).
+
+### What is NOT here
+
+- Any hardcoded prompt text — every section comes from plugins.
+- Prompt compaction (belongs on the `agent/request` seam in `dsh-agent`).

packages/core/system-prompt/package.json

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

packages/core/system-prompt/src/index.ts

@@ -0,0 +1,148 @@
+/**
+ * System prompt assembly registry. Plugins contribute ordered text sections and
+ * tool schema providers; `assemble()` collates them through a waterfall that
+ * runs once per step.
+ *
+ * @module @deepseek-ai/dsh-system-prompt
+ */
+
+import { Context, Service } from 'cordis'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+declare module 'cordis' {
+  interface Context {
+    systemPrompt: SystemPrompt
+  }
+
+  interface Events {
+    /**
+     * Waterfall around prompt assembly — mutate or extend the
+     * {@link PromptAssembly} (sections + tool schemas) before it is rendered.
+     * Bound to the {@link SystemPrompt} service; call `next()` to delegate.
+     * @mode waterfall
+     */
+    'system-prompt/assemble'(this: SystemPrompt, assembly: PromptAssembly, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+    /**
+     * A section or tool provider was registered or unregistered (the assembly
+     * inputs changed).
+     * @mode emit
+     */
+    'system-prompt/change'(): void
+  }
+}
+
+/** One contributed section of the system prompt. */
+export interface PromptSection {
+  /** Unique name (diagnostics / dedup). */
+  name: string
+  /** Sections are concatenated in ascending order. */
+  order: number
+  /** Static text or a provider evaluated at each assembly. */
+  text: string | (() => string)
+}
+
+/**
+ * The assembled prompt.
+ *
+ * Tool schemas are part of the assembly by design: "what the model is told it
+ * can do" is one coherent thing managed here, even though adapters transmit
+ * `tools` as a separate wire field rather than prompt text.
+ *
+ * Merge-extensible: plugins can declare extra fields on this interface.
+ */
+export interface PromptAssembly {
+  sections: PromptSection[]
+  tools: ToolSchema[]
+}
+
+/** Renders the text part of an assembly (sections joined by blank lines). */
+export function renderPrompt(assembly: PromptAssembly): string {
+  return assembly.sections
+    .map(section => typeof section.text === 'function' ? section.text() : section.text)
+    .filter(text => text.length > 0)
+    .join('\n\n')
+}
+
+/**
+ * Registry service (`ctx.systemPrompt`): plugins contribute ordered text
+ * sections and tool-schema providers; the agent loop calls `assemble()` once
+ * per step.
+ */
+export class SystemPrompt extends Service {
+  private sections: PromptSection[] = []
+  private toolProviders: (() => ToolSchema[])[] = []
+
+  constructor(ctx: Context) {
+    super(ctx, 'systemPrompt')
+  }
+
+  /**
+   * Contribute a text section to the system prompt. Order is determined by
+   * `section.order` (ascending). The section is removed when the calling
+   * fiber is disposed. Emits `system-prompt/change` on register/unregister.
+   */
+  section(section: PromptSection): () => void {
+    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
+      this.sections.push(section)
+      // Yield the rollback BEFORE emitting `system-prompt/change`: a generator
+      // effect collects each yielded disposer before the next step runs, so a
+      // throwing change listener removes the section instead of leaking it into
+      // every future assembly.
+      yield () => {
+        const index = this.sections.indexOf(section)
+        /* v8 ignore next 3 -- defensive: section was registered, so indexOf is guaranteed >= 0 */
+        if (index >= 0) this.sections.splice(index, 1)
+        this.ctx.emit('system-prompt/change')
+      }
+      this.ctx.emit('system-prompt/change')
+    }.bind(this), 'systemPrompt.section()')
+    // ctx.effect's disposer returns Promise<void>; our disposer API is
+    // synchronous fire-and-forget — discard the (always-resolved) promise.
+    return () => void dispose()
+  }
+
+  /**
+   * Contribute a tool-schema provider that is evaluated at each assembly
+   * call (so it can reflect the live registry state). The provider is
+   * removed when the calling fiber is disposed. Emits `system-prompt/change`.
+   */
+  tools(provider: () => ToolSchema[]): () => void {
+    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
+      this.toolProviders.push(provider)
+      // Yield the rollback BEFORE emitting `system-prompt/change` (see section()).
+      yield () => {
+        const index = this.toolProviders.indexOf(provider)
+        /* v8 ignore next 3 -- defensive: provider was registered, so indexOf is guaranteed >= 0 */
+        if (index >= 0) this.toolProviders.splice(index, 1)
+        this.ctx.emit('system-prompt/change')
+      }
+      this.ctx.emit('system-prompt/change')
+    }.bind(this), 'systemPrompt.tools()')
+    // ctx.effect's disposer returns Promise<void>; our disposer API is
+    // synchronous fire-and-forget — discard the (always-resolved) promise.
+    return () => void dispose()
+  }
+
+  /**
+   * Assemble the current prompt (sections sorted by order, tools collected
+   * from all providers). Section records are top-level clones (the `text`
+   * provider may be a function and is intentionally shared); tool schemas are
+   * deep-cloned because adapters and request waterfalls may mutate schema
+   * objects. Runs through the `system-prompt/assemble` waterfall, giving
+   * listeners the opportunity to mutate or replace the assembly before it
+   * reaches the model. Await the result before reading the assembly values —
+   * waterfall listeners may be async.
+   */
+  assemble(): Promise<PromptAssembly> {
+    const assembly: PromptAssembly = {
+      sections: this.sections
+        .map(section => ({ ...section }))
+        .sort((a, b) => a.order - b.order),
+      tools: this.toolProviders.flatMap(provider =>
+        provider().map(tool => ({ ...tool, parameters: structuredClone(tool.parameters) }))),
+    }
+    return this.ctx.waterfall(this, 'system-prompt/assemble', assembly, () => Promise.resolve(assembly))
+  }
+}
+
+export default SystemPrompt

packages/core/system-prompt/tests/system-prompt.spec.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt, { PromptAssembly, PromptSection, renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+
+describe('SystemPrompt', () => {
+  it('assembles sections in order with dynamic text and collected tools', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are DeepSeek Code.' })
+    ctx.systemPrompt.section({ name: 'cwd', order: 20, text: () => 'cwd: /tmp' })
+    ctx.systemPrompt.section({ name: 'rules', order: 10, text: 'Be precise.' })
+    ctx.systemPrompt.tools(() => [{ name: 'echo', description: 'echo back', parameters: {} }])
+
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.map(s => s.name)).toEqual(['persona', 'rules', 'cwd'])
+    expect(assembly.tools).toEqual([{ name: 'echo', description: 'echo back', parameters: {} }])
+    expect(renderPrompt(assembly)).toBe('You are DeepSeek Code.\n\nBe precise.\n\ncwd: /tmp')
+  })
+
+  it('removes contributions when the contributing fiber is disposed (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.systemPrompt.section({ name: 'scoped', order: 0, text: 'scoped section' })
+      inner.systemPrompt.tools(() => [{ name: 'scoped-tool', description: '', parameters: {} }])
+    }, { inject: ['systemPrompt'] }))
+
+    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(1)
+    await fiber.dispose()
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections).toHaveLength(0)
+    expect(assembly.tools).toHaveLength(0)
+  })
+
+  it('rolls back a section when a system-prompt/change listener throws (P1-1)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    // Throw on the first emit only. Note the rollback path itself emits
+    // system-prompt/change, so a multi-shot guard would also fire on rollback;
+    // a single-shot guard isolates the register's own emit.
+    let threw = false
+    const off = ctx.on('system-prompt/change', () => {
+      if (!threw) { threw = true; throw new Error('boom change listener') }
+    })
+
+    expect(() => ctx.systemPrompt.section({ name: 'p', order: 0, text: 'persona' })).toThrow('boom change listener')
+    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(0) // nothing leaked
+
+    // Subsequent listener-free register contributes exactly once.
+    off()
+    ctx.systemPrompt.section({ name: 'p', order: 0, text: 'persona' })
+    expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['p'])
+  })
+
+  it('rolls back a tool provider when a system-prompt/change listener throws (P1-1)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    let threw = false
+    const off = ctx.on('system-prompt/change', () => {
+      if (!threw) { threw = true; throw new Error('boom change listener') }
+    })
+
+    expect(() => ctx.systemPrompt.tools(() => [{ name: 't', description: '', parameters: {} }])).toThrow('boom change listener')
+    expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(0) // nothing leaked
+
+    off()
+    ctx.systemPrompt.tools(() => [{ name: 't', description: '', parameters: {} }])
+    expect((await ctx.systemPrompt.assemble()).tools.map(t => t.name)).toEqual(['t'])
+  })
+
+  it('composes multiple system-prompt/assemble waterfall listeners in order', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'base', order: 0, text: 'base' })
+
+    // Listener A appends a section, then delegates.
+    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, next) => {
+      assembly.sections.push({ name: 'from-a', order: 100, text: 'a' })
+      return next()
+    })
+    // Listener B (registered later, runs after A) sees A's contribution.
+    const seen: string[][] = []
+    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, next) => {
+      seen.push(assembly.sections.map(s => s.name))
+      return next()
+    })
+
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(seen).toEqual([['base', 'from-a']])
+    expect(assembly.sections.map(s => s.name)).toEqual(['base', 'from-a'])
+  })
+
+  it('lets a waterfall listener short-circuit by not calling next()', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'real', order: 0, text: 'real' })
+
+    ctx.on('system-prompt/assemble', async () => {
+      return { sections: [], tools: [] } satisfies PromptAssembly
+    })
+
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections).toHaveLength(0)
+  })
+
+  it('assembles snapshots so one-step mutations do not leak into future assemblies', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'base', order: 0, text: 'base' })
+    ctx.systemPrompt.tools(() => [{ name: 't', description: 'tool', parameters: { type: 'object', properties: {} } }])
+
+    const first = await ctx.systemPrompt.assemble()
+    first.sections[0]!.name = 'mutated'
+    first.tools[0]!.description = 'mutated'
+    const firstParameters = first.tools[0]!.parameters as { properties: Record<string, unknown> }
+    firstParameters.properties['leak'] = { type: 'string' }
+
+    const second = await ctx.systemPrompt.assemble()
+    expect(second.sections.map(section => section.name)).toEqual(['base'])
+    expect(second.tools).toEqual([{ name: 't', description: 'tool', parameters: { type: 'object', properties: {} } }])
+  })
+
+  it('filters out empty section text from renderPrompt', () => {
+    // Direct test of renderPrompt: function returning empty string, and empty static text
+    const result = renderPrompt({
+      sections: [
+        { name: 'empty-fn', order: 0, text: () => '' },
+        { name: 'real', order: 1, text: 'content' },
+        { name: 'empty-static', order: 2, text: '' },
+      ],
+      tools: [],
+    })
+    expect(result).toBe('content')
+  })
+
+  it('evaluates dynamic function-text sections at each renderPrompt call', () => {
+    let counter = 0
+    const section: PromptSection = { name: 'dynamic', order: 0, text: () => `call ${++counter}` }
+    expect(renderPrompt({ sections: [section], tools: [] })).toBe('call 1')
+    expect(renderPrompt({ sections: [section], tools: [] })).toBe('call 2')
+  })
+
+  it('emits system-prompt/change when a tool provider is registered and disposed', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    const changes: number = 0
+    let changeCount = 0
+    ctx.on('system-prompt/change', () => void changeCount++)
+
+    const dispose = ctx.systemPrompt.tools(() => [])
+    // registration emits change
+    expect(changeCount).toBe(1)
+
+    dispose()
+    // disposal emits change again
+    expect(changeCount).toBe(2)
+    void changes // silence unused
+  })
+
+  it('cleans up tool providers on fiber dispose', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.systemPrompt.tools(() => [{ name: 'fiber-tool', description: '', parameters: {} }])
+    }, { inject: ['systemPrompt'] }))
+
+    expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(1)
+    await fiber.dispose()
+    expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(0)
+  })
+
+  it('removes section when returned disposer is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    const dispose = ctx.systemPrompt.section({ name: 'direct', order: 0, text: 'direct section' })
+    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(1)
+
+    dispose()
+    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(0)
+  })
+
+  it('removes tool provider when returned disposer is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    const dispose = ctx.systemPrompt.tools(() => [{ name: 'direct-tool', description: '', parameters: {} }])
+    expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(1)
+
+    dispose()
+    expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(0)
+  })
+})

packages/core/system-prompt/tsconfig.json

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