ns-bridge-core

The host-neutral half of ns-bridge: the vocabulary every vendor core speaks, and one bridge per host family that turns that vocabulary into the host's own types. A dependency of the ns-bridge adapters — not meant to be installed on its own.

The vocabulary (ns-bridge-core)

BridgeMessage, BridgeTool, BridgeContext, BridgeStreamEvent, BridgeUsage, BridgeEffort, BridgeStopReason. ns-kiro-core and ns-devin-core emit this shape structurally — their own request and event types are assignable to it (each core's vocabulary.test.ts pins that). The cores depend on this package for the sidecar client (ns-bridge-core/sidecar); this package never depends on a vendor core.

Pi-family bridge (ns-bridge-core/pi)

For hosts built on Pi's provider API: Pi itself and OMP. Typed against structural *Like shapes, so it serves both @earendil-works/pi-ai and @oh-my-pi/pi-ai without importing either.

| Export | Does | | --- | --- | | toBridgeContext, toBridgeMessages, toBridgeTools | Pi context in: system prompt (string or OMP's string[]), messages, tools | | streamToPi | Vendor events out, as the host's AssistantMessageEventStream | | toBridgeEffort, toPiThinkingLevelMap, toOmpThinking | Reasoning effort, both directions | | getCurrentSystemPrompt, getCurrentTools, withoutInitialSystemMessage | Pi 1.0 transcript helpers OMP does not ship |

Harness bridge (ns-bridge-core/dsh)

For the DeepSeek Harness (@deepseek-ai/dsh-llm, an optional peer).

| Export | Does | | --- | --- | | toBridgeMessagesFromDsh | Harness messages in (dsh 0.2 tool-role messages and dsh 0.1 tool-result blocks), images through the attachment store | | streamToDsh, toDshUsage | Vendor events out, as Harness StreamChunks |

Adding a vendor or a host

A new vendor is a core that emits BridgeStreamEvents; every host gets it through the existing bridges. A new host is one bridge here; every vendor gets it for free. Host adapters stay glue: credentials and the model catalog come from the vendor core, translation from here.

Sidecar client (ns-bridge-core/sidecar)

Runs a vendor call in the ns-bridge Go binary and yields its events, ready for streamToPi or streamToDsh. Protocol: docs/SIDECAR-PROTOCOL.md.

| Export | Does | | --- | --- | | sidecarStream(vendor, request, { signal, binary, env }) | Start ns-bridge stream --vendor <vendor>, yield BridgeStreamEvents; abort closes stdin, then SIGTERM, then SIGKILL | | SidecarError, isSidecarError | The typed failure: kind, status, retryAfterMs, reasonCode, exitCode, stderr | | sidecarCall(vendor, op, request, options) | One ns-bridge call operation (catalog, usage, token refresh); resolves to its result | | engineStream, engineCall, selectBridgeEngine | Run a call on the engine NS_BRIDGE_ENGINE(_<VENDOR>) selects: auto (default) uses the binary when one is installed and falls back to the in-process core when it is missing or too old; go / ts force one | | resolveSidecarBinary, findPackagedSidecarBinary | NS_BRIDGE_BIN, then the explicit path, then the binary ns-bridge-bin installed (an optional peer), then ns-bridge on PATH |

Needs node:child_process (Node or Bun); the root and ./pi / ./dsh entries do not load it.