@nylorun/agents 0.5.0-beta → 0.6.0-beta

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @nylorun/agents
 
+## 0.6.0-beta
+
+### Minor Changes
+
+- c49efed: **Breaking (pre-1.0 minor):** Tenant API connection and executor credentials for Runtime Clients.
+
+  - `resolveConnection()` — options → environment → Project link; sources never mix.
+  - `createClient()` with no arguments uses `resolveConnection`.
+  - `connectAgents` application mode: save agents, `PUT /v1/executors` with **derived** tokens (HMAC of application key + Tenant + agent id), connect; tokens are not stored in Project credentials.
+  - Re-exports `PROTOCOL_FEATURES`, `ERROR_CODES`, `compareVersions`.
+
+- c49efed: **Breaking (pre-1.0 minor):** Replace a single SQLite Runtime per Project or home directory with a **Runtime Host** that serves isolated **Tenants**, selected by `Nylorun-Tenant` and negotiated with `Nylorun-Protocol` (protocol `2`, feature `runtime-tenants`). Vocabulary: Host root + Tenant + Project link.
+
+  - **core:** `PROTOCOL_VERSION = 2`, `HOST_PROTOCOL`, `TENANT_HEADER`, `PROTOCOL_HEADER`, `newTenantId` / `isTenantId`, `checkCompatibility`; health schema gains `hostId` + `protocol` (`service: "nylorun-runtime"`); Tenant/admin wire schemas; Tenant model routes under `/v1/tenant/*`.
+  - **runtime:** Host process + Tenant module; Tenant model routes under `/v1/tenant/*`; `startEphemeralRuntime` for tests/embeds; executors via `PUT /v1/executors`; sandbox prefix `nylorun-<tenant-id>-`.
+  - **agents:** `createClient({ url, key, tenant })`; Transport sends Tenant + protocol headers; `/health` compatibility cache; `IncompatibleRuntimeError` with upgrade remedies.
+  - **cli:** Host root lifecycle (`runtime up|down|status|logs|restart|run`); Project link (`.nylorun/link.json` + `credentials.json`); `tenant` commands; `runtime status --env` exports `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY`, `NYLORUN_TENANT`; removed Project/home SQLite selectors.
+  - **studio:** `startStudio({ …, tenant: { id, name } })`; proxy forwards Tenant + protocol headers; UI shows Tenant name/short id.
+
+- fd9fd87: Add workflows: compose agents and `tool()` with `Chain`, `Switch`, `Parallel`, `Map`, and `Loop`. A workflow is a registered runnable (`kind: "workflow"`) with the same session API as an agent — `export const agents`, `saveAgent` (saves referenced agents first), `createSession`, `input` (`content` or `data`), `observe({ follow })`, `pending`, `approve`, `cancel`. Slots (`{ run, id?, input? }`) reshape data between nodes. The flow engine (`runFlowDurable`) returns effects only; `harness/src/loop/` and `runDurable` are unchanged.
+
+  HostEffect gains flow kinds `agent`, `tool` (node), `fn`, and `verify`, each with `path`, `key`, and `iterations`. The Runtime drives agent nodes through the public session contract (linked sessions, shared sandbox via `PutSession.sandbox`), offers `fn` / `verify` again on lease expiry, and routes executor Actions by `(workflowId, key)` with claim-scoped `ctx.sandbox`. Optional `message.manifest` is a turn-only variant of the session pin (turn manifests). Studio shows the manifest tree, live node status, and session links. Examples under `examples/agents/{chain,switch,parallel,map,loop,ship-feature}/`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [c49efed]
+- Updated dependencies [c49efed]
+- Updated dependencies [fd9fd87]
+  - @nylorun/core@0.5.0-beta
+
 ## 0.5.0-beta
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,39 @@
 # @nylorun/agents
 
-One application install provides definition authoring, a session client, and a connected customer executor. This beta is currently built locally; no packages were published in this pass. Use the workspace or install packed SDK and core artifacts together until publishing is enabled.
+Tenant API client package: definition authoring, a session client, and a
+connected customer executor. Depends only on `@nylorun/core` among Nylorun
+packages. A developer application's production tree should contain only this
+package and `@nylorun/core` from Nylorun. Vocabulary:
+[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+
+## Application entry (preferred)
+
+```ts
+// src/main.ts
+import { connectAgents } from "@nylorun/agents";
+import { agents } from "../agents/index.js";
+
+await connectAgents({ agents }).ready;
+```
+
+Application mode saves definitions, registers **derived** executor credentials
+(HMAC of the application key + Tenant + agent id), and connects. Restarts and
+replicas re-register the same hashes; tokens are never stored in the Project.
+The same entry runs under `nylorun dev` and as `node dist/src/main.js`
+(`npm start`). See [MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta)
+for upgrading from `nylorun serve`.
+
+## Connection resolution
+
+`resolveConnection` / `createClient()` / `connectAgents({ agents })`:
+
+1. Explicit `{ url, tenant, key }`
+2. Environment — if any of `NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT`,
+   `NYLORUN_SERVER_KEY` or `NYLORUN_EXECUTOR_KEY` is set, all required pieces
+   must be present (role `executor` when `NYLORUN_EXECUTOR_KEY` is set)
+3. Project link — `.nylorun/link.json` + `credentials.json` (application role)
+
+Sources never mix. Partial environment fails with `connection_missing`.
 
 ```ts
 import { Agent, createClient, connectAgents, tool } from "@nylorun/agents";
@@ -21,10 +54,11 @@ const assistant = Agent({
   ],
 });
 
-// Run these application operations on your trusted backend.
+// Explicit Tenant API client (options or env / link via createClient()).
 const client = createClient({
   url: process.env.NYLORUN_RUNTIME_URL,
   key: process.env.NYLORUN_SERVER_KEY,
+  tenant: process.env.NYLORUN_TENANT,
 });
 await client.saveAgent(assistant, { implementationVersion: "app-1" });
 const session = await client.createSession({
@@ -34,21 +68,33 @@ const session = await client.createSession({
 await session.input("Look up item 123", { idempotencyKey: requestId });
 const history = await session.history();
 
-// Customer executor process: credential is separately scoped by the Runtime.
+// Executor-only mode when you already hold an executor key:
 const connection = connectAgents({
   agents: [assistant],
   implementationVersion: "app-1",
   runtime: {
     url: process.env.NYLORUN_RUNTIME_URL,
     key: process.env.NYLORUN_EXECUTOR_KEY,
+    tenant: process.env.NYLORUN_TENANT,
   },
   onError: console.error,
 });
 await connection.ready;
-// On shutdown:
 await connection.close();
 ```
 
+```sh
+eval "$(npx nylorun runtime status --env)"
+# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
+```
+
+Every request sets `Nylorun-Tenant` and `Nylorun-Protocol`. A `tenant` field in a
+body or query is never read from caller input. Before the first authenticated
+request, `Transport` fetches `/health` once, checks protocol compatibility, and
+throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
+required features do not match. Re-exports include `PROTOCOL_FEATURES`,
+`ERROR_CODES` and `compareVersions`.
+
 Load Agent Skills from a local catalog folder with `skills(path)`:
 
 ```ts
@@ -80,7 +126,7 @@ const assistant = Agent({
       type: "streamable-http",
       url: "https://mcp.example.com/github",
     },
-  })
+  }),
 );
 ```
 
@@ -108,7 +154,7 @@ The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux mac
 }))
 ```
 
-The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, `scope`, ...) throw a `SandboxError` that says so. See [the sandbox design](../docs/design/sandboxes.md).
+The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, …) throw a `SandboxError` that says so. See [the sandbox design](../docs/design/sandboxes.md).
 
 Put an agent in another agent's `tools` to let the model delegate to it:
 
@@ -118,15 +164,21 @@ import { z } from "zod";
 
 const researcher = Agent({
   id: "researcher",
-  description: "Investigates an order's history. Returns a short summary with the ids it relied on.",
-  instructions: "Investigate one question about one order. Be exhaustive, then be brief.",
+  description:
+    "Investigates an order's history. Returns a short summary with the ids it relied on.",
+  instructions:
+    "Investigate one question about one order. Be exhaustive, then be brief.",
   tools: [searchOrders, readTicket],
-  outputSchema: z.object({ summary: z.string(), evidence: z.array(z.string()) }),
+  outputSchema: z.object({
+    summary: z.string(),
+    evidence: z.array(z.string()),
+  }),
 });
 
 const support = Agent({
   id: "support",
-  instructions: "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.",
+  instructions:
+    "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.",
   tools: [lookupOrder, refundOrder, researcher],
 });
 ```
@@ -135,11 +187,100 @@ The tool is named after the agent's `id` and takes `{ task: string }`; the agent
 
 Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `before("step")` patch instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. Delegation is not an approval boundary; approvals live on tools.
 
+## Workflows
+
+Nest `Chain`, `Switch`, `Parallel`, `Map`, and `Loop` around agents and `tool()` to
+build durable flows. A workflow is a definition with `kind: "workflow"`: register
+it in `export const agents` (or `saveAgent(workflow)` — referenced agents are
+saved first), then `createSession({ agentId })` and `session.input(value)` like
+any agent. `input` sends string values as `content` and other JSON as `data`.
+`connectAgents({ agents: [workflow] })` saves the tree and connects executors for
+the workflow id and every referenced agent. Tool nodes, pure functions (slot
+`input`, Switch `on`, Map `over`, Loop `decide`), and Loop `verify` run as Actions
+routed by `(workflowId, key)`.
+
+```ts
+import { Agent, Chain, Loop, Map, tool } from "@nylorun/agents";
+import { z } from "zod";
+
+const planner = Agent({
+  id: "planner",
+  instructions: "Return { tasks: string[] }.",
+  outputSchema: z.object({ tasks: z.array(z.string()) }),
+}).build();
+
+const coder = Agent({
+  id: "coder",
+  instructions: "Implement one task. Return { summary }.",
+  outputSchema: z.object({ summary: z.string() }),
+}).build();
+
+const openPr = tool({
+  name: "open-pr",
+  input: z.object({ summaries: z.array(z.string()) }),
+  async run({ summaries }, ctx) {
+    if (!(await ctx.approve("Open the PR?"))) throw new Error("Rejected");
+    return { opened: true, count: summaries.length };
+  },
+});
+
+export const shipFeature = Chain({
+  id: "ship-feature",
+  steps: [
+    planner,
+    Map({
+      id: "implement",
+      over: (plan) => plan.tasks,
+      each: Loop({
+        id: "code",
+        run: coder,
+        verify: () => ({ pass: true }),
+        decide: ({ output }) => ({ output }),
+      }),
+    }),
+    {
+      run: openPr,
+      input: ({ value }) => ({
+        summaries: value.map((item: { summary: string }) => item.summary),
+      }),
+    },
+  ],
+});
+
+export const agents = [shipFeature];
+```
+
+| Primitive | Role |
+| --- | --- |
+| **Chain** | Steps in order; slots reshape with `{ run, id?, input? }` |
+| **Switch** | Pure `on(input) → key`, then the matching case (or `default`) |
+| **Parallel** | Fixed named branches at once; output is an object |
+| **Map** | Pure `over(input) → items`, one child per item; output is an array |
+| **Loop** | `run` → `verify` → `decide` until `{ output }` |
+
+Agents inside a workflow keep their own sessions (linked from the workflow
+session) and share one sandbox: declare identical specs on every agent that
+uses one, attach with `createSession({ …, sandbox: { session } })`, call
+built-ins via `session.sandbox` (application) or `ctx.sandbox` (executor).
+Observe with `session.observe({ follow: true })` to merge linked agent streams;
+`pending()` lists waits across the tree. Studio renders the manifest tree and
+live node status. Source examples:
+`examples/agents/{chain,switch,parallel,map,loop,ship-feature}/` (outside the
+default release registry). Host contract:
+[HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). Vocabulary (turn loop vs
+workflow Loop): [harness/src/CONTEXT.md](../harness/src/CONTEXT.md).
+
 Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
-The Runtime destination is explicit, or defaults from `NYLORUN_RUNTIME_URL`. Application and executor keys default from `NYLORUN_SERVER_KEY` and `NYLORUN_EXECUTOR_KEY`. Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`, then `dev`. A host must provision executor scope for the agent id. Agents do not hash the manifest, and an in-flight action stays claimable after the registered digest changes. Model selection and model credentials belong to the Runtime.
+Connection defaults follow `resolveConnection` (options → environment → Project
+link). Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`,
+then `dev`. Application mode of `connectAgents({ agents })` registers derived
+executor principals; executor-only mode still takes an explicit executor key.
+Agents do not hash the manifest, and an in-flight action stays claimable after
+the registered digest changes. Model selection and model credentials belong to
+the Tenant.
 
-`connectAgents({ agents })` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims pending actions for a connected agent id. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
+After registration, `connectAgents` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims pending actions for a connected agent id. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
 
 Tools receive state, info, identity, resume, signal, approval/response helpers and memoized `step`. Step outcomes survive a persisted wait result; they do not establish exactly-once external effects after an unacknowledged crash. `sleep` and `waitFor` currently return inspectable deferred outcomes; automatic timer/event wakeups remain runtime implementation work. Remote `onModelCall` convenience and progress-event transport are not supplied in this pass. Arbitrary middleware closures are rejected for durable definitions; use `before`/`after` hooks. The executor runs every capability registered at a hook point in one action. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
 

package/dist/client.d.ts

@@ -1,11 +1,15 @@
-import type { AgentManifest, BuiltAgent, JsonValue } from "@nylorun/core/define";
+import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
 import { type CredentialInfo, type CredentialSelection, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
 import { Transport, type Destination } from "./http.js";
+/** Application-principal access to a session's sandbox built-ins (workflows.md §8). */
+export type SessionSandbox = {
+    readonly [K in SandboxToolName]: (args: Record<string, unknown>) => Promise<unknown>;
+};
 export interface AgentSource {
     readonly id: string;
-    readonly manifest: AgentManifest;
-    build?(): BuiltAgent;
-    getBinding?: BuiltAgent["getBinding"];
+    readonly manifest: AgentManifest | WorkflowManifest;
+    build?(): BuiltAgent | BuiltWorkflow;
+    getBinding?: BuiltAgent["getBinding"] | BuiltWorkflow["getBinding"];
 }
 /** Closures stay on the live binding. The published manifest cannot name them. */
 export declare function assertNoMiddlewareClosures(agent: AgentSource): void;
@@ -15,6 +19,7 @@ export interface SessionView {
     ownerUserId: string;
     status: string;
     activeTurnId: string | null;
+    waits?: unknown;
     [key: string]: unknown;
 }
 export declare class AgentsClient {
@@ -33,7 +38,7 @@ export declare class AgentsClient {
     }): Promise<{
         sessions: SessionView[];
     }>;
-    saveAgent(agent: AgentSource, options: {
+    saveAgent(agent: AgentSource | BuiltWorkflow, options: {
         implementationVersion: string;
         requestId?: string;
     }): Promise<unknown>;
@@ -45,6 +50,10 @@ export declare class AgentsClient {
         requestId?: string;
         vaultIds?: readonly string[];
         credentialSelections?: readonly CredentialSelection[];
+        /** Share another session's sandbox (public PutSession.sandbox). */
+        sandbox?: {
+            session: string;
+        };
     }): Promise<SessionClient>;
     createVault(options: {
         name: string;
@@ -118,16 +127,23 @@ export type CommandOptions = {
 export declare class SessionClient {
     private readonly transport;
     readonly id: string;
+    readonly sandbox: SessionSandbox;
     constructor(transport: Transport, id: string);
     private get path();
     inspect(signal?: AbortSignal): Promise<SessionView>;
+    /** Pending waits / interactions from the session inspect view. */
+    pending(signal?: AbortSignal): Promise<{}>;
     command(command: SessionCommand, signal?: AbortSignal): Promise<{
         status: "accepted";
         turnId: string | null;
         cursor: string | null;
         requestId: string;
     }>;
-    input(content: string, options: CommandOptions): Promise<{
+    /**
+     * Start a turn. Strings become `message.content`; any other JSON value becomes
+     * `message.data` (workflows.md §5).
+     */
+    input(value: string | JsonValue, options: CommandOptions): Promise<{
         status: "accepted";
         turnId: string | null;
         cursor: string | null;
@@ -162,6 +178,7 @@ export declare class SessionClient {
         items: {
             eventId: string;
             sessionId: string;
+            tenantId: string;
             turnId: string | null;
             cursor: string;
             createdAt: string;
@@ -173,17 +190,32 @@ export declare class SessionClient {
     observe(options?: {
         cursor?: string;
         signal?: AbortSignal;
+        follow?: boolean;
     }): AsyncGenerator<{
         eventId: string;
         sessionId: string;
+        tenantId: string;
         turnId: string | null;
         cursor: string;
         createdAt: string;
         type: string;
         payload: unknown;
     }, void, unknown>;
+    private observeOne;
+    /**
+     * Own session stream plus linked agent sessions announced in `node.agent`
+     * events, merged by `createdAt` then arrival order (workflows.md §11).
+     */
+    private observeFollowing;
 }
-export declare function createClient(destination?: Destination): AgentsClient;
-export { RuntimeError } from "./http.js";
-export type { Destination } from "./http.js";
+/**
+ * Build a Tenant API client.
+ * Explicit connection fields keep today's sync Transport resolution (including
+ * environment fill-ins). With no connection fields, resolves via
+ * `resolveConnection` (environment → project link).
+ */
+export declare function createClient(destination: Destination): AgentsClient;
+export declare function createClient(destination?: undefined): Promise<AgentsClient>;
+export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
+export type { Destination, IncompatibleReason } from "./http.js";
 export type { LiveEvent } from "@nylorun/core/contracts";

package/dist/client.js

@@ -1,14 +1,42 @@
-import { delegateOf } from "@nylorun/core/define";
+import { SANDBOX_TOOL_NAMES, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
 import { LiveEventSchema, SessionItemsResponseSchema, } from "@nylorun/core/contracts";
+import { resolveConnection } from "./connection.js";
 import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
+function sessionSandboxOf(transport, sessionId) {
+    const call = (tool, args) => transport.json(`/v1/sessions/${segment(sessionId)}/sandbox/${segment(tool)}`, "POST", args);
+    const sandbox = {};
+    for (const tool of SANDBOX_TOOL_NAMES) {
+        if (!isSandboxToolName(tool))
+            continue;
+        sandbox[tool] = (args) => call(tool, args);
+    }
+    return sandbox;
+}
+function linkedSessionId(event) {
+    if (event.type !== "node.agent")
+        return undefined;
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return undefined;
+    const sessionId = payload.sessionId;
+    return typeof sessionId === "string" && sessionId.length > 0
+        ? sessionId
+        : undefined;
+}
 const middlewareClosure = "Hosted definitions support declarative capabilities and before/after hooks, not middleware closures";
 /** The agent's declarations, then those of each agent it uses as a tool, keyed `<child>/<capability>`. */
 function declarationsOf(agent) {
+    if (isBuiltWorkflow(agent) || agent.manifest.kind === "workflow")
+        return [];
     const built = agent.build?.() ?? agent;
+    if (isBuiltWorkflow(built))
+        return [];
     const binding = built.getBinding?.();
-    const found = (binding?.declarations ?? []).map((item) => ({ key: item.id, item }));
-    for (const tool of binding?.tools ?? []) {
+    if (!binding || !("declarations" in binding))
+        return [];
+    const found = (binding.declarations ?? []).map((item) => ({ key: item.id, item }));
+    for (const tool of binding.tools ?? []) {
         const child = delegateOf(tool)?.agent;
         for (const item of child?.getBinding().declarations ?? [])
             found.push({ key: `${child.id}/${item.id}`, item });
@@ -41,7 +69,21 @@ export class AgentsClient {
             : "";
         return this.transport.json(`/v1/sessions${query}`, "GET", undefined, options.signal);
     }
-    saveAgent(agent, options) {
+    async saveAgent(agent, options) {
+        if (isBuiltWorkflow(agent)) {
+            for (const binding of Object.values(agent.getBinding().agents)) {
+                await this.saveAgent({
+                    id: binding.manifest.id,
+                    manifest: binding.manifest,
+                    getBinding: () => binding,
+                }, options);
+            }
+            return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
+                requestId: options.requestId ?? id(),
+                manifest: agent.manifest,
+                implementationVersion: options.implementationVersion,
+            });
+        }
         assertNoMiddlewareClosures(agent);
         const pluginRoots = pluginRootsOf(agent);
         return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
@@ -62,6 +104,7 @@ export class AgentsClient {
             ...(options.credentialSelections
                 ? { credentialSelections: options.credentialSelections }
                 : {}),
+            ...(options.sandbox ? { sandbox: options.sandbox } : {}),
         });
         return this.session(sessionId);
     }
@@ -114,9 +157,11 @@ export class AgentsClient {
 export class SessionClient {
     transport;
     id;
+    sandbox;
     constructor(transport, id) {
         this.transport = transport;
         this.id = id;
+        this.sandbox = sessionSandboxOf(transport, id);
     }
     get path() {
         return `/v1/sessions/${segment(this.id)}`;
@@ -124,16 +169,27 @@ export class SessionClient {
     inspect(signal) {
         return this.transport.json(this.path, "GET", undefined, signal);
     }
+    /** Pending waits / interactions from the session inspect view. */
+    async pending(signal) {
+        const view = await this.inspect(signal);
+        return view.waits ?? [];
+    }
     command(command, signal) {
         return this.transport.json(`${this.path}/commands`, "POST", command, signal);
     }
-    input(content, options) {
-        return this.command({
+    /**
+     * Start a turn. Strings become `message.content`; any other JSON value becomes
+     * `message.data` (workflows.md §5).
+     */
+    input(value, options) {
+        const base = {
             type: "message",
-            content,
             requestId: options.requestId ?? id(),
             idempotencyKey: options.idempotencyKey,
-        }, options.signal);
+        };
+        return this.command(typeof value === "string"
+            ? { ...base, content: value }
+            : { ...base, data: value }, options.signal);
     }
     approve(interactionId, approved, options) {
         return this.command({
@@ -172,14 +228,92 @@ export class SessionClient {
         return SessionItemsResponseSchema.parse(await this.transport.json(`${this.path}/items${search ? `?${search}` : ""}`, "GET", undefined, options.signal));
     }
     async *observe(options = {}) {
-        for await (const frame of observeSSE(this.transport, `${this.path}/events`, options)) {
+        if (!options.follow) {
+            yield* this.observeOne(this.id, options);
+            return;
+        }
+        yield* this.observeFollowing(options);
+    }
+    async *observeOne(sessionId, options) {
+        for await (const frame of observeSSE(this.transport, `/v1/sessions/${segment(sessionId)}/events`, options)) {
             if (frame.event === "heartbeat" || frame.event === "ready")
                 continue;
             yield LiveEventSchema.parse(JSON.parse(frame.data));
         }
     }
+    /**
+     * Own session stream plus linked agent sessions announced in `node.agent`
+     * events, merged by `createdAt` then arrival order (workflows.md §11).
+     */
+    async *observeFollowing(options) {
+        const signal = options.signal;
+        const linked = new Set();
+        const queue = [];
+        let wait;
+        let open = 1;
+        let failed;
+        const wake = () => {
+            wait?.();
+            wait = undefined;
+        };
+        const push = (event) => {
+            queue.push(event);
+            queue.sort((a, b) => {
+                const byTime = a.createdAt.localeCompare(b.createdAt);
+                return byTime !== 0 ? byTime : a.cursor.localeCompare(b.cursor);
+            });
+            wake();
+        };
+        const pump = async (sessionId, cursor) => {
+            try {
+                for await (const event of this.observeOne(sessionId, { cursor, signal })) {
+                    push(event);
+                    const link = linkedSessionId(event);
+                    if (link && link !== this.id && !linked.has(link)) {
+                        linked.add(link);
+                        open += 1;
+                        void pump(link).finally(() => {
+                            open -= 1;
+                            wake();
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                if (!signal?.aborted)
+                    failed = error;
+            }
+        };
+        void pump(this.id, options.cursor).finally(() => {
+            open -= 1;
+            wake();
+        });
+        while (!signal?.aborted) {
+            if (failed)
+                throw failed;
+            if (queue.length) {
+                yield queue.shift();
+                continue;
+            }
+            if (open <= 0)
+                return;
+            await new Promise((resolve) => {
+                wait = resolve;
+            });
+        }
+    }
 }
 export function createClient(destination = {}) {
-    return new AgentsClient(destination);
+    if (destination.url !== undefined ||
+        destination.key !== undefined ||
+        destination.tenant !== undefined) {
+        return new AgentsClient(destination);
+    }
+    return resolveConnection().then((connection) => new AgentsClient({
+        url: connection.url,
+        key: connection.key,
+        tenant: connection.tenant,
+        ...(destination.fetch ? { fetch: destination.fetch } : {}),
+    }));
 }
-export { RuntimeError } from "./http.js";
+export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/connection.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorCode } from "@nylorun/core/compatibility";
+export interface ResolvedConnection {
+    url: string;
+    tenant: string;
+    key: string;
+    role: "application" | "executor";
+    source: "options" | "environment" | "project-link";
+}
+export declare class ConnectionError extends Error {
+    readonly code: ErrorCode;
+    constructor(message: string);
+}
+/** Resolve Tenant API connection: options → environment → project link (D§7.1). */
+export declare function resolveConnection(options?: {
+    url?: string;
+    tenant?: string;
+    key?: string;
+    cwd?: string;
+}): Promise<ResolvedConnection>;