coaiajs 0.2.0 → 0.3.0

package/.claude/settings.local.json

@@ -10,7 +10,8 @@
       "Bash(git push *)"
     ],
     "additionalDirectories": [
-      "/src/coaiapy"
+      "/src/coaiapy",
+      "/workspace/repos/jgwill/miadi-orchestration-kit"
     ]
   }
 }

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "coaiajs-marketplace",
+  "owner": {
+    "name": "Guillaume Isabelle",
+    "email": "jgi@jgwill.com",
+    "url": "https://github.com/jgwill"
+  },
+  "metadata": {
+    "description": "CoAIA Claude Code plugins",
+    "version": "0.3.0"
+  },
+  "plugins": [
+    {
+      "name": "coaiajs-langfuse",
+      "source": "./coaiajs-langfuse-claude-plugin",
+      "description": "CoAIA unified MCP — 64+ tools (structural tension charts, narrative knowledge graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
+      "version": "0.3.0",
+      "author": {
+        "name": "Guillaume Isabelle",
+        "url": "https://github.com/jgwill"
+      },
+      "license": "MIT",
+      "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
+    }
+  ]
+}

package/coaiajs-langfuse-claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "coaiajs-marketplace",
+  "owner": { "name": "Guillaume Isabelle", "email": "jgi@jgwill.com", "url": "https://github.com/jgwill" },
+  "metadata": { "description": "CoAIA Claude Code plugins", "version": "0.3.0" },
+  "plugins": [
+    {
+      "name": "coaiajs-langfuse",
+      "source": "./",
+      "description": "CoAIA unified MCP — 64+ tools (structural tension, narrative graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
+      "version": "0.3.0",
+      "author": { "name": "Guillaume Isabelle", "url": "https://github.com/jgwill" },
+      "license": "MIT",
+      "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
+    }
+  ]
+}

package/coaiajs-langfuse-claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "coaiajs-langfuse",
+  "description": "CoAIA unified MCP for Claude Code — 64+ tools across structural-tension charts, narrative knowledge graph, Prompt Decomposition Engine (PDE), action planning, Redis tash/fetch, and Langfuse tracing. Bundles the published `coaiajs` npm package's `coaiajs-mcp` server via npx.",
+  "version": "0.3.0",
+  "author": { "name": "Guillaume Isabelle", "email": "jgi@jgwill.com", "url": "https://github.com/jgwill" },
+  "homepage": "https://github.com/jgwill/coaiajs/tree/master/coaiajs-langfuse-claude-plugin",
+  "repository": "https://github.com/jgwill/coaiajs",
+  "license": "MIT",
+  "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
+}

package/coaiajs-langfuse-claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "coaia": {
+      "command": "npx",
+      "args": ["-y", "--package=coaiajs", "coaiajs-mcp"]
+    }
+  }
+}

package/coaiajs-langfuse-claude-plugin/README.md

@@ -0,0 +1,60 @@
+# coaiajs-langfuse — Claude Code Plugin
+
+A Claude Code plugin that registers the `coaiajs-mcp` server — 64+ tools, 3 prompts, and 3 resources — as an MCP server inside Claude Code. It does not bundle its own copy of the server; it launches the published `coaiajs` npm package on demand via `npx`:
+
+```
+npx -y --package=coaiajs coaiajs-mcp
+```
+
+That command is declared in `.mcp.json` at the root of this plugin, which Claude Code auto-loads on install.
+
+## Install
+
+From a marketplace source (GitHub):
+
+```
+claude plugin marketplace add https://github.com/jgwill/coaiajs
+claude plugin install coaiajs-langfuse@coaiajs-marketplace
+```
+
+Or from a local checkout:
+
+```
+claude plugin marketplace add /a/src/coaiajs/coaiajs-langfuse-claude-plugin
+claude plugin install coaiajs-langfuse@coaiajs-marketplace
+```
+
+Confirm it registered:
+
+```
+claude plugin list
+```
+
+## Tool families
+
+- **Structural-tension charts** — desired outcome / current reality / action steps, the core CoAIA data model.
+- **Narrative knowledge graph** — entities, relations, and graph queries (from coaia-narrative).
+- **PDE (Prompt Decomposition Engine)** — decompose complex prompts into actionable intent maps.
+- **Action planning** — structural tension plans and action-step management (from coaia-planning).
+- **Redis tash/fetch** — SET/GET shorthand against a Redis store.
+- **Langfuse tracing** — trace, span, and observation tools for Langfuse-backed observability.
+
+## Environment variables
+
+The server boots with no configuration — it connects to nothing at import time. Individual tool families activate only when their own credentials are present in the environment Claude Code runs in:
+
+| Variable | Used by |
+| --- | --- |
+| `REDIS_URL` | tash/fetch |
+| `OPENAI_API_KEY` | LLM-backed tools |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse tracing |
+| `LANGFUSE_SECRET_KEY` | Langfuse tracing |
+| `LANGFUSE_BASE_URL` | Langfuse tracing |
+| `GITHUB_TOKEN` | GitHub-integration tools |
+| AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc.) | Polly audio tools |
+
+None of these are set by the plugin itself — they are inherited from whatever shell/environment Claude Code is launched in. Set them in your shell profile, `.env`, or however you normally manage secrets for this machine.
+
+## Versioning
+
+This plugin tracks the published npm `coaiajs` package rather than vendoring source. `.mcp.json` calls `npx -y --package=coaiajs coaiajs-mcp`, which always resolves the latest published version at launch time. To pin a specific version, edit `.mcp.json` and change `--package=coaiajs` to `--package=coaiajs@<version>` (e.g. `coaiajs@0.3.0`).

package/dist/mcp/server.js

@@ -12,6 +12,7 @@ import { tash as redisTash, fetch as redisFetch } from '../src/redis.js';
 import { ALL_TOOL_DEFINITIONS as NARRATIVE_TOOL_DEFINITIONS, handleToolCall as handleNarrativeTool, KnowledgeGraphManager, } from '../src/narrative/index.js';
 import { PDE_MCP_TOOLS, handlePdeTool } from '../src/pde/index.js';
 import { PLANNING_MCP_TOOLS, handlePlanningTool } from '../src/planning/index.js';
+import { getPackageVersion } from '../src/version.js';
 // Langfuse imports
 import { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesMarkdown, formatTraceTree, } from '../src/langfuse/traces.js';
 import { addObservation, getObservation, formatObservationDisplay } from '../src/langfuse/observations.js';
@@ -22,7 +23,7 @@ import { listComments, getComment, createComment } from '../src/langfuse/comment
 import { uploadAndAttachMedia, getMedia, formatMediaDisplay } from '../src/langfuse/media.js';
 // ─── Server Info ────────────────────────────────────────────────────
 const SERVER_NAME = 'coaiajs-mcp';
-const SERVER_VERSION = '0.1.1';
+const SERVER_VERSION = getPackageVersion();
 // ─── Parse CLI args ─────────────────────────────────────────────────
 function parseArgs() {
     const args = process.argv.slice(2);

package/dist/src/cli.js

@@ -8,6 +8,7 @@ import { readConfig } from './config.js';
 import { llm as llmCall, transcribeAudio, abstractProcess } from './llm.js';
 import { listIssues, getIssue } from './github.js';
 import { createEnvironment, findEnvironment } from './environment.js';
+import { getPackageVersion } from './version.js';
 import { formatTable, formatJson, formatError, formatSuccess, truncate, formatDate, formatProgress, setColorEnabled, } from './cli-helpers.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -1084,7 +1085,7 @@ async function main() {
     const program = new Command();
     program
         .name('coaia')
-        .version('0.1.3', '-V, --version')
+        .version(getPackageVersion(), '-V, --version')
         .description('CoAIA unified CLI — structural tension, narrative, and DevOps tooling')
         .option('--env <path>', 'Load environment file')
         .option('-M, --memory-path <path>', 'JSONL memory file path')

package/dist/src/langfuse/index.d.ts

@@ -1,8 +1,8 @@
 export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
 export type { IngestionEvent, LangfuseClientConfig } from './client.js';
-export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTracesMarkdown, formatTraceTree } from './traces.js';
+export { addTrace, createTrace, patchTraceOutput, listTraces, getTrace, traceView, sessionView, formatTracesTable, formatTracesMarkdown, formatTraceTree, } from './traces.js';
 export type { TraceFilters } from './traces.js';
-export { addObservation, getObservation, formatObservationDisplay } from './observations.js';
+export { addObservation, addObservations, getObservation, formatObservationDisplay } from './observations.js';
 export { listPrompts, getPrompt, createPrompt, formatPromptsTable, formatPromptDisplay } from './prompts.js';
 export { listDatasets, getDataset, createDataset, listDatasetItems, createDatasetItem, formatDatasetsTable, formatDatasetForFinetuning, } from './datasets.js';
 export { createScore, applyScoreToTrace, createScoreForTarget, listScores, listScoreConfigs, getScoreConfig, createScoreConfig, exportScoreConfigs, importScoreConfigs, applyScoreConfig, getBuiltInPresets, installPreset, formatScoresTable, formatScoreConfigsTable, } from './scores.js';

package/dist/src/langfuse/index.js

@@ -1,7 +1,7 @@
 // coaiajs/src/langfuse/index.ts — Barrel export
 export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
-export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTracesMarkdown, formatTraceTree } from './traces.js';
-export { addObservation, getObservation, formatObservationDisplay } from './observations.js';
+export { addTrace, createTrace, patchTraceOutput, listTraces, getTrace, traceView, sessionView, formatTracesTable, formatTracesMarkdown, formatTraceTree, } from './traces.js';
+export { addObservation, addObservations, getObservation, formatObservationDisplay } from './observations.js';
 export { listPrompts, getPrompt, createPrompt, formatPromptsTable, formatPromptDisplay } from './prompts.js';
 export { listDatasets, getDataset, createDataset, listDatasetItems, createDatasetItem, formatDatasetsTable, formatDatasetForFinetuning, } from './datasets.js';
 export { createScore, applyScoreToTrace, createScoreForTarget, listScores, listScoreConfigs, getScoreConfig, createScoreConfig, exportScoreConfigs, importScoreConfigs, applyScoreConfig, getBuiltInPresets, installPreset, formatScoresTable, formatScoreConfigsTable, } from './scores.js';

package/dist/src/langfuse/observations.d.ts

@@ -4,9 +4,12 @@ export declare function addObservation(params: {
     type?: string;
     name: string;
     parentId?: string;
+    parentObservationId?: string;
+    input?: string;
     inputData?: unknown;
+    output?: string;
     outputData?: unknown;
-    metadata?: unknown;
+    metadata?: string | unknown;
     startTime?: string;
     endTime?: string;
     level?: string;
@@ -14,5 +17,9 @@ export declare function addObservation(params: {
     usage?: unknown;
 }): Promise<string>;
 export declare function getObservation(observationId: string): Promise<string>;
+export declare function addObservations(params: {
+    traceId?: string;
+    observations?: Array<Record<string, unknown>>;
+}): Promise<string>;
 export declare function formatObservationDisplay(json: unknown): string;
 //# sourceMappingURL=observations.d.ts.map

package/dist/src/langfuse/observations.js

@@ -15,14 +15,14 @@ export async function addObservation(params) {
     };
     if (params.name)
         body.name = params.name;
-    if (params.inputData)
-        body.input = params.inputData;
-    if (params.outputData)
-        body.output = params.outputData;
+    if (params.inputData ?? params.input)
+        body.input = parseJsonOption(params.inputData ?? params.input);
+    if (params.outputData ?? params.output)
+        body.output = parseJsonOption(params.outputData ?? params.output);
     if (params.metadata)
-        body.metadata = params.metadata;
-    if (params.parentId)
-        body.parentObservationId = params.parentId;
+        body.metadata = parseJsonOption(params.metadata);
+    if (params.parentId ?? params.parentObservationId)
+        body.parentObservationId = params.parentId ?? params.parentObservationId;
     if (params.endTime)
         body.endTime = params.endTime;
     if (params.model)
@@ -49,6 +49,28 @@ export async function getObservation(observationId) {
     const result = await client.request('GET', `/api/public/observations/${observationId}`);
     return JSON.stringify(result, null, 2);
 }
+function parseJsonOption(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+export async function addObservations(params) {
+    const observations = params.observations ?? [];
+    const results = [];
+    for (const observation of observations) {
+        const traceId = String(observation.traceId ?? params.traceId ?? '');
+        const name = String(observation.name ?? 'Observation');
+        if (!traceId)
+            throw new Error('traceId is required for every observation');
+        results.push(JSON.parse(await addObservation({ ...observation, traceId, name })));
+    }
+    return JSON.stringify({ success: true, count: results.length, observations: results }, null, 2);
+}
 // ─── Formatters ─────────────────────────────────────────────────────
 const TYPE_GLYPHS = {
     SPAN: '🔗',

package/dist/src/langfuse/traces.d.ts

@@ -21,9 +21,27 @@ export declare function addTrace(params: {
     outputData?: unknown;
     metadata?: unknown;
 }): Promise<string>;
-export declare function patchTraceOutput(traceId: string, outputData: unknown): Promise<string>;
+export declare function patchTraceOutput(traceIdOrParams: string | {
+    traceId?: string;
+    output?: string;
+    outputData?: unknown;
+}, outputData?: unknown): Promise<string>;
+export declare function createTrace(params: {
+    traceId?: string;
+    id?: string;
+    userId?: string;
+    sessionId?: string;
+    name?: string;
+    input?: string;
+    inputData?: unknown;
+    output?: string;
+    outputData?: unknown;
+    metadata?: string | unknown;
+}): Promise<string>;
 export declare function listTraces(filters: TraceFilters): Promise<string>;
 export declare function getTrace(traceId: string): Promise<string>;
+export declare function traceView(traceId: string): Promise<string>;
+export declare function sessionView(sessionId: string): Promise<string>;
 export declare function formatTracesTable(json: unknown): string;
 export declare function formatTraceTree(json: unknown): string;
 export declare function formatTracesMarkdown(json: unknown): string;

package/dist/src/langfuse/traces.js

@@ -35,13 +35,19 @@ export async function addTrace(params) {
         message: `Trace ${traceId} created`,
     }, null, 2);
 }
-export async function patchTraceOutput(traceId, outputData) {
+export async function patchTraceOutput(traceIdOrParams, outputData) {
+    const traceId = typeof traceIdOrParams === 'string' ? traceIdOrParams : traceIdOrParams.traceId;
+    if (!traceId)
+        throw new Error('traceId is required');
+    const output = typeof traceIdOrParams === 'string'
+        ? outputData
+        : parseJsonOption(traceIdOrParams.outputData ?? traceIdOrParams.output);
     const client = getClient();
     const now = nowISO();
     const body = {
         id: traceId,
         timestamp: now,
-        output: outputData,
+        output,
     };
     const eventId = `${traceId}-patch-${uuidv4().slice(0, 8)}`;
     const event = {
@@ -57,6 +63,27 @@ export async function patchTraceOutput(traceId, outputData) {
         message: `Trace output patched for ${traceId}`,
     }, null, 2);
 }
+function parseJsonOption(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+export async function createTrace(params) {
+    return addTrace({
+        traceId: params.traceId ?? params.id,
+        userId: params.userId,
+        sessionId: params.sessionId,
+        name: params.name,
+        inputData: parseJsonOption(params.inputData ?? params.input),
+        outputData: parseJsonOption(params.outputData ?? params.output),
+        metadata: parseJsonOption(params.metadata),
+    });
+}
 export async function listTraces(filters) {
     const client = getClient();
     const params = new URLSearchParams();
@@ -111,6 +138,14 @@ export async function getTrace(traceId) {
     }
     return JSON.stringify(trace, null, 2);
 }
+export async function traceView(traceId) {
+    const raw = await getTrace(traceId);
+    return formatTraceTree(raw);
+}
+export async function sessionView(sessionId) {
+    const raw = await listTraces({ sessionId, limit: 20, orderBy: 'timestamp.desc' });
+    return formatTracesMarkdown(raw);
+}
 // ─── Formatters ─────────────────────────────────────────────────────
 export function formatTracesTable(json) {
     try {

package/dist/src/version.d.ts

@@ -0,0 +1,3 @@
+/** Resolved version of the installed `coaiajs` package. */
+export declare function getPackageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/src/version.js

@@ -0,0 +1,33 @@
+// coaiajs/src/version.ts — single source of truth for the runtime version.
+// Reads package.json at runtime so the CLI banner, the MCP handshake, and the
+// published package can never drift apart again.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PACKAGE_NAME = 'coaiajs';
+let cached;
+/** Resolved version of the installed `coaiajs` package. */
+export function getPackageVersion() {
+    if (cached)
+        return cached;
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/src/version.js -> package root is two levels up.
+    // src/version.ts (ts-node/tsx) -> package root is one level up.
+    const candidates = [join(here, '..', '..', 'package.json'), join(here, '..', 'package.json')];
+    for (const candidate of candidates) {
+        let raw;
+        try {
+            raw = readFileSync(candidate, 'utf8');
+        }
+        catch {
+            continue; // not at this depth; try the next candidate
+        }
+        const pkg = JSON.parse(raw);
+        if (pkg.name === PACKAGE_NAME && pkg.version) {
+            cached = pkg.version;
+            return cached;
+        }
+    }
+    throw new Error(`Unable to resolve ${PACKAGE_NAME} version: no package.json found near ${here}`);
+}
+//# sourceMappingURL=version.js.map

package/mcp/server.ts

@@ -28,6 +28,7 @@ import {
 import { PDE_MCP_TOOLS, handlePdeTool } from '../src/pde/index.js';
 import { PLANNING_MCP_TOOLS, handlePlanningTool } from '../src/planning/index.js';
 import type { McpToolResult } from '../src/types.js';
+import { getPackageVersion } from '../src/version.js';
 
 // Langfuse imports
 import {
@@ -46,7 +47,7 @@ import { uploadAndAttachMedia, getMedia, formatMediaDisplay } from '../src/langf
 // ─── Server Info ────────────────────────────────────────────────────
 
 const SERVER_NAME = 'coaiajs-mcp';
-const SERVER_VERSION = '0.1.1';
+const SERVER_VERSION = getPackageVersion();
 
 // ─── Parse CLI args ─────────────────────────────────────────────────
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "coaiajs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "CoAIA unified TypeScript monorepo — CLI, MCP server, and library consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy patterns into one package.",
   "bin": {
-    "coaia": "./dist/src/cli.js",
-    "coaiajs-mcp": "./dist/mcp/server.js"
+    "coaia": "dist/src/cli.js",
+    "coaiajs-mcp": "dist/mcp/server.js"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/cli.ts

@@ -9,6 +9,7 @@ import { readConfig, getConfig } from './config.js';
 import { llm as llmCall, transcribeAudio, abstractProcess } from './llm.js';
 import { listIssues, getIssue } from './github.js';
 import { createEnvironment, findEnvironment } from './environment.js';
+import { getPackageVersion } from './version.js';
 import {
   formatTable, formatJson, formatError, formatSuccess,
   truncate, formatDate, formatProgress, setColorEnabled,
@@ -1221,7 +1222,7 @@ async function main(): Promise<void> {
 
   program
     .name('coaia')
-    .version('0.1.3', '-V, --version')
+    .version(getPackageVersion(), '-V, --version')
     .description('CoAIA unified CLI — structural tension, narrative, and DevOps tooling')
     .option('--env <path>', 'Load environment file')
     .option('-M, --memory-path <path>', 'JSONL memory file path')

package/src/langfuse/index.ts

@@ -3,10 +3,14 @@
 export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
 export type { IngestionEvent, LangfuseClientConfig } from './client.js';
 
-export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTracesMarkdown, formatTraceTree } from './traces.js';
+export {
+  addTrace, createTrace, patchTraceOutput,
+  listTraces, getTrace, traceView, sessionView,
+  formatTracesTable, formatTracesMarkdown, formatTraceTree,
+} from './traces.js';
 export type { TraceFilters } from './traces.js';
 
-export { addObservation, getObservation, formatObservationDisplay } from './observations.js';
+export { addObservation, addObservations, getObservation, formatObservationDisplay } from './observations.js';
 
 export { listPrompts, getPrompt, createPrompt, formatPromptsTable, formatPromptDisplay } from './prompts.js';
 

package/src/langfuse/observations.ts

@@ -11,9 +11,12 @@ export async function addObservation(params: {
   type?: string;
   name: string;
   parentId?: string;
+  parentObservationId?: string;
+  input?: string;
   inputData?: unknown;
+  output?: string;
   outputData?: unknown;
-  metadata?: unknown;
+  metadata?: string | unknown;
   startTime?: string;
   endTime?: string;
   level?: string;
@@ -33,10 +36,10 @@ export async function addObservation(params: {
   };
 
   if (params.name) body.name = params.name;
-  if (params.inputData) body.input = params.inputData;
-  if (params.outputData) body.output = params.outputData;
-  if (params.metadata) body.metadata = params.metadata;
-  if (params.parentId) body.parentObservationId = params.parentId;
+  if (params.inputData ?? params.input) body.input = parseJsonOption(params.inputData ?? params.input);
+  if (params.outputData ?? params.output) body.output = parseJsonOption(params.outputData ?? params.output);
+  if (params.metadata) body.metadata = parseJsonOption(params.metadata);
+  if (params.parentId ?? params.parentObservationId) body.parentObservationId = params.parentId ?? params.parentObservationId;
   if (params.endTime) body.endTime = params.endTime;
   if (params.model) body.model = params.model;
   if (params.usage) body.usage = params.usage;
@@ -65,6 +68,27 @@ export async function getObservation(observationId: string): Promise<string> {
   return JSON.stringify(result, null, 2);
 }
 
+function parseJsonOption(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+export async function addObservations(params: { traceId?: string; observations?: Array<Record<string, unknown>> }): Promise<string> {
+  const observations = params.observations ?? [];
+  const results: unknown[] = [];
+  for (const observation of observations) {
+    const traceId = String(observation.traceId ?? params.traceId ?? '');
+    const name = String(observation.name ?? 'Observation');
+    if (!traceId) throw new Error('traceId is required for every observation');
+    results.push(JSON.parse(await addObservation({ ...observation, traceId, name })) as unknown);
+  }
+  return JSON.stringify({ success: true, count: results.length, observations: results }, null, 2);
+}
+
 // ─── Formatters ─────────────────────────────────────────────────────
 
 const TYPE_GLYPHS: Record<string, string> = {

package/src/langfuse/traces.ts

@@ -61,14 +61,23 @@ export async function addTrace(params: {
   }, null, 2);
 }
 
-export async function patchTraceOutput(traceId: string, outputData: unknown): Promise<string> {
+export async function patchTraceOutput(
+  traceIdOrParams: string | { traceId?: string; output?: string; outputData?: unknown },
+  outputData?: unknown,
+): Promise<string> {
+  const traceId = typeof traceIdOrParams === 'string' ? traceIdOrParams : traceIdOrParams.traceId;
+  if (!traceId) throw new Error('traceId is required');
+  const output = typeof traceIdOrParams === 'string'
+    ? outputData
+    : parseJsonOption(traceIdOrParams.outputData ?? traceIdOrParams.output);
+
   const client = getClient();
   const now = nowISO();
 
   const body: Record<string, unknown> = {
     id: traceId,
     timestamp: now,
-    output: outputData,
+    output,
   };
 
   const eventId = `${traceId}-patch-${uuidv4().slice(0, 8)}`;
@@ -88,6 +97,38 @@ export async function patchTraceOutput(traceId: string, outputData: unknown): Pr
   }, null, 2);
 }
 
+function parseJsonOption(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+export async function createTrace(params: {
+  traceId?: string;
+  id?: string;
+  userId?: string;
+  sessionId?: string;
+  name?: string;
+  input?: string;
+  inputData?: unknown;
+  output?: string;
+  outputData?: unknown;
+  metadata?: string | unknown;
+}): Promise<string> {
+  return addTrace({
+    traceId: params.traceId ?? params.id,
+    userId: params.userId,
+    sessionId: params.sessionId,
+    name: params.name,
+    inputData: parseJsonOption(params.inputData ?? params.input),
+    outputData: parseJsonOption(params.outputData ?? params.output),
+    metadata: parseJsonOption(params.metadata),
+  });
+}
+
 export async function listTraces(filters: TraceFilters): Promise<string> {
   const client = getClient();
   const params = new URLSearchParams();
@@ -141,6 +182,16 @@ export async function getTrace(traceId: string): Promise<string> {
   return JSON.stringify(trace, null, 2);
 }
 
+export async function traceView(traceId: string): Promise<string> {
+  const raw = await getTrace(traceId);
+  return formatTraceTree(raw);
+}
+
+export async function sessionView(sessionId: string): Promise<string> {
+  const raw = await listTraces({ sessionId, limit: 20, orderBy: 'timestamp.desc' });
+  return formatTracesMarkdown(raw);
+}
+
 // ─── Formatters ─────────────────────────────────────────────────────
 
 export function formatTracesTable(json: unknown): string {

package/src/version.ts

@@ -0,0 +1,39 @@
+// coaiajs/src/version.ts — single source of truth for the runtime version.
+// Reads package.json at runtime so the CLI banner, the MCP handshake, and the
+// published package can never drift apart again.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = 'coaiajs';
+
+let cached: string | undefined;
+
+/** Resolved version of the installed `coaiajs` package. */
+export function getPackageVersion(): string {
+  if (cached) return cached;
+
+  const here = dirname(fileURLToPath(import.meta.url));
+  // dist/src/version.js -> package root is two levels up.
+  // src/version.ts (ts-node/tsx) -> package root is one level up.
+  const candidates = [join(here, '..', '..', 'package.json'), join(here, '..', 'package.json')];
+
+  for (const candidate of candidates) {
+    let raw: string;
+    try {
+      raw = readFileSync(candidate, 'utf8');
+    } catch {
+      continue; // not at this depth; try the next candidate
+    }
+    const pkg = JSON.parse(raw) as { name?: string; version?: string };
+    if (pkg.name === PACKAGE_NAME && pkg.version) {
+      cached = pkg.version;
+      return cached;
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve ${PACKAGE_NAME} version: no package.json found near ${here}`,
+  );
+}