col-dsh-plugin — COL as a DeepSeek Harness / Cordis plugin

English · 简体中文

Context Organization Layer, as a real DSH service. Contexts are persistent organizational slots (positions); Agents/Models are replaceable executors (staff rotate, the position stays); every write-back is verified (3-tier) and every action is audited. Install it into DeepSeek Harness and your agents get a durable, contamination-resistant, auditable "org memory" — plus a model-callable tool to create Contexts.

Zero runtime dependencies besides the peer @deepseek-ai/cordis that DSH already provides. The core (context-service, governance) is bundled inline.

---

Why this exists (the 10-second pitch)

Long-running agent systems degrade in three ways — this plugin targets exactly those:

Degradation	What COL does
Executor churn — swap model/agent and lose state	Contexts persist by design; swapping an executor never touches Context state (verified loss = 0 in live tests)
Context rot — stale/misleading docs poison later runs	Executors only ever see a compiled, need-to-know Brief; what they can't be trusted with never reaches them
No accountability — who did what, under which constraint?	Every mutation is an append-only event with attribution; lifecycle changes require governance, never the executor itself

Honest boundary (same tone as our verdict): this guarantees continuity, hygiene and auditability — not output quality. Quality is bounded by verifier × model, and no architecture removes that. On short one-shot tasks the layer is pure overhead by design; use it where org-scale properties matter.

---

中文摘要

COL（Context Organization Layer）现在可以作为 DSH 插件安装。 Context = 持久职位（组织槽位）；Agent/Model = 可换员工（换人不丢状态）；写回必须过验证（asserted/inferred/verified 三分层）；一切动作 append-only 可审计。装上后 agent 生态获得：①换执行器状态零丢失（live 实测）；②上下文污染免疫（编译选择而非提示运气）；③全动作可追溯。本包自包含（核心内联），仅依赖 DSH 已提供的 @deepseek-ai/cordis。MVP 边界与判词见 ContextForge。

---

Quickstart

1. Install

# inside your DSH project
npm i col-dsh-plugin

2. Mount it

Add to your DSH assembly (a cordis.patch.yml overlay on the base/headless profile, or your app cordis.yml):

- id: col
  name: 'col-dsh-plugin'
  config:
    dataDir: '/var/lib/col'    # optional; default ~/.col/ctx-data

3. Verify it loaded

The service registers as ctx.col. A model (or any tool caller) can invoke the registered tool col.create_context to mint a persistent Context (see example). In your DSH context:

// any plugin with `inject: ['col']` can use it:
const ref = await ctx.col.create({ kind: 'domain', role: 'backend' })
await ctx.col.activate(ref)
console.log(await ctx.col.get(ref))   // durable, rev-tracked org slot

Example: give the model the tool

examples/col-tool.mjs (drop into your overlay as a plugin, inject: ['tools', 'col']):

ctx.tools.register(defineTool({
  name: 'col.create_context',
  description: 'Create a new persistent Context (organizational slot).',
  parameters: {
    kind: { type: 'string', required: true, description: 'domain | task' },
    role: { type: 'string', required: true },
  },
  output: {
    schema: { type: 'object', additionalProperties: true },
    render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }],
  },
  async execute(args) { return ctx.col.create(args) },
}))

API notes (two gotchas we hit, saved for you): parameters is a property map (not a full JSON schema object), and output.schema needs explicit additionalProperties plus a render that materializes content blocks.

---

Service API (ctx.col)

Method	Semantics
create({ kind, role, ... }) → {id, rev}	create a Context (proposed)
activate(ref)	proposed → active (rev+1)
commit(ref, beliefs)	3-tier verified write-back → state accepts verified only; kn accepts inferred/verified; asserted never persists (rev+1, supersede-folded history)
assign(ref, binding)	swap executor — event + exec update, rev unchanged
get(ref) / events(id)	read / audit event stream
transition(ref, op, reason)	suspend / resume / terminate … (governance semantics)

Persistence: dataDir/ctx/<id>/ → current.json + append-only events.jsonl + per-rev snapshots r<rev>.json (atomic writes). Restart-safe (verified in two environments).

---

Events & hooks

Event	Meaning
tools/result	tool pipeline result (real, verified on live DSH)
agent/pre-step, agent/request-error, agent/turn-stopping, agent/created, agent/disposed	registered listeners; path-checked (real firing requires an agent run)

See LAB-EVIDENCE.md for live evidence (loader smoke on local + independent server, real tools-pipeline invocation creating a persisted Context, restart persistence, official dsh 0.1.2-rc.1 headless run) and HEADLESS-FEASIBILITY.md for the assembly-time item we honestly could not complete from a source checkout.

---

Boundaries & FAQ

• Not related to: Kong Inc. "Context Mesh" (data-connectivity product); our compile mechanism is also deliberately distinguished from CCA (arXiv 2609.00759).
• "How is this different from just a durable session?" Sessions are per-executor conversation history; Contexts are org-owned slots with verified state, governance over lifecycle, and compiled need-to-know Briefs.
• License: MIT (this package); the peer @deepseek-ai/cordis and DSH follow their own licenses.
• Status: MVP semantics implemented & load-verified; published on npm as col-dsh-plugin. Contributions welcome via Issues/PRs.

---

Design docs & the full experiment verdict (including the honest negative results) live in a private companion archive; the public face is contextforge. Implementation assisted by DeepSeek Harness under the author's design and review (Co-authored-by trailers in history).