@barry-rocks/sdk/adapters/harnesses

The contract a session adapter implements to bring a harness to Barry: the Adapter shape, capabilities, guarantees, launch and engine types, and the errors an adapter raises. Session modes and guarantees describes what these declare.

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

API

Classes

AdapterNotInstalled

Extends

• Error

Constructors

Constructor

new AdapterNotInstalled(adapterId): AdapterNotInstalled

Parameters

Parameter	Type
adapterId	string

Returns

AdapterNotInstalled

Overrides

Error.constructor

Properties

Property	Modifier	Type
adapterId	readonly	string

---

AdapterRefused

A package whose declarations do not hold up. Distinct from AdapterNotInstalled because the repair differs: reinstalling a package that is already present changes nothing.

Extends

• Error

Constructors

Constructor

new AdapterRefused(adapterId, problems): AdapterRefused

Parameters

Parameter	Type
adapterId	string
problems	string[]

Returns

AdapterRefused

Overrides

Error.constructor

Properties

Property	Modifier	Type
adapterId	readonly	string
problems	readonly	string[]

---

HarnessVersionMismatch

A launch refused because its build is outside the verified compatibility family.

Extends

• Error

Constructors

Constructor

new HarnessVersionMismatch(message, adapterId, binary, observed, verifiedOn): HarnessVersionMismatch

Parameters

Parameter	Type
message	string
adapterId	string
binary	string
observed	string
verifiedOn	string

Returns

HarnessVersionMismatch

Overrides

Error.constructor

Properties

Property	Modifier	Type
adapterId	readonly	string
binary	readonly	string
observed	readonly	string
verifiedOn	readonly	string

Interfaces

Adapter

Properties

Property	Type	Description
aliases?	readonly string[]	Former ids this harness still answers to — what sessions, identities, flags and settings recorded before a rename. Wherever an id is read, an alias resolves to id.
bag?	string	Relative directory containing this adapter’s ordinary bag manifest.
capabilities	HarnessCapabilities	-
defaultMode	ModeId	-
experimental?	string	Present means experimental; the reason names the missing evidence.
id	string	-
label	string	-
modes	object	null is the complete answer “not today”; there is no way to leave a slot unanswered.
modes.guest	LaunchMode | null	-
modes.hosted	SessionMode | null	-
modes.instrumented	LaunchMode | null	-
nativeTools	readonly string[]	The harness’s own tools, as it names them — everything the harness can offer a session.
offeredModels?	readonly OfferedModel[]	The models a harness with no vendor offers, named as it names them (vendor/model). A harness with a vendor offers that vendor’s catalog, and the catalogs of vendors it can be routed to, instead.
options?	JsonSchema	JSON Schema for harness-specific settings, which arrive as SessionConfig.options.
requirements	Requirements	-
transcript?	TranscriptSource	-
vendor?	string	The vendor whose API this harness speaks. A model of another vendor is reachable only through that vendor’s imitation of this one. Absent for a harness that connects to vendors itself (opencode), where Barry routes nothing.

Methods

listModels()?

optional listModels(options): Promise<string[]>

The models this account can use, where the harness can say.

Parameters

Parameter	Type
options	{ env: Readonly<Record<string, string | undefined>>; }
options.env	Readonly<Record<string, string | undefined>>

Returns

Promise<string[]>

resolveBinary()?

optional resolveBinary(): string | Promise<string>

An executable a caller asks for itself, such as an IDE CLI; not necessarily the session binary.

Returns

string | Promise<string>

---

AdapterCheck

Properties

Property	Type	Description
checked	number	How many checks ran. Zero is a broken checker, not a clean adapter.
problems	string[]	-

---

Adapters

Methods

add()

add(path, options?): Promise<InstalledAdapter>

Load, check and record the adapter package at path. Nothing is recorded that did not pass.

Parameters

Parameter	Type
path	string
options?	AddOptions

Returns

Promise<InstalledAdapter>

installed()

installed(): InstalledAdapter[]

The records alone — no adapter code runs.

Returns

InstalledAdapter[]

load()

load(id): Promise<Adapter>

By id or alias.

Parameters

Parameter	Type
id	string

Returns

Promise<Adapter>

loadVendorCode()

loadVendorCode(): Promise<{ factories: VendorFactories; refused: Map<string, string[]>; }>

The installed adapters’ vendor call code, loaded: each vendor-carrying adapter is imported and its factories merged in. One that fails to load is reported by name rather than failing the caller — a broken third party must not take down the boot that asked. Rows stay available either way; only the factories are lost, and the refusal says whose.

Returns

Promise<{ factories: VendorFactories; refused: Map<string, string[]>; }>

remove()

remove(id): boolean

Remove a selection without deleting its package or registered bag data.

Parameters

Parameter	Type
id	string

Returns

boolean

vendorRows()

vendorRows(): Vendor[]

Every vendor row installed adapters declare — read off the records, so a catalog, a picker or createModels costs no adapter imports. Shipped rows come from registered bags’ vendor declarations and arrive separately.

Returns

Vendor[]

---

AddOptions

Properties

Property	Type	Description
vet?	(adapter) => Promise<string[]>	Problems running this adapter on this machine — a missing binary, a login. Asked after the adapter’s own declarations pass and before anything is recorded.

---

Command

Extended by

• LaunchPlan

Properties

Property	Type	Description
args	string[]	-
command	string	-
cwd?	string	Absent means the repo.
env	Record<string, string | undefined>	-

---

EngineHandle

Properties

Property	Modifier	Type	Description
address	readonly	string	-
password?	readonly	string	In memory only, for the client that needs it.
sessionId	readonly	string	-

Methods

recordVersion()

recordVersion(version): Promise<void>

Record the build once observed, so a mismatch with the verified one is visible.

Parameters

Parameter	Type
version	string

Returns

Promise<void>

stop()

stop(): Promise<void>

Returns

Promise<void>

---

EngineSpec

Not a command line: the adapter knows how to build one, but not which port is free or where this machine keeps its sockets — the two things it must not guess.

Properties

Property	Type	Description
cwd?	string	-
kind	string	-
needsPassword?	boolean	A per-session secret, generated by the allocator and passed through the environment — never argv, which any user on the machine can read via ps.
passwordEnvVar?	string	The harness decides this name, not Barry: opencode reads OPENCODE_SERVER_PASSWORD and nothing else, so any other name would leave the server unprotected while everything looked configured.
sessionId	string	-
transport	"unix" | "tcp"	codex listens on a unix socket, opencode on a 127.0.0.1 port.

Methods

command()

command(address): object

Called with the address the allocator chose, so the adapter never picks a taken one.

Parameters

Parameter	Type
address	string

Returns

object

Name	Type
args	readonly string[]
command	string
env	Record<string, string>

---

Guarantees

Properties

Property	Type	Description
capture	CaptureLevel	-
delivery	DeliveryLevel	-
gating	GatingLevel	-
identity	IdentityLevel	-
interrupt	boolean	-
keepsVendorUi	boolean	Whether the human keeps the harness’s own TUI.
steer	boolean	A message folded into the running turn, not queued behind it.

---

HarnessCapabilities

Properties

Property	Type	Description
endpoint	"configurable" | "fixed"	Whether Barry can point the harness at another vendor’s endpoint that serves its vendor’s API. fixed means it reaches only its own, so a model of another vendor is refused before a session starts rather than sent in an API nobody on the other end speaks.
mcpTransports	("stdio" | "http" | "sse")[]	-
skillsMount	"none" | "plugin"	-
systemPromptFormat	"unsupported" | "preset-append" | "raw"	unsupported means guidance must be prefixed onto the prompt instead.
toolDenial	"native" | "none"	none means deniedTools cannot be enforced: Barry denies the harness’s own shell so every command runs through its guarded tool, and on a none harness that guard does not apply.
withoutKey	"subscription-oauth" | "unauthenticated"	What the harness does with no API key. subscription-oauth falls back to the user’s own login — which must never be sent to another vendor’s endpoint, so routing refuses a keyless endpoint on such a harness.

---

InstalledAdapter

What Barry knows about an adapter without loading its code — enough for barry adapter list, doctor and the UI, which must work even when the code will not load.

Properties

Property	Type	Description
aliases?	string[]	-
bag?	object	Validated bag declarations, readable without loading adapter code.
bag.manifest	BagManifest	-
bag.path	string	-
capabilities	HarnessCapabilities	-
contractVersion	1	-
defaultMode	ModeId	-
experimental?	string	-
id	string	-
installedAt	string	-
label	string	-
modes	Record<ModeId, Mode | null>	-
nativeTools	string[]	-
offeredModels?	OfferedModel[]	-
packageName	string	-
path	string	-
requirements	Requirements	-
vendor?	string	-
vendorCode?	object	Vendor call code this adapter ships: the DATA half, snapshotted at install — vendor rows a picker or a model catalog reads without loading the adapter. The factories are not recorded; they load from the recorded path when the process that hosts models asks for them (loadVendorCode).
vendorCode.vendors	Vendor[]	-
version	string	-

---

LaunchInbox

A way into a running TUI for Barry’s messages.

The launcher keeps it for as long as the TUI runs: it tells Barry’s inbox the session has a live surface with this guarantee, and hands each message to deliver. The adapter owns the how (claude’s inbox socket frame); the launcher owns the loop, which is the same for every harness.

Properties

Property	Type	Description
guarantee	DeliveryLevel	What a sender can be promised while the TUI runs.

Methods

deliver()

deliver(message): Promise<boolean>

Put one message in front of the agent. False when nothing received it.

Parameters

Parameter	Type
message	{ content: string; from?: string; }
message.content	string
message.from?	string

Returns

Promise<boolean>

---

LaunchMode

A human drives, in the harness’s own TUI; Barry plans the launch.

Extends

• Mode

Properties

Property	Type	Description	Inherited from
approvalContinuation?	ApprovalContinuation	Conversation resume alone never establishes approval continuation.	Mode.approvalContinuation
attachesTo?	"hosted"	Set on a launch mode whose TUI renders the hosted session rather than running its own: it attaches to the engine Barry already holds, so it may declare guarantees up to the hosted mode’s.	Mode.attachesTo
build?	"binary" | "bundled"	What this mode runs: the binary requirements.binary names (the default), or a build the adapter carries itself, such as an SDK’s bundled CLI or a library run in-process. The binary on PATH says nothing about a bundled build, so a launch checks its version only for binary.	Mode.build
egressSandbox	boolean	Whether Barry’s egress proxy holds in this mode.	Mode.egressSandbox
evidence	object	The runnable check that showed them — a claim with no check is not declared.	Mode.evidence
evidence.check	string	-	-
evidence.proves	string	-	-
guarantees	Guarantees	-	Mode.guarantees
native?	NativeControl	-	Mode.native
platforms?	Platform[]	Where they were shown. Other platforms are unverified, not broken.	Mode.platforms
verifiedOn	string	The harness build these guarantees were shown on. A session that observes another build records its guarantees as unverified rather than as fact.	Mode.verifiedOn

Methods

plan()

plan(config): Promise<LaunchPlan>

Parameters

Parameter	Type
config	SessionConfig

Returns

Promise<LaunchPlan>

---

LaunchPlan

Extends

• Command

Properties

Property	Type	Description	Inherited from
args	string[]	-	Command.args
command	string	-	Command.command
cwd?	string	Absent means the repo.	Command.cwd
env	Record<string, string | undefined>	-	Command.env
guarantees	Guarantees	What this launch actually arranged. A side door that could not be opened lowers these, and the session records the lower ones.	-
harnessSessionId?	string	A conversation id reserved before spawning, so the session is resumable even if it dies early.	-
inbox?	LaunchInbox	A way into the running TUI for Barry’s messages, when the launch opened one.	-
tmpDirs	string[]	Directories the adapter created; the caller removes them on exit, spawned or not.	-
warnings	string[]	Things the user should know that are not failures — a denial the harness cannot express, a sandbox it will not enforce. A partial guard that reads as total is worse than a missing one.	-

Methods

discoverHarnessSessionId()?

optional discoverHarnessSessionId(): Promise<string | undefined>

For a harness that can’t be told an id up front: finds the conversation once the TUI has started one. The launcher asks while the TUI runs and once more when it exits. Undefined means not yet, or not knowable.

Returns

Promise<string | undefined>

---

Mode

Extended by

• AcpHarness
• SessionMode
• LaunchMode

Properties

Property	Type	Description
approvalContinuation?	ApprovalContinuation	Conversation resume alone never establishes approval continuation.
attachesTo?	"hosted"	Set on a launch mode whose TUI renders the hosted session rather than running its own: it attaches to the engine Barry already holds, so it may declare guarantees up to the hosted mode’s.
build?	"binary" | "bundled"	What this mode runs: the binary requirements.binary names (the default), or a build the adapter carries itself, such as an SDK’s bundled CLI or a library run in-process. The binary on PATH says nothing about a bundled build, so a launch checks its version only for binary.
egressSandbox	boolean	Whether Barry’s egress proxy holds in this mode.
evidence	object	The runnable check that showed them — a claim with no check is not declared.
evidence.check	string	-
evidence.proves	string	-
guarantees	Guarantees	-
native?	NativeControl	-
platforms?	Platform[]	Where they were shown. Other platforms are unverified, not broken.
verifiedOn	string	The harness build these guarantees were shown on. A session that observes another build records its guarantees as unverified rather than as fact.

---

NativeControl

Properties

Property	Type	Description
grantable	readonly string[]	Tools this mode can turn on while the rest stay off.
inseparable?	readonly readonly string[][]	Groups that can only be turned on whole.
operatorOverride?	string	How the operator can lift this mode’s native gate.
uncontrolled?	Readonly<Record<string, string>>	Tools this mode cannot turn off, with the reason.

---

OfferedModel

Properties

Property	Type
id	string
label	string

---

Requirements

Properties

Property	Type	Description
binary	object	-
binary.command	string	-
binary.install	object	-
binary.install.darwin?	string	-
binary.install.fallback?	string	-
binary.install.linux?	string	-
binary.paths?	string[]	Absolute installed paths, tried in order before command on PATH.
binary.pin	object	The build the modes were verified on, and what stops the harness replacing it — opencode and cursor self-update at startup unless told not to, and a pin nothing enforces is a wish.
binary.pin.enforcedBy	string	-
binary.pin.version	string	-
binary.versionArgs	string[]	-
binary.versionPattern	string	A regex whose first capture group is the version, applied to the binary’s output.
platforms?	Platform[]	-

---

SessionMode

Barry drives: every event, delivery, interrupt, and a ruling on each tool call.

Extends

• Mode

Properties

Property	Type	Description	Inherited from
approvalContinuation?	ApprovalContinuation	Conversation resume alone never establishes approval continuation.	Mode.approvalContinuation
attachesTo?	"hosted"	Set on a launch mode whose TUI renders the hosted session rather than running its own: it attaches to the engine Barry already holds, so it may declare guarantees up to the hosted mode’s.	Mode.attachesTo
build?	"binary" | "bundled"	What this mode runs: the binary requirements.binary names (the default), or a build the adapter carries itself, such as an SDK’s bundled CLI or a library run in-process. The binary on PATH says nothing about a bundled build, so a launch checks its version only for binary.	Mode.build
egressSandbox	boolean	Whether Barry’s egress proxy holds in this mode.	Mode.egressSandbox
evidence	object	The runnable check that showed them — a claim with no check is not declared.	Mode.evidence
evidence.check	string	-	-
evidence.proves	string	-	-
guarantees	Guarantees	-	Mode.guarantees
native?	NativeControl	-	Mode.native
platforms?	Platform[]	Where they were shown. Other platforms are unverified, not broken.	Mode.platforms
structuredOutput	"native" | "prompted"	-	-
verifiedOn	string	The harness build these guarantees were shown on. A session that observes another build records its guarantees as unverified rather than as fact.	Mode.verifiedOn

Methods

adopt()?

optional adopt(harnessSessionId, config): Promise<Session>

Take over a conversation the harness started without Barry.

Parameters

Parameter	Type
harnessSessionId	string
config	SessionConfig

Returns

Promise<Session>

openContinuation()?

optional openContinuation(config, startEngine): Promise<ContinuationHarness>

Parameters

Parameter	Type
config	SessionConfig
startEngine	StartEngine

Returns

Promise<ContinuationHarness>

start()

start(config, startEngine): Promise<Session>

startEngine is passed in because a harness that needs a long-running process must not depend on the bag that supervises one.

Parameters

Parameter	Type
config	SessionConfig
startEngine	StartEngine

Returns

Promise<Session>

Type Aliases

CaptureLevel

CaptureLevel = "total" | "near-total" | "post-hoc" | "none"

---

DeliveryLevel

DeliveryLevel = "wake" | "wake-peer-framed" | "turn-end" | "tool-call" | "on-resume" | "none"

Identical to the sessions bag’s delivery guarantee on purpose: what an adapter declares is what a live surface registers, and a sender is told one vocabulary either way.

---

GatingLevel

GatingLevel = "per-call" | "static" | "hooks" | "none"

per-call means the harness asks and Barry answers; static is a denylist fixed at launch; hooks is a vendor hook that can veto; none means a native call cannot be stopped once started.

---

IdentityLevel

IdentityLevel = "inherent" | "mcp-url" | "hooks" | "none"

---

StartEngine

StartEngine = (spec) => Promise<EngineHandle>

Parameters

Parameter	Type
spec	EngineSpec

Returns

Promise<EngineHandle>

Functions

checkAdapter()

checkAdapter(adapter, options?): AdapterCheck

Parameters

Parameter	Type	Description
adapter	Adapter	-
options	{ bagManifest?: { credentials?: Record<string, { field: string; item: string; source: "vault"; }>; }; }	The parsed bag manifest, when the adapter declares one — the credentials rule reads it.
options.bagManifest?	{ credentials?: Record<string, { field: string; item: string; source: "vault"; }>; }	-
options.bagManifest.credentials?	Record<string, { field: string; item: string; source: "vault"; }>	-

Returns

AdapterCheck

---

defineAdapter()

defineAdapter(adapter): Adapter

Gives an adapter literal its type, so a missing slot or implementation is a compile error.

Parameters

Parameter	Type
adapter	Adapter

Returns

Adapter

---

findInstalled()

findInstalled<Record>(records, id): Record | undefined

The installed record answering to id, by its id or one of its aliases.

Type Parameters

Type Parameter
Record extends object

Parameters

Parameter	Type
records	readonly Record[]
id	string

Returns

Record | undefined

---

testAdapter()

testAdapter(overrides?): Adapter

Parameters

Parameter	Type
overrides	Partial<Adapter>

Returns

Adapter