Split Ambion package into application, host, protocol, and Node entry points

packages/ambion/package.json

@@ -22,6 +22,18 @@
 			"types": "./dist/index.d.mts",
 			"import": "./dist/index.mjs"
 		},
+		"./host": {
+			"types": "./dist/host.d.mts",
+			"import": "./dist/host.mjs"
+		},
+		"./protocol": {
+			"types": "./dist/protocol.d.mts",
+			"import": "./dist/protocol.mjs"
+		},
+		"./node": {
+			"types": "./dist/node.d.mts",
+			"import": "./dist/node.mjs"
+		},
 		"./package.json": "./package.json"
 	},
 	"main": "./dist/index.mjs",

packages/ambion/src/host.ts

@@ -0,0 +1,19 @@
+/** APIs for hosts which own runtimes, persistence, transports, and lifecycle. */
+export type { CreateRuntimeOptions, RunningRoom, Runtime, Transport } from './host/runtime.ts';
+export { createRuntime, defaultRuntime, sessionsOver, systemClock } from './host/runtime.ts';
+export type { Sql, SqlValue } from './host/sqlite.ts';
+export { sqliteSessions } from './host/sqlite.ts';
+export type { SeatContext } from './seat/seat.ts';
+export { createSeatActor, inProcessTransport } from './seat/seat.ts';
+export type { ReadSessionOptions, ResumeSessionOptions, SessionView, Visit } from './session.ts';
+export { readSession, resumeSession, stopSession, visitSession } from './session.ts';
+export { attentive, passive, seated } from './define.ts';
+export { destroyWorkspace } from './tools/workspace.ts';
+export type {
+	Clock,
+	FencedSession,
+	ModelResolver,
+	SessionOpener,
+	WorkspaceBackend,
+} from './types.ts';
+export { isPresence, isSeatedAgent, isSpoken, isSummary } from './types.ts';

packages/ambion/src/index.ts

@@ -1,124 +1,34 @@
-/**
- * The Ambion runtime: five primitives, and a dependency for every other concern.
- *
- * `defineAgent` makes an agent, `defineHuman` names a person, `defineTool`
- * gives agents hands, `defineWorkspace` names the identity and data boundary
- * an agent's tools reach into, `seated` chooses what wakes a seat — with
- * `passive` and `attentive` for the two points worth naming — and
- * `startSession` brings up a named room the agents work in and people visit.
- * A person's question opens an exchange, the room works, and quiescence
- * closes it — the exchange every other feature reads. `stopSession` takes
- * the room down, `readSession` reads a name without starting anything,
- * `visitSession` puts a person in a running room, and `destroyWorkspace`
- * retires a workspace for good. The room's assistant composes the room at
- * the open of an exchange, from the agents held in reserve, and writes the
- * one message a person reads when the exchange closes. The design contracts
- * live in docs/agent.md, docs/exchange.md, docs/presence.md,
- * docs/assistant.md, docs/workspace.md and docs/roster.md.
+/** The small, application-facing Ambion API. Host integration and wire
+ * contracts live at `./host` and `./protocol`; Node adapters live at `./node`.
  */
-
-export type {
-	ExecutionEnv,
-	SessionMetadata,
-	SessionRepo,
-	SessionStorage,
-} from '@earendil-works/pi-agent-core';
-// Storage is Pi's, re-exported — Ambion adds no storage abstraction of its own.
-// `ExecutionEnv` is what a workspace backend's `connect` returns, and Pi's too.
-export {
-	InMemorySessionRepo,
-	InMemorySessionStorage,
-	JsonlSessionRepo,
-} from '@earendil-works/pi-agent-core';
 export type { DefineAgentOptions, DefineHumanOptions, DefineToolOptions } from './define.ts';
-export { attentive, defineAgent, defineHuman, defineTool, passive, seated } from './define.ts';
-export type {
-	CreateRuntimeOptions,
-	RunningRoom,
-	Runtime,
-	SessionRepoLike,
-	Transport,
-} from './host/runtime.ts';
-export { createRuntime, defaultRuntime, sessionsOver, systemClock } from './host/runtime.ts';
-export { type Sql, SqliteSessionStorage, type SqlValue, sqliteSessions } from './host/sqlite.ts';
-export type { SeatContext } from './seat/seat.ts';
-export { inProcessTransport, SeatActor } from './seat/seat.ts';
-export type {
-	ReadSessionOptions,
-	ResumeSessionOptions,
-	Session,
-	SessionView,
-	StartSessionOptions,
-	Visit,
-} from './session.ts';
-export { readSession, resumeSession, startSession, stopSession, visitSession } from './session.ts';
-export type {
-	MemoryBackendFile,
-	MemoryBackendOptions,
-	MemoryWorkspaceBackend,
-	SeedWriter,
-} from './tools/just-bash.ts';
-// A workspace over a real directory, or the in-memory default with seeding
-// and read-back. Neither import is needed for the in-memory default's own
-// use inside `defineWorkspace` — only a host that wants to seed or read it.
-export { directoryBackend, memoryBackend } from './tools/just-bash.ts';
-export type { DefineWorkspaceOptions } from './tools/workspace.ts';
-export { defineWorkspace, destroyWorkspace } from './tools/workspace.ts';
+export { defineAgent, defineHuman, defineTool } from './define.ts';
+export type { Session, StartSessionOptions } from './session.ts';
+export { startSession } from './session.ts';
 export type {
 	AgentDefinition,
 	AgentSeat,
 	AgentSeatInfo,
 	AmbionTool,
 	Attention,
-	Clock,
 	ClosedExchange,
 	Exchange,
-	FencedSession,
 	HumanDefinition,
 	HumanSeatInfo,
 	Message,
-	ModelResolver,
 	Participant,
-	PresenceChange,
 	PresenceMessage,
 	PresenceStatus,
 	SeatedAgent,
 	SeatInfo,
 	SeatStatus,
 	Seq,
 	SessionEvent,
-	SessionOpener,
 	SpokenMessage,
 	SummaryMessage,
 	ToolContext,
 	Workspace,
-	WorkspaceBackend,
 	WorkspaceHandle,
 } from './types.ts';
-export { isPresence, isSeatedAgent, isSpoken, isSummary } from './types.ts';
-export type {
-	ActivationView,
-	CheckpointRow,
-	CloseRow,
-	Commit,
-	CommitResponse,
-	CompositionRow,
-	EndReason,
-	Hand,
-	Intent,
-	Lease,
-	LeaseHold,
-	LeaseResponse,
-	LeaseRow,
-	RunRow,
-	SeatPort,
-	SeatRoom,
-	SeatRow,
-	Stale,
-	ViewResponse,
-	Wake,
-} from './wire.ts';
-export { assertWire, roundTrip } from './wire.ts';
-
-/** Kept in step with package.json by a test. */
-export const PACKAGE_NAME = '@ambionframework/ambion';
+export type { DefineWorkspaceOptions } from './tools/workspace.ts';
+export { defineWorkspace } from './tools/workspace.ts';

packages/ambion/src/internal.ts

@@ -0,0 +1,124 @@
+/**
+ * The Ambion runtime: five primitives, and a dependency for every other concern.
+ *
+ * `defineAgent` makes an agent, `defineHuman` names a person, `defineTool`
+ * gives agents hands, `defineWorkspace` names the identity and data boundary
+ * an agent's tools reach into, `seated` chooses what wakes a seat — with
+ * `passive` and `attentive` for the two points worth naming — and
+ * `startSession` brings up a named room the agents work in and people visit.
+ * A person's question opens an exchange, the room works, and quiescence
+ * closes it — the exchange every other feature reads. `stopSession` takes
+ * the room down, `readSession` reads a name without starting anything,
+ * `visitSession` puts a person in a running room, and `destroyWorkspace`
+ * retires a workspace for good. The room's assistant composes the room at
+ * the open of an exchange, from the agents held in reserve, and writes the
+ * one message a person reads when the exchange closes. The design contracts
+ * live in docs/agent.md, docs/exchange.md, docs/presence.md,
+ * docs/assistant.md, docs/workspace.md and docs/roster.md.
+ */
+
+export type {
+	ExecutionEnv,
+	SessionMetadata,
+	SessionRepo,
+	SessionStorage,
+} from '@earendil-works/pi-agent-core';
+// Storage is Pi's, re-exported — Ambion adds no storage abstraction of its own.
+// `ExecutionEnv` is what a workspace backend's `connect` returns, and Pi's too.
+export {
+	InMemorySessionRepo,
+	InMemorySessionStorage,
+	JsonlSessionRepo,
+} from '@earendil-works/pi-agent-core';
+export type { DefineAgentOptions, DefineHumanOptions, DefineToolOptions } from './define.ts';
+export { attentive, defineAgent, defineHuman, defineTool, passive, seated } from './define.ts';
+export type {
+	CreateRuntimeOptions,
+	RunningRoom,
+	Runtime,
+	SessionRepoLike,
+	Transport,
+} from './host/runtime.ts';
+export { createRuntime, defaultRuntime, sessionsOver, systemClock } from './host/runtime.ts';
+export { type Sql, SqliteSessionStorage, type SqlValue, sqliteSessions } from './host/sqlite.ts';
+export type { SeatContext } from './seat/seat.ts';
+export { inProcessTransport, SeatActor } from './seat/seat.ts';
+export type {
+	ReadSessionOptions,
+	ResumeSessionOptions,
+	Session,
+	SessionView,
+	StartSessionOptions,
+	Visit,
+} from './session.ts';
+export { readSession, resumeSession, startSession, stopSession, visitSession } from './session.ts';
+export type {
+	MemoryBackendFile,
+	MemoryBackendOptions,
+	MemoryWorkspaceBackend,
+	SeedWriter,
+} from './tools/just-bash.ts';
+// A workspace over a real directory, or the in-memory default with seeding
+// and read-back. Neither import is needed for the in-memory default's own
+// use inside `defineWorkspace` — only a host that wants to seed or read it.
+export { directoryBackend, memoryBackend } from './tools/just-bash.ts';
+export type { DefineWorkspaceOptions } from './tools/workspace.ts';
+export { defineWorkspace, destroyWorkspace } from './tools/workspace.ts';
+export type {
+	AgentDefinition,
+	AgentSeat,
+	AgentSeatInfo,
+	AmbionTool,
+	Attention,
+	Clock,
+	ClosedExchange,
+	Exchange,
+	FencedSession,
+	HumanDefinition,
+	HumanSeatInfo,
+	Message,
+	ModelResolver,
+	Participant,
+	PresenceChange,
+	PresenceMessage,
+	PresenceStatus,
+	SeatedAgent,
+	SeatInfo,
+	SeatStatus,
+	Seq,
+	SessionEvent,
+	SessionOpener,
+	SpokenMessage,
+	SummaryMessage,
+	ToolContext,
+	Workspace,
+	WorkspaceBackend,
+	WorkspaceHandle,
+} from './types.ts';
+export { isPresence, isSeatedAgent, isSpoken, isSummary } from './types.ts';
+export type {
+	ActivationView,
+	CheckpointRow,
+	CloseRow,
+	Commit,
+	CommitResponse,
+	CompositionRow,
+	EndReason,
+	Hand,
+	Intent,
+	Lease,
+	LeaseHold,
+	LeaseResponse,
+	LeaseRow,
+	RunRow,
+	SeatPort,
+	SeatRoom,
+	SeatRow,
+	Stale,
+	ViewResponse,
+	Wake,
+} from './wire.ts';
+export { assertWire, roundTrip } from './wire.ts';
+
+/** Kept in step with package.json by a test. */
+export const PACKAGE_NAME = '@ambionframework/ambion';

packages/ambion/src/node.ts

@@ -0,0 +1,8 @@
+/** Filesystem-backed workspace adapters for Node.js hosts. */
+export type {
+	MemoryBackendFile,
+	MemoryBackendOptions,
+	MemoryWorkspaceBackend,
+	SeedWriter,
+} from './tools/just-bash.ts';
+export { directoryBackend, memoryBackend } from './tools/just-bash.ts';

packages/ambion/src/protocol.ts

@@ -0,0 +1,22 @@
+/** Stable JSON values exchanged by a room and a remote seat. */
+export type {
+	ActivationView,
+	CloseRow,
+	Commit,
+	CommitResponse,
+	EndReason,
+	Hand,
+	Intent,
+	Lease,
+	LeaseResponse,
+	LeaseRow,
+	CompositionRow,
+	RunRow,
+	SeatPort,
+	SeatRoom,
+	SeatRow,
+	Stale,
+	ViewResponse,
+	Wake,
+} from './wire.ts';
+export { assertWire, roundTrip } from './wire.ts';

packages/ambion/src/seat/seat.ts

@@ -338,6 +338,16 @@ export class SeatActor implements SeatPort {
 	}
 }
 
+/** Build the seat side of a host transport without exposing its implementation class. */
+export function createSeatActor(
+	room: SeatRoom,
+	context: SeatContext,
+): SeatPort & {
+	run(activation: string): Promise<void>;
+} {
+	return new SeatActor(room, context);
+}
+
 // -- the transport ------------------------------------------------------------
 
 /** Every seat is an actor in this process, holding the room directly. */

packages/ambion/test/assistant.test.ts

@@ -19,7 +19,7 @@ import {
 	startSession,
 	stopSession,
 	visitSession,
-} from '../src/index.ts';
+} from '../src/internal.ts';
 import { renderRecord } from '../src/render.ts';
 import { fakeClock } from './support/clock.ts';
 import { assistantEnded, collect, deferred, roomName as name, tick } from './support/room.ts';

packages/ambion/test/chaos.test.ts

@@ -26,7 +26,7 @@ import {
 	type Session,
 	stopSession,
 	visitSession,
-} from '../src/index.ts';
+} from '../src/internal.ts';
 import { agents, priya, type Question, questions, sam, script, TIMING } from './support/cast.ts';
 import { idle, liveLeases, outcome, World, within } from './support/chaos.ts';
 import { type FakeClock, fakeClock } from './support/clock.ts';

packages/ambion/test/checkpoint.test.ts

@@ -5,7 +5,7 @@
  * messages stay, and a room that folds the rest behaves the same.
  */
 import { describe, expect, it } from 'vitest';
-import type { CompositionRow, Seq } from '../src/index.ts';
+import type { CompositionRow, Seq } from '../src/internal.ts';
 import {
 	createRuntime,
 	defineAgent,
@@ -17,7 +17,7 @@ import {
 	startSession,
 	stopSession,
 	visitSession,
-} from '../src/index.ts';
+} from '../src/internal.ts';
 import { RoomLog } from '../src/log/log.ts';
 import { checkpointOf, foldRoom, type RoomState } from '../src/room/fold.ts';
 import { type FakeClock, fakeClock } from './support/clock.ts';

packages/ambion/test/consistency.test.ts

@@ -20,7 +20,7 @@ import {
 	stopSession,
 	type Visit,
 	visitSession,
-} from '../src/index.ts';
+} from '../src/internal.ts';
 import { foldRoom } from '../src/room/fold.ts';
 import { agents, assistant, colleague, priya, product, sam, troubled } from './support/cast.ts';
 import { liveLeases } from './support/chaos.ts';

packages/ambion/test/doubt.test.ts

@@ -13,7 +13,7 @@ import {
 	type SessionEvent,
 	startSession,
 	visitSession,
-} from '../src/index.ts';
+} from '../src/internal.ts';
 import { fakeClock } from './support/clock.ts';
 import { collect, roomName, rowsOf } from './support/room.ts';
 import {