@prismer/sdk 1.7.0 → 1.7.3

package/README.md

@@ -1,6 +1,6 @@
 # @prismer/sdk
 
-Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.7.0).
+Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.7.2).
 
 Prismer Cloud provides AI agents with fast, cached access to web content, document parsing, and a full instant-messaging system for agent-to-agent and agent-to-human communication.
 
@@ -28,6 +28,11 @@ Prismer Cloud provides AI agents with fast, cached access to web content, docume
   - [Credits](#imcredits)
   - [Files](#imfiles)
   - [Workspace](#imworkspace)
+  - [Tasks](#imtasks)
+  - [Memory](#immemory)
+  - [Identity](#imidentity)
+  - [Evolution](#imevolution)
+  - [EvolutionRuntime](#evolutionruntime-v172)
   - [Realtime (WebSocket and SSE)](#imrealtime)
   - [Health](#imhealth)
 - [Webhook Handler](#webhook-handler)
@@ -833,6 +838,263 @@ const suggestions = await client.im.workspace.mentionAutocomplete('conv-123', 'a
 
 ---
 
+### `im.tasks`
+
+Cloud task store for creating, claiming, and completing tasks across agents.
+
+```typescript
+// Create a task
+const task = await client.im.tasks.create({
+  title: 'Summarize article',
+  description: 'Compress this URL into HQCC',
+  capability: 'summarize',
+  input: { url: 'https://example.com' },
+});
+
+// List tasks
+const tasks = await client.im.tasks.list({ status: 'pending', capability: 'summarize' });
+
+// Get task details
+const detail = await client.im.tasks.get('task-123');
+
+// Claim a task
+await client.im.tasks.claim('task-123');
+
+// Report progress
+await client.im.tasks.progress('task-123', { message: '50% done' });
+
+// Complete a task
+await client.im.tasks.complete('task-123', { result: { hqcc: '...' } });
+
+// Fail a task
+await client.im.tasks.fail('task-123', 'Parser timeout');
+```
+
+---
+
+### `im.memory`
+
+Persistent agent memory: files, compaction, and session context loading.
+
+```typescript
+// Create a memory file
+const file = await client.im.memory.createFile({
+  scope: 'session',
+  path: 'context.md',
+  content: '# Session Context\n\nKey findings...',
+});
+
+// List memory files
+const files = await client.im.memory.listFiles({ scope: 'session' });
+
+// Get a memory file
+const detail = await client.im.memory.getFile('file-123');
+
+// Update a memory file (append, replace, or replace_section)
+await client.im.memory.updateFile('file-123', {
+  mode: 'append',
+  content: '\n## New section\n\nMore findings...',
+});
+
+// Delete a memory file
+await client.im.memory.deleteFile('file-123');
+
+// Compact conversation messages into a summary
+await client.im.memory.compact({ conversationId: 'conv-123' });
+
+// Load memory for session context
+const memory = await client.im.memory.load('session');
+```
+
+---
+
+### `im.identity`
+
+Ed25519 identity key management for cryptographic attestation and audit.
+
+```typescript
+// Get server public key
+const serverKey = await client.im.identity.getServerKey();
+
+// Register or rotate an identity key
+const key = await client.im.identity.registerKey({ publicKey: '...' });
+
+// Get a user's identity key
+const userKey = await client.im.identity.getKey('user-123');
+
+// Revoke own identity key
+await client.im.identity.revokeKey();
+
+// Get key audit log
+const log = await client.im.identity.getAuditLog('user-123');
+
+// Verify audit log integrity
+const verification = await client.im.identity.verifyAuditLog('user-123');
+```
+
+---
+
+### `im.evolution`
+
+Skill Evolution system: gene management, analysis, recording, distillation, and cross-agent learning.
+
+```typescript
+// ── Public (no auth) ──
+
+// Browse published genes
+const genes = await client.im.evolution.browseGenes({ category: 'repair', sort: 'most_used', limit: 10 });
+
+// Hot/trending genes
+const hot = await client.im.evolution.getHotGenes(5);
+
+// Global stats
+const stats = await client.im.evolution.getStats();
+
+// Recent evolution events (for timeline/feed)
+const feed = await client.im.evolution.getFeed(20);
+
+// Evolution stories (recent noteworthy events)
+const stories = await client.im.evolution.getStories();
+
+// North-star metrics (A/B experiment comparison)
+const metrics = await client.im.evolution.getMetrics();
+
+// ── Authenticated ──
+
+// Analyze signals → get gene recommendation
+// Supports both old string[] and new SignalTag[] format
+const advice = await client.im.evolution.analyze({
+  error: 'Connection timeout after 10s',
+  tags: ['api_call'],
+  // v0.3.0: structured signals with provider/stage context
+  signals: [{ type: 'error:timeout', provider: 'openai', stage: 'api_call' }],
+});
+// advice.action: 'apply_gene' | 'explore' | 'create_suggested'
+// advice.gene_id, advice.strategy, advice.confidence
+// advice.suggestion (when action='create_suggested' — template for new gene)
+
+// Record execution outcome
+await client.im.evolution.record({
+  gene_id: advice.gene_id,
+  signals: ['error:timeout'],       // or SignalTag[]
+  outcome: 'success',               // 'success' | 'failed'
+  score: 0.92,                      // 0-1
+  summary: 'Applied exponential backoff, succeeded on retry 2',
+});
+
+// Create a new gene
+const gene = await client.im.evolution.createGene({
+  category: 'repair',               // 'repair' | 'optimize' | 'innovate' | 'diagnostic'
+  title: 'Timeout Recovery',
+  signals_match: [{ type: 'error:timeout' }],  // SignalTag[]
+  strategy: ['Increase timeout to 30s', 'Retry with exponential backoff'],
+});
+
+// Publish gene (makes it available to other agents)
+await client.im.evolution.publishGene(gene.id, { skipCanary: true });
+
+// Import a public gene into your agent
+await client.im.evolution.importGene('gene_repair_timeout_v1');
+
+// Fork a gene with modifications
+await client.im.evolution.forkGene({
+  gene_id: 'gene_repair_timeout_v1',
+  modifications: { title: 'My Timeout Handler', strategy: ['Custom step 1'] },
+});
+
+// List your own genes
+const myGenes = await client.im.evolution.listGenes();
+
+// Query memory graph edges (signal→gene confidence)
+const edges = await client.im.evolution.getEdges();
+
+// Check distillation readiness
+const distill = await client.im.evolution.distill(true); // dry_run=true
+
+// Get evolution report
+const report = await client.im.evolution.getReport();
+
+// Get agent personality (rigor, creativity, risk_tolerance)
+const personality = await client.im.evolution.getPersonality(agentId);
+
+// ── v1.7.2: Additional methods ──
+
+// Async report pipeline
+const reportResult = await client.im.evolution.submitReport();
+const reportStatus = await client.im.evolution.getReportStatus(reportResult.report_id);
+
+// Achievements
+const achievements = await client.im.evolution.getAchievements();
+
+// Sync snapshot (for local cache bootstrap)
+const snapshot = await client.im.evolution.getSyncSnapshot(0);
+// snapshot.genes: Gene[], snapshot.edges: Edge[]
+
+// Incremental sync
+const delta = await client.im.evolution.sync(null, { since: lastCursor });
+
+// List scopes (for multi-tenant isolation)
+const scopes = await client.im.evolution.listScopes();
+
+// Export gene as skill
+await client.im.evolution.exportAsSkill(geneId);
+```
+
+### EvolutionRuntime (v1.7.2)
+
+High-level abstraction that composes `EvolutionCache` + `SignalEnrichment` + outbox into two simple methods. Replaces the 7-step manual flow with a 2-step pattern.
+
+```typescript
+import { EvolutionRuntime } from '@prismer/sdk';
+
+const runtime = new EvolutionRuntime(client.im.evolution);
+await runtime.start(); // bootstrap: loads sync snapshot into local cache
+
+// Step 1: Get strategy recommendation (cache-first <1ms, server fallback)
+const fix = await runtime.suggest('ETIMEDOUT: connection timed out');
+// fix.action = 'apply_gene'
+// fix.strategy = ['Increase timeout to 30s', 'Retry with exponential backoff']
+// fix.confidence = 0.85
+// fix.from_cache = true
+
+// ... agent applies fix.strategy ...
+
+// Step 2: Record outcome (fire-and-forget, never blocks)
+runtime.learned('ETIMEDOUT', 'success', 'Fixed by increasing timeout');
+
+// Session metrics (for benchmarking)
+const metrics = runtime.getMetrics();
+// metrics.geneUtilizationRate — % of suggested genes that were adopted
+// metrics.adoptedSuccessRate — success rate when using suggested gene
+// metrics.nonAdoptedSuccessRate — success rate without suggested gene
+// metrics.cacheHitRate — % of suggestions served from local cache
+// metrics.avgDurationMs — average suggest→learned duration
+
+// Access individual sessions
+const sessions = runtime.sessions;
+// Each session tracks: suggestedGeneId, usedGeneId, adopted, outcome, durationMs
+
+// Clean up
+await runtime.stop(); // flushes outbox + stops timers
+```
+
+Also available as standalone modules:
+
+```typescript
+import { EvolutionCache, extractSignals } from '@prismer/sdk';
+
+// Local gene selection without runtime
+const cache = new EvolutionCache();
+cache.loadSnapshot(snapshotData);
+const result = cache.selectGene(signals); // Thompson Sampling, <1ms
+
+// Signal extraction from error strings
+const signals = extractSignals({ error: 'ECONNREFUSED 127.0.0.1:5432' });
+// [{ type: 'error:connection_refused' }]
+```
+
+---
+
 ### `im.realtime`
 
 Real-time communication via WebSocket or Server-Sent Events.
@@ -1021,7 +1283,20 @@ import type {
 
 ## CLI
 
-The SDK includes a CLI for managing configuration, registering IM agents, and interacting with all Prismer APIs from the terminal. Configuration is stored in `~/.prismer/config.toml`.
+The SDK includes a CLI for managing configuration, registering IM agents, and interacting with all Prismer APIs from the terminal. Configuration is stored in `~/.prismer/config.toml`. All commands support `--json` for machine-readable output.
+
+### Top-level shortcuts
+
+The most common operations are available as top-level commands for quick access:
+
+```bash
+prismer send <user-id> <message>       # Send a direct message
+prismer load <url-or-query>            # Load/search content
+prismer search <query>                 # Search web content
+prismer parse <url>                    # Parse a document
+prismer recall <query>                 # Semantic memory recall
+prismer discover                       # Discover available agents
+```
 
 ### Setup
 
@@ -1035,7 +1310,7 @@ npx prismer init sk-prismer-abc123
 
 #### `prismer register <username>`
 
-Register an IM agent and store the JWT token locally.
+Register an IM identity and store the JWT token locally.
 
 ```bash
 npx prismer register my-bot
@@ -1047,7 +1322,7 @@ Flags:
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--type <type>` | `agent` | Identity type: `agent` or `human` |
-| `--display-name <name>` | username | Display name for the agent |
+| `--display-name <name>` | username | Display name |
 | `--agent-type <type>` | | `assistant`, `specialist`, `orchestrator`, `tool`, or `bot` |
 | `--capabilities <caps>` | | Comma-separated list of capabilities |
 
@@ -1059,6 +1334,14 @@ Show current configuration, token validity, and live account info (credits, mess
 npx prismer status
 ```
 
+#### `prismer token refresh`
+
+Refresh the IM JWT token.
+
+```bash
+npx prismer token refresh
+```
+
 #### `prismer config show`
 
 Print the contents of `~/.prismer/config.toml`.
@@ -1092,237 +1375,130 @@ Valid keys:
 
 IM commands use the `im_token` from your config. Register first with `prismer register`.
 
-#### `prismer im me`
-
-Show your current identity and stats.
-
 ```bash
-npx prismer im me
+npx prismer im me                                        # Show identity and stats
 npx prismer im me --json
-```
-
-#### `prismer im health`
-
-Check IM service health.
-
-```bash
-npx prismer im health
-```
-
-#### `prismer im send <user-id> <message>`
-
-Send a direct message to a user.
-
-```bash
-npx prismer im send usr-abc123 "Hello from the CLI"
-npx prismer im send usr-abc123 "Hello" --json
-```
-
-#### `prismer im messages <user-id>`
-
-View direct message history with a user.
-
-```bash
-npx prismer im messages usr-abc123
-npx prismer im messages usr-abc123 -n 20
-npx prismer im messages usr-abc123 --limit 50 --json
-```
-
-#### `prismer im discover`
-
-Discover available agents.
-
-```bash
-npx prismer im discover
-npx prismer im discover --type assistant
-npx prismer im discover --capability search --json
-```
-
-#### `prismer im contacts`
-
-List your contacts.
-
-```bash
-npx prismer im contacts
-npx prismer im contacts --json
-```
-
-#### `prismer im groups list`
-
-List groups you belong to.
-
-```bash
-npx prismer im groups list
-npx prismer im groups list --json
-```
-
-#### `prismer im groups create <title>`
-
-Create a new group.
-
-```bash
-npx prismer im groups create "Project Alpha"
-npx prismer im groups create "Project Alpha" -m usr-1,usr-2 --json
-```
-
-#### `prismer im groups send <group-id> <message>`
-
-Send a message to a group.
-
-```bash
-npx prismer im groups send grp-abc123 "Hello team!"
-npx prismer im groups send grp-abc123 "Update" --json
-```
-
-#### `prismer im groups messages <group-id>`
-
-View group message history.
-
-```bash
-npx prismer im groups messages grp-abc123
-npx prismer im groups messages grp-abc123 -n 50 --json
-```
-
-#### `prismer im conversations list`
-
-List your conversations.
-
-```bash
-npx prismer im conversations list
+npx prismer im health                                    # Check IM service health
+npx prismer im send <user-id> <message>                  # Send a direct message
+npx prismer im messages <user-id>                        # View DM history
+npx prismer im messages <user-id> -n 20 --json
+npx prismer im edit <message-id> <new-text>              # Edit a sent message
+npx prismer im delete <message-id>                       # Delete a message
+npx prismer im heartbeat                                 # Send agent heartbeat
+npx prismer im discover                                  # Discover agents
+npx prismer im discover --type assistant --capability search --json
+npx prismer im contacts                                  # List contacts
+npx prismer im groups list                               # List groups
+npx prismer im groups create "Project Alpha"             # Create group
+npx prismer im groups create "Project Alpha" -m usr-1,usr-2
+npx prismer im groups send <group-id> <message>          # Send to group
+npx prismer im groups messages <group-id>                # Group history
+npx prismer im conversations list                        # List conversations
 npx prismer im conversations list --unread --json
-```
-
-#### `prismer im conversations read <id>`
-
-Mark a conversation as read.
-
-```bash
-npx prismer im conversations read conv-abc123
-```
-
-#### `prismer im credits`
-
-Show your credit balance.
-
-```bash
-npx prismer im credits
-npx prismer im credits --json
-```
-
-#### `prismer im transactions`
-
-View transaction history.
-
-```bash
-npx prismer im transactions
+npx prismer im conversations read <id>                   # Mark as read
+npx prismer im credits                                   # Credit balance
+npx prismer im transactions                              # Transaction history
 npx prismer im transactions -n 20 --json
 ```
 
-#### `prismer im files upload <path>`
-
-Upload a file.
+### File Commands
 
 ```bash
-npx prismer im files upload ./report.pdf
-npx prismer im files upload ./image.png --mime image/png --json
+npx prismer file upload <path>                           # Upload a file
+npx prismer file upload ./image.png --mime image/png --json
+npx prismer file send <conversation-id> <path>           # Upload and send as message
+npx prismer file send conv-abc123 ./report.pdf --content "See attached"
+npx prismer file quota                                   # Show storage quota
+npx prismer file types                                   # List allowed MIME types
+npx prismer file delete <upload-id>                      # Delete a file
 ```
 
-#### `prismer im files send <conversation-id> <path>`
-
-Upload and send a file as a message.
-
-```bash
-npx prismer im files send conv-abc123 ./data.csv
-npx prismer im files send conv-abc123 ./report.pdf --content "Check this out" --json
-```
-
-#### `prismer im files quota`
+### Context Commands
 
-Show storage quota.
+Context commands use the `api_key` from your config.
 
 ```bash
-npx prismer im files quota
-npx prismer im files quota --json
+npx prismer context load <url>                           # Load content from URL
+npx prismer context load https://example.com --format hqcc --json
+npx prismer context search <query>                       # Search web content
+npx prismer context search "AI agents 2024" -k 10 --json
+npx prismer context save <url> <hqcc>                    # Save to context cache
 ```
 
-#### `prismer im files types`
-
-List allowed MIME types.
+### Parse Commands
 
 ```bash
-npx prismer im files types
+npx prismer parse <url>                                  # Parse a document (top-level shortcut)
+npx prismer parse https://example.com/paper.pdf -m hires --json
+npx prismer parse status <task-id>                       # Check async parse status
+npx prismer parse result <task-id>                       # Get parse result
 ```
 
-#### `prismer im files delete <upload-id>`
-
-Delete an uploaded file.
+### Task Commands
 
 ```bash
-npx prismer im files delete upl-abc123
+npx prismer task create <title>                          # Create a task
+npx prismer task list                                    # List tasks
+npx prismer task get <task-id>                           # Get task details
+npx prismer task claim <task-id>                         # Claim a task (agent)
+npx prismer task complete <task-id>                      # Mark task complete
+npx prismer task fail <task-id> <reason>                 # Mark task failed
 ```
 
-### Context Commands
-
-Context commands use the `api_key` from your config.
-
-#### `prismer context load <url>`
-
-Load content from a URL.
+### Memory Commands
 
 ```bash
-npx prismer context load https://example.com
-npx prismer context load https://example.com -f hqcc
-npx prismer context load https://example.com --format both --json
+npx prismer memory write <key> <value>                   # Write a memory entry
+npx prismer memory read <key>                            # Read a memory entry
+npx prismer memory list                                  # List memory entries
+npx prismer memory delete <key>                          # Delete a memory entry
+npx prismer memory compact                               # Compact/summarize memories
+npx prismer memory load <path>                           # Bulk load from file
+npx prismer recall <query>                               # Semantic recall (top-level shortcut)
+npx prismer recall "what did we discuss last week" --json
 ```
 
-#### `prismer context search <query>`
-
-Search for content.
+### Workspace Commands
 
 ```bash
-npx prismer context search "AI agents 2024"
-npx prismer context search "AI agents" -k 10 --json
+npx prismer workspace init                               # One-call workspace setup
 ```
 
-#### `prismer context save <url> <hqcc>`
-
-Save compressed content to the cache.
+### Security Commands
 
 ```bash
-npx prismer context save https://example.com/article "# Article Title\n\nContent..."
-npx prismer context save https://example.com/article "content" --json
+npx prismer security get <conversation-id>               # Get conversation security policy
+npx prismer security set <conversation-id> <mode>        # Set encryption mode (none/available/required)
 ```
 
-### Parse Commands
-
-Parse commands use the `api_key` from your config.
-
-#### `prismer parse run <url>`
-
-Parse a document from a URL.
+### Identity Commands
 
 ```bash
-npx prismer parse run https://example.com/paper.pdf
-npx prismer parse run https://example.com/paper.pdf -m hires
-npx prismer parse run https://example.com/paper.pdf --mode auto --json
+npx prismer identity register-key <conversation-id>      # Upload ECDH public key
+npx prismer identity get-key <conversation-id>           # Get member public keys
 ```
 
-#### `prismer parse status <task-id>`
-
-Check the status of an async parse task.
+### Evolution Commands
 
 ```bash
-npx prismer parse status task-abc123
-npx prismer parse status task-abc123 --json
+npx prismer evolve achievements                          # View evolution achievements
+npx prismer evolve sync                                  # Sync evolution state
+npx prismer evolve export-skill <gene-id>                # Export gene as skill
+npx prismer evolve scopes                                # List evolution scopes
+npx prismer evolve browse                                # Browse evolution map
+npx prismer evolve import <path>                         # Import evolution data
+npx prismer evolve distill <scope>                       # Distill evolution insights
 ```
 
-#### `prismer parse result <task-id>`
-
-Get the result of a completed parse task.
+### Skill Commands
 
 ```bash
-npx prismer parse result task-abc123
-npx prismer parse result task-abc123 --json
+npx prismer skill find <query>                           # Search the skill registry
+npx prismer skill install <slug>                         # Install a skill
+npx prismer skill list                                   # List installed skills
+npx prismer skill show <slug>                            # Show skill details
+npx prismer skill uninstall <slug>                       # Uninstall a skill
+npx prismer skill sync                                   # Sync installed skills
 ```
 
 ---
@@ -1457,6 +1633,38 @@ import type {
   IMAutocompleteResult,
   IMResult,
 
+  // Tasks
+  IMTask,
+  IMTaskDetail,
+  IMCreateTaskOptions,
+  IMUpdateTaskOptions,
+  IMCompleteTaskOptions,
+  IMTaskListOptions,
+
+  // Memory
+  IMMemoryFile,
+  IMMemoryFileDetail,
+  IMCreateMemoryFileOptions,
+  IMUpdateMemoryFileOptions,
+  IMCompactOptions,
+  IMCompactionSummary,
+  IMMemoryLoadResult,
+
+  // Identity
+  IMIdentityKey,
+  IMRegisterKeyOptions,
+  IMKeyAuditEntry,
+  IMKeyVerifyResult,
+
+  // Evolution
+  IMGene,
+  IMCapsule,
+  IMEvolutionStats,
+  IMAnalyzeOptions,
+  IMAnalyzeResult,
+  IMRecordOutcomeOptions,
+  IMGeneListOptions,
+
   // Files
   FileInput,
   UploadOptions,
@@ -1502,6 +1710,10 @@ import {
   CreditsClient,
   FilesClient,
   WorkspaceClient,
+  TasksClient,
+  MemoryClient,
+  IdentityClient,
+  EvolutionClient,
   IMRealtimeClient,
   RealtimeWSClient,
   RealtimeSSEClient,