@workser/engine 0.1.19 → 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -37,6 +37,11 @@ export interface CompactionBudget {
37
37
  * one on DeepSeek). Landing well below leaves room for many calls to append to a prompt that stays cached.
38
38
  */
39
39
  lowWaterShare?: number;
40
+ /**
41
+ * Clear out-of-date results (`tidyStale`) before a call once they add up to this many tokens, without waiting for
42
+ * the compaction. For models whose cached tokens are barely cheaper than fresh ones (Kimi); unset (off) by default.
43
+ */
44
+ tidyStaleTokens?: number;
40
45
  }
41
46
  /** Where a job makes room at the latest (prompt diet, 1 Nov 2026): the same point Workser's other AI agents summarize at. */
42
47
  export declare const COST_COMPACT_TOKENS = 48000;
@@ -85,6 +90,25 @@ export declare const WRITE_TOOLS: ReadonlySet<string>;
85
90
  export declare const OPEN_FILES_TOKENS = 20000;
86
91
  /** Step 0. Out-of-date reads become a one-line note (changed in place); returns how many. */
87
92
  export declare function dropSupersededReads(messages: ChatMessage[]): number;
93
+ /** Commands whose output is replaced when the same command is run again. */
94
+ export declare const RUN_TOOLS: ReadonlySet<string>;
95
+ /**
96
+ * What is out of date in the conversation, without changing it: reads a later read or change made stale (as
97
+ * `dropSupersededReads`), and the outputs of a command that was run again later word for word (trace 01a1e9fc: the
98
+ * job's own browser check, run 12 times, each 4k characters, every old run resent on every call).
99
+ */
100
+ export declare function staleResults(messages: ChatMessage[]): Array<{
101
+ message: ChatMessage;
102
+ note: string;
103
+ }>;
104
+ /**
105
+ * CLEAR WHAT IS OUT OF DATE AS SOON AS IT ADDS UP (owner 17 Nov: "optimize it more for Kimi"). Each call resends the whole
106
+ * conversation. On Kimi a cached token costs $0.18/1M against $0.253 fresh, so rewriting history costs one call about
107
+ * $0.003 more, while 6k tokens of stale output resent on the next twenty calls cost about $0.02. (On DeepSeek a cached
108
+ * token is about 1/50 of a fresh one, so there the rewrite costs more than it saves: the budget leaves this off.) Only
109
+ * what is out of date goes, so nothing the job still needs is lost. Returns how many results were cleared (in place).
110
+ */
111
+ export declare function tidyStale(messages: ChatMessage[], minTokens: number): number;
88
112
  /** The latest read of each file still as it was read (not changed since), newest first, within `maxTokens`. */
89
113
  export declare function openFiles(messages: ChatMessage[], maxTokens?: number): Array<{
90
114
  path: string;
@@ -82,7 +82,7 @@ export function overBudget(messages, budget, reportedPromptTokens) {
82
82
  * trigger and tell the job to write.
83
83
  */
84
84
  export const READ_TOOLS = new Set(['read']);
85
- export const WRITE_TOOLS = new Set(['write', 'edit', 'apply_patch']);
85
+ export const WRITE_TOOLS = new Set(['write', 'edit', 'multiedit', 'apply_patch']);
86
86
  /** The most of the open files' latest contents a summary carries, in tokens. */
87
87
  export const OPEN_FILES_TOKENS = 20_000;
88
88
  /** A tool call's file path (`filePath`, `path`, `file_path`), or null. */
@@ -156,6 +156,83 @@ export function dropSupersededReads(messages) {
156
156
  }
157
157
  return dropped;
158
158
  }
159
+ /** Commands whose output is replaced when the same command is run again. */
160
+ export const RUN_TOOLS = new Set(['bash']);
161
+ function commandOf(call) {
162
+ try {
163
+ const command = JSON.parse(call.function.arguments || '{}').command;
164
+ return typeof command === 'string' && command.trim() ? command.trim() : null;
165
+ }
166
+ catch {
167
+ return null;
168
+ }
169
+ }
170
+ /**
171
+ * What is out of date in the conversation, without changing it: reads a later read or change made stale (as
172
+ * `dropSupersededReads`), and the outputs of a command that was run again later word for word (trace 01a1e9fc: the
173
+ * job's own browser check, run 12 times, each 4k characters, every old run resent on every call).
174
+ */
175
+ export function staleResults(messages) {
176
+ const calls = callsById(messages);
177
+ const readLater = new Set();
178
+ const changedLater = new Set();
179
+ const ranLater = new Set();
180
+ const out = [];
181
+ for (let i = messages.length - 1; i >= 0; i--) {
182
+ const message = messages[i];
183
+ for (const call of message.tool_calls ?? []) {
184
+ if (WRITE_TOOLS.has(call.function.name)) {
185
+ const path = pathOfCall(call);
186
+ if (path)
187
+ changedLater.add(path);
188
+ }
189
+ }
190
+ if (message.role !== 'tool' || !message.tool_call_id || !message.content || message.content.startsWith('['))
191
+ continue;
192
+ const call = calls.get(message.tool_call_id);
193
+ if (!call)
194
+ continue;
195
+ if (RUN_TOOLS.has(call.function.name)) {
196
+ const command = commandOf(call);
197
+ if (!command)
198
+ continue;
199
+ if (ranLater.has(command))
200
+ out.push({ message, note: `[Old output: this command was run again later: ${command.slice(0, 80)}]` });
201
+ ranLater.add(command);
202
+ continue;
203
+ }
204
+ if (!READ_TOOLS.has(call.function.name))
205
+ continue;
206
+ const key = readKey(call);
207
+ const path = pathOfCall(call);
208
+ if (!key || !path)
209
+ continue;
210
+ if (readLater.has(key))
211
+ out.push({ message, note: `[Read again later: ${path}]` });
212
+ else if (changedLater.has(path))
213
+ out.push({ message, note: `[${path} was changed after this read]` });
214
+ readLater.add(key);
215
+ }
216
+ return out;
217
+ }
218
+ /**
219
+ * CLEAR WHAT IS OUT OF DATE AS SOON AS IT ADDS UP (owner 17 Nov: "optimize it more for Kimi"). Each call resends the whole
220
+ * conversation. On Kimi a cached token costs $0.18/1M against $0.253 fresh, so rewriting history costs one call about
221
+ * $0.003 more, while 6k tokens of stale output resent on the next twenty calls cost about $0.02. (On DeepSeek a cached
222
+ * token is about 1/50 of a fresh one, so there the rewrite costs more than it saves: the budget leaves this off.) Only
223
+ * what is out of date goes, so nothing the job still needs is lost. Returns how many results were cleared (in place).
224
+ */
225
+ export function tidyStale(messages, minTokens) {
226
+ if (!(minTokens > 0))
227
+ return 0;
228
+ const stale = staleResults(messages);
229
+ const tokens = stale.reduce((sum, one) => sum + Math.ceil((one.message.content ?? '').length / 4), 0);
230
+ if (tokens < minTokens)
231
+ return 0;
232
+ for (const one of stale)
233
+ one.message.content = one.note;
234
+ return stale.length;
235
+ }
159
236
  /** The latest read of each file still as it was read (not changed since), newest first, within `maxTokens`. */
160
237
  export function openFiles(messages, maxTokens = OPEN_FILES_TOKENS) {
161
238
  const calls = callsById(messages);
@@ -294,7 +371,7 @@ export function makeRoom(messages, budget, reportedPromptTokens) {
294
371
  return null;
295
372
  const overhead = Math.max(0, (reportedPromptTokens ?? 0) - estimateTokens(messages));
296
373
  // Out-of-date reads go first: the room they free loses nothing, and the newest read of each file outlives the prune.
297
- const superseded = dropSupersededReads(messages);
374
+ const superseded = dropSupersededReads(messages) + tidyStale(messages, 1);
298
375
  const cleared = pruneToolOutputs(messages, budget.keepToolTokens) + superseded;
299
376
  const shortened = shortenOldArguments(messages, budget.keepToolTokens);
300
377
  if (estimateTokens(messages) + overhead <= lowWater(budget))
@@ -15,6 +15,8 @@ export interface CoreEngineOptions {
15
15
  onTurnEnded?: (summary: string) => Promise<void> | void;
16
16
  stream?: boolean;
17
17
  budget?: CoreSessionOptions['budget'];
18
+ /** The model that writes the job's summaries (a cheap one); the job's own model when unset. */
19
+ summaryModel?: string;
18
20
  askFor?: string[];
19
21
  extraTools?: CoreSessionOptions['extraTools'];
20
22
  extraPrompt?: string;
@@ -52,6 +54,9 @@ export interface RunEngineInput {
52
54
  modelBaseUrl: string;
53
55
  modelKey: string | (() => string);
54
56
  model?: string;
57
+ /** The model that writes the job's summaries (see CoreSessionOptions.summaryModel). */
58
+ summaryModel?: string;
59
+ budget?: CoreSessionOptions['budget'];
55
60
  fetch?: typeof fetch;
56
61
  maxSteps?: number;
57
62
  state?: EngineSessionState;
@@ -59,6 +59,7 @@ export class CoreEngine {
59
59
  ...(this.options.onTurnEnded ? { onTurnEnded: this.options.onTurnEnded } : {}),
60
60
  ...(this.options.stream !== undefined ? { stream: this.options.stream } : {}),
61
61
  ...(this.options.budget ? { budget: this.options.budget } : {}),
62
+ ...(this.options.summaryModel ? { summaryModel: this.options.summaryModel } : {}),
62
63
  ...(this.options.askFor ? { askFor: this.options.askFor } : {}),
63
64
  ...(this.options.extraTools?.length ? { extraTools: this.options.extraTools } : {}),
64
65
  ...(this.options.extraPrompt ? { extraPrompt: this.options.extraPrompt } : {}),
@@ -84,6 +85,8 @@ export async function runEngine(input) {
84
85
  ask: (ask) => input.runnerClient.ask(ask),
85
86
  ...serviceExtras(input),
86
87
  ...(input.model ? { model: input.model } : {}),
88
+ ...(input.summaryModel ? { summaryModel: input.summaryModel } : {}),
89
+ ...(input.budget ? { budget: input.budget } : {}),
87
90
  ...(input.fetch ? { fetch: input.fetch } : {}),
88
91
  ...(input.maxSteps ? { maxSteps: input.maxSteps } : {}),
89
92
  ...(input.onCheckpoint ? { onCheckpoint: input.onCheckpoint } : {}),
@@ -6,8 +6,9 @@ export { OPENCODE_VERSION } from './vendor.js';
6
6
  export { providerPrompt, environmentPrompt, bashDescription } from './prompts.js';
7
7
  export { needsAsk } from './tools/shell.js';
8
8
  export { ShellSession } from './tools/shell.js';
9
+ export { editMissHint } from './tools/files.js';
9
10
  export { applyPatchTool, parsePatch, applyChunks, usesPatch, PatchError } from './tools/patch.js';
10
- export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, lowWater, tailBudget, makeRoom, type RoomPlan, LOW_WATER_SHARE, MIN_TAIL_TOKENS, SUMMARY_ALLOWANCE_TOKENS, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, summaryRequest, splitHead, dropSupersededReads, openFiles, READ_TOOLS, WRITE_TOOLS, OPEN_FILES_TOKENS, PRUNED_NOTE, type CompactionBudget, } from './compact.js';
11
+ export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, lowWater, tailBudget, makeRoom, type RoomPlan, LOW_WATER_SHARE, MIN_TAIL_TOKENS, SUMMARY_ALLOWANCE_TOKENS, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, summaryRequest, splitHead, dropSupersededReads, staleResults, tidyStale, RUN_TOOLS, openFiles, READ_TOOLS, WRITE_TOOLS, OPEN_FILES_TOKENS, PRUNED_NOTE, type CompactionBudget, } from './compact.js';
11
12
  export { vaultFetchTool, type KeyRelay } from './tools/relay.js';
12
13
  export { workserTool, type ToolsClient } from './tools/workser-tool.js';
13
14
  export { publishFileTool, mimeOf, MAX_PUBLISH_BYTES, type FileClient } from './tools/publish.js';
package/dist/src/index.js CHANGED
@@ -6,8 +6,9 @@ export { OPENCODE_VERSION } from './vendor.js';
6
6
  export { providerPrompt, environmentPrompt, bashDescription } from './prompts.js';
7
7
  export { needsAsk } from './tools/shell.js';
8
8
  export { ShellSession } from './tools/shell.js';
9
+ export { editMissHint } from './tools/files.js';
9
10
  export { applyPatchTool, parsePatch, applyChunks, usesPatch, PatchError } from './tools/patch.js';
10
- export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, lowWater, tailBudget, makeRoom, LOW_WATER_SHARE, MIN_TAIL_TOKENS, SUMMARY_ALLOWANCE_TOKENS, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, summaryRequest, splitHead, dropSupersededReads, openFiles, READ_TOOLS, WRITE_TOOLS, OPEN_FILES_TOKENS, PRUNED_NOTE, } from './compact.js';
11
+ export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, lowWater, tailBudget, makeRoom, LOW_WATER_SHARE, MIN_TAIL_TOKENS, SUMMARY_ALLOWANCE_TOKENS, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, summaryRequest, splitHead, dropSupersededReads, staleResults, tidyStale, RUN_TOOLS, openFiles, READ_TOOLS, WRITE_TOOLS, OPEN_FILES_TOKENS, PRUNED_NOTE, } from './compact.js';
11
12
  export { vaultFetchTool } from './tools/relay.js';
12
13
  export { workserTool } from './tools/workser-tool.js';
13
14
  export { publishFileTool, mimeOf, MAX_PUBLISH_BYTES } from './tools/publish.js';
@@ -12,6 +12,12 @@ export interface CoreSessionOptions {
12
12
  /** The run token — read on every call, so a rotation takes effect at once. */
13
13
  modelKey: string | (() => string);
14
14
  model?: string;
15
+ /**
16
+ * The model that writes the job's summaries (owner 17 Nov, trace 01a1e9c7: four summaries were 12k output tokens on
17
+ * Kimi at $8.80 a 1M). A summary is plain text work, so a cheap model does it; the job's own model when unset, and
18
+ * again when this one fails.
19
+ */
20
+ summaryModel?: string;
15
21
  /** Ask the owner (the runner's `ask`); the answer comes back through `answer()`. */
16
22
  ask?: (ask: Ask) => Promise<AskResult>;
17
23
  fetch?: typeof fetch;
@@ -121,6 +127,8 @@ export declare class CoreSession implements EngineSession {
121
127
  */
122
128
  private compactIfNeeded;
123
129
  private checkpoint;
130
+ /** Whether this exact text is still somewhere in the conversation (a tool result, or the summary's open files). */
131
+ private inConversation;
124
132
  private runTool;
125
133
  /**
126
134
  * READ ENOUGH, NOW WRITE (owner 12 Nov trace: a job read and re-planned for 20 minutes, about 5k tokens of reasoning
@@ -1,12 +1,14 @@
1
1
  import { chat, ModelError } from './model.js';
2
2
  import { environmentPrompt, providerPrompt } from './prompts.js';
3
3
  import { bashTool, ShellSession } from './tools/shell.js';
4
- import { editTool, readTool, todoWriteTool, writeTool } from './tools/files.js';
4
+ import { editTool, multiEditTool, readTool, todoWriteTool, writeTool } from './tools/files.js';
5
5
  import { applyPatchTool, usesPatch } from './tools/patch.js';
6
- import { DEFAULT_BUDGET, makeRoom, summaryRequest, splitHead, withSummary, WRITE_TOOLS, } from './compact.js';
6
+ import { DEFAULT_BUDGET, makeRoom, tidyStale, summaryRequest, splitHead, withSummary, WRITE_TOOLS, } from './compact.js';
7
7
  import { globTool, grepTool } from './tools/search.js';
8
8
  import { repairArgs, TOOL_ALIASES } from './tools/repair.js';
9
9
  import { PermissionDenied } from './tools/types.js';
10
+ /** A read this long or longer is checked against the conversation before it is sent again (a short one costs nothing). */
11
+ const SAME_READ_MIN_CHARS = 600;
10
12
  export const ENGINE_NAME = 'workser-core';
11
13
  const STATE_VERSION = 2;
12
14
  /** Deltas are sent in pieces of about this size or this often, not per token. */
@@ -109,7 +111,7 @@ export class CoreSession {
109
111
  const info = await this.options.place.info();
110
112
  this.root = info.root;
111
113
  // Upstream's rule: GPT models edit with apply_patch, everyone else with edit and write.
112
- const editing = usesPatch(this.model) ? [applyPatchTool] : [writeTool, editTool];
114
+ const editing = usesPatch(this.model) ? [applyPatchTool] : [writeTool, editTool, multiEditTool];
113
115
  this.tools.push(bashTool({ os: info.os, tmp: '/tmp', shell: this.shell }), readTool, ...editing, globTool, grepTool, todoWriteTool, ...(this.options.extraTools ?? []));
114
116
  if (this.messages.length === 0) {
115
117
  const isGit = (await this.options.place.exec('git rev-parse --is-inside-work-tree', { timeoutMs: 10_000 }))
@@ -394,6 +396,12 @@ export class CoreSession {
394
396
  }
395
397
  // ONE STEP DOWN TO THE LOW WATER (compact.ts `makeRoom`): a compaction that stops just under its trigger is back at
396
398
  // it a call later, and each one rewrites the history the provider has cached.
399
+ // Out-of-date results go once they add up, where rewriting history is cheap (compact.ts `tidyStale`).
400
+ const tidied = tidyStale(this.messages, budget.tidyStaleTokens ?? 0);
401
+ if (tidied) {
402
+ this.lastPromptTokens = 0; // the reported size is of the old conversation
403
+ this.options.emit('log', { level: 'info', text: `Cleared ${tidied} out-of-date tool results to keep the job small.` });
404
+ }
397
405
  const plan = makeRoom(this.messages, budget, this.lastPromptTokens);
398
406
  if (!plan)
399
407
  return;
@@ -410,22 +418,38 @@ export class CoreSession {
410
418
  const wrote = this.messages.slice(2).some((message) => (message.tool_calls ?? []).some((call) => WRITE_TOOLS.has(call.function.name)));
411
419
  const stalled = this.compactions > 0 && !wrote;
412
420
  try {
413
- const result = await chat({
421
+ const head = splitHead(this.messages[1]?.content);
422
+ const request = summaryRequest(this.messages.slice(2, cut), head.request, head.earlier);
423
+ const ask = (model) => chat({
414
424
  baseUrl: this.options.modelBaseUrl,
415
425
  key: this.key(),
416
- model: this.model,
417
- messages: summaryRequest(this.messages.slice(2, cut), splitHead(this.messages[1]?.content).request, splitHead(this.messages[1]?.content).earlier),
426
+ model,
427
+ messages: request,
418
428
  tools: [],
419
429
  signal: this.abort.signal,
420
430
  ...(this.options.fetch ? { fetch: this.options.fetch } : {}),
421
431
  });
432
+ const cheap = this.options.summaryModel?.trim();
433
+ let model = cheap && cheap !== this.model ? cheap : this.model;
434
+ let result;
435
+ try {
436
+ result = await ask(model);
437
+ if (!result.message.content?.trim() && model !== this.model)
438
+ throw new Error('empty summary');
439
+ }
440
+ catch (error) {
441
+ if (model === this.model || this.abort.signal.aborted)
442
+ throw error;
443
+ model = this.model;
444
+ result = await ask(model);
445
+ }
422
446
  const summary = result.message.content?.trim();
423
447
  if (!summary) {
424
448
  this.compactCooldown = COMPACT_RETRY_AFTER_TURNS;
425
449
  return;
426
450
  }
427
451
  if (result.usage) {
428
- this.options.emit('usage', usageEvent(this.model, result.usage, result.provider));
452
+ this.options.emit('usage', usageEvent(model, result.usage, result.provider));
429
453
  }
430
454
  this.stalls = stalled ? this.stalls + 1 : 0;
431
455
  const next = withSummary(this.messages, cut, summary, stalled
@@ -453,6 +477,10 @@ export class CoreSession {
453
477
  // A missed checkpoint costs a resume point, never the job.
454
478
  }
455
479
  }
480
+ /** Whether this exact text is still somewhere in the conversation (a tool result, or the summary's open files). */
481
+ inConversation(text) {
482
+ return this.messages.some((message) => typeof message.content === 'string' && message.content.includes(text));
483
+ }
456
484
  async runTool(callId, name, rawArgs) {
457
485
  const stepId = `s${++this.stepSeq}`;
458
486
  // A name from another harness runs the tool it means (tools/repair.ts), and the result says which one ran.
@@ -502,6 +530,15 @@ export class CoreSession {
502
530
  : `Error: ${error?.message ?? String(error)}`;
503
531
  }
504
532
  }
533
+ // THE SAME READ, ALREADY IN HAND (owner 17 Nov, trace 01a1e9c7: after a summary the job read six files again that
534
+ // the summary carried word for word, the prompt went back to 58k and made it summarize again seven calls later).
535
+ // The read still runs; only a result identical to a copy still in the conversation (an earlier read, or the open
536
+ // files a summary carries) becomes a note. A file changed in any way (an edit, a script, a formatter) comes back
537
+ // whole. The note starts with "[", so it never counts as a newer read (compact.ts) and the full copy stays.
538
+ if (status === 'ok' && tool?.name === 'read' && output.length >= SAME_READ_MIN_CHARS && this.inConversation(output)) {
539
+ const path = typeof args.filePath === 'string' ? args.filePath : 'this file';
540
+ output = `[Unchanged since you read it: ${path} is already in this conversation word for word (an earlier read, or the files you have open). Use that copy; read it again only after you change it.]`;
541
+ }
505
542
  if (notes.length)
506
543
  output = `${output}\n\n${notes.join('\n')}`;
507
544
  this.messages.push({ role: 'tool', tool_call_id: callId, content: output });
@@ -593,7 +630,7 @@ function relativeTo(root, path) {
593
630
  return path.startsWith(`${base}/`) ? path.slice(base.length + 1) : path;
594
631
  }
595
632
  /** Tools that change a file in the job's folder (a turn with one is not "only reading"). */
596
- const CHANGING_TOOLS = new Set(['write', 'edit', 'apply_patch']);
633
+ const CHANGING_TOOLS = new Set(['write', 'edit', 'multiedit', 'apply_patch']);
597
634
  /** Turns in a row with no file changed before the job is told to write. */
598
635
  export const READ_ONLY_TURNS = 8;
599
636
  export const READ_ONLY_NUDGE = `(Workser: ${READ_ONLY_TURNS} turns in a row without changing a file. If this task needs code, you have read enough: ` +
@@ -3,8 +3,23 @@ import { type ToolContext, type ToolSpec } from './types.js';
3
3
  export declare const readTool: ToolSpec;
4
4
  /** Upstream `write`: whole-file write; asks for the `edit` permission. */
5
5
  export declare const writeTool: ToolSpec;
6
+ /**
7
+ * A MISSED EDIT SAYS WHERE TO LOOK (owner 17 Nov, trace 01a1e9fc: on Kimi one multiedit was sent four times with the same
8
+ * wrong line, guessing `.slice(0, 1500)`, `4500`, `5000`, `4000` instead of re-reading; a 15-edit multiedit was lost to
9
+ * one line that matched twice). Every retry resends the whole job, so the error carries what the retry needs: the file's
10
+ * closest lines, numbered as `read` numbers them, or the lines where the text matched more than once.
11
+ */
12
+ export declare const HINT_MAX_LINES = 12;
13
+ /** The hint for an edit that did not apply, or '' when there is nothing useful to show. */
14
+ export declare function editMissHint(content: string, oldString: string, message: string): string;
6
15
  /** Upstream `edit`: oldString → newString with upstream's own matching (vendored). */
7
16
  export declare const editTool: ToolSpec;
17
+ /**
18
+ * SEVERAL CHANGES TO ONE FILE IN ONE CALL (owner 17 Nov, trace 01a1e9c7: eight edits to globals.css in eight calls, each
19
+ * resending the whole job; then the file was rewritten anyway). The edits apply in order, each to the result of the one
20
+ * before, with `edit`'s own matching; if any one fails, nothing is written and the error names it.
21
+ */
22
+ export declare const multiEditTool: ToolSpec;
8
23
  /** Upstream `todowrite`: the plan as a list; returned as JSON like upstream. */
9
24
  export declare const todoWriteTool: ToolSpec;
10
25
  /**
@@ -143,6 +143,85 @@ export const writeTool = {
143
143
  };
144
144
  },
145
145
  };
146
+ /**
147
+ * A MISSED EDIT SAYS WHERE TO LOOK (owner 17 Nov, trace 01a1e9fc: on Kimi one multiedit was sent four times with the same
148
+ * wrong line, guessing `.slice(0, 1500)`, `4500`, `5000`, `4000` instead of re-reading; a 15-edit multiedit was lost to
149
+ * one line that matched twice). Every retry resends the whole job, so the error carries what the retry needs: the file's
150
+ * closest lines, numbered as `read` numbers them, or the lines where the text matched more than once.
151
+ */
152
+ export const HINT_MAX_LINES = 12;
153
+ const HINT_LINE_CHARS = 240;
154
+ const words = (line) => line.toLowerCase().match(/[a-z0-9_$]+|[^\sa-z0-9_$]/g) ?? [];
155
+ /** How alike two lines are (0..1): shared words and marks over both lines' counts. */
156
+ function alike(a, b) {
157
+ const left = words(a);
158
+ const right = words(b);
159
+ if (!left.length || !right.length)
160
+ return 0;
161
+ const pool = new Map();
162
+ for (const w of right)
163
+ pool.set(w, (pool.get(w) ?? 0) + 1);
164
+ let shared = 0;
165
+ for (const w of left) {
166
+ const n = pool.get(w) ?? 0;
167
+ if (n > 0) {
168
+ shared++;
169
+ pool.set(w, n - 1);
170
+ }
171
+ }
172
+ return (2 * shared) / (left.length + right.length);
173
+ }
174
+ const numbered = (lines, from, to) => lines
175
+ .slice(from, to)
176
+ .map((line, i) => `${from + i + 1}: ${line.length > HINT_LINE_CHARS ? `${line.slice(0, HINT_LINE_CHARS)}…` : line}`)
177
+ .join('\n');
178
+ /** The hint for an edit that did not apply, or '' when there is nothing useful to show. */
179
+ export function editMissHint(content, oldString, message) {
180
+ const lines = content.split('\n');
181
+ if (/multiple matches/i.test(message)) {
182
+ const at = [];
183
+ for (let index = content.indexOf(oldString); index !== -1 && at.length < 8; index = content.indexOf(oldString, index + 1)) {
184
+ at.push(content.slice(0, index).split('\n').length);
185
+ }
186
+ return at.length > 1 ? `\nIt matches at lines ${at.join(', ')}: add a nearby line to oldString so only the one you mean matches.` : '';
187
+ }
188
+ if (!/could not find/i.test(message))
189
+ return '';
190
+ const wanted = oldString.split('\n');
191
+ // The search line: oldString's longest line (the most telling), and where it sits in oldString.
192
+ let key = 0;
193
+ wanted.forEach((line, i) => {
194
+ if (line.trim().length > wanted[key].trim().length)
195
+ key = i;
196
+ });
197
+ const keyLine = wanted[key].trim();
198
+ if (!keyLine)
199
+ return '';
200
+ let best = -1;
201
+ let score = 0;
202
+ lines.forEach((line, i) => {
203
+ const s = alike(keyLine, line.trim());
204
+ if (s > score) {
205
+ score = s;
206
+ best = i;
207
+ }
208
+ });
209
+ if (best < 0 || score < 0.4)
210
+ return '';
211
+ const span = Math.min(HINT_MAX_LINES, Math.max(1, wanted.length));
212
+ const from = Math.max(0, Math.min(best - key, lines.length - span));
213
+ return `\nThe closest text in the file (line ${best + 1}), as it is now:\n${numbered(lines, from, from + span)}\nCopy oldString from these lines exactly (without the line numbers), or read the file again.`;
214
+ }
215
+ /** `replace` whose error, when the text was not found or not unique, says where to look. */
216
+ function replaceOrHint(content, oldString, newString, replaceAll) {
217
+ try {
218
+ return replace(content, oldString, newString, replaceAll);
219
+ }
220
+ catch (error) {
221
+ const message = error?.message ?? String(error);
222
+ throw new Error(`${message}${editMissHint(content, oldString, message)}`);
223
+ }
224
+ }
146
225
  /** Upstream `edit`: oldString → newString with upstream's own matching (vendored). */
147
226
  export const editTool = {
148
227
  name: 'edit',
@@ -176,13 +255,79 @@ export const editTool = {
176
255
  const before = new TextDecoder().decode(await ctx.place.readFile(filepath));
177
256
  const ending = before.includes('\r\n') ? '\r\n' : '\n';
178
257
  const normal = before.replaceAll('\r\n', '\n');
179
- const after = replace(normal, oldString.replaceAll('\r\n', '\n'), newString.replaceAll('\r\n', '\n'), args.replaceAll === true);
258
+ const after = replaceOrHint(normal, oldString.replaceAll('\r\n', '\n'), newString.replaceAll('\r\n', '\n'), args.replaceAll === true);
180
259
  await ctx.ask({ permission: 'edit', title: `Edit ${filepath}`, detail: filepath, patterns: [filepath] });
181
260
  await ctx.place.writeFile(filepath, ending === '\r\n' ? after.replaceAll('\n', '\r\n') : after);
182
261
  ctx.read.add(filepath);
183
262
  return { title: filepath, output: 'Edit applied successfully.', changed: [{ path: filepath, change: 'modified' }] };
184
263
  },
185
264
  };
265
+ /**
266
+ * SEVERAL CHANGES TO ONE FILE IN ONE CALL (owner 17 Nov, trace 01a1e9c7: eight edits to globals.css in eight calls, each
267
+ * resending the whole job; then the file was rewritten anyway). The edits apply in order, each to the result of the one
268
+ * before, with `edit`'s own matching; if any one fails, nothing is written and the error names it.
269
+ */
270
+ export const multiEditTool = {
271
+ name: 'multiedit',
272
+ description: 'Make several changes to ONE file in one call: a list of edits applied in order, each to the result of the one before, ' +
273
+ 'all or nothing (if one fails, the file is left as it was and the error says which). Use it instead of several edit ' +
274
+ 'calls to the same file. Each edit works like edit: oldString must match the file exactly (whitespace and indentation ' +
275
+ 'included) and be unique unless replaceAll is set; read the file first. To change many files, call multiedit for each ' +
276
+ 'file in the same turn rather than one per turn.',
277
+ parameters: {
278
+ type: 'object',
279
+ properties: {
280
+ filePath: { type: 'string', description: 'The absolute path to the file to modify' },
281
+ edits: {
282
+ type: 'array',
283
+ minItems: 1,
284
+ description: 'The changes, applied in order',
285
+ items: {
286
+ type: 'object',
287
+ properties: {
288
+ oldString: { type: 'string', description: 'The text to replace' },
289
+ newString: { type: 'string', description: 'The text to replace it with (must be different from oldString)' },
290
+ replaceAll: { type: 'boolean', description: 'Replace all occurrences of oldString (default false)' },
291
+ },
292
+ required: ['oldString', 'newString'],
293
+ },
294
+ },
295
+ },
296
+ required: ['filePath', 'edits'],
297
+ },
298
+ async execute(args, ctx) {
299
+ const filepath = absolute(ctx.root, str(args.filePath, 'filePath'));
300
+ const edits = Array.isArray(args.edits) ? args.edits : [];
301
+ if (!edits.length)
302
+ throw new Error('No edits given: edits must list at least one change.');
303
+ const kind = await exists(ctx, filepath);
304
+ if (!kind)
305
+ throw new Error(`File ${filepath} not found`);
306
+ if (kind === 'dir')
307
+ throw new Error(`Path is a directory, not a file: ${filepath}`);
308
+ const before = new TextDecoder().decode(await ctx.place.readFile(filepath));
309
+ const ending = before.includes('\r\n') ? '\r\n' : '\n';
310
+ let text = before.replaceAll('\r\n', '\n');
311
+ edits.forEach((one, index) => {
312
+ const oldString = typeof one?.oldString === 'string' ? one.oldString : null;
313
+ const newString = typeof one?.newString === 'string' ? one.newString : null;
314
+ if (oldString === null || newString === null)
315
+ throw new Error(`Edit ${index + 1}: oldString and newString are required.`);
316
+ if (oldString === newString)
317
+ throw new Error(`Edit ${index + 1}: oldString and newString are identical.`);
318
+ try {
319
+ text = replaceOrHint(text, oldString.replaceAll('\r\n', '\n'), newString.replaceAll('\r\n', '\n'), one.replaceAll === true);
320
+ }
321
+ catch (error) {
322
+ throw new Error(`Edit ${index + 1} of ${edits.length} failed, so none were applied: ${error?.message ?? String(error)}`);
323
+ }
324
+ });
325
+ await ctx.ask({ permission: 'edit', title: `Edit ${filepath}`, detail: filepath, patterns: [filepath] });
326
+ await ctx.place.writeFile(filepath, ending === '\r\n' ? text.replaceAll('\n', '\r\n') : text);
327
+ ctx.read.add(filepath);
328
+ return { title: filepath, output: `${edits.length} edit${edits.length === 1 ? '' : 's'} applied successfully.`, changed: [{ path: filepath, change: 'modified' }] };
329
+ },
330
+ };
186
331
  /** Upstream `todowrite`: the plan as a list; returned as JSON like upstream. */
187
332
  export const todoWriteTool = {
188
333
  name: 'todowrite',
@@ -19,6 +19,8 @@ export const TOOL_ALIASES = {
19
19
  create_file: 'write',
20
20
  edit_file: 'edit',
21
21
  str_replace: 'edit',
22
+ multi_edit: 'multiedit',
23
+ MultiEdit: 'multiedit',
22
24
  search: 'grep',
23
25
  find_files: 'glob',
24
26
  todo_write: 'todowrite',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workser/engine",
3
- "version": "0.1.19",
3
+ "version": "0.1.22",
4
4
  "description": "Workser's coding engine for the 'loop in our service' mode: OpenCode's agent contract (its prompts, tool schemas and edit semantics, vendored from v1.19.5) running on Node, with every file and shell action going through a Place — so the machine can be a remote sandbox and no model key is ever on it.",
5
5
  "license": "MIT",
6
6
  "type": "module",