coaiajs 0.1.0

package/mcp/tools/coaiapy-tools.ts

@@ -0,0 +1,364 @@
+// coaiajs/mcp/tools/coaiapy-tools.ts — Tool definitions for coaiapy-equivalent tools
+// Port of coaiapy-mcp/server.py tool schemas (20 tools)
+
+import type { FeatureConfig } from '../config.js';
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export function getCoaiapyToolDefinitions(featureConfig: FeatureConfig): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+
+  // ─── Redis Tools ────────────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_tash')) {
+    tools.push({
+      name: 'coaia_tash',
+      description: 'Stash key-value pair to Redis',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'Redis key' },
+          value: { type: 'string', description: 'Value to store' },
+        },
+        required: ['key', 'value'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fetch')) {
+    tools.push({
+      name: 'coaia_fetch',
+      description: 'Fetch value from Redis by key',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'Redis key to fetch' },
+        },
+        required: ['key'],
+      },
+    });
+  }
+
+  // ─── Trace Tools ────────────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_trace_create')) {
+    tools.push({
+      name: 'coaia_fuse_trace_create',
+      description: 'Create a Langfuse trace for observability tracking',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'Unique trace identifier' },
+          user_id: { type: 'string', description: 'User identifier' },
+          session_id: { type: 'string', description: 'Session identifier' },
+          name: { type: 'string', description: 'Trace name' },
+          metadata: { type: 'object', description: 'Metadata dictionary' },
+          input_data: { description: 'Input data' },
+          output_data: { description: 'Output data' },
+        },
+        required: ['trace_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_add_observation')) {
+    tools.push({
+      name: 'coaia_fuse_add_observation',
+      description: 'Add an observation (event, span, or generation) to a trace',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          observation_id: { type: 'string', description: 'Unique observation identifier' },
+          trace_id: { type: 'string', description: 'Parent trace ID' },
+          name: { type: 'string', description: 'Observation name' },
+          observation_type: { type: 'string', enum: ['SPAN', 'EVENT', 'GENERATION'], description: 'Observation type' },
+          parent_id: { type: 'string', description: 'Parent observation ID for nesting' },
+          metadata: { type: 'object', description: 'Metadata' },
+          input_data: { description: 'Input data' },
+          output_data: { description: 'Output data' },
+          start_time: { type: 'string', description: 'Start timestamp (ISO 8601)' },
+          end_time: { type: 'string', description: 'End timestamp (ISO 8601)' },
+        },
+        required: ['observation_id', 'trace_id', 'name'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_trace_patch_output')) {
+    tools.push({
+      name: 'coaia_fuse_trace_patch_output',
+      description: 'Update the output field of an existing trace',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'Trace ID to update' },
+          output_data: { description: 'New output data' },
+        },
+        required: ['trace_id', 'output_data'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_trace_get')) {
+    tools.push({
+      name: 'coaia_fuse_trace_get',
+      description: 'Get a specific trace by ID with all its observations',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'Trace ID to fetch' },
+          json_output: { type: 'boolean', description: 'Return raw JSON instead of formatted tree' },
+        },
+        required: ['trace_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_trace_view')) {
+    tools.push({
+      name: 'coaia_fuse_trace_view',
+      description: 'View trace details with observations (alias for trace_get)',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'Trace ID' },
+          json_output: { type: 'boolean', description: 'Return raw JSON' },
+        },
+        required: ['trace_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_observation_get')) {
+    tools.push({
+      name: 'coaia_fuse_observation_get',
+      description: 'Get a specific observation by ID',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          observation_id: { type: 'string', description: 'Observation ID' },
+          json_output: { type: 'boolean', description: 'Return raw JSON' },
+        },
+        required: ['observation_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_traces_list')) {
+    tools.push({
+      name: 'coaia_fuse_traces_list',
+      description: 'List traces with optional filtering by session, user, name, tags, and time range',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          session_id: { type: 'string', description: 'Filter by session ID' },
+          user_id: { type: 'string', description: 'Filter by user ID' },
+          name: { type: 'string', description: 'Filter by trace name' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
+          from_timestamp: { type: 'string', description: 'Filter from timestamp (ISO 8601)' },
+          to_timestamp: { type: 'string', description: 'Filter to timestamp (ISO 8601)' },
+          order_by: { type: 'string', description: 'Sort order' },
+          page: { type: 'integer', description: 'Page number', default: 1 },
+          limit: { type: 'integer', description: 'Items per page', default: 50 },
+        },
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_traces_session_view')) {
+    tools.push({
+      name: 'coaia_fuse_traces_session_view',
+      description: 'View all traces for a specific session',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          session_id: { type: 'string', description: 'Session ID to view traces for' },
+          json_output: { type: 'boolean', description: 'Return raw JSON' },
+        },
+        required: ['session_id'],
+      },
+    });
+  }
+
+  // ─── Prompts Tools ──────────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_prompts_list')) {
+    tools.push({
+      name: 'coaia_fuse_prompts_list',
+      description: 'List all Langfuse prompts',
+      inputSchema: { type: 'object', properties: {} },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_prompts_get')) {
+    tools.push({
+      name: 'coaia_fuse_prompts_get',
+      description: 'Get a specific Langfuse prompt by name',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Prompt name' },
+          label: { type: 'string', description: 'Optional deployment label' },
+        },
+        required: ['name'],
+      },
+    });
+  }
+
+  // ─── Dataset Tools ──────────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_datasets_list')) {
+    tools.push({
+      name: 'coaia_fuse_datasets_list',
+      description: 'List all Langfuse datasets',
+      inputSchema: { type: 'object', properties: {} },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_datasets_get')) {
+    tools.push({
+      name: 'coaia_fuse_datasets_get',
+      description: 'Get a specific dataset by name with its items',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Dataset name' },
+        },
+        required: ['name'],
+      },
+    });
+  }
+
+  // ─── Score Config Tools ─────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_score_configs_list')) {
+    tools.push({
+      name: 'coaia_fuse_score_configs_list',
+      description: 'List all Langfuse score configurations',
+      inputSchema: { type: 'object', properties: {} },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_score_configs_get')) {
+    tools.push({
+      name: 'coaia_fuse_score_configs_get',
+      description: 'Get specific Langfuse score configuration',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name_or_id: { type: 'string', description: 'Score config name or ID' },
+        },
+        required: ['name_or_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_score_apply')) {
+    tools.push({
+      name: 'coaia_fuse_score_apply',
+      description: 'Apply a score configuration to a trace or observation with validation',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          config_name_or_id: { type: 'string', description: 'Name or ID of the score configuration' },
+          target_type: { type: 'string', enum: ['trace', 'session'], description: 'Target type' },
+          target_id: { type: 'string', description: 'ID of the trace or session' },
+          value: { description: 'Score value (validated against config)' },
+          observation_id: { type: 'string', description: 'Optional observation ID' },
+          comment: { type: 'string', description: 'Optional comment' },
+        },
+        required: ['config_name_or_id', 'target_type', 'target_id', 'value'],
+      },
+    });
+  }
+
+  // ─── Comment Tools ──────────────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_comments_list')) {
+    tools.push({
+      name: 'coaia_fuse_comments_list',
+      description: 'List comments with optional filtering by object type/ID or author',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          object_type: { type: 'string', description: 'Filter by object type (trace, observation, session, prompt)' },
+          object_id: { type: 'string', description: 'Filter by specific object ID' },
+          author_user_id: { type: 'string', description: 'Filter by author user ID' },
+          page: { type: 'integer', description: 'Page number', default: 1 },
+          limit: { type: 'integer', description: 'Items per page', default: 50 },
+        },
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_comments_get')) {
+    tools.push({
+      name: 'coaia_fuse_comments_get',
+      description: 'Get a specific comment by ID',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          comment_id: { type: 'string', description: 'Comment ID' },
+        },
+        required: ['comment_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_comments_create')) {
+    tools.push({
+      name: 'coaia_fuse_comments_create',
+      description: 'Create a comment attached to an object (trace, observation, session, or prompt)',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'Comment text' },
+          object_type: { type: 'string', description: 'Object type (trace, observation, session, prompt)' },
+          object_id: { type: 'string', description: 'Object ID' },
+          author_user_id: { type: 'string', description: 'Author user ID' },
+        },
+        required: ['text', 'object_type', 'object_id'],
+      },
+    });
+  }
+
+  // ─── Media Tools (FULL only) ────────────────────────────────────
+
+  if (featureConfig.isToolEnabled('coaia_fuse_media_upload')) {
+    tools.push({
+      name: 'coaia_fuse_media_upload',
+      description: 'Upload a file and attach it to a Langfuse trace or observation. Supports images, video, audio, documents. Auto-detects MIME type.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: { type: 'string', description: 'Absolute path to the file to upload' },
+          trace_id: { type: 'string', description: 'Trace ID to attach media to' },
+          field: { type: 'string', enum: ['input', 'output', 'metadata'], description: 'Field to attach to', default: 'input' },
+          observation_id: { type: 'string', description: 'Optional observation ID' },
+          content_type: { type: 'string', description: 'MIME type override (auto-detected if omitted)' },
+        },
+        required: ['file_path', 'trace_id'],
+      },
+    });
+  }
+
+  if (featureConfig.isToolEnabled('coaia_fuse_media_get')) {
+    tools.push({
+      name: 'coaia_fuse_media_get',
+      description: 'Get media metadata by media ID',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          media_id: { type: 'string', description: 'Media ID' },
+        },
+        required: ['media_id'],
+      },
+    });
+  }
+
+  return tools;
+}

package/mcp/tools/index.ts

@@ -0,0 +1,4 @@
+// coaiajs/mcp/tools/index.ts — Barrel export of all tool definitions
+
+export { getCoaiapyToolDefinitions } from './coaiapy-tools.js';
+export type { ToolDefinition } from './coaiapy-tools.js';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "coaiajs",
+  "version": "0.1.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"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/src/cli.js",
+    "mcp": "node dist/mcp/server.js",
+    "test": "node --test",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "ioredis": "^5.4.0",
+    "zod": "^3.23.0",
+    "commander": "^12.1.0",
+    "openai": "^4.70.0",
+    "@aws-sdk/client-polly": "^3.700.0",
+    "@octokit/rest": "^21.0.0",
+    "dotenv": "^16.4.0",
+    "js-yaml": "^4.1.0",
+    "langfuse": "^3.0.0",
+    "minimist": "^1.2.8",
+    "chalk": "^5.3.0",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/minimist": "^1.2.5",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "coaia",
+    "structural-tension",
+    "mcp",
+    "narrative",
+    "pde",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/rispecs/00-coaiajs-platform.spec.md

@@ -0,0 +1,102 @@
+# 00 — CoAiA.js Platform
+
+> Master specification for the unified TypeScript platform.
+
+## Desired Outcome
+
+A unified TypeScript platform that consolidates coaiapy, coaia-narrative, coaia-pde, and coaia-planning into a single modern Node.js package with full CLI and MCP server parity.
+
+Single `npm install coaiajs` provides:
+- Unified CLI (`coaia`) with all commands
+- Unified MCP server (`coaiajs-mcp`) with 64+ tools
+- Shared type system and JSONL storage engine
+- Modern Node.js 20+ (no Python 3.6 constraints)
+
+## Structural Tension
+
+**Current Reality:**
+- Four separate repositories with overlapping type systems, duplicated JSONL logic, and fragmented MCP servers:
+  - coaiapy v0.4.5 (Python, ~28,700 LOC, 68 files) — config, Redis, Langfuse, pipeline, audio, GitHub, LLM
+  - coaia-narrative v0.12.0 (TypeScript, ~2,500 LOC) — JSONL graph, STC, narrative beats, MMOT, 27 MCP tools
+  - coaia-pde v0.1.1 (TypeScript, ~1,600 LOC) — PDE→STC transformation, 12 MCP tools
+  - coaia-planning v0.1.0 (TypeScript, ~1,400 LOC) — plan parsing, plan↔STC sync, 5 MCP tools
+- coaiajs v0.1.0 exists with core modules implemented (config, redis, github, llm, audio, environment — ~1,042 LOC) and types unified (280 lines)
+- Five sub-module directories (narrative, pde, planning, langfuse, pipeline) are empty stubs
+- MCP server directory is scaffolded but empty
+- CLI is referenced in package.json but has no implementation
+- No tests exist
+
+**Desired Outcome:**
+Single `coaiajs` npm package providing:
+- Unified CLI (`coaia`) with all commands
+- Unified MCP server (`coaiajs-mcp`) with 64+ tools
+- Shared type system and JSONL storage engine
+- Modern Node.js 20+ (no Python 3.6 constraints)
+
+## Components
+
+- [01-core-config](./01-core-config.spec.md) — Configuration management
+- [02-redis-module](./02-redis-module.spec.md) — Redis tash/fetch
+- [03-langfuse-module](./03-langfuse-module.spec.md) — Langfuse observability
+- [04-narrative-engine](./04-narrative-engine.spec.md) — JSONL knowledge graph, STC, narrative beats, MMOT
+- [05-pde-engine](./05-pde-engine.spec.md) — PDE→STC transformation
+- [06-planning-engine](./06-planning-engine.spec.md) — Plan parsing, plan↔STC sync
+- [07-pipeline-templates](./07-pipeline-templates.spec.md) — Pipeline template engine
+- [08-cli-interface](./08-cli-interface.spec.md) — Unified CLI
+- [09-mcp-server](./09-mcp-server.spec.md) — Unified MCP server
+- [10-audio-module](./10-audio-module.spec.md) — Audio transcription and synthesis
+
+## Lineage
+
+| Source | Version | What is inherited |
+|--------|---------|-------------------|
+| coaiapy | v0.4.5 (Python) | Core config, Redis, Langfuse, pipeline, environment, audio, GitHub, LLM |
+| coaia-narrative | v0.12.0 (TypeScript) | JSONL graph, STC lifecycle, narrative beats, MMOT, CLI visualizer |
+| coaia-pde | v0.1.1 (TypeScript) | PDE→STC transformation, session management, direction mapping |
+| coaia-planning | v0.1.0 (TypeScript) | Plan parsing, plan↔STC sync, action step telescoping |
+
+## Architectural Decisions
+
+### ESM-Only Package
+All imports use `.js` extensions. `"type": "module"` in package.json. No CommonJS fallback.
+
+### Strict TypeScript
+`strict: true`, no `any` without explicit justification. Zod for runtime validation at module boundaries.
+
+### Lazy Client Initialization
+Redis, OpenAI, Polly, Octokit, Langfuse clients are created on first use. Each module exports `resetClient()` for test isolation. No side effects at import time.
+
+### Single Type Source
+All types live in `src/types.ts`. Sub-modules import from there, never define their own parallel types. This is the union of all four parent type systems.
+
+### Config Priority Chain
+Environment variables → `.env` file → `coaia.json` → defaults. Deep merge for nested structures.
+
+## MCP Tool Budget
+
+| Module | Inherited tools | Target tools |
+|--------|----------------|--------------|
+| narrative-engine | 27 (coaia-narrative) | 28 |
+| pde-engine | 12 (coaia-pde) | 12 |
+| planning-engine | 5 (coaia-planning) | 6 |
+| redis | 0 (new) | 5 |
+| langfuse | 0 (new) | 8 |
+| pipeline | 0 (new) | 3 |
+| audio | 0 (new) | 2 |
+| **Total** | **44** | **64** |
+
+## Feature Gating
+
+The MCP server supports three modes controlled by `COAIAJS_MCP_MODE`:
+- **MINIMAL** — Core narrative tools only (STC, knowledge graph, MMOT)
+- **STANDARD** — Narrative + PDE + planning + Redis
+- **FULL** — All 64+ tools including Langfuse, pipeline, audio
+
+## Quality Criteria
+
+- ✅ Every coaiapy CLI command has a `coaia` subcommand equivalent
+- ✅ Every MCP tool from parent projects is available in `coaiajs-mcp`
+- ✅ Type system covers 100% of parent project types
+- ✅ JSONL format is byte-compatible with coaia-narrative output
+- ✅ Redis tash/fetch behavior identical to coaiapy
+- ✅ Config loading produces identical results to coaiapy's read_config()

package/rispecs/01-core-config.spec.md

@@ -0,0 +1,89 @@
+# 01 — Core Config
+
+> Configuration management system for all CoAiA modules.
+
+## Desired Outcome
+
+A unified config loader that provides every CoAiA module with its settings through a single `getConfig()` call, merging environment variables, `.env` files, and `coaia.json` with deterministic priority.
+
+## Structural Tension
+
+**Current Reality:**
+- `src/config.ts` is fully implemented (172 lines) with `readConfig()`, `getConfig()`, `mergeConfigs()`, `resetConfig()`, and a `config` Proxy for lazy access
+- Supports env vars > .env > coaia.json > defaults priority chain
+- Searches for `coaia.json` or `.coaia/config.json` in cwd and home directory
+- Covers Redis (URL, host/port, Upstash), Langfuse, OpenAI, AWS, GitHub credentials
+- Singleton pattern with lazy loading and proxy access
+- Deep merge implementation for nested config objects
+
+**Desired Outcome:**
+Config system that handles all module configuration needs including:
+- Everything currently implemented
+- Langfuse extended config (dataset settings, prompt cache TTL)
+- Pipeline template directory paths
+- MCP server mode selection (MINIMAL/STANDARD/FULL)
+- Narrative memory file path
+- PDE working directory
+- Plan sync settings
+
+## CoaiaConfig Shape
+
+```typescript
+interface CoaiaConfig {
+  // Redis
+  redis_url?: string;
+  redis_host?: string;
+  redis_port?: number;
+
+  // Langfuse
+  langfuse_secret_key?: string;
+  langfuse_public_key?: string;
+  langfuse_host?: string;
+  langfuse_dataset_name?: string;
+  langfuse_prompt_cache_ttl?: number;
+
+  // OpenAI
+  openai_api_key?: string;
+  openai_model?: string;
+
+  // AWS (Polly)
+  aws_access_key_id?: string;
+  aws_secret_access_key?: string;
+  aws_region?: string;
+  aws_polly_voice?: string;
+
+  // GitHub
+  github_token?: string;
+
+  // Narrative
+  memory_file_path?: string;
+
+  // PDE
+  pde_dir?: string;
+
+  // Pipeline
+  pipeline_template_dir?: string;
+
+  // MCP
+  mcp_mode?: 'MINIMAL' | 'STANDARD' | 'FULL';
+}
+```
+
+## Config Resolution
+
+```
+1. process.env       — highest priority, always wins
+2. .env file         — loaded via dotenv from cwd
+3. coaia.json        — searched in cwd, then ~/.coaia/config.json
+4. defaults          — hardcoded fallbacks (redis_host: 'localhost', redis_port: 6379, etc.)
+```
+
+Deep merge: nested objects are merged recursively. Arrays are replaced, not concatenated. `undefined` values do not overwrite existing values.
+
+## Quality Criteria
+
+- ✅ `getConfig()` returns identical results to coaiapy's `read_config()` for the same env/file state
+- ✅ Config is loaded once and cached; `resetConfig()` clears the cache for testing
+- ✅ `config` proxy provides `config.redis_url` shorthand without explicit `getConfig()` call
+- ✅ Missing config keys return `undefined`, never throw
+- ✅ Deep merge handles nested structures correctly

package/rispecs/02-redis-module.spec.md

@@ -0,0 +1,62 @@
+# 02 — Redis Module
+
+> Redis key-value store with tash/fetch convention.
+
+## Desired Outcome
+
+A thin Redis wrapper providing `tash(key, value, ttl?)` and `fetch(key)` with lazy ioredis connection, Upstash support, and pattern-based key operations — the universal CoAiA data persistence shorthand.
+
+## Structural Tension
+
+**Current Reality:**
+- `src/redis.ts` is fully implemented (94 lines) with `tash()`, `fetch()`, `del()`, `keys()`, `exists()`, `disconnect()`, `resetClient()`
+- Uses ioredis with lazy connection
+- Supports direct URL, Upstash REST (`rediss://`) URLs, host/port fallback
+- Key-value operations with optional TTL
+- Parity with coaiapy's `tash/fetch` pattern achieved
+
+**Desired Outcome:**
+Redis module with everything currently implemented plus:
+- Hash operations (`htash`/`hfetch`) for structured data
+- Sorted set operations for time-series data (session logs, trace ordering)
+- Pub/Sub support for inter-agent messaging
+- Connection health check (`ping()`)
+- MCP tool exposure (5 tools: tash, fetch, del, keys, exists)
+
+## Core API
+
+```typescript
+// Key-value (implemented)
+tash(key: string, value: string, ttl?: number): Promise<void>
+fetch(key: string): Promise<string | null>
+del(key: string): Promise<number>
+keys(pattern: string): Promise<string[]>
+exists(key: string): Promise<boolean>
+
+// Hash (desired)
+htash(key: string, field: string, value: string): Promise<void>
+hfetch(key: string, field?: string): Promise<Record<string, string> | string | null>
+
+// Sorted set (desired)
+zadd(key: string, score: number, member: string): Promise<void>
+zrange(key: string, start: number, stop: number): Promise<string[]>
+
+// Utility (desired)
+ping(): Promise<boolean>
+```
+
+## Connection Strategy
+
+1. If `REDIS_URL` or config `redis_url` is set → use it directly
+2. If URL starts with `rediss://` → enable TLS (Upstash pattern)
+3. Otherwise → construct from `redis_host` (default: `localhost`) and `redis_port` (default: `6379`)
+4. Connection is lazy — no connect until first operation
+5. Reconnect automatically on transient failures (ioredis default behavior)
+
+## Quality Criteria
+
+- ✅ `tash('key', 'value')` behaves identically to coaiapy's `tash('key', 'value')`
+- ✅ `tash('key', 'value', 300)` sets a 300-second TTL
+- ✅ `fetch('nonexistent')` returns `null`, never throws
+- ✅ Upstash URLs work without additional configuration
+- ✅ `resetClient()` disconnects and clears for test isolation