SDK client and host bridge

The main public integration surface is @ostinato/aionis.

Integration surface

Use the runtime client when you want direct route access. Use the host bridge when your host already thinks in terms of tasks, pause/resume, and session lifecycle.

Direct clientTask session bridgePause / resumeTyped contracts

The package gives you:

the runtime HTTP client
typed request and response contracts
higher-level host bridge utilities for task session flows

Choose the right surface

Use case	Best surface
Call runtime routes directly	Runtime client
Build your own host logic around memory, handoff, replay, or automation	Runtime client
You already have a task object and want session lifecycle helpers	Host bridge
You need pause / resume / complete flows with task-shaped helpers	Host bridge

Runtime client

Use the runtime client when you want direct access to:

memory
handoff
replay
automation
sandbox
review packs

Minimal shape:

import { createAionisClient } from "@ostinato/aionis";

const aionis = createAionisClient({
  baseUrl: "http://127.0.0.1:3001",
});

const taskStart = await aionis.memory.taskStart({
  tenant_id: "default",
  scope: "repair-flow",
  query_text: "repair export serializer bug",
  context: {
    goal: "repair export serializer bug",
  },
  candidates: ["read", "edit", "test"],
});

This is the right layer when you want full control over how your application composes runtime calls.

Host bridge

Use the host bridge when you want a more opinionated task session adapter that bundles:

task start
session events
inspect task context
pause / resume / complete flows

That bridge is useful when your host app already thinks in terms of tasks and lifecycle transitions.

Minimal shape:

import { createAionisHostBridge } from "@ostinato/aionis";

const bridge = createAionisHostBridge({
  baseUrl: "http://127.0.0.1:3001",
});

const session = await bridge.openTaskSession({
  task_id: "task-123",
  text: "repair export serializer bug",
  tenant_id: "default",
  scope: "repair-flow",
  actor: "local-user",
});

const plan = await session.planTaskStart();
const pause = await session.pauseTask({
  summary: "stopped after isolating serializer branch",
  handoff_text: "resume in src/routes/export.ts and verify the JSON payload",
});

What the bridge adds

The host bridge is a task-shaped layer over the same runtime.

What it adds is:

task/session framing
startup planning helpers
session event recording
pause/resume/complete lifecycle helpers
state snapshotting for host-side workflow control

That makes it useful when you are building a real host experience, not just testing raw routes.

Recommended adoption pattern

Most teams should adopt the SDK in this order:

start with the runtime client to understand the public route families
add the host bridge only if your application already has task lifecycle concepts
keep raw route access for advanced flows, even if you also use the bridge

The bridge is opinionated, but it is not all-or-nothing.

SDK client and host bridge ​

Choose the right surface ​

Runtime client ​

Host bridge ​

What the bridge adds ​

Recommended adoption pattern ​

Best reads ​