@cmetech/otto 1.1.1 → 1.2.5

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

@@ -0,0 +1,207 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import type { ExtensionAPI, ExtensionContext } from '@otto/pi-coding-agent';
+import { ScratchpadManager, type DataLoadDrawer, type ArtifactCreateDrawer } from '@otto/coworker-scratchpad';
+import { getScratchpadsRoot } from '../shared/coworker-paths.js';
+import { getMemoryRecorder } from '../coworker-memory/index.js';
+import { getArtifactStore } from '../coworker-artifacts/index.js';
+import { registerSpCommand } from './sp-command.js';
+import { registerScratchpadTool } from './scratchpad-tool.js';
+import { sessionSidecarPath, readSessionSidecar, deleteSessionSidecar, sweepStaleSidecars } from './session-sidecar.js';
+import { detectWorkspaceRoot } from './workspace-root.js';
+import { workspaceHash, workspacePointerPath, readWorkspacePointer, isPointerFresh } from './workspace-pointer.js';
+import { formatRelativeAge } from './format-age.js';
+
+function deriveSessionId(ctx: ExtensionContext): string {
+  const file = ctx.sessionManager.getSessionFile() as string | undefined;
+  if (!file) return 'default';
+  const base = basename(file);
+  return base.endsWith('.jsonl') ? base.slice(0, -6) : base;
+}
+
+/**
+ * Computes restore precedence with sidecar-fallback. Returns the scratchpad to restore
+ * (if any) and the notice string to surface to the user. Does NOT call ctx.ui.notify —
+ * the caller does.
+ *
+ * Side-effect: deletes a broken sidecar (one whose referenced scratchpad no longer
+ * exists) so subsequent fresh sessions don't repeatedly re-check it. Not a pure
+ * function — a cleanup-closure refactor was considered and rejected as over-engineering
+ * for a single in-process call site.
+ *
+ * Precedence:
+ *   (a) per-session sidecar — wins when its scratchpad still exists on disk.
+ *   (b) broken sidecar — silently deleted, falls through to (c).
+ *   (c) workspace pointer — fresh (≤ 7d) AND its scratchpad still exists on disk.
+ *   (d) no restore.
+ */
+export function tryRestoreCurrentName(
+  root: string,
+  sessionId: string,
+  cwd: string,
+  now: number,
+): { name: string | null; notice: string | null } {
+  // (a) Sidecar restore
+  const sidecarPath = sessionSidecarPath(root, sessionId);
+  const sidecar = readSessionSidecar(sidecarPath);
+  if (sidecar) {
+    const meta = join(root, sidecar.current_name, 'meta.json');
+    if (existsSync(meta)) {
+      return { name: sidecar.current_name, notice: `attached to ${sidecar.current_name} (restored)` };
+    }
+    deleteSessionSidecar(sidecarPath); // broken sidecar — clean up silently and fall through
+  }
+
+  // (b) Workspace-pointer fallback
+  const wsRoot = detectWorkspaceRoot(cwd);
+  const ptr = readWorkspacePointer(workspacePointerPath(root, workspaceHash(wsRoot)));
+  if (ptr && isPointerFresh(ptr, now)) {
+    const meta = join(root, ptr.last_current_name, 'meta.json');
+    if (existsSync(meta)) {
+      const rel = formatRelativeAge(now - Date.parse(ptr.last_attached_at));
+      return {
+        name: ptr.last_current_name,
+        notice: `attached to ${ptr.last_current_name} (from workspace, last used ${rel})`,
+      };
+    }
+  }
+
+  // (c) No restore
+  return { name: null, notice: null };
+}
+
+const SUBAGENT_NAME_REGEX = /^subagent-[a-z0-9-]+$/;
+
+/**
+ * Phase 4.5: When the OTTO_SUBAGENT_SCRATCHPAD env var is set, force-attach
+ * to the named scratchpad (creating it if needed) BEFORE the sidecar/pointer
+ * restore path runs. Idempotent: re-running with same name attaches without
+ * overwriting existing state.
+ */
+export function forceSubagentAttach(name: string, scratchpadsRoot: string): { ok: true } | { ok: false; reason: string } {
+  if (!SUBAGENT_NAME_REGEX.test(name) || name.length > 80) {
+    return { ok: false, reason: `invalid subagent scratchpad name: ${name}` };
+  }
+  const dir = join(scratchpadsRoot, name);
+  try {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const metaPath = join(dir, 'meta.json');
+    if (!existsSync(metaPath)) {
+      const meta = {
+        name,
+        schema_version: 1,
+        created_at: new Date().toISOString(),
+        source: 'subagent-dispatch',
+      };
+      writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: (err as Error).message };
+  }
+}
+
+export default function coworkerScratchpadExtension(pi: ExtensionAPI): void {
+  let manager: ScratchpadManager | null = null;
+  let workspaceCwd: string | null = null;
+  let sessionId: string | null = null;
+  let currentName: string | null = null;
+  const root = getScratchpadsRoot();
+
+  const getManager = (): ScratchpadManager => {
+    if (!manager) {
+      if (!workspaceCwd) throw new Error('scratchpad: manager requested before session_start');
+      manager = new ScratchpadManager({
+        workspace: workspaceCwd,
+        root,
+        sessionId: sessionId ?? 'default',
+        // Phase 4 Task 11/12: lazy getter for the artifact store — returns null
+        // before artifacts session_start or after session_shutdown. Cross-pillar
+        // wiring is one-way (scratchpad → artifacts), so activator load order
+        // is indifferent.
+        getArtifactStore,
+        // Phase 3.1 Task 4: production hop into memory. `getMemoryRecorder()` is
+        // called lazily on each event so activator load order is indifferent —
+        // returns null before memory session_start or after session_shutdown,
+        // which is the correct no-op signal. Failures are swallowed silently
+        // (spec §3.8): file loads are frequent and a memory backend hiccup must
+        // not break the kernel runtime; surfaces in /audit instead.
+        onDataLoad: (drawer: DataLoadDrawer, scratchpadName: string): void => {
+          const recorder = getMemoryRecorder();
+          if (!recorder) return;
+          void recorder.recordFileLoad({
+            scratchpadName,
+            collector: drawer.collector,
+            uri: drawer.uri,
+            bytes: drawer.bytes ?? 0,
+            rows_loaded: drawer.rows_loaded ?? undefined,
+            schema: drawer.schema ?? undefined,
+            turnId: '',
+          }).catch(() => { /* silent: file loads are frequent; failures visible in /audit */ });
+        },
+        // Phase 4 Task 12: production hop into memory for artifact-create events.
+        // Mirrors the onDataLoad pattern: lazy recorder lookup, silent failures
+        // (spec §3.9). drawer.artifact_kind is the actual artifact kind
+        // (e.g. 'report'); drawer.kind is the discriminator literal 'artifact'.
+        onArtifactCreate: (drawer: ArtifactCreateDrawer, scratchpadName: string): void => {
+          const recorder = getMemoryRecorder();
+          if (!recorder) return;
+          void recorder.recordArtifact({
+            scratchpadName,
+            slug: drawer.slug,
+            kind: drawer.artifact_kind,
+            uri: drawer.uri,
+            turnId: '',
+          }).catch(() => { /* silent per spec §3.9 */ });
+        },
+      });
+    }
+    return manager;
+  };
+  const getCurrentName = (): string | null => currentName;
+  const setCurrentName = (n: string | null): void => { currentName = n; };
+  const rootDir = (): string => root;
+  const getSessionId = (): string => sessionId ?? 'default';
+  const getWorkspaceCwd = (): string => workspaceCwd ?? process.cwd();
+
+  registerSpCommand(pi, { getManager, getCurrentName, setCurrentName, rootDir, getSessionId, getWorkspaceCwd });
+  registerScratchpadTool(pi, { getManager, getCurrentName, setCurrentName, rootDir });
+
+  pi.on('session_start', async (_event, ctx) => {
+    workspaceCwd = ctx.cwd;
+    sessionId = deriveSessionId(ctx);
+
+    // Phase 4.5: force-attach to subagent scratchpad if OTTO_SUBAGENT_SCRATCHPAD is set.
+    const subagentName = process.env.OTTO_SUBAGENT_SCRATCHPAD;
+    if (subagentName) {
+      const result = forceSubagentAttach(subagentName, root);
+      if (result.ok) {
+        currentName = subagentName;
+        ctx.ui.notify(`attached to ${subagentName} (subagent dispatch)`, 'info');
+        try { sweepStaleSidecars(root, sessionId, Date.now()); } catch { /* silent */ }
+        return;
+      }
+      ctx.ui.notify(`subagent scratchpad attach failed: ${result.reason}; continuing without`, 'warning');
+      // fall through to normal restore
+    }
+
+    const restore = tryRestoreCurrentName(root, sessionId, ctx.cwd ?? process.cwd(), Date.now());
+    if (restore.name) {
+      currentName = restore.name;
+      ctx.ui.notify(restore.notice!, 'info');
+    }
+    // When neither sidecar nor fresh pointer resolves to an existing scratchpad,
+    // we stay silent — the user gets a clean session_start with no noise.
+    try { sweepStaleSidecars(root, sessionId, Date.now()); } catch { /* sweep failures are silent */ }
+  });
+
+  pi.on('session_shutdown', async () => {
+    if (manager) {
+      await manager.disposeAll();
+      manager = null;
+    }
+    // Sidecar deliberately NOT deleted here — survives so /resume restores.
+  });
+}

package/src/resources/extensions/coworker-scratchpad/mime-bundle.test.ts

@@ -0,0 +1,61 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { deriveMimeBundle } from './mime-bundle.js';
+
+describe('deriveMimeBundle', () => {
+  it('returns an empty bundle when value is undefined and stdout is empty', () => {
+    assert.deepEqual(deriveMimeBundle(undefined, ''), {});
+  });
+
+  it('returns only text/plain when stdout is non-empty and value is undefined', () => {
+    const b = deriveMimeBundle(undefined, 'hello\nworld');
+    assert.deepEqual(b, { 'text/plain': 'hello\nworld' });
+  });
+
+  it('returns only application/json when value is a number and stdout is empty', () => {
+    assert.deepEqual(deriveMimeBundle(42, ''), { 'application/json': 42 });
+  });
+
+  it('drops application/json when value is null', () => {
+    assert.deepEqual(deriveMimeBundle(null, 'log'), { 'text/plain': 'log' });
+  });
+
+  it('returns text/plain AND application/json when both present', () => {
+    assert.deepEqual(deriveMimeBundle({ rows: 3 }, 'loaded'), {
+      'text/plain': 'loaded',
+      'application/json': { rows: 3 },
+    });
+  });
+
+  it('adds text/markdown when value is a string starting with # (heading)', () => {
+    const b = deriveMimeBundle('# Title\n\nbody', '');
+    assert.equal(b['application/json'], '# Title\n\nbody');
+    assert.equal(b['text/markdown'], '# Title\n\nbody');
+  });
+
+  it('adds text/markdown when value is a string starting with | (table)', () => {
+    const md = '| a | b |\n|---|---|\n| 1 | 2 |';
+    const b = deriveMimeBundle(md, '');
+    assert.equal(b['text/markdown'], md);
+  });
+
+  it('adds text/markdown when value contains a GFM table separator row mid-string', () => {
+    const md = 'preamble\n\n| a | b |\n|---|---|\n| 1 | 2 |\n';
+    const b = deriveMimeBundle(md, '');
+    assert.equal(b['text/markdown'], md);
+  });
+
+  it('does NOT add text/markdown for plain prose strings', () => {
+    const b = deriveMimeBundle('just a sentence', '');
+    assert.equal(b['application/json'], 'just a sentence');
+    assert.equal(b['text/markdown'], undefined);
+  });
+
+  it('keeps the value in application/json when also tagged markdown', () => {
+    // A future LLM consumer that always reads application/json must not lose data
+    // just because the string looked markdown-shaped.
+    const b = deriveMimeBundle('# h', '');
+    assert.equal(b['application/json'], '# h');
+    assert.equal(b['text/markdown'], '# h');
+  });
+});

package/src/resources/extensions/coworker-scratchpad/mime-bundle.ts

@@ -0,0 +1,23 @@
+export interface MimeBundle {
+  'text/plain'?: string;
+  'application/json'?: unknown;
+  'text/markdown'?: string;
+}
+
+export function deriveMimeBundle(value: unknown, stdout: string): MimeBundle {
+  const bundle: MimeBundle = {};
+  if (stdout.length > 0) bundle['text/plain'] = stdout;
+  if (value !== undefined && value !== null) bundle['application/json'] = value;
+  if (typeof value === 'string' && looksLikeMarkdown(value)) {
+    bundle['text/markdown'] = value;
+  }
+  return bundle;
+}
+
+function looksLikeMarkdown(s: string): boolean {
+  const trimmed = s.trimStart();
+  if (trimmed.startsWith('#') || trimmed.startsWith('|')) return true;
+  // GFM table separator row: a line that is just |---|---|...
+  if (/\n\s*\|[-:|\s]+\|\s*\n/.test(s)) return true;
+  return false;
+}

package/src/resources/extensions/coworker-scratchpad/scratchpad-tool.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerScratchpadTool } from './scratchpad-tool.js';
+
+interface StubMgr {
+  runCell(name: string, code: string): Promise<{ value: unknown; stdout: string }>;
+  calls: Array<['runCell', string, string]>;
+  nextResult: { value: unknown; stdout: string } | { throw: Error };
+}
+function makeStub(): StubMgr {
+  const calls: StubMgr['calls'] = [];
+  return {
+    calls,
+    nextResult: { value: undefined, stdout: '' },
+    async runCell(name, code) {
+      calls.push(['runCell', name, code]);
+      if ('throw' in this.nextResult) throw this.nextResult.throw;
+      return this.nextResult;
+    },
+  };
+}
+
+interface FakePi {
+  tools: Map<string, { name: string; execute: (id: string, params: unknown, signal: unknown, onUpdate: unknown, ctx: unknown) => Promise<{ details: unknown }> }>;
+  registerTool(opts: { name: string; execute: (id: string, params: unknown, signal: unknown, onUpdate: unknown, ctx: unknown) => Promise<{ details: unknown }>; [k: string]: unknown }): void;
+}
+function makePi(): FakePi {
+  const tools = new Map();
+  return { tools, registerTool(opts) { tools.set(opts.name, opts); } };
+}
+
+let root: string;
+
+describe('scratchpad-tool dispatch (stubbed manager)', () => {
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'stool-root-'));
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function wire(currentName: string | null = null): { pi: FakePi; mgr: StubMgr; current: { name: string | null } } {
+    const pi = makePi();
+    const mgr = makeStub();
+    const current = { name: currentName };
+    registerScratchpadTool(pi as unknown as Parameters<typeof registerScratchpadTool>[0], {
+      getManager: () => mgr as unknown as Parameters<typeof registerScratchpadTool>[1]['getManager'] extends () => infer T ? T : never,
+      getCurrentName: () => current.name,
+      setCurrentName: (n) => { current.name = n; },
+      rootDir: () => root,
+    } as Parameters<typeof registerScratchpadTool>[1]);
+    return { pi, mgr, current };
+  }
+
+  it('exec without name uses currentName (or auto-default)', async () => {
+    const { pi, mgr, current } = wire(null);
+    mgr.nextResult = { value: 42, stdout: '' };
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'exec', code: 'return 42;' }, undefined, undefined, {})).details as { ok: boolean; mime: Record<string, unknown> };
+    assert.equal(current.name, 'default');
+    assert.deepEqual(mgr.calls, [['runCell', 'default', 'return 42;']]);
+    assert.equal(res.ok, true);
+    assert.equal(res.mime['application/json'], 42);
+  });
+
+  it('exec with explicit name does NOT change currentName', async () => {
+    const { pi, mgr, current } = wire('p1');
+    mgr.nextResult = { value: 'ok', stdout: '' };
+    await pi.tools.get('cw_scratchpad')!.execute('', { action: 'exec', name: 'side', code: 'return "ok";' }, undefined, undefined, {}).then(r => r.details);
+    assert.deepEqual(mgr.calls, [['runCell', 'side', 'return "ok";']]);
+    assert.equal(current.name, 'p1');
+  });
+
+  it('exec returns ok:false when manager throws', async () => {
+    const { pi, mgr } = wire('p1');
+    mgr.nextResult = { throw: Object.assign(new Error('boom'), { name: 'BoomError' }) } as any;
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'exec', code: 'throw new Error("boom");' }, undefined, undefined, {})).details as { ok: boolean; error: { name: string; message: string } };
+    assert.equal(res.ok, false);
+    assert.equal(res.error.name, 'BoomError');
+    assert.match(res.error.message, /boom/);
+  });
+
+  it('view returns tail-5 by default and the right total_cells', async () => {
+    const { pi } = wire('p1');
+    await mkdir(join(root, 'p1'), { recursive: true });
+    const lines = [JSON.stringify({ type: 'header', version: 1 })];
+    for (let i = 1; i <= 8; i++) {
+      lines.push(JSON.stringify({ id: i, parentId: i === 1 ? null : i - 1, code: `return ${i};`, ok: true, value: i, stdout: '', ts: `t${i}` }));
+    }
+    await writeFile(join(root, 'p1', 'cells.jsonl'), lines.join('\n') + '\n');
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'view' }, undefined, undefined, {})).details as { cells: Array<{ id: number }>; total_cells: number };
+    assert.equal(res.total_cells, 8);
+    assert.equal(res.cells.length, 5);
+    assert.deepEqual(res.cells.map((c) => c.id), [4, 5, 6, 7, 8]);
+  });
+
+  it('view caps tail at 20', async () => {
+    const { pi } = wire('p1');
+    await mkdir(join(root, 'p1'), { recursive: true });
+    const lines = [JSON.stringify({ type: 'header', version: 1 })];
+    for (let i = 1; i <= 30; i++) {
+      lines.push(JSON.stringify({ id: i, parentId: i === 1 ? null : i - 1, code: 'x', ok: true, value: i, stdout: '', ts: 't' }));
+    }
+    await writeFile(join(root, 'p1', 'cells.jsonl'), lines.join('\n') + '\n');
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'view', tail: 100 }, undefined, undefined, {})).details as { cells: unknown[] };
+    assert.equal(res.cells.length, 20);
+  });
+
+  it('view with from_id returns cells with id >= from_id', async () => {
+    const { pi } = wire('p1');
+    await mkdir(join(root, 'p1'), { recursive: true });
+    const lines = [JSON.stringify({ type: 'header', version: 1 })];
+    for (let i = 1; i <= 10; i++) {
+      lines.push(JSON.stringify({ id: i, parentId: i === 1 ? null : i - 1, code: 'x', ok: true, value: i, stdout: '', ts: 't' }));
+    }
+    await writeFile(join(root, 'p1', 'cells.jsonl'), lines.join('\n') + '\n');
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'view', from_id: 7 }, undefined, undefined, {})).details as { cells: Array<{ id: number }> };
+    assert.deepEqual(res.cells.map((c) => c.id), [7, 8, 9, 10]);
+  });
+
+  it('view truncates value strings to 200 chars and stdout to 500 chars', async () => {
+    const { pi } = wire('p1');
+    await mkdir(join(root, 'p1'), { recursive: true });
+    const longValue = 'x'.repeat(500);
+    const longStdout = 'y'.repeat(1000);
+    const lines = [
+      JSON.stringify({ type: 'header', version: 1 }),
+      JSON.stringify({ id: 1, parentId: null, code: 'long', ok: true, value: longValue, stdout: longStdout, ts: 't' }),
+    ];
+    await writeFile(join(root, 'p1', 'cells.jsonl'), lines.join('\n') + '\n');
+    const res = (await pi.tools.get('cw_scratchpad')!.execute('', { action: 'view' }, undefined, undefined, {})).details as { cells: Array<{ value: string; stdout: string }> };
+    assert.equal(res.cells[0].value.length, 200);
+    assert.equal(res.cells[0].stdout.length, 500);
+  });
+});

package/src/resources/extensions/coworker-scratchpad/scratchpad-tool.ts

@@ -0,0 +1,165 @@
+import { join } from 'node:path';
+import { StringEnum } from '@otto/pi-ai';
+import type { ExtensionAPI } from '@otto/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import type { ScratchpadManager, CellEntry } from '@otto/coworker-scratchpad';
+import { validateName, readCellsJsonl } from './helpers.js';
+import { deriveMimeBundle, type MimeBundle } from './mime-bundle.js';
+
+export interface ScratchpadToolDeps {
+  getManager: () => ScratchpadManager;
+  getCurrentName: () => string | null;
+  setCurrentName: (name: string | null) => void;
+  rootDir: () => string;
+}
+
+const VIEW_DEFAULT_TAIL = 5;
+const VIEW_MAX_TAIL = 20;
+const VALUE_TRUNCATE = 200;
+const STDOUT_TRUNCATE = 500;
+
+interface ExecResultOk {
+  ok: true;
+  cell_id: number;
+  total_cells: number;
+  mime: MimeBundle;
+}
+interface ExecResultErr {
+  ok: false;
+  cell_id: number;
+  total_cells: number;
+  error: { name: string; message: string };
+}
+type ExecResult = ExecResultOk | ExecResultErr;
+
+interface ViewCell {
+  id: number;
+  parentId: number | null;
+  ts: string;
+  code: string;
+  ok: boolean;
+  value?: unknown;
+  error?: { name: string; message: string };
+  stdout: string;
+}
+interface ViewResult {
+  name: string;
+  cells: ViewCell[];
+  total_cells: number;
+}
+
+function ensureCurrent(deps: ScratchpadToolDeps): string {
+  let current = deps.getCurrentName();
+  if (!current) {
+    current = 'default';
+    deps.setCurrentName(current);
+  }
+  return current;
+}
+
+function resolveName(deps: ScratchpadToolDeps, explicit?: string): string {
+  if (explicit) {
+    validateName(explicit);
+    return explicit;
+  }
+  return ensureCurrent(deps);
+}
+
+function truncateValue(value: unknown): unknown {
+  if (typeof value === 'string' && value.length > VALUE_TRUNCATE) {
+    return value.slice(0, VALUE_TRUNCATE);
+  }
+  return value;
+}
+
+function projectViewCell(c: CellEntry): ViewCell {
+  return {
+    id: c.id,
+    parentId: c.parentId,
+    ts: c.ts,
+    code: c.code,
+    ok: c.ok,
+    value: c.ok ? truncateValue(c.value) : undefined,
+    error: c.ok ? undefined : c.error,
+    stdout: (c.stdout ?? '').slice(0, STDOUT_TRUNCATE),
+  };
+}
+
+export function registerScratchpadTool(pi: ExtensionAPI, deps: ScratchpadToolDeps): void {
+  pi.registerTool({
+    name: 'cw_scratchpad',
+    label: 'Co-worker scratchpad',
+    description:
+      'USE FOR: loading or analyzing files (CSV, Excel, JSON, Parquet), tabular data manipulation with polars or DuckDB, multi-step data exploration where state should persist across turns, or anything that calls otto.collectors. ' +
+      'DO NOT USE FOR: simple arithmetic, lookups answerable from reasoning alone, pure prose, code review, or one-off calculations with no file or data source involved. ' +
+      'IF the user explicitly names this tool ("use cw_scratchpad", "run this in the scratchpad", "exec a cell"), use it regardless of the rules above. ' +
+      'IF UNSURE whether a request belongs here, ASK the user once: "Do you want me to run this in cw_scratchpad so you can inspect the cells via /sp view, or answer inline?" Wait for their reply before deciding. ' +
+      'Runs TypeScript cells in a persistent JS kernel scoped to a named scratchpad. State persists across cells via globalThis.* and across Otto sessions via on-disk kernel.db + namespace.json. ' +
+      'Pre-bound libs in every cell: polars, DuckDB, ExcelJS, dateFns, lodash, zod, axios. otto.collectors.{list,open} enumerates and loads data sources. ' +
+      'Actions: exec (run a TypeScript cell), view (return the last N cells). ' +
+      'Distinct from the analyst extension\'s SQL-only `scratchpad` tool — this one runs arbitrary TypeScript.',
+    promptSnippet:
+      'cw_scratchpad — run TypeScript cells in a persistent JS kernel. USE for files (CSV/Excel/JSON/Parquet), polars/DuckDB analysis, otto.collectors, or multi-step data work. NOT for arithmetic or pure prose. If unsure, ASK the user first.',
+    promptGuidelines: [
+      'Trigger criteria: the request involves loading a file (CSV/Excel/JSON/Parquet/etc.), querying tabular data via polars or DuckDB, calling otto.collectors, or building state that must survive across turns.',
+      'Skip the tool for: trivial arithmetic, lookups you can answer from reasoning, prose generation, code review, and pure-explanation tasks.',
+      'If the user names the tool explicitly (e.g. "use cw_scratchpad", "in the scratchpad", "exec a cell"), always honor that request and skip the unsure-prompt.',
+      'IF UNSURE whether a request fits the trigger criteria, ask the user once before deciding: "Do you want me to run this in cw_scratchpad (you can inspect the cells via /sp view) or answer inline?" Wait for the user\'s reply before either calling the tool or answering inline.',
+      'Use action="exec" to run TypeScript code in the current scratchpad. State persists across calls.',
+      'The cell body is wrapped in (async () => { ... })(). let/const/var are local to the cell. To persist, assign to globalThis.foo = ...',
+      'For DuckDB tables that survive across Otto sessions, use `await otto.duckdb.connect()`. For ephemeral in-memory, use `DuckDB.DuckDBInstance.create(":memory:")`.',
+      'For polars→DuckDB: prefer `otto.duckdb.registerDf(name, df)` over manual API discovery. If inference picks the wrong column type, pass `{ schema: { col: \'TYPE\' } }` as the third argument. Falls back to polars\' own SQL (`df.sql(...)`) for one-off aggregations.',
+      'Pre-bound libs available in every cell: polars, DuckDB, ExcelJS, dateFns, lodash, zod, axios. No imports needed.',
+      'Use otto.collectors.list() to discover data sources and otto.collectors.open(uri) to load one.',
+      'The `name` parameter defaults to the currently attached scratchpad. Omit it unless you want to operate on a different one (this does NOT switch the user attachment).',
+      'A returned string that looks markdown-shaped will appear in the response as text/markdown automatically. Return a markdown table or heading to render it.',
+      'Use action="view" to see the last 5 cells (default). Pass tail=20 or from_id to see more.',
+      'A failed cell IS recorded; the next view call will show it. Use this to recover.',
+      'Default cell timeout is 120s. Long operations should call progress("status") periodically to reset the inactivity timer.',
+    ],
+    parameters: Type.Object({
+      action: StringEnum(['exec', 'view'] as const),
+      name: Type.Optional(Type.String({ description: "Scratchpad name; defaults to the current session attachment, auto-creating 'default' if none." })),
+      code: Type.Optional(Type.String({ description: "TypeScript cell code (action='exec' only)." })),
+      tail: Type.Optional(Type.Number({ description: `How many trailing cells to return (action='view' only). Default ${VIEW_DEFAULT_TAIL}, max ${VIEW_MAX_TAIL}.` })),
+      from_id: Type.Optional(Type.Number({ description: "If set, view returns cells with id >= from_id (overrides tail)." })),
+    }),
+    async execute(_toolCallId: string, params: { action: 'exec' | 'view'; name?: string; code?: string; tail?: number; from_id?: number }, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown): Promise<{ content: { type: 'text'; text: string }[]; details: ExecResult | ViewResult }> {
+      const name = resolveName(deps, params.name);
+
+      let result: ExecResult | ViewResult;
+
+      if (params.action === 'exec') {
+        if (!params.code) {
+          throw new Error('code is required for action="exec"');
+        }
+        const mgr = deps.getManager();
+        try {
+          const { value, stdout } = await mgr.runCell(name, params.code);
+          const { total_cells } = readCellsJsonl(join(deps.rootDir(), name));
+          result = { ok: true, cell_id: total_cells, total_cells, mime: deriveMimeBundle(value, stdout) };
+        } catch (err) {
+          const e = err as Error;
+          const { total_cells } = readCellsJsonl(join(deps.rootDir(), name));
+          result = { ok: false, cell_id: total_cells, total_cells, error: { name: e.name, message: e.message } };
+        }
+      } else {
+        // view
+        const { cells, total_cells } = readCellsJsonl(join(deps.rootDir(), name));
+        let selected: CellEntry[];
+        if (typeof params.from_id === 'number') {
+          selected = cells.filter((c) => c.id >= params.from_id!);
+        } else {
+          const tail = Math.min(params.tail ?? VIEW_DEFAULT_TAIL, VIEW_MAX_TAIL);
+          selected = cells.slice(-tail);
+        }
+        result = { name, cells: selected.map(projectViewCell), total_cells };
+      }
+
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}