coaiajs 0.1.2 → 0.2.0

package/articles/technical/yaml-parsing-node.md

@@ -0,0 +1,266 @@
+# YAML Parsing in Node.js: Technical Assessment for CoAiA.js
+
+> Package selection brief — YAML parser for pipeline templates, session files, and config loading replacing coaiapy's PyYAML
+
+## Summary & Recommendation
+
+**Use `yaml` v2.x** (the npm package named simply `yaml`). Despite `js-yaml` having higher download numbers, the modern `yaml` package offers streaming support for large files, comment preservation (critical for human-edited pipeline templates), and a cleaner API. CoAiA pipeline templates are user-authored YAML that benefits from round-trip fidelity — comments survive parse→stringify cycles.
+
+**Pin:** `"yaml": "^2.6.0"`
+
+## What We're Replacing
+
+Coaiapy uses PyYAML for pipeline template loading:
+
+```python
+# coaiapy/pipeline.py — PyYAML pattern
+import yaml
+
+# Load pipeline template
+for template_file in search_path.glob("*.yaml"):
+    with open(yaml_file, 'r') as f:
+        data = yaml.safe_load(f)  # Parse YAML → dict
+
+# Pipeline template format:
+# name: "trace-session"
+# version: "1.0"
+# variables:
+#   - name: session_id
+#     type: string
+#     required: true
+# steps:
+#   - name: create_trace
+#     observation_type: SPAN
+```
+
+PyYAML's `safe_load` works well; the JavaScript equivalent needs the same safety guarantees plus TypeScript types.
+
+## Options Compared
+
+| Feature | yaml v2.6 | js-yaml v4.1 |
+|---------|-----------|-------------|
+| Weekly npm downloads | ~80M | ~130M |
+| GitHub stars | ~1,600 | ~6,500 |
+| Parse speed (typical files) | Good | Faster (~10%) |
+| Stringify speed | Faster | Slower |
+| Streaming support | ✅ Parse & stringify | ❌ Memory only |
+| Comment preservation | ✅ Round-trip fidelity | ❌ Comments lost |
+| Anchor/alias support | ✅ Full | ✅ Full |
+| Custom tags | ✅ Flexible API | ✅ Schema-based |
+| TypeScript | Native types | `@types/js-yaml` |
+| YAML 1.2 compliance | ✅ Full | ⚠️ Mostly |
+| Security (CVEs) | None known | CVE-2025-64718 (fixed in 4.1.1) |
+| API style | `parse(str)`, `stringify(obj)` | `load(str)`, `dump(obj)` |
+| Bundle size | ~45KB | ~30KB |
+| Dependencies | 0 | 0 |
+
+## API Overview
+
+### Basic Parse & Stringify
+
+```typescript
+import { parse, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+// Parse YAML file
+async function loadYaml<T>(filePath: string): Promise<T> {
+  const content = await readFile(filePath, 'utf-8');
+  return parse(content) as T;
+}
+
+// Stringify to YAML
+async function saveYaml(filePath: string, data: unknown): Promise<void> {
+  const yamlStr = stringify(data, {
+    indent: 2,
+    lineWidth: 120,
+  });
+  await writeFile(filePath, yamlStr, 'utf-8');
+}
+```
+
+### Pipeline Template Loading (replacing pipeline.py)
+
+```typescript
+import { parse } from 'yaml';
+import { readFile } from 'fs/promises';
+import { glob } from 'glob';
+import { z } from 'zod';
+
+// Schema (validated with Zod after YAML parse)
+const PipelineTemplateSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().default('1.0'),
+  variables: z.array(z.object({
+    name: z.string().min(1),
+    type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
+    required: z.boolean().default(true),
+    default: z.unknown().optional(),
+    choices: z.array(z.unknown()).optional(),
+  })).default([]),
+  steps: z.array(z.object({
+    name: z.string().min(1),
+    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
+    conditional: z.string().optional(),
+  })).min(1),
+});
+
+type PipelineTemplate = z.infer<typeof PipelineTemplateSchema>;
+
+async function loadPipelineTemplates(templateDir: string): Promise<Map<string, PipelineTemplate>> {
+  const templates = new Map<string, PipelineTemplate>();
+  const files = await glob('*.yaml', { cwd: templateDir, absolute: true });
+  
+  for (const file of files) {
+    const raw = parse(await readFile(file, 'utf-8'));
+    const template = PipelineTemplateSchema.parse(raw);
+    templates.set(template.name, template);
+  }
+  
+  return templates;
+}
+```
+
+### Comment-Preserving Round-Trip (unique to `yaml` package)
+
+```typescript
+import { parseDocument, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+// Load, modify, save — preserving user comments
+async function updateTemplateVersion(filePath: string, newVersion: string): Promise<void> {
+  const content = await readFile(filePath, 'utf-8');
+  const doc = parseDocument(content);  // Preserves comments, anchors, formatting
+  
+  doc.set('version', newVersion);
+  
+  await writeFile(filePath, doc.toString(), 'utf-8');
+  // Original comments and formatting are preserved!
+}
+
+// Example input:
+// # Pipeline for session tracing
+// name: trace-session
+// version: "1.0"  # Bump this on changes
+// 
+// After update, the comment "# Bump this on changes" survives
+```
+
+### Session File Persistence
+
+```typescript
+import { parse, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+interface SessionFile {
+  id: string;
+  created: string;
+  traces: { id: string; name: string; status: string }[];
+  charts: { id: string; outcome: string }[];
+  metadata: Record<string, unknown>;
+}
+
+async function saveSession(filePath: string, session: SessionFile): Promise<void> {
+  await writeFile(filePath, stringify(session, {
+    indent: 2,
+    lineWidth: 120,
+    sortMapEntries: false,  // Preserve insertion order
+  }), 'utf-8');
+}
+
+async function loadSession(filePath: string): Promise<SessionFile> {
+  const content = await readFile(filePath, 'utf-8');
+  return parse(content) as SessionFile;
+}
+```
+
+### Streaming for Large Files
+
+```typescript
+import { parseAllDocuments } from 'yaml';
+import { createReadStream } from 'fs';
+
+// Stream-parse a multi-document YAML file
+async function parseMultiDoc(filePath: string) {
+  const content = await readFile(filePath, 'utf-8');
+  const docs = parseAllDocuments(content);
+  
+  for (const doc of docs) {
+    if (doc.errors.length > 0) {
+      console.error(`Parse errors in ${filePath}:`, doc.errors);
+      continue;
+    }
+    yield doc.toJSON();
+  }
+}
+```
+
+### Config File Loading
+
+```typescript
+import { parse } from 'yaml';
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+// Load coaia.json or coaia.yaml config
+async function loadConfigFile(configPath: string): Promise<Record<string, unknown>> {
+  if (!existsSync(configPath)) return {};
+  
+  const content = await readFile(configPath, 'utf-8');
+  
+  if (configPath.endsWith('.yaml') || configPath.endsWith('.yml')) {
+    return parse(content) ?? {};
+  }
+  if (configPath.endsWith('.json')) {
+    return JSON.parse(content);
+  }
+  
+  // Try YAML first (superset of JSON)
+  try {
+    return parse(content) ?? {};
+  } catch {
+    return JSON.parse(content);
+  }
+}
+```
+
+## Integration Plan
+
+1. **Core utility:** `src/yaml.ts` — typed `loadYaml<T>()` and `saveYaml()` wrappers
+2. **Pipeline templates:** `src/pipeline/template-loader.ts` — YAML template discovery + Zod validation
+3. **Session files:** `src/session/file.ts` — YAML session persistence
+4. **Config loading:** `src/config.ts` — support `.yaml` config alongside `.json`
+5. **Round-trip editing:** Use `parseDocument()` for user-facing template modifications
+6. **Multi-doc:** Support `---` separated YAML documents for batch operations
+
+## Why Not js-yaml?
+
+1. **Comment preservation**: Pipeline templates are human-authored; losing comments on round-trip is unacceptable
+2. **Security**: CVE-2025-64718 (prototype pollution) was a recent concern; `yaml` has a clean record
+3. **YAML 1.2**: Full compliance matters for interop with other tools
+4. **Streaming**: Future-proofing for large narrative JSONL files converted to/from YAML
+5. **TypeScript**: Native types without DefinitelyTyped dependency
+
+The ~10% parse speed advantage of js-yaml is irrelevant for config/template files (sub-millisecond either way).
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 2.6.x (2026) |
+| Weekly downloads | ~80M |
+| TypeScript | Native types |
+| Dependencies | 0 |
+| YAML spec | 1.2 compliant |
+| Comment round-trip | ✅ Full support |
+| Streaming | ✅ Parse & stringify |
+| Node.js compat | ≥14 (we target ≥20) |
+| License | ISC |
+
+## References
+
+- npm: https://www.npmjs.com/package/yaml
+- GitHub: https://github.com/eemeli/yaml
+- js-yaml: https://www.npmjs.com/package/js-yaml
+- Comparison: https://npm-compare.com/js-yaml,yaml
+- Performance: https://github.com/eemeli/yaml/discussions/358
+- CVE-2025-64718: https://www.cvedetails.com/cve/CVE-2025-64718/

package/articles/technical/zod-runtime-validation.md

@@ -0,0 +1,212 @@
+# Zod Runtime Validation: Technical Assessment for CoAiA.js
+
+> Package selection brief — TypeScript-first schema validation replacing coaia-narrative's custom 181-line validation.ts
+
+## Summary & Recommendation
+
+**Use `zod` v4.x** as the unified validation layer for all coaiajs modules. Zod replaces coaia-narrative's custom `validation.ts` (181 lines of hand-rolled recursive validation) with a standard, composable, type-inferring schema library. The MCP SDK already requires Zod as a peer dependency for tool argument schemas — using it everywhere eliminates dual validation code.
+
+**Pin:** `"zod": "^4.0.0"` (v4.3.6 stable, required by `@modelcontextprotocol/sdk`)
+
+## What We're Replacing
+
+coaia-narrative has a custom `validation.ts` implementing recursive schema validation:
+
+```typescript
+// coaia-narrative/src/validation.ts — 181 lines of custom validation
+type ValidationType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'enum';
+
+interface ValidationRule {
+  type: ValidationType;
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+  minValue?: number;
+  maxValue?: number;
+  enumValues?: (string | number)[];
+  items?: ValidationRule;         // array items schema
+  properties?: Record<string, ValidationRule>;  // object properties
+}
+
+export function validate(args: any, schema: ValidationSchema): { valid: boolean; error?: string }
+```
+
+Pre-built schemas: `stringArray()`, `entityArray()`, `relationArray()`, `isoDate()`, `nonEmptyString()`.
+
+This works but: no type inference, no composition, no transform/coerce, no JSON Schema export, and every new validation type requires manual code.
+
+## Options Compared
+
+| Feature | Zod v4 | Custom validation.ts | io-ts | Yup |
+|---------|--------|---------------------|-------|-----|
+| Type inference | ✅ Automatic `z.infer<>` | ❌ Manual types | ✅ (verbose) | ⚠️ Partial |
+| Schema composition | ✅ `.merge()`, `.extend()`, `.pick()` | ❌ Manual nesting | ✅ | ✅ |
+| MCP SDK compat | ✅ Required peer dep | ❌ N/A | ❌ | ❌ |
+| JSON Schema export | ✅ `toJSONSchema()` | ❌ N/A | ❌ | ❌ |
+| Transform/coerce | ✅ `.transform()`, `.coerce` | ❌ N/A | ❌ | ✅ |
+| Error messages | ✅ Structured `ZodError` | ⚠️ Single string | ⚠️ Verbose | ✅ |
+| Bundle size | ~2KB gzip (core) | ~3KB | ~15KB | ~12KB |
+| Weekly downloads | ~100M+ | N/A | ~8M | ~15M |
+| Performance (v4) | 14x faster strings, 7x faster arrays vs v3 | Adequate | Slower | Slower |
+
+## API Overview
+
+### Replacing Custom Schemas
+
+```typescript
+import { z } from 'zod';
+
+// Replaces: ValidationSchemas.nonEmptyString()
+const NonEmptyString = z.string().min(1);
+
+// Replaces: ValidationSchemas.isoDate()
+const IsoDate = z.string().datetime();
+
+// Replaces: ValidationSchemas.stringArray(minLength)
+const StringArray = (min = 0) => z.array(z.string()).min(min);
+
+// Replaces: ValidationSchemas.entityArray()
+const Entity = z.object({
+  name: z.string().min(1),
+  entityType: z.string().min(1),
+  observations: z.array(z.string()).default([]),
+});
+const EntityArray = z.array(Entity).min(1);
+
+// Replaces: ValidationSchemas.relationArray()
+const Relation = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+  relationType: z.string().min(1),
+});
+const RelationArray = z.array(Relation);
+```
+
+### Structural Tension Chart Schema
+
+```typescript
+const ChartSchema = z.object({
+  id: z.string().min(1),
+  desiredOutcome: z.string().min(1),
+  currentReality: z.string().min(1),
+  dueDate: z.string().datetime().optional(),
+  actionSteps: z.array(z.object({
+    title: z.string().min(1),
+    status: z.enum(['pending', 'in_progress', 'done', 'blocked']),
+    currentReality: z.string().optional(),
+  })).default([]),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+type Chart = z.infer<typeof ChartSchema>;  // TypeScript type auto-generated
+```
+
+### MCP Tool Argument Validation
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'coaiajs', version: '1.0.0' });
+
+// Zod schemas ARE the MCP tool input schemas — zero duplication
+server.tool(
+  'create_chart',
+  'Create a structural tension chart',
+  {
+    desiredOutcome: z.string().describe('What you want to CREATE'),
+    currentReality: z.string().describe('Factual assessment of current state'),
+    dueDate: z.string().datetime().optional().describe('Target date (ISO 8601)'),
+    actionSteps: z.array(z.string()).optional().describe('Initial action steps'),
+  },
+  async ({ desiredOutcome, currentReality, dueDate, actionSteps }) => {
+    // Arguments are already validated and typed
+    const chart = await createChart({ desiredOutcome, currentReality, dueDate, actionSteps });
+    return { content: [{ type: 'text', text: JSON.stringify(chart) }] };
+  }
+);
+```
+
+### Pipeline Template Validation
+
+```typescript
+// Replaces coaiapy's pipeline.py validate_variables()
+const PipelineVariable = z.object({
+  name: z.string().min(1),
+  type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
+  required: z.boolean().default(true),
+  default: z.unknown().optional(),
+  choices: z.array(z.unknown()).optional(),
+});
+
+const PipelineTemplate = z.object({
+  name: z.string().min(1),
+  version: z.string().default('1.0'),
+  variables: z.array(PipelineVariable).default([]),
+  steps: z.array(z.object({
+    name: z.string().min(1),
+    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
+    conditional: z.string().optional(),
+  })).min(1),
+});
+
+// Validate and get typed result
+function loadTemplate(raw: unknown): PipelineTemplate {
+  return PipelineTemplate.parse(raw);  // throws ZodError on invalid
+}
+```
+
+### Error Handling
+
+```typescript
+import { z } from 'zod';
+
+function validateSafe<T>(schema: z.ZodSchema<T>, data: unknown): { valid: true; data: T } | { valid: false; error: string } {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { valid: true, data: result.data };
+  }
+  // Structured error messages
+  const messages = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
+  return { valid: false, error: messages.join('; ') };
+}
+```
+
+## Integration Plan
+
+1. **Shared schemas:** `src/schemas/` directory with reusable Zod schemas
+   - `chart.ts` — ChartSchema, ActionStepSchema
+   - `entity.ts` — Entity, Relation schemas (replaces validation.ts)
+   - `pipeline.ts` — PipelineTemplate, PipelineVariable
+   - `session.ts` — Session, Trace schemas
+2. **MCP tools:** Direct Zod schemas in tool definitions (no separate validation layer)
+3. **Config validation:** Zod for config file/env var validation at startup
+4. **JSON Schema export:** `toJSONSchema()` for documentation and interop
+5. **Migration:** Delete coaia-narrative's `validation.ts`, import from `@coaiajs/schemas`
+
+### @zod/mini for Future Frontend
+
+If coaiajs adds a web UI, use `@zod/mini` (~1.9KB) for client-side validation with the same schemas.
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 4.3.6 (Jan 2026) |
+| Weekly downloads | ~100M+ |
+| TypeScript | First-class, type inference is the core value |
+| Bundle size | ~2KB gzip (core), ~1.9KB (@zod/mini) |
+| MCP SDK | Required peer dependency |
+| JSON Schema | `toJSONSchema()` built-in |
+| Node.js compat | Any (zero native deps) |
+| License | MIT |
+
+## References
+
+- npm: https://www.npmjs.com/package/zod
+- GitHub: https://github.com/colinhacks/zod
+- v4 announcement: https://www.infoq.com/news/2025/08/zod-v4-available/
+- What's new in v4: https://basicutils.com/learn/zod/whats-new-in-zod-v4
+- MCP SDK peer dep: https://www.npmjs.com/package/@modelcontextprotocol/sdk

package/dist/mcp/server.js

@@ -13,7 +13,7 @@ import { ALL_TOOL_DEFINITIONS as NARRATIVE_TOOL_DEFINITIONS, handleToolCall as h
 import { PDE_MCP_TOOLS, handlePdeTool } from '../src/pde/index.js';
 import { PLANNING_MCP_TOOLS, handlePlanningTool } from '../src/planning/index.js';
 // Langfuse imports
-import { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTraceTree, } from '../src/langfuse/traces.js';
+import { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesMarkdown, formatTraceTree, } from '../src/langfuse/traces.js';
 import { addObservation, getObservation, formatObservationDisplay } from '../src/langfuse/observations.js';
 import { listPrompts, getPrompt, formatPromptsTable, formatPromptDisplay } from '../src/langfuse/prompts.js';
 import { listDatasets, getDataset, formatDatasetsTable } from '../src/langfuse/datasets.js';
@@ -133,7 +133,9 @@ async function handleCoaiapyTool(name, args) {
                     page: args.page,
                     limit: args.limit,
                 });
-                return textResult(formatTracesTable(result));
+                if (args.json_output)
+                    return textResult(result);
+                return textResult(formatTracesMarkdown(result));
             }
             case 'coaia_fuse_traces_session_view': {
                 const result = await listTraces({
@@ -141,7 +143,7 @@ async function handleCoaiapyTool(name, args) {
                 });
                 if (args.json_output)
                     return textResult(result);
-                return textResult(formatTracesTable(result));
+                return textResult(formatTracesMarkdown(result));
             }
             // ── Prompts ──
             case 'coaia_fuse_prompts_list': {

package/dist/mcp/tools/coaiapy-tools.js

@@ -145,6 +145,7 @@ export function getCoaiapyToolDefinitions(featureConfig) {
                     order_by: { type: 'string', description: 'Sort order' },
                     page: { type: 'integer', description: 'Page number', default: 1 },
                     limit: { type: 'integer', description: 'Items per page', default: 50 },
+                    json_output: { type: 'boolean', description: 'Return raw JSON instead of markdown table' },
                 },
             },
         });

package/dist/src/cli.js

@@ -61,6 +61,9 @@ async function readStdin() {
     }
     return chunks.join('');
 }
+function parseInteger(value) {
+    return parseInt(value, 10);
+}
 function resolveText(positional, opts) {
     if (opts.file)
         return readFileSync(resolve(opts.file), 'utf-8');
@@ -91,7 +94,7 @@ function registerRootCommands(program) {
         .argument('<key>', 'Redis key')
         .argument('[value]', 'Value to store')
         .option('-F, --file <path>', 'Read value from file')
-        .option('-T, --ttl <seconds>', 'Time to live in seconds', parseInt)
+        .option('-T, --ttl <minutes>', 'Time to live in minutes', parseInteger, 5555)
         .option('-v, --verbose', 'Verbose output')
         .action(actionHandler(async (key, value, opts, cmd) => {
         const val = resolveText(value, opts);
@@ -101,7 +104,7 @@ function registerRootCommands(program) {
         }
         await tash(key, val, opts.ttl);
         if (opts.verbose) {
-            console.log(formatSuccess(`Stored ${key} (${val.length} bytes${opts.ttl ? `, ttl=${opts.ttl}s` : ''})`));
+            console.log(formatSuccess(`Stored ${key} (${val.length} bytes${opts.ttl ? `, ttl=${opts.ttl}m` : ''})`));
         }
         else {
             console.log(formatSuccess(`Stored ${key}`));
@@ -112,8 +115,8 @@ function registerRootCommands(program) {
         .command('fetch')
         .description('Get a value from Redis')
         .argument('<key>', 'Redis key')
-        .option('--output <path>', 'Write result to file')
-        .option('--verbose', 'Verbose output')
+        .option('-O, --output <path>', 'Write result to file')
+        .option('-v, --verbose', 'Verbose output')
         .action(actionHandler(async (key, opts, cmd) => {
         const result = await redisFetch(key);
         if (result === null) {
@@ -458,6 +461,39 @@ function registerFuseCommands(program) {
     }));
     // ── traces ───────────────────────────────────────────────────────────
     const traces = fuse.command('traces').description('Trace operations');
+    traces
+        .command('list')
+        .description('List traces with optional filters')
+        .option('--session-id <id>', 'Filter by session ID')
+        .option('--user-id <id>', 'Filter by user ID')
+        .option('--name <name>', 'Filter by trace name')
+        .option('--tags <tags>', 'Comma-separated tags to filter by')
+        .option('--from <timestamp>', 'From timestamp (ISO 8601)')
+        .option('--to <timestamp>', 'To timestamp (ISO 8601)')
+        .option('--order-by <field>', 'Order by field')
+        .option('--page <n>', 'Page number', parseInt)
+        .option('--limit <n>', 'Items per page (default 50)', parseInt)
+        .action(actionHandler(async (opts, cmd) => {
+        const filters = {
+            sessionId: opts.sessionId,
+            userId: opts.userId,
+            name: opts.name,
+            tags: opts.tags ? opts.tags.split(',').map((t) => t.trim()) : undefined,
+            fromTimestamp: opts.from,
+            toTimestamp: opts.to,
+            orderBy: opts.orderBy,
+            page: opts.page,
+            limit: opts.limit,
+        };
+        const raw = await callModule('langfuse', 'listTraces', filters);
+        if (globals(cmd).json) {
+            console.log(raw);
+        }
+        else {
+            const formatted = await callModule('langfuse', 'formatTracesMarkdown', raw);
+            console.log(formatted);
+        }
+    }));
     traces
         .command('create')
         .description('Create a trace')
@@ -1048,7 +1084,7 @@ async function main() {
     const program = new Command();
     program
         .name('coaia')
-        .version('0.1.2', '-V, --version')
+        .version('0.1.3', '-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,6 +1,6 @@
 export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
 export type { IngestionEvent, LangfuseClientConfig } from './client.js';
-export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTraceTree } from './traces.js';
+export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTracesMarkdown, formatTraceTree } from './traces.js';
 export type { TraceFilters } from './traces.js';
 export { addObservation, getObservation, formatObservationDisplay } from './observations.js';
 export { listPrompts, getPrompt, createPrompt, formatPromptsTable, formatPromptDisplay } from './prompts.js';

package/dist/src/langfuse/index.js

@@ -1,6 +1,6 @@
 // coaiajs/src/langfuse/index.ts — Barrel export
 export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
-export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTraceTree } from './traces.js';
+export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTracesMarkdown, formatTraceTree } from './traces.js';
 export { addObservation, 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';

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

@@ -26,4 +26,5 @@ export declare function listTraces(filters: TraceFilters): Promise<string>;
 export declare function getTrace(traceId: string): Promise<string>;
 export declare function formatTracesTable(json: unknown): string;
 export declare function formatTraceTree(json: unknown): string;
+export declare function formatTracesMarkdown(json: unknown): string;
 //# sourceMappingURL=traces.d.ts.map

package/dist/src/langfuse/traces.js

@@ -211,6 +211,30 @@ export function formatTraceTree(json) {
         return `Error formatting trace tree: ${e}`;
     }
 }
+export function formatTracesMarkdown(json) {
+    try {
+        const data = typeof json === 'string' ? JSON.parse(json) : json;
+        const traces = Array.isArray(data)
+            ? data
+            : data.data ?? [];
+        if (!traces.length)
+            return '_No traces found._';
+        const header = '| ID | Name | Session | User | Timestamp |';
+        const sep = '|----|------|---------|------|-----------|';
+        const rows = traces.map((t) => {
+            const id = trunc(String(t.id ?? ''), 20);
+            const name = trunc(String(t.name ?? 'Unnamed'), 30);
+            const session = trunc(String(t.sessionId ?? ''), 24);
+            const user = trunc(String(t.userId ?? ''), 16);
+            const ts = String(t.timestamp ?? '').slice(0, 19);
+            return `| ${id} | ${name} | ${session} | ${user} | ${ts} |`;
+        });
+        return [header, sep, ...rows, '', `_Total: ${traces.length} trace(s)_`].join('\n');
+    }
+    catch (e) {
+        return `Error formatting traces: ${e}`;
+    }
+}
 // ─── Helpers ────────────────────────────────────────────────────────
 function trunc(s, len) {
     return s.length > len ? s.slice(0, len - 3) + '...' : s;

package/dist/src/redis.d.ts

@@ -3,7 +3,7 @@ declare const Redis: typeof IORedis.Redis;
 type RedisClient = InstanceType<typeof Redis>;
 /** Get or create the lazy Redis client. */
 export declare function getClient(): RedisClient;
-/** Store a key-value pair with optional TTL (seconds). */
+/** Store a key-value pair with optional TTL in minutes, matching coaiapy. */
 export declare function tash(key: string, value: string, ttl?: number): Promise<void>;
 /** Fetch a value by key. Returns null if not found. */
 export declare function fetch(key: string): Promise<string | null>;