@workser/engine 0.1.15 → 0.1.17

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.
@@ -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') } : {}),
@@ -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
@@ -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';
@@ -29,6 +29,8 @@ export interface ChatTool {
29
29
  export interface ChatResult {
30
30
  message: ChatMessage;
31
31
  finishReason: string | null;
32
+ /** Who served the call, when the route says (OpenRouter names it on every response). Cost audit 2026-11-13. */
33
+ provider?: string;
32
34
  usage?: {
33
35
  prompt_tokens?: number;
34
36
  completion_tokens?: number;
package/dist/src/model.js CHANGED
@@ -105,6 +105,7 @@ export async function chat(input) {
105
105
  : {}),
106
106
  },
107
107
  finishReason: choice.finish_reason ?? null,
108
+ ...(typeof body.provider === 'string' && body.provider ? { provider: body.provider } : {}),
108
109
  ...(body.usage ? { usage: body.usage } : {}),
109
110
  };
110
111
  }
@@ -126,6 +127,7 @@ async function readStream(body, onDelta, status, onReasoning) {
126
127
  let content = '';
127
128
  let finishReason = null;
128
129
  let usage;
130
+ let provider = '';
129
131
  const calls = [];
130
132
  let sawChoice = false;
131
133
  const handle = (data) => {
@@ -142,6 +144,8 @@ async function readStream(body, onDelta, status, onReasoning) {
142
144
  throw new ModelError(chunk.error.message ?? 'The model stream failed.', status);
143
145
  if (chunk?.usage)
144
146
  usage = chunk.usage;
147
+ if (typeof chunk?.provider === 'string' && chunk.provider)
148
+ provider = chunk.provider;
145
149
  const choice = chunk?.choices?.[0];
146
150
  if (!choice)
147
151
  return;
@@ -193,6 +197,7 @@ async function readStream(body, onDelta, status, onReasoning) {
193
197
  return {
194
198
  message: { role: 'assistant', content: content || null, ...(toolCalls.length ? { tool_calls: toolCalls } : {}) },
195
199
  finishReason,
200
+ ...(provider ? { provider } : {}),
196
201
  ...(usage ? { usage } : {}),
197
202
  };
198
203
  }
@@ -71,6 +71,8 @@ export declare class CoreSession implements EngineSession {
71
71
  private shell;
72
72
  private lastPromptTokens;
73
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;
74
76
  constructor(options: CoreSessionOptions);
75
77
  /** The id `engine.session` names, so a restarted runner can resume this job. */
76
78
  get id(): string;
@@ -133,4 +135,4 @@ export declare const READ_ONLY_NUDGE: string;
133
135
  * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
134
136
  * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
135
137
  */
136
- export declare function usageEvent(model: string, usage: NonNullable<ChatResult['usage']>): Record<string, unknown>;
138
+ export declare function usageEvent(model: string, usage: NonNullable<ChatResult['usage']>, provider?: string): 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;
@@ -50,6 +52,8 @@ export class CoreSession {
50
52
  shell;
51
53
  lastPromptTokens = 0;
52
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;
53
57
  constructor(options) {
54
58
  this.options = options;
55
59
  this.done = new Promise((resolve) => (this.settle = resolve));
@@ -312,7 +316,7 @@ export class CoreSession {
312
316
  this.messages.push(result.message);
313
317
  this.lastPromptTokens = Number(result.usage?.prompt_tokens ?? 0);
314
318
  if (result.usage) {
315
- this.options.emit('usage', usageEvent(this.model, result.usage));
319
+ this.options.emit('usage', usageEvent(this.model, result.usage, result.provider));
316
320
  }
317
321
  if (result.message.content) {
318
322
  this.options.emit('message', {
@@ -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,20 +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', usageEvent(this.model, result.usage));
418
+ this.options.emit('usage', usageEvent(this.model, result.usage, result.provider));
409
419
  }
410
420
  const next = withSummary(this.messages, cut, summary);
411
421
  this.messages.splice(0, this.messages.length, ...next);
412
422
  this.compactions += 1;
413
- 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." });
414
424
  await this.checkpoint();
415
425
  }
416
426
  catch (error) {
417
427
  if (this.finished)
418
428
  return;
429
+ this.compactCooldown = COMPACT_RETRY_AFTER_TURNS;
419
430
  this.options.emit('log', { level: 'warn', text: `Could not summarize the conversation: ${error?.message ?? error}` });
420
431
  }
421
432
  }
@@ -580,11 +591,14 @@ export const READ_ONLY_NUDGE = `(Workser: ${READ_ONLY_TURNS} turns in a row with
580
591
  * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
581
592
  * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
582
593
  */
583
- export function usageEvent(model, usage) {
594
+ export function usageEvent(model, usage, provider) {
584
595
  const cached = usage.prompt_tokens_details?.cached_tokens;
585
596
  const reasoning = usage.completion_tokens_details?.reasoning_tokens;
586
597
  return {
587
598
  model,
599
+ // Who served this call: a cache lives on one provider's machines, so a call that moved provider reads none of it
600
+ // (cost audit 2026-11-13: 10-18% of cache misses came with no change to the history).
601
+ ...(provider ? { provider } : {}),
588
602
  tokens_in: Number(usage.prompt_tokens ?? 0),
589
603
  tokens_out: Number(usage.completion_tokens ?? 0),
590
604
  ...(typeof usage.cost === 'number' ? { cost_usd: usage.cost } : {}),
@@ -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
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workser/engine",
3
- "version": "0.1.15",
3
+ "version": "0.1.17",
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",