@cmetech/otto 1.1.1 → 1.2.4

package/src/resources/extensions/_coworker-paths.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getCoworkerGlobalDir, getScratchpadsRoot } from './_coworker-paths.js';
+
+const ORIGINAL_GLOBAL = process.env.OTTO_COWORKER_GLOBAL_DIR;
+const ORIGINAL_SCRATCH = process.env.OTTO_SCRATCHPAD_ROOT;
+
+describe('_coworker-paths', () => {
+  before(() => {
+    delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+    delete process.env.OTTO_SCRATCHPAD_ROOT;
+  });
+  after(() => {
+    if (ORIGINAL_GLOBAL !== undefined) process.env.OTTO_COWORKER_GLOBAL_DIR = ORIGINAL_GLOBAL;
+    else delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+    if (ORIGINAL_SCRATCH !== undefined) process.env.OTTO_SCRATCHPAD_ROOT = ORIGINAL_SCRATCH;
+    else delete process.env.OTTO_SCRATCHPAD_ROOT;
+  });
+
+  it('getCoworkerGlobalDir defaults to ~/.otto', () => {
+    delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+    assert.equal(getCoworkerGlobalDir(), join(homedir(), '.otto'));
+  });
+  it('getCoworkerGlobalDir respects OTTO_COWORKER_GLOBAL_DIR env', () => {
+    process.env.OTTO_COWORKER_GLOBAL_DIR = '/tmp/otto-test';
+    assert.equal(getCoworkerGlobalDir(), '/tmp/otto-test');
+    delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+  });
+  it('getScratchpadsRoot defaults to ~/.otto/scratchpads', () => {
+    delete process.env.OTTO_SCRATCHPAD_ROOT;
+    assert.equal(getScratchpadsRoot(), join(homedir(), '.otto', 'scratchpads'));
+  });
+  it('getScratchpadsRoot respects OTTO_SCRATCHPAD_ROOT env', () => {
+    process.env.OTTO_SCRATCHPAD_ROOT = '/tmp/sp-test';
+    assert.equal(getScratchpadsRoot(), '/tmp/sp-test');
+    delete process.env.OTTO_SCRATCHPAD_ROOT;
+  });
+});

package/src/resources/extensions/_coworker-paths.ts

@@ -0,0 +1,10 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function getCoworkerGlobalDir(): string {
+  return process.env.OTTO_COWORKER_GLOBAL_DIR ?? join(homedir(), '.otto');
+}
+
+export function getScratchpadsRoot(): string {
+  return process.env.OTTO_SCRATCHPAD_ROOT ?? join(homedir(), '.otto', 'scratchpads');
+}

package/src/resources/extensions/coworker-artifacts/artifacts-command.test.ts

@@ -0,0 +1,54 @@
+// src/resources/extensions/coworker-artifacts/artifacts-command.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ArtifactStore } from '@otto/coworker-artifacts';
+import { runArtifactsCommand } from './artifacts-command.js';
+
+describe('/artifacts command', () => {
+  it('list returns markdown table', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ac-')) });
+    await store.create('report', 'a');
+    const out = await runArtifactsCommand(store, ['list']);
+    assert.match(out.message, /### Artifacts \(1\)/);
+  });
+  it('bare invocation defaults to list', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ac2-')) });
+    const out = await runArtifactsCommand(store, []);
+    assert.match(out.message, /### Artifacts \(0\)/);
+  });
+  it('show <slug> dumps content + provenance', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ac3-')) });
+    const h = await store.create('report', 'r');
+    await store.update(h, [{ path: 'report.md', content: '# yo\n' }]);
+    const out = await runArtifactsCommand(store, ['show', 'r']);
+    assert.match(out.message, /# yo/);
+  });
+  it('remove --confirm deletes', async () => {
+    const ws = mkdtempSync(join(tmpdir(), 'ac4-'));
+    const store = new ArtifactStore({ workspaceDir: ws });
+    const h = await store.create('report', 'r');
+    const out = await runArtifactsCommand(store, ['remove', 'r', '--confirm']);
+    assert.match(out.message, /removed: r/);
+    assert.equal(existsSync(h.dir), false);
+  });
+  it('remove without --confirm errors', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ac5-')) });
+    await store.create('report', 'r');
+    await assert.rejects(() => runArtifactsCommand(store, ['remove', 'r']));
+  });
+  it('unknown subcommand errors', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ac6-')) });
+    await assert.rejects(() => runArtifactsCommand(store, ['banana']));
+  });
+  it('remove --confirm <slug> (flag-first) also deletes', async () => {
+    const ws = mkdtempSync(join(tmpdir(), 'ac-flag-'));
+    const store = new ArtifactStore({ workspaceDir: ws });
+    const h = await store.create('report', 'r');
+    const out = await runArtifactsCommand(store, ['remove', '--confirm', 'r']);
+    assert.match(out.message, /removed: r/);
+    assert.equal(existsSync(h.dir), false);
+  });
+});

package/src/resources/extensions/coworker-artifacts/artifacts-command.ts

@@ -0,0 +1,43 @@
+// src/resources/extensions/coworker-artifacts/artifacts-command.ts
+//
+// /artifacts slash command dispatcher. Subcommands:
+//   list (default)        — markdown table of artifacts in this workspace
+//   show <slug>           — body + recent provenance for one artifact
+//   remove <slug> --confirm — destructive delete, gated by --confirm
+import type { ArtifactStore } from '@otto/coworker-artifacts';
+import { runListArtifacts } from './list-tool.js';
+import { runOpenArtifact } from './open-tool.js';
+
+export interface ArtifactsCommandResult {
+  message: string;
+}
+
+export async function runArtifactsCommand(
+  store: ArtifactStore,
+  argv: string[],
+): Promise<ArtifactsCommandResult> {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case 'list':
+    case undefined: {
+      const out = await runListArtifacts(store);
+      return { message: out.markdown };
+    }
+    case 'show': {
+      const slug = rest[0];
+      if (!slug) throw new Error('Usage: /artifacts show <slug>');
+      const out = await runOpenArtifact(store, { slug });
+      return { message: out.markdown };
+    }
+    case 'remove': {
+      const slug = rest.find((a) => !a.startsWith('--'));
+      const confirm = rest.includes('--confirm');
+      if (!slug) throw new Error('Usage: /artifacts remove <slug> --confirm');
+      if (!confirm) throw new Error('Usage: /artifacts remove <slug> --confirm');
+      await store.remove(slug, true);
+      return { message: `removed: ${slug}` };
+    }
+    default:
+      throw new Error(`Unknown /artifacts subcommand: ${sub}. Try: list, show, remove.`);
+  }
+}

package/src/resources/extensions/coworker-artifacts/artifacts-singleton.test.ts

@@ -0,0 +1,25 @@
+// src/resources/extensions/coworker-artifacts/artifacts-singleton.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createArtifactsBundle } from './artifacts-singleton.js';
+
+describe('createArtifactsBundle', () => {
+  it('returns bundle with ArtifactStore', async () => {
+    const ws = mkdtempSync(join(tmpdir(), 'art-bundle-'));
+    const b = await createArtifactsBundle({ workspaceDir: ws });
+    assert.ok(b.store);
+    assert.equal(b.workspaceDir, ws);
+    await b.dispose();
+  });
+  it('store creates an artifact in the workspace dir', async () => {
+    const ws = mkdtempSync(join(tmpdir(), 'art-b2-'));
+    const b = await createArtifactsBundle({ workspaceDir: ws });
+    const h = await b.store.create('report', 'test');
+    assert.equal(h.slug, 'test');
+    assert.match(h.dir, /\.otto\/artifacts\/test$/);
+    await b.dispose();
+  });
+});

package/src/resources/extensions/coworker-artifacts/artifacts-singleton.ts

@@ -0,0 +1,29 @@
+// src/resources/extensions/coworker-artifacts/artifacts-singleton.ts
+//
+// Factory for the per-session ArtifactStore bundle. Mirrors the Phase 3
+// memory-singleton pattern so the activator can construct/dispose state in
+// one place. dispose() is a no-op in v1 (ArtifactStore holds no async
+// resources) but kept for pattern symmetry with memory + scratchpad bundles.
+import { ArtifactStore } from '@otto/coworker-artifacts';
+
+export interface ArtifactsBundleOptions {
+  workspaceDir: string;
+  now?: () => string;
+}
+
+export interface ArtifactsBundle {
+  store: ArtifactStore;
+  workspaceDir: string;
+  dispose(): Promise<void>;
+}
+
+export async function createArtifactsBundle(opts: ArtifactsBundleOptions): Promise<ArtifactsBundle> {
+  const store = new ArtifactStore({ workspaceDir: opts.workspaceDir, now: opts.now });
+  return {
+    store,
+    workspaceDir: opts.workspaceDir,
+    async dispose(): Promise<void> {
+      /* no async resources in v1 */
+    },
+  };
+}

package/src/resources/extensions/coworker-artifacts/extension-manifest.json

@@ -0,0 +1,13 @@
+{
+  "id": "coworker-artifacts",
+  "name": "Co-worker Artifacts",
+  "version": "1.0.0",
+  "description": "Workspace-scoped artifact store: artifact://<slug> URIs, /artifacts slash, list_artifacts + open_artifact tools",
+  "tier": "bundled",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["list_artifacts", "open_artifact"],
+    "commands": ["artifacts"],
+    "hooks": ["session_start", "session_shutdown"]
+  }
+}

package/src/resources/extensions/coworker-artifacts/index.test.ts

@@ -0,0 +1,46 @@
+// src/resources/extensions/coworker-artifacts/index.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import coworkerArtifactsExtension, { getArtifactStore } from './index.js';
+import { makeFakeApi, fireSessionStart, fireSessionShutdown } from '../coworker-vault/test-helpers.js';
+
+describe('coworker-artifacts activator', () => {
+  it('barrel exports key surface', () => {
+    assert.equal(typeof coworkerArtifactsExtension, 'function');
+    assert.equal(typeof getArtifactStore, 'function');
+  });
+  it('getArtifactStore is null before session_start', () => {
+    assert.equal(getArtifactStore(), null);
+  });
+  it('registers list_artifacts + open_artifact tools and /artifacts command', () => {
+    const api = makeFakeApi();
+    coworkerArtifactsExtension(api.api);
+    assert.ok(api.tools.has('list_artifacts'));
+    assert.ok(api.tools.has('open_artifact'));
+    assert.ok(api.commands.has('artifacts'));
+  });
+  it('session_start constructs bundle and getArtifactStore returns store', async () => {
+    const api = makeFakeApi();
+    coworkerArtifactsExtension(api.api);
+    const ws = mkdtempSync(join(tmpdir(), 'art-act-'));
+    await fireSessionStart(api, { cwd: ws });
+    assert.equal(api.notifyCalls.find((c) => /unavailable/.test(c.message)), undefined);
+    assert.ok(getArtifactStore());
+    await fireSessionShutdown(api);
+    assert.equal(getArtifactStore(), null);
+  });
+  it('command gates on bundle and notifies "not ready" when session_start never fires', async () => {
+    // ArtifactStore is lazy — its constructor doesn't fail even on an empty
+    // workspaceDir. The intended assertion of this test is the GATING path:
+    // a fresh activator whose session_start was never fired must respond to
+    // /artifacts with a "not ready" notify rather than crashing.
+    const fresh = makeFakeApi();
+    coworkerArtifactsExtension(fresh.api);
+    const cmd = fresh.commands.get('artifacts')!;
+    await cmd.handler('list', fresh.commandCtx);
+    assert.ok(fresh.notifyCalls.find((c) => /not ready/.test(c.message)));
+  });
+});

package/src/resources/extensions/coworker-artifacts/index.ts

@@ -0,0 +1,154 @@
+// src/resources/extensions/coworker-artifacts/index.ts
+//
+// Coworker Artifacts production activator. Wires the Phase 4 artifact
+// primitives (createArtifactsBundle, runListArtifacts, runOpenArtifact,
+// runArtifactsCommand) into pi's ExtensionAPI so /artifacts, the
+// list_artifacts + open_artifact tools, and the artifact://<slug> store
+// light up in a live Otto session.
+//
+// Cross-pillar surface: the scratchpad activator imports getArtifactStore()
+// from this module so its onArtifactCreate closure can resolve artifact://
+// URIs and bind them to the active scratchpad turn (Phase 4 Task 12).
+import type { ExtensionAPI } from '@otto/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import { ArtifactStore } from '@otto/coworker-artifacts';
+import { createArtifactsBundle, type ArtifactsBundle } from './artifacts-singleton.js';
+import { runListArtifacts } from './list-tool.js';
+import { runOpenArtifact } from './open-tool.js';
+import { runArtifactsCommand } from './artifacts-command.js';
+
+export { createArtifactsBundle };
+export type { ArtifactsBundle, ArtifactsBundleOptions } from './artifacts-singleton.js';
+
+// Cross-pillar export — null before session_start or after session_shutdown.
+let activeStore: ArtifactStore | null = null;
+export function getArtifactStore(): ArtifactStore | null {
+  return activeStore;
+}
+
+const LIST_PARAMS = Type.Object({});
+const OPEN_PARAMS = Type.Object({
+  slug: Type.String({ description: 'The artifact slug (e.g. "report" or "report-2") to read.' }),
+});
+
+// Union TDetails so TS accepts both error and success branches of execute().
+type ListDetails =
+  | { error: string; result_count?: undefined }
+  | { error?: undefined; result_count: number };
+type OpenDetails =
+  | { error: string; slug?: undefined }
+  | { error?: undefined; slug: string };
+
+export default function coworkerArtifactsExtension(api: ExtensionAPI): void {
+  let bundle: ArtifactsBundle | null = null;
+  let unavailable = false;
+
+  api.on('session_start', async (_event, ctx) => {
+    try {
+      bundle = await createArtifactsBundle({ workspaceDir: ctx.cwd });
+      activeStore = bundle.store;
+      unavailable = false;
+    } catch (err) {
+      unavailable = true;
+      bundle = null;
+      activeStore = null;
+      ctx.ui.notify(`artifacts unavailable: ${(err as Error).message}`, 'warning');
+    }
+  });
+
+  api.registerTool<typeof LIST_PARAMS, ListDetails>({
+    name: 'list_artifacts',
+    label: 'List artifacts',
+    description: 'List all artifacts in the current workspace.',
+    parameters: LIST_PARAMS,
+    async execute() {
+      if (!bundle) {
+        return {
+          content: [{ type: 'text', text: 'artifacts unavailable' }],
+          details: { error: 'unavailable' },
+        };
+      }
+      try {
+        const out = await runListArtifacts(bundle.store);
+        return {
+          content: [{ type: 'text', text: out.markdown }],
+          details: { result_count: out.artifacts.length },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `list failed: ${(err as Error).message}` }],
+          details: { error: (err as Error).message },
+        };
+      }
+    },
+  });
+
+  api.registerTool<typeof OPEN_PARAMS, OpenDetails>({
+    name: 'open_artifact',
+    label: 'Open artifact',
+    description: 'Read the contents of an artifact by slug. Returns markdown body + recent provenance.',
+    parameters: OPEN_PARAMS,
+    async execute(_toolCallId, params) {
+      if (!bundle) {
+        return {
+          content: [{ type: 'text', text: 'artifacts unavailable' }],
+          details: { error: 'unavailable' },
+        };
+      }
+      try {
+        const out = await runOpenArtifact(bundle.store, params);
+        return {
+          content: [{ type: 'text', text: out.markdown }],
+          details: { slug: params.slug },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `open failed: ${(err as Error).message}` }],
+          details: { error: (err as Error).message },
+        };
+      }
+    },
+  });
+
+  api.registerCommand('artifacts', {
+    description: 'Inspect artifacts: /artifacts list | show <slug> | remove <slug> --confirm',
+    getArgumentCompletions: (prefix) => {
+      const subs = [
+        { label: 'list', description: 'List all artifacts' },
+        { label: 'show', description: 'Show artifact body + provenance: /artifacts show <slug>' },
+        { label: 'remove', description: 'Delete artifact: /artifacts remove <slug> --confirm' },
+      ];
+      return subs
+        .filter((s) => s.label.startsWith(prefix))
+        .map((s) => ({ value: s.label, label: s.label, description: s.description }));
+    },
+    handler: async (args, ctx) => {
+      if (!bundle) {
+        ctx.ui.notify(
+          unavailable ? 'artifacts unavailable; chat continues without it.' : 'artifacts not ready yet.',
+          'warning',
+        );
+        return;
+      }
+      const argv = args.trim().split(/\s+/).filter(Boolean);
+      try {
+        const result = await runArtifactsCommand(bundle.store, argv);
+        ctx.ui.notify(result.message, 'info');
+      } catch (err) {
+        ctx.ui.notify(`/artifacts failed: ${(err as Error).message}`, 'error');
+      }
+    },
+  });
+
+  api.on('session_shutdown', async () => {
+    if (bundle) {
+      try {
+        await bundle.dispose();
+      } catch {
+        /* best effort */
+      }
+    }
+    bundle = null;
+    activeStore = null;
+  });
+}

package/src/resources/extensions/coworker-artifacts/list-tool.test.ts

@@ -0,0 +1,29 @@
+// src/resources/extensions/coworker-artifacts/list-tool.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ArtifactStore } from '@otto/coworker-artifacts';
+import { runListArtifacts } from './list-tool.js';
+
+describe('runListArtifacts', () => {
+  it('returns empty when no artifacts', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'lt-')) });
+    const out = await runListArtifacts(store);
+    assert.equal(out.artifacts.length, 0);
+    assert.match(out.markdown, /### Artifacts \(0\)/);
+  });
+  it('returns rows with markdown table for present artifacts', async () => {
+    const ws = mkdtempSync(join(tmpdir(), 'lt2-'));
+    const store = new ArtifactStore({ workspaceDir: ws });
+    await store.create('report', 'a');
+    await store.create('report', 'b');
+    const out = await runListArtifacts(store);
+    assert.equal(out.artifacts.length, 2);
+    assert.match(out.markdown, /### Artifacts \(2\)/);
+    assert.match(out.markdown, /\| slug \| kind \| turns \| last updated \| uri \|/);
+    assert.match(out.markdown, /artifact:\/\/a/);
+    assert.match(out.markdown, /artifact:\/\/b/);
+  });
+});

package/src/resources/extensions/coworker-artifacts/list-tool.ts

@@ -0,0 +1,53 @@
+// src/resources/extensions/coworker-artifacts/list-tool.ts
+//
+// `list_artifacts` LLM tool runner. Reads each artifact's metadata.json for
+// the timestamp + turn_count fields not carried on ArtifactHandle, and emits
+// both a structured payload and a markdown table for the assistant to surface.
+import type { ArtifactStore } from '@otto/coworker-artifacts';
+
+export interface ListedArtifact {
+  slug: string;
+  kind: string;
+  name: string;
+  uri: string;
+  created_at: string;
+  last_updated_at: string;
+  turn_count: number;
+}
+
+export interface ListToolOutput {
+  artifacts: ListedArtifact[];
+  markdown: string;
+}
+
+export async function runListArtifacts(store: ArtifactStore): Promise<ListToolOutput> {
+  const handles = await store.list();
+  // We need the metadata fields not on the handle — re-read each metadata.json.
+  const { readFileSync } = await import('node:fs');
+  const rows: ListedArtifact[] = handles.map((h) => {
+    const meta = JSON.parse(readFileSync(h.metadataPath, 'utf8')) as {
+      created_at: string;
+      last_updated_at: string;
+      turn_count: number;
+    };
+    return {
+      slug: h.slug,
+      kind: h.kind,
+      name: h.name,
+      uri: h.uri,
+      created_at: meta.created_at,
+      last_updated_at: meta.last_updated_at,
+      turn_count: meta.turn_count,
+    };
+  });
+  if (rows.length === 0) {
+    return { artifacts: [], markdown: '### Artifacts (0)\n' };
+  }
+  const lines: string[] = [`### Artifacts (${rows.length})`, ''];
+  lines.push('| slug | kind | turns | last updated | uri |');
+  lines.push('|---|---|---|---|---|');
+  for (const r of rows) {
+    lines.push(`| ${r.slug} | ${r.kind} | ${r.turn_count} | ${r.last_updated_at} | \`${r.uri}\` |`);
+  }
+  return { artifacts: rows, markdown: lines.join('\n') + '\n' };
+}

package/src/resources/extensions/coworker-artifacts/open-tool.test.ts

@@ -0,0 +1,30 @@
+// src/resources/extensions/coworker-artifacts/open-tool.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ArtifactStore, ArtifactNotFound } from '@otto/coworker-artifacts';
+import { runOpenArtifact } from './open-tool.js';
+
+describe('runOpenArtifact', () => {
+  it('returns markdown with content + provenance tail', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ot-')) });
+    const h = await store.create('report', 'r');
+    await store.update(h, [{ path: 'report.md', content: '# hello\n' }]);
+    await store.recordTurn(h, {
+      action: 'create',
+      turn_id: 't1',
+      user_prompt: 'draft',
+      files_touched: [],
+    });
+    const out = await runOpenArtifact(store, { slug: 'r' });
+    assert.match(out.markdown, /# hello/);
+    assert.match(out.markdown, /Recent provenance/);
+    assert.match(out.markdown, /turn `t1`/);
+  });
+  it('throws ArtifactNotFound for missing slug', async () => {
+    const store = new ArtifactStore({ workspaceDir: mkdtempSync(join(tmpdir(), 'ot2-')) });
+    await assert.rejects(() => runOpenArtifact(store, { slug: 'missing' }), ArtifactNotFound);
+  });
+});

package/src/resources/extensions/coworker-artifacts/open-tool.ts

@@ -0,0 +1,43 @@
+// src/resources/extensions/coworker-artifacts/open-tool.ts
+//
+// `open_artifact` LLM tool runner. Returns the primary file body wrapped in a
+// fenced markdown block plus the tail 5 provenance entries so the assistant
+// can summarise recent edits without flooding context with the full ledger.
+import type { ArtifactStore } from '@otto/coworker-artifacts';
+import { ArtifactNotFound } from '@otto/coworker-artifacts';
+
+export interface OpenToolOutput {
+  markdown: string;
+}
+
+export async function runOpenArtifact(
+  store: ArtifactStore,
+  args: { slug: string },
+): Promise<OpenToolOutput> {
+  const handle = await store.get(args.slug);
+  if (!handle) throw new ArtifactNotFound(args.slug);
+  const { readFileSync } = await import('node:fs');
+  const body = readFileSync(handle.primaryPath, 'utf8');
+  const provRaw = readFileSync(handle.provenancePath, 'utf8');
+  const prov = JSON.parse(provRaw) as Array<{
+    ts: string;
+    action: string;
+    turn_id: string;
+    user_prompt: string;
+  }>;
+  const tail = prov.slice(-5);
+  const lines: string[] = [];
+  lines.push(`### ${handle.name} (\`${handle.uri}\`)`);
+  lines.push('');
+  lines.push('```markdown');
+  lines.push(body);
+  lines.push('```');
+  lines.push('');
+  if (tail.length > 0) {
+    lines.push('**Recent provenance:**');
+    for (const e of tail) {
+      lines.push(`- ${e.ts} · ${e.action} · turn \`${e.turn_id}\` · ${e.user_prompt}`);
+    }
+  }
+  return { markdown: lines.join('\n') + '\n' };
+}

package/src/resources/extensions/coworker-memory/extension-manifest.json

@@ -0,0 +1,13 @@
+{
+  "id": "coworker-memory",
+  "name": "Co-worker Memory",
+  "version": "1.0.0",
+  "description": "Layered memory: Layer A (markdown rules/lessons) + Layer B (verbatim SQLite drawers) with /memory commands and memorize/recall tools",
+  "tier": "bundled",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["memorize", "recall"],
+    "commands": ["memory"],
+    "hooks": ["session_start", "session_shutdown"]
+  }
+}