@cmetech/otto 1.1.1 → 1.2.5

package/packages/coworker-types/src/artifacts.ts

@@ -0,0 +1,35 @@
+// Artifact-store types. See spec §2.3.
+
+export type ArtifactKind = 'report' | 'workbook' | 'dataset';
+
+export interface ArtifactHandle {
+  slug: string;
+  kind: ArtifactKind;
+  base_path: string;
+  created_at: string;
+}
+
+export interface FileWrite {
+  path: string;          // relative to artifact base_path
+  content: string | Uint8Array;
+}
+
+export interface TurnEntry {
+  turn_id: string;
+  timestamp: string;
+  prompt_excerpt: string;       // truncated to 240 chars
+  files_touched: string[];      // sorted, deduped, relative paths
+}
+
+export interface ProvenanceEntry {
+  session_id: string;
+  turns: TurnEntry[];
+}
+
+export interface ArtifactStore {
+  create(kind: ArtifactKind, name: string): Promise<ArtifactHandle>;
+  update(handle: ArtifactHandle, files: FileWrite[]): Promise<void>;
+  recordTurn(handle: ArtifactHandle, turn: { turn_id: string; prompt: string }): Promise<void>;
+  get(slug: string): Promise<ArtifactHandle | null>;
+  list(): Promise<ArtifactHandle[]>;
+}

package/packages/coworker-types/src/contracts.test.ts

@@ -0,0 +1,43 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { MemoryRecorder, RecordEpisodeArgs, RecordCellArgs, AccEventArgs } from './contracts.js';
+
+describe('inter-package contracts', () => {
+  it('RecordEpisodeArgs uses DrawerKind enum, not free string', () => {
+    const args: RecordEpisodeArgs = {
+      sessionId: 'sess_001',
+      room: 'p1-1234',
+      kind: 'ticket',     // must compile only because 'ticket' is a DrawerKind
+      content: 'verbatim',
+      turnId: 'turn_001',
+    };
+    assert.equal(args.kind, 'ticket');
+  });
+
+  it('RecordCellArgs has scratchpadName + cellId + duration', () => {
+    const args: RecordCellArgs = {
+      scratchpadName: 'p1-1234',
+      cellId: 'cell_001',
+      code: 'const x = 1;',
+      stdout: '',
+      error: null,
+      durationMs: 42,
+    };
+    assert.equal(args.durationMs, 42);
+  });
+
+  it('AccEventArgs has kind + detail + severity', () => {
+    const args: AccEventArgs = {
+      sessionId: 'sess_001',
+      kind: 'repeated_error_signature',
+      detail: 'UnicodeDecodeError x4',
+      severity: 'medium',
+    };
+    assert.equal(args.severity, 'medium');
+  });
+
+  it('MemoryRecorder has the three required methods', () => {
+    const _methods: Array<keyof MemoryRecorder> = ['recordEpisode', 'recordCell', 'observeAccEvent'];
+    assert.equal(_methods.length, 3);
+  });
+});

package/packages/coworker-types/src/contracts.ts

@@ -0,0 +1,36 @@
+// Inter-package contracts. See spec §2.5.
+import type { DrawerKind } from './memory.js';
+
+export interface RecordEpisodeArgs {
+  sessionId: string;
+  room: string;
+  kind: DrawerKind;
+  content: string;
+  turnId: string;
+  metadata?: Record<string, unknown>;
+  // wing is intentionally absent — otto-memory derives it from active scoping mode.
+}
+
+export interface RecordCellArgs {
+  scratchpadName: string;
+  cellId: string;
+  code: string;
+  stdout: string;
+  error: { type: string; message: string } | null;
+  durationMs: number;
+}
+
+export type AccSeverity = 'low' | 'medium' | 'high';
+
+export interface AccEventArgs {
+  sessionId: string;
+  kind: string;          // ACC detector vocabulary — closed set defined in coworker-memory Phase 5
+  detail: string;
+  severity: AccSeverity;
+}
+
+export interface MemoryRecorder {
+  recordEpisode(args: RecordEpisodeArgs): Promise<void>;
+  recordCell(args: RecordCellArgs): Promise<void>;
+  observeAccEvent(args: AccEventArgs): void;
+}

package/packages/coworker-types/src/index.ts

@@ -0,0 +1,5 @@
+export * from './memory.js';
+export * from './artifacts.js';
+export * from './vault.js';
+export * from './scratchpad.js';
+export * from './contracts.js';

package/packages/coworker-types/src/memory.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { Drawer, DrawerKind, RecallQuery, MemoryBackend, Wing, Room } from './memory.js';
+
+describe('memory types', () => {
+  it('Wing is a string alias', () => {
+    const w: Wing = 'acme-noc';
+    assert.equal(typeof w, 'string');
+  });
+
+  it('Room is a string alias', () => {
+    const r: Room = 'p1-1234';
+    assert.equal(typeof r, 'string');
+  });
+
+  it('DrawerKind covers the closed v1 vocabulary', () => {
+    const kinds: DrawerKind[] = ['turn', 'paste', 'file_load', 'ticket', 'email', 'rca', 'note'];
+    assert.equal(kinds.length, 7);
+  });
+
+  it('Drawer requires id, wing, room, kind, content, created_at', () => {
+    const d: Drawer = {
+      id: 'drw_001',
+      wing: 'acme-noc',
+      room: 'p1-1234',
+      kind: 'ticket',
+      content: 'verbatim ticket body',
+      metadata: {},
+      created_at: '2026-05-31T10:00:00Z',
+    };
+    assert.equal(d.kind, 'ticket');
+  });
+
+  it('RecallQuery has required query and optional filters', () => {
+    const q: RecallQuery = { query: 'kernel 4.18' };
+    assert.equal(q.query, 'kernel 4.18');
+    const qf: RecallQuery = { query: 'mttr', kind: 'rca', wing: 'acme-noc', room: 'p1-1234', max_results: 5 };
+    assert.equal(qf.kind, 'rca');
+  });
+
+  it('MemoryBackend interface has the seven required methods', () => {
+    // Compile-time check via a structural variable
+    const _check: keyof MemoryBackend = 'recall';
+    const _methods: Array<keyof MemoryBackend> = [
+      'recall', 'retain', 'listRooms', 'listWings',
+      'entityQuery', 'entityAssert', 'status', 'clear',
+    ];
+    assert.equal(_methods.length, 8);
+  });
+});

package/packages/coworker-types/src/memory.ts

@@ -0,0 +1,79 @@
+// Memory-layer types for the otto-memory contract.
+// See spec §2.1 "Layer B structure — Wings, Rooms, Drawers as contract concepts".
+
+export type Wing = string;
+export type Room = string;
+
+export type DrawerKind =
+  | 'turn'
+  | 'paste'
+  | 'file_load'
+  | 'ticket'
+  | 'email'
+  | 'rca'
+  | 'note';
+
+export interface Drawer {
+  id: string;
+  wing: Wing;
+  room: Room;
+  kind: DrawerKind;
+  content: string;
+  metadata: Record<string, unknown>;
+  created_at: string;
+  parent_id?: string;
+}
+
+export interface RecallQuery {
+  query: string;
+  wing?: Wing;
+  room?: Room;
+  kind?: DrawerKind | DrawerKind[];
+  days_back?: number;
+  max_results?: number;
+}
+
+export interface Entity {
+  id: string;
+  type: string;
+  canonical: string;
+  aliases: string[];
+  metadata: Record<string, unknown>;
+  first_seen: string;
+  last_seen: string;
+}
+
+export interface EntityEdge {
+  subject: string;
+  predicate: string;
+  object: string;
+  valid_from: string;
+  valid_to?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface EntityQuery {
+  entity_type?: string;
+  name?: string;
+  predicate?: string;
+  as_of?: string;
+}
+
+export interface BackendStatus {
+  backend_id: string;
+  drawer_count: number;
+  entity_count: number;
+  size_bytes: number;
+  last_write_at?: string;
+}
+
+export interface MemoryBackend {
+  recall(query: RecallQuery): Promise<Drawer[]>;
+  retain(drawer: Omit<Drawer, 'id' | 'created_at'>): Promise<Drawer>;
+  listRooms(wing?: Wing): Promise<Room[]>;
+  listWings(): Promise<Wing[]>;
+  entityQuery(query: EntityQuery): Promise<Entity[]>;
+  entityAssert(edge: EntityEdge): Promise<void>;
+  status(): Promise<BackendStatus>;
+  clear(): Promise<void>;
+}

package/packages/coworker-types/src/scratchpad.test.ts

@@ -0,0 +1,46 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type {
+  DataSourceRef, DataSource, CollectorCapabilities,
+  Collector, CollectorRegistry, Unsubscribe,
+} from './scratchpad.js';
+
+describe('scratchpad/collector types', () => {
+  it('DataSourceRef has collector id + uri + kind + metadata', () => {
+    const ref: DataSourceRef = {
+      collector: 'file',
+      uri: 'file:///workspace/inputs/cmdb.csv',
+      kind: 'csv',
+      bytes: 1024,
+      modified: '2026-05-31T10:00:00Z',
+      metadata: {},
+    };
+    assert.equal(ref.collector, 'file');
+  });
+
+  it('CollectorCapabilities advertises supports_uris and supports_kinds', () => {
+    const caps: CollectorCapabilities = {
+      supports_uris: ['file://*'],
+      supports_kinds: ['csv', 'xlsx'],
+      supports_streaming: true,
+      supports_watching: true,
+    };
+    assert.equal(caps.supports_streaming, true);
+  });
+
+  it('Collector interface has describe + list + open + optional watch', () => {
+    const _check: keyof Collector = 'describe';
+    const _required: Array<keyof Collector> = ['id', 'kind', 'describe', 'list', 'open'];
+    assert.equal(_required.length, 5);
+  });
+
+  it('CollectorRegistry has register/list/get/resolve', () => {
+    const _methods: Array<keyof CollectorRegistry> = ['register', 'list', 'get', 'resolve'];
+    assert.equal(_methods.length, 4);
+  });
+
+  it('Unsubscribe is a void-returning function', () => {
+    const u: Unsubscribe = () => undefined;
+    assert.equal(typeof u, 'function');
+  });
+});

package/packages/coworker-types/src/scratchpad.ts

@@ -0,0 +1,51 @@
+// Scratchpad/collector types. See spec §2.4 collector facade.
+
+export type DataKind =
+  | 'csv' | 'xlsx' | 'json' | 'parquet' | 'txt' | 'md'
+  | 'rest' | 'mcp-resource' | 'acp-stream';
+
+export interface DataSourceRef {
+  collector: string;
+  uri: string;
+  kind: DataKind;
+  bytes?: number;
+  modified?: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface DataSource {
+  ref: DataSourceRef;
+  load(): Promise<Buffer | string | object>;
+  stream?(): AsyncIterable<Buffer>;
+}
+
+export interface CollectorCapabilities {
+  supports_uris: string[];          // wildcard patterns: 'file://*', 'servicenow://*'
+  supports_kinds: DataKind[];
+  supports_streaming: boolean;
+  supports_watching: boolean;
+}
+
+export interface ListOpts {
+  workspace?: string;
+  prefix?: string;
+  limit?: number;
+}
+
+export type Unsubscribe = () => void;
+
+export interface Collector {
+  readonly id: string;
+  readonly kind: 'file' | 'api' | 'protocol';
+  describe(): CollectorCapabilities;
+  list(opts?: ListOpts): AsyncIterable<DataSourceRef>;
+  open(ref: DataSourceRef): Promise<DataSource>;
+  watch?(ref: DataSourceRef, onChange: (ref: DataSourceRef) => void): Unsubscribe;
+}
+
+export interface CollectorRegistry {
+  register(collector: Collector): void;
+  list(): Collector[];
+  get(id: string): Collector | null;
+  resolve(uri: string): Promise<{ collector: Collector; ref: DataSourceRef } | null>;
+}

package/packages/coworker-types/src/smoke.test.ts

@@ -0,0 +1,34 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('phase 0 smoke', () => {
+  it('coworker-types barrel exports all five modules', async () => {
+    const mod = await import('./index.js');
+    // Memory
+    assert.ok('Drawer' in mod === false, 'types only — runtime should be empty');
+    // But at runtime imports should resolve without throwing.
+    assert.ok(mod, 'module loaded');
+  });
+
+  it('coworker-utils barrel exports all helpers at runtime', async () => {
+    const mod = await import('@otto/coworker-utils');
+    assert.equal(typeof (mod as any).writeNdjson, 'function');
+    assert.equal(typeof (mod as any).readNdjson, 'function');
+    assert.equal(typeof (mod as any).acquireLease, 'function');
+    assert.equal(typeof (mod as any).releaseLease, 'function');
+    assert.equal(typeof (mod as any).MigrationRunner, 'function');
+    assert.equal(typeof (mod as any).SecretScanner, 'function');
+    assert.equal(typeof (mod as any).createLogger, 'function');
+  });
+
+  it('all four pillar packages import without error', async () => {
+    const memory    = await import('@otto/coworker-memory');
+    const vault     = await import('@otto/coworker-vault');
+    const artifacts = await import('@otto/coworker-artifacts');
+    const scratch   = await import('@otto/coworker-scratchpad');
+    assert.ok(memory);
+    assert.ok(vault);
+    assert.ok(artifacts);
+    assert.ok(scratch);
+  });
+});

package/packages/coworker-types/src/vault.test.ts

@@ -0,0 +1,49 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type {
+  VaultEntry, EngineDef, EngineField, BoundClient, CredentialInjector,
+} from './vault.js';
+
+describe('vault types', () => {
+  it('EngineField carries name + secret + name_from flag', () => {
+    const f: EngineField = { name: 'password', secret: true };
+    assert.equal(f.secret, true);
+  });
+
+  it('EngineDef carries engine slug + fields + test_snippet', () => {
+    const e: EngineDef = {
+      slug: 'servicenow',
+      display_name: 'ServiceNow',
+      pip: null,
+      fields: [{ name: 'instance', secret: false }],
+      auth_methods: ['basic'],
+      test_snippet: '/* ts code */',
+    };
+    assert.equal(e.slug, 'servicenow');
+  });
+
+  it('VaultEntry has engine + name + values + secure_keys', () => {
+    const v: VaultEntry = {
+      engine: 'servicenow',
+      name: 'prod',
+      values: { instance: 'acme.service-now.com' },
+      secure_keys: ['password'],
+      created_at: '2026-05-31T10:00:00Z',
+    };
+    assert.equal(v.engine, 'servicenow');
+  });
+
+  it('CredentialInjector has injectEnv + loadForBinding', () => {
+    const _methods: Array<keyof CredentialInjector> = ['injectEnv', 'loadForBinding'];
+    assert.equal(_methods.length, 2);
+  });
+
+  it('BoundClient is a generic typed wrapper', () => {
+    const b: BoundClient<{ ping: () => Promise<string> }> = {
+      engine: 'servicenow',
+      name: 'prod',
+      client: { ping: async () => 'ok' },
+    };
+    assert.equal(b.engine, 'servicenow');
+  });
+});

package/packages/coworker-types/src/vault.ts

@@ -0,0 +1,40 @@
+// Vault types. See spec §2.2.
+
+export interface EngineField {
+  name: string;
+  secret: boolean;            // true → uses VAULT_KEEP sentinel on round-trip
+  description?: string;
+  default?: string;
+  name_from?: boolean;        // if true, used to auto-name the entry
+}
+
+export interface EngineDef {
+  slug: string;
+  display_name: string;
+  pip: string | null;          // for parity with Anton's YAML; null when not applicable
+  fields: EngineField[];
+  auth_methods: string[];
+  test_snippet?: string;
+  popular?: boolean;
+  custom?: boolean;
+}
+
+export interface VaultEntry {
+  engine: string;             // engine slug
+  name: string;               // user-chosen, sanitized
+  values: Record<string, string>;
+  secure_keys: string[];      // fields that should never be logged or echoed
+  created_at: string;
+  updated_at?: string;
+}
+
+export interface BoundClient<TClient = unknown> {
+  engine: string;
+  name: string;
+  client: TClient;
+}
+
+export interface CredentialInjector {
+  injectEnv(processEnv: NodeJS.ProcessEnv, vaultEntries: string[]): NodeJS.ProcessEnv;
+  loadForBinding<TClient = unknown>(serviceName: string): Promise<BoundClient<TClient> | null>;
+}

package/packages/coworker-types/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/packages/coworker-types/tsconfig.publish.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "incremental": false }
+}

package/packages/coworker-utils/dist/audit-log.d.ts

@@ -0,0 +1,34 @@
+export interface AuditRecord {
+    _schema: 1;
+    ts: string;
+    producer: string;
+    action: string;
+    severity?: 'info' | 'warn';
+    sessionId?: string;
+    scratchpadName?: string;
+    pid?: number;
+    detail: Record<string, unknown>;
+}
+export interface AuditLogOptions {
+    path: string;
+    maxBytes?: number;
+    maxTails?: number;
+}
+export interface AuditFilter {
+    since?: string;
+    producer?: string;
+    action?: string;
+    severity?: 'info' | 'warn';
+    engineId?: string;
+}
+export declare class AuditLog {
+    private readonly path;
+    private readonly maxBytes;
+    private readonly maxTails;
+    constructor(opts: AuditLogOptions);
+    append(record: AuditRecord): void;
+    read(filter: AuditFilter): AsyncIterable<AuditRecord>;
+    private listLogFiles;
+    private matches;
+    private rotateIfNeeded;
+}

package/packages/coworker-utils/dist/audit-log.js

@@ -0,0 +1,88 @@
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_TAILS = 5;
+export class AuditLog {
+    path;
+    maxBytes;
+    maxTails;
+    constructor(opts) {
+        this.path = opts.path;
+        this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.maxTails = opts.maxTails ?? DEFAULT_MAX_TAILS;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    }
+    append(record) {
+        this.rotateIfNeeded();
+        const line = JSON.stringify(record) + '\n';
+        try {
+            appendFileSync(this.path, line, { mode: 0o600 });
+        }
+        catch (err) {
+            process.stderr.write(`audit: write failed (${err.message}); continuing\n`);
+        }
+    }
+    async *read(filter) {
+        const files = this.listLogFiles();
+        const records = [];
+        for (const f of files) {
+            if (!existsSync(f))
+                continue;
+            const text = readFileSync(f, 'utf8');
+            for (const line of text.split('\n')) {
+                if (!line)
+                    continue;
+                try {
+                    const rec = JSON.parse(line);
+                    if (!this.matches(rec, filter))
+                        continue;
+                    records.push(rec);
+                }
+                catch { /* skip malformed line */ }
+            }
+        }
+        records.sort((a, b) => (a.ts === b.ts ? 0 : a.ts < b.ts ? 1 : -1));
+        for (const r of records)
+            yield r;
+    }
+    listLogFiles() {
+        const out = [this.path];
+        for (let n = 1; n <= this.maxTails; n++) {
+            out.push(`${this.path.replace(/\.jsonl$/, '')}.${n}.jsonl`);
+        }
+        return out;
+    }
+    matches(rec, f) {
+        if (f.producer && rec.producer !== f.producer)
+            return false;
+        if (f.action && rec.action !== f.action)
+            return false;
+        if (f.severity && rec.severity !== f.severity)
+            return false;
+        if (f.since && rec.ts < f.since)
+            return false;
+        if (f.engineId && rec.detail.engine !== f.engineId)
+            return false;
+        return true;
+    }
+    rotateIfNeeded() {
+        if (!existsSync(this.path))
+            return;
+        const size = statSync(this.path).size;
+        if (size < this.maxBytes)
+            return;
+        // Find next available tail slot; if maxTails full, drop tail N (delete) before shifting.
+        const base = this.path.replace(/\.jsonl$/, '');
+        const tailN = `${base}.${this.maxTails}.jsonl`;
+        if (existsSync(tailN))
+            unlinkSync(tailN);
+        for (let n = this.maxTails - 1; n >= 1; n--) {
+            const src = `${base}.${n}.jsonl`;
+            const dst = `${base}.${n + 1}.jsonl`;
+            if (existsSync(src))
+                renameSync(src, dst);
+        }
+        renameSync(this.path, `${base}.1.jsonl`);
+        closeSync(openSync(this.path, 'w', 0o600));
+    }
+}

package/packages/coworker-utils/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './ndjson-channel.js';
+export * from './lease.js';
+export * from './migration-runner.js';
+export * from './secret-scanner.js';
+export * from './logger.js';
+export * from './audit-log.js';

package/packages/coworker-utils/dist/index.js

@@ -0,0 +1,6 @@
+export * from './ndjson-channel.js';
+export * from './lease.js';
+export * from './migration-runner.js';
+export * from './secret-scanner.js';
+export * from './logger.js';
+export * from './audit-log.js';

package/packages/coworker-utils/dist/lease.d.ts

@@ -0,0 +1,7 @@
+export interface LeaseOptions {
+    ttlMs: number;
+    holder?: string;
+}
+export declare function acquireLease(path: string, opts: LeaseOptions): Promise<boolean>;
+export declare function releaseLease(path: string): Promise<void>;
+export declare function isLeaseHeld(path: string): Promise<boolean>;