@owlmeans/agent 0.1.18-rc.39 → 0.1.18-rc.41

package/tests/pipeline-compat.spec.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from 'bun:test'
+import { PipelineRunStatus } from '@owlmeans/agent-common'
+import type { PipelineRun, PipelineSpec } from '@owlmeans/agent-common'
+import { createMemoryPipelineRunStore, makePipeline } from '../src/index.js'
+import type { PipelineRunContext, PipelineRunStore, PipelineStep } from '../src/index.js'
+
+/**
+ * A pipeline that declares no plugin behaves exactly as the runner did before plugins existed.
+ *
+ * The expected values below are GOLDEN: they were recorded from the runner as it stood before the
+ * plugin seam was added, and every row the store is handed, every trace line and every progress
+ * event must still match them byte for byte. Timestamps are the only thing normalised — they are
+ * the one field that differs between two runs of the same code.
+ */
+
+interface State extends Record<string, unknown> {
+  value?: number
+  cursor?: string
+  child?: number
+}
+
+interface Deps { log: string[] }
+
+const normalise = (run: PipelineRun): string => JSON.stringify({
+  ...run, startedAt: 'T', heartbeatAt: 'T', updatedAt: 'T',
+})
+
+const recording = (): { store: PipelineRunStore, saved: string[] } => {
+  const inner = createMemoryPipelineRunStore()
+  const saved: string[] = []
+
+  return {
+    saved,
+    store: {
+      load: inner.load,
+      find: inner.find,
+      save: async run => {
+        saved.push(normalise(run))
+        await inner.save(run)
+      },
+    },
+  }
+}
+
+const childSpec: PipelineSpec = {
+  alias: 'child', version: 1, steps: [{ step: 'c1' }, { step: 'c2', after: ['c1'] }],
+}
+
+const parentSpec: PipelineSpec = {
+  alias: 'parent',
+  version: 1,
+  steps: [
+    { step: 'a' },
+    { step: 'left', after: ['a'] },
+    { step: 'right', after: ['a'], optional: true },
+    { step: 'skipped', after: ['left'] },
+    { step: 'nested', after: ['left', 'right'] },
+    { step: 'last', after: ['skipped', 'nested'] },
+  ],
+}
+
+const build = (store: PipelineRunStore, keys: { withPluginsKey: boolean }) => {
+  const contexts: PipelineRunContext<State, Deps>[] = []
+  const child = makePipeline<State, Deps>(childSpec, {
+    steps: [
+      { step: 'c1', run: async state => ({ child: (state.child ?? 0) + 1 }) },
+      { step: 'c2', run: async state => ({ child: (state.child ?? 0) + 10 }) },
+    ],
+    runs: store,
+    ...(keys.withPluginsKey ? { plugins: [] } : {}),
+  })
+  const steps: PipelineStep<State, Deps>[] = [
+    {
+      step: 'a',
+      run: async (_state, ctx) => {
+        contexts.push(ctx)
+        await ctx.mark({ cursor: 'half' })
+        ctx.report('halfway')
+
+        return { value: 1 }
+      },
+    },
+    { step: 'left', run: async (state, ctx) => { ctx.deps.log.push('left'); return { value: (state.value ?? 0) + 1 } } },
+    { step: 'right', run: async () => { throw new Error('right refused') } },
+    { step: 'skipped', skipWhen: () => true, run: async () => ({ value: 999 }) },
+    child.asStep<State>('nested', {
+      input: parent => ({ child: parent.value }),
+      output: result => ({ child: result.child }),
+    }),
+    { step: 'last', run: async (state, ctx) => { contexts.push(ctx); return { value: (state.value ?? 0) + 100 } } },
+  ]
+  const trace: string[] = []
+  const progress: string[] = []
+  const parent = makePipeline<State, Deps>(parentSpec, {
+    steps,
+    runs: store,
+    trace: line => { trace.push(line) },
+    onProgress: event => { progress.push(JSON.stringify(event)) },
+    ...(keys.withPluginsKey ? { plugins: [] } : {}),
+  })
+
+  return { parent, trace, progress, contexts }
+}
+
+const GOLDEN_SAVED = [
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":[],"pending":["a","left","right","skipped","nested","last"],"state":"{\\"cursor\\":\\"half\\"}","stateChars":17,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a"],"pending":["left","right","skipped","nested","last"],"state":"{\\"cursor\\":\\"half\\",\\"value\\":1}","stateChars":27,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a","left"],"pending":["right","skipped","nested","last"],"state":"{\\"cursor\\":\\"half\\",\\"value\\":2}","stateChars":27,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a","left","right"],"pending":["skipped","nested","last"],"state":"{\\"cursor\\":\\"half\\",\\"value\\":2}","stateChars":27,"warnings":["right: right refused"],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a","left","right","skipped"],"pending":["nested","last"],"state":"{\\"cursor\\":\\"half\\",\\"value\\":2}","stateChars":27,"warnings":["right: right refused"],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r/nested","pipeline":"child","version":1,"scope":"s","status":"running","completed":["c1"],"pending":["c2"],"state":"{\\"child\\":3}","stateChars":11,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T"}',
+  '{"runId":"r/nested","pipeline":"child","version":1,"scope":"s","status":"running","completed":["c1","c2"],"pending":[],"state":"{\\"child\\":13}","stateChars":12,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T"}',
+  '{"runId":"r/nested","pipeline":"child","version":1,"scope":"s","status":"done","completed":["c1","c2"],"pending":[],"state":"{\\"child\\":13}","stateChars":12,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a","left","right","skipped","nested"],"pending":["last"],"state":"{\\"cursor\\":\\"half\\",\\"value\\":2,\\"child\\":13}","stateChars":38,"warnings":["right: right refused"],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"running","completed":["a","left","right","skipped","nested","last"],"pending":[],"state":"{\\"cursor\\":\\"half\\",\\"value\\":102,\\"child\\":13}","stateChars":40,"warnings":["right: right refused"],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+  '{"runId":"r","pipeline":"parent","version":1,"scope":"s","status":"done","completed":["a","left","right","skipped","nested","last"],"pending":[],"state":"{\\"cursor\\":\\"half\\",\\"value\\":102,\\"child\\":13}","stateChars":40,"warnings":["right: right refused"],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","note":"halfway"}',
+]
+
+const GOLDEN_TRACE = [
+  '[pipe:parent:r] start · steps=6 inherited=0 attempt=0',
+  '[pipe:parent:r] step 1/6 a (run)',
+  '[pipe:parent:r] row saved · completed=0/6 chars=17',
+  '[pipe:parent:r] row saved · completed=1/6 chars=27',
+  '[pipe:parent:r] step 2/6 left (run)',
+  '[pipe:parent:r] step 3/6 right (run)',
+  '[pipe:parent:r] row saved · completed=3/6 chars=27',
+  '[pipe:parent:r] row saved · completed=3/6 chars=27',
+  '[pipe:parent:r] step 5/6 nested (run)',
+  '[pipe:parent:r] step 4/6 skipped (skip)',
+  '[pipe:parent:r] row saved · completed=4/6 chars=27',
+  '[pipe:parent:r] row saved · completed=5/6 chars=38',
+  '[pipe:parent:r] step 6/6 last (run)',
+  '[pipe:parent:r] row saved · completed=6/6 chars=40',
+  '[pipe:parent:r] row saved · completed=6/6 chars=40',
+]
+
+const GOLDEN_PROGRESS = [
+  '{"pipeline":"parent","runId":"r","step":"a","index":1,"total":6}',
+  '{"pipeline":"parent","runId":"r","step":"a","index":1,"total":6,"note":"halfway"}',
+  '{"pipeline":"parent","runId":"r","step":"left","index":2,"total":6}',
+  '{"pipeline":"parent","runId":"r","step":"right","index":3,"total":6}',
+  '{"pipeline":"parent","runId":"r","step":"nested","index":5,"total":6}',
+  '{"pipeline":"parent","runId":"r","step":"skipped","index":4,"total":6,"skipped":true}',
+  '{"pipeline":"parent","runId":"r","step":"last","index":6,"total":6}',
+]
+
+describe('agent — a pipeline without plugins is unchanged', () => {
+  for (const withPluginsKey of [false, true]) {
+    test(`rows, trace and progress match the pre-plugin runner (plugins key ${withPluginsKey ? 'empty' : 'absent'})`, async () => {
+      const { store, saved } = recording()
+      const { parent, trace, progress, contexts } = build(store, { withPluginsKey })
+      const log: string[] = []
+
+      const result = await parent.invoke({}, { runId: 'r', deps: { log }, scope: 's' })
+
+      expect(result.status).toBe(PipelineRunStatus.Done)
+      expect(result.state).toEqual({ cursor: 'half', value: 102, child: 13 })
+      expect(result.warnings).toEqual(['right: right refused'])
+      expect(saved).toEqual(GOLDEN_SAVED)
+      expect(trace).toEqual(GOLDEN_TRACE)
+      expect(progress).toEqual(GOLDEN_PROGRESS)
+      // A step of a pipeline that never opted in has no results surface at all — not even the key.
+      for (const ctx of contexts) {
+        expect('results' in ctx).toBe(false)
+        expect(Object.keys(ctx).sort()).toEqual([
+          'ask', 'completed', 'deps', 'entityId', 'expired', 'mark', 'remainingMs', 'report', 'runId', 'scope',
+          'signal', 'spec', 'step',
+        ])
+      }
+    })
+  }
+
+  test('a fatal error still writes the row Failed first and then escapes', async () => {
+    class OutOfTokens extends Error {}
+    const { store, saved } = recording()
+    const pipeline = makePipeline<State, Deps>(
+      { alias: 'fatal', version: 1, steps: [{ step: 'a' }, { step: 'b', after: ['a'] }] },
+      {
+        steps: [
+          { step: 'a', run: async () => ({ value: 1 }) },
+          { step: 'b', run: async () => { throw new OutOfTokens('no balance') } },
+        ],
+        runs: store,
+        fatal: e => e instanceof OutOfTokens,
+      },
+    )
+
+    await expect(pipeline.invoke({}, { runId: 'f', deps: { log: [] }, scope: 's' }))
+      .rejects.toThrow('no balance')
+    expect(saved).toEqual([
+      '{"runId":"f","pipeline":"fatal","version":1,"scope":"s","status":"running","completed":["a"],"pending":["b"],"state":"{\\"value\\":1}","stateChars":11,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T"}',
+      '{"runId":"f","pipeline":"fatal","version":1,"scope":"s","status":"failed","completed":["a"],"pending":["b"],"state":"{\\"value\\":1}","stateChars":11,"warnings":[],"attempts":0,"startedAt":"T","heartbeatAt":"T","updatedAt":"T","failedAt":"b","error":"no balance"}',
+    ])
+  })
+})

package/tests/pipeline-plugins.spec.ts

@@ -0,0 +1,194 @@
+import { describe, expect, test } from 'bun:test'
+import { PipelineRunStatus } from '@owlmeans/agent-common'
+import type { PipelineSpec } from '@owlmeans/agent-common'
+import { createMemoryPipelineRunStore, makePipeline } from '../src/index.js'
+import type {
+  PipelinePlugin, PipelineRunStore, PipelineStep, StepResults,
+} from '../src/index.js'
+
+/**
+ * The pipeline plugin seam: when each hook fires, what it is told, and the two containment rules —
+ * a plugin that throws never fails the run, and a plugin error the pipeline calls fatal takes the
+ * same road a fatal step error takes.
+ */
+
+interface State extends Record<string, unknown> { value?: number }
+interface Deps { log: string[] }
+
+const spec: PipelineSpec = {
+  alias: 'seam',
+  version: 1,
+  steps: [
+    { step: 'a' },
+    { step: 'skipped', after: ['a'] },
+    { step: 'soft', after: ['a'], optional: true },
+    { step: 'z', after: ['skipped', 'soft'] },
+  ],
+}
+
+const steps = (fail: string[] = []): PipelineStep<State, Deps>[] => [
+  { step: 'a', run: async (_s, ctx) => { ctx.deps.log.push('run:a'); return { value: 1 } } },
+  { step: 'skipped', skipWhen: () => true, run: async () => ({ value: 999 }) },
+  { step: 'soft', run: async () => { throw new Error('soft refused') } },
+  {
+    step: 'z',
+    run: async (state, ctx) => {
+      ctx.deps.log.push('run:z')
+      if (fail.includes('z')) throw new Error('z refused')
+      return { value: (state.value ?? 0) + 1 }
+    },
+  },
+]
+
+/** Records every hook as one line, and checks the row at `afterStep` time. */
+const recorder = (log: string[], runs: PipelineRunStore, patch: Partial<PipelinePlugin<State, Deps>> = {}) => ({
+  alias: 'recorder',
+  enter: event => { log.push(`enter:${event.mode}:${event.inherited.join(',')}`) },
+  beforeStep: ({ step }) => { log.push(`before:${step}`) },
+  afterStep: async ({ step, state, ctx }) => {
+    const row = await runs.load(ctx.runId)
+    // The patch is already merged, and the step is NOT yet durably complete.
+    log.push(`after:${step}:value=${state.value}:committed=${row?.completed.includes(step) === true}`)
+  },
+  passStep: ({ step, reason, error }) => { log.push(`pass:${step}:${reason}${error != null ? `:${error.message}` : ''}`) },
+  exit: ({ result }) => { log.push(`exit:${result.status}`) },
+  ...patch,
+}) as PipelinePlugin<State, Deps>
+
+describe('agent — pipeline plugin hooks', () => {
+  test('fire in order: enter, before/after around each run, pass for a skip and an optional failure, exit', async () => {
+    const log: string[] = []
+    const runs = createMemoryPipelineRunStore()
+    const pipeline = makePipeline<State, Deps>(spec, { steps: steps(), runs, plugins: [recorder(log, runs)] })
+
+    const result = await pipeline.invoke({}, { runId: 'r', deps: { log }, scope: 's' })
+
+    expect(result.status).toBe(PipelineRunStatus.Done)
+    // `skipped` and `soft` share a superstep; the guard's await lets `soft` start first.
+    expect(log).toEqual([
+      'enter:fresh:',
+      'before:a', 'run:a', 'after:a:value=1:committed=false',
+      'before:soft', 'pass:skipped:skipped', 'pass:soft:failed:soft refused',
+      'before:z', 'run:z', 'after:z:value=2:committed=false',
+      'exit:done',
+    ])
+  })
+
+  test('enter says how the run came in, and which steps it inherits', async () => {
+    const log: string[] = []
+    const runs = createMemoryPipelineRunStore()
+    const build = (fail: string[]) =>
+      makePipeline<State, Deps>(spec, { steps: steps(fail), runs, plugins: [recorder(log, runs)] })
+
+    await build(['z']).invoke({}, { runId: 'r', deps: { log: [] }, scope: 's' })
+    await build([]).invoke({}, { runId: 'r', deps: { log: [] }, scope: 's' })
+    await build(['z']).invoke({}, { runId: 'r2', deps: { log: [] }, scope: 's' })
+    await build([]).resume('r2', { deps: { log: [] } })
+    await build([]).invoke({}, { runId: 'r2', deps: { log: [] }, scope: 's', restart: true })
+
+    expect(log.filter(line => line.startsWith('enter:'))).toEqual([
+      'enter:fresh:',
+      'enter:continue:a,skipped,soft',
+      'enter:fresh:',
+      'enter:continue:a,skipped,soft',
+      'enter:restart:',
+    ])
+  })
+
+  test('are seated by alias and run by order', async () => {
+    const log: string[] = []
+    const named = (alias: string, order: number, tag: string): PipelinePlugin<State, Deps> =>
+      ({ alias, order, enter: () => { log.push(tag) } })
+    const pipeline = makePipeline<State, Deps>(
+      { alias: 'order', version: 1, steps: [{ step: 'a' }] },
+      {
+        steps: [{ step: 'a', run: async () => undefined }],
+        plugins: [named('late', 90, 'late'), named('early', 10, 'first-early'), named('early', 10, 'early')],
+      },
+    )
+
+    await pipeline.invoke({}, { runId: 'r', deps: { log: [] }, scope: 's' })
+
+    expect(log).toEqual(['early', 'late'])
+  })
+
+  test('the first plugin that offers results owns ctx.results', async () => {
+    const seen: Array<string | undefined> = []
+    const offer = (alias: string, ledger: string): PipelinePlugin<State, Deps> => ({
+      alias, beforeStep: () => ({ results: { ledger } as StepResults }),
+    })
+    const pipeline = makePipeline<State, Deps>(
+      { alias: 'offer', version: 1, steps: [{ step: 'a' }] },
+      {
+        steps: [{ step: 'a', run: async (_s, ctx) => { seen.push(ctx.results?.ledger) } }],
+        plugins: [offer('one', 'first'), offer('two', 'second')],
+      },
+    )
+
+    await pipeline.invoke({}, { runId: 'r', deps: { log: [] }, scope: 's' })
+
+    expect(seen).toEqual(['first'])
+  })
+
+  test('a composed run is told which step of which run it runs under', async () => {
+    const parents: unknown[] = []
+    const child = makePipeline<State, Deps>(
+      { alias: 'child', version: 1, steps: [{ step: 'c' }] },
+      {
+        steps: [{ step: 'c', run: async () => ({ value: 5 }) }],
+        plugins: [{ alias: 'watch', enter: event => { parents.push(event.parent) } }],
+      },
+    )
+    const parent = makePipeline<State, Deps>(
+      { alias: 'parent', version: 1, steps: [{ step: 'nested' }] },
+      { steps: [child.asStep<State>('nested', { input: () => ({}), output: out => ({ value: out.value }) })] },
+    )
+
+    await parent.invoke({}, { runId: 'p', deps: { log: [] }, scope: 's' })
+
+    expect(parents).toEqual([{ pipeline: 'parent', runId: 'p', step: 'nested' }])
+  })
+})
+
+describe('agent — pipeline plugin containment', () => {
+  test('a plugin that throws on every hook costs nothing but a warning', async () => {
+    const log: string[] = []
+    const boom = () => { throw new Error('plugin down') }
+    const pipeline = makePipeline<State, Deps>(spec, {
+      steps: steps(),
+      runs: createMemoryPipelineRunStore(),
+      plugins: [{ alias: 'broken', enter: boom, beforeStep: boom, afterStep: boom, passStep: boom, exit: boom }],
+    })
+
+    const result = await pipeline.invoke({}, { runId: 'r', deps: { log }, scope: 's' })
+
+    expect(result.status).toBe(PipelineRunStatus.Done)
+    expect(result.state.value).toBe(2)
+    expect(log).toEqual(['run:a', 'run:z'])
+  })
+
+  class OutOfTokens extends Error {}
+  const fatal = (e: unknown): boolean => e instanceof OutOfTokens
+
+  for (const hook of ['enter', 'afterStep', 'passStep', 'exit'] as const) {
+    test(`a fatal error on ${hook} writes the row Failed first, then escapes`, async () => {
+      const runs = createMemoryPipelineRunStore()
+      const pipeline = makePipeline<State, Deps>(spec, {
+        steps: steps(),
+        runs,
+        fatal,
+        plugins: [{ alias: 'fatal', [hook]: () => { throw new OutOfTokens(`spent on ${hook}`) } }],
+      })
+
+      await expect(pipeline.invoke({}, { runId: 'r', deps: { log: [] }, scope: 's' }))
+        .rejects.toThrow(`spent on ${hook}`)
+
+      const row = await runs.load('r')
+      expect(row?.status).toBe(PipelineRunStatus.Failed)
+      expect(row?.error).toBe(`spent on ${hook}`)
+      // Both passing steps share a superstep and both hit the fatal plugin; either may be named.
+      const expected = { enter: ['a'], afterStep: ['a'], passStep: ['skipped', 'soft'], exit: ['z'] }[hook]
+      expect(expected).toContain(row?.failedAt ?? '')
+    })
+  }
+})