coaiajs

CoAIA unified TypeScript package — a library, a CLI (coaia), and an MCP server (coaiajs-mcp) consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy into one installable package.

npm install coaiajs

import { tash, fetch, narrative, planning } from 'coaiajs';
import { parsePlan } from 'coaiajs/planning';
import type { StructuralTensionPlan, Entity } from 'coaiajs';

• Node.js >= 20.0.0 · ESM only ("type": "module") · MIT
• Ships compiled JavaScript and TypeScript declarations for every entry point.

What is this?

coaiajs is the TypeScript consolidation of the CoAIA (Creative Orientation AI Architecture) ecosystem. It unifies four previously separate projects behind one type system:

| Origin Project | What it did | Where it lives now | |---|---|---| | coaia-narrative | JSONL knowledge graph, structural tension charts, narrative beats | src/narrative/ | | coaia-pde | Prompt Decomposition Engine | src/pde/ | | coaia-planning | Action planning, structural tension chart management | src/planning/ | | coaiapy | Redis, LLM, audio, GitHub, config, environment | src/ (core modules) |

The shared type system in src/types.ts is the union of all four.

It can be consumed three ways — as a library you import, a CLI you run, or an MCP server an AI client connects to. All three share the same underlying modules.

1. Library

Entry points

Import from the root, or from a subpath to pull in only what you need. Every entry point carries its own .d.ts.

| Import path | Exports | |---|---| | coaiajs | Everything below, plus langfuse / narrative / pde / planning / pipeline namespaces and all shared types | | coaiajs/config | readConfig, getConfig, resetConfig, config, mergeConfigs, findExistingConfig, findEnvFiles | | coaiajs/redis | tash, fetch, del, keys, exists, disconnect, getClient, resetClient | | coaiajs/llm | llm, transcribeAudio, generateImage, abstractProcess, resetClient | | coaiajs/audio | synthesize, resetClient | | coaiajs/github | listIssues, getIssue, getIssueComments, resetClient | | coaiajs/environment | EnvironmentManager, createEnvironment, findEnvironment | | coaiajs/version | getPackageVersion, getPackageRoot | | coaiajs/langfuse | Langfuse JS SDK v5/OpenTelemetry tracing plus v4 observations, prompts, datasets, scores, comments, media, projects, and formatters (56 runtime exports) | | coaiajs/media-upload-proxy | Deployable Custom GPT conversation-file to Langfuse media bridge | | coaiajs/narrative | KnowledgeGraphManager, chart operations, markdown export, tool definitions, JSONL preservation, argument hygiene, GitHub bridge | | coaiajs/narrative/contract | The store read contract for renderers — zero I/O, tolerant of a bad line | | coaiajs/skill | The packaged agent skill: showSkill, installSkill, checkSkill, renderSkill, renderToolMap | | coaiajs/pde | SessionManager, StcMapper, handlePdeTool, PDE_MCP_TOOLS (10 exports) | | coaiajs/planning | parsePlan, planToSTC, syncToChart, syncToPlan, handlePlanningTool (10 exports) | | coaiajs/pipeline | MobileTemplateEngine, TemplateLoader, TemplateRenderer |

Root-namespace access is equivalent to the subpath:

import { narrative } from 'coaiajs';
import * as narrative from 'coaiajs/narrative';   // same module

Examples

Redis key/value (coaiapy tash/fetch semantics)

import { tash, fetch, disconnect } from 'coaiajs/redis';

await tash('session:42', JSON.stringify({ phase: 'design' }));
const raw = await fetch('session:42');
await disconnect();                 // clients are lazy; close when done

Parse a plan into a structural tension chart

import { parsePlan, planToSTC } from 'coaiajs/planning';

const plan = await parsePlan('./PLAN.md');
const chart = planToSTC(plan);

Knowledge graph

import { KnowledgeGraphManager } from 'coaiajs/narrative';

const kg = new KnowledgeGraphManager('./memory.jsonl');
const graph = await kg.readGraph();

Client lifecycle

Redis, OpenAI, Polly, and Octokit clients are created lazily on first use — importing a module never opens a connection or reads a file. Each module exports resetClient() so tests can drop cached state:

import { resetRedisClient, resetLlmClient } from 'coaiajs';

2. CLI

npx coaia <command>          # or: npm i -g coaiajs && coaia <command>

Global options: --env <path> · -M, --memory-path <path> · --json · --no-color · -V, --version

| Command | Purpose | |---|---| | tash (m) | Store a key-value pair in Redis | | fetch | Get a value from Redis | | llm | Make a raw LLM call | | summarize (s) | Summarize text | | transcribe (t) | Transcribe audio via Whisper | | p <tag> [text] | Process text with a custom tag | | init | Create a sample coaia.json | | fuse | Langfuse operations — traces, prompts, datasets, scores, score-configs, sessions, comments, media, projects, dataset-items | | skill | The packaged agent skill — show, install, check | | narrative (n) | Chart operations — list, view, current, update, add-action, add-obs, complete, export, export-all, stats, progress, mmot, set-date, delay, delayed, end-delay, link-issue | | pde | import, list, sessions, show | | plan | parse, convert, sync-to-chart, sync-to-plan | | pipeline | list, show, create, init | | env | init, list, source, set, get, unset, clear, save | | gh | issues |

coaia tash follows coaiapy semantics: -F/--file reads the value from a file, -T/--ttl is in minutes, default TTL 5555.

coaia fuse prompts get <name> outputs Markdown by default (--md is available explicitly); use the global --json option for JSON.

Langfuse v4 compatibility

coaia fuse uses the current scoped Langfuse JS SDK v5. Trace writes are exported as immutable OpenTelemetry spans to POST /api/public/otel/v1/traces with ingestion version 4. Trace, observation, and session reads use Observations API v2; score reads use Scores API v3. The removed v4 concepts are reflected in the CLI: sessions are reconstructed from observations, and legacy trace-output patching is no longer exposed. Langfuse Cloud sunsets the legacy APIs on November 16, 2026.

Migration references: Langfuse v4 · versions and compatibility · deprecated API mapping · custom ingestion migration · current OpenAPI reference.

Custom GPT observation actions

agents/custom_gpt/ceremony-observations.yml is a focused OpenAPI 3.1 action specification for creating a root observation and appending child observations to the same Langfuse trace through OTLP/HTTP JSON. It contains 23 core actions—below the 30-action limit—including media upload-record, retrieval, and finalization capabilities; destructive operations remain omitted. Media hashes use the required 44-character padded Base64 SHA-256 digest of the exact upload bytes, and the documented workflow distinguishes URL creation from the actual presigned PUT. Setup, authentication, ID/timestamp rules, and ready-to-paste GPT instructions are in ceremony-observations.instructions.md. The broader imported API surface remains available in ceremony.yml.

For autonomous conversation-file uploads, deploy the included coaiajs-media-proxy service and import ceremony-media-proxy.yml as a second Action. It uses OpenAI's openaiFileIdRefs transfer, downloads the actual user/DALL-E/Code Interpreter file, performs the Langfuse media record + presigned PUT + finalization sequence, and returns a renderable @@@langfuseMedia...@@@ token. Deployment and security instructions are in ceremony-media-proxy.instructions.md. Together both specs expose 24 actions.

3. MCP Server

npx coaiajs-mcp

Serves 70 tools, 3 prompts, and 1 listable resource over stdio.

| Group | Count | Examples | |---|---|---| | coaiapy + Langfuse | 19 | coaia_tash, coaia_fetch, coaia_fuse_trace_create, coaia_fuse_traces_list | | Narrative / knowledge graph | 35 | create_entities, read_graph, create_structural_tension_chart, delay_resolution, perform_mmot_evaluation | | PDE | 10 | import_pde_decomposition, create_stc_from_pde, complete_session | | Planning | 6 | parse_plan_structural, plan_to_stc, sync_plan_to_chart, pde_to_plan |

Four PDE tools carry a pde_ prefix (pde_add_action_step, pde_mark_action_complete, pde_update_action_progress, pde_update_current_reality) because their unprefixed names belong to the narrative group.

Prompts: mia_miette_duo, create_observability_pipeline, analyze_audio_workflow

Resources: coaia://templates/ is listable; coaia://templates/{name} and coaia://templates/{name}/variables are readable URI patterns.

Feature levels

Set COAIAJS_FEATURES to control the exposed tool set (default STANDARD):

| Level | Effect | |---|---| | MINIMAL | Core tash/fetch and essential graph tools | | STANDARD | Default — the 70 tools above | | OBSERVABILITY | Same set as STANDARD | | FULL | Everything, including media tools |

Agent skill

coaiajs ships a skill describing its own surface. The tool map inside it is generated from the server's tool definitions at install time, so it cannot advertise a tool this package does not serve.

coaia skill show                 # print it
coaia skill install --yes        # ./.agents/skills/coaiajs + the .claude/skills symlink
coaia skill install --global     # ~/.agents/skills/coaiajs
coaia skill check                # is the installed copy current?

Run coaia skill check after upgrading. A skill installed by an older version describes an older tool surface, and nothing else reports that. It exits non-zero when stale or missing.

Claude Code

A ready-made plugin lives in coaiajs-langfuse-claude-plugin/. It registers this server via npx rather than vendoring a copy. Or wire it manually:

{
  "mcpServers": {
    "coaia": { "command": "npx", "args": ["-y", "--package=coaiajs", "coaiajs-mcp"] }
  }
}

Configuration

Loaded with the following priority (highest wins):

1. Environment variables
2. .env files — explicit --env, then COAIAJS_ENV_PATH, COAIAPY_ENV_PATH, ./.env, ~/.coaia/.env
3. coaia.json — ./coaia.json, ~/coaia.json, ~/.coaia/config.json
4. Defaults

| Variable | Description | |---|---| | UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN | Upstash Redis endpoint and token, preferred over direct Redis URLs | | KV_REST_API_URL / KV_REST_API_TOKEN | Vercel KV REST aliases for Upstash Redis | | KV_URL / REDIS_URL | Redis connection URL (redis:// or rediss://) | | REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_SSL | Traditional Redis configuration | | UPSTASH_HOST / UPSTASH_PASSWORD | coaiapy-compatible fallback aliases | | OPENAI_API_KEY | OpenAI API key | | LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY | Langfuse credentials | | AWS_ACCESS_KEY_ID | AWS credentials for Polly | | GITHUB_TOKEN | GitHub API token | | COAIAJS_FEATURES | MCP feature level (see above) |

{
  "redis": { "url": "redis://localhost:6379" },
  "openai": { "apiKey": "sk-...", "model": "gpt-4o" },
  "langfuse": { "publicKey": "pk-...", "secretKey": "sk-..." },
  "github": { "token": "ghp_..." }
}

Architecture

The data model follows the structural tension pattern from Robert Fritz's creative process framework:

• Desired Outcome — what you want to create
• Current Reality — honest assessment of where you are
• Action Steps — telescoped sub-charts holding the tension between the two

Each module operates independently but shares the unified type system in src/types.ts, which is what lets the CLI and the MCP server expose the same capabilities through different protocols.

coaiajs/
├── src/
│   ├── types.ts            # Shared types (union of all four origin projects)
│   ├── index.ts            # Public library entry point
│   ├── config.ts           # Configuration resolution
│   ├── redis.ts            # Redis tash/fetch
│   ├── environment.ts      # Environment variable management
│   ├── llm.ts              # OpenAI wrapper
│   ├── audio.ts            # AWS Polly text-to-speech
│   ├── github.ts           # GitHub API wrapper
│   ├── version.ts          # Runtime version resolution
│   ├── cli.ts              # CLI entry point
│   ├── langfuse/           # Langfuse observability
│   ├── narrative/          # Knowledge graph, charts, beats
│   ├── pde/                # Prompt Decomposition Engine
│   ├── planning/           # Action planning
│   └── pipeline/           # Pipeline template engine
├── mcp/                    # MCP server and tool definitions
├── test/                   # Tests (node:test)
├── rispecs/                # RISE specification files
└── coaiajs-langfuse-claude-plugin/   # Claude Code plugin

Development

npm install
npm run build      # tsc
npm run lint       # tsc --noEmit
npm test           # node --test
npm run dev        # tsc --watch

Conventions: ESM only, all relative imports end in .js · strict: true, no unjustified any · all shared types in src/types.ts · no side effects at import time.

For AI agents

llms.txt is a compact orientation file; llms-full.txt documents the complete API surface, every MCP tool, and the CLI in one pass.

License

MIT