dsh-csp-runtime: Cognitive State Interoperability Layer

Introduction¶

In the DSH ecosystem, session state is usually recorded through event sourcing. To share an AI’s “thinking process” with other frameworks (such as CrewAI or LangGraph) or generic JSON consumers, directly parsing the event stream can be costly. We need a standardized way to describe, serialize, and migrate cognitive state.

The dsh-csp-runtime plugin implements Cognitive State Protocol (CSP) v0.1, a cross-framework interoperation layer. It packages an AI’s cognitive state (goals, beliefs, plans, decisions, and uncertainty) into serializable JSON snapshots that can be persisted and migrated across Agents.

Core Positioning¶

This plugin is positioned as an interoperation layer, not as a replacement for event sourcing.
- DSH still records sessions internally as event streams.
- CSP only describes the “thinking state” and does not define specific tools or orchestration logic.
- Orthogonal design: It can coexist with CDP (semantic layer) and intent networks (orchestration layer). CSP only references IDs and does not redefine entities.

Core Features¶

1. State Conversion: Converts DSH event streams to CSP format.
2. State Capture and Persistence: Captures and persists six categories of cognitive states, such as goals, beliefs, plans, decisions, and uncertainty.
3. Cross-Framework Interoperability: Provides dshToCsp and cspToGeneric interfaces for framework-agnostic import and export.
4. Handoff Tokens: Supports three modes—transferable, final, and blocked—defining how states can be taken over.
5. CLI Editing Tool: Provides csp-edit.ts for interactively editing .csp.json files.

Installation and Configuration¶

Prerequisites: Node.js >= 22.19, DSH cordis >= 0.1.0.

dsh plugin --profile web add github:helibeiqi/dsh-csp-runtime

The plugin only registers the cspStore service and disables registration of other services. Configuration allows only the following five top-level fields:

Typical Usage¶

1. Export and Conversion¶

Export cognitive state from DSH event streams and convert it to a generic format.

import { dshToCsp, cspToGeneric } from 'dsh-csp-runtime';

// 1. 将 DSH event stream 转换为 CSP
const csp = dshToCsp(dshEventStream, store);

// 2. 导出为框架无关对象
const generic = cspToGeneric(csp);
// 交给 crewai / langgraph / 通用消费方

2. Handoff Tokens¶

Generate and verify handoff tokens to ensure the taking-over side correctly understands the state context.

import { createHandoff, verifyHandoff } from 'dsh-csp-runtime';

// 生成令牌
const token = createHandoff(store, stateId, {
  mode: 'transferable',
  continuation_prompt: '从 step-3 续做利润率假设',
  required_capabilities: ['cdp:equity-research'],
  ttl_seconds: 3600,
});

// 校验并重建可接续骨架
const result = verifyHandoff(JSON.stringify(token));
if (result.ok) {
  // result.skeleton.goal_stack / plan_tree 完整保留
  // belief_set 中的 transferred 字段将标记为 true
}

3. Example Structure¶

A complete cognitive state snapshot (using AAPL stock analysis as an example) includes:
- goal_stack: Currently in-progress and completed tasks.
- belief_set: A set of beliefs grounded in evidence.
- plan_tree: Execution step tree.
- decision_trace: Decision history.
- uncertainty: Uncertainty assessment.
- handoff: Handoff instructions.

Use Cases and Notes¶

• Interoperability: Suitable for applications that need to migrate cognitive state between DSH and other Agent frameworks.
• M1 Developer Preview: This is currently a protocol design-layer deliverable. APIs and schemas may change in 0.x versions. Pin versions in production.
• Performance: capture is disabled by default. Enable it explicitly to capture state.
• Security: Handoff Tokens currently use hash integrity checks only and have no cryptographic signatures. In production, add transport encryption at the host layer.
• Capability Limits: Specific adapters for CrewAI / LangGraph have not been implemented yet; only generic mappings are provided.

Ecosystem Links¶

• Plugin Catalog Page
• GitHub Repository