@soleri/core 2.0.2 → 2.4.0

package/src/runtime/vault-extra-ops.ts

@@ -0,0 +1,225 @@
+/**
+ * Extra vault operations — 12 ops that extend the 4 base vault ops in core-ops.ts.
+ *
+ * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3), analytics (1).
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { AgentRuntime } from './types.js';
+
+const entrySchema = z.object({
+  id: z.string(),
+  type: z.enum(['pattern', 'anti-pattern', 'rule']),
+  domain: z.string(),
+  title: z.string(),
+  severity: z.enum(['critical', 'warning', 'suggestion']),
+  description: z.string(),
+  context: z.string().optional(),
+  example: z.string().optional(),
+  counterExample: z.string().optional(),
+  why: z.string().optional(),
+  tags: z.array(z.string()),
+  appliesTo: z.array(z.string()).optional(),
+});
+
+export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault } = runtime;
+
+  return [
+    // ─── Single-Entry CRUD ──────────────────────────────────────────
+    {
+      name: 'vault_get',
+      description: 'Get a single vault entry by ID.',
+      auth: 'read',
+      schema: z.object({ id: z.string() }),
+      handler: async (params) => {
+        const entry = vault.get(params.id as string);
+        if (!entry) return { error: 'Entry not found: ' + params.id };
+        return entry;
+      },
+    },
+    {
+      name: 'vault_update',
+      description:
+        'Update an existing vault entry. Only the fields provided are changed; the rest stay the same.',
+      auth: 'write',
+      schema: z.object({
+        id: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        context: z.string().optional(),
+        example: z.string().optional(),
+        counterExample: z.string().optional(),
+        why: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        appliesTo: z.array(z.string()).optional(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule']).optional(),
+        domain: z.string().optional(),
+      }),
+      handler: async (params) => {
+        const id = params.id as string;
+        const { id: _id, ...fields } = params;
+        // Strip undefined values so we only pass what was actually provided
+        const cleaned: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(fields)) {
+          if (v !== undefined) cleaned[k] = v;
+        }
+        if (Object.keys(cleaned).length === 0) {
+          return { error: 'No fields to update' };
+        }
+        const updated = vault.update(
+          id,
+          cleaned as Partial<
+            Pick<
+              IntelligenceEntry,
+              | 'title'
+              | 'description'
+              | 'context'
+              | 'example'
+              | 'counterExample'
+              | 'why'
+              | 'tags'
+              | 'appliesTo'
+              | 'severity'
+              | 'type'
+              | 'domain'
+            >
+          >,
+        );
+        if (!updated) return { error: 'Entry not found: ' + id };
+        return { updated: true, entry: updated };
+      },
+    },
+    {
+      name: 'vault_remove',
+      description: 'Remove a single vault entry by ID.',
+      auth: 'admin',
+      schema: z.object({ id: z.string() }),
+      handler: async (params) => {
+        const removed = vault.remove(params.id as string);
+        return { removed, id: params.id };
+      },
+    },
+
+    // ─── Bulk Operations ────────────────────────────────────────────
+    {
+      name: 'vault_bulk_add',
+      description: 'Add multiple vault entries at once. Uses upsert — existing IDs are updated.',
+      auth: 'write',
+      schema: z.object({
+        entries: z.array(entrySchema),
+      }),
+      handler: async (params) => {
+        const entries = params.entries as IntelligenceEntry[];
+        const count = vault.seed(entries);
+        return { added: count, total: vault.stats().totalEntries };
+      },
+    },
+    {
+      name: 'vault_bulk_remove',
+      description: 'Remove multiple vault entries by IDs in a single transaction.',
+      auth: 'admin',
+      schema: z.object({
+        ids: z.array(z.string()),
+      }),
+      handler: async (params) => {
+        const ids = params.ids as string[];
+        const removed = vault.bulkRemove(ids);
+        return { removed, requested: ids.length, total: vault.stats().totalEntries };
+      },
+    },
+
+    // ─── Discovery ──────────────────────────────────────────────────
+    {
+      name: 'vault_tags',
+      description: 'List all unique tags used across vault entries with their occurrence counts.',
+      auth: 'read',
+      handler: async () => {
+        const tags = vault.getTags();
+        return { tags, count: tags.length };
+      },
+    },
+    {
+      name: 'vault_domains',
+      description: 'List all domains in the vault with their entry counts.',
+      auth: 'read',
+      handler: async () => {
+        const domains = vault.getDomains();
+        return { domains, count: domains.length };
+      },
+    },
+    {
+      name: 'vault_recent',
+      description: 'Get recently added or updated vault entries, ordered by most recent first.',
+      auth: 'read',
+      schema: z.object({
+        limit: z.number().optional().describe('Max entries to return (default 20)'),
+      }),
+      handler: async (params) => {
+        const limit = (params.limit as number | undefined) ?? 20;
+        const entries = vault.getRecent(limit);
+        return { entries, count: entries.length };
+      },
+    },
+
+    // ─── Import / Export / Seed ──────────────────────────────────────
+    {
+      name: 'vault_import',
+      description:
+        'Import vault entries from a JSON bundle. Uses upsert — existing IDs are updated, new IDs are inserted.',
+      auth: 'write',
+      schema: z.object({
+        entries: z.array(entrySchema),
+      }),
+      handler: async (params) => {
+        const entries = params.entries as IntelligenceEntry[];
+        const before = vault.stats().totalEntries;
+        const count = vault.seed(entries);
+        const after = vault.stats().totalEntries;
+        return {
+          imported: count,
+          newEntries: after - before,
+          updatedEntries: count - (after - before),
+          total: after,
+        };
+      },
+    },
+    {
+      name: 'vault_seed',
+      description:
+        'Seed the vault from intelligence data. Idempotent — safe to call multiple times. Uses upsert.',
+      auth: 'write',
+      schema: z.object({
+        entries: z.array(entrySchema),
+      }),
+      handler: async (params) => {
+        const entries = params.entries as IntelligenceEntry[];
+        const count = vault.seed(entries);
+        return { seeded: count, total: vault.stats().totalEntries };
+      },
+    },
+    {
+      name: 'vault_backup',
+      description:
+        'Export the full vault as a JSON bundle suitable for backup or transfer to another agent.',
+      auth: 'read',
+      handler: async () => {
+        return vault.exportAll();
+      },
+    },
+
+    // ─── Analytics ──────────────────────────────────────────────────
+    {
+      name: 'vault_age_report',
+      description:
+        'Show vault entry age distribution — how many entries are from today, this week, this month, this quarter, or older.',
+      auth: 'read',
+      handler: async () => {
+        return vault.getAgeReport();
+      },
+    },
+  ];
+}

package/src/telemetry/telemetry.ts

@@ -0,0 +1,118 @@
+/**
+ * In-memory telemetry tracker for facade calls.
+ *
+ * No external deps — records calls, computes stats, bounds memory usage.
+ * Max 10 000 entries; auto-trims to 5 000 when limit is hit.
+ */
+
+export interface FacadeCall {
+  facade: string;
+  op: string;
+  timestamp: number;
+  durationMs: number;
+  success: boolean;
+  error?: string;
+}
+
+export interface TelemetryStats {
+  totalCalls: number;
+  successRate: number;
+  avgDurationMs: number;
+  callsByFacade: Record<string, number>;
+  callsByOp: Record<string, number>;
+  errorsByOp: Record<string, number>;
+  slowestOps: Array<{ op: string; avgMs: number }>;
+  since: number;
+}
+
+const MAX_ENTRIES = 10_000;
+const TRIM_TO = 5_000;
+
+export class Telemetry {
+  private calls: FacadeCall[] = [];
+  private startedAt = Date.now();
+
+  /**
+   * Record a facade call. Timestamp is auto-set to Date.now().
+   */
+  record(call: Omit<FacadeCall, 'timestamp'>): void {
+    this.calls.push({ ...call, timestamp: Date.now() });
+    if (this.calls.length > MAX_ENTRIES) {
+      this.calls = this.calls.slice(-TRIM_TO);
+    }
+  }
+
+  /**
+   * Compute aggregate stats from all recorded calls.
+   */
+  getStats(): TelemetryStats {
+    const total = this.calls.length;
+    if (total === 0) {
+      return {
+        totalCalls: 0,
+        successRate: 1,
+        avgDurationMs: 0,
+        callsByFacade: {},
+        callsByOp: {},
+        errorsByOp: {},
+        slowestOps: [],
+        since: this.startedAt,
+      };
+    }
+
+    const successes = this.calls.filter((c) => c.success).length;
+    const totalDuration = this.calls.reduce((sum, c) => sum + c.durationMs, 0);
+
+    const callsByFacade: Record<string, number> = {};
+    const callsByOp: Record<string, number> = {};
+    const errorsByOp: Record<string, number> = {};
+    const durationsByOp: Record<string, number[]> = {};
+
+    for (const call of this.calls) {
+      callsByFacade[call.facade] = (callsByFacade[call.facade] ?? 0) + 1;
+      callsByOp[call.op] = (callsByOp[call.op] ?? 0) + 1;
+
+      if (!call.success) {
+        errorsByOp[call.op] = (errorsByOp[call.op] ?? 0) + 1;
+      }
+
+      if (!durationsByOp[call.op]) durationsByOp[call.op] = [];
+      durationsByOp[call.op].push(call.durationMs);
+    }
+
+    // Compute slowest ops by average duration, top 10
+    const opAvgDurations = Object.entries(durationsByOp)
+      .map(([op, durations]) => ({
+        op,
+        avgMs: Math.round(durations.reduce((a, b) => a + b, 0) / durations.length),
+      }))
+      .sort((a, b) => b.avgMs - a.avgMs)
+      .slice(0, 10);
+
+    return {
+      totalCalls: total,
+      successRate: Math.round((successes / total) * 1000) / 1000,
+      avgDurationMs: Math.round(totalDuration / total),
+      callsByFacade,
+      callsByOp,
+      errorsByOp,
+      slowestOps: opAvgDurations,
+      since: this.startedAt,
+    };
+  }
+
+  /**
+   * Get the N most recent calls, newest first.
+   */
+  getRecent(limit = 50): FacadeCall[] {
+    return this.calls.slice(-limit).reverse();
+  }
+
+  /**
+   * Clear all recorded data and reset the start timestamp.
+   */
+  reset(): void {
+    this.calls = [];
+    this.startedAt = Date.now();
+  }
+}