Invoke patterns, SSE streams, pagination, and error handling for @auvy-os/client.

Jobs, streaming, and errors

AUVY execution is job-centric: neuron invokes and receptor fires return a job_id. Long work streams over SSE or is polled via jobs.getStatus.

Are you an AI agent? See SDK source of truth for exact method names.

Pattern matrix

Pattern	When	SDK	CLI
Fire-and-forget	You manage stream or status	`receptors.fire(id, { stream: true })` → `createStream(auvy, job_id)`	`auvy receptors execute SLUG --async --output json`
Waiter	Scripts that need full output	`receptors.invokeAndStream(...)` or `streamJobUntilComplete`	`auvy receptors execute SLUG --stream --output jsonl`
Poll loop	Custom UI or interventions	`jobs.getStatus` + `jobs.provideInput` when `waiting`	`auvy jobs get JOB_ID`, `auvy jobs input JOB_ID`

sequenceDiagram
  participant App
  participant API
  participant Execution
  App->>API: POST invoke or fire
  API->>Execution: enqueue job
  API-->>App: job_id
  alt Stream
    App->>API: GET job SSE stream
    API-->>App: token chunks
  else Poll
    App->>API: GET /v1/jobs/:id
  end

Streaming helpers

When stream: true on invoke, tokens arrive at GET /v1/jobs/:jobId/stream. The SDK wraps SSE:

createStream(auvy, jobId) — async iterable
streamJobUntilComplete(auvy, jobId, callbacks) — runs until terminal state
subscribeJobStream(auvy, jobId, callbacks, { reconnect: true, resumeAfter }) — reconnect-safe

import { fromApiKey, createStream, isTokenChunk } from '@auvy-os/client'

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

for await (const chunk of createStream(auvy, job_id)) {
  if (isTokenChunk(chunk) && chunk.token) process.stdout.write(chunk.token)
}

Pass signal: AbortController.signal to cancel. For share flows, use shareCredentialToStreamOptions — see Public API.

Pagination

List endpoints accept limit and offset. The SDK provides paginate() and listAll():

for await (const receptor of auvy.receptors.paginate({ pageSize: 20 })) {
  console.log(receptor.slug)
}

const all = await auvy.receptors.listAll({ target_type: 'neuron' })

Errors and retries

Both SDK packages throw typed errors with stable code fields. Treat the Retryable column as authoritative.

import { AUVYError, ERROR_CODES, withRetry } from '@auvy-os/client'

try {
  await auvy.receptors.get('missing-id')
} catch (e) {
  if (e instanceof AUVYError) {
    if (AUVYError.isRateLimitError(e)) { /* backoff */ }
    if (AUVYError.isRetryableError(e)) { /* retry */ }
  }
}

const receptors = await withRetry(() => auvy.receptors.list({ limit: 20 }), { maxRetries: 3 })

HTTP	`code`	Retryable
400	`VALIDATION_ERROR`	No
401	`AUTH_REQUIRED`	No
403	`FORBIDDEN`, `trial_expired`, `cost_cap`	No
404	`NOT_FOUND`, `RESOURCE_NOT_FOUND`	No
429	`RATE_LIMIT`	Yes
5xx	`INTERNAL_SERVER_ERROR`	Yes
0	`NETWORK_ERROR`	Yes

Connect client: ConnectError with CONNECT_ERROR_CODES — see Connect SDK.

Job status	Meaning
`completed`	Success — read result
`failed`	Terminal — fix input and re-invoke
`waiting`	Needs `jobs.provideInput`

Jobs API — REST status and stream paths
SDK recipes — copy-paste patterns
First SDK call — first invoke walkthrough

Jobs, streaming, and errors

Jobs, streaming, and errors

Pattern matrix

Streaming helpers

Pagination

Errors and retries

Related

On this page