@electric-ax/agents-server-conformance-tests 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,540 @@
+import { StreamFn } from "@mariozechner/pi-agent-core";
+
+//#region src/electric-agents-tests.d.ts
+/**
+* Conformance tests for the Electric Agents entity runtime.
+*
+* Uses the electricAgents() DSL for declarative scenario-based testing.
+* Each test first registers an entity type before spawning entities.
+*
+* Spec reference: docs/electric-agents-spec.md
+*/
+/**
+ * Conformance tests for the Electric Agents entity runtime.
+ *
+ * Uses the electricAgents() DSL for declarative scenario-based testing.
+ * Each test first registers an entity type before spawning entities.
+ *
+ * Spec reference: docs/electric-agents-spec.md
+ */
+interface ElectricAgentsTestOptions {
+  baseUrl: string;
+}
+declare function runElectricAgentsConformanceTests(config: ElectricAgentsTestOptions): void;
+interface CliTestOptions {
+  baseUrl: string;
+  cliBin: string;
+}
+declare function runCliConformanceTests(config: CliTestOptions): void;
+interface MockAgentTestOptions {
+  baseUrl: string;
+}
+declare function runMockAgentTests(config: MockAgentTestOptions): void;
+interface MockAgentCliTestOptions {
+  baseUrl: string;
+  cliBin: string;
+}
+declare function runMockAgentCliTests(config: MockAgentCliTestOptions): void; //#endregion
+//#region src/electric-agents-dsl.d.ts
+/**
+ * Electric Agents testing DSL — fluent builder, history recorder, and invariant checkers.
+ *
+ * Usage:
+ *   await electricAgents(baseUrl)
+ *     .subscription('/agents/**', 'agent-handler')
+ *     .spawn('/agents/task-1')
+ *     .send({ text: 'hello' })
+ *     .expectWebhook()
+ *     .expectEntityContext()
+ *     .respondDone()
+ *     .expectStatus('running')
+ *     .kill()
+ *     .expectStatus('stopped')
+ *     .run()
+ */
+type HistoryEvent = {
+  type: `subscription_created`;
+  pattern: string;
+  subscriptionId: string;
+  webhookUrl: string;
+} | {
+  type: `entity_spawned`;
+  entityUrl: string;
+  entityType?: string;
+  status: string;
+  streams: {
+    main: string;
+    error: string;
+  };
+  parent?: string;
+} | {
+  type: `message_sent`;
+  entityUrl: string;
+  payload: unknown;
+  from?: string;
+} | {
+  type: `webhook_received`;
+  consumer_id: string;
+  epoch: number;
+  wake_id: string;
+  entity?: WebhookEntityContext;
+  trigger_event?: string;
+} | {
+  type: `webhook_responded`;
+  status: number;
+  body: unknown;
+} | {
+  type: `entity_status_checked`;
+  entityUrl: string;
+  status: string;
+} | {
+  type: `entity_killed`;
+  entityUrl: string;
+} | {
+  type: `entity_list_fetched`;
+  count: number;
+  filter?: {
+    type?: string;
+    status?: string;
+  };
+} | {
+  type: `stream_read`;
+  path: string;
+  messageCount: number;
+} | {
+  type: `send_rejected`;
+  entityUrl: string;
+  status: number;
+  code: string;
+} | {
+  type: `spawn_rejected`;
+  url: string;
+  status: number;
+  code: string;
+} | {
+  type: `entity_type_registered`;
+  name: string;
+  revision: number;
+} | {
+  type: `entity_type_inspected`;
+  name: string;
+  revision: number;
+} | {
+  type: `entity_type_deleted`;
+  name: string;
+} | {
+  type: `entity_type_schemas_amended`;
+  name: string;
+  revision: number;
+} | {
+  type: `entity_write`;
+  entityUrl: string;
+  eventType?: string;
+  payload: unknown;
+} | {
+  type: `tags_updated`;
+  entityUrl: string;
+  tags: Record<string, string>;
+} | {
+  type: `tags_checked`;
+  entityUrl: string;
+  tags: Record<string, string>;
+} | {
+  type: `spawn_schema_rejected`;
+  typeName: string;
+  instanceId: string;
+  status: number;
+  code: string;
+} | {
+  type: `send_schema_rejected`;
+  entityUrl: string;
+  messageType: string;
+  status: number;
+  code: string;
+} | {
+  type: `write_schema_rejected`;
+  entityUrl: string;
+  eventType: string;
+  status: number;
+  code: string;
+} | {
+  type: `send_unknown_type_rejected`;
+  entityUrl: string;
+  messageType: string;
+  status: number;
+  code: string;
+} | {
+  type: `write_unknown_type_rejected`;
+  entityUrl: string;
+  eventType: string;
+  status: number;
+  code: string;
+} | {
+  type: `entity_persisted_verified`;
+  entityUrl: string;
+} | {
+  type: `state_protocol_write`;
+  entityUrl: string;
+  eventType: string;
+  key: string;
+};
+interface WebhookEntityContext {
+  type?: string;
+  status: string;
+  url: string;
+  streams: {
+    main: string;
+    error: string;
+  };
+  tags?: Record<string, string>;
+}
+interface EntityTypeRegistration {
+  name: string;
+  description: string;
+  creation_schema?: Record<string, unknown>;
+  input_schemas?: Record<string, Record<string, unknown>>;
+  output_schemas?: Record<string, Record<string, unknown>>;
+  inbox_schemas?: Record<string, Record<string, unknown>>;
+  state_schemas?: Record<string, Record<string, unknown>>;
+  metadata_schema?: Record<string, unknown>;
+  serve_endpoint?: string;
+}
+interface ElectricAgentsStreamValue {
+  from?: string;
+  payload?: unknown;
+  [key: string]: unknown;
+}
+interface ElectricAgentsStreamEvent {
+  type: string;
+  key?: string;
+  value?: ElectricAgentsStreamValue;
+  headers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+interface WebhookNotification {
+  body: string;
+  parsed: {
+    consumer_id: string;
+    epoch: number;
+    wake_id: string;
+    primary_stream: string;
+    streams: Array<{
+      path: string;
+      offset: string;
+    }>;
+    triggered_by: Array<string>;
+    callback: string;
+    token: string;
+    entity?: WebhookEntityContext;
+    trigger_event?: string;
+  };
+  resolve: (response: {
+    status: number;
+    body: string;
+  }) => void;
+}
+declare class WebhookReceiver {
+  private server;
+  private _url;
+  private notifications;
+  private waitResolvers;
+  private consumedCount;
+  start(): Promise<string>;
+  stop(): Promise<void>;
+  get url(): string;
+  private handleRequest;
+  waitForNotification(timeoutMs?: number): Promise<WebhookNotification>;
+  expectNoNotification(timeoutMs?: number): Promise<void>;
+  get received(): Array<WebhookNotification>;
+}
+declare class ServeEndpointReceiver {
+  private server;
+  private _url;
+  private manifest;
+  start(manifest: EntityTypeRegistration): Promise<string>;
+  stop(): Promise<void>;
+  get url(): string;
+  private handleRequest;
+}
+interface ExpectWebhookOpts {
+  timeoutMs?: number;
+}
+interface EntityContextChecks {
+  url?: string;
+  type?: string;
+  status?: string;
+}
+interface RunContext {
+  baseUrl: string;
+  receiver: WebhookReceiver;
+  history: Array<HistoryEvent>;
+  subscriptions: Array<{
+    pattern: string;
+    id: string;
+  }>;
+  currentEntityUrl: string | null;
+  currentEntityStreams: {
+    main: string;
+    error: string;
+  } | null;
+  currentWriteToken: string | null;
+  notification: WebhookNotification | null;
+  lastListResult: Array<{
+    url: string;
+    type: string;
+    status: string;
+    [key: string]: unknown;
+  }> | null;
+  lastListTotal: number | null;
+  lastStreamMessages: Array<ElectricAgentsStreamEvent> | null;
+  currentEntityType: string | null;
+  lastTypeResult: Record<string, unknown> | null;
+  lastTypeListResult: Array<{
+    name: string;
+    description: string | null;
+    [key: string]: unknown;
+  }> | null;
+  serveReceiver: ServeEndpointReceiver | null;
+}
+declare class ElectricAgentsScenario {
+  private baseUrl;
+  private steps;
+  private _skipInvariants;
+  constructor(baseUrl: string);
+  subscription(pattern: string, id: string): this;
+  spawn(typeName: string, instanceId: string, opts?: {
+    args?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    parent?: string;
+    initialMessage?: unknown;
+  }): this;
+  send(payload: unknown, opts: {
+    from: string;
+    type?: string;
+  }): this;
+  sendTo(url: string, payload: unknown, opts: {
+    from: string;
+  }): this;
+  kill(): this;
+  killUrl(url: string): this;
+  expectWebhook(opts?: ExpectWebhookOpts): this;
+  respondDone(): this;
+  expectEntityContext(checks?: EntityContextChecks): this;
+  expectStatus(status: string): this;
+  expectStreamContains(messageType: string): this;
+  readStream(stream?: `main` | `error`): this;
+  list(filter?: {
+    type?: string;
+    status?: string;
+    parent?: string;
+    limit?: number;
+    offset?: number;
+  }): this;
+  expectListCount(opts: {
+    min?: number;
+    max?: number;
+    exact?: number;
+  }): this;
+  expectListTotal(total: number): this;
+  registerType(registration: EntityTypeRegistration): this;
+  expectTypeExists(name: string): this;
+  inspectType(name: string): this;
+  deleteType(name: string): this;
+  expectTypeNotExists(name: string): this;
+  amendSchemas(name: string, schemas: {
+    input_schemas?: Record<string, Record<string, unknown>>;
+    output_schemas?: Record<string, Record<string, unknown>>;
+  }): this;
+  listTypes(): this;
+  registerTypeViaServe(registration: EntityTypeRegistration): this;
+  write(payload: unknown, opts?: {
+    type?: string;
+  }): this;
+  writeStateProtocol(event: {
+    type: string;
+    key: string;
+    value: Record<string, unknown>;
+    headers: {
+      operation: `insert` | `update`;
+      [k: string]: unknown;
+    };
+  }): this;
+  expectStreamEvent(type: string, key: string, operation: `insert` | `update`, valueCheck?: (value: Record<string, unknown>) => void): this;
+  expectStreamEventCount(type: string, count: number): this;
+  setTags(tags: Record<string, string>): this;
+  expectTags(expected: Record<string, string>): this;
+  expectSpawnSchemaError(typeName: string, instanceId: string, opts?: {
+    args?: Record<string, unknown>;
+  }): this;
+  expectSendSchemaError(payload: unknown, opts: {
+    from: string;
+    type?: string;
+  }): this;
+  expectWriteSchemaError(payload: unknown, opts?: {
+    type?: string;
+  }): this;
+  expectSendUnknownType(payload: unknown, opts: {
+    from: string;
+    type: string;
+  }): this;
+  expectWriteUnknownType(payload: unknown, opts: {
+    type: string;
+  }): this;
+  expectEntityPersisted(): this;
+  expectSpawnError(url: string, code: string, status: number): this;
+  expectSendError(code: string, status: number): this;
+  custom(fn: (ctx: RunContext) => Promise<void>): this;
+  wait(ms: number): this;
+  skipInvariants(): this;
+  run(): Promise<Array<HistoryEvent>>;
+}
+declare function checkInvariants(history: Array<HistoryEvent>): void;
+/**
+ * Actions available in the Electric Agents entity lifecycle.
+ * Used by enabledElectricAgentsActions() as the ENABLED predicate.
+ */
+type ElectricAgentsAction = `register_type` | `delete_type` | `spawn` | `send` | `kill` | `check_status` | `list`;
+/**
+ * Model of a single entity type's state.
+ */
+interface EntityTypeModel {
+  name: string;
+  hasCreationSchema: boolean;
+  hasInputSchemas: boolean;
+  hasOutputSchemas: boolean;
+}
+/**
+ * Model of a single entity's state — the "abstract" version
+ * that tracks what should be true, independent of the server.
+ */
+interface EntityModel {
+  url: string;
+  typeName: string;
+  status: `running` | `stopped`;
+  messageCount: number;
+}
+/**
+ * World model tracking all entities and entity types in a scenario.
+ * This is the Init/Next state that the property test evolves.
+ */
+interface ElectricAgentsWorldModel {
+  entityTypes: Array<EntityTypeModel>;
+  entities: Array<EntityModel>;
+  nextEntityNum: number;
+}
+/**
+ * ENABLED predicate — determines which actions can fire from the current state.
+ *
+ * - register_type: always (up to a cap of 3 types)
+ * - delete_type: when entity types exist and no running entities use them
+ * - spawn: when at least one entity type is registered (up to a cap)
+ * - send: when at least one entity is running
+ * - kill: when at least one entity is running
+ * - check_status: when at least one entity exists
+ * - list: always
+ */
+declare function enabledElectricAgentsActions(model: ElectricAgentsWorldModel): Array<ElectricAgentsAction>;
+/**
+ * Next relation — pure state transition for the model.
+ * The real server execution happens separately in the property test.
+ */
+declare function applyElectricAgentsAction(model: ElectricAgentsWorldModel, action: ElectricAgentsAction, targetIdx?: number): ElectricAgentsWorldModel;
+declare function electricAgents(baseUrl: string): ElectricAgentsScenario;
+declare function checkStateProtocolInvariants(events: Array<Record<string, unknown>>): void; //#endregion
+//#region src/cli-dsl.d.ts
+/**
+ * CLI Testing DSL — fluent builder for testing the electric-agents CLI binary.
+ *
+ * Executes CLI commands as subprocesses against a running test server,
+ * asserting on stdout, stderr, and exit codes.
+ *
+ * Usage:
+ *   await cliTest(baseUrl, cliBin)
+ *     .exec('types')
+ *     .expectStdout(/No entity types/)
+ *     .exec('spawn', '/my-type/instance-1')
+ *     .expectStdout(/Spawned/)
+ *     .exec('ps')
+ *     .expectStdout(/my-type/)
+ *     .exec('kill', '/my-type/instance-1')
+ *     .expectStdout(/Killed/)
+ *     .run()
+ */
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+interface CliHistory {
+  command: Array<string>;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+declare class CliScenario {
+  private baseUrl;
+  private cliBin;
+  private steps;
+  constructor(baseUrl: string, cliBin: string);
+  /**
+   * Register an entity type via HTTP (setup, not a CLI test).
+   */
+  setupType(registration: Record<string, unknown>): this;
+  /**
+   * Create a webhook subscription via HTTP (setup, not a CLI test).
+   */
+  setupSubscription(pattern: string, id: string): this;
+  /**
+   * Verify internal server state via direct API call.
+   * Provides an extra level of guarantee beyond CLI output.
+   */
+  verifyApi(fn: (baseUrl: string) => void | Promise<void>): this;
+  /**
+   * Execute a CLI command. Args are passed directly to the binary.
+   */
+  exec(...args: Array<string>): this;
+  /**
+   * Assert stdout of the last exec matches a regex.
+   */
+  expectStdout(pattern: RegExp): this;
+  /**
+   * Assert stdout of the last exec does NOT match a regex.
+   */
+  expectStdoutNot(pattern: RegExp): this;
+  /**
+   * Assert stdout contains exact text.
+   */
+  expectStdoutContains(text: string): this;
+  /**
+   * Assert stderr of the last exec matches a regex.
+   */
+  expectStderr(pattern: RegExp): this;
+  /**
+   * Assert exit code of the last exec.
+   */
+  expectExitCode(code: number): this;
+  /**
+   * Parse stdout as JSON and run a check function.
+   */
+  expectJson(check: (data: unknown) => void): this;
+  /**
+   * Custom assertion on the last exec result.
+   */
+  custom(fn: (last: ExecResult) => void | Promise<void>): this;
+  /**
+   * Wait for a given number of milliseconds.
+   */
+  wait(ms: number): this;
+  /**
+   * Run all steps sequentially, returning the history.
+   */
+  run(): Promise<Array<CliHistory>>;
+}
+declare function cliTest(baseUrl: string, cliBin: string): CliScenario;
+
+//#endregion
+//#region src/mock-stream.d.ts
+declare function createMockStreamFn(text: string): StreamFn;
+
+//#endregion
+export { CliHistory, CliScenario, CliTestOptions, ElectricAgentsAction, ElectricAgentsScenario, ElectricAgentsTestOptions, ElectricAgentsWorldModel, EntityModel, HistoryEvent, MockAgentCliTestOptions, MockAgentTestOptions, RunContext, ServeEndpointReceiver, applyElectricAgentsAction, checkInvariants, checkStateProtocolInvariants, cliTest, createMockStreamFn, electricAgents, enabledElectricAgentsActions, runCliConformanceTests, runElectricAgentsConformanceTests, runMockAgentCliTests, runMockAgentTests };