@cmetech/otto 1.1.1 → 1.2.4

package/packages/coworker-artifacts/src/artifacts-integration.test.ts

@@ -0,0 +1,109 @@
+// packages/coworker-artifacts/src/artifacts-integration.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import coworkerVaultExtension from '../../../src/resources/extensions/coworker-vault/index.js';
+import coworkerMemoryExtension, { getMemoryRecorder, createMemoryBundle } from '../../../src/resources/extensions/coworker-memory/index.js';
+import coworkerArtifactsExtension, { getArtifactStore } from '../../../src/resources/extensions/coworker-artifacts/index.js';
+import coworkerScratchpadExtension from '../../../src/resources/extensions/coworker-scratchpad/index.js';
+import { makeFakeApi, fireSessionStart, fireSessionShutdown } from '../../../src/resources/extensions/coworker-vault/test-helpers.js';
+
+describe('Phase 4 — cross-extension integration', () => {
+  it('artifact created by store surfaces as kind:artifact drawer in memory and persists on disk', async () => {
+    const global = mkdtempSync(join(tmpdir(), 'p4-g-'));
+    const ws = mkdtempSync(join(tmpdir(), 'p4-w-'));
+    const sp = mkdtempSync(join(tmpdir(), 'p4-sp-'));
+    process.env.OTTO_COWORKER_GLOBAL_DIR = global;
+    process.env.OTTO_SCRATCHPAD_ROOT = sp;
+    try {
+      const vaultApi = makeFakeApi();
+      const memApi = makeFakeApi();
+      const artApi = makeFakeApi();
+      const spApi = makeFakeApi();
+      coworkerVaultExtension(vaultApi.api);
+      coworkerMemoryExtension(memApi.api);
+      coworkerArtifactsExtension(artApi.api);
+      coworkerScratchpadExtension(spApi.api);
+
+      await fireSessionStart(vaultApi, { cwd: ws });
+      await fireSessionStart(memApi, { cwd: ws });
+      await fireSessionStart(artApi, { cwd: ws });
+      await fireSessionStart(spApi, { cwd: ws });
+
+      const store = getArtifactStore();
+      const recorder = getMemoryRecorder();
+      assert.ok(store);
+      assert.ok(recorder);
+
+      // Simulate kernel→manager flow: store.create + recorder.recordArtifact
+      const handle = await store.create('report', 'RCA: load balancer 503');
+      await store.update(handle, [{ path: 'report.md', content: '# RCA\n\nbody\n' }]);
+      await recorder.recordArtifact({
+        scratchpadName: 'p1-incident',
+        slug: handle.slug,
+        kind: handle.kind,
+        uri: handle.uri,
+        turnId: 'turn-abc',
+      });
+
+      // Disk verification
+      assert.ok(existsSync(handle.dir));
+      assert.match(readFileSync(handle.primaryPath, 'utf8'), /# RCA/);
+      assert.match(readFileSync(handle.metadataPath, 'utf8'), /"slug": "rca-load-balancer-503"/);
+
+      // Memory recall via peek bundle
+      const peek = await createMemoryBundle({
+        globalDir: global, workspaceDir: ws,
+        scopeMode: 'per-project-tagged',
+        currentScratchpadName: () => null,
+      });
+      try {
+        const r = await peek.backend.recall({ query: 'rca-load-balancer-503', kind: 'artifact' });
+        assert.equal(r.length, 1);
+        const parsed = JSON.parse(r[0]!.drawer.content);
+        assert.equal(parsed.slug, 'rca-load-balancer-503');
+        assert.equal(parsed.uri, 'artifact://rca-load-balancer-503');
+        assert.equal(r[0]!.drawer.room, 'p1-incident');
+      } finally { await peek.dispose(); }
+
+      await fireSessionShutdown(spApi);
+      await fireSessionShutdown(artApi);
+      await fireSessionShutdown(memApi);
+      await fireSessionShutdown(vaultApi);
+    } finally {
+      delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+      delete process.env.OTTO_SCRATCHPAD_ROOT;
+    }
+  });
+
+  it('artifact init failure does not break memory or vault', async () => {
+    // Skip artifact activation; vault + memory + scratchpad activate normally
+    const global = mkdtempSync(join(tmpdir(), 'p4-mix-'));
+    const ws = mkdtempSync(join(tmpdir(), 'p4-mix-ws-'));
+    const sp = mkdtempSync(join(tmpdir(), 'p4-mix-sp-'));
+    process.env.OTTO_COWORKER_GLOBAL_DIR = global;
+    process.env.OTTO_SCRATCHPAD_ROOT = sp;
+    try {
+      const vaultApi = makeFakeApi();
+      const memApi = makeFakeApi();
+      const spApi = makeFakeApi();
+      coworkerVaultExtension(vaultApi.api);
+      coworkerMemoryExtension(memApi.api);
+      coworkerScratchpadExtension(spApi.api);
+      await fireSessionStart(vaultApi, { cwd: ws });
+      await fireSessionStart(memApi, { cwd: ws });
+      await fireSessionStart(spApi, { cwd: ws });
+      assert.equal(getArtifactStore(), null);
+      assert.equal(getMemoryRecorder() !== null, true);
+      await fireSessionShutdown(spApi);
+      await fireSessionShutdown(memApi);
+      await fireSessionShutdown(vaultApi);
+    } finally {
+      delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+      delete process.env.OTTO_SCRATCHPAD_ROOT;
+    }
+  });
+});

package/packages/coworker-artifacts/src/dir-snapshot.test.ts

@@ -0,0 +1,71 @@
+// packages/coworker-artifacts/src/dir-snapshot.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { takeSnapshot, diffSnapshots } from './dir-snapshot.js';
+
+function tmp(): string { return mkdtempSync(join(tmpdir(), 'ds-')); }
+
+describe('takeSnapshot', () => {
+  it('returns empty map for empty dir', () => {
+    const snap = takeSnapshot(tmp());
+    assert.equal(snap.size, 0);
+  });
+  it('captures relative path + size for each file', () => {
+    const dir = tmp();
+    writeFileSync(join(dir, 'a.md'), 'hello');
+    writeFileSync(join(dir, 'b.md'), 'world!');
+    const snap = takeSnapshot(dir);
+    assert.equal(snap.size, 2);
+    assert.equal(snap.get('a.md')!.sizeBytes, 5);
+    assert.equal(snap.get('b.md')!.sizeBytes, 6);
+    assert.equal(typeof snap.get('a.md')!.mtimeNs, 'bigint');
+  });
+  it('recurses into subdirs with forward-slash paths', () => {
+    const dir = tmp();
+    mkdirSync(join(dir, 'sub'));
+    writeFileSync(join(dir, 'sub', 'c.md'), 'nested');
+    const snap = takeSnapshot(dir);
+    assert.ok(snap.has('sub/c.md'));
+  });
+  it('returns empty map when dir does not exist', () => {
+    const snap = takeSnapshot(join(tmp(), 'nope'));
+    assert.equal(snap.size, 0);
+  });
+});
+
+describe('diffSnapshots', () => {
+  it('detects added files', () => {
+    const before = new Map();
+    const after = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.added, ['a.md']);
+    assert.deepEqual(d.modified, []);
+    assert.deepEqual(d.removed, []);
+  });
+  it('detects removed files', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map();
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.removed, ['a.md']);
+  });
+  it('detects modified when sizeBytes differs', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map([['a.md', { mtimeNs: 2n, sizeBytes: 7 }]]);
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.modified, ['a.md']);
+  });
+  it('detects modified when mtimeNs differs (same size)', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map([['a.md', { mtimeNs: 999n, sizeBytes: 5 }]]);
+    assert.deepEqual(diffSnapshots(before, after).modified, ['a.md']);
+  });
+  it('no diff when identical', () => {
+    const a = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const b = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const d = diffSnapshots(a, b);
+    assert.equal(d.added.length + d.modified.length + d.removed.length, 0);
+  });
+});

package/packages/coworker-artifacts/src/dir-snapshot.ts

@@ -0,0 +1,52 @@
+// packages/coworker-artifacts/src/dir-snapshot.ts
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import type { DirSnapshot } from './types.js';
+
+export function takeSnapshot(dir: string): DirSnapshot {
+  const out: DirSnapshot = new Map();
+  if (!existsSync(dir)) return out;
+  walk(dir, dir, out);
+  return out;
+}
+
+function walk(root: string, current: string, out: DirSnapshot): void {
+  let entries;
+  try { entries = readdirSync(current, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    const abs = join(current, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, out);
+    } else if (entry.isFile()) {
+      const stat = statSync(abs, { bigint: true });
+      const rel = relative(root, abs).split(sep).join('/');
+      out.set(rel, {
+        mtimeNs: stat.mtimeNs,
+        sizeBytes: Number(stat.size),
+      });
+    }
+  }
+}
+
+export function diffSnapshots(
+  before: DirSnapshot,
+  after: DirSnapshot,
+): { added: string[]; modified: string[]; removed: string[] } {
+  const added: string[] = [];
+  const modified: string[] = [];
+  const removed: string[] = [];
+  for (const [path, a] of after) {
+    const b = before.get(path);
+    if (!b) added.push(path);
+    else if (b.mtimeNs !== a.mtimeNs || b.sizeBytes !== a.sizeBytes) modified.push(path);
+  }
+  for (const path of before.keys()) {
+    if (!after.has(path)) removed.push(path);
+  }
+  return {
+    added: added.sort(),
+    modified: modified.sort(),
+    removed: removed.sort(),
+  };
+}

package/packages/coworker-artifacts/src/errors.test.ts

@@ -0,0 +1,37 @@
+// packages/coworker-artifacts/src/errors.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ArtifactNotFound, ArtifactKindRejected, ArtifactUriMalformed, ArtifactSlugCollision,
+} from './errors.js';
+
+describe('artifact errors', () => {
+  it('ArtifactNotFound carries slug', () => {
+    const e = new ArtifactNotFound('rca-1');
+    assert.equal(e.name, 'ArtifactNotFound');
+    assert.equal(e.slug, 'rca-1');
+    assert.match(e.message, /rca-1/);
+  });
+  it('ArtifactKindRejected carries kind', () => {
+    const e = new ArtifactKindRejected('workbook');
+    assert.equal(e.name, 'ArtifactKindRejected');
+    assert.equal(e.kind, 'workbook');
+    assert.match(e.message, /workbook/);
+    assert.match(e.message, /report/);
+  });
+  it('ArtifactUriMalformed carries uri + reason', () => {
+    const e = new ArtifactUriMalformed('artifact://../x', 'path traversal');
+    assert.equal(e.name, 'ArtifactUriMalformed');
+    assert.equal(e.uri, 'artifact://../x');
+    assert.equal(e.reason, 'path traversal');
+    assert.match(e.message, /path traversal/);
+  });
+  it('ArtifactSlugCollision carries base + attempts', () => {
+    const e = new ArtifactSlugCollision('rca', 100);
+    assert.equal(e.name, 'ArtifactSlugCollision');
+    assert.equal(e.base, 'rca');
+    assert.equal(e.attempts, 100);
+    assert.match(e.message, /rca/);
+    assert.match(e.message, /100/);
+  });
+});

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

@@ -0,0 +1,28 @@
+// packages/coworker-artifacts/src/errors.ts
+export class ArtifactNotFound extends Error {
+  constructor(public readonly slug: string) {
+    super(`Artifact not found: ${slug}. /artifacts list to see available.`);
+    this.name = 'ArtifactNotFound';
+  }
+}
+
+export class ArtifactKindRejected extends Error {
+  constructor(public readonly kind: string) {
+    super(`Artifact kind '${kind}' is not supported. v1 ships only 'report'.`);
+    this.name = 'ArtifactKindRejected';
+  }
+}
+
+export class ArtifactUriMalformed extends Error {
+  constructor(public readonly uri: string, public readonly reason: string) {
+    super(`Bad artifact URI ${uri}: ${reason}.`);
+    this.name = 'ArtifactUriMalformed';
+  }
+}
+
+export class ArtifactSlugCollision extends Error {
+  constructor(public readonly base: string, public readonly attempts: number) {
+    super(`Slug collision: '${base}' has ${attempts} colliding suffixes (-2…-${attempts + 1}). Pick a different name.`);
+    this.name = 'ArtifactSlugCollision';
+  }
+}

package/packages/coworker-artifacts/src/index.test.ts

@@ -0,0 +1,22 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import * as artifacts from './index.js';
+
+describe('@otto/coworker-artifacts barrel', () => {
+  it('exports key surface', () => {
+    assert.equal(typeof artifacts.ArtifactStore, 'function');
+    assert.equal(typeof artifacts.deriveSlug, 'function');
+    assert.equal(typeof artifacts.nextCollisionSlug, 'function');
+    assert.equal(typeof artifacts.takeSnapshot, 'function');
+    assert.equal(typeof artifacts.diffSnapshots, 'function');
+    assert.equal(typeof artifacts.resolveArtifactUri, 'function');
+    assert.equal(typeof artifacts.renderReadme, 'function');
+    assert.equal(artifacts.ARTIFACT_URI_SCHEME, 'artifact://');
+  });
+  it('exports error classes', () => {
+    assert.equal(typeof artifacts.ArtifactNotFound, 'function');
+    assert.equal(typeof artifacts.ArtifactKindRejected, 'function');
+    assert.equal(typeof artifacts.ArtifactUriMalformed, 'function');
+    assert.equal(typeof artifacts.ArtifactSlugCollision, 'function');
+  });
+});

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

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './slug.js';
+export * from './dir-snapshot.js';
+export * from './resolve-uri.js';
+export * from './readme-renderer.js';
+export * from './artifact-store.js';

package/packages/coworker-artifacts/src/readme-renderer.test.ts

@@ -0,0 +1,72 @@
+// packages/coworker-artifacts/src/readme-renderer.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderReadme } from './readme-renderer.js';
+import type { ArtifactMetadata, Provenance } from './types.js';
+
+const META: ArtifactMetadata = {
+  _schema: 1,
+  slug: 'rca-1',
+  kind: 'report',
+  name: 'RCA: load balancer 503',
+  created_at: '2026-06-02T14:32:00Z',
+  last_updated_at: '2026-06-02T15:18:00Z',
+  turn_count: 2,
+  primary_file: 'report.md',
+  uri: 'artifact://rca-1',
+};
+
+const PROV: Provenance = [
+  {
+    _schema: 1, ts: '2026-06-02T14:32:00Z', action: 'create',
+    turn_id: 'turn-abc', agent_turn_id: 'agent-xyz',
+    user_prompt: 'draft the RCA', scratchpad_name: 'p1',
+    files_touched: ['report.md'],
+  },
+  {
+    _schema: 1, ts: '2026-06-02T15:18:00Z', action: 'update',
+    turn_id: 'turn-def', user_prompt: 'add timeline',
+    scratchpad_name: 'p1', files_touched: ['report.md'],
+  },
+];
+
+describe('renderReadme', () => {
+  it('renders header with name + uri + dates + turn count', () => {
+    const md = renderReadme(META, PROV, [{ path: 'report.md', sizeBytes: 4200 }]);
+    assert.match(md, /^# RCA: load balancer 503/m);
+    assert.match(md, /\*\*Kind:\*\* report/);
+    assert.match(md, /\*\*URI:\*\* `artifact:\/\/rca-1`/);
+    assert.match(md, /\*\*Created:\*\* 2026-06-02T14:32:00Z/);
+    assert.match(md, /\*\*Last updated:\*\* 2026-06-02T15:18:00Z/);
+    assert.match(md, /\*\*Turns:\*\* 2/);
+  });
+  it('renders files section with human-readable sizes', () => {
+    const md = renderReadme(META, PROV, [{ path: 'report.md', sizeBytes: 4200 }]);
+    assert.match(md, /## Files/);
+    assert.match(md, /`report.md` — 4\.1 KB/);
+  });
+  it('renders provenance table', () => {
+    const md = renderReadme(META, PROV, [{ path: 'report.md', sizeBytes: 4200 }]);
+    assert.match(md, /## Provenance/);
+    assert.match(md, /\| # \| ts \| action \| turn \| prompt \|/);
+    assert.match(md, /\| 1 \| 2026-06-02T14:32:00Z \| create \| turn-abc \| draft the RCA \|/);
+    assert.match(md, /\| 2 \| 2026-06-02T15:18:00Z \| update \| turn-def \| add timeline \|/);
+  });
+  it('is deterministic — same inputs produce byte-identical output', () => {
+    const a = renderReadme(META, PROV, [{ path: 'report.md', sizeBytes: 4200 }]);
+    const b = renderReadme(META, PROV, [{ path: 'report.md', sizeBytes: 4200 }]);
+    assert.equal(a, b);
+  });
+  it('handles empty provenance', () => {
+    const md = renderReadme(META, [], [{ path: 'report.md', sizeBytes: 0 }]);
+    assert.match(md, /## Provenance/);
+    // No table rows beyond header
+    const tableRows = (md.match(/^\| \d+ \|/gm) ?? []).length;
+    assert.equal(tableRows, 0);
+  });
+  it('handles empty file stats', () => {
+    const md = renderReadme(META, PROV, []);
+    assert.match(md, /## Files/);
+    assert.match(md, /\(none\)/);
+  });
+});

package/packages/coworker-artifacts/src/readme-renderer.ts

@@ -0,0 +1,56 @@
+// packages/coworker-artifacts/src/readme-renderer.ts
+import type { ArtifactMetadata, Provenance } from './types.js';
+
+const UNITS = ['B', 'KB', 'MB', 'GB'] as const;
+
+function humanSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value.toFixed(1)} ${UNITS[unit]}`;
+}
+
+function escapeMarkdownPipe(s: string): string {
+  return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+export function renderReadme(
+  metadata: ArtifactMetadata,
+  provenance: Provenance,
+  fileStats: Array<{ path: string; sizeBytes: number }>,
+): string {
+  const firstTurn = provenance[0]?.turn_id ?? '';
+  const lastTurn = provenance.length > 0 ? provenance[provenance.length - 1]!.turn_id : '';
+
+  const lines: string[] = [];
+  lines.push(`# ${metadata.name}`);
+  lines.push('');
+  lines.push(`**Kind:** ${metadata.kind}`);
+  lines.push(`**URI:** \`${metadata.uri}\``);
+  lines.push(`**Created:** ${metadata.created_at}${firstTurn ? ` (turn \`${firstTurn}\`)` : ''}`);
+  lines.push(`**Last updated:** ${metadata.last_updated_at}${lastTurn ? ` (turn \`${lastTurn}\`)` : ''}`);
+  lines.push(`**Turns:** ${metadata.turn_count}`);
+  lines.push('');
+  lines.push('## Files');
+  lines.push('');
+  if (fileStats.length === 0) {
+    lines.push('(none)');
+  } else {
+    for (const f of fileStats) {
+      lines.push(`- \`${f.path}\` — ${humanSize(f.sizeBytes)}`);
+    }
+  }
+  lines.push('');
+  lines.push('## Provenance');
+  lines.push('');
+  lines.push('| # | ts | action | turn | prompt |');
+  lines.push('|---|---|---|---|---|');
+  provenance.forEach((e, i) => {
+    lines.push(`| ${i + 1} | ${e.ts} | ${e.action} | ${e.turn_id} | ${escapeMarkdownPipe(e.user_prompt)} |`);
+  });
+  return lines.join('\n') + '\n';
+}

package/packages/coworker-artifacts/src/resolve-uri.test.ts

@@ -0,0 +1,46 @@
+// packages/coworker-artifacts/src/resolve-uri.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveArtifactUri, ARTIFACT_URI_SCHEME } from './resolve-uri.js';
+import { ArtifactUriMalformed } from './errors.js';
+
+describe('resolveArtifactUri', () => {
+  const ws = '/tmp/workspace';
+  it('parses simple slug', () => {
+    const r = resolveArtifactUri('artifact://rca-1', ws);
+    assert.equal(r.slug, 'rca-1');
+    assert.equal(r.dir, '/tmp/workspace/.otto/artifacts/rca-1');
+    assert.equal(r.primaryPath, '/tmp/workspace/.otto/artifacts/rca-1/report.md');
+    assert.equal(r.metadataPath, '/tmp/workspace/.otto/artifacts/rca-1/metadata.json');
+    assert.equal(r.provenancePath, '/tmp/workspace/.otto/artifacts/rca-1/provenance.json');
+    assert.equal(r.readmePath, '/tmp/workspace/.otto/artifacts/rca-1/README.md');
+  });
+  it('accepts single-char slug', () => {
+    const r = resolveArtifactUri('artifact://x', ws);
+    assert.equal(r.slug, 'x');
+  });
+  it('rejects bad scheme', () => {
+    assert.throws(() => resolveArtifactUri('memory://x', ws), ArtifactUriMalformed);
+  });
+  it('rejects uppercase slug', () => {
+    assert.throws(() => resolveArtifactUri('artifact://RCA', ws), ArtifactUriMalformed);
+  });
+  it('rejects path traversal', () => {
+    assert.throws(() => resolveArtifactUri('artifact://../escape', ws), ArtifactUriMalformed);
+  });
+  it('rejects leading dash', () => {
+    assert.throws(() => resolveArtifactUri('artifact://-foo', ws), ArtifactUriMalformed);
+  });
+  it('rejects trailing dash', () => {
+    assert.throws(() => resolveArtifactUri('artifact://foo-', ws), ArtifactUriMalformed);
+  });
+  it('rejects > 64 chars', () => {
+    assert.throws(() => resolveArtifactUri(`artifact://${'a'.repeat(65)}`, ws), ArtifactUriMalformed);
+  });
+  it('rejects empty slug', () => {
+    assert.throws(() => resolveArtifactUri('artifact://', ws), ArtifactUriMalformed);
+  });
+  it('exports scheme constant', () => {
+    assert.equal(ARTIFACT_URI_SCHEME, 'artifact://');
+  });
+});

package/packages/coworker-artifacts/src/resolve-uri.ts

@@ -0,0 +1,29 @@
+// packages/coworker-artifacts/src/resolve-uri.ts
+import { join } from 'node:path';
+import { ArtifactUriMalformed } from './errors.js';
+import type { ResolvedArtifactUri } from './types.js';
+
+export const ARTIFACT_URI_SCHEME = 'artifact://';
+const SLUG_REGEX = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+
+export function resolveArtifactUri(uri: string, workspaceDir: string): ResolvedArtifactUri {
+  if (!uri.startsWith(ARTIFACT_URI_SCHEME)) {
+    throw new ArtifactUriMalformed(uri, `must start with ${ARTIFACT_URI_SCHEME}`);
+  }
+  const slug = uri.slice(ARTIFACT_URI_SCHEME.length);
+  if (!slug) throw new ArtifactUriMalformed(uri, 'empty slug');
+  if (slug.includes('..')) throw new ArtifactUriMalformed(uri, 'path traversal');
+  if (slug.length > 64) throw new ArtifactUriMalformed(uri, 'slug exceeds 64 chars');
+  if (!SLUG_REGEX.test(slug)) {
+    throw new ArtifactUriMalformed(uri, 'slug must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$');
+  }
+  const dir = join(workspaceDir, '.otto', 'artifacts', slug);
+  return {
+    slug,
+    dir,
+    primaryPath: join(dir, 'report.md'),
+    metadataPath: join(dir, 'metadata.json'),
+    provenancePath: join(dir, 'provenance.json'),
+    readmePath: join(dir, 'README.md'),
+  };
+}

package/packages/coworker-artifacts/src/slug.test.ts

@@ -0,0 +1,47 @@
+// packages/coworker-artifacts/src/slug.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { deriveSlug, nextCollisionSlug, MAX_COLLISION_ATTEMPTS } from './slug.js';
+import { ArtifactSlugCollision } from './errors.js';
+
+describe('deriveSlug', () => {
+  it('lowercases and kebab-cases simple input', () => {
+    assert.equal(deriveSlug('RCA: Load Balancer 503'), 'rca-load-balancer-503');
+  });
+  it('strips non-ASCII and punctuation', () => {
+    assert.equal(deriveSlug('résumé — final draft!'), 'resume-final-draft');
+  });
+  it('collapses runs of dashes', () => {
+    assert.equal(deriveSlug('foo --- bar'), 'foo-bar');
+  });
+  it('trims leading + trailing dashes', () => {
+    assert.equal(deriveSlug('---hello---'), 'hello');
+  });
+  it('truncates to 64 chars', () => {
+    const long = 'a'.repeat(100);
+    assert.equal(deriveSlug(long).length, 64);
+  });
+  it('produces fallback for fully-stripped input', () => {
+    assert.match(deriveSlug('!!!'), /^artifact-/);
+  });
+  it('single-char input is preserved', () => {
+    assert.equal(deriveSlug('x'), 'x');
+  });
+});
+
+describe('nextCollisionSlug', () => {
+  it('returns -2 on first collision', () => {
+    assert.equal(nextCollisionSlug('rca', new Set(['rca'])), 'rca-2');
+  });
+  it('skips already-taken numeric suffixes', () => {
+    assert.equal(nextCollisionSlug('rca', new Set(['rca', 'rca-2', 'rca-3'])), 'rca-4');
+  });
+  it('throws ArtifactSlugCollision after MAX_COLLISION_ATTEMPTS', () => {
+    const taken = new Set<string>(['rca']);
+    for (let i = 2; i <= MAX_COLLISION_ATTEMPTS + 1; i++) taken.add(`rca-${i}`);
+    assert.throws(() => nextCollisionSlug('rca', taken), ArtifactSlugCollision);
+  });
+  it('returns base if base not taken', () => {
+    assert.equal(nextCollisionSlug('rca', new Set()), 'rca');
+  });
+});

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

@@ -0,0 +1,31 @@
+// packages/coworker-artifacts/src/slug.ts
+import { ArtifactSlugCollision } from './errors.js';
+
+export const MAX_SLUG_LENGTH = 64;
+export const MAX_COLLISION_ATTEMPTS = 100;
+
+export function deriveSlug(name: string): string {
+  let s = name.toLowerCase();
+  // Strip diacritics (NFKD + remove combining marks U+0300–U+036F)
+  s = s.normalize('NFKD').replace(/[̀-ͯ]/g, '');
+  // Replace non a-z 0-9 with dash
+  s = s.replace(/[^a-z0-9]+/g, '-');
+  // Collapse runs of dashes
+  s = s.replace(/-+/g, '-');
+  // Trim leading/trailing dashes
+  s = s.replace(/^-+|-+$/g, '');
+  // Truncate
+  if (s.length > MAX_SLUG_LENGTH) s = s.slice(0, MAX_SLUG_LENGTH).replace(/-+$/, '');
+  // Fallback if empty
+  if (!s) s = `artifact-${Date.now().toString(36)}`;
+  return s;
+}
+
+export function nextCollisionSlug(base: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base;
+  for (let n = 2; n <= MAX_COLLISION_ATTEMPTS + 1; n++) {
+    const candidate = `${base}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw new ArtifactSlugCollision(base, MAX_COLLISION_ATTEMPTS);
+}