things-api 0.14.0 → 0.16.0

package/dist/mcp/server.js

@@ -327,6 +327,17 @@ const MCP_UNTAGGED_CONFLICT = "untagged does not combine with tag/exact_tag";
 const dryRunShape = {
     dry_run: z.boolean().optional().describe("Preview the planned change without applying anything"),
 };
+const preserveModifiedShape = {
+    preserve_modified: z
+        .boolean()
+        .optional()
+        .describe("Keep this change off the modification-date timeline: capture each pre-existing edited " +
+        "item's modification date and restore it (to the whole second) after the change, so a " +
+        "changes/watch query keyed on it does not surface the edit. A no-op on a pure create. " +
+        "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
+        "the item stays off the timeline everywhere — unless another device edits the same item " +
+        "at nearly the same time, which re-dates it."),
+};
 /**
  * The per-call idempotency key for a single write tool — the analogue of a batch
  * line's op_id. A resubmission carrying the same key is recognized as already
@@ -507,6 +518,7 @@ export function createThingsMcpServer(options = {}) {
         ...(args.allow_non_empty_area === true && { allowNonEmptyArea: true }),
         ...(args.dangerously_drive_gui === true && { dangerouslyDriveGui: true }),
         ...(args.create_tags === true && { createTags: true }),
+        ...(args.preserve_modified === true && { preserveModified: true }),
         ...(args.tz !== undefined && { zone: args.tz }),
         ...(args.op_id !== undefined && { opId: assertOpId(args.op_id) }),
     });
@@ -600,7 +612,10 @@ export function createThingsMcpServer(options = {}) {
         description: "Read a Things list as the app presents it: today (two children buckets — " +
             "children.today and children.evening, evening expires daily; the whole-view " +
             "count due/overdue vs. other rides the result's second block), inbox, anytime, " +
-            "upcoming, someday, logbook, or trash. For upcoming, " +
+            "upcoming, someday, logbook, trash, or deadlines (a flat items list of everything " +
+            "carrying a deadline — to-dos and projects — in deadline order, most-overdue first; " +
+            "repeating items appear at their next occurrence's projected deadline; scope with " +
+            "today/overdue/project/area/tag). For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
             "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
@@ -615,13 +630,30 @@ export function createThingsMcpServer(options = {}) {
             " " +
             REF_RULE_NOTE,
         inputSchema: {
-            view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
+            view: z.enum([
+                "today",
+                "inbox",
+                "anytime",
+                "upcoming",
+                "someday",
+                "logbook",
+                "trash",
+                "deadlines",
+            ]),
             ...tagFilterShape,
             ...tzShape,
             area: z
                 .string()
                 .optional()
-                .describe(`today/anytime/someday/upcoming/logbook only: ${AREA_FILTER_DESC}`),
+                .describe(`today/anytime/someday/upcoming/logbook/deadlines only: ${AREA_FILTER_DESC}`),
+            today: z
+                .boolean()
+                .optional()
+                .describe("deadlines only: keep only current Today members (This Evening included)"),
+            project: z
+                .string()
+                .optional()
+                .describe("deadlines only: restrict to one project's children (uuid or unique name)"),
             evening: z.boolean().optional().describe("today only: show only the This Evening section"),
             show_active_project_items: z
                 .union([z.boolean(), z.number().int().min(1)])
@@ -679,7 +711,7 @@ export function createThingsMcpServer(options = {}) {
             // (the current-work views), matching FILTER_CONTRACT.
             const validated = validateViewArgs(args.view, { ...tagPresence(args), overdue: args.overdue }, {
                 untaggedConflict: MCP_UNTAGGED_CONFLICT,
-                overdueRejected: `overdue applies to today/inbox/anytime/someday, not ${args.view}`,
+                overdueRejected: `overdue applies to today/inbox/anytime/someday/deadlines, not ${args.view}`,
                 overdueStatusWiden: "",
             });
             if (!validated.ok)
@@ -701,6 +733,14 @@ export function createThingsMcpServer(options = {}) {
             if (args.view !== "today" && args.evening === true) {
                 return usage(`evening applies only to today, not ${args.view}`);
             }
+            // The two deadlines-only scopes. `area`/`tag`/`overdue`/`limit` are
+            // shared with the other flat views; `today`/`project` are not.
+            if (args.view !== "deadlines" && args.today === true) {
+                return usage(`today applies only to deadlines, not ${args.view}`);
+            }
+            if (args.view !== "deadlines" && args.project !== undefined) {
+                return usage(`project applies only to deadlines, not ${args.view}`);
+            }
             // The `area` filter applies to the area-carrying views only; inbox
             // (area-less captures) and trash have no area to scope by.
             if ((args.view === "inbox" || args.view === "trash") && args.area !== undefined) {
@@ -786,19 +826,34 @@ export function createThingsMcpServer(options = {}) {
                     return groupedResult(withSectionTotals(shapeReadPayload("someday", view, full, c.refPromoter()), sectionTotals), truncation);
                 }
                 case "logbook": {
-                    const { items, truncation, filter: fm, } = c.read.logbook({
+                    const { items, truncation, logging, filter: fm, } = c.read.logbook({
                         ...filter,
                         ...zone,
                         ...area,
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("logbook", items, full, c.refPromoter()), truncation);
+                    // The log-move cadence fact rides the metadata block (the CLI
+                    // meta.logging analog, exactly as today's counts do).
+                    return truncatedResult(shapeReadPayload("logbook", items, full, c.refPromoter()), truncation, { logging });
                 }
                 case "trash": {
                     const { items, truncation } = c.read.trash({ ...zone, limit });
                     return truncatedResult(shapeReadPayload("trash", items, full, c.refPromoter()), truncation);
                 }
+                case "deadlines": {
+                    // `project`/`area` scope inside the view (SQL), not the shared
+                    // area post-filter — so no `meta.filter` here (parity with search).
+                    const { items, truncation } = c.read.deadlines({
+                        ...filter,
+                        ...zone,
+                        ...(args.today === true && { todayOnly: true }),
+                        ...(args.project !== undefined && { project: args.project }),
+                        ...(args.area !== undefined && { area: args.area }),
+                        limit,
+                    });
+                    return truncatedResult(shapeReadPayload("deadlines", items, full, c.refPromoter()), truncation);
+                }
             }
         }, args.tz, () => (filterMeta !== undefined ? { filter: filterMeta } : undefined), () => looseAreaWarnings(getClient(), args.area));
     });
@@ -1094,6 +1149,7 @@ export function createThingsMcpServer(options = {}) {
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -1171,6 +1227,7 @@ export function createThingsMcpServer(options = {}) {
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -1286,6 +1343,7 @@ export function createThingsMcpServer(options = {}) {
                 .describe(`status completed or canceled: the completion timestamp (${RESOLUTION_DATE_FORMAT})`),
             ...tzShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -1380,6 +1438,7 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("Confirm moving into a completed/canceled project (this reopens it)"),
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1425,6 +1484,7 @@ export function createThingsMcpServer(options = {}) {
             mode: z.enum(["replace", "add"]).optional().describe("Default: replace"),
             ...createTagsShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -1483,6 +1543,7 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("replace: confirm discarding the existing items and their checked states"),
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1558,6 +1619,7 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("kind tag: confirm permanent deletion of ALL nested child tags too"),
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: DESTRUCTIVE,
@@ -1579,7 +1641,7 @@ export function createThingsMcpServer(options = {}) {
         description: "Restore a trashed to-do or project. A to-do returns to the Inbox without its " +
             "previous schedule or project/area. A project is restored in place: its schedule, " +
             "area, and children come back exactly as they were.",
-        inputSchema: { uuid: z.string(), ...dryRunShape, ...opIdShape },
+        inputSchema: { uuid: z.string(), ...dryRunShape, ...preserveModifiedShape, ...opIdShape },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
         const c = getClient();
@@ -1666,6 +1728,7 @@ export function createThingsMcpServer(options = {}) {
                 .describe("add/move: place immediately after this heading (title or uuid)"),
             ...driveGuiShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1766,6 +1829,7 @@ export function createThingsMcpServer(options = {}) {
             uuid: z.string().describe("the to-do's uuid"),
             ...driveGuiShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: DESTRUCTIVE,
@@ -1775,7 +1839,7 @@ export function createThingsMcpServer(options = {}) {
             "Things proxy shortcuts when installed (in place, and the only path for a repeating " +
             "to-do); otherwise a non-repeating dated to-do falls back to a URL re-schedule that " +
             "briefly moves it to Today and back. Reversible with the undo tool.",
-        inputSchema: { uuid: z.string(), ...dryRunShape },
+        inputSchema: { uuid: z.string(), ...dryRunShape, ...preserveModifiedShape },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.clearReminder(args.uuid, writeOptions(args)))));
     // -------------------------------------------- GUI-driven (Accessibility)
@@ -1859,16 +1923,17 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("repeat", {
         description: "Manage recurrence on a to-do or project (scope) by driving the local Things app's " +
             "interface — every action needs dangerously_drive_gui. action start: turn a plain item " +
-            "into a repeating one — this REPLACES it with a new series and cannot be undone (give " +
-            "frequency + interval and optionally the weekday set, monthly/yearly day, end bound, " +
-            "reminder, or per-occurrence deadline); returns a repeating block with instanceUuid (the " +
-            "visible occurrence), templateUuid (the rule), and replacedUuid. action reschedule: " +
-            "change a repeating item's rule in place, keeping the same item (undoable — it restores " +
-            "the previous rule). action pause/resume: stop or restart its new occurrences, keeping " +
-            "the rule. action add (scope project only): create a project and make it repeating in " +
-            "one call — the project is created first and PERSISTS even if the make-repeating step " +
-            "refuses; give an area to place it or omit it to create in Someday (only frequency and " +
-            "interval are supported); returns the new project's uuid.",
+            "into a repeating one (promote-via-clone: a disposable copy is promoted and the ORIGINAL " +
+            "is moved to the Trash, so undo reverses it — it removes the new series and restores the " +
+            "original); give frequency + interval and optionally the weekday set, monthly/yearly day, " +
+            "end bound, or per-occurrence deadline; returns a repeating block with instanceUuid (the " +
+            "visible occurrence), templateUuid (the rule), and replacedUuid. A project holding a " +
+            "nested repeating template is refused. action reschedule: change a repeating item's rule " +
+            "in place, keeping the same item (undoable — it restores the previous rule). action " +
+            "pause/resume: stop or restart its new occurrences, keeping the rule. action add: create " +
+            "an item and make it repeating in one call — it is created first and PERSISTS even if the " +
+            "promote refuses (give a title; for a project give an area to place it or omit it to " +
+            "create in Someday); undo removes the created series. Returns the new template's uuid.",
         inputSchema: {
             scope: z.enum(["todo", "project"]),
             action: z.enum(["start", "reschedule", "pause", "resume", "add"]),
@@ -1876,13 +1941,13 @@ export function createThingsMcpServer(options = {}) {
                 .string()
                 .optional()
                 .describe("start/reschedule/pause/resume: the item (a project also accepts a unique name)"),
-            title: z.string().optional().describe("add (project): the new project's title"),
-            notes: z.string().optional().describe("add (project): notes"),
+            title: z.string().optional().describe("add: the new item's title"),
+            notes: z.string().optional().describe("add: notes"),
             area: z.string().optional().describe(`add (project): destination area (${REF_FORMAT})`),
             project_deadline: z
                 .string()
                 .optional()
-                .describe(`add (project): the project's due date — ${DATE_FORMAT}`),
+                .describe(`add: the item's due date — ${DATE_FORMAT}`),
             todos: z.array(z.string()).optional().describe("add (project): initial child to-do titles"),
             frequency: z
                 .enum(["daily", "weekly", "monthly", "yearly"])
@@ -1908,6 +1973,7 @@ export function createThingsMcpServer(options = {}) {
             start_days_earlier: repeatRuleShape.start_days_earlier,
             ...driveGuiShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1915,13 +1981,25 @@ export function createThingsMcpServer(options = {}) {
         const opts = writeOptions(args);
         const { frequency, interval } = args;
         if (args.action === "add") {
-            if (args.scope !== "project")
-                return usage('action "add" requires scope "project"');
             if (args.title === undefined)
                 return usage('action "add" requires title');
             if (frequency === undefined || interval === undefined) {
                 return usage('action "add" requires frequency and interval');
             }
+            // add-repeating carries only the calendar-anchor rule fields; the base
+            // add owns the item's own deadline, and the rule reminder/start-offset
+            // are set with a follow-up reschedule.
+            const { reminder: _reminder, deadline: _deadline, startDaysEarlier: _sde, ...ruleExtras } = repeatExtras(args, frequency);
+            if (args.scope === "todo") {
+                return mutationResult(await c.write.addRepeatingTodo({
+                    title: args.title,
+                    ...(args.notes !== undefined && { notes: args.notes }),
+                    ...(args.project_deadline !== undefined && { deadline: args.project_deadline }),
+                    frequency,
+                    interval,
+                    ...ruleExtras,
+                }, opts));
+            }
             return mutationResult(await c.write.addRepeatingProject({
                 title: args.title,
                 ...(args.notes !== undefined && { notes: args.notes }),
@@ -1930,6 +2008,7 @@ export function createThingsMcpServer(options = {}) {
                 ...(args.todos !== undefined && { todos: args.todos }),
                 frequency,
                 interval,
+                ...ruleExtras,
             }, opts));
         }
         if (args.uuid === undefined)
@@ -1950,8 +2029,10 @@ export function createThingsMcpServer(options = {}) {
         }
         const extras = repeatExtras(args, frequency);
         if (args.scope === "todo") {
-            const op = args.action === "start" ? "todo.make-repeating" : "todo.reschedule-repeat";
-            return mutationResult(await c.write.run(op, { uuid: args.uuid, frequency, interval, ...extras }, opts));
+            if (args.action === "start") {
+                return mutationResult(await c.write.makeRepeatingTodo(args.uuid, { frequency, interval, ...extras }, opts));
+            }
+            return mutationResult(await c.write.run("todo.reschedule-repeat", { uuid: args.uuid, frequency, interval, ...extras }, opts));
         }
         // scope project
         if (args.action === "reschedule") {
@@ -1963,7 +2044,7 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("duplicate_item", {
         description: "Duplicate a to-do or project and return the copy's uuid; a duplicated project " +
             "includes its children. Not available for repeating items.",
-        inputSchema: { uuid: z.string(), ...dryRunShape, ...opIdShape },
+        inputSchema: { uuid: z.string(), ...dryRunShape, ...preserveModifiedShape, ...opIdShape },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
         const c = getClient();
@@ -1971,6 +2052,42 @@ export function createThingsMcpServer(options = {}) {
             ? await c.write.duplicateTodo(args.uuid, writeOptions(args))
             : await c.write.duplicateProject(args.uuid, writeOptions(args)));
     }));
+    server.registerTool("clone_item", {
+        description: "Clone a to-do or project — a faithful content copy through official write surfaces and " +
+            "return the clone's uuid. Copies title, notes, tags, when, reminder, deadline, checklist " +
+            "items and their checked state, container, and completed/canceled state with the exact " +
+            "original timestamp; a project also copies its area, headings, and children. The clone is " +
+            "a new capture (a new uuid, created now, at its container's usual position). Refuses a " +
+            "trashed source and a project holding a nested repeating template. A repeating template is " +
+            "cloned as a NEW repeating series (its content plus the source's rule, minted fresh — no " +
+            "instances copied); this drives the app (requires dangerously_drive_gui) and refuses a " +
+            "rule the Repeat dialog cannot express. Undo trashes the clone (a template clone trashes " +
+            "the new series). Not the same as duplicate_item (Things' own native copy).",
+        inputSchema: {
+            uuid: z.string(),
+            title: z
+                .string()
+                .optional()
+                .describe("Give the clone a different title (default: the source's title)"),
+            preserve_created: z
+                .boolean()
+                .optional()
+                .describe("Copy the source's creation date onto the clone (minute resolution)"),
+            ...driveGuiShape,
+            ...dryRunShape,
+            ...opIdShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => {
+        const c = getClient();
+        const clone = {
+            ...(args.title !== undefined && { title: args.title }),
+            ...(args.preserve_created === true && { preserveCreated: true }),
+        };
+        return mutationResult(itemType(args.uuid) === "to-do"
+            ? await c.write.cloneTodo(args.uuid, clone, writeOptions(args))
+            : await c.write.cloneProject(args.uuid, clone, writeOptions(args)));
+    }));
     // -------------------------------------------------------------- projects
     server.registerTool("add_project", {
         description: "Create a project and return its uuid. Optionally place it in an area, schedule " +
@@ -1993,6 +2110,7 @@ export function createThingsMcpServer(options = {}) {
                 `(${RESOLUTION_DATE_FORMAT}); cannot seed open child to-dos`),
             ...tzShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -2024,6 +2142,7 @@ export function createThingsMcpServer(options = {}) {
             no_area: z.boolean().optional().describe("Leave the current area (a project's detach)"),
             ...positionShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -2052,6 +2171,7 @@ export function createThingsMcpServer(options = {}) {
             tags: z.array(z.string()).optional().describe(`Tags — ${TAG_REF_FORMAT}`),
             ...createTagsShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -2063,10 +2183,18 @@ export function createThingsMcpServer(options = {}) {
             title: z.string(),
             parent: z.string().optional().describe("Existing parent tag name"),
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addTag({ title: args.title, ...(args.parent !== undefined && { parent: args.parent }) }, writeOptions(args)))));
+    server.registerTool("log_now", {
+        description: "Move completed items to the Logbook now. The result discloses how many items were moved " +
+            "(observed.logged); when none are waiting it logs nothing — a clean no-op, not an error. " +
+            "This cannot be undone.",
+        inputSchema: { ...dryRunShape, ...preserveModifiedShape, ...opIdShape },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.logNow(writeOptions(args)))));
     // -------------------------------------------------- generic + discovery
     server.registerTool("run_operation", {
         description: "Run any cataloged operation by kind — the generic entry for operations without a " +
@@ -2092,22 +2220,28 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("area.delete: delete a non-empty area together with its contents"),
             ...dryRunShape,
+            ...preserveModifiedShape,
             ...opIdShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.run(args.op, args.params, writeOptions(args)))));
     server.registerTool("batch", {
         description: "Run several operations in order, each independently — there are no transactions, " +
-            "and a failure does not roll back earlier operations. Per-operation results return " +
-            "in order; fail_fast skips the remainder after the first failure. " +
+            "and a failure does not roll back earlier operations. A statically-invalid operation " +
+            "(bad shape, unknown op, a $ref to an undeclared/forward temp_id, a duplicate temp_id) " +
+            "refuses the WHOLE batch before anything runs, naming every bad operation. Otherwise " +
+            "per-operation results return in order. By DEFAULT a runtime failure STOPS the batch " +
+            "(later operations reported not-run, with resume guidance in the summary); " +
+            "continue_on_error runs past failures. " +
             "CHAINING: an operation that creates something may carry temp_id (a handle); a LATER " +
             'operation references that new uuid as "$handle" in any id/container field (dotted ' +
             '"$handle.instance"/"$handle.replaced" reach a repeating op\'s spawned instance / ' +
             "replaced source). A temp_id is valid only on a creating operation (not tag.add — " +
             "reference a tag by title) and unique per batch. IDEMPOTENCY: op_id makes resubmission " +
             "safe — an operation matching an earlier success is reported already-applied, not " +
-            "re-created. The result adds temp_id_mapping (handle → uuid) and undo_token, which " +
-            "reverses the whole batch as one unit via the undo tool.",
+            "re-created (put an op_id on EVERY operation so a stopped batch can be resubmitted " +
+            "verbatim to resume). The result adds temp_id_mapping (handle → uuid) and undo_token, " +
+            "which reverses the whole batch as one unit via the undo tool.",
         inputSchema: {
             ops: z
                 .array(z.object({
@@ -2133,8 +2267,12 @@ export function createThingsMcpServer(options = {}) {
                     .optional(),
             }))
                 .describe("Ops in execution order"),
-            fail_fast: z.boolean().optional().describe("Skip remaining ops after the first failure"),
+            continue_on_error: z
+                .boolean()
+                .optional()
+                .describe("Run past a failed op instead of stopping (default: stop on failure)"),
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -2163,7 +2301,7 @@ export function createThingsMcpServer(options = {}) {
         });
         const batchResult = await getClient().write.batch(ops, {
             ...(args.dry_run === true && { dryRun: true }),
-            ...(args.fail_fast === true && { failFast: true }),
+            ...(args.continue_on_error === true && { continueOnError: true }),
             actor: mcpActor(),
         });
         // First block: the per-op results, each FLATTENED to the wire shape (a
@@ -2172,7 +2310,9 @@ export function createThingsMcpServer(options = {}) {
         // chaining/undo summary, present only when the batch minted a token or
         // bound temp ids.
         const lines = batchResult.results.map(flattenBatchLine);
-        const hasSummary = batchResult.undoToken !== undefined || Object.keys(batchResult.tempIdMapping).length > 0;
+        const hasSummary = batchResult.undoToken !== undefined ||
+            batchResult.resumption !== undefined ||
+            Object.keys(batchResult.tempIdMapping).length > 0;
         if (!hasSummary)
             return jsonResult(lines);
         return {
@@ -2183,6 +2323,10 @@ export function createThingsMcpServer(options = {}) {
                     text: JSON.stringify({
                         tempIdMapping: batchResult.tempIdMapping,
                         ...(batchResult.undoToken !== undefined && { undoToken: batchResult.undoToken }),
+                        // Resume guidance when a runtime failure stopped the batch (Change 2).
+                        ...(batchResult.resumption !== undefined && {
+                            resumption: batchResult.resumption,
+                        }),
                     }),
                 },
             ],
@@ -2224,6 +2368,7 @@ export function createThingsMcpServer(options = {}) {
                 "day-block intermix both kinds."),
             ...driveGuiShape,
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -2242,9 +2387,14 @@ export function createThingsMcpServer(options = {}) {
             "cannot be undone here). By default this undoes only changes made through THIS " +
             "connection — this client's own writes; it will not touch the user's own edits, or " +
             'another client\'s, unless you pass by="*" (all authors) or a specific author name; ' +
-            "pass a txn token to undo one exact change. Some changes cannot be reversed — " +
-            "permanent deletions, or changes whose prior state is unknown — and are reported as " +
-            "irreversible; a to-do brought back from an undone delete returns to the Inbox " +
+            "pass a txn token to undo one exact change. last/by select the N newest NOT-YET-undone " +
+            "changes: a change already undone is SKIPPED, so repeating undo with last:N walks " +
+            "progressively deeper into history instead of re-selecting the same changes. An " +
+            "irreversible change is NOT skipped — it still counts toward N and is reported every " +
+            "pass, so you see it rather than silently reaching past it. Some changes cannot be " +
+            "reversed — permanent deletions, or changes whose prior state is unknown — and are " +
+            "reported as irreversible; a to-do brought back from an undone delete returns to the " +
+            "Inbox " +
             "without its schedule. Undoing the creation of an area or tag deletes it " +
             "permanently — requires dangerously_permanent. An undo is refused when the item " +
             "changed outside this interface since (its list or project, status, schedule, " +
@@ -2272,6 +2422,7 @@ export function createThingsMcpServer(options = {}) {
                 "or by another tool) — overwrites whatever the out-of-band change left, instead of " +
                 "refusing."),
             ...dryRunShape,
+            ...preserveModifiedShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {