coaiajs 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/KINSHIP.md +1 -1
  2. package/README.md +191 -75
  3. package/dist/mcp/config.d.ts.map +1 -0
  4. package/dist/mcp/config.js +0 -2
  5. package/dist/mcp/config.js.map +1 -0
  6. package/dist/mcp/prompts.d.ts.map +1 -0
  7. package/dist/mcp/prompts.js.map +1 -0
  8. package/dist/mcp/resources.d.ts.map +1 -0
  9. package/dist/mcp/resources.js.map +1 -0
  10. package/dist/mcp/server.d.ts.map +1 -0
  11. package/dist/mcp/server.js +1 -1
  12. package/dist/mcp/server.js.map +1 -0
  13. package/dist/mcp/tools/coaiapy-tools.d.ts.map +1 -0
  14. package/dist/mcp/tools/coaiapy-tools.js.map +1 -0
  15. package/dist/mcp/tools/index.d.ts.map +1 -0
  16. package/dist/mcp/tools/index.js.map +1 -0
  17. package/dist/src/audio.d.ts.map +1 -0
  18. package/dist/src/audio.js.map +1 -0
  19. package/dist/src/cli-helpers.d.ts.map +1 -0
  20. package/dist/src/cli-helpers.js.map +1 -0
  21. package/dist/src/cli.d.ts.map +1 -0
  22. package/dist/src/cli.js +1 -0
  23. package/dist/src/cli.js.map +1 -0
  24. package/dist/src/config.d.ts.map +1 -0
  25. package/dist/src/config.js.map +1 -0
  26. package/dist/src/environment.d.ts.map +1 -0
  27. package/dist/src/environment.js.map +1 -0
  28. package/dist/src/github.d.ts.map +1 -0
  29. package/dist/src/github.js.map +1 -0
  30. package/dist/src/index.d.ts +1 -0
  31. package/dist/src/index.d.ts.map +1 -0
  32. package/dist/src/index.js +1 -0
  33. package/dist/src/index.js.map +1 -0
  34. package/dist/src/langfuse/client.d.ts.map +1 -0
  35. package/dist/src/langfuse/client.js.map +1 -0
  36. package/dist/src/langfuse/comments.d.ts.map +1 -0
  37. package/dist/src/langfuse/comments.js.map +1 -0
  38. package/dist/src/langfuse/datasets.d.ts.map +1 -0
  39. package/dist/src/langfuse/datasets.js.map +1 -0
  40. package/dist/src/langfuse/index.d.ts +1 -0
  41. package/dist/src/langfuse/index.d.ts.map +1 -0
  42. package/dist/src/langfuse/index.js.map +1 -0
  43. package/dist/src/langfuse/media.d.ts.map +1 -0
  44. package/dist/src/langfuse/media.js.map +1 -0
  45. package/dist/src/langfuse/observations.d.ts.map +1 -0
  46. package/dist/src/langfuse/observations.js.map +1 -0
  47. package/dist/src/langfuse/prompts.d.ts +5 -1
  48. package/dist/src/langfuse/prompts.d.ts.map +1 -0
  49. package/dist/src/langfuse/prompts.js +16 -3
  50. package/dist/src/langfuse/prompts.js.map +1 -0
  51. package/dist/src/langfuse/scores.d.ts.map +1 -0
  52. package/dist/src/langfuse/scores.js.map +1 -0
  53. package/dist/src/langfuse/traces.d.ts.map +1 -0
  54. package/dist/src/langfuse/traces.js.map +1 -0
  55. package/dist/src/llm.d.ts.map +1 -0
  56. package/dist/src/llm.js.map +1 -0
  57. package/dist/src/narrative/graph-manager.d.ts.map +1 -0
  58. package/dist/src/narrative/graph-manager.js.map +1 -0
  59. package/dist/src/narrative/index.d.ts.map +1 -0
  60. package/dist/src/narrative/index.js.map +1 -0
  61. package/dist/src/narrative/markdown-export.d.ts.map +1 -0
  62. package/dist/src/narrative/markdown-export.js.map +1 -0
  63. package/dist/src/narrative/tool-definitions.d.ts.map +1 -0
  64. package/dist/src/narrative/tool-definitions.js.map +1 -0
  65. package/dist/src/narrative/tool-handlers.d.ts.map +1 -0
  66. package/dist/src/narrative/tool-handlers.js.map +1 -0
  67. package/dist/src/narrative/types.d.ts.map +1 -0
  68. package/dist/src/narrative/types.js.map +1 -0
  69. package/dist/src/narrative/validation.d.ts.map +1 -0
  70. package/dist/src/narrative/validation.js.map +1 -0
  71. package/dist/src/pde/index.d.ts.map +1 -0
  72. package/dist/src/pde/index.js.map +1 -0
  73. package/dist/src/pde/mcp-handlers.d.ts.map +1 -0
  74. package/dist/src/pde/mcp-handlers.js.map +1 -0
  75. package/dist/src/pde/mcp-tools.d.ts.map +1 -0
  76. package/dist/src/pde/mcp-tools.js.map +1 -0
  77. package/dist/src/pde/session-manager.d.ts.map +1 -0
  78. package/dist/src/pde/session-manager.js.map +1 -0
  79. package/dist/src/pde/stc-mapper.d.ts.map +1 -0
  80. package/dist/src/pde/stc-mapper.js.map +1 -0
  81. package/dist/src/pipeline/index.d.ts.map +1 -0
  82. package/dist/src/pipeline/index.js.map +1 -0
  83. package/dist/src/pipeline/template-engine.d.ts.map +1 -0
  84. package/dist/src/pipeline/template-engine.js.map +1 -0
  85. package/dist/src/planning/index.d.ts.map +1 -0
  86. package/dist/src/planning/index.js.map +1 -0
  87. package/dist/src/planning/mcp-handlers.d.ts.map +1 -0
  88. package/dist/src/planning/mcp-handlers.js.map +1 -0
  89. package/dist/src/planning/mcp-tools.d.ts.map +1 -0
  90. package/dist/src/planning/mcp-tools.js.map +1 -0
  91. package/dist/src/planning/plan-parser.d.ts.map +1 -0
  92. package/dist/src/planning/plan-parser.js.map +1 -0
  93. package/dist/src/redis.d.ts.map +1 -0
  94. package/dist/src/redis.js.map +1 -0
  95. package/dist/src/types.d.ts.map +1 -0
  96. package/dist/src/types.js.map +1 -0
  97. package/dist/src/version.d.ts.map +1 -0
  98. package/dist/src/version.js.map +1 -0
  99. package/llms-full.txt +361 -0
  100. package/llms.txt +43 -0
  101. package/package.json +79 -12
  102. package/.claude/settings.local.json +0 -17
  103. package/.claude-plugin/marketplace.json +0 -26
  104. package/articles/academic/NOTES.md +0 -1
  105. package/articles/academic/README.md +0 -1
  106. package/articles/academic/creative-orientation-vs-problem-solving.md +0 -177
  107. package/articles/academic/jsonl-knowledge-graphs-agent-memory.md +0 -142
  108. package/articles/academic/langfuse-observability-llm-pipelines.md +0 -144
  109. package/articles/academic/medicine-wheel-software-architecture.md +0 -163
  110. package/articles/academic/mmot-autonomous-agents.md +0 -156
  111. package/articles/academic/model-context-protocol-interagent.md +0 -161
  112. package/articles/academic/pde-prompt-decomposition.md +0 -186
  113. package/articles/academic/structural-tension-in-ai-agents.md +0 -134
  114. package/articles/reviews/mcp-protocol-design-review.md +0 -170
  115. package/articles/reviews/observability-ai-systems-review.md +0 -176
  116. package/articles/reviews/prompt-engineering-decomposition-review.md +0 -184
  117. package/articles/surveys/agent-orchestration-survey.md +0 -186
  118. package/articles/surveys/knowledge-graph-storage-survey.md +0 -204
  119. package/articles/surveys/structural-tension-methodology-survey.md +0 -154
  120. package/articles/technical/aws-sdk-v3-polly.md +0 -270
  121. package/articles/technical/commander-cli-framework.md +0 -262
  122. package/articles/technical/dotenv-config-patterns.md +0 -360
  123. package/articles/technical/ioredis-vs-redis.md +0 -142
  124. package/articles/technical/langfuse-js-sdk-vs-rest.md +0 -191
  125. package/articles/technical/mcp-sdk-typescript.md +0 -291
  126. package/articles/technical/octokit-github-api.md +0 -293
  127. package/articles/technical/openai-sdk-modern.md +0 -231
  128. package/articles/technical/yaml-parsing-node.md +0 -266
  129. package/articles/technical/zod-runtime-validation.md +0 -212
  130. package/coaiajs-langfuse-claude-plugin/.claude-plugin/marketplace.json +0 -16
  131. package/coaiajs-langfuse-claude-plugin/.claude-plugin/plugin.json +0 -10
  132. package/coaiajs-langfuse-claude-plugin/.mcp.json +0 -8
  133. package/coaiajs-langfuse-claude-plugin/README.md +0 -60
  134. package/mcp/config.ts +0 -225
  135. package/mcp/prompts.ts +0 -131
  136. package/mcp/resources.ts +0 -84
  137. package/mcp/server.ts +0 -519
  138. package/mcp/tools/coaiapy-tools.ts +0 -366
  139. package/mcp/tools/index.ts +0 -4
  140. package/src/audio.ts +0 -76
  141. package/src/cli-helpers.ts +0 -86
  142. package/src/cli.ts +0 -1261
  143. package/src/config.ts +0 -207
  144. package/src/environment.ts +0 -171
  145. package/src/github.ts +0 -143
  146. package/src/index.ts +0 -82
  147. package/src/langfuse/client.ts +0 -105
  148. package/src/langfuse/comments.ts +0 -52
  149. package/src/langfuse/datasets.ts +0 -178
  150. package/src/langfuse/index.ts +0 -37
  151. package/src/langfuse/media.ts +0 -193
  152. package/src/langfuse/observations.ts +0 -155
  153. package/src/langfuse/prompts.ts +0 -157
  154. package/src/langfuse/scores.ts +0 -456
  155. package/src/langfuse/traces.ts +0 -353
  156. package/src/llm.ts +0 -106
  157. package/src/narrative/graph-manager.ts +0 -1358
  158. package/src/narrative/index.ts +0 -188
  159. package/src/narrative/markdown-export.ts +0 -535
  160. package/src/narrative/tool-definitions.ts +0 -635
  161. package/src/narrative/tool-handlers.ts +0 -528
  162. package/src/narrative/types.ts +0 -9
  163. package/src/narrative/validation.ts +0 -179
  164. package/src/pde/index.ts +0 -34
  165. package/src/pde/mcp-handlers.ts +0 -359
  166. package/src/pde/mcp-tools.ts +0 -201
  167. package/src/pde/session-manager.ts +0 -248
  168. package/src/pde/stc-mapper.ts +0 -298
  169. package/src/pipeline/index.ts +0 -7
  170. package/src/pipeline/template-engine.ts +0 -398
  171. package/src/planning/index.ts +0 -32
  172. package/src/planning/mcp-handlers.ts +0 -369
  173. package/src/planning/mcp-tools.ts +0 -155
  174. package/src/planning/plan-parser.ts +0 -587
  175. package/src/redis.ts +0 -111
  176. package/src/types.ts +0 -281
  177. package/src/version.ts +0 -39
  178. package/test/config.test.mjs +0 -93
  179. package/tsconfig.json +0 -26
package/llms-full.txt ADDED
@@ -0,0 +1,361 @@
1
+ # coaiajs — Full Reference
2
+
3
+ > Complete API surface for `coaiajs`: every entry point, every export, all 63 MCP tools, and the full CLI. Written for AI agents integrating against this package.
4
+
5
+ Package: `coaiajs` · License: MIT · Node.js >= 20 · **ESM only**
6
+
7
+ ---
8
+
9
+ ## 1. Orientation
10
+
11
+ `coaiajs` is the TypeScript consolidation of four CoAIA projects — `coaia-narrative` (knowledge graph, charts), `coaia-pde` (Prompt Decomposition Engine), `coaia-planning` (action planning), and `coaiapy` (Redis/LLM/audio/GitHub/config). It is consumable three ways, all sharing the same modules and the same type system (`src/types.ts`):
12
+
13
+ 1. **Library** — `import { ... } from 'coaiajs'`
14
+ 2. **CLI** — `npx coaia <command>`
15
+ 3. **MCP server** — `npx coaiajs-mcp` (stdio)
16
+
17
+ ### Central concept: the structural tension chart
18
+
19
+ The core data model comes from Robert Fritz's creative process framework. A chart holds three parts:
20
+
21
+ - **Desired Outcome** — what is to be created
22
+ - **Current Reality** — an honest assessment of where things stand
23
+ - **Action Steps** — steps holding the tension between the two; any step can *telescope* into its own sub-chart
24
+
25
+ Charts are stored as JSONL entities in a knowledge graph. "MMOT" (Managerial Moment of Truth) is a structured evaluation over a chart: acknowledge → analyze → plan → recommit.
26
+
27
+ ### Rules that prevent the common mistakes
28
+
29
+ - **ESM only.** `require('coaiajs')` fails. Use `import`. The package sets `"type": "module"`.
30
+ - **Never import `coaiajs/src/...`.** `src/` is not in the published tarball. Use the documented subpaths. (Older documentation showed `coaiajs/src/redis.js`; that path has never resolved from an installed package.)
31
+ - **No side effects at import.** Importing opens no connection and reads no file. Clients are constructed on first use.
32
+ - **Close what you open.** `disconnect()` on Redis; `resetClient()` on any module to drop cached client state (primarily for tests).
33
+
34
+ ---
35
+
36
+ ## 2. Installation
37
+
38
+ ```bash
39
+ npm install coaiajs
40
+ ```
41
+
42
+ ```typescript
43
+ import { tash, fetch, narrative } from 'coaiajs';
44
+ import { parsePlan } from 'coaiajs/planning';
45
+ import type { StructuralTensionPlan, Entity, CoaiaConfig } from 'coaiajs';
46
+ ```
47
+
48
+ TypeScript consumers should use `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` so the `exports` map and its `.d.ts` files resolve correctly.
49
+
50
+ ---
51
+
52
+ ## 3. Library API
53
+
54
+ Root import exposes everything below plus five namespaces (`langfuse`, `narrative`, `pde`, `planning`, `pipeline`) and 26 shared types. A subpath import and its root namespace are the same module.
55
+
56
+ ### `coaiajs/config`
57
+
58
+ ```
59
+ readConfig, getConfig, resetConfig, config, mergeConfigs, findExistingConfig, findEnvFiles
60
+ ```
61
+
62
+ Resolution order (highest wins): environment variables → `.env` files (explicit `--env`, `COAIAJS_ENV_PATH`, `COAIAPY_ENV_PATH`, `./.env`, `~/.coaia/.env`) → `coaia.json` (`./coaia.json`, `~/coaia.json`, `~/.coaia/config.json`) → defaults.
63
+
64
+ ### `coaiajs/redis`
65
+
66
+ ```
67
+ tash, fetch, del, keys, exists, disconnect, getClient, resetClient
68
+ ```
69
+
70
+ `tash`/`fetch` are SET/GET shorthand carried over from coaiapy. TTL is expressed in **minutes** at the CLI layer (default `5555`).
71
+
72
+ ```typescript
73
+ import { tash, fetch, disconnect } from 'coaiajs/redis';
74
+ await tash('session:42', JSON.stringify({ phase: 'design' }));
75
+ const raw = await fetch('session:42');
76
+ await disconnect();
77
+ ```
78
+
79
+ ### `coaiajs/llm`
80
+
81
+ ```
82
+ llm, transcribeAudio, generateImage, abstractProcess, resetClient
83
+ ```
84
+
85
+ OpenAI-backed. `abstractProcess` applies a named tag/template to text; `transcribeAudio` uses Whisper.
86
+
87
+ ### `coaiajs/audio`
88
+
89
+ ```
90
+ synthesize, resetClient
91
+ ```
92
+
93
+ AWS Polly text-to-speech.
94
+
95
+ ### `coaiajs/github`
96
+
97
+ ```
98
+ listIssues, getIssue, getIssueComments, resetClient
99
+ ```
100
+
101
+ Octokit-backed; reads `GITHUB_TOKEN`.
102
+
103
+ ### `coaiajs/environment`
104
+
105
+ ```
106
+ EnvironmentManager, createEnvironment, findEnvironment
107
+ ```
108
+
109
+ ### `coaiajs/version`
110
+
111
+ ```
112
+ getPackageVersion
113
+ ```
114
+
115
+ Returns the resolved version of the installed package, read from `package.json` at runtime.
116
+
117
+ ### `coaiajs/narrative`
118
+
119
+ ```
120
+ KnowledgeGraphManager, ValidationSchemas, validate,
121
+ addAction, completeAction, addObservation, setDueDate, setCurrentChart, getCurrentChart,
122
+ updateChart, viewChart, listCharts, getProgress, getStats, performMmot,
123
+ exportChart, exportAllCharts, exportChartToMarkdown, exportAllChartsToMarkdown,
124
+ exportChartProgress, exportChartStats, writeMarkdownToFile, getDefaultFilename,
125
+ handleToolCall, ALL_TOOL_DEFINITIONS, CORE_TOOLS, KG_TOOLS, NARRATIVE_TOOLS, STC_TOOLS
126
+ ```
127
+
128
+ ```typescript
129
+ import { KnowledgeGraphManager } from 'coaiajs/narrative';
130
+ const kg = new KnowledgeGraphManager('./memory.jsonl');
131
+ const graph = await kg.readGraph();
132
+ ```
133
+
134
+ ### `coaiajs/pde`
135
+
136
+ ```
137
+ SessionManager, sessionManager, StcMapper, stcMapper,
138
+ importDecomposition, listDecompositions, listSessions, showSession,
139
+ handlePdeTool, PDE_MCP_TOOLS
140
+ ```
141
+
142
+ ### `coaiajs/planning`
143
+
144
+ ```
145
+ parsePlan, parsePlanContent, planToSTC, convertToChart, decompositionResultToPlan,
146
+ syncToChart, syncToPlan, exportToJSONL, handlePlanningTool, PLANNING_MCP_TOOLS
147
+ ```
148
+
149
+ ```typescript
150
+ import { parsePlan, planToSTC } from 'coaiajs/planning';
151
+ const plan = await parsePlan('./PLAN.md');
152
+ const chart = planToSTC(plan);
153
+ ```
154
+
155
+ ### `coaiajs/pipeline`
156
+
157
+ ```
158
+ MobileTemplateEngine, TemplateLoader, TemplateRenderer
159
+ ```
160
+
161
+ ### `coaiajs/langfuse`
162
+
163
+ Client and errors: `LangfuseClient`, `LangfuseApiError`, `getClient`, `resetClient`, `nowISO`, `detectContentType`
164
+
165
+ - **Traces:** `createTrace`, `addTrace`, `getTrace`, `listTraces`, `patchTraceOutput`, `traceView`, `sessionView`
166
+ - **Observations:** `addObservation`, `addObservations`, `getObservation`
167
+ - **Prompts:** `createPrompt`, `getPrompt`, `listPrompts`
168
+ - **Datasets:** `createDataset`, `getDataset`, `listDatasets`, `createDatasetItem`, `listDatasetItems`
169
+ - **Scores:** `createScore`, `listScores`, `createScoreForTarget`, `applyScoreToTrace`, `createScoreConfig`, `getScoreConfig`, `listScoreConfigs`, `applyScoreConfig`, `importScoreConfigs`, `exportScoreConfigs`, `getBuiltInPresets`, `installPreset`
170
+ - **Comments:** `createComment`, `getComment`, `listComments`
171
+ - **Media:** `uploadAndAttachMedia`, `getMedia`
172
+ - **Formatters:** `formatTracesTable`, `formatTracesMarkdown`, `formatTraceTree`, `formatObservationDisplay`, `formatPromptDisplay`, `formatPromptsTable`, `formatDatasetsTable`, `formatDatasetForFinetuning`, `formatScoresTable`, `formatScoreConfigsTable`, `formatMediaDisplay`
173
+
174
+ ### Exported types
175
+
176
+ ```
177
+ Entity, EntityMetadata, Relation, RelationMetadata, KnowledgeGraph, McpToolResult,
178
+ PrimaryIntent, SecondaryIntent, ContextRequirements, ExpectedOutputs,
179
+ DirectionItem, DirectionMap, ActionItem, AmbiguityFlag,
180
+ DecompositionResult, StoredDecomposition, DecompositionOptions, PdeSession,
181
+ StructuralElement, StructuralTensionPlan,
182
+ ScoreCategory, ScoreConfig,
183
+ PipelineVariable, PipelineStep, PipelineTemplate, CoaiaConfig
184
+ ```
185
+
186
+ ---
187
+
188
+ ## 4. MCP Server
189
+
190
+ ```bash
191
+ npx coaiajs-mcp
192
+ ```
193
+
194
+ Transport: **stdio**. Serves **63 tools, 3 prompts, 1 listable resource**.
195
+
196
+ Flags: `--memory-path <path>` (JSONL knowledge graph), `--plans-dir <path>`, `--feature-level <level>`.
197
+
198
+ Claude Code / client registration:
199
+
200
+ ```json
201
+ {
202
+ "mcpServers": {
203
+ "coaia": { "command": "npx", "args": ["-y", "--package=coaiajs", "coaiajs-mcp"] }
204
+ }
205
+ }
206
+ ```
207
+
208
+ ### Feature levels
209
+
210
+ `COAIAJS_FEATURES` selects the exposed tool set; default `STANDARD`.
211
+
212
+ | Level | Effect |
213
+ |---|---|
214
+ | `MINIMAL` | Core tash/fetch and essential graph tools |
215
+ | `STANDARD` | Default — the 63 tools listed below |
216
+ | `OBSERVABILITY` | Same set as `STANDARD` |
217
+ | `FULL` | Everything, including media tools |
218
+
219
+ ### Tools — coaiapy + Langfuse (20)
220
+
221
+ ```
222
+ coaia_tash, coaia_fetch,
223
+ coaia_fuse_trace_create, coaia_fuse_add_observation, coaia_fuse_trace_patch_output,
224
+ coaia_fuse_trace_get, coaia_fuse_trace_view, coaia_fuse_observation_get,
225
+ coaia_fuse_traces_list, coaia_fuse_traces_session_view,
226
+ coaia_fuse_prompts_list, coaia_fuse_prompts_get,
227
+ coaia_fuse_datasets_list, coaia_fuse_datasets_get,
228
+ coaia_fuse_score_configs_list, coaia_fuse_score_configs_get, coaia_fuse_score_apply,
229
+ coaia_fuse_comments_list, coaia_fuse_comments_get, coaia_fuse_comments_create
230
+ ```
231
+
232
+ ### Tools — narrative / knowledge graph (27)
233
+
234
+ ```
235
+ create_entities, create_relations, add_observations,
236
+ delete_entities, delete_observations, delete_relations,
237
+ read_graph, search_nodes, open_nodes,
238
+ create_structural_tension_chart, manage_action_step, add_action_step,
239
+ telescope_action_step, remove_action_step, mark_action_complete,
240
+ get_chart_progress, list_active_charts, get_chart, get_action_step,
241
+ update_action_progress, update_current_reality, update_desired_outcome,
242
+ perform_mmot_evaluation,
243
+ create_narrative_beat, telescope_narrative_beat, list_narrative_beats,
244
+ init_llm_guidance
245
+ ```
246
+
247
+ ### Tools — PDE (10)
248
+
249
+ ```
250
+ import_pde_decomposition, create_stc_from_pde, list_pde_decompositions,
251
+ get_session, list_sessions, complete_session,
252
+ pde_update_action_progress, pde_mark_action_complete,
253
+ pde_add_action_step, pde_update_current_reality
254
+ ```
255
+
256
+ The last four carry a `pde_` prefix because their unprefixed names belong to the narrative group. Calling `add_action_step` targets the narrative chart; `pde_add_action_step` targets the PDE session.
257
+
258
+ ### Tools — planning (6)
259
+
260
+ ```
261
+ parse_plan_structural, plan_to_stc, sync_plan_to_chart,
262
+ sync_chart_to_plan, create_plan_trace, pde_to_plan
263
+ ```
264
+
265
+ ### Prompts (3)
266
+
267
+ - `mia_miette_duo` — dual AI embodiment for narrative-driven technical work
268
+ - `create_observability_pipeline` — step-by-step guide for creating a Langfuse observability pipeline
269
+ - `analyze_audio_workflow` — workflow for audio analysis
270
+
271
+ ### Resources
272
+
273
+ - `coaia://templates/` — listable; returns all pipeline templates
274
+ - `coaia://templates/{name}` — readable URI pattern; a single template
275
+ - `coaia://templates/{name}/variables` — readable URI pattern; a template's variables
276
+
277
+ ### Error convention
278
+
279
+ Tool failures return a normal result with `isError: true` and a text explanation rather than a JSON-RPC error. An unknown tool name yields `Unknown tool: <name>`.
280
+
281
+ ---
282
+
283
+ ## 5. CLI
284
+
285
+ ```bash
286
+ npx coaia <command>
287
+ ```
288
+
289
+ Global options: `--env <path>` · `-M, --memory-path <path>` · `--json` · `--no-color` · `-V, --version` · `-h, --help`
290
+
291
+ | Command | Aliases | Purpose |
292
+ |---|---|---|
293
+ | `tash <key> [value]` | `m` | Store a key-value pair in Redis. `-F/--file` reads value from a file; `-T/--ttl` in minutes (default 5555) |
294
+ | `fetch <key>` | | Get a value from Redis |
295
+ | `llm <user> [system]` | | Raw LLM call |
296
+ | `summarize [text]` | `s` | Summarize text |
297
+ | `transcribe <file>` | `t` | Transcribe audio via Whisper |
298
+ | `p <tag> [text]` | | Process text with a custom tag |
299
+ | `init` | | Create a sample `coaia.json` |
300
+ | `fuse` | | Langfuse operations |
301
+ | `narrative` | `n` | Structural tension chart operations |
302
+ | `pde` | | Prompt Decomposition Engine |
303
+ | `plan` | | Structural tension plan operations |
304
+ | `pipeline` | | Pipeline template operations |
305
+ | `env` | | Environment variable management |
306
+ | `gh` | | GitHub operations |
307
+
308
+ Subcommands:
309
+
310
+ - **`fuse`** — `traces`, `prompts`, `datasets`, `sessions`, `scores` (`sc`), `score-configs` (`scc`), `comments`, `media`, `dataset-items`, `projects`
311
+ - **`narrative`** — `list` (`ls`), `view` (`v`), `current` (`cur`), `update` (`up`), `add-action` (`aa`), `add-obs` (`ao`), `complete` (`done`), `export` (`exp`), `export-all`, `stats` (`st`), `progress` (`pg`), `mmot`, `set-date` (`sd`)
312
+ - **`pde`** — `import <pdeId>`, `list`, `sessions`, `show <sessionId>`
313
+ - **`plan`** — `parse <planPath>`, `convert <planPath>`, `sync-to-chart <planPath> <chartsPath>`, `sync-to-plan <chartsPath> <planPath>`
314
+ - **`pipeline`** — `list`, `show <name>`, `create <name>`, `init <name>`
315
+ - **`env`** — `init`, `list`, `source`, `set <key> <value>`, `get <key>`, `unset <key>`, `clear`, `save`
316
+ - **`gh`** — `issues`
317
+
318
+ ---
319
+
320
+ ## 6. Configuration reference
321
+
322
+ | Variable | Description |
323
+ |---|---|
324
+ | `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | Upstash Redis endpoint and token; preferred over direct Redis URLs |
325
+ | `KV_REST_API_URL` / `KV_REST_API_TOKEN` | Vercel KV REST aliases for Upstash Redis |
326
+ | `KV_URL` / `REDIS_URL` | Redis connection URL (`redis://` or `rediss://`) |
327
+ | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` / `REDIS_SSL` | Traditional Redis configuration |
328
+ | `UPSTASH_HOST` / `UPSTASH_PASSWORD` | coaiapy-compatible fallback aliases |
329
+ | `OPENAI_API_KEY` | OpenAI API key |
330
+ | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Langfuse credentials |
331
+ | `AWS_ACCESS_KEY_ID` | AWS credentials for Polly |
332
+ | `GITHUB_TOKEN` | GitHub API token |
333
+ | `COAIAJS_ENV_PATH` / `COAIAPY_ENV_PATH` | Explicit `.env` file locations |
334
+ | `COAIAJS_FEATURES` | MCP feature level |
335
+
336
+ `coaia.json`:
337
+
338
+ ```json
339
+ {
340
+ "redis": { "url": "redis://localhost:6379" },
341
+ "openai": { "apiKey": "sk-...", "model": "gpt-4o" },
342
+ "langfuse": { "publicKey": "pk-...", "secretKey": "sk-..." },
343
+ "github": { "token": "ghp_..." }
344
+ }
345
+ ```
346
+
347
+ ---
348
+
349
+ ## 7. Working on this codebase
350
+
351
+ ```bash
352
+ npm install
353
+ npm run build # tsc
354
+ npm run lint # tsc --noEmit
355
+ npm test # node --test
356
+ npm run dev # tsc --watch
357
+ ```
358
+
359
+ Conventions: ESM only, relative imports end in `.js` · `strict: true`, no unjustified `any` · shared types live in `src/types.ts` · clients lazy, each module exports `resetClient()` · no side effects at import time.
360
+
361
+ Per-module RISE specifications live in `rispecs/`, one file per module.
package/llms.txt ADDED
@@ -0,0 +1,43 @@
1
+ # coaiajs
2
+
3
+ > TypeScript package consolidating the CoAIA (Creative Orientation AI Architecture) ecosystem into one installable unit: a **library**, a **CLI** (`coaia`), and an **MCP server** (`coaiajs-mcp`, 63 tools). Its core data model is the *structural tension chart* — desired outcome, current reality, and telescoping action steps — backed by a JSONL knowledge graph.
4
+
5
+ Install with `npm install coaiajs`. Requires Node.js >= 20. **ESM only** — there is no CommonJS build, so `require('coaiajs')` will not work. Ships `.d.ts` for every entry point.
6
+
7
+ Key facts an agent usually needs first:
8
+
9
+ - Import from `coaiajs` (root) or a subpath such as `coaiajs/narrative`. **Do not** import `coaiajs/src/*.js` — `src/` is not shipped in the published package.
10
+ - Clients (Redis, OpenAI, Polly, Octokit) are lazy: importing a module opens no connection and reads no file. Call `disconnect()` when finished.
11
+ - Config precedence: environment variables > `.env` files > `coaia.json` > defaults.
12
+ - The MCP server serves 63 tools, 3 prompts, and 1 listable resource over stdio. `COAIAJS_FEATURES` (`MINIMAL`/`STANDARD`/`OBSERVABILITY`/`FULL`) controls the tool set; default is `STANDARD`.
13
+
14
+ ## Documentation
15
+
16
+ - [README](./README.md): install, the three consumption modes, configuration, architecture
17
+ - [llms-full.txt](./llms-full.txt): complete API surface — every export, every MCP tool, every CLI command, in one file
18
+ - [CLAUDE.md](./CLAUDE.md): repository conventions for agents working *on* this codebase
19
+ - [KINSHIP.md](./KINSHIP.md): lineage and type provenance from the four origin projects
20
+
21
+ ## Entry points
22
+
23
+ - `coaiajs`: everything, plus `langfuse`/`narrative`/`pde`/`planning`/`pipeline` namespaces and shared types
24
+ - `coaiajs/config`: configuration resolution — `readConfig`, `getConfig`, `resetConfig`
25
+ - `coaiajs/redis`: `tash`, `fetch`, `del`, `keys`, `exists`, `disconnect`
26
+ - `coaiajs/llm`: `llm`, `transcribeAudio`, `generateImage`, `abstractProcess`
27
+ - `coaiajs/audio`: `synthesize` (AWS Polly)
28
+ - `coaiajs/github`: `listIssues`, `getIssue`, `getIssueComments`
29
+ - `coaiajs/environment`: `EnvironmentManager`, `createEnvironment`, `findEnvironment`
30
+ - `coaiajs/version`: `getPackageVersion`
31
+ - `coaiajs/langfuse`: tracing, observations, prompts, datasets, scores, comments, media
32
+ - `coaiajs/narrative`: `KnowledgeGraphManager`, structural tension charts, markdown export
33
+ - `coaiajs/pde`: Prompt Decomposition Engine — sessions, STC mapping
34
+ - `coaiajs/planning`: `parsePlan`, `planToSTC`, `syncToChart`, `syncToPlan`
35
+ - `coaiajs/pipeline`: pipeline template engine
36
+
37
+ ## Specifications
38
+
39
+ - [rispecs/](./rispecs/): RISE specification files, one per module (config, redis, langfuse, narrative, PDE, planning, pipeline, CLI, MCP, audio)
40
+
41
+ ## Optional
42
+
43
+ - [Claude Code plugin](./coaiajs-langfuse-claude-plugin/): registers the MCP server in Claude Code via `npx`
package/package.json CHANGED
@@ -1,8 +1,74 @@
1
1
  {
2
2
  "name": "coaiajs",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "type": "module",
5
5
  "description": "CoAIA unified TypeScript monorepo — CLI, MCP server, and library consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy patterns into one package.",
6
+ "main": "./dist/src/index.js",
7
+ "types": "./dist/src/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/src/index.d.ts",
11
+ "import": "./dist/src/index.js"
12
+ },
13
+ "./config": {
14
+ "types": "./dist/src/config.d.ts",
15
+ "import": "./dist/src/config.js"
16
+ },
17
+ "./redis": {
18
+ "types": "./dist/src/redis.d.ts",
19
+ "import": "./dist/src/redis.js"
20
+ },
21
+ "./llm": {
22
+ "types": "./dist/src/llm.d.ts",
23
+ "import": "./dist/src/llm.js"
24
+ },
25
+ "./audio": {
26
+ "types": "./dist/src/audio.d.ts",
27
+ "import": "./dist/src/audio.js"
28
+ },
29
+ "./github": {
30
+ "types": "./dist/src/github.d.ts",
31
+ "import": "./dist/src/github.js"
32
+ },
33
+ "./environment": {
34
+ "types": "./dist/src/environment.d.ts",
35
+ "import": "./dist/src/environment.js"
36
+ },
37
+ "./version": {
38
+ "types": "./dist/src/version.d.ts",
39
+ "import": "./dist/src/version.js"
40
+ },
41
+ "./langfuse": {
42
+ "types": "./dist/src/langfuse/index.d.ts",
43
+ "import": "./dist/src/langfuse/index.js"
44
+ },
45
+ "./narrative": {
46
+ "types": "./dist/src/narrative/index.d.ts",
47
+ "import": "./dist/src/narrative/index.js"
48
+ },
49
+ "./pde": {
50
+ "types": "./dist/src/pde/index.d.ts",
51
+ "import": "./dist/src/pde/index.js"
52
+ },
53
+ "./planning": {
54
+ "types": "./dist/src/planning/index.d.ts",
55
+ "import": "./dist/src/planning/index.js"
56
+ },
57
+ "./pipeline": {
58
+ "types": "./dist/src/pipeline/index.d.ts",
59
+ "import": "./dist/src/pipeline/index.js"
60
+ },
61
+ "./package.json": "./package.json"
62
+ },
63
+ "files": [
64
+ "dist",
65
+ "rispecs",
66
+ "README.md",
67
+ "KINSHIP.md",
68
+ "CLAUDE.md",
69
+ "llms.txt",
70
+ "llms-full.txt"
71
+ ],
6
72
  "bin": {
7
73
  "coaia": "dist/src/cli.js",
8
74
  "coaiajs-mcp": "dist/mcp/server.js"
@@ -15,28 +81,29 @@
15
81
  "dev": "tsc --watch",
16
82
  "start": "node dist/src/cli.js",
17
83
  "mcp": "node dist/mcp/server.js",
84
+ "pretest": "tsc",
18
85
  "test": "node --test",
19
86
  "lint": "tsc --noEmit"
20
87
  },
21
88
  "dependencies": {
22
- "@modelcontextprotocol/sdk": "^1.25.0",
23
- "ioredis": "^5.4.0",
24
- "zod": "^3.23.0",
89
+ "@aws-sdk/client-polly": "^3.1117.0",
90
+ "@modelcontextprotocol/sdk": "^1.30.0",
91
+ "@octokit/rest": "^21.1.1",
92
+ "chalk": "^5.6.2",
25
93
  "commander": "^12.1.0",
26
- "openai": "^4.70.0",
27
- "@aws-sdk/client-polly": "^3.700.0",
28
- "@octokit/rest": "^21.0.0",
29
- "dotenv": "^16.4.0",
94
+ "dotenv": "^16.6.1",
95
+ "ioredis": "^5.11.1",
30
96
  "js-yaml": "^4.1.0",
31
- "langfuse": "^3.0.0",
97
+ "langfuse": "^3.38.20",
32
98
  "minimist": "^1.2.8",
33
- "chalk": "^5.3.0",
34
- "uuid": "^11.1.0"
99
+ "openai": "^4.104.0",
100
+ "uuid": "^11.1.1",
101
+ "zod": "^3.25.76"
35
102
  },
36
103
  "devDependencies": {
37
- "@types/node": "^22.0.0",
38
104
  "@types/js-yaml": "^4.0.9",
39
105
  "@types/minimist": "^1.2.5",
106
+ "@types/node": "^22.0.0",
40
107
  "@types/uuid": "^10.0.0",
41
108
  "typescript": "^5.7.0"
42
109
  },
@@ -1,17 +0,0 @@
1
- {
2
- "permissions": {
3
- "allow": [
4
- "mcp__claude_ai_Notion__notion-create-pages",
5
- "Bash(git add *)",
6
- "Bash(git config *)",
7
- "Bash(git commit *)",
8
- "Bash(gh issue *)",
9
- "Bash(git rebase *)",
10
- "Bash(git push *)"
11
- ],
12
- "additionalDirectories": [
13
- "/src/coaiapy",
14
- "/workspace/repos/jgwill/miadi-orchestration-kit"
15
- ]
16
- }
17
- }
@@ -1,26 +0,0 @@
1
- {
2
- "name": "coaiajs-marketplace",
3
- "owner": {
4
- "name": "Guillaume Isabelle",
5
- "email": "jgi@jgwill.com",
6
- "url": "https://github.com/jgwill"
7
- },
8
- "metadata": {
9
- "description": "CoAIA Claude Code plugins",
10
- "version": "0.3.0"
11
- },
12
- "plugins": [
13
- {
14
- "name": "coaiajs-langfuse",
15
- "source": "./coaiajs-langfuse-claude-plugin",
16
- "description": "CoAIA unified MCP — 64+ tools (structural tension charts, narrative knowledge graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
17
- "version": "0.3.0",
18
- "author": {
19
- "name": "Guillaume Isabelle",
20
- "url": "https://github.com/jgwill"
21
- },
22
- "license": "MIT",
23
- "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
24
- }
25
- ]
26
- }
@@ -1 +0,0 @@
1
- These article were written by AI
@@ -1 +0,0 @@
1
- These article were written by AI