Class FakeServer

The in-process server the SDK's tests and an adapter's tests run against.

Create it with new FakeServer(options), open it with FakeServer.start and close it with FakeServer.stop (the shape of the Python FakeServer). Members that depend on the port (FakeServer.origin, FakeServer.baseUrl, FakeServer.gatewayUrl) hold their value after the start.

Implements

ScenarioServer

Constructors

constructor

new FakeServer(options?: FakeServerOptions): FakeServer
Creates the server; FakeServer.start opens the listener.
Parameters
- options: FakeServerOptions = {}
  Clock, timings, DPoP, billing mode and tool class.
Returns FakeServer
Throws
RangeError on an unknown timing key.

Properties

`Readonly`clock

clock: FakeClock

The clock shared with the SDK under test.

`Readonly`credentials

credentials: Credentials

Lotse's API token and, with dpop, its key.

origin

origin: string = ""

http://127.0.0.1:<port> after the start; empty before.

`Readonly`sdkSettings

sdkSettings: SdkSettings

Settings an adapter under test should use (short waits, a leeway within auth.clock_leeway).

`Readonly`timings

timings: Timings

The server keys in effect: durations in milliseconds, agent.max_inflight_events a count.

Accessors

agentId

get agentId(): string
Lotse's principal ID, the agent under test.

Returns string
Implementation of ScenarioServer.agentId

baseUrl

get baseUrl(): string
The REST base URL, origin + "/api/v1".

Returns string
Implementation of ScenarioServer.baseUrl

commands

get commands(): ReadonlyMap<string, {}>
The registered commands by ID.

Returns ReadonlyMap<string, {}>

gatewayHtu

get gatewayHtu(): string
The htu of a gateway proof: always HTTPS with the server's host and port.

Returns string

gatewayUrl

get gatewayUrl(): string
The gateway's WebSocket URL.

Returns string

heartbeats

get heartbeats(): readonly Readonly<Record<string, unknown>>[]
The heartbeat bodies received (REST and the gateway member agent), in order.

Returns readonly Readonly<Record<string, unknown>>[]

instanceId

get instanceId(): string
The instance (iss of every token).

Returns string
Implementation of ScenarioServer.instanceId

messages

get messages(): readonly Readonly<Record<string, unknown>>[]
The stored createMessage bodies (with client_msg_id), in order.

Returns readonly Readonly<Record<string, unknown>>[]

otherAgentId

get otherAgentId(): string
Texter's principal ID, a second agent.

Returns string
Implementation of ScenarioServer.otherAgentId

Methods

[asyncDispose]

"[asyncDispose]"(): Promise<void>
Stops the server at the end of an await using block.

Returns Promise<void>
A promise that resolves when the server stopped.

autocompleteAnswer

autocompleteAnswer(requestId: string): {}[] | undefined
Returns what the adapter answered before expires_at, if anything.
Parameters
- requestId: string
  The request.
Returns {}[] | undefined
The choices, or undefined when no answer arrived in time.

cancel

cancel(
    runId: string,
    reason?:
        | "user_disabled"
        | "user_cancelled"
        | "access_revoked"
        | "agent_disabled"
        | "channel_read_only",
): Promise<void>
Lets a person cancel the run: run.cancel_requested.

A queued run ends cancelled at once; an active run waits agent.cancel_grace for the adapter's cancelled and then ends with cancel_timeout.
Parameters
- runId: string
  The run.
- reason:
      | "user_disabled"
      | "user_cancelled"
      | "access_revoked"
      | "agent_disabled"
      | "channel_read_only" = "user_cancelled"
  The payload's reason.
Returns Promise<void>
Throws
Error when the run has completed or failed.

closeConnections

closeConnections(code: number): Promise<void>
Closes every gateway connection with code.
Parameters
- code: number
  A close code of docs/api/asyncapi.yaml.
Returns Promise<void>

consumerState

consumerState(consumer: string): ConsumerView
Returns the consumer's stored acknowledgement and the head.
Parameters
- consumer: string
  The consumer name.
Returns ConsumerView
The view.

Throws
RangeError when the consumer never connected.

deliverFollowup

deliverFollowup(runId: string, text?: string): Promise<string>
Lets Alex post a follow-up to the run: agent.followup.
Parameters
- runId: string
  The run.
- text: string = "One more thing"
  The message content.
Returns Promise<string>
The follow-up message ID.

deliverInteraction

deliverInteraction(
    runId: string,
    customId?: string,
    values?: Readonly<Record<string, unknown>>,
): Promise<string>
Lets Alex operate a component of the run: interaction.created.
Parameters
- runId: string
  The run.
- customId: string = "approval.once"
  The component's custom ID (created on a card of the run if missing).
- values: Readonly<Record<string, unknown>> = {}
  The submitted values.
Returns Promise<string>
The interaction ID.

deliverWithToken

deliverWithToken(envelopeId: string, token: Secret): Promise<string>
Delivers an existing event's payload again under a new event ID with token.

The replay case of AZ-P6: the same token on a second event.
Parameters
- envelopeId: string
  The ID of an event in the log.
- token: Secret
  The token the new delivery carries (not recorded on the run).
Returns Promise<string>
The new event ID.

Throws
RangeError when no event has that ID.

deprecate

deprecate(operationId: string, sunset?: string): void
Marks an operation deprecated: its answers carry Deprecation: true and Sunset.
Parameters
- operationId: string
  The operation.
- sunset: string = "Wed, 30 Jun 2027 00:00:00 GMT"
  The HTTP date of the Sunset header.
Returns void

forgeToken

forgeToken(
runId: string,
variant: "bad_signature" | "alg_hs256" | "aud_other_agent" | "typ_access",
): Promise<Secret>
Returns a forged token for the run, built from its newest delivered token.

A run without a delivery yet gets the claims its agent.invocation would carry; nothing is recorded on the run, so it stays as it is (AG-08 sends these to a queued run).
Parameters
- runId: string
  The run.
- variant: "bad_signature" | "alg_hs256" | "aud_other_agent" | "typ_access"
  bad_signature, alg_hs256, typ_access or aud_other_agent.
Returns Promise<Secret>
The forged token.

Throws
RangeError on an unknown variant or run.

Implementation of ScenarioServer.forgeToken

frames

frames(): RecordedFrame[]
Returns the op of every gateway frame received from a client, in order.

Returns RecordedFrame[]
Copies of the records.

inject

inject(target: string, fault: Fault, times?: number): void
Lets the next times calls of target fail with fault.
Parameters
- target: string
  An operationId or a gateway op (ack, run.update, heartbeat, ...); on a gateway op every fault drops the connection.
- fault: Fault
  The fault, built with the static methods of Fault.
- times: number = 1
  How many calls it hits; a positive integer.
Returns void
Throws
TypeError when fault is not a Fault, RangeError on a bad times.

invokeCommand

invokeCommand(
name: string,
options?: { runId?: string; threadId?: string },
): Promise<string>
Lets Alex run Lotse's command name (registered first if missing): command.invoked.
Parameters
- name: string
  The command name.
- options: { runId?: string; threadId?: string } = {}
  The run of the thread (its thread is used) or a thread without a run.
Returns Promise<string>
The invocation ID of the payload.

passTime

passTime(ms: number): Promise<void>
Moves the shared clock forward (FakeClock.advance).
Parameters
- ms: number
  How far, in milliseconds.
Returns Promise<void>
Implementation of ScenarioServer.passTime

redeliver

redeliver(consumer?: string): Promise<void>
Delivers every unacknowledged event again now, with fresh tokens and redelivered.
Parameters
- Optionalconsumer: string
  Only this consumer; every consumer when absent.
Returns Promise<void>

registerCommand

registerCommand(name: string): Promise<string>
Registers a command of Lotse in the channel (as registerCommand would).
Parameters
- name: string
  The command name.
Returns Promise<string>
The command ID.

requestAutocomplete

requestAutocomplete(
    commandId: string,
    value?: string,
    options?: { expiresInMs?: number },
): Promise<string>
Sends command.autocomplete_requested to a live gateway connection of Lotse.
Parameters
- commandId: string
  A registered command.
- value: string = ""
  What Alex has typed so far.
- options: { expiresInMs?: number } = {}
  expiresInMs until expires_at; command.autocomplete_timeout when absent.
Returns Promise<string>
The request ID.

Throws
RangeError when the command is not registered, Error when no gateway connection of Lotse is live.

requests

requests(): RecordedRequest[]
Returns every REST request received, in order: method, path and status only.

Returns RecordedRequest[]
Copies of the records.

restart

restart(consumer?: string, ackedSeq?: number): Promise<void>
Restarts the server process and keeps its data.

Every gateway connection closes with 4013 (as the server's shutdown does), sessions and delivery windows in memory are forgotten, and one consumer's cursor may be set; the next delivery of every unacknowledged event carries a new token (AG-28).
Parameters
- Optionalconsumer: string
  The consumer whose cursor is set.
- OptionalackedSeq: number
  The cursor value (for example the seq before an event, AG-28).
Returns Promise<void>
Implementation of ScenarioServer.restart

rotateNonce

rotateNonce(): void
Starts a new DPoP nonce window now; the previous nonce stays valid one window.

Returns void

run

run(runId: string): {}
Returns the getRun body of the run.
Parameters
- runId: string
  The run.
Returns {}
The Run document.

Throws
RangeError on an unknown run.

runState

runState(runId: string): Promise<RunView>
Returns the run's state, reason, version and start count.
Parameters
- runId: string
  The run.
Returns Promise<RunView>
The view.

Throws
RangeError on an unknown run.

Implementation of ScenarioServer.runState

sendWebhook

sendWebhook(
    url: string,
    envelope: { id: string },
    options?: SendWebhookOptions,
): Promise<Response>
Posts a webhook signed with the FakeServer's own key (see getWebhookKeys) and the given HMAC secrets (webhooks.md 2): webhook-id is the envelope's id, webhook-timestamp the clock's Unix seconds, webhook-signature the v1a entry first and then the v1 entries.
Parameters
- url: string
  The receiver.
- envelope: { id: string }
  The event envelope; its id is the webhook-id.
- options: SendWebhookOptions = {}
  The HMAC secrets of the v1 entries.
Returns Promise<Response>
The receiver's response.

start

start(): Promise<void>
Opens the listener on 127.0.0.1 with a free port.

Returns Promise<void>
A promise that resolves when the server listens.

stop

stop(): Promise<void>
Closes every connection and the listener.

Returns Promise<void>
A promise that resolves when everything is closed.

trigger

trigger(text?: string): Promise<Triggered>
Lets Alex post text in a new thread: a queued run and its agent.invocation.
Parameters
- text: string = "Hello @Lotse"
  The message content.
Returns Promise<Triggered>
The run, thread and message.

Implementation of ScenarioServer.trigger

Class FakeServer

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns FakeServer

Throws

Properties

Readonlyclock

Readonlycredentials

origin

ReadonlysdkSettings

Readonlytimings

Accessors

agentId

Returns string

baseUrl

Returns string

commands

Returns ReadonlyMap<string, {}>

gatewayHtu

Returns string

gatewayUrl

Returns string

heartbeats

Returns readonly Readonly<Record<string, unknown>>[]

instanceId

Returns string

messages

Returns readonly Readonly<Record<string, unknown>>[]

otherAgentId

Returns string

Methods

[asyncDispose]

Returns Promise<void>

autocompleteAnswer

Parameters

Returns {}[] | undefined

cancel

Parameters

Returns Promise<void>

Throws

closeConnections

Parameters

Returns Promise<void>

consumerState

Parameters

Returns ConsumerView

Throws

deliverFollowup

Parameters

Returns Promise<string>

deliverInteraction

Parameters

Returns Promise<string>

deliverWithToken

Parameters

Returns Promise<string>

Throws

deprecate

Parameters

Returns void

forgeToken

Parameters

Returns Promise<Secret>

Throws

frames

Returns RecordedFrame[]

inject

Parameters

Returns void

Throws

invokeCommand

Parameters

Returns Promise<string>

`Readonly`clock

`Readonly`credentials

`Readonly`sdkSettings

`Readonly`timings