@volcanic-dev/tephra 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Tephra
 
-**A clipboard for AI agents.** Tephra is an MCP server that lets a model copy an exact character range from a file — start `(line, char)` to end `(line, char)` — and paste it at an exact position somewhere else. Byte-for-byte, no retyping, no transcription drift, no tokens spent regenerating code that already exists.
+**A clipboard for AI agents.** When a model moves code by regenerating it, it retypes 200 lines from memory — and sometimes what lands isn't quite what left. That transcription drift is a correctness bug, not just a token cost. Tephra is an MCP server for byte-exact copy and paste: name whole lines (or exact `(line, char)` ranges), copy them byte-for-byte, paste them at an exact position anywhere else. **Your agent will never subtly mangle code it's moving.**
 
 The clipboard is a **private in-process buffer, deliberately not the OS clipboard**. An agent can never read what you last copied (passwords, tokens, anything) and can never overwrite what you're about to paste. Nothing touches disk; the buffer dies with the session.
 
@@ -18,16 +18,30 @@ npx -y @volcanic-dev/tephra
 
 | Tool | What it does |
 |------|--------------|
-| `copy` | Copy `(start_line, start_char)` → `(end_line, end_char)` from a file to the clipboard. Both ends inclusive, 1-indexed. Newlines inside the range are included. |
-| `cut` | Same as `copy`, but removes the range from the source file. |
-| `paste` | Insert the clipboard into a file before the character at `(line, char)`. `char` may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
-| `peek` | Show the clipboard's current size and a preview. |
+| `copy` | Copy one or more ranges `{start_line, end_line, whole_lines?, start_char?, end_char?, slot?, expect?}` from a file into clipboard slots. Both ends inclusive, 1-indexed. Newlines inside a range are included. |
+| `cut` | Same as `copy`, but removes the ranges from the source file (ranges must be disjoint). Whole-line cuts take the newline too — no empty line left behind. |
+| `paste` | Insert clipboard slots into a file at one or more targets `{line, char?, slot?, expect?}` — before the character at `(line, char)`; `char` defaults to 1 and may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
+| `peek` | List the slots that hold text, or show one slot's size and preview. |
+
+## Named slots
+
+Every range and target takes an optional `slot` (default `"default"`). Gather many snippets in one pass — each into its own slot — then paste them in any order, any number of times. Multi-range calls must name a distinct slot per range.
+
+## Staying robust as line numbers shift
+
+Cutting or pasting lines shifts the numbering of everything below the edit — the classic way agents (especially several agents on one file) end up acting on stale coordinates. Tephra attacks this three ways:
+
+- **Bottom-up batches.** All ranges/targets in one call are addressed against the file *as you last read it* and applied from the bottom of the file up, so none invalidates another. One read, one call, no arithmetic.
+- **`expect` anchors — coordinates are hints, content is truth.** Pass the text you believe is at the position (up to 200 chars). On mismatch, nothing is modified and the error reports what is actually there and where your expected text lives now (`"the content has moved; re-aim at 43:12"`), so recovery is one round-trip. This catches *every* source of drift, including edits made outside Tephra.
+- **Shift reports.** Every cut and paste result states how line numbers moved (`"former line 4 is now line 3"`) and the file's new addressable line count, so positions noted earlier can be recomputed instead of silently going stale.
 
 ## Addressing
 
-- Lines and characters are **1-indexed**: the first character of a file is `(1, 1)`.
-- Copy/cut ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
-- To copy whole lines 10–14: start `(10, 1)`, end `(14, <length of line 14>)`.
+Models read line numbers well and count characters badly, so the common case never counts:
+
+- **Whole lines** (the usual move): `{start_line: 10, end_line: 14, whole_lines: true}`. Linewise, vim-style — the trailing newline comes along, so a cut lifts the lines out cleanly and a paste at `{line: 42}` drops them in as complete lines.
+- Character positions are optional refinements: omitted `end_char` means end-of-line, omitted `start_char` (or paste `char`) means column 1.
+- When given, everything is **1-indexed** and ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
 - A file ending in a newline has an addressable empty final line, so appending at end-of-file is `paste` at `(lastLine, 1)`.
 - Out-of-range positions return the line's real length and a preview of it, so an agent can self-correct in one step.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanic-dev/tephra",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server that gives AI agents a clipboard of their own: copy an exact line:char range from a file, paste it anywhere — byte-for-byte, without touching the OS clipboard.",
   "license": "MIT",
   "type": "module",

package/server.js

@@ -2,17 +2,30 @@
 // @tephra-server
 // Tephra — an MCP server that gives AI agents a clipboard of their own.
 //
-// Models are bad at retyping: moving 80 lines of code by regenerating them
-// invites transcription drift and burns tokens. Tephra lets an agent name an
-// exact range — start (line, char) to end (line, char), both 1-indexed and
-// inclusive — copy it byte-for-byte, and paste it at an exact position in
-// another file.
+// Models are bad at retyping: regenerating 200 lines to move them invites
+// transcription drift — a correctness bug, not just a token cost. Tephra
+// lets an agent name an exact range — whole lines, or (line, char) to
+// (line, char), 1-indexed and inclusive — copy it byte-for-byte, and paste
+// it at an exact position in another file.
+//
+// Models are also bad at counting characters within a line, so character
+// positions are optional everywhere: whole_lines ranges take line numbers
+// only (linewise, including the trailing newline, so cuts leave no empty
+// husk), an omitted end_char means end-of-line, an omitted start_char or
+// paste char means column 1.
 //
 // The clipboard is a private in-process buffer, deliberately NOT the OS
 // clipboard: an agent must not be able to read whatever the human last
 // copied (passwords, tokens) or overwrite what they're about to paste.
 // Nothing is written to disk; the buffer dies with the session.
 //
+// Coordinates are hints; content is truth. Any range or paste target can
+// carry an `expect` anchor that is verified before anything is touched — a
+// mismatch modifies nothing and reports where that text actually is now.
+// Batched ranges/targets are applied bottom-up, so one read of a file
+// yields coordinates that stay valid for the whole call, and any edit that
+// changes line numbering reports the shift.
+//
 // Tools: copy, cut, paste, peek.
 
 import { readFile, writeFile } from 'node:fs/promises'
@@ -20,8 +33,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
 
-// @tephra-buffer — the private clipboard; in-memory only, per-session
-let clipboard = ''
+// @tephra-buffer — the private clipboard; in-memory only, per-session.
+// Named slots let an agent hold several snippets at once (gather many
+// ranges, then paste them in any order) without round-tripping content.
+const slots = new Map()
+
+function slotList() {
+  return [...slots.entries()].map(([name, text]) => `"${name}" (${describe(text)})`).join(', ')
+}
 
 // @tephra-positions — 1-indexed (line, char) ↔ absolute offset math
 // indexLines keeps a trailing empty line when the file ends with \n, so
@@ -57,8 +76,8 @@ function charOffset(text, lines, line, char, label, maxExtra) {
   const len = L.contentEnd - L.start
   const max = len + maxExtra
   if (!Number.isInteger(char) || char < 1 || char > max) {
-    const preview = text.slice(L.start, L.contentEnd)
-    const shown = preview.length > 80 ? `${preview.slice(0, 80)}…` : preview
+    const previewText = text.slice(L.start, L.contentEnd)
+    const shown = previewText.length > 80 ? `${previewText.slice(0, 80)}…` : previewText
     throw new PositionError(
       `${label}: char ${char} is out of range on line ${line}, which has ${len} character${len === 1 ? '' : 's'}` +
       (maxExtra ? ` (valid: 1–${max}, where ${max} means end of line)` : ` (valid: 1–${Math.max(max, 1)})`) +
@@ -68,34 +87,134 @@ function charOffset(text, lines, line, char, label, maxExtra) {
   return L.start + (char - 1)
 }
 
+// positionOf: absolute offset → 1-indexed { line, char }
+function positionOf(lines, off) {
+  let lo = 0
+  let hi = lines.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (lines[mid].start <= off) lo = mid
+    else hi = mid - 1
+  }
+  return { line: lo + 1, char: off - lines[lo].start + 1 }
+}
+
+// @tephra-verify — expect anchors: verify content before acting. On mismatch
+// nothing is modified; the error reports what IS at the position and where
+// the expected text actually lives now, so the agent re-aims in one step.
+function verifyExpect(text, lines, off, expect, label) {
+  if (text.startsWith(expect, off)) return
+  const at = positionOf(lines, off)
+  const actual = text.slice(off, off + Math.min(Math.max(expect.length, 20), 80))
+  const found = []
+  let total = 0
+  let i = text.indexOf(expect)
+  while (i !== -1) {
+    total++
+    if (found.length < 5) found.push(positionOf(lines, i))
+    i = text.indexOf(expect, i + 1)
+  }
+  let msg = `${label}: the file does not have the expected text at ${at.line}:${at.char}. It has ${JSON.stringify(actual)} there, not ${JSON.stringify(expect.slice(0, 80))}.`
+  if (total === 1) {
+    msg += ` The expected text IS in the file, at ${found[0].line}:${found[0].char} — the content has moved; re-aim there.`
+  } else if (total > 1) {
+    msg += ` The expected text appears ${total} times: at ${found.map((p) => `${p.line}:${p.char}`).join(', ')}${total > found.length ? ', …' : ''}. Pick the right one and re-aim.`
+  } else {
+    msg += ' The expected text does not appear anywhere in the file — re-read the file before retrying.'
+  }
+  throw new PositionError(`${msg} Nothing was modified.`)
+}
+
 // @tephra-preview — head/tail preview so results stay small even for big copies
 function preview(text) {
   if (text.length <= 300) return text
   return `${text.slice(0, 200)}\n… [${text.length - 300} chars omitted] …\n${text.slice(-100)}`
 }
 
+function inlinePreview(text) {
+  return JSON.stringify(text.length <= 60 ? text : `${text.slice(0, 45)}…${text.slice(-10)}`)
+}
+
 function describe(text) {
   const lines = text.length === 0 ? 0 : text.split('\n').length
   return `${text.length} chars, ${lines} line${lines === 1 ? '' : 's'}`
 }
 
-// endPosition: (line, char) of the character right after `text` inserted at (line, char)
-function endPosition(startLine, startChar, text) {
-  const parts = text.split('\n')
-  if (parts.length === 1) return { line: startLine, char: startChar + text.length }
-  return { line: startLine + parts.length - 1, char: parts[parts.length - 1].length + 1 }
+function newlineCount(text) {
+  let n = 0
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') n++
+  return n
 }
 
-// @tephra-extract — shared range extraction for copy/cut
-async function extractRange(file, startLine, startChar, endLine, endChar) {
-  const text = await readFile(file, 'utf8')
-  const lines = indexLines(text)
-  const startOff = charOffset(text, lines, startLine, startChar, 'start', 0)
-  const endOff = charOffset(text, lines, endLine, endChar, 'end', 0)
-  if (endOff < startOff) {
-    throw new PositionError(`The end position (line ${endLine}, char ${endChar}) comes before the start position (line ${startLine}, char ${startChar}).`)
+// @tephra-shift — cut/paste change the file's line numbering; say so explicitly,
+// so agents (and other agents coordinating on the same file) can recalibrate
+// instead of acting on stale positions.
+function shiftNote(afterLine, delta) {
+  if (delta === 0) return ''
+  const dir = delta > 0 ? 'down' : 'up'
+  return `\nLine numbers have shifted: every line that was below line ${afterLine} moved ${dir} by ${Math.abs(delta)} (former line ${afterLine + 1} is now line ${afterLine + 1 + delta}). Recompute any positions you noted earlier before using them.`
+}
+
+// @tephra-extract — shared range resolution for copy/cut. All ranges are
+// addressed against the same read of the file; cut applies them bottom-up so
+// none invalidates another. Multi-range calls must name a distinct slot per
+// range (defaulting them all to "default" would silently overwrite).
+// whole_lines ranges are linewise: they include the end line's terminator,
+// so cutting them removes the lines entirely instead of leaving empty husks.
+function resolveRanges(text, lines, ranges, forCut) {
+  const resolved = ranges.map((r, idx) => {
+    const label = ranges.length === 1 ? 'range' : `range ${idx + 1}`
+    let slot = r.slot
+    if (slot === undefined) {
+      if (ranges.length > 1) throw new PositionError(`${label}: when passing multiple ranges, every range must name its own slot (otherwise they would overwrite each other).`)
+      slot = 'default'
+    }
+    let startOff
+    let endOff
+    if (r.whole_lines) {
+      if (r.start_char !== undefined || r.end_char !== undefined) {
+        throw new PositionError(`${label}: whole_lines ranges take only start_line and end_line — omit start_char and end_char.`)
+      }
+      startOff = lineAt(lines, r.start_line, `${label} start`).start
+      lineAt(lines, r.end_line, `${label} end`)
+      endOff = r.end_line < lines.length ? lines[r.end_line].start : text.length
+    } else {
+      startOff = r.start_char === undefined
+        ? lineAt(lines, r.start_line, `${label} start`).start
+        : charOffset(text, lines, r.start_line, r.start_char, `${label} start`, 0)
+      endOff = r.end_char === undefined
+        ? lineAt(lines, r.end_line, `${label} end`).contentEnd
+        : charOffset(text, lines, r.end_line, r.end_char, `${label} end`, 0) + 1 // end is inclusive
+    }
+    if (endOff <= startOff) {
+      throw new PositionError(`${label}: the range from ${rangeDesc(r)} is empty or reversed — the end does not come after the start.`)
+    }
+    if (r.expect !== undefined) verifyExpect(text, lines, startOff, r.expect, label)
+    return { ...r, idx, label, slot, startOff, endOff }
+  })
+  const seen = new Map()
+  for (const r of resolved) {
+    if (seen.has(r.slot)) throw new PositionError(`${r.label} and ${seen.get(r.slot)} both target slot "${r.slot}" — one would overwrite the other. Use distinct slots.`)
+    seen.set(r.slot, r.label)
+  }
+  if (forCut) {
+    const byOff = [...resolved].sort((a, b) => a.startOff - b.startOff)
+    for (let i = 1; i < byOff.length; i++) {
+      if (byOff[i].startOff < byOff[i - 1].endOff) {
+        throw new PositionError(`${byOff[i - 1].label} and ${byOff[i].label} overlap — cut ranges must be disjoint. Nothing was modified.`)
+      }
+    }
   }
-  return { text, startOff, endOff: endOff + 1 } // end is inclusive
+  return resolved
+}
+
+function rangeDesc(r) {
+  if (r.whole_lines) return r.start_line === r.end_line ? `line ${r.start_line}` : `lines ${r.start_line}–${r.end_line}`
+  return `${r.start_line}:${r.start_char ?? 1} → ${r.end_line}:${r.end_char ?? 'end-of-line'}`
+}
+
+function rangeSummary(r, snippet) {
+  return `slot "${r.slot}": ${describe(snippet)} (${rangeDesc(r)}) — ${inlinePreview(snippet)}`
 }
 
 function ok(message) {
@@ -115,52 +234,97 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.1.0' })
+const server = new McpServer({ name: 'tephra', version: '0.3.0' })
+
+const expectSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .optional()
+  .describe('Verification anchor: the text you believe is at this position (up to 200 chars). On mismatch nothing is modified and the error reports where that text actually is now. Strongly recommended whenever the file may have changed since you read it.')
 
-const rangeSchema = {
-  file: z.string().describe('Absolute path of the file to copy from'),
-  start_line: z.number().int().describe('Line of the first character to copy (1-indexed)'),
-  start_char: z.number().int().describe('Character position on start_line of the first character to copy (1-indexed)'),
-  end_line: z.number().int().describe('Line of the last character to copy (1-indexed, inclusive)'),
-  end_char: z.number().int().describe('Character position on end_line of the last character to copy (1-indexed, inclusive)'),
+const rangeItem = z.object({
+  start_line: z.number().int().describe('Line of the first character (1-indexed)'),
+  start_char: z.number().int().optional().describe('Character position on start_line of the first character (1-indexed). Omit to start at the beginning of the line.'),
+  end_line: z.number().int().describe('Line of the last character (1-indexed, inclusive)'),
+  end_char: z.number().int().optional().describe('Character position on end_line of the last character (1-indexed, inclusive). Omit to run to the end of the line. Prefer omitting over counting characters.'),
+  whole_lines: z.boolean().optional().describe('Take start_line through end_line as complete lines, INCLUDING the trailing newline (so cutting removes the lines entirely, leaving no empty line behind). With this set, omit start_char/end_char. Preferred for any whole-line move.'),
+  slot: z.string().min(1).max(64).optional().describe('Clipboard slot to store this range in. Optional for a single range (defaults to "default"); required, and distinct, when passing multiple ranges.'),
+  expect: expectSchema,
+})
+
+const rangesSchema = {
+  file: z.string().describe('Absolute path of the file to read from'),
+  ranges: z
+    .array(rangeItem)
+    .min(1)
+    .max(20)
+    .describe('One or more ranges, all addressed against the file as it is right now — they are applied bottom-up, so earlier ranges never invalidate later ones.'),
 }
 
 server.registerTool(
   'copy',
   {
-    title: 'Copy range to clipboard',
+    title: 'Copy ranges to clipboard',
     description:
-      "Copy an exact character range from a file to Tephra's clipboard, byte-for-byte. " +
-      'The range runs from (start_line, start_char) through (end_line, end_char), inclusive on both ends; ' +
-      'newlines inside the range are included. Use this instead of retyping text you intend to move or duplicate. ' +
+      "Copy one or more exact ranges from a file into Tephra's clipboard slots, byte-for-byte — use this instead of retyping text you intend to move or duplicate, so nothing gets subtly mangled in transit. " +
+      'For whole lines (the common case), set whole_lines: true and give line numbers only. ' +
+      'Character positions are optional: each range runs (start_line, start_char) → (end_line, end_char), inclusive on both ends, 1-indexed; omit start_char for column 1 and end_char for end-of-line rather than counting characters. ' +
+      "Pass `expect` (the range's first characters) to verify the coordinates still match the content before copying. " +
       'The clipboard is private to this session, not the operating system clipboard.',
-    inputSchema: rangeSchema,
+    inputSchema: rangesSchema,
   },
-  async ({ file, start_line, start_char, end_line, end_char }) =>
+  async ({ file, ranges }) =>
     guarded(async () => {
-      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
-      const snippet = text.slice(startOff, endOff)
-      clipboard = snippet
-      return ok(`Copied ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard.\n\nPreview:\n${preview(snippet)}`)
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const resolved = resolveRanges(text, lines, ranges, false)
+      const snippets = resolved.map((r) => text.slice(r.startOff, r.endOff))
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      if (resolved.length === 1) {
+        const [r] = resolved
+        return ok(`Copied ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) to slot "${r.slot}".\n\nPreview:\n${preview(snippets[0])}`)
+      }
+      return ok(`Copied ${resolved.length} ranges from ${file}:\n${resolved.map((r, i) => `- ${rangeSummary(r, snippets[i])}`).join('\n')}`)
     }),
 )
 
 server.registerTool(
   'cut',
   {
-    title: 'Cut range to clipboard',
+    title: 'Cut ranges to clipboard',
     description:
-      'Same as copy, but also removes the range from the source file. ' +
-      'The range is inclusive on both ends. The file is written back immediately.',
-    inputSchema: rangeSchema,
+      'Same as copy, but also removes the ranges from the source file (they must not overlap). ' +
+      'For moving whole lines, set whole_lines: true — the trailing newline comes along, so the lines are removed entirely with no empty line left behind. ' +
+      'Ranges are removed bottom-up, so every range is addressed against the file exactly as you last read it. The file is written back immediately. ' +
+      'CAUTION: removing lines shifts the line numbers of everything below a cut — the result says by how much; recompute stale positions before reusing them.',
+    inputSchema: rangesSchema,
   },
-  async ({ file, start_line, start_char, end_line, end_char }) =>
+  async ({ file, ranges }) =>
     guarded(async () => {
-      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
-      const snippet = text.slice(startOff, endOff)
-      clipboard = snippet
-      await writeFile(file, text.slice(0, startOff) + text.slice(endOff), 'utf8')
-      return ok(`Cut ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard. The file has been updated.\n\nPreview:\n${preview(snippet)}`)
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const resolved = resolveRanges(text, lines, ranges, true)
+      const snippets = resolved.map((r) => text.slice(r.startOff, r.endOff))
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      let out = text
+      for (const r of [...resolved].sort((a, b) => b.startOff - a.startOff)) {
+        out = out.slice(0, r.startOff) + out.slice(r.endOff)
+      }
+      await writeFile(file, out, 'utf8')
+      const finalCount = indexLines(out).length
+      if (resolved.length === 1) {
+        const [r] = resolved
+        return ok(`Cut ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) to slot "${r.slot}". The file has been updated (${finalCount} addressable lines).${shiftNote(r.end_line, -newlineCount(snippets[0]))}\n\nPreview:\n${preview(snippets[0])}`)
+      }
+      const removedLines = snippets.reduce((acc, s) => acc + newlineCount(s), 0)
+      return ok(
+        `Cut ${resolved.length} ranges from ${file}, applied bottom-up (file updated, ${finalCount} addressable lines):\n` +
+        resolved.map((r, i) => `- ${rangeSummary(r, snippets[i])}`).join('\n') +
+        (removedLines > 0
+          ? `\n${removedLines} line${removedLines === 1 ? '' : 's'} of numbering removed in total — line numbers below each cut have shifted up; recompute any positions you noted earlier before using them.`
+          : ''),
+      )
     }),
 )
 
@@ -169,25 +333,68 @@ server.registerTool(
   {
     title: 'Paste clipboard into file',
     description:
-      "Insert Tephra's clipboard contents into a file at an exact position. " +
-      'The clipboard text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
-      'Existing text is never overwritten — it shifts to make room.',
+      "Insert Tephra clipboard slot contents into a file at one or more exact positions. " +
+      'Text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
+      'Multiple targets are applied bottom-up, so they all use the coordinates of the file as you last read it. ' +
+      'Pass `expect` (the text that currently begins at the position) to verify before pasting. ' +
+      'Existing text is never overwritten — it shifts to make room, and the result says how line numbers moved.',
     inputSchema: {
       file: z.string().describe('Absolute path of the file to paste into'),
-      line: z.number().int().describe('Line to paste at (1-indexed)'),
-      char: z.number().int().describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line)'),
+      targets: z
+        .array(
+          z.object({
+            line: z.number().int().describe('Line to paste at (1-indexed)'),
+            char: z.number().int().default(1).describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line). Omit to paste at the start of the line — the right choice when pasting whole lines.'),
+            slot: z.string().min(1).max(64).default('default').describe('Clipboard slot to paste from (defaults to "default")'),
+            expect: expectSchema,
+          }),
+        )
+        .min(1)
+        .max(20)
+        .describe('One or more paste positions, all addressed against the file as it is right now — they are applied bottom-up, so earlier targets never invalidate later ones.'),
     },
   },
-  async ({ file, line, char }) =>
+  async ({ file, targets }) =>
     guarded(async () => {
-      const clip = clipboard
-      if (clip.length === 0) return fail('The clipboard is empty — nothing to paste. Use copy or cut first.')
       const text = await readFile(file, 'utf8')
       const lines = indexLines(text)
-      const off = charOffset(text, lines, line, char, 'paste position', 1)
-      await writeFile(file, text.slice(0, off) + clip + text.slice(off), 'utf8')
-      const end = endPosition(line, char, clip)
-      return ok(`Pasted ${describe(clip)} into ${file} at ${line}:${char}. The inserted text now spans ${line}:${char} → ${end.line}:${end.char} (exclusive end).\n\nPreview:\n${preview(clip)}`)
+      const resolved = targets.map((t, idx) => {
+        const label = targets.length === 1 ? 'paste position' : `target ${idx + 1}`
+        const clip = slots.get(t.slot)
+        if (clip === undefined || clip.length === 0) {
+          throw new PositionError(`${label}: slot "${t.slot}" is empty — nothing to paste. ${slots.size > 0 ? `Slots that do hold text: ${slotList()}.` : 'Use copy or cut first.'}`)
+        }
+        const off = charOffset(text, lines, t.line, t.char, label, 1)
+        if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
+        return { ...t, idx, label, off, clip }
+      })
+      let out = text
+      for (const t of [...resolved].sort((a, b) => b.off - a.off || b.idx - a.idx)) {
+        out = out.slice(0, t.off) + t.clip + out.slice(t.off)
+      }
+      await writeFile(file, out, 'utf8')
+      const finalLines = indexLines(out)
+      // final coordinates: shift each target by everything inserted above it
+      const placed = resolved.map((t) => {
+        const delta = resolved.reduce((acc, o) => acc + (o.off < t.off || (o.off === t.off && o.idx < t.idx) ? o.clip.length : 0), 0)
+        return {
+          t,
+          start: positionOf(finalLines, t.off + delta),
+          end: positionOf(finalLines, t.off + delta + t.clip.length),
+        }
+      })
+      if (placed.length === 1) {
+        const [{ t, start, end }] = placed
+        return ok(`Pasted ${describe(t.clip)} from slot "${t.slot}" into ${file} at ${t.line}:${t.char}. The inserted text now spans ${start.line}:${start.char} → ${end.line}:${end.char} (exclusive end).${shiftNote(t.line, newlineCount(t.clip))}\n\nPreview:\n${preview(t.clip)}`)
+      }
+      const addedLines = resolved.reduce((acc, t) => acc + newlineCount(t.clip), 0)
+      return ok(
+        `Pasted ${placed.length} targets into ${file}, applied bottom-up (file updated, ${finalLines.length} addressable lines):\n` +
+        placed.map(({ t, start, end }) => `- slot "${t.slot}" (${describe(t.clip)}) at ${t.line}:${t.char} → final span ${start.line}:${start.char} → ${end.line}:${end.char}`).join('\n') +
+        (addedLines > 0
+          ? `\n${addedLines} line${addedLines === 1 ? '' : 's'} of numbering inserted in total — line numbers below each paste have shifted down; recompute any positions you noted earlier before using them.`
+          : ''),
+      )
     }),
 )
 
@@ -195,13 +402,22 @@ server.registerTool(
   'peek',
   {
     title: 'Peek at clipboard',
-    description: "Show what is currently on Tephra's clipboard (size and a preview) without modifying anything.",
-    inputSchema: {},
+    description:
+      "Show what is currently on Tephra's clipboard without modifying anything. " +
+      "With a slot name: that slot's size and a preview. Without: a listing of every slot that holds text.",
+    inputSchema: {
+      slot: z.string().min(1).max(64).optional().describe('Slot to inspect; omit to list all slots'),
+    },
   },
-  async () =>
+  async ({ slot }) =>
     guarded(async () => {
-      if (clipboard.length === 0) return ok('The clipboard is empty.')
-      return ok(`Clipboard holds ${describe(clipboard)}.\n\nPreview:\n${preview(clipboard)}`)
+      if (slot !== undefined) {
+        const clip = slots.get(slot)
+        if (clip === undefined || clip.length === 0) return ok(`Slot "${slot}" is empty.`)
+        return ok(`Slot "${slot}" holds ${describe(clip)}.\n\nPreview:\n${preview(clip)}`)
+      }
+      if (slots.size === 0) return ok('The clipboard is empty — no slots hold text.')
+      return ok(`Slots holding text: ${slotList()}. Pass a slot name to peek to see its contents.`)
     }),
 )