Skip to main content

Using @dsh-agentic-roleplay/state

@dsh-agentic-roleplay/state is a DSH plugin that exposes ctx.roleplayState. Consumers declare it through Cordis injection and use its session-store and repository contracts instead of opening SQLite directly.

import type {} from '@dsh-agentic-roleplay/state'
import type {Context} from '@deepseek-ai/cordis'

export const inject = ['roleplayState']

export function apply(ctx: Context) {
  const store = ctx.roleplayState.openSession('/absolute/root/sessions', sessionId)
  const characters = store.characters.list()
  ctx.logger.info('%d characters', characters.length)
}

Create sessions through the service so the directory, schema and metadata are initialised consistently. Group related edits in one transaction. Repository errors distinguish missing records, invalid input and conflicts such as attempts to mutate sealed events.

Records​

The records API reads a model-facing view and applies validated edits for events, perceptions, beliefs, state, movement, items, relationships, knowledge and other story data. Beliefs carry a confidence and explicit links to perceptions that support or contradict them. Sealing occurs only after a keeper has completed and verified its commit.

Session metadata may also hold the world's calendar. Agenda and trigger helpers read it when evaluating date, season and holiday rules, so consumers should use the exported calendar functions rather than interpreting on tokens independently.

The package re-exports canonical model types, so external consumers do not depend on the private model package. See the package README for lower-level repository contracts and migration guidance.

Dice​

Sessions keep dice checks and a log of rolls (schema version 8). session.dice defines and reads checks and records rolls. createDiceTools(resolve) builds roll_dice, roll_check and list_checks for an agent: dice come from the system's random source (a roller can be injected in tests), a check is read with its own bands, and every roll is recorded with the turn, the character and who asked. Notation, check validation and reading live in parseNotation, rollCheck, readBands and checkProblems. The plugin registers the tools for every agent of a roleplay session only when its configuration has diceTools: true; the roleplay core leaves it off and registers them per agent from its own tool switches.