feat(compact): compaction capability seam — abstract CompactService interface

Adds the @deepseek-ai/dsh-compact interface package: the abstract
CompactService (ctx.compact) with compactIfNeeded / compactRegion, the
compact/* session-event types via SessionEventMap declaration merging, and the
capability-seam RFC. Wires the package into the three root tsconfigs and the
cordis catalog. A backend implementation lands separately.

packages/compact/compact/README.md

@@ -0,0 +1,52 @@
+# @deepseek-ai/dsh-compact
+
+The **compaction seam**: an abstract `CompactService` (`ctx.compact`) defining WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
+
+This package is the interface tier of the compaction capability, split so each concern evolves (and swaps) independently:
+
+| Package | Role |
+|---|---|
+| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` |
+| `@deepseek-ai/dsh-compact-basic` | a backend: char/4 estimation + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` |
+
+Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam RFC](../../../docs/rfc/proposed/feature/2026-06-18-compaction-capability-seam.md).
+
+## Service API (`ctx.compact`)
+
+Both methods are **abstract** — the backend owns the entire strategy (token estimation, retention policy, event sequencing, summarization).
+
+| Member | Semantics |
+|---|---|
+| `compactIfNeeded(session, systemPrompt?, model?)` | Estimate the history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. |
+| `compactRegion(session, start, end, model)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start > end`. |
+
+## Surface contract
+
+`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` may carry `surfaceOp`. A `compact/*` event therefore **cannot** appear on the surface. A successful compaction instead:
+
+1. appends `compact/start` (log-only) — acquires the lock,
+2. summarizes the range,
+3. appends `compact/summary` (log-only) — provenance: summary, range, shadowed seqs, token count,
+4. appends `compact/end` (log-only) — releases the lock,
+5. appends a single `user/message` with `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation**.
+
+`deriveMessages()` then renders the summary as a user-role message followed by the retained nodes. The shadowed events remain in the raw log, so replay is deterministic.
+
+## Blocking
+
+Compaction is serialized via a log-recorded lock: `compactRegion` refuses to start if the last `compact/start` has no matching `compact/end` after it. The lock is the log (not an in-memory mutex), so it survives replay and a persistence backend can detect an orphaned `compact/start` on reload. `compact/end` is appended even when summarization throws, so a failure can never wedge the lock.
+
+## Events
+
+The `compact/*` events extend `SessionEventMap` (merge-extensible) via declaration merging — they are session events, not cordis `Events`:
+
+| Event | Payload | On surface? |
+|---|---|---|
+| `compact/start` | `{ turn }` | no (log-only) |
+| `compact/summary` | `{ summary, compactedRange, compactedEventSeqs, tokenCount }` | no (log-only) |
+| `compact/end` | `{ turn, error? }` | no (log-only) |
+
+## Implementing a backend
+
+Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. See `@deepseek-ai/dsh-compact-basic` for the reference implementation.

packages/compact/compact/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@deepseek-ai/dsh-compact",
+  "description": "Abstract compaction service seam (ctx.compact) 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-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/compact/compact/src/index.ts

@@ -0,0 +1,102 @@
+/**
+ * The compaction service seam (`ctx.compact`): an abstract service defining
+ * WHAT compaction does — decide when to compact, summarize a range of
+ * conversation history into a single surface node — without saying HOW.
+ *
+ * Implementations subclass {@link CompactService}, implement
+ * {@link CompactService.compactIfNeeded} and {@link CompactService.compactRegion},
+ * and load as a plugin — registering as `ctx.compact` (one implementation per
+ * context). `@deepseek-ai/dsh-compact-basic` (char/4 estimation + token-budget
+ * retention + `ctx.llm.stream()` summarization) is the first. A tokenizer- or
+ * template-based backend swaps in without touching consumers.
+ *
+ * The split follows the capability-seams RFC — interface (this) /
+ * implementation (`dsh-compact-basic`) / consumer (a `/compact` tool, deferred)
+ * — modeled on the bash trio. Unlike `dsh-bash`, this interface necessarily
+ * depends on `dsh-session` and `dsh-llm`: the contract's verbs are defined over
+ * a `Session` and its output is the `ContentBlock` vocabulary. That deviation
+ * from the "interface depends only on cordis" guidance is intentional and
+ * recorded in the [compaction capability-seam RFC](../../../../docs/rfc/proposed/feature/2026-06-18-compaction-capability-seam.md).
+ *
+ * @module @deepseek-ai/dsh-compact
+ */
+
+import { Context, Service } from 'cordis'
+import type { Session } from '@deepseek-ai/dsh-session'
+import type { CompactionResult } from './types.ts'
+
+export type { CompactionResult } from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    compact: CompactService
+  }
+}
+
+/**
+ * Abstract compaction service. Subclass implement the two abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.compact` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Both core methods are abstract: the contract states WHAT compaction does,
+ * while the entire strategy — token estimation, retention policy, event
+ * sequencing, summarization — is a HOW decision owned by the implementation.
+ *
+ * Implementations MUST honor:
+ * - **Surface contract**: a successful compaction shadows the compacted surface
+ *   nodes with a SINGLE replacement node carrying the summary. Because
+ *   `SurfaceEventType` is a closed union, that node is a `user/message` with
+ *   `surfaceOp: { op:'replace', start, end }`; the `compact/*` events are
+ *   log-only (lock + provenance).
+ * - **Blocking**: no compaction begins while another is in progress for the
+ *   same session. The recommended mechanism is the log-recorded lock — append
+ *   `compact/start` before the slow work and `compact/end` after (even on
+ *   failure) — so the lock is visible to replay and crash recovery.
+ */
+export abstract class CompactService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'compact')
+  }
+
+  /**
+   * Check token pressure and compact if the conversation is too large.
+   *
+   * Estimates the current history size (optionally including a system prompt),
+   * and if it exceeds the backend's threshold, compacts an older range via
+   * {@link compactRegion}, keeping recent context intact.
+   *
+   * @param session - the session whose surface may be compacted.
+   * @param systemPrompt - optional system prompt, counted toward the estimate.
+   * @param model - optional summarization model (falls back to backend config).
+   * @returns the compaction result, or `null` if no compaction was needed.
+   */
+  abstract compactIfNeeded(
+    session: Session,
+    systemPrompt?: string,
+    model?: string,
+  ): Promise<CompactionResult | null>
+
+  /**
+   * Forcibly compact a range of surface nodes into a single summary node.
+   *
+   * `start` and `end` are inclusive seqs of surface nodes to shadow; the backend
+   * summarizes their content and appends a replacement surface node. Used by the
+   * (future) `/compact` tool and internally by {@link compactIfNeeded}.
+   *
+   * @param session - the session whose surface is mutated.
+   * @param start - inclusive seq of the first surface node to compact.
+   * @param end - inclusive seq of the last surface node to compact.
+   * @param model - summarization model.
+   * @throws if compaction is already in progress, or if `start`/`end` are not
+   *   valid surface nodes, or if `start > end`.
+   */
+  abstract compactRegion(
+    session: Session,
+    start: number,
+    end: number,
+    model: string,
+  ): Promise<CompactionResult>
+}
+
+export default CompactService

packages/compact/compact/src/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Compaction vocabulary: the result type and the `compact/*` session events.
+ *
+ * Extends {@link SessionEventMap} with `compact/*` event types via declaration
+ * merging. {@link SurfaceEventType} is deliberately NOT extended — `compact/*`
+ * events are log-only markers (lock + provenance); only the five
+ * surface-eligible types can carry `surfaceOp`. The actual surface mutation is
+ * performed by a separate `user/message` event carrying the summary (see the
+ * [compaction capability-seam RFC](../../../../docs/rfc/proposed/feature/2026-06-18-compaction-capability-seam.md)).
+ *
+ * Configuration lives in the backend, not here: the contract states WHAT
+ * compaction produces, while every tunable (context window, thresholds,
+ * retention budget) is a HOW decision owned by the implementation.
+ *
+ * @module @deepseek-ai/dsh-compact/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /** Marks the start of a compaction — log-only, holds the lock until `compact/end`. */
+    'compact/start': { turn: number }
+    /**
+     * Provenance record of a completed summarization — log-only, no surfaceOp.
+     * The summary content is in `data.summary`; the actual surface replacement
+     * is performed by a subsequent `user/message` event that shadows the
+     * compacted range.
+     */
+    'compact/summary': {
+      summary: ContentBlock[]
+      compactedRange: { startSeq: number; endSeq: number }
+      compactedEventSeqs: number[]
+      tokenCount: number
+    }
+    /** Marks the end of a compaction — log-only, releases the lock. `error` set if summarization failed. */
+    'compact/end': { turn: number; error?: string }
+  }
+}
+
+/** Result of a successful compaction operation. */
+export interface CompactionResult {
+  /** The seq of the appended `compact/start` event. */
+  startSeq: number
+  /** The seq of the appended `compact/summary` event. */
+  summarySeq: number
+  /** The seq of the appended `compact/end` event. */
+  endSeq: number
+  /** The summary content blocks produced by the backend. */
+  summary: ContentBlock[]
+  /** The seq range that was shadowed [start, end] inclusive. */
+  shadowedRange: { start: number; end: number }
+  /** The seq numbers of all shadowed surface nodes. */
+  shadowedSeqs: number[]
+  /** Estimated token count of the shadowed content. */
+  compactedTokenCount: number
+}

packages/compact/compact/tests/compact.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CompactService } from '@deepseek-ai/dsh-compact'
+import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+/**
+ * A trivial concrete CompactService implementing the abstract contract. The
+ * interface package owns no algorithm — these tests exercise the seam itself:
+ * service registration, the abstract method shape, and the `compact/*` event
+ * declaration merge.
+ */
+class StubCompactService extends CompactService {
+  override async compactIfNeeded(_session: Session, _systemPrompt?: string, _model?: string): Promise<CompactionResult | null> {
+    return null
+  }
+
+  override async compactRegion(session: Session, start: number, end: number, _model: string): Promise<CompactionResult> {
+    // Minimal stub honoring the lock + log-only event contract.
+    const startEvent = session.append('compact/start', { turn: 0 })
+    const summaryEvent = session.append('compact/summary', {
+      summary: [{ type: 'text', text: 'stub' }],
+      compactedRange: { startSeq: start, endSeq: end },
+      compactedEventSeqs: [],
+      tokenCount: 0,
+    })
+    const endEvent = session.append('compact/end', { turn: 0 })
+    return {
+      startSeq: startEvent.seq,
+      summarySeq: summaryEvent.seq,
+      endSeq: endEvent.seq,
+      summary: [{ type: 'text', text: 'stub' }],
+      shadowedRange: { start, end },
+      shadowedSeqs: [],
+      compactedTokenCount: 0,
+    }
+  }
+}
+
+describe('CompactService seam', () => {
+  it('registers as ctx.compact', () => {
+    const ctx = new Context()
+    void new StubCompactService(ctx)
+    expect(ctx.compact).toBeDefined()
+    expect(ctx.compact).toBeInstanceOf(StubCompactService)
+  })
+
+  it('disposing the fiber unregisters ctx.compact (HMR safety)', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(StubCompactService)
+    expect(ctx.compact).toBeInstanceOf(StubCompactService)
+    await fiber.dispose()
+    expect(ctx.compact).toBeUndefined()
+  })
+
+  it('exposes the abstract contract methods', async () => {
+    const ctx = new Context()
+    const svc = new StubCompactService(ctx)
+    expect(await svc.compactIfNeeded(new Session(SessionId('s')))).toBeNull()
+  })
+
+  it('compact/* events merge into SessionEventMap and are log-only', async () => {
+    const ctx = new Context()
+    const svc = new StubCompactService(ctx)
+    const session = new Session(SessionId('s'))
+
+    const result = await svc.compactRegion(session, 0, 0, 'm')
+
+    const startEvent = session.events.find(e => e.type === 'compact/start')
+    expect(startEvent).toBeDefined()
+    // Log-only: the compiler rejects surfaceOp on compact/* (not a SurfaceEventType);
+    // verify the runtime value is absent.
+    const raw = startEvent as unknown as { surfaceOp?: unknown }
+    expect(raw.surfaceOp).toBeUndefined()
+    expect(result.summarySeq).toBeGreaterThan(result.startSeq)
+    expect(result.endSeq).toBeGreaterThan(result.summarySeq)
+  })
+})

packages/compact/compact/tsconfig.json

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