@wildo-ai/saas-minions-lib 1.1.3

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.
Files changed (47) hide show
  1. package/LICENSE +34 -0
  2. package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.d.ts +22 -0
  3. package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.d.ts.map +1 -0
  4. package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.js +234 -0
  5. package/dist/esm/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.js.map +1 -0
  6. package/dist/esm/index.d.ts +9 -0
  7. package/dist/esm/index.d.ts.map +1 -0
  8. package/dist/esm/index.js +9 -0
  9. package/dist/esm/index.js.map +1 -0
  10. package/dist/esm/inject/models/container.d.ts +7 -0
  11. package/dist/esm/inject/models/container.d.ts.map +1 -0
  12. package/dist/esm/inject/models/container.js +55 -0
  13. package/dist/esm/inject/models/container.js.map +1 -0
  14. package/dist/esm/inject/models/service-types.d.ts +7 -0
  15. package/dist/esm/inject/models/service-types.d.ts.map +1 -0
  16. package/dist/esm/inject/models/service-types.js +6 -0
  17. package/dist/esm/inject/models/service-types.js.map +1 -0
  18. package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.d.ts +47 -0
  19. package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.d.ts.map +1 -0
  20. package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.js +157 -0
  21. package/dist/esm/runtime/queue/minion-tick-consumer.backend.service.js.map +1 -0
  22. package/dist/esm/runtime/services/define-minion-init.d.ts +98 -0
  23. package/dist/esm/runtime/services/define-minion-init.d.ts.map +1 -0
  24. package/dist/esm/runtime/services/define-minion-init.js +4 -0
  25. package/dist/esm/runtime/services/define-minion-init.js.map +1 -0
  26. package/dist/esm/runtime/services/own-schedule-reader.backend.service.d.ts +75 -0
  27. package/dist/esm/runtime/services/own-schedule-reader.backend.service.d.ts.map +1 -0
  28. package/dist/esm/runtime/services/own-schedule-reader.backend.service.js +124 -0
  29. package/dist/esm/runtime/services/own-schedule-reader.backend.service.js.map +1 -0
  30. package/dist/esm/runtime/services/start-minion-application.backend.service.d.ts +48 -0
  31. package/dist/esm/runtime/services/start-minion-application.backend.service.d.ts.map +1 -0
  32. package/dist/esm/runtime/services/start-minion-application.backend.service.js +304 -0
  33. package/dist/esm/runtime/services/start-minion-application.backend.service.js.map +1 -0
  34. package/dist/tsconfig.build.tsbuildinfo +1 -0
  35. package/package.json +56 -0
  36. package/src/base-classes/services/services/__tests__/minion-scoped-services-registry-handler.backend.service.test.ts +252 -0
  37. package/src/base-classes/services/services/minion-scoped-services-registry-handler.backend.service.ts +337 -0
  38. package/src/index.ts +11 -0
  39. package/src/inject/models/__tests__/container.test.ts +30 -0
  40. package/src/inject/models/container.ts +68 -0
  41. package/src/inject/models/service-types.ts +11 -0
  42. package/src/runtime/queue/minion-tick-consumer.backend.service.ts +181 -0
  43. package/src/runtime/services/__tests__/own-schedule-reader.backend.service.test.ts +118 -0
  44. package/src/runtime/services/__tests__/start-minion-application.backend.service.test.ts +422 -0
  45. package/src/runtime/services/define-minion-init.ts +113 -0
  46. package/src/runtime/services/own-schedule-reader.backend.service.ts +146 -0
  47. package/src/runtime/services/start-minion-application.backend.service.ts +398 -0
@@ -0,0 +1,422 @@
1
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
2
+ import type {
3
+ AppConfigurationService,
4
+ LoggerService,
5
+ StartApplicationBackendService,
6
+ } from '@wildo-ai/saas-backend-lib';
7
+ import { PROVIDER_RUNTIME_ENV_KEYS } from '@wildo-ai/platform-config-lib';
8
+ import {
9
+ defineMinionInit,
10
+ type MinionProviderRuntimeArtifact,
11
+ } from '../define-minion-init';
12
+ import { MinionTickConsumerBackendService } from '../../queue/minion-tick-consumer.backend.service';
13
+ import { StartMinionApplicationBackendService } from '../start-minion-application.backend.service';
14
+ import { ApplicationRuntimeProfile, RuntimePrincipalBackendService } from '@wildo-ai/saas-backend-lib';
15
+ import type { OwnScheduleReaderBackendService } from '../own-schedule-reader.backend.service';
16
+
17
+ /**
18
+ * Set the runtime env keys that `assertProviderRuntimeEnvInSync` reads
19
+ * at boot, simulating the `.wildo-providers.env` mount that production
20
+ * minion processes always have. Tests that DON'T set these will trip
21
+ * the fail-closed reconciliation guard — by design.
22
+ */
23
+ function withMatchingProviderRuntimeEnv(input: {
24
+ refs: ReadonlyArray<string>;
25
+ digest: string;
26
+ }): void {
27
+ vi.stubEnv(PROVIDER_RUNTIME_ENV_KEYS.REFS, [...input.refs].sort().join(','));
28
+ vi.stubEnv(PROVIDER_RUNTIME_ENV_KEYS.RUNTIME_DIGEST, input.digest);
29
+ }
30
+
31
+ function createTickConsumerStub() {
32
+ return {
33
+ start: vi.fn().mockResolvedValue(undefined),
34
+ stop: vi.fn().mockResolvedValue(undefined),
35
+ isRunning: vi.fn().mockReturnValue(false),
36
+ } as unknown as MinionTickConsumerBackendService;
37
+ }
38
+
39
+ function createAppConfigServiceStub(applicationId = 'wonder-todos') {
40
+ return {
41
+ applicationId,
42
+ } as unknown as AppConfigurationService;
43
+ }
44
+
45
+ function createLoggerStub(): LoggerService {
46
+ return {
47
+ info: vi.fn(),
48
+ warn: vi.fn(),
49
+ error: vi.fn(),
50
+ debug: vi.fn(),
51
+ debugByType: vi.fn(() => vi.fn()),
52
+ setDebugTypeLogging: vi.fn(),
53
+ } as unknown as LoggerService;
54
+ }
55
+
56
+ function instantiate(delegate: StartApplicationBackendService): {
57
+ service: StartMinionApplicationBackendService;
58
+ tickConsumer: MinionTickConsumerBackendService;
59
+ runtimePrincipal: RuntimePrincipalBackendService;
60
+ systemAccess: any;
61
+ } {
62
+ const tickConsumer = createTickConsumerStub();
63
+ // A REAL principal, not a stub: this harness is the only place that proves a minion
64
+ // declares its identity at startup, and a stub would let a broken initialize() pass.
65
+ const runtimePrincipal = new RuntimePrincipalBackendService();
66
+ // The tick context hands the author the CONTAINED system-access door; the stub only
67
+ // needs identity here, since what this harness proves is that the context is assembled
68
+ // and passed — the door's own containment + fail-closed behaviour is pinned in
69
+ // `system-access.service.test.ts`.
70
+ const systemAccess = { listAsSystem: vi.fn(), readAsSystem: vi.fn() } as any;
71
+ const service = new StartMinionApplicationBackendService(
72
+ delegate,
73
+ createAppConfigServiceStub(),
74
+ tickConsumer,
75
+ createLoggerStub(),
76
+ runtimePrincipal,
77
+ systemAccess,
78
+ { read: vi.fn().mockResolvedValue([]) } as unknown as OwnScheduleReaderBackendService,
79
+ );
80
+ return { service, tickConsumer, runtimePrincipal, systemAccess };
81
+ }
82
+
83
+ describe('StartMinionApplicationBackendService', () => {
84
+ afterEach(() => {
85
+ vi.unstubAllEnvs();
86
+ });
87
+
88
+ it('maps minion startup onto the backend runtime with headless, cron-sync and job-consumer guards', async () => {
89
+ const initialize = vi.fn().mockResolvedValue(undefined);
90
+ const delegate = {
91
+ initialize,
92
+ shutdown: vi.fn().mockResolvedValue(undefined),
93
+ isApplicationInitialized: vi.fn().mockReturnValue(true),
94
+ } as unknown as StartApplicationBackendService;
95
+ const { service } = instantiate(delegate);
96
+ const providerRuntime: MinionProviderRuntimeArtifact = {
97
+ __AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
98
+ generatedBy: 'wildo provider-runtime-artifact',
99
+ generatedAt: '2026-05-03T06:00:00.000Z',
100
+ sourceDigest: 'sha256:test',
101
+ providerRefs: ['openai'],
102
+ artifactKind: 'minions',
103
+ modules: {
104
+ declaredModules: {},
105
+ moduleIds: [],
106
+ moduleIdsByService: {},
107
+ },
108
+ scopes: {
109
+ marketingScrapper: {
110
+ providers: {
111
+ openai: {
112
+ engineCapabilities: [],
113
+ providerCapabilities: ['LLM_CHAT'],
114
+ protocols: ['LLM_PROVIDER'],
115
+ },
116
+ },
117
+ selection: {},
118
+ },
119
+ },
120
+ };
121
+
122
+ // Boot-time reconciliation requires the env file to be mounted.
123
+ // Production minion processes get this via docker-compose `env_file:`
124
+ // or K8s envFrom; in tests we stub the equivalent process.env keys.
125
+ withMatchingProviderRuntimeEnv({
126
+ refs: providerRuntime.providerRefs!,
127
+ digest: providerRuntime.sourceDigest,
128
+ });
129
+
130
+ const minionInit = defineMinionInit({
131
+ minionName: 'marketingScrapper',
132
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
133
+ sharedResourceConfigurations: {} as any,
134
+ sharedResourceRelationships: [],
135
+ customServiceImplementations: [],
136
+ providerRuntime,
137
+ });
138
+
139
+ await service.initialize(minionInit);
140
+
141
+ expect(initialize).toHaveBeenCalledTimes(1);
142
+ // The `providerRuntime` assertion uses `objectContaining` (NOT exact match)
143
+ // so the test pins the load-bearing facts of the minion → backend
144
+ // projection — `artifactKind` flipped to `'backend'` and `scope` extracted
145
+ // from the minion's slot — without coupling the orchestration test to the
146
+ // shape evolution of the backend artifact itself. Fields like
147
+ // `lockfileSectionDigest`, `providerGraphDigest`, and `providerRefs` are
148
+ // added by the lockfile-tracking work in the active
149
+ // provider-migration-continuation plan; they belong in the projection's
150
+ // OWN unit tests, not in this top-level "the minion startup wires the
151
+ // right delegate input" smoke test.
152
+ expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
153
+ sharedResourceConfigurations: minionInit.sharedResourceConfigurations,
154
+ sharedResourceRelationships: minionInit.sharedResourceRelationships,
155
+ customServiceImplementations: minionInit.customServiceImplementations,
156
+ providerRuntime: expect.objectContaining({
157
+ artifactKind: 'backend',
158
+ scope: providerRuntime.scopes.marketingScrapper,
159
+ modules: providerRuntime.modules,
160
+ sourceDigest: providerRuntime.sourceDigest,
161
+ }),
162
+ headlessMode: true,
163
+ skipCronSync: true,
164
+ // The minion must opt OUT of the shared application job consumers so it
165
+ // never competes with the backend-api pod for the scheduled/operations/
166
+ // callbacks queues (task_ddb489d1). Without this, RabbitMQ round-robins
167
+ // scheduled-cron ticks onto the minion, which dead-letters them.
168
+ skipJobConsumers: true,
169
+ serviceIdentifier: 'minions.marketingScrapper',
170
+ }));
171
+ expect(initialize.mock.calls[0]?.[0]?.servicesRegistryDecoratorFactory).toEqual(expect.any(Function));
172
+ expect(initialize.mock.calls[0]?.[0]?.afterResourcesRegistryInitialized).toEqual(expect.any(Function));
173
+ });
174
+
175
+ it('skips boot-time env reconciliation when the per-host scope is empty (no false-positive throw on union providerRefs)', async () => {
176
+ // A multi-scope artifact whose union `providerRefs` includes
177
+ // sibling refs the typed module preserves uncollapsed. The
178
+ // projection MUST recompute per-host refs from `scope.providers`
179
+ // — without this the minion startup would throw `env-missing` at
180
+ // boot because the CLI emitter deliberately does NOT write
181
+ // `.wildo-providers.env` for empty scopes. This pins the
182
+ // 2026-05-10 fix in `selectMinionProviderRuntimeScope`.
183
+ const initialize = vi.fn().mockResolvedValue(undefined);
184
+ const delegate = {
185
+ initialize,
186
+ shutdown: vi.fn().mockResolvedValue(undefined),
187
+ isApplicationInitialized: vi.fn().mockReturnValue(true),
188
+ } as unknown as StartApplicationBackendService;
189
+ const { service } = instantiate(delegate);
190
+ const providerRuntime: MinionProviderRuntimeArtifact = {
191
+ __AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
192
+ generatedBy: 'wildo provider-runtime-artifact',
193
+ generatedAt: '2026-05-10T12:00:00.000Z',
194
+ sourceDigest: 'sha256:union',
195
+ // Multi-scope union — `openai` belongs to a sibling minion, NOT
196
+ // to `emptyMinion` whose own `scope.providers` is `{}`.
197
+ providerRefs: ['openai'],
198
+ artifactKind: 'minions',
199
+ modules: { declaredModules: {}, moduleIds: [], moduleIdsByService: {} },
200
+ scopes: {
201
+ emptyMinion: {
202
+ providers: {},
203
+ selection: {},
204
+ },
205
+ },
206
+ };
207
+
208
+ // Note: NO env stub. The fix means `assertProviderRuntimeEnvInSync`
209
+ // should NOT run for an empty-scope minion. Without the fix this
210
+ // would throw `env-missing` because the parent's union refs
211
+ // wrongly survive the projection.
212
+ await expect(
213
+ service.initialize(defineMinionInit({
214
+ minionName: 'emptyMinion',
215
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
216
+ sharedResourceConfigurations: {} as any,
217
+ sharedResourceRelationships: [],
218
+ customServiceImplementations: [],
219
+ providerRuntime,
220
+ })),
221
+ ).resolves.toBeUndefined();
222
+
223
+ expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
224
+ providerRuntime: expect.objectContaining({
225
+ artifactKind: 'backend',
226
+ // After projection, providerRefs reflects the per-host scope (empty), NOT the union.
227
+ providerRefs: [],
228
+ }),
229
+ }));
230
+ });
231
+
232
+ it('preserves an explicit serviceIdentifier override', async () => {
233
+ const initialize = vi.fn().mockResolvedValue(undefined);
234
+ const delegate = {
235
+ initialize,
236
+ shutdown: vi.fn().mockResolvedValue(undefined),
237
+ isApplicationInitialized: vi.fn().mockReturnValue(false),
238
+ } as unknown as StartApplicationBackendService;
239
+ const { service } = instantiate(delegate);
240
+
241
+ await service.initialize(defineMinionInit({
242
+ minionName: 'marketingScrapper',
243
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
244
+ serviceIdentifier: 'minions.marketingScrapper.blue',
245
+ sharedResourceConfigurations: {} as any,
246
+ sharedResourceRelationships: [],
247
+ customServiceImplementations: [],
248
+ }));
249
+
250
+ expect(initialize).toHaveBeenCalledWith(expect.objectContaining({
251
+ serviceIdentifier: 'minions.marketingScrapper.blue',
252
+ }));
253
+ });
254
+
255
+ it('fails fast when the generated minion runtime omits the current minion scope', async () => {
256
+ const initialize = vi.fn().mockResolvedValue(undefined);
257
+ const delegate = {
258
+ initialize,
259
+ shutdown: vi.fn().mockResolvedValue(undefined),
260
+ isApplicationInitialized: vi.fn().mockReturnValue(false),
261
+ } as unknown as StartApplicationBackendService;
262
+ const { service } = instantiate(delegate);
263
+
264
+ await expect(service.initialize(defineMinionInit({
265
+ minionName: 'marketingScrapper',
266
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
267
+ sharedResourceConfigurations: {} as any,
268
+ sharedResourceRelationships: [],
269
+ customServiceImplementations: [],
270
+ providerRuntime: {
271
+ __AUTOGENERATED__: 'AUTO-GENERATED FILE. DO NOT EDIT. Regenerate with `wildo config sync`.',
272
+ generatedBy: 'wildo provider-runtime-artifact',
273
+ generatedAt: '2026-05-03T06:00:00.000Z',
274
+ sourceDigest: 'sha256:test',
275
+ artifactKind: 'minions',
276
+ modules: {
277
+ declaredModules: {},
278
+ moduleIds: [],
279
+ moduleIdsByService: {},
280
+ },
281
+ scopes: {},
282
+ },
283
+ }))).rejects.toThrow("Provider runtime artifact does not contain a scope for minion 'marketingScrapper'.");
284
+ expect(initialize).not.toHaveBeenCalled();
285
+ });
286
+
287
+ it('delegates lifecycle state helpers to the shared startup service', async () => {
288
+ const shutdown = vi.fn().mockResolvedValue(undefined);
289
+ const isApplicationInitialized = vi.fn()
290
+ .mockReturnValueOnce(true)
291
+ .mockReturnValueOnce(false);
292
+ const delegate = {
293
+ initialize: vi.fn().mockResolvedValue(undefined),
294
+ shutdown,
295
+ isApplicationInitialized,
296
+ } as unknown as StartApplicationBackendService;
297
+ const { service } = instantiate(delegate);
298
+
299
+ expect(service.isApplicationInitialized()).toBe(true);
300
+ expect(service.isApplicationInitialized()).toBe(false);
301
+ await service.shutdown();
302
+
303
+ expect(shutdown).toHaveBeenCalledTimes(1);
304
+ });
305
+
306
+ it('auto-starts the minion tick consumer with the registered onTick handler', async () => {
307
+ const initialize = vi.fn().mockResolvedValue(undefined);
308
+ const delegate = {
309
+ initialize,
310
+ shutdown: vi.fn().mockResolvedValue(undefined),
311
+ isApplicationInitialized: vi.fn().mockReturnValue(true),
312
+ } as unknown as StartApplicationBackendService;
313
+ const { service, tickConsumer } = instantiate(delegate);
314
+ const onTick = vi.fn().mockResolvedValue(undefined);
315
+
316
+ await service.initialize(defineMinionInit({
317
+ minionName: 'marketingScrapper',
318
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
319
+ sharedResourceConfigurations: {} as any,
320
+ sharedResourceRelationships: [],
321
+ customServiceImplementations: [],
322
+ onTick,
323
+ }));
324
+
325
+ expect(tickConsumer.start).toHaveBeenCalledTimes(1);
326
+ expect(tickConsumer.start).toHaveBeenCalledWith(expect.objectContaining({
327
+ applicationId: 'wonder-todos',
328
+ minionName: 'marketingScrapper',
329
+ handler: expect.any(Function),
330
+ }));
331
+
332
+ // The handler is no longer the author's function by IDENTITY — startup adapts it to
333
+ // inject the framework-supplied `MinionTickContext`. Asserting identity would now
334
+ // pin the absence of that context, so this asserts the stronger property instead:
335
+ // invoking what the consumer received must call the author's onTick WITH the
336
+ // contained system-access door and the minion's own name.
337
+ const registered = (tickConsumer.start as any).mock.calls[0][0].handler;
338
+ const token = { jobId: 'job-1', minionName: 'marketingScrapper', applicationId: 'wonder-todos' };
339
+ await registered(token);
340
+
341
+ expect(onTick).toHaveBeenCalledTimes(1);
342
+ expect(onTick).toHaveBeenCalledWith(token, expect.objectContaining({
343
+ minionName: 'marketingScrapper',
344
+ systemAccess: expect.anything(),
345
+ }));
346
+
347
+ await service.shutdown();
348
+ expect(tickConsumer.stop).toHaveBeenCalledTimes(1);
349
+ });
350
+
351
+ it('still subscribes the tick consumer when no onTick handler is registered (logs a warning instead)', async () => {
352
+ const initialize = vi.fn().mockResolvedValue(undefined);
353
+ const delegate = {
354
+ initialize,
355
+ shutdown: vi.fn().mockResolvedValue(undefined),
356
+ isApplicationInitialized: vi.fn().mockReturnValue(true),
357
+ } as unknown as StartApplicationBackendService;
358
+ const { service, tickConsumer } = instantiate(delegate);
359
+
360
+ await service.initialize(defineMinionInit({
361
+ minionName: 'marketingScrapper',
362
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
363
+ sharedResourceConfigurations: {} as any,
364
+ sharedResourceRelationships: [],
365
+ customServiceImplementations: [],
366
+ }));
367
+
368
+ expect(tickConsumer.start).toHaveBeenCalledTimes(1);
369
+ const firstCall = (tickConsumer.start as unknown as { mock: { calls: Array<[{ handler: unknown }]> } }).mock.calls[0];
370
+ expect(firstCall?.[0].handler).toEqual(expect.any(Function));
371
+ });
372
+ });
373
+
374
+ /**
375
+ * Step 3 / D9 — a minion must declare WHO it is before it can perform any privileged
376
+ * access, and it must do so structurally (framework-owned startup), never by relying on
377
+ * each minion author to remember. Attribution an author can forget is attribution that
378
+ * will be missing exactly when an auditor needs it.
379
+ */
380
+ describe('StartMinionApplicationBackendService — runtime identity (D9)', () => {
381
+ function instantiateWithDelegate() {
382
+ const delegate = {
383
+ initialize: vi.fn().mockResolvedValue(undefined),
384
+ shutdown: vi.fn().mockResolvedValue(undefined),
385
+ isApplicationInitialized: vi.fn().mockReturnValue(true),
386
+ } as unknown as StartApplicationBackendService;
387
+ return instantiate(delegate);
388
+ }
389
+
390
+ it('declares the minion identity on the runtime principal at startup', async () => {
391
+ const { service, runtimePrincipal } = instantiateWithDelegate();
392
+
393
+ await service.initialize(defineMinionInit({
394
+ minionName: 'marketingScrapper',
395
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
396
+ sharedResourceConfigurations: {} as any,
397
+ sharedResourceRelationships: [],
398
+ customServiceImplementations: [],
399
+ }));
400
+
401
+ expect(runtimePrincipal.describeForAudit()).toEqual({
402
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
403
+ runtimeKey: 'marketingScrapper',
404
+ serviceIdentifier: 'minions.marketingScrapper',
405
+ });
406
+ });
407
+
408
+ it('honours an explicit serviceIdentifier (blue/green minion instances stay distinguishable)', async () => {
409
+ const { service, runtimePrincipal } = instantiateWithDelegate();
410
+
411
+ await service.initialize(defineMinionInit({
412
+ minionName: 'marketingScrapper',
413
+ runtimeProfile: ApplicationRuntimeProfile.MINION,
414
+ serviceIdentifier: 'minions.marketingScrapper.blue',
415
+ sharedResourceConfigurations: {} as any,
416
+ sharedResourceRelationships: [],
417
+ customServiceImplementations: [],
418
+ }));
419
+
420
+ expect(runtimePrincipal.describeForAudit().serviceIdentifier).toBe('minions.marketingScrapper.blue');
421
+ });
422
+ });
@@ -0,0 +1,113 @@
1
+ import type {
2
+ ProjectedMinionInitializationConfig,
3
+ ProviderRuntimeArtifact,
4
+ SystemAccessBackendService,
5
+ } from '@wildo-ai/saas-backend-lib';
6
+ import type { MinionTickHandler } from '../queue/minion-tick-consumer.backend.service';
7
+ import type { OwnScheduleReaderBackendService } from './own-schedule-reader.backend.service';
8
+
9
+ type ProviderRuntimeScope = ProviderRuntimeArtifact['scope'];
10
+ type ProviderRuntimeModules = ProviderRuntimeArtifact['modules'];
11
+
12
+ export interface MinionProviderRuntimeArtifact {
13
+ __AUTOGENERATED__: string;
14
+ generatedBy: ProviderRuntimeArtifact['generatedBy'];
15
+ generatedAt: string;
16
+ sourceDigest: string;
17
+ providerRefs?: ProviderRuntimeArtifact['providerRefs'];
18
+ /**
19
+ * Mirrored from the engine artifact so the per-host projection can FORWARD it (#330).
20
+ *
21
+ * This interface is a hand-written mirror of the CLI's multi-scope artifact, so a field the
22
+ * CLI emits and this shape omits is a field the projection can only reach through a cast —
23
+ * which would assert, across a package boundary, the very thing nobody checked.
24
+ */
25
+ providerRuntimeImports?: ProviderRuntimeArtifact['providerRuntimeImports'];
26
+ providerGraphDigest?: ProviderRuntimeArtifact['providerGraphDigest'];
27
+ lockfileSectionDigest?: ProviderRuntimeArtifact['lockfileSectionDigest'];
28
+ artifactKind: 'minions';
29
+ modules: ProviderRuntimeModules;
30
+ scopes: Record<string, ProviderRuntimeScope>;
31
+ }
32
+
33
+ /**
34
+ * The surface a minion's tick handler is given to do its work with.
35
+ *
36
+ * Handed to the handler rather than left for each author to resolve from the
37
+ * container, for the same reason the runtime identity is established in
38
+ * framework-owned startup: a boundary an author has to find is a boundary an author
39
+ * can get wrong. What arrives here is already the CONTAINED surface —
40
+ * `systemAccess` routes through the minion's `resourceAccess` ACL proxy, because
41
+ * minion startup rebinds the services registry to the scoped decorator before any
42
+ * tick is delivered.
43
+ *
44
+ * So a minion's effective authority is the INTERSECTION of two independent doors
45
+ * (see `.claude/plans/minion-runtime-scope.md` D6):
46
+ *
47
+ * - `resourceAccess` — operator-declared containment, enforced by the DI proxy;
48
+ * - the system-access door — the sanctioned per-tenant-authorization bypass, which
49
+ * for a minion is fail-closed on audit (D9 + OQ-5b): audited, or refused.
50
+ *
51
+ * Neither subsumes the other. A resource the ACL forbids is refused even though the
52
+ * system-access door would have allowed it, and a read the ACL permits is still
53
+ * refused if it cannot be recorded.
54
+ */
55
+ export interface MinionTickContext {
56
+ /**
57
+ * The sanctioned privileged-access door, already contained by this minion's
58
+ * `resourceAccess` whitelist.
59
+ *
60
+ * Use this — never a repository directly (the `no-direct-repo-from-minion` ESLint
61
+ * rule enforces that) — so every access stays inside both doors and leaves an
62
+ * attributable audit record naming this minion.
63
+ */
64
+ systemAccess: SystemAccessBackendService;
65
+ /** This minion's name, as declared in `wildo.saas.config.ts > minions`. */
66
+ minionName: string;
67
+ /**
68
+ * Read this minion's OWN cron schedule and recent runs (R4).
69
+ *
70
+ * Present only when the application declared the `own_cron_records` scope in
71
+ * this minion's `platformAccess`; otherwise the platform refuses and `read()`
72
+ * rejects. It is deliberately NOT absent from the type in that case — the
73
+ * authority decision belongs to the platform, and a client-side `undefined`
74
+ * would be this process guessing at it, which drifts the moment the
75
+ * declaration changes under a running minion.
76
+ *
77
+ * `read()` takes no arguments, and that is the contract rather than a
78
+ * convenience: the subject is derived from this runtime's attested identity,
79
+ * so another minion's schedule is not something this call could be asked for.
80
+ */
81
+ ownSchedule: OwnScheduleReaderBackendService;
82
+ }
83
+
84
+ /**
85
+ * Tick handler invoked by `MinionTickConsumerBackendService` once per verified
86
+ * `MINION_TICK` token addressed to this minion (KD-12).
87
+ */
88
+ export type MinionTickAuthorHandler = (
89
+ token: Parameters<MinionTickHandler>[0],
90
+ context: MinionTickContext,
91
+ ) => Promise<void>;
92
+
93
+ export type MinionInitializationConfig = Omit<ProjectedMinionInitializationConfig, 'providerRuntime'> & {
94
+ providerRuntime?: ProviderRuntimeArtifact | MinionProviderRuntimeArtifact;
95
+ /**
96
+ * Tick handler invoked once per verified `MINION_TICK` token addressed to this
97
+ * minion (KD-12), receiving the framework-supplied {@link MinionTickContext}.
98
+ *
99
+ * Minion authors typically route the tick into the locally-hosted
100
+ * `flowsActorsRegistry` (per Q9 LOCKED — per-minion-local actor
101
+ * catalog). If omitted, the consumer still subscribes to the
102
+ * per-minion queue but logs a warning on every tick — useful as a
103
+ * fail-loud signal that ticks are arriving while the minion has not
104
+ * registered any tick-handling logic yet.
105
+ */
106
+ onTick?: MinionTickAuthorHandler;
107
+ };
108
+
109
+ export function defineMinionInit(
110
+ config: MinionInitializationConfig,
111
+ ): MinionInitializationConfig {
112
+ return config;
113
+ }
@@ -0,0 +1,146 @@
1
+ /**
2
+ * A minion reading its OWN cron records from the platform (R4).
3
+ *
4
+ * ## The client is as selector-free as the route
5
+ *
6
+ * `read()` takes no arguments. Not a minion name, not an application id, not a
7
+ * job id — there is nothing to pass, so there is nothing an author could pass
8
+ * wrongly and nothing a later caller could parameterise. The route it calls
9
+ * derives its subject from the attestation, and this client's shape mirrors that
10
+ * rather than merely respecting it.
11
+ *
12
+ * That symmetry is deliberate. A client with a `minionName` argument that always
13
+ * happens to be filled with the caller's own name is one refactor away from being
14
+ * filled with something else, and the server would still be correct while every
15
+ * reader of this file had been taught the wrong mental model.
16
+ *
17
+ * ## Authority, and where it is decided
18
+ *
19
+ * Nothing here checks `platformAccess`. Two other places do, and both are better
20
+ * placed: apps-manager refuses to mint an attestation for a minion whose
21
+ * application declared no scope, and crontabs re-checks the scope before it
22
+ * queries. A third check here would be a client-side guess about a server-side
23
+ * decision — it would drift, and the day it drifted it would either refuse work
24
+ * the platform allows or promise work the platform refuses.
25
+ *
26
+ * So a minion without the scope gets a refusal from the platform, which is the
27
+ * party that knows.
28
+ */
29
+
30
+ import 'reflect-metadata';
31
+
32
+ import { inject, injectable } from 'inversify';
33
+
34
+ import { ErrorCustomMessageReference, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';
35
+ import {
36
+ AppConfigurationService,
37
+ PlatformApplicationType,
38
+ RuntimePrincipalAttestationBackendService,
39
+ SAAS_SERVICE_TYPES,
40
+ type ErrorBuilderBackendService,
41
+ type LoggerService,
42
+ } from '@wildo-ai/saas-backend-lib';
43
+
44
+ /**
45
+ * One cron job that ticks this minion, with its recent runs.
46
+ *
47
+ * Typed structurally rather than importing the platform's `CronJob` — a minion
48
+ * runtime has no dependency on `platform-shared-lib` and giving it one to name a
49
+ * response body would be a package boundary crossed for a type alias.
50
+ */
51
+ export interface OwnScheduleEntry {
52
+ job: {
53
+ jobId: string;
54
+ name?: string;
55
+ schedule?: { cron: string; timezone?: string; enabled?: boolean };
56
+ status?: string;
57
+ [field: string]: unknown;
58
+ };
59
+ recentExecutions: Array<{
60
+ status?: string;
61
+ startTime?: string;
62
+ endTime?: string;
63
+ error?: string;
64
+ [field: string]: unknown;
65
+ }>;
66
+ }
67
+
68
+ const OWN_SCHEDULE_PATH = '/api/v1/runtime-self/cron-jobs';
69
+
70
+ @injectable()
71
+ export class OwnScheduleReaderBackendService {
72
+ private baseUrl: string | null = null;
73
+
74
+ constructor(
75
+ @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
76
+ @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
77
+ @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
78
+ @inject(SAAS_SERVICE_TYPES.RuntimePrincipalAttestationService)
79
+ private readonly attestations: RuntimePrincipalAttestationBackendService,
80
+ ) {}
81
+
82
+ /**
83
+ * This minion's cron job definitions and their recent runs.
84
+ *
85
+ * The attestation is fetched per call rather than held: the exchange caches it,
86
+ * so this costs nothing, and a client that cached it itself would eventually
87
+ * present an expired one.
88
+ */
89
+ public async read(): Promise<OwnScheduleEntry[]> {
90
+ const baseUrl = this.resolveBaseUrl();
91
+ const attestation = await this.attestations.getAttestation(
92
+ PlatformApplicationType.PLATFORM_CRONTABS_BATCHES_MANAGER,
93
+ );
94
+
95
+ const response = await fetch(`${baseUrl}${OWN_SCHEDULE_PATH}`, {
96
+ method: 'GET',
97
+ headers: {
98
+ [WildoHeaderKeys.CONTENT_TYPE]: 'application/json',
99
+ // Deliberately the ONLY credential. A minion is not a platform service,
100
+ // so no `X-Service-Id`; and an application JWT would carry an identity
101
+ // meaning "some runtime of this app" — attaching one as well would only
102
+ // invite the server to read the weaker of the two.
103
+ [WildoHeaderKeys.RUNTIME_PRINCIPAL_TOKEN]: attestation,
104
+ },
105
+ });
106
+
107
+ if (!response.ok) {
108
+ // Surfaced rather than swallowed into an empty schedule. A refusal and "you
109
+ // have no jobs" are different answers, and returning `[]` for both would
110
+ // make a missing `platformAccess` declaration look like a correctly-empty
111
+ // schedule — the one failure an author cannot debug from the result.
112
+ throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
113
+ customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
114
+ context: {
115
+ message: 'The platform refused this runtime\'s own-schedule read',
116
+ status: response.status,
117
+ },
118
+ });
119
+ }
120
+
121
+ const body = (await response.json()) as { jobs?: OwnScheduleEntry[] } | null;
122
+ return body?.jobs ?? [];
123
+ }
124
+
125
+ private resolveBaseUrl(): string {
126
+ if (this.baseUrl) return this.baseUrl;
127
+
128
+ const baseUrl =
129
+ this.appConfigService.config.runtime.endPoints[PlatformApplicationType.PLATFORM_CRONTABS_BATCHES_MANAGER]
130
+ ?.internalUrl;
131
+
132
+ if (!baseUrl) {
133
+ // A CONFIGURATION failure, not an authorization one. Blurring them would
134
+ // send an operator to inspect the minion's `platformAccess` declaration
135
+ // over what is really a missing endpoint in this deployment's topology.
136
+ throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
137
+ customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
138
+ context: { message: 'The crontabs-manager endpoint is not configured for this runtime' },
139
+ });
140
+ }
141
+
142
+ this.baseUrl = baseUrl.replace(/\/+$/, '');
143
+ this.logger.debug?.('Own-schedule reader bound to the crontabs endpoint', { baseUrl: this.baseUrl });
144
+ return this.baseUrl;
145
+ }
146
+ }