@barry-rocks/sdk/apps

The client for AG-UI, the protocol a bag’s app uses to watch and drive a session: AgUiConnection, its event and delivery types, and the public session snapshot. Use it from an app that shows a session to a person.

import { … } from "@barry-rocks/sdk/apps";

API

Classes

AgUiConnection

A connection starts no work until an operation is explicitly invoked.

Constructors

Constructor

new AgUiConnection(options): AgUiConnection

Parameters

Parameter	Type
options	AgUiConnectionOptions

Returns

AgUiConnection

Methods

cancel()

cancel(sessionId, turnId, options?): Promise<TurnSnapshot>

Parameters

Parameter	Type
sessionId	string
turnId	string
options	RequestOptions

Returns

Promise<TurnSnapshot>

close()

close(): void

Returns

void

queue()

queue(input, options?): Promise<{ id: string; state: string; }>

Parameters

Parameter	Type
input	RunAgentInput
options	RequestOptions

Returns

Promise<{ id: string; state: string; }>

run()

run(input, options?): AsyncIterable<AgUiDelivery>

Parameters

Parameter	Type
input	RunAgentInput
options	RequestOptions

Returns

AsyncIterable<AgUiDelivery>

snapshot()

snapshot(sessionId, options?): Promise<PublicSessionSnapshot>

Parameters

Parameter	Type
sessionId	string
options	RequestOptions

Returns

Promise<PublicSessionSnapshot>

subscribe()

subscribe(sessionId, options?): AsyncIterable<AgUiDelivery>

Parameters

Parameter	Type
sessionId	string
options	AgUiSubscriptionOptions

Returns

AsyncIterable<AgUiDelivery>

---

BarryApiError

Why a call to Barry’s API did not produce a result.

status is the HTTP status once response headers arrive, and null before then. A deadline or cancellation can interrupt an unfinished response body. code is the machine-readable reason: the actions routes’ error field, or one of this client’s own (“unreachable”, “timeout”, “cancelled”, “invalid_request”, “malformed_response”, “credential_error”, “service_unconfigured”, “invalid_pagination”, “http_”).

Extends

• Error

Constructors

Constructor

new BarryApiError(message, options): BarryApiError

Parameters

Parameter	Type
message	string
options	{ code: string; detail?: unknown; requestId?: string; status: number | null; }
options.code	string
options.detail?	unknown
options.requestId?	string
options.status	number | null

Returns

BarryApiError

Overrides

Error.constructor

Properties

Property	Modifier	Type
code	readonly	string
detail	readonly	unknown
requestId	readonly	string | undefined
status	readonly	number | null

Interfaces

AgUiConnectionOptions

Extends

• ClientCredentials

Properties

Property	Type	Description	Inherited from
baseUrl	string	Sessions root, such as http://localhost:4885/api/v2/sessions.	-
fetch?	{(input, init?): Promise<Response>; (input, init?): Promise<Response>; }	-	-
maxFrameBytes?	number	-	-
resolveCredential?	CredentialResolver	Called for each request, including reconnects; the client never caches tokens.	ClientCredentials.resolveCredential
secret?	string	-	ClientCredentials.secret
timeoutMs?	number	HTTP deadline; streaming deadlines end after the response headers arrive.	-

---

AgUiDelivery

Properties

Property	Type
cursor	string
event	Event

---

AgUiSubscriptionOptions

Controls for one request; pass separately from resource filters or inputs.

Extends

• RequestOptions

Properties

Property	Type	Description	Inherited from
after?	string | number	-	-
reconnect?	object	Opt-in GET reconnects; writes are never retried. At most ten reconnects.	-
reconnect.delayMs?	number	-	-
reconnect.maxAttempts	number	-	-
signal?	AbortSignal	-	RequestOptions.signal
timeoutMs?	number	-	RequestOptions.timeoutMs

---

ClientCredentials

Extended by

• ConnectOptions
• AgUiConnectionOptions
• ServiceClientOptions

Properties

Property	Type	Description
resolveCredential?	CredentialResolver	Called for each request, including reconnects; the client never caches tokens.
secret?	string	-

---

ExecutionEvent

Properties

Property	Type
event	SessionEvent | { type: "segment_started" | "resolution_accepted"; } | { snapshot: TurnSnapshot; type: "segment_interrupted" | "turn_finished" | "turn_snapshot"; }
runId	string
sequence	number
turnId	string

---

PublicSessionSnapshot

Properties

Property	Type
agUiPackageVersion	string
appExtensionVersion	number
capabilities	object
capabilities.approvalContinuation	ApprovalContinuation
capabilities.approveWithEdits	boolean
capabilities.attachments	boolean
capabilities.frontendTools	boolean
capabilities.replay	boolean
cursor	number
messages	Message[]
protocolVersion	string
threadId	string
turn	TurnSnapshot | null

---

RequestOptions

Controls for one request; pass separately from resource filters or inputs.

Extended by

• AgUiSubscriptionOptions

Properties

Property	Type
signal?	AbortSignal
timeoutMs?	number

---

RequestScope

Properties

Property	Type
controller	AbortController
response?	Response

Methods

dispose()

dispose(): void

Returns

void

stopDeadline()

stopDeadline(): void

Returns

void

Type Aliases

AgUiSubscriptionDelivery

AgUiSubscriptionDelivery = { sessionId: string; snapshot: PublicSessionSnapshot; type: "snapshot"; } | { cursor: string; event: AgUiEvent; sessionId: string; type: "event"; } | { message: string; type: "error"; }

---

AgUiSubscriptionRequest

AgUiSubscriptionRequest = z.infer<typeof AgUiSubscriptionRequestSchema>

Variables

AG_UI_PACKAGE_VERSION

const AG_UI_PACKAGE_VERSION: "1.0.1" = "1.0.1"

---

AgUiSubscriptionRequestSchema

const AgUiSubscriptionRequestSchema: ZodDiscriminatedUnion<[ZodObject<{ after: ZodOptional<ZodString>; sessionId: ZodString; type: ZodLiteral<"subscribe">; }, $strict>, ZodObject<{ type: ZodLiteral<"unsubscribe">; }, $strict>], "type">

---

APP_EXTENSION_VERSION

const APP_EXTENSION_VERSION: 2 = 2

---

PublicSessionSnapshotSchema

const PublicSessionSnapshotSchema: ZodObject<{ agUiPackageVersion: ZodString; appExtensionVersion: ZodInt; capabilities: ZodObject<{ approvalContinuation: ZodEnum<{ durable: "durable"; live: "live"; unsupported: "unsupported"; }>; approveWithEdits: ZodBoolean; attachments: ZodBoolean; frontendTools: ZodBoolean; replay: ZodBoolean; }, $strict>; cursor: ZodInt; messages: ZodArray<ZodDiscriminatedUnion<[ZodObject<{ }, $loose>, ZodObject<{ }, $loose>, ZodObject<{ }, $loose>], string>>; protocolVersion: ZodString; threadId: ZodString; turn: ZodNullable<ZodObject<{ error: ZodOptional<ZodString>; id: ZodString; interrupts: ZodArray<ZodObject<{ call: ZodObject<{ description: ZodOptional<…>; id: ZodString; input: ZodUnknown; tool: ZodString; }, $strict>; expiresAt: ZodOptional<ZodString>; id: ZodString; runId: ZodString; status: ZodEnum<{ approved: "approved"; cancelled: "cancelled"; denied: "denied"; expired: "expired"; pending: "pending"; }>; }, $strict>>; result: ZodOptional<ZodUnknown>; reviewPolicy: ZodDiscriminatedUnion<[ZodObject<{ mode: ZodLiteral<"automatic">; }, $strict>, ZodObject<{ expiresAt: ZodOptional<ZodISODateTime>; mode: ZodLiteral<"review_required">; }, $strict>], "mode">; revision: ZodInt; runId: ZodString; sessionId: ZodString; state: ZodEnum<{ cancelled: "cancelled"; completed: "completed"; failed: "failed"; queued: "queued"; recovery_required: "recovery_required"; running: "running"; waiting_for_input: "waiting_for_input"; }>; }, $strict>>; }, $strict>

---

PublicTurnSchema

const PublicTurnSchema: ZodObject<{ error: ZodOptional<ZodString>; id: ZodString; interrupts: ZodArray<ZodObject<{ call: ZodObject<{ description: ZodOptional<ZodString>; id: ZodString; input: ZodUnknown; tool: ZodString; }, $strict>; expiresAt: ZodOptional<ZodString>; id: ZodString; runId: ZodString; status: ZodEnum<{ approved: "approved"; cancelled: "cancelled"; denied: "denied"; expired: "expired"; pending: "pending"; }>; }, $strict>>; result: ZodOptional<ZodUnknown>; reviewPolicy: ZodDiscriminatedUnion<[ZodObject<{ mode: ZodLiteral<"automatic">; }, $strict>, ZodObject<{ expiresAt: ZodOptional<ZodISODateTime>; mode: ZodLiteral<"review_required">; }, $strict>], "mode">; revision: ZodInt; runId: ZodString; sessionId: ZodString; state: ZodEnum<{ cancelled: "cancelled"; completed: "completed"; failed: "failed"; queued: "queued"; recovery_required: "recovery_required"; running: "running"; waiting_for_input: "waiting_for_input"; }>; }, $strict>

Functions

agUiContractSchemas()

agUiContractSchemas(): Record<string, unknown>

Upstream owns AG-UI schemas; Apps owns only Barry’s extensions.

Returns

Record<string, unknown>

---

agUiSse()

agUiSse(sessionId, record): string

One cursor may project several wire events; index makes every SSE ID stable.

Parameters

Parameter	Type
sessionId	string
record	ExecutionEvent

Returns

string

---

approvalDecisions()

approvalDecisions(input): ApprovalDecision[]

Parameters

Parameter	Type
input	RunAgentInput

Returns

ApprovalDecision[]

---

attachmentIdsForRun()

attachmentIdsForRun(input): string[]

Uploaded Barry files are references, not generic multimodal AG-UI input.

Parameters

Parameter	Type
input	RunAgentInput

Returns

string[]

---

barryExtensionsForRun()

barryExtensionsForRun(input): object

Parameters

Parameter	Type
input	RunAgentInput

Returns

object

Name	Type
attachmentIds	string[]
ifActive?	"error" | "queue"

---

executionTranscript()

executionTranscript(inputs, events): Message[]

Build presentation history only from server-accepted input and committed events.

Parameters

Parameter	Type
inputs	object[]
events	ExecutionEvent[]

Returns

Message[]

---

messageRunInput()

messageRunInput(snapshot, content, messageId, runId): RunAgentInput

Build an idempotent user-message run from the server-owned transcript.

Parameters

Parameter	Type
snapshot	PublicSessionSnapshot
content	string
messageId	string
runId	string

Returns

RunAgentInput

---

parseAgUiEvent()

parseAgUiEvent(value): Event

Parameters

Parameter	Type
value	unknown

Returns

Event

---

parseRunAgentInput()

parseRunAgentInput(value, sessionId): RunAgentInput

Validate upstream wire shapes; Barry never forks the AG-UI schema.

Parameters

Parameter	Type
value	unknown
sessionId	string

Returns

RunAgentInput

---

projectAgUi()

projectAgUi(sessionId, record): Event[]

Replay is a projection of committed domain events, never another run loop.

Parameters

Parameter	Type
sessionId	string
record	ExecutionEvent

Returns

Event[]

References

CredentialResolver

Re-exports CredentialResolver