Reference#

This page lists Conduit's public surface: the package entrypoints, types, adapter factories, host profiles, lifecycle helpers, conformance API, and the repository's npm scripts. Concepts explains how the pieces fit together.

Entrypoints#

All code entrypoints are ES modules with TypeScript declarations. The package requires Node 22 or newer.

Core types#

install and project return promises. An installation receipt and its installed and skipped arrays are frozen, but the freeze is shallow: the entries inside the arrays are not frozen.

Adapter factories#

createManifestHarnessAdapter#

createManifestHarnessAdapter(options: ManifestHarnessOptions): AgentHostAdapter

ManifestHarnessOptions is { id, capabilities, resolveTarget(asset), write(target, content) }. resolveTarget returns a target string or undefined. write may return a promise, which install awaits.

install calls resolveTarget for each asset, in order. It skips the asset with reason unsupported if the kind's install fidelity is unavailable, or unmapped if no target was returned. Otherwise it calls write and records the asset's digest.

createInProcessHostAdapter#

createInProcessHostAdapter(options: InProcessHostOptions): AgentHostAdapter

InProcessHostOptions is { id, capabilities, installAsset?(asset), applyOutcome(event, outcome) }.

install skips an asset with reason unsupported if installAsset is missing or the kind's install fidelity is unavailable, and otherwise calls installAsset. project awaits applyOutcome and then applies outcome projection to its result.

Named factories#

Each named factory fixes the adapter id and capability profile and takes only the caller's bindings.

LocalHarnessBinding is { resolveTarget, write }. FrameworkBridge is { installAsset?, applyOutcome }.

Host profiles#

Each profile is exported as a frozen HostCapabilities constant: claudeCodeCapabilities, codexCapabilities, openCodeCapabilities, strandsCapabilities, and voltAgentCapabilities from the main entrypoint, piCapabilities from /pi, and kiroCapabilities from /kiro.

Lifecycle, decision, and context fidelity for every phase is listed in the host conformance matrix. Install fidelity per asset kind:

Notes recorded in the source and the committed evidence:

• Codex exposes no lifecycle surface except before-tool, which can block and inject context, and an observational stop. Its hook install is approximated because a copied project hook is not active until Codex trusts its exact definition.
• Pi targets Pi 0.80.6 and later extensions. It can block at before-tool and inject context at before-model.
• Kiro targets Kiro CLI 2.13 and later custom-agent hooks, not standalone IDE hook files. It can block at before-tool and stop, and inject context at session-start and before-model.
• Strands and VoltAgent are caller-bound. Conduit does not depend on either framework package.

Lifecycle binding#

bindAdapterLifecycle#

bindAdapterLifecycle(options: LifecycleBindingOptions): () => void

LifecycleBindingOptions is { adapter, registrar, evaluate(event) }, where registrar is a LifecycleRegistrar:

interface LifecycleRegistrar {
  register(phase: LifecyclePhase, handler: LifecycleHandler): void | (() => void);
}
type LifecycleHandler = (event: LifecycleEvent) => Promise<LifecycleOutcome>;

For each phase whose lifecycle fidelity is not unavailable, it calls registrar.register once with a handler that runs evaluate and then adapter.project. The handler throws if it receives an event for a different phase. The returned function calls every disposer that register returned, in reverse registration order. Disposal happens once: calling the returned function again is a no-op.

Pi entrypoint#

createPiLifecycleHandlers#

createPiLifecycleHandlers(options: PiExtensionBindingOptions): PiLifecycleHandlers

PiExtensionBindingOptions is { adapter, sessionId(phase, event, context), evaluate(event) }. sessionId returns the host's session identity. Each handler builds a LifecycleEvent with context: { hostEvent: event }, runs evaluate, and projects the result through the adapter.

Installation goes through createPiAdapter, which needs explicit resolveTarget and write bindings.

Kiro entrypoint#

evaluateKiroHook#

evaluateKiroHook(options: KiroHookBindingOptions, event: KiroHookEvent): Promise<KiroHookResult>

KiroHookBindingOptions is { adapter, evaluate(event) }. KiroHookEvent is the decoded hook JSON: hook_event_name, cwd, session_id, and the optional prompt, tool_name, tool_input, tool_response, and assistant_response. The caller reads and parses stdin, then writes the result's stdout and stderr unchanged and exits with exitCode.

Hook events map to phases as follows. session_id becomes the event's sessionId, and the hook event is passed as context.hostEvent.

Any other hook_event_name is refused: evaluateKiroHook rejects with UnsupportedKiroHookEventError (code: "UNSUPPORTED_KIRO_HOOK_EVENT", with the received name in hookEventName) before evaluate runs. Conduit does not guess a phase for an event it cannot classify. The caller decides how its hook process reports the error; exiting with a status other than 0 or 2 makes Kiro treat it as a hook failure rather than a block.

The projected outcome becomes a KiroHookResult:

Installation goes through createKiroAdapter, which needs explicit resolveTarget and write bindings. Registering the executable bridge in a Kiro custom-agent configuration is the application's job.

Conformance API#

EvidenceInput is { adapter, evidenceScope, adapterVersion, hostId, hostVersion, limitations? }. evidenceScope is "adapter-contract" or "host-bound".

ConformanceReport is { schemaVersion: "2", adapters: AdapterConformanceEvidence[] }. Each AdapterConformanceEvidence has evidenceScope, adapterId, adapterVersion, hostId, hostVersion, normalized capabilities, limitations, and results.

UnsupportedConformanceSchemaVersionError has code UNSUPPORTED_CONFORMANCE_SCHEMA_VERSION and a schemaVersion property holding the version it found. parseConformanceReport checks only the schema version; it does not validate the rest of the report against the JSON Schema.

Repository scripts#

These npm scripts run in a checkout of this repository.