narrative-runtime

Goal-oriented narrative state machine for AI agents.

Model agent work as Stories → Scenes → Beats with soft/hard constraints, parallel lanes, failure routing, checkpoints, and a template narrator. The runtime enforces invariants and exposes live world/scene context as MCP tools + resources.

Interactive fiction engine × agent orchestration.

Features

• Core domain: Story, Scene, Beat, Constraint, WorldState, Transition, Outcome, InvariantChecker
• Engine: YAML/JSON load, graph validation, step transitions, dead-end detection, checkpoint/restore
• Soft vs hard constraints — warn or block / route to failure scenes
• Parallel scene lanes with join gates (fork: true transitions)
• Template narrator (no API key)
• Mermaid story-graph + timeline export
• MCP server (stdio) with tools, resources, and a continue prompt
• CLI + optional Vite studio for graph visualization
• Sample stories: incident-response-agent, research-agent

Requirements

• Node.js 20+

Install

git clone https://github.com/SanjoyDat1/narrative-runtime.git
cd narrative-runtime
npm install
npm run build
npm test

CLI

# Summarize a story
npx tsx src/cli/index.ts load stories/research-agent/story.yaml

# Print Mermaid graph
npx tsx src/cli/index.ts mermaid stories/incident-response-agent/story.yaml

# Advance one beat
npx tsx src/cli/index.ts step stories/research-agent/story.yaml define-topic \
  --patch '{"research":{"topic":"MCP resources"}}'

# Start MCP server (stdio)
npm run mcp
# or after build:
node dist/mcp/server.js

Cursor MCP config

Add to your Cursor MCP settings (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "narrative-runtime": {
      "command": "node",
      "args": ["/ABS/PATH/to/narrative-runtime/dist/mcp/server.js"],
      "env": {}
    }
  }
}

Or during development:

{
  "mcpServers": {
    "narrative-runtime": {
      "command": "npx",
      "args": ["tsx", "/ABS/PATH/to/narrative-runtime/src/mcp/server.ts"]
    }
  }
}

MCP tools

Tool	Description
nr_load_story	Load YAML/JSON story (path sandboxed)
nr_get_state	Runtime snapshot
nr_list_beats	Beats in active lanes
nr_advance	Complete a beat (+ optional world patch)
nr_check_invariants	Soft/hard constraint check
nr_checkpoint	Save checkpoint JSON
nr_restore	Restore checkpoint
nr_export_timeline	Timeline JSON / Mermaid / story graph

MCP resources

URI	Description
nr://story/current	Loaded story metadata
nr://scene/current	Active scene(s) + beats
nr://world/state	World state JSON
nr://timeline/latest	Narrator + recent events (markdown)

MCP prompt

• nr_continue — guides the agent to pick the next beat

Agent workflow

1. nr_load_story → stories/research-agent/story.yaml
2. Read nr://scene/current and nr://world/state
3. nr_list_beats → choose a beat
4. nr_advance with required patch fields
5. nr_check_invariants / re-read resources
6. nr_checkpoint before risky branches

Studio

npm run build   # also used to sync sample JSON if you run export
cd studio && npm install && npm run dev

Open http://localhost:5173 — pick a sample story and view the Mermaid graph + initial world state.

Generate studio JSON samples from the repo root:

npx tsx scripts/sync-studio-samples.ts

Story authoring (YAML sketch)

id: my-story
title: My Story
startSceneId: start
initialWorldState: { flag: false }
scenes:
  - id: start
    title: Start
    lane: main
    failureSceneId: fail
    beats:
      - id: do-thing
        title: Do the thing
        allowPatch: [flag]
        apply: { flag: true }
        constraints:
          - id: flag-on
            severity: hard
            path: flag
            op: eq
            value: true
            onViolation: block
    transitions:
      - id: win
        afterBeats: [do-thing]
        to: success
  - id: fail
    kind: failure
    title: Fail
    beats: []
    transitions: []
outcomes:
  - id: success
    title: Success
    kind: success

Constraint operators: eq, neq, gt, gte, lt, lte, exists, in, contains.
Severity: soft | hard. Hard onViolation: block | route_failure.

Architecture

See docs/ARCHITECTURE.md and docs/PLAN.md.

License

MIT