@forgeax/engine-intelligence 0.1.2

package/src/__tests__/runtime.test.ts

@@ -0,0 +1,504 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { IntelligenceError } from '../errors';
+import { createIntelligenceRuntime } from '../runtime';
+import {
+  type ActivityId,
+  type ActivitySink,
+  type ActivitySubmission,
+  activityId,
+  type IntelligenceProvider,
+} from '../types';
+
+function controlledProvider(id = 'test.provider') {
+  const sinks = new Map<ActivityId, ActivitySink>();
+  let closed = false;
+  const provider: IntelligenceProvider = {
+    id,
+    start(submission, sink) {
+      sinks.set(submission.id, sink);
+      return ok(undefined);
+    },
+    cancel(activity) {
+      const sink = sinks.get(activity);
+      if (sink === undefined) {
+        return err(
+          new IntelligenceError({
+            code: 'intelligence-activity-not-found',
+            detail: { activityId: activity },
+          }),
+        );
+      }
+      sinks.delete(activity);
+      sink.cancelled();
+      return ok(undefined);
+    },
+    async close() {
+      closed = true;
+      for (const sink of sinks.values()) sink.cancelled();
+      sinks.clear();
+    },
+  };
+  return {
+    provider,
+    sinks,
+    get closed() {
+      return closed;
+    },
+  };
+}
+
+describe('IntelligenceRuntime', () => {
+  it('delivers ordered bounded deltas and a terminal result without awaiting in poll', () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider, {
+      createActivityId: () => activityId('activity-a'),
+      createSessionId: () => 'session-a',
+    });
+    const started = runtime.submit({ input: 'hello' });
+    expect(started.ok).toBe(true);
+    if (!started.ok) return;
+    const sink = controlled.sinks.get(started.value.id);
+    expect(sink).toBeDefined();
+    sink?.text('hel');
+    sink?.text('lo');
+    sink?.complete('hello');
+
+    expect(runtime.poll()).toEqual([
+      { type: 'text-delta', activityId: activityId('activity-a'), sequence: 1, text: 'hel' },
+      { type: 'text-delta', activityId: activityId('activity-a'), sequence: 2, text: 'lo' },
+      {
+        type: 'completed',
+        activityId: activityId('activity-a'),
+        sequence: 3,
+        session: { providerId: 'test.provider', id: 'session-a' },
+        output: 'hello',
+      },
+    ]);
+    expect(runtime.poll()).toEqual([]);
+  });
+
+  it('rejects cross-provider session reuse before provider dispatch', () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider);
+    const result = runtime.submit({
+      input: 'resume',
+      session: { providerId: 'another.provider', id: 'session-a' },
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('intelligence-session-provider-mismatch');
+    expect(controlled.sinks.size).toBe(0);
+  });
+
+  it('turns queue overflow into one structured terminal failure and cancels the provider', () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider, {
+      limits: { maxPendingEventsPerActivity: 3 },
+      createActivityId: () => activityId('overflow'),
+    });
+    const started = runtime.submit({ input: 'overflow' });
+    if (!started.ok) throw started.error;
+    const sink = controlled.sinks.get(started.value.id);
+    sink?.text('one');
+    sink?.text('two');
+    sink?.text('three');
+
+    const events = runtime.poll();
+    expect(events).toHaveLength(3);
+    expect(events[2]?.type).toBe('failed');
+    if (events[2]?.type === 'failed') {
+      expect(events[2].error.code).toBe('intelligence-output-overflow');
+    }
+    expect(controlled.sinks.size).toBe(0);
+  });
+
+  it('preserves the provider error category and cause projection', () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider, {
+      createActivityId: () => activityId('failed'),
+    });
+    const started = runtime.submit({ input: 'fail' });
+    if (!started.ok) throw started.error;
+    controlled.sinks.get(started.value.id)?.fail(new Error('provider exploded'));
+    const event = runtime.poll()[0];
+    expect(event?.type).toBe('failed');
+    if (event?.type === 'failed') {
+      expect(event.error.code).toBe('intelligence-provider-failed');
+      if (event.error.code === 'intelligence-provider-failed') {
+        expect(event.error.detail.cause).toBe('provider exploded');
+      }
+    }
+  });
+
+  it('closes the provider and rejects later work', async () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider);
+    await runtime.close();
+    expect(controlled.closed).toBe(true);
+    const result = runtime.submit({ input: 'late' });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('intelligence-closed');
+  });
+
+  it('accepts a transport-owned identity and provider session', () => {
+    const controlled = controlledProvider();
+    const runtime = createIntelligenceRuntime(controlled.provider);
+    const submission: ActivitySubmission = {
+      id: activityId('transport-owned'),
+      session: { providerId: 'test.provider', id: 'saved-session' },
+      input: 'next turn',
+    };
+    const result: Result<void, IntelligenceError> = runtime.accept(submission);
+    expect(result.ok).toBe(true);
+    expect(controlled.sinks.has(submission.id)).toBe(true);
+  });
+
+  it('contains synchronous provider start throws and permits same-runtime retry', () => {
+    const siblingId = activityId('sibling');
+    const failedId = activityId('failed');
+    const spareId = activityId('spare');
+    const failedSession = { providerId: 'test.provider', id: 'failed-session' };
+    const ids = [siblingId, failedId, spareId, failedId];
+    const sinks = new Map<ActivityId, ActivitySink>();
+    const starts = new Map<ActivityId, number>();
+    let throwOnFailedStart = true;
+    let cancelCalls = 0;
+    let closeCalls = 0;
+    const provider: IntelligenceProvider = {
+      id: 'test.provider',
+      start(submission, sink) {
+        starts.set(submission.id, (starts.get(submission.id) ?? 0) + 1);
+        if (submission.id === failedId && throwOnFailedStart) {
+          throw new Error('sentinel provider start failure');
+        }
+        sinks.set(submission.id, sink);
+        return ok(undefined);
+      },
+      cancel() {
+        cancelCalls += 1;
+        return ok(undefined);
+      },
+      async close() {
+        closeCalls += 1;
+      },
+    };
+    const runtime = createIntelligenceRuntime(provider, {
+      limits: { maxConcurrentActivities: 2 },
+      createActivityId: () => {
+        const id = ids.shift();
+        if (id === undefined) throw new Error('test activity identity exhausted');
+        return id;
+      },
+    });
+
+    const sibling = runtime.submit({ input: 'sibling' });
+    expect(sibling.ok).toBe(true);
+    if (!sibling.ok) return;
+    const siblingSink = sinks.get(sibling.value.id);
+    expect(siblingSink).toBeDefined();
+    siblingSink?.text('sibling');
+    expect(runtime.poll()).toEqual([
+      { type: 'text-delta', activityId: siblingId, sequence: 1, text: 'sibling' },
+    ]);
+
+    let refused: ReturnType<typeof runtime.submit> | undefined;
+    let rawThrow: unknown;
+    try {
+      refused = runtime.submit({ input: 'throw', session: failedSession });
+    } catch (error) {
+      rawThrow = error;
+    }
+    expect(rawThrow).toBeUndefined();
+    expect(refused?.ok).toBe(false);
+    if (refused === undefined || refused.ok) return;
+    expect(refused.error.code).toBe('intelligence-provider-failed');
+    if (refused.error.code === 'intelligence-provider-failed') {
+      expect(refused.error.detail.providerId).toBe(provider.id);
+      expect(refused.error.detail.cause).toBeInstanceOf(Error);
+      expect(refused.error.message).not.toContain('sentinel provider start failure');
+      expect(refused.error.hint).not.toContain('sentinel provider start failure');
+    }
+    expect(runtime.poll()).toEqual([]);
+    expect(sinks.has(failedId)).toBe(false);
+    expect(cancelCalls).toBe(0);
+    expect(closeCalls).toBe(0);
+
+    const spare = runtime.submit({ input: 'spare' });
+    expect(spare.ok).toBe(true);
+    if (!spare.ok) return;
+    sinks.get(spare.value.id)?.complete('spare');
+    expect(runtime.poll()).toEqual([
+      {
+        type: 'completed',
+        activityId: spareId,
+        sequence: 1,
+        session: spare.value.session,
+        output: 'spare',
+      },
+    ]);
+
+    throwOnFailedStart = false;
+    const retry = runtime.submit({ input: 'retry', session: failedSession });
+    expect(retry.ok).toBe(true);
+    if (!retry.ok) return;
+    expect(retry.value.id).toBe(failedId);
+    expect(retry.value.session).toBe(failedSession);
+    siblingSink?.complete('sibling-done');
+    sinks.get(retry.value.id)?.complete('retry-done');
+    expect(runtime.poll()).toEqual([
+      {
+        type: 'completed',
+        activityId: siblingId,
+        sequence: 2,
+        session: sibling.value.session,
+        output: 'sibling-done',
+      },
+      {
+        type: 'completed',
+        activityId: failedId,
+        sequence: 1,
+        session: failedSession,
+        output: 'retry-done',
+      },
+    ]);
+    expect(runtime.poll()).toEqual([]);
+    expect(starts.get(siblingId)).toBe(1);
+    expect(starts.get(failedId)).toBe(2);
+    expect(starts.get(spareId)).toBe(1);
+    expect(cancelCalls).toBe(0);
+
+    const close = runtime.close();
+    expect(close).toBe(runtime.close());
+    return close.then(() => {
+      expect(closeCalls).toBe(1);
+      expect(runtime.poll()).toEqual([]);
+    });
+  });
+
+  it('contains synchronous provider cancel throws and preserves the same Activity for retry', () => {
+    const siblingId = activityId('cancel-sibling');
+    const failedId = activityId('cancel-failed');
+    const spareId = activityId('cancel-spare');
+    const failedSession = { providerId: 'cancel.throw.provider', id: 'failed-session' };
+    const ids = [siblingId, failedId, spareId];
+    const sinks = new Map<ActivityId, ActivitySink>();
+    const starts = new Map<ActivityId, number>();
+    const cancelCalls: ActivityId[] = [];
+    const sentinel = new Error('sentinel provider cancel failure');
+    let throwOnFailedCancel = true;
+    const provider: IntelligenceProvider = {
+      id: 'cancel.throw.provider',
+      start(submission, sink) {
+        starts.set(submission.id, (starts.get(submission.id) ?? 0) + 1);
+        sinks.set(submission.id, sink);
+        return ok(undefined);
+      },
+      cancel(activity) {
+        cancelCalls.push(activity);
+        if (activity === failedId && throwOnFailedCancel) throw sentinel;
+        const sink = sinks.get(activity);
+        if (sink === undefined) {
+          return err(
+            new IntelligenceError({
+              code: 'intelligence-activity-not-found',
+              detail: { activityId: activity },
+            }),
+          );
+        }
+        sinks.delete(activity);
+        sink.cancelled();
+        return ok(undefined);
+      },
+      async close() {},
+    };
+    const runtime = createIntelligenceRuntime(provider, {
+      limits: { maxConcurrentActivities: 2 },
+      createActivityId: () => {
+        const id = ids.shift();
+        if (id === undefined) throw new Error('test activity identity exhausted');
+        return id;
+      },
+    });
+
+    const sibling = runtime.submit({ input: 'sibling' });
+    const failed = runtime.submit({ input: 'cancel', session: failedSession });
+    expect(sibling.ok).toBe(true);
+    expect(failed.ok).toBe(true);
+    if (!sibling.ok || !failed.ok) return;
+    expect(runtime.poll()).toEqual([]);
+
+    let rawThrow: unknown;
+    let refused: ReturnType<typeof runtime.cancel> | undefined;
+    try {
+      refused = runtime.cancel(failed.value.id);
+    } catch (error) {
+      rawThrow = error;
+    }
+    expect(rawThrow).toBeUndefined();
+    expect(refused?.ok).toBe(false);
+    if (refused === undefined || refused.ok) return;
+    expect(refused.error.code).toBe('intelligence-provider-failed');
+    if (refused.error.code === 'intelligence-provider-failed') {
+      expect(refused.error.detail.providerId).toBe(provider.id);
+      expect(refused.error.detail.cause).toBe(sentinel);
+      expect(refused.error.message).not.toContain(sentinel.message);
+      expect(refused.error.hint).not.toContain(sentinel.message);
+    }
+    expect(cancelCalls).toEqual([failedId]);
+    expect(runtime.poll()).toEqual([]);
+
+    const spare = runtime.submit({ input: 'spare' });
+    expect(spare.ok).toBe(false);
+    if (!spare.ok) expect(spare.error.code).toBe('intelligence-capacity-exceeded');
+    expect(starts.has(spareId)).toBe(false);
+
+    const siblingSink = sinks.get(sibling.value.id);
+    expect(siblingSink).toBeDefined();
+    siblingSink?.text('healthy');
+    expect(runtime.poll()).toEqual([
+      { type: 'text-delta', activityId: siblingId, sequence: 1, text: 'healthy' },
+    ]);
+
+    throwOnFailedCancel = false;
+    const retried = runtime.cancel(failed.value.id);
+    expect(retried.ok).toBe(true);
+    expect(cancelCalls).toEqual([failedId, failedId]);
+    expect(runtime.poll()).toEqual([{ type: 'cancelled', activityId: failedId, sequence: 1 }]);
+    const afterCancel = runtime.cancel(failed.value.id);
+    expect(afterCancel.ok).toBe(false);
+    if (!afterCancel.ok) expect(afterCancel.error.code).toBe('intelligence-activity-not-found');
+
+    siblingSink?.complete('healthy-done');
+    expect(runtime.poll()).toEqual([
+      {
+        type: 'completed',
+        activityId: siblingId,
+        sequence: 2,
+        session: sibling.value.session,
+        output: 'healthy-done',
+      },
+    ]);
+    expect(starts.get(siblingId)).toBe(1);
+    expect(starts.get(failedId)).toBe(1);
+  });
+
+  it('contains a throwing overflow cancellation and preserves provider Result errors', () => {
+    const siblingId = activityId('overflow-sibling');
+    const returnedId = activityId('returned-cancel-error');
+    const overflowId = activityId('overflow-throw');
+    const ids = [siblingId, returnedId, overflowId];
+    const sinks = new Map<ActivityId, ActivitySink>();
+    const cancelCalls: ActivityId[] = [];
+    const overflowSentinel = new Error('sentinel overflow cancel failure');
+    const returnedError = new IntelligenceError({
+      code: 'intelligence-provider-failed',
+      detail: { providerId: 'inner.provider', cause: 'provider returned error' },
+    });
+    const returnedResult = err(returnedError);
+    const provider: IntelligenceProvider = {
+      id: 'overflow.throw.provider',
+      start(submission, sink) {
+        sinks.set(submission.id, sink);
+        return ok(undefined);
+      },
+      cancel(activity) {
+        cancelCalls.push(activity);
+        if (activity === returnedId) return returnedResult;
+        if (activity === overflowId) throw overflowSentinel;
+        const sink = sinks.get(activity);
+        if (sink === undefined) {
+          return err(
+            new IntelligenceError({
+              code: 'intelligence-activity-not-found',
+              detail: { activityId: activity },
+            }),
+          );
+        }
+        sinks.delete(activity);
+        sink.cancelled();
+        return ok(undefined);
+      },
+      async close() {},
+    };
+    const runtime = createIntelligenceRuntime(provider, {
+      limits: { maxPendingEventsPerActivity: 2, maxConcurrentActivities: 3 },
+      createActivityId: () => {
+        const id = ids.shift();
+        if (id === undefined) throw new Error('test activity identity exhausted');
+        return id;
+      },
+    });
+
+    const sibling = runtime.submit({ input: 'sibling' });
+    const returned = runtime.submit({ input: 'returned' });
+    const overflow = runtime.submit({ input: 'overflow' });
+    expect(sibling.ok).toBe(true);
+    expect(returned.ok).toBe(true);
+    expect(overflow.ok).toBe(true);
+    if (!sibling.ok || !returned.ok || !overflow.ok) return;
+
+    const returnedCancel = runtime.cancel(returned.value.id);
+    expect(returnedCancel).toBe(returnedResult);
+    expect(runtime.poll()).toEqual([]);
+    sinks.get(returned.value.id)?.complete('returned-retry');
+    expect(runtime.poll()).toEqual([
+      {
+        type: 'completed',
+        activityId: returnedId,
+        sequence: 1,
+        session: returned.value.session,
+        output: 'returned-retry',
+      },
+    ]);
+
+    const overflowSink = sinks.get(overflow.value.id);
+    expect(overflowSink).toBeDefined();
+    overflowSink?.text('first');
+    let rawThrow: unknown;
+    try {
+      overflowSink?.text('second');
+    } catch (error) {
+      rawThrow = error;
+    }
+    expect(rawThrow).toBeUndefined();
+    const events = runtime.poll();
+    expect(events).toHaveLength(2);
+    expect(events.filter((event) => event.type === 'failed')).toHaveLength(1);
+    expect(events[0]).toEqual({
+      type: 'text-delta',
+      activityId: overflowId,
+      sequence: 1,
+      text: 'first',
+    });
+    const overflowEvent = events[1];
+    expect(overflowEvent?.type).toBe('failed');
+    if (overflowEvent?.type === 'failed') {
+      expect(overflowEvent.error.code).toBe('intelligence-output-overflow');
+      if (overflowEvent.error.code === 'intelligence-output-overflow') {
+        expect(overflowEvent.error.detail).toEqual({
+          activityId: overflowId,
+          bound: 'pending-events',
+          limit: 2,
+        });
+      }
+    }
+    expect(cancelCalls).toEqual([returnedId, overflowId]);
+
+    const siblingSink = sinks.get(sibling.value.id);
+    siblingSink?.text('sibling-alive');
+    expect(runtime.poll()).toEqual([
+      { type: 'text-delta', activityId: siblingId, sequence: 1, text: 'sibling-alive' },
+    ]);
+    siblingSink?.complete('sibling-done');
+    expect(runtime.poll()).toEqual([
+      {
+        type: 'completed',
+        activityId: siblingId,
+        sequence: 2,
+        session: sibling.value.session,
+        output: 'sibling-done',
+      },
+    ]);
+  });
+});

package/src/__tests__/transport.test.ts

@@ -0,0 +1,130 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createIntelligenceRuntime } from '../runtime';
+import {
+  bindIntelligencePort,
+  createIntelligencePortClient,
+  type IntelligenceMessagePort,
+} from '../transport';
+import { type ActivitySink, activityId, type IntelligenceProvider } from '../types';
+
+describe('intelligence MessagePort boundary', () => {
+  it('moves only structured-cloneable POD across a Worker-style channel', async () => {
+    const sinks: ActivitySink[] = [];
+    let providerClosed = false;
+    const provider: IntelligenceProvider = {
+      id: 'port.provider',
+      start(_submission, sink) {
+        sinks.push(sink);
+        return ok(undefined);
+      },
+      cancel() {
+        sinks[0]?.cancelled();
+        return ok(undefined);
+      },
+      async close() {
+        providerClosed = true;
+      },
+    };
+    const runtime = createIntelligenceRuntime(provider);
+    const channel = new MessageChannel();
+    const host = bindIntelligencePort(channel.port1 as unknown as IntelligenceMessagePort, runtime);
+    const client = createIntelligencePortClient(
+      'port.provider',
+      channel.port2 as unknown as IntelligenceMessagePort,
+      {
+        createActivityId: () => activityId('worker-activity'),
+        createSessionId: () => 'worker-session',
+      },
+    );
+
+    const started = client.submit({ input: 'hello worker' });
+    expect(started.ok).toBe(true);
+    for (let attempt = 0; attempt < 10 && sinks.length === 0; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    expect(sinks).toHaveLength(1);
+    sinks[0]?.text('hello ');
+    sinks[0]?.complete('hello worker');
+    const received = [] as ReturnType<typeof client.poll>[number][];
+    for (let attempt = 0; attempt < 10 && received.length === 0; attempt += 1) {
+      received.push(...client.poll());
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    expect(structuredClone(received)).toEqual([
+      {
+        type: 'text-delta',
+        activityId: 'worker-activity',
+        sequence: 1,
+        text: 'hello ',
+      },
+      {
+        type: 'completed',
+        activityId: 'worker-activity',
+        sequence: 2,
+        session: { providerId: 'port.provider', id: 'worker-session' },
+        output: 'hello worker',
+      },
+    ]);
+
+    await client.close();
+    expect(providerClosed).toBe(true);
+    await host.close();
+  });
+
+  it('bounds realm submissions and releases capacity after a terminal event', async () => {
+    const sinks = new Map<string, ActivitySink>();
+    const provider: IntelligenceProvider = {
+      id: 'bounded.provider',
+      start(submission, sink) {
+        sinks.set(submission.id, sink);
+        return ok(undefined);
+      },
+      cancel(id) {
+        sinks.get(id)?.cancelled();
+        sinks.delete(id);
+        return ok(undefined);
+      },
+      async close() {},
+    };
+    const runtime = createIntelligenceRuntime(provider, {
+      limits: { maxConcurrentActivities: 1 },
+    });
+    const channel = new MessageChannel();
+    const host = bindIntelligencePort(channel.port1 as unknown as IntelligenceMessagePort, runtime);
+    let identity = 0;
+    const client = createIntelligencePortClient(
+      'bounded.provider',
+      channel.port2 as unknown as IntelligenceMessagePort,
+      {
+        limits: { maxConcurrentActivities: 1 },
+        createActivityId: () => {
+          identity += 1;
+          return activityId(`bounded-${identity}`);
+        },
+      },
+    );
+
+    const first = client.submit({ input: 'first' });
+    expect(first.ok).toBe(true);
+    const second = client.submit({ input: 'second' });
+    expect(second.ok).toBe(false);
+    if (!second.ok) expect(second.error.code).toBe('intelligence-capacity-exceeded');
+
+    client.poll();
+    client.poll();
+    for (let attempt = 0; attempt < 10 && sinks.size === 0; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    if (!first.ok) return;
+    sinks.get(first.value.id)?.complete('done');
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      client.poll();
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    expect(client.submit({ input: 'after terminal' }).ok).toBe(true);
+
+    await client.close();
+    await host.close();
+  });
+});