@forgeax/engine-intelligence 0.0.0-dev.8d955ade1c79

package/src/errors.ts

@@ -0,0 +1,154 @@
+import type { ActivityId } from './types';
+
+export type IntelligenceErrorCode =
+  | 'intelligence-invalid-request'
+  | 'intelligence-session-provider-mismatch'
+  | 'intelligence-capacity-exceeded'
+  | 'intelligence-activity-not-found'
+  | 'intelligence-provider-failed'
+  | 'intelligence-output-overflow'
+  | 'intelligence-closed';
+
+export interface IntelligenceErrorDetailMap {
+  readonly 'intelligence-invalid-request': { readonly field: 'input'; readonly reason: string };
+  readonly 'intelligence-session-provider-mismatch': {
+    readonly expectedProviderId: string;
+    readonly receivedProviderId: string;
+  };
+  readonly 'intelligence-capacity-exceeded': { readonly limit: number };
+  readonly 'intelligence-activity-not-found': { readonly activityId: ActivityId };
+  readonly 'intelligence-provider-failed': { readonly providerId: string; readonly cause: unknown };
+  readonly 'intelligence-output-overflow': {
+    readonly activityId: ActivityId;
+    readonly bound: 'output-chars' | 'pending-events';
+    readonly limit: number;
+  };
+  readonly 'intelligence-closed': Readonly<Record<string, never>>;
+}
+
+export type IntelligenceErrorDetailFor<C extends IntelligenceErrorCode> =
+  IntelligenceErrorDetailMap[C];
+
+const policy = {
+  'intelligence-invalid-request': {
+    expected: 'activity input must be a non-empty string within the configured bound',
+    hint: 'validate and bound player input before submitting the activity',
+  },
+  'intelligence-session-provider-mismatch': {
+    expected: 'a session reference must be resumed by the provider that created it',
+    hint: 'discard the incompatible session or select its original provider',
+  },
+  'intelligence-capacity-exceeded': {
+    expected: 'active intelligence work must remain within the configured concurrency bound',
+    hint: 'wait for an activity to finish or raise the explicit provider capacity',
+  },
+  'intelligence-activity-not-found': {
+    expected: 'the activity must still be running when cancellation is requested',
+    hint: 'ignore an already observed terminal activity or retain the correct ActivityId',
+  },
+  'intelligence-provider-failed': {
+    expected: 'the selected provider must complete or report a structured failure',
+    hint: 'inspect detail.cause and provider configuration, then retry or select another provider',
+  },
+  'intelligence-output-overflow': {
+    expected: 'incremental and final output must remain within configured queue and text bounds',
+    hint: 'consume events every frame or raise the explicit bound for this application',
+  },
+  'intelligence-closed': {
+    expected: 'the intelligence service must be open for submit and cancel operations',
+    hint: 'create a new service after its Cordis realm or owner has been disposed',
+  },
+} satisfies Record<IntelligenceErrorCode, { readonly expected: string; readonly hint: string }>;
+
+export const INTELLIGENCE_EXPECTED = Object.fromEntries(
+  Object.entries(policy).map(([code, value]) => [code, value.expected]),
+) as Readonly<Record<IntelligenceErrorCode, string>>;
+
+export const INTELLIGENCE_ERROR_HINTS = Object.fromEntries(
+  Object.entries(policy).map(([code, value]) => [code, value.hint]),
+) as Readonly<Record<IntelligenceErrorCode, string>>;
+
+class IntelligenceErrorClass extends Error {
+  readonly code: IntelligenceErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: IntelligenceErrorDetailFor<IntelligenceErrorCode>;
+
+  constructor(args: {
+    code: IntelligenceErrorCode;
+    detail: IntelligenceErrorDetailFor<IntelligenceErrorCode>;
+  }) {
+    const selected = policy[args.code];
+    super(
+      `[IntelligenceError ${args.code}] expected: ${selected.expected}; hint: ${selected.hint}`,
+    );
+    this.name = 'IntelligenceError';
+    this.code = args.code;
+    this.expected = selected.expected;
+    this.hint = selected.hint;
+    this.detail = args.detail;
+  }
+}
+
+type IntelligenceErrorVariant<C extends IntelligenceErrorCode> = IntelligenceErrorClass & {
+  readonly code: C;
+  readonly detail: IntelligenceErrorDetailFor<C>;
+};
+
+export type IntelligenceError = {
+  [C in IntelligenceErrorCode]: IntelligenceErrorVariant<C>;
+}[IntelligenceErrorCode];
+
+interface IntelligenceErrorConstructor {
+  new <C extends IntelligenceErrorCode>(args: {
+    code: C;
+    detail: IntelligenceErrorDetailFor<C>;
+  }): IntelligenceErrorVariant<C>;
+  readonly prototype: IntelligenceErrorClass;
+}
+
+export const IntelligenceError: IntelligenceErrorConstructor =
+  IntelligenceErrorClass as unknown as IntelligenceErrorConstructor;
+
+type PodDetailMap = Omit<IntelligenceErrorDetailMap, 'intelligence-provider-failed'> & {
+  readonly 'intelligence-provider-failed': { readonly providerId: string; readonly cause: string };
+};
+
+export type IntelligenceFailure = {
+  [C in IntelligenceErrorCode]: {
+    readonly code: C;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PodDetailMap[C];
+  };
+}[IntelligenceErrorCode];
+
+export function intelligenceFailure(error: IntelligenceError): IntelligenceFailure {
+  if (error.code === 'intelligence-provider-failed') {
+    return {
+      code: error.code,
+      expected: error.expected,
+      hint: error.hint,
+      detail: {
+        providerId: error.detail.providerId,
+        cause:
+          error.detail.cause instanceof Error
+            ? error.detail.cause.message
+            : String(error.detail.cause),
+      },
+    };
+  }
+  return {
+    code: error.code,
+    expected: error.expected,
+    hint: error.hint,
+    detail: error.detail,
+  } as IntelligenceFailure;
+}
+
+export function providerError(providerId: string, cause: unknown): IntelligenceError {
+  return new IntelligenceError({
+    code: 'intelligence-provider-failed',
+    detail: { providerId, cause },
+  });
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export {
+  INTELLIGENCE_ERROR_HINTS,
+  INTELLIGENCE_EXPECTED,
+  IntelligenceError,
+  type IntelligenceErrorCode,
+  type IntelligenceErrorDetailFor,
+  type IntelligenceFailure,
+  intelligenceFailure,
+  providerError,
+} from './errors';
+export { intelligencePlugin } from './plugin';
+export { createIntelligenceRuntime, IntelligenceRuntime } from './runtime';
+export {
+  bindIntelligencePort,
+  createIntelligencePortClient,
+  type IntelligenceHostCommand,
+  type IntelligenceMessagePort,
+  type IntelligencePortBinding,
+  IntelligencePortClient,
+  type IntelligenceRealmMessage,
+} from './transport';
+export {
+  type ActivityEvent,
+  type ActivityId,
+  type ActivityRef,
+  type ActivityRequest,
+  type ActivitySink,
+  type ActivitySubmission,
+  activityId,
+  DEFAULT_INTELLIGENCE_LIMITS,
+  type IntelligenceLimits,
+  type IntelligenceProvider,
+  type IntelligenceRuntimeOptions,
+  type IntelligenceService,
+  type SessionRef,
+} from './types';

package/src/plugin.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { IntelligenceService } from './types';
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    intelligence?: IntelligenceService;
+  }
+}
+
+/** Install one optional intelligence service and bind its lifetime to this Cordis Fiber. */
+export function intelligencePlugin(service: IntelligenceService): Plugin {
+  return {
+    name: 'intelligence',
+    provide: 'intelligence',
+    apply(ctx) {
+      ctx.provide('intelligence', service);
+      ctx.effect(() => () => service.close(), 'intelligence/service');
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,297 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { IntelligenceError, intelligenceFailure, providerError } from './errors';
+import {
+  type ActivityEvent,
+  type ActivityId,
+  type ActivityRef,
+  type ActivityRequest,
+  type ActivitySink,
+  type ActivitySubmission,
+  activityId,
+  DEFAULT_INTELLIGENCE_LIMITS,
+  type IntelligenceLimits,
+  type IntelligenceProvider,
+  type IntelligenceRuntimeOptions,
+  type IntelligenceService,
+} from './types';
+
+interface ActivityRecord {
+  readonly ref: ActivityRef;
+  readonly events: ActivityEvent[];
+  sequence: number;
+  outputChars: number;
+  terminal: boolean;
+}
+
+let fallbackIdentity = 0;
+
+function nextIdentity(prefix: string): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid !== undefined) return `${prefix}-${uuid}`;
+  fallbackIdentity += 1;
+  return `${prefix}-${Date.now().toString(36)}-${fallbackIdentity.toString(36)}`;
+}
+
+export function resolveIntelligenceLimits(
+  overrides: Partial<IntelligenceLimits> | undefined,
+): IntelligenceLimits {
+  const limits = { ...DEFAULT_INTELLIGENCE_LIMITS, ...overrides };
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new RangeError(`${name} must be a positive integer`);
+    }
+  }
+  if (limits.maxPendingEventsPerActivity < 2) {
+    throw new RangeError(
+      'maxPendingEventsPerActivity must reserve at least one data and terminal event',
+    );
+  }
+  return limits;
+}
+
+export class IntelligenceRuntime implements IntelligenceService {
+  readonly providerId: string;
+  readonly limits: IntelligenceLimits;
+  private readonly records = new Map<ActivityId, ActivityRecord>();
+  private readonly createActivityId: () => ActivityId;
+  private readonly createSessionId: () => string;
+  private closed = false;
+  private closeTask: Promise<void> | undefined;
+
+  constructor(
+    private readonly provider: IntelligenceProvider,
+    options: IntelligenceRuntimeOptions = {},
+  ) {
+    this.providerId = provider.id;
+    this.limits = resolveIntelligenceLimits(options.limits);
+    this.createActivityId =
+      options.createActivityId ?? (() => activityId(nextIdentity('activity')));
+    this.createSessionId = options.createSessionId ?? (() => nextIdentity('session'));
+  }
+
+  submit(request: ActivityRequest): Result<ActivityRef, IntelligenceError> {
+    const validated = this.validateRequest(request);
+    if (!validated.ok) return validated;
+    const ref: ActivityRef = {
+      id: this.createActivityId(),
+      session: request.session ?? { providerId: this.providerId, id: this.createSessionId() },
+    };
+    const accepted = this.accept({ ...ref, input: request.input });
+    return accepted.ok ? ok(ref) : accepted;
+  }
+
+  /** Accept an already identified request from a realm transport. */
+  accept(submission: ActivitySubmission): Result<void, IntelligenceError> {
+    const validated = this.validateRequest({
+      input: submission.input,
+      session: submission.session,
+    });
+    if (!validated.ok) return validated;
+    if (this.records.has(submission.id)) {
+      return err(
+        providerError(this.providerId, `duplicate activity identity: ${String(submission.id)}`),
+      );
+    }
+    if (this.runningCount >= this.limits.maxConcurrentActivities) {
+      return err(
+        new IntelligenceError({
+          code: 'intelligence-capacity-exceeded',
+          detail: { limit: this.limits.maxConcurrentActivities },
+        }),
+      );
+    }
+    const record: ActivityRecord = {
+      ref: { id: submission.id, session: submission.session },
+      events: [],
+      sequence: 0,
+      outputChars: 0,
+      terminal: false,
+    };
+    this.records.set(submission.id, record);
+    let started: Result<void, IntelligenceError>;
+    try {
+      started = this.provider.start(submission, this.createSink(record));
+    } catch (cause) {
+      this.records.delete(submission.id);
+      return err(providerError(this.providerId, cause));
+    }
+    if (!started.ok) {
+      this.records.delete(submission.id);
+      return started;
+    }
+    return ok(undefined);
+  }
+
+  poll(maxEvents = this.limits.maxPollEvents): readonly ActivityEvent[] {
+    if (!Number.isInteger(maxEvents) || maxEvents <= 0) return [];
+    const bounded = Math.min(maxEvents, this.limits.maxPollEvents);
+    const events: ActivityEvent[] = [];
+    for (const [id, record] of this.records) {
+      while (record.events.length > 0 && events.length < bounded) {
+        const event = record.events.shift();
+        if (event !== undefined) events.push(event);
+      }
+      if (record.terminal && record.events.length === 0) this.records.delete(id);
+      if (events.length === bounded) break;
+    }
+    return events;
+  }
+
+  cancel(activity: ActivityId): Result<void, IntelligenceError> {
+    if (this.closed) return err(this.closedError());
+    const record = this.records.get(activity);
+    if (record === undefined || record.terminal) {
+      return err(
+        new IntelligenceError({
+          code: 'intelligence-activity-not-found',
+          detail: { activityId: activity },
+        }),
+      );
+    }
+    try {
+      return this.provider.cancel(activity);
+    } catch (cause) {
+      return err(providerError(this.providerId, cause));
+    }
+  }
+
+  close(): Promise<void> {
+    this.closeTask ??= this.performClose();
+    return this.closeTask;
+  }
+
+  private async performClose(): Promise<void> {
+    this.closed = true;
+    try {
+      await this.provider.close();
+    } catch {
+      // Disposal is terminal; provider failure must not strand the realm transport.
+    }
+    this.records.clear();
+  }
+
+  private get runningCount(): number {
+    let count = 0;
+    for (const record of this.records.values()) if (!record.terminal) count += 1;
+    return count;
+  }
+
+  private validateRequest(request: ActivityRequest): Result<void, IntelligenceError> {
+    if (this.closed) return err(this.closedError());
+    if (request.input.length === 0 || request.input.length > this.limits.maxInputChars) {
+      return err(
+        new IntelligenceError({
+          code: 'intelligence-invalid-request',
+          detail: {
+            field: 'input',
+            reason:
+              request.input.length === 0
+                ? 'input is empty'
+                : `input exceeds ${this.limits.maxInputChars} characters`,
+          },
+        }),
+      );
+    }
+    if (request.session !== undefined && request.session.providerId !== this.providerId) {
+      return err(
+        new IntelligenceError({
+          code: 'intelligence-session-provider-mismatch',
+          detail: {
+            expectedProviderId: this.providerId,
+            receivedProviderId: request.session.providerId,
+          },
+        }),
+      );
+    }
+    return ok(undefined);
+  }
+
+  private createSink(record: ActivityRecord): ActivitySink {
+    return {
+      text: (text) => {
+        if (this.closed || record.terminal || text.length === 0) return;
+        if (record.outputChars + text.length > this.limits.maxOutputChars) {
+          this.overflow(record, 'output-chars', this.limits.maxOutputChars);
+          return;
+        }
+        if (record.events.length >= this.limits.maxPendingEventsPerActivity - 1) {
+          this.overflow(record, 'pending-events', this.limits.maxPendingEventsPerActivity);
+          return;
+        }
+        record.outputChars += text.length;
+        this.push(record, { type: 'text-delta', text });
+      },
+      complete: (output) => {
+        if (this.closed || record.terminal) return;
+        if (output.length > this.limits.maxOutputChars) {
+          this.overflow(record, 'output-chars', this.limits.maxOutputChars);
+          return;
+        }
+        record.terminal = true;
+        this.push(record, { type: 'completed', session: record.ref.session, output });
+      },
+      fail: (cause) => {
+        if (this.closed || record.terminal) return;
+        record.terminal = true;
+        const error = providerError(this.providerId, cause);
+        this.push(record, { type: 'failed', error: intelligenceFailure(error) });
+      },
+      cancelled: () => {
+        if (this.closed || record.terminal) return;
+        record.terminal = true;
+        this.push(record, { type: 'cancelled' });
+      },
+    };
+  }
+
+  private overflow(
+    record: ActivityRecord,
+    bound: 'output-chars' | 'pending-events',
+    limit: number,
+  ): void {
+    if (record.terminal) return;
+    record.terminal = true;
+    const error = new IntelligenceError({
+      code: 'intelligence-output-overflow',
+      detail: { activityId: record.ref.id, bound, limit },
+    });
+    if (record.events.length >= this.limits.maxPendingEventsPerActivity) record.events.pop();
+    this.push(record, { type: 'failed', error: intelligenceFailure(error) });
+    try {
+      this.provider.cancel(record.ref.id);
+    } catch {
+      // The overflow terminal already owns the activity outcome.
+    }
+  }
+
+  private push(
+    record: ActivityRecord,
+    event:
+      | { readonly type: 'text-delta'; readonly text: string }
+      | {
+          readonly type: 'completed';
+          readonly session: ActivityRef['session'];
+          readonly output: string;
+        }
+      | { readonly type: 'failed'; readonly error: ReturnType<typeof intelligenceFailure> }
+      | { readonly type: 'cancelled' },
+  ): void {
+    record.sequence += 1;
+    record.events.push({
+      ...event,
+      activityId: record.ref.id,
+      sequence: record.sequence,
+    } as ActivityEvent);
+  }
+
+  private closedError(): IntelligenceError {
+    return new IntelligenceError({ code: 'intelligence-closed', detail: {} });
+  }
+}
+
+export function createIntelligenceRuntime(
+  provider: IntelligenceProvider,
+  options: IntelligenceRuntimeOptions = {},
+): IntelligenceRuntime {
+  return new IntelligenceRuntime(provider, options);
+}