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';

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, 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 67 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 27 create_entities, read_graph, create_structural_tension_chart, 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 67 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:

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