@workser/engine 0.1.14 → 0.1.15

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.
@@ -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';
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';
@@ -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,6 +64,9 @@ 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;
@@ -111,7 +115,22 @@ export declare class CoreSession implements EngineSession {
111
115
  private compactIfNeeded;
112
116
  private checkpoint;
113
117
  private runTool;
118
+ /**
119
+ * READ ENOUGH, NOW WRITE (owner 12 Nov trace: a job read and re-planned for 20 minutes, about 5k tokens of reasoning
120
+ * a turn, and changed no file). After `READ_ONLY_TURNS` turns in a row that changed no file, the last tool result
121
+ * of the turn carries one line saying so. Said again only after as many more such turns.
122
+ */
123
+ private nudgeIfOnlyReading;
114
124
  private context;
115
125
  }
116
126
  /** What an ask says the AI agent wants to do, by permission (`mcp`: a connected MCP server's tool, from the runner). */
117
127
  export declare function askVerb(permission: string): string;
128
+ /** Turns in a row with no file changed before the job is told to write. */
129
+ export declare const READ_ONLY_TURNS = 8;
130
+ export declare const READ_ONLY_NUDGE: string;
131
+ /**
132
+ * One model turn's use, as the `usage` event: tokens, the provider's charge, and (when the route says) the prompt
133
+ * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
134
+ * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
135
+ */
136
+ export declare function usageEvent(model: string, usage: NonNullable<ChatResult['usage']>): Record<string, unknown>;
@@ -43,6 +43,9 @@ export class CoreSession {
43
43
  finished = false;
44
44
  turn = 0;
45
45
  stepSeq = 0;
46
+ /** Turns in a row that changed no file (`READ_ONLY_NUDGE`), and whether this one did. */
47
+ turnsWithoutChange = 0;
48
+ changedThisTurn = false;
46
49
  root = '';
47
50
  shell;
48
51
  lastPromptTokens = 0;
@@ -309,12 +312,7 @@ export class CoreSession {
309
312
  this.messages.push(result.message);
310
313
  this.lastPromptTokens = Number(result.usage?.prompt_tokens ?? 0);
311
314
  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
- });
315
+ this.options.emit('usage', usageEvent(this.model, result.usage));
318
316
  }
319
317
  if (result.message.content) {
320
318
  this.options.emit('message', {
@@ -328,11 +326,13 @@ export class CoreSession {
328
326
  await this.checkpoint();
329
327
  return;
330
328
  }
329
+ this.changedThisTurn = false;
331
330
  for (const call of calls) {
332
331
  if (this.finished)
333
332
  return;
334
333
  await this.runTool(call.id, call.function.name, call.function.arguments);
335
334
  }
335
+ this.nudgeIfOnlyReading();
336
336
  await this.checkpoint();
337
337
  }
338
338
  if (!this.finished) {
@@ -405,12 +405,7 @@ export class CoreSession {
405
405
  if (!summary)
406
406
  return;
407
407
  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
- });
408
+ this.options.emit('usage', usageEvent(this.model, result.usage));
414
409
  }
415
410
  const next = withSummary(this.messages, cut, summary);
416
411
  this.messages.splice(0, this.messages.length, ...next);
@@ -469,6 +464,8 @@ export class CoreSession {
469
464
  const result = await tool.execute(args, this.context());
470
465
  output = result.output;
471
466
  recorded = result.recorded;
467
+ if ((result.changed?.length ?? 0) > 0 || CHANGING_TOOLS.has(tool.name))
468
+ this.changedThisTurn = true;
472
469
  for (const changed of result.changed ?? []) {
473
470
  this.options.emit('file.changed', { path: relativeTo(this.root, changed.path), change: changed.change });
474
471
  }
@@ -494,6 +491,24 @@ export class CoreSession {
494
491
  duration_ms: Date.now() - started,
495
492
  });
496
493
  }
494
+ /**
495
+ * READ ENOUGH, NOW WRITE (owner 12 Nov trace: a job read and re-planned for 20 minutes, about 5k tokens of reasoning
496
+ * a turn, and changed no file). After `READ_ONLY_TURNS` turns in a row that changed no file, the last tool result
497
+ * of the turn carries one line saying so. Said again only after as many more such turns.
498
+ */
499
+ nudgeIfOnlyReading() {
500
+ if (this.changedThisTurn) {
501
+ this.turnsWithoutChange = 0;
502
+ return;
503
+ }
504
+ this.turnsWithoutChange += 1;
505
+ if (this.turnsWithoutChange < READ_ONLY_TURNS)
506
+ return;
507
+ this.turnsWithoutChange = 0;
508
+ const last = [...this.messages].reverse().find((one) => one.role === 'tool');
509
+ if (last && typeof last.content === 'string')
510
+ last.content = `${last.content}\n\n${READ_ONLY_NUDGE}`;
511
+ }
497
512
  context() {
498
513
  return {
499
514
  place: this.options.place,
@@ -553,3 +568,27 @@ function relativeTo(root, path) {
553
568
  const base = root.replace(/\/+$/, '');
554
569
  return path.startsWith(`${base}/`) ? path.slice(base.length + 1) : path;
555
570
  }
571
+ /** Tools that change a file in the job's folder (a turn with one is not "only reading"). */
572
+ const CHANGING_TOOLS = new Set(['write', 'edit', 'apply_patch']);
573
+ /** Turns in a row with no file changed before the job is told to write. */
574
+ export const READ_ONLY_TURNS = 8;
575
+ 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: ` +
576
+ "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. " +
577
+ "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.)";
578
+ /**
579
+ * One model turn's use, as the `usage` event: tokens, the provider's charge, and (when the route says) the prompt
580
+ * tokens read from its cache and the hidden reasoning tokens. Owner 12 Nov: a trace showed no cache reads on
581
+ * 40–50k-token calls only because these counts were dropped here, so nobody could tell whether caching worked.
582
+ */
583
+ export function usageEvent(model, usage) {
584
+ const cached = usage.prompt_tokens_details?.cached_tokens;
585
+ const reasoning = usage.completion_tokens_details?.reasoning_tokens;
586
+ return {
587
+ model,
588
+ tokens_in: Number(usage.prompt_tokens ?? 0),
589
+ tokens_out: Number(usage.completion_tokens ?? 0),
590
+ ...(typeof usage.cost === 'number' ? { cost_usd: usage.cost } : {}),
591
+ ...(typeof cached === 'number' ? { cached_tokens_in: cached } : {}),
592
+ ...(typeof reasoning === 'number' ? { reasoning_tokens: reasoning } : {}),
593
+ };
594
+ }
@@ -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.15",
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",