Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auvy.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
SDK streaming

Long-running receptor and pathway work returns a job_id. When stream: true is set on invoke or job execute, the API emits a server-sent events stream at GET /v1/jobs/:jobId/stream (or public share URLs). The SDK wraps this so you do not parse SSE by hand.

​
Facade-safe entry points

The object returned by createAUVYClient is not the low-level HTTP class, but these APIs accept it directly:
  • createStream(auvy, jobId) — async iterable of discriminated TokenStreamChunk values (see package exports)
  • streamJobTokens(auvy, jobId, callbacks, options?) — callback style; returns { close, getLastStreamId } for resume
  • subscribeJobStream(auvy, jobId, callbacks, options?) — resilient callback stream with reconnect + resume support; returns the same { close, getLastStreamId }
  • streamJobUntilComplete(auvy, jobId, callbacks, options?) — resolves when a terminal complete or error event is processed
If 'getStreamClient' in client, that method supplies the transport; otherwise the value must be a StreamClient (e.g. new AUVYClient(...)). The dashboard auvyClient proxy forwards get/has to the session-scoped facade, so streamJobTokens(auvyClient, jobId, ...) uses the same path.

​
Receptor helper

const { job_id } = await auvy.receptors.invoke('workspace-slug', 'receptor-slug', {
  message: 'Hello',
  stream: true,
})

for await (const chunk of auvy.receptors.createStream(job_id)) {
  if (chunk.type === 'token' && chunk.token) process.stdout.write(chunk.token)
}

​
Cancellation

Pass signal: AbortController.signal into createStream, streamJobTokens, or streamJobUntilComplete options. Calling close() on the object returned by streamJobTokens also stops the reader.

​
Resume after disconnect

Pass resumeAfter in the options object (same shape as the server’s after query). The SDK appends it to the stream URL. While reading, call getLastStreamId() on the returned handle to obtain the latest SSE id (Redis stream id) for the next connection.

​
Scale and limits

  • Server: Stream key, field name, TTL, and max length live in @auvy-synapse/internal (jobTokenStream). Agent-end XADDs each event to a Redis Stream (durable), then PUBLISHes (fire-and-forget) to job:token:live:{jobId} with { id: <stream entry id>, event: <payload> }. The API uses one PSUBSCRIBE per process (job:token:live:*) and fans out to SSE clients via an in-memory EventEmitter (jobTokenPubSubRouter.ts). On each new SSE connection the API subscribes live first (buffering), replays history via XRANGE (jobTokenStreamReplay.ts), then flushes the buffer with dedup. Resume uses the Redis stream entry id as SSE id. Tune with:
    • AUVY_JOB_STREAM_REPLAY_POOL — Redis connections for history replay on SSE connect (default 16, max 256)
    • AUVY_JOB_STREAM_HEARTBEAT_MS — SSE comment interval (default 20000)
    SSE comment keepalives; idle wall-clock cutoff follows stream TTL. Redis connections for SSE: 1 subscriber + replay pool per API process (unlimited concurrent SSE clients).
  • SDK: SSE line buffering is capped; for await over createStream uses a bounded queue so a slow consumer cannot grow memory without bound.

​
Dashboard reconnect

useJobStream().subscribe(jobId, callbacks, { reconnect: true }) retries with exponential backoff after transport errors, passes resumeAfter from getLastStreamId, and resolves terminal state via GET /v1/jobs/:id/status when the SSE error may be ambiguous. Opt in where you want resilience; default remains a single connection attempt.

​
Public / share flows

For share links and trace tokens, streamJobTokens and related helpers accept optional shareToken, shareTraceToken, or useShareSession in the options object. Use shareCredentialToStreamOptions from the package when building options from a ShareCredential.