@matatbread/matbot-background-jobs-node 0.4.18 → 0.5.0

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/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "matbotRuntime": [
4
4
  "node"
5
5
  ],
6
- "version": "0.4.18",
6
+ "version": "0.5.0",
7
7
  "engines": {
8
8
  "node": ">=24.0.0"
9
9
  },
@@ -32,15 +32,15 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
- "@matatbread/matbot-background-jobs": "^0.4.18"
35
+ "@matatbread/matbot-background-jobs": "^0.5.0"
36
36
  },
37
37
  "peerDependencies": {
38
- "@matatbread/matbot-plugin-api": "^0.4.18"
38
+ "@matatbread/matbot-plugin-api": "^0.5.0"
39
39
  },
40
40
  "devDependencies": {
41
41
  "@types/node": "^22.0.0",
42
42
  "typescript": "^6.0.3",
43
- "@matatbread/matbot-plugin-api": "^0.4.18"
43
+ "@matatbread/matbot-plugin-api": "^0.5.0"
44
44
  },
45
45
  "scripts": {
46
46
  "typecheck": "tsc --noEmit"
package/src/channel.ts CHANGED
@@ -64,22 +64,26 @@ export function serveJob(child: Endpoint, handlers: JobHandlers): void {
64
64
  });
65
65
  }
66
66
 
67
- // What a job may say: assistant text and nothing else. It speaks for itself — never as the user, and
68
- // never with metadata of its own, which the parent supplies.
67
+ // What a job may say: text, and nothing else. Either it speaks for itself (assistant), or it asks the
68
+ // conversation something (user — a robo-submit, which the parent's appender marks as one and runs as a
69
+ // turn). Never with metadata of its own, which the parent supplies, and never as a person: every block is
70
+ // `origin: 'robo'`.
69
71
  function jobText(raw: unknown): AppendMessage[] {
70
72
  if (!Array.isArray(raw) || raw.length === 0) throw new Error('Nothing to append.');
71
- return raw.map((m: unknown) => {
72
- const msg = m as { role?: unknown; content?: unknown };
73
- if (msg.role !== 'assistant') throw new Error('A background job may append only assistant messages.');
73
+ return raw.map((m: unknown): AppendMessage => {
74
+ const msg = m as { role?: unknown; content?: unknown; mode?: unknown };
75
+ if (msg.role !== 'assistant' && msg.role !== 'user') throw new Error('A background job may append only assistant or user messages.');
74
76
  if (!Array.isArray(msg.content) || msg.content.length === 0) throw new Error('An appended message needs content.');
75
- return {
76
- role: 'assistant',
77
- content: msg.content.map((c: unknown) => {
78
- const block = c as { type?: unknown; text?: unknown };
79
- if (block.type !== 'text' || typeof block.text !== 'string') throw new Error('An appended message may carry text only.');
80
- return { type: 'text' as const, text: block.text, origin: 'robo' as const };
81
- }),
82
- };
77
+ const content = msg.content.map((c: unknown) => {
78
+ const block = c as { type?: unknown; text?: unknown };
79
+ if (block.type !== 'text' || typeof block.text !== 'string') throw new Error('An appended message may carry text only.');
80
+ return { type: 'text' as const, text: block.text, origin: 'robo' as const };
81
+ });
82
+ if (msg.role === 'assistant') return { role: 'assistant', content };
83
+ if (msg.mode !== 'queue' && msg.mode !== 'parallel' && msg.mode !== 'interrupt') {
84
+ throw new Error('A user message is submitted as a turn, and needs a mode for meeting a running one: "queue", "parallel" or "interrupt".');
85
+ }
86
+ return { role: 'user', content, mode: msg.mode };
83
87
  });
84
88
  }
85
89
 
package/src/index.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  import { spawn, type ChildProcess } from 'node:child_process';
2
- import { execArgv, argv, execPath } from 'node:process';
2
+ import { execArgv, argv, execPath, env } from 'node:process';
3
3
  import { resolve, dirname } from 'node:path';
4
4
  import { existsSync } from 'node:fs';
5
5
  import { pathToFileURL } from 'node:url';
6
6
  import type { MatbotMachine, MatbotPluginSpec, AppendResult } from '@matatbread/matbot-plugin-api';
7
7
  import { ItemChangeKind } from '@matatbread/matbot-plugin-api';
8
8
  import {
9
- createBackgroundJobsPlugin, appendFor, jobContext, jobInfo, REPLY_TAIL,
9
+ createBackgroundJobsPlugin, appendFor, filterJobTriggers, jobContext, jobInfo, REPLY_TAIL,
10
10
  type JobInfo, type JobRunner, type RunOutcome, type RunSpec,
11
11
  } from '@matatbread/matbot-background-jobs';
12
12
  import { connectToParent, relayable, serveJob, type Endpoint, type ParentLink } from './channel.js';
@@ -16,6 +16,11 @@ import { connectToParent, relayable, serveJob, type Endpoint, type ParentLink }
16
16
  // that hangs or leaks can be killed outright, and nothing it does touches this process's heap — at the
17
17
  // cost of a whole boot per run. The child never writes a session itself; it asks over an IPC channel,
18
18
  // and what it changes elsewhere is announced back over the same channel.
19
+ //
20
+ // So its host is the matbot CLI, as docker-bash's is a machine with docker: a job is the CLI's own command
21
+ // line — the script this process was started as, `--config -`, a config extending the one this process
22
+ // booted with (which the CLI publishes as MATBOT_CONFIG), and the CLI's IS_SUB_AGENT/MATBOT_PRINCIPAL. Under
23
+ // any other host it disables itself; `matbot-background-jobs` runs jobs in-process anywhere.
19
24
 
20
25
  // When true, jobs run in a new process group and survive the parent exiting.
21
26
  const DETACH_JOBS = false;
@@ -78,10 +83,10 @@ export function superviseChild(child: ChildProcess, input: string): Promise<Erro
78
83
  }
79
84
 
80
85
  function spawnRunner(machine: MatbotMachine): JobRunner | undefined {
81
- const configPath = machine.configPath;
86
+ const configPath = env['MATBOT_CONFIG'];
82
87
  const script = argv[1];
83
88
  if (configPath === undefined || script === undefined) {
84
- console.warn('[background-jobs] no config path or entry script to spawn a job from, so no job can run here.');
89
+ console.warn('[background-jobs] this process is not the matbot CLI (no MATBOT_CONFIG, or no entry script), so it cannot start a job as one. Use matbot-background-jobs to run jobs in-process.');
85
90
  return undefined;
86
91
  }
87
92
 
@@ -116,7 +121,7 @@ function spawnRunner(machine: MatbotMachine): JobRunner | undefined {
116
121
  info: () => jobInfo(machine, job),
117
122
  append: async (sessionId, messages) => {
118
123
  const result = await appendFor(machine, job, sessionId, messages);
119
- appended += result.messageIds.length;
124
+ appended += result.traceId !== undefined ? 1 : result.messageIds.length; // a robo-submit is minted later
120
125
  return result;
121
126
  },
122
127
  notify: n => relay(machine, job, n),
@@ -169,6 +174,11 @@ async function setupJob(services: MatbotMachine, signal: AbortSignal): Promise<v
169
174
  }),
170
175
  });
171
176
  services.systemContext.register(() => jobContext(job));
177
+ // This process runs nothing but the job's turn, so every session it judges is the job's.
178
+ if (job.triggers !== undefined && job.triggers !== 'all') {
179
+ const triggers = job.triggers;
180
+ await filterJobTriggers(services, () => triggers);
181
+ }
172
182
  // What this job changes, announced where someone is listening. Locally produced only — a relayed one
173
183
  // carries an `instance`, and relaying it back would be the loop the field exists to break.
174
184
  services.Notifier.consume(