@workser/engine 0.1.14 → 0.1.16

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.
package/README.md CHANGED
@@ -54,7 +54,7 @@ an engine too (`start`, `resume(state)`, `send`, `answer`, `stop`, `save`).
54
54
  ## Production pieces
55
55
 
56
56
  - `apply_patch` for GPT models (upstream's rule); `edit` + `write` for the rest.
57
- - A persistent shell: exported variables and the folder carry between `bash` calls.
57
+ - A persistent shell: exported variables carry between `bash` calls; every command starts in the project folder (or its `workdir`).
58
58
  - Streaming: `message.delta` events as the model writes.
59
59
  - Compaction: old tool output cleared, then the middle summarized, at 80 % of the context budget (`input.context_tokens`, default 128k).
60
60
  - Session mode (`mode: 'session'`) and `continue()` for a job restored from a checkpoint.
@@ -30,12 +30,43 @@ export interface CompactionBudget {
30
30
  * model could take: a 1M-window model would otherwise carry 800k a turn.
31
31
  */
32
32
  maxPromptTokens?: number;
33
+ /**
34
+ * Where a compaction lands, as a share of the point that triggered it (default `LOW_WATER_SHARE`). A prompt that
35
+ * stops just under its trigger crosses it again a call or two later, and every compaction rewrites history, which
36
+ * makes the provider re-read everything after the rewrite at the full uncached price (about 25 times the cached
37
+ * one on DeepSeek). Landing well below leaves room for many calls to append to a prompt that stays cached.
38
+ */
39
+ lowWaterShare?: number;
33
40
  }
34
41
  /** Where a job makes room at the latest (prompt diet, 1 Nov 2026): the same point Workser's other AI agents summarize at. */
35
42
  export declare const COST_COMPACT_TOKENS = 48000;
36
43
  export declare const DEFAULT_BUDGET: CompactionBudget;
37
44
  /** The prompt size (tokens) at which a turn makes room first. */
38
45
  export declare function compactAt(budget: CompactionBudget): number;
46
+ /**
47
+ * WHERE A COMPACTION LANDS (cache audit 2026-11-13, three real jobs on DeepSeek V4.1 Flash). The old rule pruned
48
+ * whatever had just aged out of the kept tool output each time the prompt reached `compactAt`. In a real job about
49
+ * 36k of a 52k prompt cannot be pruned (system prompt and goal 9.5k, the model's own tool-call inputs 17.8k, the route's
50
+ * tool definitions 8.5k) and 15k is the kept tool output, so the prompt sat above its trigger and every 2-3 calls one
51
+ * old tool result became a one-line note in the middle of the history. The summary never ran, because the messages
52
+ * alone (44.5k estimated) stayed under the trigger while the real prompt (53k) was over it. Each rewrite
53
+ * dropped the provider's cache from that message on (52k cached tokens fell to 20k): those calls were 58-65% of the
54
+ * jobs' provider cost. Now a compaction goes down to `lowWater` in one step, so the next one is about
55
+ * (compactAt - lowWater) / (tokens a turn adds) calls away, and between them the history only grows at its end.
56
+ */
57
+ export declare const LOW_WATER_SHARE = 0.65;
58
+ /** Room kept in the landing for the summary the model writes, in tokens. */
59
+ export declare const SUMMARY_ALLOWANCE_TOKENS = 3000;
60
+ /** The shortest recent tail a summary keeps, in tokens: the model's latest turns stay whole. */
61
+ export declare const MIN_TAIL_TOKENS = 4000;
62
+ /** The prompt size (tokens) a compaction goes down to. */
63
+ export declare function lowWater(budget: CompactionBudget): number;
64
+ /**
65
+ * How much recent conversation a summary keeps so the prompt lands at `lowWater`: what is left of it after the system
66
+ * prompt and the goal, whatever the real prompt carries beyond the messages (`overhead`: tool definitions and the
67
+ * route's own counting), and the summary itself.
68
+ */
69
+ export declare function tailBudget(messages: ChatMessage[], budget: CompactionBudget, overhead: number): number;
39
70
  export declare function estimateTokens(messages: ChatMessage[]): number;
40
71
  export declare function overBudget(messages: ChatMessage[], budget: CompactionBudget, reportedPromptTokens?: number): boolean;
41
72
  /** Step 1. Returns how many tool outputs were cleared (the array is changed in place). */
@@ -59,6 +90,23 @@ export declare function shortenOldArguments(messages: ChatMessage[], keepTokens:
59
90
  * the head and the tail to summarize.
60
91
  */
61
92
  export declare function cutPoint(messages: ChatMessage[], keepTokens: number): number;
93
+ /** What making room did to the conversation (see `makeRoom`). */
94
+ export interface RoomPlan {
95
+ /** Old tool results turned into a note, and old long inputs shortened (the messages were changed in place). */
96
+ cleared: number;
97
+ shortened: number;
98
+ /** Clearing alone brought the prompt down to the low water: nothing more to do. */
99
+ landed: boolean;
100
+ /** Otherwise: where the kept tail starts for the summary, or -1 when there is nothing to summarize. */
101
+ cut: number;
102
+ }
103
+ /**
104
+ * Step 1 and the decision on step 2, in one place so it can be tested without a model. `null` when the prompt is
105
+ * under its trigger. Otherwise old tool output is cleared and old inputs shortened, and the prompt is judged by what
106
+ * it will really be (the messages plus what the route counted beyond them, `reportedPromptTokens - estimate`): if
107
+ * that is at or under the low water the job is done, else the summary's kept tail is sized to land there.
108
+ */
109
+ export declare function makeRoom(messages: ChatMessage[], budget: CompactionBudget, reportedPromptTokens?: number): RoomPlan | null;
62
110
  /** The request that asks the model to summarize the part being replaced. */
63
111
  export declare function summaryRequest(part: ChatMessage[]): ChatMessage[];
64
112
  /** Step 2's result: the system prompt, the goal with the summary, then the kept tail. */
@@ -28,6 +28,36 @@ export const DEFAULT_BUDGET = {
28
28
  export function compactAt(budget) {
29
29
  return Math.min(budget.contextTokens * budget.threshold, budget.maxPromptTokens ?? Number.POSITIVE_INFINITY);
30
30
  }
31
+ /**
32
+ * WHERE A COMPACTION LANDS (cache audit 2026-11-13, three real jobs on DeepSeek V4.1 Flash). The old rule pruned
33
+ * whatever had just aged out of the kept tool output each time the prompt reached `compactAt`. In a real job about
34
+ * 36k of a 52k prompt cannot be pruned (system prompt and goal 9.5k, the model's own tool-call inputs 17.8k, the route's
35
+ * tool definitions 8.5k) and 15k is the kept tool output, so the prompt sat above its trigger and every 2-3 calls one
36
+ * old tool result became a one-line note in the middle of the history. The summary never ran, because the messages
37
+ * alone (44.5k estimated) stayed under the trigger while the real prompt (53k) was over it. Each rewrite
38
+ * dropped the provider's cache from that message on (52k cached tokens fell to 20k): those calls were 58-65% of the
39
+ * jobs' provider cost. Now a compaction goes down to `lowWater` in one step, so the next one is about
40
+ * (compactAt - lowWater) / (tokens a turn adds) calls away, and between them the history only grows at its end.
41
+ */
42
+ export const LOW_WATER_SHARE = 0.65;
43
+ /** Room kept in the landing for the summary the model writes, in tokens. */
44
+ export const SUMMARY_ALLOWANCE_TOKENS = 3_000;
45
+ /** The shortest recent tail a summary keeps, in tokens: the model's latest turns stay whole. */
46
+ export const MIN_TAIL_TOKENS = 4_000;
47
+ /** The prompt size (tokens) a compaction goes down to. */
48
+ export function lowWater(budget) {
49
+ const share = budget.lowWaterShare;
50
+ return Math.floor(compactAt(budget) * (typeof share === 'number' && share > 0 && share < 1 ? share : LOW_WATER_SHARE));
51
+ }
52
+ /**
53
+ * How much recent conversation a summary keeps so the prompt lands at `lowWater`: what is left of it after the system
54
+ * prompt and the goal, whatever the real prompt carries beyond the messages (`overhead`: tool definitions and the
55
+ * route's own counting), and the summary itself.
56
+ */
57
+ export function tailBudget(messages, budget, overhead) {
58
+ const head = estimateTokens(messages.slice(0, 2));
59
+ return Math.max(MIN_TAIL_TOKENS, lowWater(budget) - Math.max(0, overhead) - head - SUMMARY_ALLOWANCE_TOKENS);
60
+ }
31
61
  export function estimateTokens(messages) {
32
62
  let chars = 0;
33
63
  for (const message of messages) {
@@ -134,6 +164,22 @@ export function cutPoint(messages, keepTokens) {
134
164
  }
135
165
  return best;
136
166
  }
167
+ /**
168
+ * Step 1 and the decision on step 2, in one place so it can be tested without a model. `null` when the prompt is
169
+ * under its trigger. Otherwise old tool output is cleared and old inputs shortened, and the prompt is judged by what
170
+ * it will really be (the messages plus what the route counted beyond them, `reportedPromptTokens - estimate`): if
171
+ * that is at or under the low water the job is done, else the summary's kept tail is sized to land there.
172
+ */
173
+ export function makeRoom(messages, budget, reportedPromptTokens) {
174
+ if (!overBudget(messages, budget, reportedPromptTokens))
175
+ return null;
176
+ const overhead = Math.max(0, (reportedPromptTokens ?? 0) - estimateTokens(messages));
177
+ const cleared = pruneToolOutputs(messages, budget.keepToolTokens);
178
+ const shortened = shortenOldArguments(messages, budget.keepToolTokens);
179
+ if (estimateTokens(messages) + overhead <= lowWater(budget))
180
+ return { cleared, shortened, landed: true, cut: -1 };
181
+ return { cleared, shortened, landed: false, cut: cutPoint(messages, tailBudget(messages, budget, overhead)) };
182
+ }
137
183
  /** The request that asks the model to summarize the part being replaced. */
138
184
  export function summaryRequest(part) {
139
185
  const transcript = part
@@ -2,6 +2,7 @@ import type { Ask, AskResult, Engine, EngineEmit, EngineOutcome, EngineSessionSt
2
2
  import { CoreSession, type CoreSessionOptions } from './session.js';
3
3
  import { type KeyRelay } from './tools/relay.js';
4
4
  import { type ToolsClient } from './tools/workser-tool.js';
5
+ import { type FileClient } from './tools/publish.js';
5
6
  export interface CoreEngineOptions {
6
7
  modelBaseUrl: string;
7
8
  modelKey: string | (() => string);
@@ -39,7 +40,7 @@ export declare class CoreEngine implements Engine {
39
40
  private begin;
40
41
  }
41
42
  /** Anything with the RunnerClient methods the engine uses. */
42
- export interface RunnerLike extends Partial<ToolsClient> {
43
+ export interface RunnerLike extends Partial<ToolsClient>, Partial<FileClient> {
43
44
  emit(type: string, data?: Record<string, unknown>): void;
44
45
  ask(ask: Ask): Promise<AskResult>;
45
46
  commands(handler: (command: RunnerCommand) => void | Promise<void>): Promise<void>;
@@ -2,6 +2,7 @@ import { CoreSession, ENGINE_NAME } from './session.js';
2
2
  import { withCommandEnv } from './place/env.js';
3
3
  import { vaultFetchTool } from './tools/relay.js';
4
4
  import { workserTool } from './tools/workser-tool.js';
5
+ import { publishFileTool } from './tools/publish.js';
5
6
  /** The first prompt of a job, from its brief (same fields the runner reads). */
6
7
  export function promptOf(brief) {
7
8
  const input = brief.run.input ?? {};
@@ -133,6 +134,10 @@ export function serviceExtras(input) {
133
134
  'If your list has inbox_read, sms_read and account_save, you have your own email address or number: use them to sign up to a service for the work you were assigned. ' +
134
135
  'Ask the owner first (the first call does), sign up with your own address or number only, wait for the code, then save the account.');
135
136
  }
137
+ if (typeof client.uploadFile === 'function') {
138
+ extraTools.push(publishFileTool(client));
139
+ notes.push('Something made for the owner (a document, a spreadsheet, a PDF, an export) is not part of the app: make it in the .workser-out/ folder and hand it over with publish_file. Never put it in the app\'s own folders or commit it.');
140
+ }
136
141
  return {
137
142
  ...(extraTools.length ? { extraTools } : {}),
138
143
  ...(notes.length ? { extraPrompt: notes.join('\n\n') } : {}),
@@ -1,5 +1,5 @@
1
1
  export { CoreEngine, runEngine, promptOf, serviceExtras, type CoreEngineOptions, type RunEngineInput, type RunnerLike } from './engine.js';
2
- export { CoreSession, ENGINE_NAME, type CoreSessionOptions } from './session.js';
2
+ export { CoreSession, ENGINE_NAME, READ_ONLY_NUDGE, READ_ONLY_TURNS, usageEvent, type CoreSessionOptions } from './session.js';
3
3
  export { LocalPlace } from './place/local.js';
4
4
  export { E2BPlace, connectE2BPlace, type E2BSandboxLike } from './place/e2b.js';
5
5
  export { OPENCODE_VERSION } from './vendor.js';
@@ -7,8 +7,9 @@ export { providerPrompt, environmentPrompt, bashDescription } from './prompts.js
7
7
  export { needsAsk } from './tools/shell.js';
8
8
  export { ShellSession } from './tools/shell.js';
9
9
  export { applyPatchTool, parsePatch, applyChunks, usesPatch, PatchError } from './tools/patch.js';
10
- export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, PRUNED_NOTE, type CompactionBudget, } from './compact.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, PRUNED_NOTE, type CompactionBudget, } from './compact.js';
11
11
  export { vaultFetchTool, type KeyRelay } from './tools/relay.js';
12
12
  export { workserTool, type ToolsClient } from './tools/workser-tool.js';
13
+ export { publishFileTool, mimeOf, MAX_PUBLISH_BYTES, type FileClient } from './tools/publish.js';
13
14
  export { withCommandEnv } from './place/env.js';
14
15
  export { repairArgs, parseLoose, TOOL_ALIASES, type Repaired } from './tools/repair.js';
package/dist/src/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export { CoreEngine, runEngine, promptOf, serviceExtras } from './engine.js';
2
- export { CoreSession, ENGINE_NAME } from './session.js';
2
+ export { CoreSession, ENGINE_NAME, READ_ONLY_NUDGE, READ_ONLY_TURNS, usageEvent } from './session.js';
3
3
  export { LocalPlace } from './place/local.js';
4
4
  export { E2BPlace, connectE2BPlace } from './place/e2b.js';
5
5
  export { OPENCODE_VERSION } from './vendor.js';
@@ -7,8 +7,9 @@ export { providerPrompt, environmentPrompt, bashDescription } from './prompts.js
7
7
  export { needsAsk } from './tools/shell.js';
8
8
  export { ShellSession } from './tools/shell.js';
9
9
  export { applyPatchTool, parsePatch, applyChunks, usesPatch, PatchError } from './tools/patch.js';
10
- export { DEFAULT_BUDGET, COST_COMPACT_TOKENS, compactAt, estimateTokens, pruneToolOutputs, shortenOldArguments, cutPoint, withSummary, PRUNED_NOTE, } from './compact.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, PRUNED_NOTE, } from './compact.js';
11
11
  export { vaultFetchTool } from './tools/relay.js';
12
12
  export { workserTool } from './tools/workser-tool.js';
13
+ export { publishFileTool, mimeOf, MAX_PUBLISH_BYTES } from './tools/publish.js';
13
14
  export { withCommandEnv } from './place/env.js';
14
15
  export { repairArgs, parseLoose, TOOL_ALIASES } from './tools/repair.js';
@@ -33,6 +33,12 @@ export interface ChatResult {
33
33
  prompt_tokens?: number;
34
34
  completion_tokens?: number;
35
35
  cost?: number;
36
+ prompt_tokens_details?: {
37
+ cached_tokens?: number;
38
+ };
39
+ completion_tokens_details?: {
40
+ reasoning_tokens?: number;
41
+ };
36
42
  };
37
43
  }
38
44
  export declare class ModelError extends Error {
@@ -1,4 +1,5 @@
1
1
  import type { EngineEmit, EngineOutcome, EngineSession, EngineSessionState, Place, RunBrief, RunnerCommand, Ask, AskResult } from '@workser/runtime';
2
+ import { type ChatResult } from './model.js';
2
3
  import { type CompactionBudget } from './compact.js';
3
4
  import { type ToolSpec } from './tools/types.js';
4
5
  export declare const ENGINE_NAME = "workser-core";
@@ -63,10 +64,15 @@ export declare class CoreSession implements EngineSession {
63
64
  private finished;
64
65
  private turn;
65
66
  private stepSeq;
67
+ /** Turns in a row that changed no file (`READ_ONLY_NUDGE`), and whether this one did. */
68
+ private turnsWithoutChange;
69
+ private changedThisTurn;
66
70
  private root;
67
71
  private shell;
68
72
  private lastPromptTokens;
69
73
  private compactions;
74
+ /** Turns to wait before trying to make room again after a summary that failed (each try is a paid model call). */
75
+ private compactCooldown;
70
76
  constructor(options: CoreSessionOptions);
71
77
  /** The id `engine.session` names, so a restarted runner can resume this job. */
72
78
  get id(): string;
@@ -111,7 +117,22 @@ export declare class CoreSession implements EngineSession {
111
117
  private compactIfNeeded;
112
118
  private checkpoint;
113
119
  private runTool;
120
+ /**
121
+ * READ ENOUGH, NOW WRITE (owner 12 Nov trace: a job read and re-planned for 20 minutes, about 5k tokens of reasoning
122
+ * a turn, and changed no file). After `READ_ONLY_TURNS` turns in a row that changed no file, the last tool result
123
+ * of the turn carries one line saying so. Said again only after as many more such turns.
124
+ */
125
+ private nudgeIfOnlyReading;
114
126
  private context;
115
127
  }
116
128
  /** What an ask says the AI agent wants to do, by permission (`mcp`: a connected MCP server's tool, from the runner). */
117
129
  export declare function askVerb(permission: string): string;
130
+ /** Turns in a row with no file changed before the job is told to write. */
131
+ export declare const READ_ONLY_TURNS = 8;
132
+ export declare const READ_ONLY_NUDGE: string;
133
+ /**
134
+ * One model turn's use, as the `usage` event: tokens, the provider's charge, and (when the route says) the prompt
135
+ * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
136
+ * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
137
+ */
138
+ export declare function usageEvent(model: string, usage: NonNullable<ChatResult['usage']>): Record<string, unknown>;
@@ -3,7 +3,7 @@ import { environmentPrompt, providerPrompt } from './prompts.js';
3
3
  import { bashTool, ShellSession } from './tools/shell.js';
4
4
  import { editTool, readTool, todoWriteTool, writeTool } from './tools/files.js';
5
5
  import { applyPatchTool, usesPatch } from './tools/patch.js';
6
- import { DEFAULT_BUDGET, compactAt, cutPoint, overBudget, pruneToolOutputs, shortenOldArguments, summaryRequest, withSummary, } from './compact.js';
6
+ import { DEFAULT_BUDGET, makeRoom, summaryRequest, withSummary, } 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';
@@ -14,6 +14,8 @@ const DELTA_FLUSH_CHARS = 200;
14
14
  const DELTA_FLUSH_MS = 150;
15
15
  /** Thinking a turn may put on the event stream; the rest is dropped (the answer is not). */
16
16
  const REASONING_MAX_CHARS = 20_000;
17
+ /** After a summary that failed, turns to wait before trying again (each try is a paid model call). */
18
+ const COMPACT_RETRY_AFTER_TURNS = 5;
17
19
  /** Workser Code's default model (owner 2026-11-10); a job normally names its own (core picks it). Claude Sonnet 4.5 retires 30 Nov 2026. */
18
20
  const DEFAULT_MODEL = 'deepseek/deepseek-v4.1-flash-1017';
19
21
  const MAX_OUTPUT_IN_EVENT = 4_000;
@@ -43,10 +45,15 @@ export class CoreSession {
43
45
  finished = false;
44
46
  turn = 0;
45
47
  stepSeq = 0;
48
+ /** Turns in a row that changed no file (`READ_ONLY_NUDGE`), and whether this one did. */
49
+ turnsWithoutChange = 0;
50
+ changedThisTurn = false;
46
51
  root = '';
47
52
  shell;
48
53
  lastPromptTokens = 0;
49
54
  compactions = 0;
55
+ /** Turns to wait before trying to make room again after a summary that failed (each try is a paid model call). */
56
+ compactCooldown = 0;
50
57
  constructor(options) {
51
58
  this.options = options;
52
59
  this.done = new Promise((resolve) => (this.settle = resolve));
@@ -309,12 +316,7 @@ export class CoreSession {
309
316
  this.messages.push(result.message);
310
317
  this.lastPromptTokens = Number(result.usage?.prompt_tokens ?? 0);
311
318
  if (result.usage) {
312
- this.options.emit('usage', {
313
- model: this.model,
314
- tokens_in: Number(result.usage.prompt_tokens ?? 0),
315
- tokens_out: Number(result.usage.completion_tokens ?? 0),
316
- ...(typeof result.usage.cost === 'number' ? { cost_usd: result.usage.cost } : {}),
317
- });
319
+ this.options.emit('usage', usageEvent(this.model, result.usage));
318
320
  }
319
321
  if (result.message.content) {
320
322
  this.options.emit('message', {
@@ -328,11 +330,13 @@ export class CoreSession {
328
330
  await this.checkpoint();
329
331
  return;
330
332
  }
333
+ this.changedThisTurn = false;
331
334
  for (const call of calls) {
332
335
  if (this.finished)
333
336
  return;
334
337
  await this.runTool(call.id, call.function.name, call.function.arguments);
335
338
  }
339
+ this.nudgeIfOnlyReading();
336
340
  await this.checkpoint();
337
341
  }
338
342
  if (!this.finished) {
@@ -377,18 +381,22 @@ export class CoreSession {
377
381
  */
378
382
  async compactIfNeeded() {
379
383
  const budget = this.budget;
380
- if (!overBudget(this.messages, budget, this.lastPromptTokens))
384
+ if (this.compactCooldown > 0) {
385
+ this.compactCooldown--;
386
+ return;
387
+ }
388
+ // ONE STEP DOWN TO THE LOW WATER (compact.ts `makeRoom`): a compaction that stops just under its trigger is back at
389
+ // it a call later, and each one rewrites the history the provider has cached.
390
+ const plan = makeRoom(this.messages, budget, this.lastPromptTokens);
391
+ if (!plan)
381
392
  return;
382
- const cleared = pruneToolOutputs(this.messages, budget.keepToolTokens);
383
- const shortened = shortenOldArguments(this.messages, budget.keepToolTokens);
384
393
  this.lastPromptTokens = 0; // the reported size is of the old conversation
385
- if (!overBudget(this.messages, budget)) {
386
- if (cleared || shortened)
387
- this.options.emit('log', { level: 'info', text: `Cleared ${cleared} old tool results and shortened ${shortened} old inputs to keep the job small.` });
394
+ if (plan.landed) {
395
+ if (plan.cleared || plan.shortened)
396
+ this.options.emit('log', { level: 'info', text: `Cleared ${plan.cleared} old tool results and shortened ${plan.shortened} old inputs to keep the job small.` });
388
397
  return;
389
398
  }
390
- // The kept tail is well under the point, so the next turn does not summarize again at once.
391
- const cut = cutPoint(this.messages, Math.floor(compactAt(budget) * 0.4));
399
+ const cut = plan.cut;
392
400
  if (cut < 0)
393
401
  return;
394
402
  try {
@@ -402,25 +410,23 @@ export class CoreSession {
402
410
  ...(this.options.fetch ? { fetch: this.options.fetch } : {}),
403
411
  });
404
412
  const summary = result.message.content?.trim();
405
- if (!summary)
413
+ if (!summary) {
414
+ this.compactCooldown = COMPACT_RETRY_AFTER_TURNS;
406
415
  return;
416
+ }
407
417
  if (result.usage) {
408
- this.options.emit('usage', {
409
- model: this.model,
410
- tokens_in: Number(result.usage.prompt_tokens ?? 0),
411
- tokens_out: Number(result.usage.completion_tokens ?? 0),
412
- ...(typeof result.usage.cost === 'number' ? { cost_usd: result.usage.cost } : {}),
413
- });
418
+ this.options.emit('usage', usageEvent(this.model, result.usage));
414
419
  }
415
420
  const next = withSummary(this.messages, cut, summary);
416
421
  this.messages.splice(0, this.messages.length, ...next);
417
422
  this.compactions += 1;
418
- this.options.emit('log', { level: 'info', text: 'Summarized the earlier conversation to keep the job in the model\'s window.' });
423
+ this.options.emit('log', { level: 'info', text: "Summarized the earlier conversation to keep the job in the model's window." });
419
424
  await this.checkpoint();
420
425
  }
421
426
  catch (error) {
422
427
  if (this.finished)
423
428
  return;
429
+ this.compactCooldown = COMPACT_RETRY_AFTER_TURNS;
424
430
  this.options.emit('log', { level: 'warn', text: `Could not summarize the conversation: ${error?.message ?? error}` });
425
431
  }
426
432
  }
@@ -469,6 +475,8 @@ export class CoreSession {
469
475
  const result = await tool.execute(args, this.context());
470
476
  output = result.output;
471
477
  recorded = result.recorded;
478
+ if ((result.changed?.length ?? 0) > 0 || CHANGING_TOOLS.has(tool.name))
479
+ this.changedThisTurn = true;
472
480
  for (const changed of result.changed ?? []) {
473
481
  this.options.emit('file.changed', { path: relativeTo(this.root, changed.path), change: changed.change });
474
482
  }
@@ -494,6 +502,24 @@ export class CoreSession {
494
502
  duration_ms: Date.now() - started,
495
503
  });
496
504
  }
505
+ /**
506
+ * READ ENOUGH, NOW WRITE (owner 12 Nov trace: a job read and re-planned for 20 minutes, about 5k tokens of reasoning
507
+ * a turn, and changed no file). After `READ_ONLY_TURNS` turns in a row that changed no file, the last tool result
508
+ * of the turn carries one line saying so. Said again only after as many more such turns.
509
+ */
510
+ nudgeIfOnlyReading() {
511
+ if (this.changedThisTurn) {
512
+ this.turnsWithoutChange = 0;
513
+ return;
514
+ }
515
+ this.turnsWithoutChange += 1;
516
+ if (this.turnsWithoutChange < READ_ONLY_TURNS)
517
+ return;
518
+ this.turnsWithoutChange = 0;
519
+ const last = [...this.messages].reverse().find((one) => one.role === 'tool');
520
+ if (last && typeof last.content === 'string')
521
+ last.content = `${last.content}\n\n${READ_ONLY_NUDGE}`;
522
+ }
497
523
  context() {
498
524
  return {
499
525
  place: this.options.place,
@@ -553,3 +579,27 @@ function relativeTo(root, path) {
553
579
  const base = root.replace(/\/+$/, '');
554
580
  return path.startsWith(`${base}/`) ? path.slice(base.length + 1) : path;
555
581
  }
582
+ /** Tools that change a file in the job's folder (a turn with one is not "only reading"). */
583
+ const CHANGING_TOOLS = new Set(['write', 'edit', 'apply_patch']);
584
+ /** Turns in a row with no file changed before the job is told to write. */
585
+ export const READ_ONLY_TURNS = 8;
586
+ 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: ` +
587
+ "put your plan in todowrite once if it is not there yet, then write the code now, one file at a time, and run it after. " +
588
+ "Don't re-plan the whole task again each turn, and don't re-read files you have already read. If the task is only to look into something, say what you found.)";
589
+ /**
590
+ * One model turn's use, as the `usage` event: tokens, the provider's charge, and (when the route says) the prompt
591
+ * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
592
+ * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
593
+ */
594
+ export function usageEvent(model, usage) {
595
+ const cached = usage.prompt_tokens_details?.cached_tokens;
596
+ const reasoning = usage.completion_tokens_details?.reasoning_tokens;
597
+ return {
598
+ model,
599
+ tokens_in: Number(usage.prompt_tokens ?? 0),
600
+ tokens_out: Number(usage.completion_tokens ?? 0),
601
+ ...(typeof usage.cost === 'number' ? { cost_usd: usage.cost } : {}),
602
+ ...(typeof cached === 'number' ? { cached_tokens_in: cached } : {}),
603
+ ...(typeof reasoning === 'number' ? { reasoning_tokens: reasoning } : {}),
604
+ };
605
+ }
@@ -0,0 +1,20 @@
1
+ import type { ToolSpec } from './types.js';
2
+ /** The slice of the SDK's RunnerClient this uses: the run's own file upload (the file is registered on the run). */
3
+ export interface FileClient {
4
+ uploadFile(name: string, body: Uint8Array | string, options?: {
5
+ kind?: string;
6
+ mime?: string;
7
+ description?: string;
8
+ }): Promise<unknown>;
9
+ }
10
+ /** The most one published file may be (bytes). Bigger goes through the project's storage tools. */
11
+ export declare const MAX_PUBLISH_BYTES: number;
12
+ export declare function mimeOf(name: string): string;
13
+ /**
14
+ * HOW WORK LEAVES THE MACHINE (audit 2026-11-13). A job that made a document for the owner (a proposal, a price sheet,
15
+ * a report) had no way to hand it over: `save_to_project_files` and `publish_workspace_file` move bytes through the
16
+ * runner, which a loop outside the machine does not have, so two jobs searched the machine and the tool list for
17
+ * where to save, then shipped the files inside the app under `public/`, which the web app serves. This reads the file
18
+ * from the machine and uploads it as the run's own file, shown to the owner as a download.
19
+ */
20
+ export declare function publishFileTool(client: FileClient): ToolSpec;
@@ -0,0 +1,77 @@
1
+ import { absolute } from './types.js';
2
+ /** The most one published file may be (bytes). Bigger goes through the project's storage tools. */
3
+ export const MAX_PUBLISH_BYTES = 25 * 1024 * 1024;
4
+ const MIME = {
5
+ docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
6
+ xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
7
+ pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
8
+ pdf: 'application/pdf',
9
+ csv: 'text/csv',
10
+ txt: 'text/plain',
11
+ md: 'text/markdown',
12
+ json: 'application/json',
13
+ html: 'text/html',
14
+ png: 'image/png',
15
+ jpg: 'image/jpeg',
16
+ jpeg: 'image/jpeg',
17
+ webp: 'image/webp',
18
+ gif: 'image/gif',
19
+ svg: 'image/svg+xml',
20
+ mp4: 'video/mp4',
21
+ mov: 'video/quicktime',
22
+ mp3: 'audio/mpeg',
23
+ wav: 'audio/wav',
24
+ zip: 'application/zip',
25
+ };
26
+ export function mimeOf(name) {
27
+ const ext = name.split('.').pop()?.toLowerCase() ?? '';
28
+ return MIME[ext] ?? 'application/octet-stream';
29
+ }
30
+ /**
31
+ * HOW WORK LEAVES THE MACHINE (audit 2026-11-13). A job that made a document for the owner (a proposal, a price sheet,
32
+ * a report) had no way to hand it over: `save_to_project_files` and `publish_workspace_file` move bytes through the
33
+ * runner, which a loop outside the machine does not have, so two jobs searched the machine and the tool list for
34
+ * where to save, then shipped the files inside the app under `public/`, which the web app serves. This reads the file
35
+ * from the machine and uploads it as the run's own file, shown to the owner as a download.
36
+ */
37
+ export function publishFileTool(client) {
38
+ return {
39
+ name: 'publish_file',
40
+ description: 'Hand a finished file (a document, spreadsheet, PDF, set of pictures in a zip, an export) to the owner. It is attached to this job and shown to them as a download. ' +
41
+ 'Make the file in the .workser-out/ folder of this job (Workser keeps it out of git) and publish it from there: a file left in the app\'s own folders is part of the app and ships with it. ' +
42
+ 'Do not read a published file back to check it; say what you made and move on.',
43
+ parameters: {
44
+ type: 'object',
45
+ properties: {
46
+ path: { type: 'string', description: 'The file to publish, in this job\'s folder (for example .workser-out/Proposal.docx).' },
47
+ name: { type: 'string', description: 'The name the owner sees. Defaults to the file\'s own name.' },
48
+ description: { type: 'string', description: 'One short line on what it is, shown with the download.' },
49
+ },
50
+ required: ['path'],
51
+ },
52
+ async execute(args, ctx) {
53
+ const path = typeof args.path === 'string' ? args.path.trim() : '';
54
+ if (!path)
55
+ throw new Error('publish_file needs the path of the file.');
56
+ let bytes;
57
+ try {
58
+ bytes = await ctx.place.readFile(absolute(ctx.root, path));
59
+ }
60
+ catch (error) {
61
+ throw new Error(`Could not read ${path} on this machine (${String(error?.message ?? error).slice(0, 160)}). Make the file first, then publish it.`);
62
+ }
63
+ if (bytes.byteLength === 0)
64
+ throw new Error(`${path} is empty. Nothing was published.`);
65
+ if (bytes.byteLength > MAX_PUBLISH_BYTES) {
66
+ throw new Error(`${path} is ${(bytes.byteLength / 1_048_576).toFixed(1)} MB; the most one published file may be is ${MAX_PUBLISH_BYTES / 1_048_576} MB. Split it or zip it smaller.`);
67
+ }
68
+ const name = (typeof args.name === 'string' && args.name.trim() ? args.name.trim() : path.split('/').pop() ?? path).slice(0, 200);
69
+ await client.uploadFile(name, bytes, {
70
+ kind: 'file',
71
+ mime: mimeOf(name),
72
+ ...(typeof args.description === 'string' && args.description.trim() ? { description: args.description.trim().slice(0, 300) } : {}),
73
+ });
74
+ return { title: `published ${name}`, output: `Published ${name} (${bytes.byteLength} bytes). The owner gets it as a download on this job.` };
75
+ },
76
+ };
77
+ }
@@ -5,12 +5,15 @@ export declare function needsAsk(command: string): boolean;
5
5
  * commands"). Each `bash` call is still one `exec` — a Place has no PTY to
6
6
  * hold open, and a sandbox may be paused between calls — but the shell's
7
7
  * state rides between them: exported variables (`export`, `source
8
- * .venv/bin/activate`) and the working folder (`cd`) are written to a small
9
- * state folder on the machine when a command ends, and restored before the
10
- * next one. Functions and aliases are not kept.
8
+ * .venv/bin/activate`) are written to a small state folder on the machine
9
+ * when a command ends, and restored before the next one. Functions and
10
+ * aliases are not kept.
11
11
  *
12
- * A call with `workdir` runs there and leaves the kept folder alone, as
13
- * upstream's `workdir` means "for this command".
12
+ * THE FOLDER IS NOT KEPT (owner 12 Nov trace): every command starts in the
13
+ * project's folder, or in its `workdir`, as plain OpenCode's do. A job ran
14
+ * `cd node_modules/@workser/app/dist/resources` once, and every later
15
+ * `cat src/...` failed in that folder; it spent turns finding out why and
16
+ * reading everything again.
14
17
  */
15
18
  export declare class ShellSession {
16
19
  readonly id: string;
@@ -33,12 +33,15 @@ function tail(text) {
33
33
  * commands"). Each `bash` call is still one `exec` — a Place has no PTY to
34
34
  * hold open, and a sandbox may be paused between calls — but the shell's
35
35
  * state rides between them: exported variables (`export`, `source
36
- * .venv/bin/activate`) and the working folder (`cd`) are written to a small
37
- * state folder on the machine when a command ends, and restored before the
38
- * next one. Functions and aliases are not kept.
36
+ * .venv/bin/activate`) are written to a small state folder on the machine
37
+ * when a command ends, and restored before the next one. Functions and
38
+ * aliases are not kept.
39
39
  *
40
- * A call with `workdir` runs there and leaves the kept folder alone, as
41
- * upstream's `workdir` means "for this command".
40
+ * THE FOLDER IS NOT KEPT (owner 12 Nov trace): every command starts in the
41
+ * project's folder, or in its `workdir`, as plain OpenCode's do. A job ran
42
+ * `cd node_modules/@workser/app/dist/resources` once, and every later
43
+ * `cat src/...` failed in that folder; it spent turns finding out why and
44
+ * reading everything again.
42
45
  */
43
46
  export class ShellSession {
44
47
  id;
@@ -51,7 +54,6 @@ export class ShellSession {
51
54
  wrap(command, root, workdir) {
52
55
  const dir = quote(this.dir);
53
56
  const save = [
54
- workdir ? '' : `pwd > ${dir}/cwd`,
55
57
  // Everything exported, minus what bash sets itself.
56
58
  `export -p | grep -v -E '^declare -x (PWD|OLDPWD|SHLVL|_)(=|$)' > ${dir}/env.tmp 2>/dev/null && mv -f ${dir}/env.tmp ${dir}/env`,
57
59
  ]
@@ -60,9 +62,7 @@ export class ShellSession {
60
62
  return [
61
63
  `mkdir -p ${dir}`,
62
64
  `[ -f ${dir}/env ] && . ${dir}/env >/dev/null 2>&1`,
63
- workdir
64
- ? `cd ${quote(workdir)}`
65
- : `cd "$(cat ${dir}/cwd 2>/dev/null || echo ${quote(root)})" 2>/dev/null || cd ${quote(root)}`,
65
+ `cd ${quote(workdir ?? root)}`,
66
66
  // An EXIT trap, so `exit 3` in the command still saves the state.
67
67
  `trap '__ws_code=$?; ${save.replace(/'/g, `'\\''`)}; exit $__ws_code' EXIT`,
68
68
  command,
@@ -37,3 +37,15 @@ export interface ToolsClient {
37
37
  * id once the owner has said yes; until then core-api answers the same.
38
38
  */
39
39
  export declare function workserTool(client: ToolsClient): ToolSpec;
40
+ /**
41
+ * THE TOOL LIST, FINDABLE (owner 12 Nov trace: a job listed every tool four times, could not search the answer, and
42
+ * guessed `app_db_schema`, which doesn't exist, then wrote five scripts of its own instead of `app_db_query`). Each
43
+ * tool as its name, what it does in one line, and whether it changes something; `query` keeps the ones whose name or
44
+ * description has every word of it, each described in full.
45
+ */
46
+ export declare function listedTools<T extends {
47
+ name: string;
48
+ description?: string;
49
+ }>(tools: readonly T[], query: string): Array<T & {
50
+ description?: string;
51
+ }>;
@@ -12,13 +12,14 @@
12
12
  export function workserTool(client) {
13
13
  return {
14
14
  name: 'workser_tool',
15
- description: "Use Workser's tools and the project's connected apps. action 'list' shows the tools; action 'call' runs one by name. " +
15
+ description: "Use Workser's tools and the project's connected apps. action 'list' shows the tools (add query, e.g. \"db\", \"env\", \"payments\", to see only those); action 'call' runs one by name. " +
16
16
  "A tool that changes something outside this job, or spends money, needs the owner's yes first: you get approval_required " +
17
17
  'and an approval_id; call again with approval_id (and spend_approval_id for a spend over the limit) after they approve.',
18
18
  parameters: {
19
19
  type: 'object',
20
20
  properties: {
21
21
  action: { type: 'string', enum: ['list', 'call'] },
22
+ query: { type: 'string', description: "list: words to match in a tool's name or description (e.g. db, env, storage); omit for every tool" },
22
23
  name: { type: 'string', description: "The tool's name (for call)" },
23
24
  arguments: { type: 'object', description: "The tool's arguments (for call)" },
24
25
  approval_id: { type: 'string' },
@@ -30,7 +31,11 @@ export function workserTool(client) {
30
31
  async execute(args) {
31
32
  if (args.action === 'list') {
32
33
  const list = await client.listTools();
33
- return { title: `${list.tools.length} tools`, output: JSON.stringify(list, null, 2).slice(0, 50_000) };
34
+ const shown = listedTools(list.tools, typeof args.query === 'string' ? args.query : '');
35
+ return {
36
+ title: `${shown.length} tools`,
37
+ output: JSON.stringify({ ...list, tools: shown, ...(shown.length < list.tools.length ? { of: list.tools.length } : {}) }, null, 1).slice(0, 50_000),
38
+ };
34
39
  }
35
40
  if (args.action !== 'call' || typeof args.name !== 'string' || !args.name)
36
41
  throw new Error("action is 'list' or 'call' (call needs a name).");
@@ -49,3 +54,25 @@ export function workserTool(client) {
49
54
  },
50
55
  };
51
56
  }
57
+ /**
58
+ * THE TOOL LIST, FINDABLE (owner 12 Nov trace: a job listed every tool four times, could not search the answer, and
59
+ * guessed `app_db_schema`, which doesn't exist, then wrote five scripts of its own instead of `app_db_query`). Each
60
+ * tool as its name, what it does in one line, and whether it changes something; `query` keeps the ones whose name or
61
+ * description has every word of it, each described in full.
62
+ */
63
+ export function listedTools(tools, query) {
64
+ const words = query.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
65
+ const matching = words.length
66
+ ? tools.filter((tool) => {
67
+ const text = `${tool.name} ${tool.description ?? ''}`.toLowerCase();
68
+ return words.every((word) => text.includes(word));
69
+ })
70
+ : [...tools];
71
+ // A filtered list keeps each description whole (the few that matter); the whole list keeps one line each.
72
+ if (words.length)
73
+ return matching;
74
+ return matching.map((tool) => {
75
+ const first = String(tool.description ?? '').split(/(?<=\.)\s/)[0].slice(0, 200);
76
+ return { ...tool, ...(tool.description ? { description: first } : {}) };
77
+ });
78
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workser/engine",
3
- "version": "0.1.14",
3
+ "version": "0.1.16",
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",