@barry-rocks/sdk/sessions

Types for live sessions: turns, delivery, continuation, approvals, and the per-turn options a session adapter works with. Most bags don’t need it; session adapters and apps that drive sessions do.

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

API

Classes

EventQueue

Events pushed by a session and pulled by its reader, each delivered once.

Buffers while nobody is reading, because a reader typically starts reading just after delivering a message — and the harness may already have answered.

Type Parameters

Type Parameter
`T`

Implements

AsyncIterable<T>

Constructors

Constructor

new EventQueue<T>(): EventQueue<T>

Returns

EventQueue<T>

Methods

[asyncIterator]()

[asyncIterator](): AsyncIterator<T>

Returns

AsyncIterator<T>

Implementation of

AsyncIterable.[asyncIterator]

end()

end(): void

Readers drain what is buffered, then stop.

Returns

void

push()

push(item): void

Parameters

Parameter	Type
`item`	`T`

Returns

void

LiveContinuation

A live permission callback is retained, never represented as a durable snapshot.

Implements

ContinuationHarness

Properties

Property	Modifier	Type
`approvalContinuation`	`readonly`	`"live"`

Methods

begin()

begin(content, emit, conversation?): Promise<SegmentOutcome>

Parameters

Parameter	Type
`content`	`string`
`emit`	(`event`) => `Promise`<`void`>
`conversation?`	`ContinuationDescriptor`

Returns

Promise<SegmentOutcome>

Implementation of

ContinuationHarness.begin

close()

close(): Promise<void>

Returns

Promise<void>

Implementation of

ContinuationHarness.close

interrupt()

interrupt(): Promise<void>

Returns

Promise<void>

Implementation of

ContinuationHarness.interrupt

restore()

restore(continuation, decisions, effects, emit): Promise<SegmentOutcome>

Parameters

Parameter	Type
`continuation`	`ContinuationDescriptor`
`decisions`	`ReadonlyMap`<`string`, `PermissionDecision`>
`effects`	`ContinuationEffects`
`emit`	(`event`) => `Promise`<`void`>

Returns

Promise<SegmentOutcome>

Implementation of

ContinuationHarness.restore

validate()

validate(continuation): void

Parameters

Parameter	Type
`continuation`	`ContinuationDescriptor`

Returns

void

Implementation of

ContinuationHarness.validate

open()

static open(adapterId, fingerprint, config, start): Promise<LiveContinuation>

Parameters

Parameter	Type
`adapterId`	`string`
`fingerprint`	`string`
`config`	`SessionConfig`
`start`	(`config`) => `Promise`<`Session`>

Returns

Promise<LiveContinuation>

NotSupportedInMode

A method the session’s mode cannot perform, naming the mode that refused.

Extends

Error

Constructors

Constructor

new NotSupportedInMode(operation, mode): NotSupportedInMode

Parameters

Parameter	Type
`operation`	`string`
`mode`	`ModeId`

Returns

NotSupportedInMode

Overrides

Error.constructor

Properties

Property	Modifier	Type
`mode`	`readonly`	`ModeId`
`operation`	`readonly`	`string`

TurnExecution

One execution path for HTTP, apps and workflow turn receipts.

Constructors

Constructor

new TurnExecution(dependencies): TurnExecution

Parameters

Parameter	Type
`dependencies`	`TurnExecutionDependencies`

Returns

TurnExecution

Methods

admit()

admit(input): TurnSnapshot

Parameters

Parameter	Type
`input`	{ `actor`: `string`; `content`: `unknown`; `ifActive?`: `"error"` \| `"queue"`; `policy`: { `mode`: `"automatic"`; } \| { `expiresAt?`: `string`; `mode`: `"review_required"`; }; `requestId`: `string`; `runId`: `string`; `sessionId`: `string`; }
`input.actor`	`string`
`input.content`	`unknown`
`input.ifActive?`	`"error"` \| `"queue"`
`input.policy`	{ `mode`: `"automatic"`; } \| { `expiresAt?`: `string`; `mode`: `"review_required"`; }
`input.requestId`	`string`
`input.runId`	`string`
`input.sessionId`	`string`

Returns

TurnSnapshot

cancel()

cancel(sessionId, turnId): Promise<TurnSnapshot>

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`

Returns

Promise<TurnSnapshot>

close()

close(): Promise<void>

Returns

Promise<void>

recover()

recover(turn, input?, restoring?): void

Only runnable, unclaimed records are dispatched; never steal a process lease.

Parameters

Parameter	Type	Default value
`turn`	`TurnSnapshot`	`undefined`
`input?`	`unknown`	`undefined`
`restoring?`	`boolean`	`true`

Returns

void

resolve()

resolve(input): TurnSnapshot

Parameters

Parameter	Type
`input`	{ `actor`: `string`; `context?`: `unknown`; `decisions`: `ApprovalDecision`[]; `requestId`: `string`; `runId`: `string`; `sessionId`: `string`; `turnId`: `string`; }
`input.actor`	`string`
`input.context?`	`unknown`
`input.decisions`	`ApprovalDecision`[]
`input.requestId`	`string`
`input.runId`	`string`
`input.sessionId`	`string`
`input.turnId`	`string`

Returns

TurnSnapshot

settled()

settled(turnId): Promise<void>

Parameters

Parameter	Type
`turnId`	`string`

Returns

Promise<void>

Interfaces

ApprovalDecision

Properties

Property	Type
`decision`	`PermissionDecision`
`interruptId`	`string`

ContinuationDescriptor

Private adapter data. Never include this value in an app snapshot.

Properties

Property	Type
`adapterId`	`string`
`adapterVersion`	`string`
`configFingerprint`	`string`
`format`	`string`
`harnessVersion`	`string`
`payload`	`unknown`
`version`	`number`

ContinuationEffects

Every call goes through current authority and a persisted effect boundary.

Methods

authorize()

authorize(call): Promise<PermissionDecision>

Parameters

Parameter	Type
`call`	`PermissionRequest`

Returns

Promise<PermissionDecision>

denied()?

optional denied(call, result): Promise<RecordedCallResult>

Parameters

Parameter	Type
`call`	`PermissionRequest`
`result`	`RecordedCallResult`

Returns

Promise<RecordedCallResult>

execute()

execute(call, effect): Promise<RecordedCallResult>

Parameters

Parameter	Type
`call`	`PermissionRequest`
`effect`	() => `Promise`<`RecordedCallResult`>

Returns

Promise<RecordedCallResult>

recorded()?

optional recorded(call): Promise<RecordedCallResult | undefined>

Parameters

Parameter	Type
`call`	`PermissionRequest`

Returns

Promise<RecordedCallResult | undefined>

ContinuationHarness

A quiescent segment returns before its runtime is released. The owner commits the returned checkpoint before publishing an interrupt or closing the handle.

Properties

Property	Modifier	Type
`approvalContinuation`	`readonly`	`ApprovalContinuation`

Methods

begin()

begin(content, emit, conversation?): Promise<SegmentOutcome>

Parameters

Parameter	Type
`content`	`string`
`emit`	(`event`) => `Promise`<`void`>
`conversation?`	`ContinuationDescriptor`

Returns

Promise<SegmentOutcome>

close()

close(): Promise<void>

Returns

Promise<void>

interrupt()

interrupt(): Promise<void>

Returns

Promise<void>

restore()

restore(continuation, decisions, effects, emit): Promise<SegmentOutcome>

Parameters

Parameter	Type
`continuation`	`ContinuationDescriptor`
`decisions`	`ReadonlyMap`<`string`, `PermissionDecision`>
`effects`	`ContinuationEffects`
`emit`	(`event`) => `Promise`<`void`>

Returns

Promise<SegmentOutcome>

validate()

validate(continuation): void

Parameters

Parameter	Type
`continuation`	`ContinuationDescriptor`

Returns

void

DeliveryOptions

Properties

Property	Type	Description
`from?`	`Sender`	-
`ifActive?`	`"queue"` \| `"steer"`	Asked for, not promised: a session that cannot steer queues, and its receipt says so.
`outputSchema?`	`JsonSchema`	Constrains this turn’s final answer; see `runStructured` for harnesses that cannot.

DeliveryReceipt

What actually happened to a delivery, which is what the sender is told.

Properties

Property	Type	Description
`messageId`	`string`	-
`status`	`"started"` \| `"steered"` \| `"queued"` \| `"held"`	`started` a new turn; `steered` into the running one; `queued` behind it; `held` by Barry because the harness could not take it now.

EgressPolicy

The network half of a bound, when it asks to be enforced by a sandbox rather than by guards. An empty allowlist means nothing leaves the machine.

Properties

Property	Type	Description
`allowDomains`	`string`[]	-
`allowUnixSockets?`	`string`[]	Unix sockets the session still needs, such as a local MCP server.

PermissionRequest

Properties

Property	Type	Description
`description?`	`string`	The harness’s own description, when it gives one.
`id`	`string`	-
`input`	`unknown`	-
`tool`	`string`	-

PerTurnOptions

Properties

Property	Type	Description
`guarantees`	`Guarantees`	-
`harnessSessionId?`	`string`	The conversation to continue, when resuming one.
`harnessVersion?`	`string`	-
`id`	`string`	-

Methods

close()?

optional close(): Promise<void>

Release anything held across turns.

Returns

Promise<void>

runTurn()

runTurn(content, turn): AsyncIterable<SessionEvent>

Run one turn to completion. harnessSessionId is the conversation so far — null on the first turn of a new one — so each turn resumes the last.

Parameters

Parameter	Type
`content`	`string`
`turn`	{ `harnessSessionId`: `string` \| `null`; `outputSchema?`: `JsonSchema`; `signal`: `AbortSignal`; }
`turn.harnessSessionId`	`string` \| `null`
`turn.outputSchema?`	`JsonSchema`
`turn.signal`	`AbortSignal`

Returns

AsyncIterable<SessionEvent>

PublicInterrupt

Properties

Property	Type
`call`	`PermissionRequest`
`expiresAt?`	`string`
`id`	`string`
`runId`	`string`
`status`	`"pending"` \| `"cancelled"` \| `"approved"` \| `"denied"` \| `"expired"`

RecordedCallResult

Properties

Property	Type
`error?`	`boolean`
`id`	`string`
`result`	`unknown`

Sender

Properties

Property	Type
`name`	`string`
`sessionId?`	`string`

Session

Properties

Property	Modifier	Type	Description
`guarantees`	`readonly`	`Guarantees`	Copied from the mode that started it — what this session has, not what a new one would.
`harnessSessionId`	`readonly`	`string` \| `null`	-
`harnessVersion`	`readonly`	`string` \| `null`	The harness build this session observed, when it could see one.
`id`	`readonly`	`string`	-
`mode`	`readonly`	`ModeId`	-
`warnings?`	`readonly`	readonly `string`[]	What the adapter wants known about this session as it starts — the same notes a launch returns in `LaunchPlan.warnings`, such as native tools still reachable that Barry has equivalents for. Absent means none.

Methods

answer()

answer(request, decision): Promise<void>

Parameters

Parameter	Type
`request`	`PermissionRequest`
`decision`	`PermissionDecision`

Returns

Promise<void>

attach()?

optional attach(): Promise<SessionAttachment>

Opens the session to a vendor TUI that renders it, where the harness’s TUI can attach to Barry’s engine. The engine stays up while anything is attached; each attach is undone by one detach.

Returns

Promise<SessionAttachment>

close()

close(): Promise<void>

Returns

Promise<void>

compact()?

optional compact(): Promise<void>

Compact the conversation so far, where the harness supports it. Optional: its presence is the capability. A harness that cannot compact (codex, cursor, opencode today) simply does not define it, and callers answer 501 rather than sending a literal /compact that lands as a user message.

Returns

Promise<void>

deliver()

deliver(content, options?): Promise<DeliveryReceipt>

Parameters

Parameter	Type
`content`	`string`
`options?`	`DeliveryOptions`

Returns

Promise<DeliveryReceipt>

detach()?

optional detach(): void

Returns

void

events()

events(): AsyncIterable<SessionEvent>

Every event, across turns, each yielded once. A session has one reader; events that arrive while nobody is reading wait for the next one.

Returns

AsyncIterable<SessionEvent>

externalTurns()?

optional externalTurns(): AsyncIterable<SessionEvent>

Turns another client started, such as a person typing in an attached TUI, kept apart from events(), whose reader is waiting on Barry’s own turns. The person’s message arrives as a text with role user. Each turn ends with one done.

Returns

AsyncIterable<SessionEvent>

interrupt()

interrupt(): Promise<void>

Stop the running turn. Rejects with NotSupportedInMode where the mode cannot — resolving and doing nothing would read as “stopped” to every caller.

Returns

Promise<void>

status()

status(): "error" | "idle" | "active"

Returns

"error" | "idle" | "active"

SessionAttachment

Where a vendor TUI attaches to render a hosted session.

Properties

Property	Type	Description
`address`	`string`	The engine’s address, as the TUI’s own client takes it.
`harnessSessionId`	`string`	The conversation the TUI resumes.

SessionConfig

Properties

Property	Type	Description
`allowedNativeTools?`	`string`[]	-
`cwd`	`string`	-
`decide?`	(`request`) => `Promise`<`PermissionDecision`>	Rules on each native tool call the harness asks about. Absent means every such call is refused: a hosted session with no bound would otherwise run whatever the harness offers.
`deniedTools?`	`string`[]	Honoured only where the harness can deny natively; see `HarnessCapabilities.toolDenial`.
`egressSandbox?`	`EgressPolicy`	-
`endpoint?`	`Endpoint`	Set only when the model’s vendor is not the harness’s own: where to send requests instead, and with what key. Absent means the harness’s own settings.
`env`	`Record`<`string`, `string` \| `undefined`>	-
`ephemeral?`	`boolean`	The session runs one piece of work and is never resumed, so the harness keeps no state past `close` — a structured run, not a conversation.
`extraArgs?`	`string`[]	Raw passthrough args the user typed after Barry’s own flags.
`maxTurns?`	`number`	-
`mcpServers`	`Record`<`string`, `McpServerConfig`>	-
`model?`	`${string}/${string}`	Absent means the harness picks its own model.
`options?`	`unknown`	Harness-specific settings, validated against `Adapter.options`.
`pluginDirs?`	`string`[]	Directories of skills and commands to mount, where the harness mounts plugins.
`projectRoots?`	`string`[]	Extra roots the agent may reach, under the harness’s own access rules.
`resume?`	`object`	-
`resume.harnessSessionId?`	`string`	-
`resume.last?`	`boolean`	-
`resume.picker?`	`boolean`	-
`sessionId`	`string`	Barry’s session id.
`smallModel?`	`${string}/${string}`	For the harness’s own cheap background calls, where it makes any.
`strictMcpConfig?`	`boolean`	False lets the harness also load MCP servers from its own config (`--relax`).
`systemPrompt?`	`string`	-
`telemetryEndpoint?`	`string`	Where Barry’s OTLP receiver listens. Passed in because where a bag service listens is a host fact an adapter must not look up.
`telemetryHeaders?`	`Record`<`string`, `string`>	Headers the receiver requires — its auth, which is the host’s to know.

SessionDeclaration

Properties

Property	Type
`guarantees`	`Guarantees`
`guaranteesUnverified`	`boolean`
`harnessVersion?`	`string`

StructuredReply

Properties

Property	Type	Description
`data`	`unknown`	-
`harnessSessionId?`	`string`	-
`raw`	`string`	The final text the payload was taken from.

StructuredRun

Properties

Property	Type	Description
`maxRetries?`	`number`	Correction rounds after the first prompted attempt. Default 1.
`prompt`	`string`	-
`schema`	`JsonSchema`	-
`signal?`	`AbortSignal`	Stops the attempt in flight and the run; the run then rejects.
`structuredOutput`	`"native"` \| `"prompted"`	From the session’s mode, overridden by the endpoint when a model is routed elsewhere.

Methods

start()

start(): Promise<Session>

A FRESH session per attempt. Retries carry the previous output and its errors in the prompt rather than continuing a conversation, because not every harness can resume one, and a structured run must behave the same on all of them.

Returns

Promise<Session>

TurnExecutionDependencies

Properties

Property	Type
`store`	`TurnExecutionStore`

Methods

acquire()?

optional acquire(): Promise<{ release: void; }>

Returns

Promise<{ release: void; }>

authorize()

authorize(sessionId, call): Promise<PermissionDecision>

Parameters

Parameter	Type
`sessionId`	`string`
`call`	`PermissionRequest`

Returns

Promise<PermissionDecision>

committed()?

optional committed(sessionId, sequence): void

Notification is only a wake-up; the committed store is the replay source.

Parameters

Parameter	Type
`sessionId`	`string`
`sequence`	`number`

Returns

void

openHarness()

openHarness(sessionId): Promise<ContinuationHarness>

Parameters

Parameter	Type
`sessionId`	`string`

Returns

Promise<ContinuationHarness>

TurnExecutionStore

Methods

admit()

admit(input): TurnSnapshot

Parameters

Parameter	Type
`input`	{ `actor`: `string`; `content`: `unknown`; `ifActive?`: `"error"` \| `"queue"`; `policy`: { `mode`: `"automatic"`; } \| { `expiresAt?`: `string`; `mode`: `"review_required"`; }; `requestId`: `string`; `runId`: `string`; `sessionId`: `string`; }
`input.actor`	`string`
`input.content`	`unknown`
`input.ifActive?`	`"error"` \| `"queue"`
`input.policy`	{ `mode`: `"automatic"`; } \| { `expiresAt?`: `string`; `mode`: `"review_required"`; }
`input.requestId`	`string`
`input.runId`	`string`
`input.sessionId`	`string`

Returns

TurnSnapshot

append()

append(sessionId, turnId, event): number

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`event`	`unknown`

Returns

number

cancel()

cancel(sessionId, turnId): TurnSnapshot

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`

Returns

TurnSnapshot

claim()

claim(sessionId, turnId, owner): boolean

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`

Returns

boolean

continuation()

continuation(sessionId, turnId): ContinuationDescriptor

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`

Returns

ContinuationDescriptor

conversation()

conversation(sessionId): ContinuationDescriptor | undefined

Parameters

Parameter	Type
`sessionId`	`string`

Returns

ContinuationDescriptor | undefined

decisions()

decisions(sessionId, turnId): Map<string, PermissionDecision>

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`

Returns

Map<string, PermissionDecision>

denied()

denied(sessionId, turnId, owner, call, outcome): RecordedCallResult

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`
`call`	`PermissionRequest`
`outcome`	`RecordedCallResult`

Returns

RecordedCallResult

execute()

execute(sessionId, turnId, owner, call, effect): Promise<RecordedCallResult>

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`
`call`	`PermissionRequest`
`effect`	() => `Promise`<`RecordedCallResult`>

Returns

Promise<RecordedCallResult>

finish()

finish(sessionId, turnId, owner, outcome): TurnSnapshot

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`
`outcome`	{ `conversation?`: `ContinuationDescriptor`; `error?`: `string`; `result?`: `unknown`; `state`: `"failed"` \| `"completed"` \| `"recovery_required"`; }
`outcome.conversation?`	`ContinuationDescriptor`
`outcome.error?`	`string`
`outcome.result?`	`unknown`
`outcome.state`	`"failed"` \| `"completed"` \| `"recovery_required"`

Returns

TurnSnapshot

lost()

lost(sessionId, turnId, error): TurnSnapshot

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`error`	`string`

Returns

TurnSnapshot

pause()

pause(sessionId, turnId, owner, continuation, calls): TurnSnapshot

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`
`continuation`	`ContinuationDescriptor`
`calls`	`PermissionRequest`[]

Returns

TurnSnapshot

promoteQueued()?

optional promoteQueued(sessionId): { input: unknown; turn: TurnSnapshot; } | undefined

Parameters

Parameter	Type
`sessionId`	`string`

Returns

{ input: unknown; turn: TurnSnapshot; } | undefined

recorded()

recorded(sessionId, turnId, call): RecordedCallResult | undefined

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`call`	`PermissionRequest`

Returns

RecordedCallResult | undefined

released()

released(sessionId, turnId, owner): void

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`
`owner`	`string`

Returns

void

resolve()

resolve(input): TurnSnapshot

Parameters

Parameter	Type
`input`	{ `actor`: `string`; `context?`: `unknown`; `decisions`: `ApprovalDecision`[]; `requestId`: `string`; `runId`: `string`; `sessionId`: `string`; `turnId`: `string`; }
`input.actor`	`string`
`input.context?`	`unknown`
`input.decisions`	`ApprovalDecision`[]
`input.requestId`	`string`
`input.runId`	`string`
`input.sessionId`	`string`
`input.turnId`	`string`

Returns

TurnSnapshot

snapshot()

snapshot(sessionId, turnId): TurnSnapshot

Parameters

Parameter	Type
`sessionId`	`string`
`turnId`	`string`

Returns

TurnSnapshot

TurnSnapshot

Properties

Property	Type
`error?`	`string`
`id`	`string`
`interrupts`	`PublicInterrupt`[]
`result?`	`unknown`
`reviewPolicy`	{ `mode`: `"automatic"`; } \| { `expiresAt?`: `string`; `mode`: `"review_required"`; }
`revision`	`number`
`runId`	`string`
`sessionId`	`string`
`state`	`TurnState`

Type Aliases

ApprovalContinuation

ApprovalContinuation = "durable" | "live" | "unsupported"

CallState

CallState = "not_started" | "executing" | "completed" | "failed" | "denied" | "uncertain"

McpServerConfig

McpServerConfig = { args?: string[]; command: string; env?: Record<string, string>; type?: "stdio"; } | { headers?: Record<string, string>; type: "http" | "sse"; url: string; }

PermissionDecision

PermissionDecision = { allow: true; persist?: boolean; } | { allow: false; reason?: string; }

Union Members

Type Literal

{ allow: true; persist?: boolean; }

persist applies the answer to every later call of the same shape.

Type Literal

{ allow: false; reason?: string; }

ReviewPolicy

ReviewPolicy = z.infer<typeof ReviewPolicySchema>

SegmentOutcome

SegmentOutcome = { conversation?: ContinuationDescriptor; result?: unknown; type: "completed"; } | { error: string; type: "failed"; } | { calls: PermissionRequest[]; continuation: ContinuationDescriptor; type: "interrupted"; }

SessionEvent

SessionEvent = object & { harnessSessionId: string; type: "init"; } | { role?: "assistant" | "user"; text: string; type: "text"; } | { text: string; type: "partial"; } | { id: string; input: unknown; tool: string; type: "tool_use"; } | { error?: boolean; id?: string; result: unknown; type: "tool_result"; } | { elapsedSeconds: number; id: string; tool: string; type: "tool_progress"; } | { description?: string; id: string; input: unknown; tool: string; type: "permission_request"; } | { status: "idle" | "active" | "error"; type: "status"; } | { error?: string; result?: string; structured?: unknown; type: "result"; } | { error: string; type: "error"; } | { id: string; type: "usage"; usage: TokenUsage; } | { durationMs?: number; turns?: number; type: "done"; usage?: TokenUsage; }

The one event vocabulary. Every turn ends with exactly one done, so a reader can wait for it without knowing how the harness ends a turn.

Type Declaration

Name	Type	Description
`parentToolUseId?`	`string`	Set when a subagent, not the main thread, produced the event: the tool call that spawned it.

TurnState

TurnState = "queued" | "running" | "waiting_for_input" | "recovery_required" | "completed" | "failed" | "cancelled"

Variables

ReviewPolicySchema

const ReviewPolicySchema: ZodDiscriminatedUnion<[ZodObject<{ mode: ZodLiteral<"automatic">; }, $strict>, ZodObject<{ expiresAt: ZodOptional<ZodISODateTime>; mode: ZodLiteral<"review_required">; }, $strict>], "mode">

Functions

allowedNative()

allowedNative(config, nativeTools, native?): string[]

The native tools a session may use (ADP-6): every adapter derived this the same way, so it lives here once. grantable restricts to a declared subset (pi); omit it to allow any requested native tool. inseparable groups drop whole when any member is unavailable. Denials are case-insensitive, matching the native policy and configureHarnessSession.

Parameters

Parameter	Type
`config`	`Pick`<`SessionConfig`, `"allowedNativeTools"` \| `"deniedTools"`>
`nativeTools`	readonly `string`[]
`native?`	`NativeControl`

Returns

string[]

assertSessionOwner()

assertSessionOwner(session, identity): void

Parameters

Parameter	Type
`session`	{ `identity_id?`: `number` \| `null`; } \| `undefined`
`identity`	`number`

Returns

void

canEnforceInSandbox()

canEnforceInSandbox(actions): boolean

Whether Barry’s egress proxy can fully enforce a network bound’s actions.

The proxy filters by host, not by HTTP method, so it cannot express “reads allowed, writes denied”. Partial denials fall back to the app-level guards; callers should say so rather than implying kernel-grade coverage.

Parameters

Parameter	Type
`actions`	`string`[] \| `undefined`

Returns

boolean

canonicalJson()

canonicalJson(value): string

Canonical JSON rejects values that would silently change across persistence.

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

configureHarnessSession()

configureHarnessSession(input, nativeTools, native?): SessionConfig

Apply the non-negotiable native ceiling before any adapter starts work.

Parameters

Parameter	Type
`input`	`SessionConfig`
`nativeTools`	readonly `string`[]
`native?`	`NativeControl`

Returns

SessionConfig

configureSession()

configureSession(input): SessionConfig

Every interface supplies the same effective harness configuration. Own mutable collections.

Parameters

Parameter	Type
`input`	`SessionConfig`

Returns

SessionConfig

declareSession()

declareSession(mode, observedVersion?): SessionDeclaration

An unknown build is not a mismatch: not every harness reports one, and marking every such session unverified would make the flag meaningless.

Parameters

Parameter	Type
`mode`	`Mode`
`observedVersion?`	`string`

Returns

SessionDeclaration

disallowedTools()

disallowedTools(config, nativeTools, native?): string[]

The native tools a session must refuse: the complement of allowedNative over the adapter’s table, plus the caller’s explicit denials (ADP-6).

Parameters

Parameter	Type
`config`	`Pick`<`SessionConfig`, `"allowedNativeTools"` \| `"deniedTools"`>
`nativeTools`	readonly `string`[]
`native?`	`NativeControl`

Returns

string[]

executionHash()

executionHash(value): string

Parameters

Parameter	Type
`value`	`unknown`

Returns

string

extractFence()

extractFence(text, label): string | null

Extract labeled fences, preferring four backticks and respecting JSON strings when balancing three-backtick payloads.

Parameters

Parameter	Type
`text`	`string`
`label`	`string`

Returns

string | null

isScopedMcpTool()

isScopedMcpTool(tool, servers): boolean

Vendor spellings for a tool on an explicitly configured MCP server.

Parameters

Parameter	Type
`tool`	`string`
`servers`	readonly `string`[]

Returns

boolean

perTurnSession()

perTurnSession(options): Session

Parameters

Parameter	Type
`options`	`PerTurnOptions`

Returns

Session

refuseDeniedTools()

refuseDeniedTools(deniedTools?): (request) => Promise<PermissionDecision>

The ruling for a session whose only per-call policy is its denied tools: a tool denied by name is refused, and everything else runs — what the session got before its harness asked. A hosted session given no ruling refuses every call, so a caller with nothing to deny still passes this.

Parameters

Parameter	Type	Default value
`deniedTools`	readonly `string`[]	`[]`

Returns

(request) => Promise<PermissionDecision>

runStructured()

runStructured(run): Promise<StructuredReply>

Parameters

Parameter	Type
`run`	`StructuredRun`

Returns

Promise<StructuredReply>

structuredOutputFor()

structuredOutputFor(mode, route): "native" | "prompted"

Who enforces a structured run’s schema. The endpoint a model is routed to has the final say when the model is another vendor’s: a compatible API can accept a schema field and ignore it, which is measured per endpoint. Else the hosted mode does.

Parameters

Parameter	Type
`mode`	{ `structuredOutput`: `"native"` \| `"prompted"`; }
`mode.structuredOutput`	`"native"` \| `"prompted"`
`route`	{ `harnessVendor`: `string` \| `undefined`; `model`: `${string}/${string}` \| `undefined`; `models`: `Pick`<`Models`, `"endpoint"`>; }
`route.harnessVendor`	`string` \| `undefined`
`route.model`	`${string}/${string}` \| `undefined`
`route.models`	`Pick`<`Models`, `"endpoint"`>

Returns

"native" | "prompted"