eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/tutorial/remember-definitions.mdx

@@ -0,0 +1,72 @@
+---
+title: "Step 6: Remember definitions"
+description: "Use defineState to remember the team's metric glossary across turns."
+---
+
+Every team has house definitions. “Active” means a purchase in the last 30 days, revenue is net of refunds, a “week” starts Monday. Re-explaining all of that on every turn is a waste. State gives the agent a place to keep it.
+
+`defineState(name, initial)` creates a typed, named slot that survives across step and turn boundaries within a session. You read it with `get()` and change it with `update()`.
+
+## Define the glossary slot
+
+```ts title="agent/lib/glossary.ts"
+import { defineState } from "eve/context";
+
+export interface Glossary {
+  readonly terms: Readonly<Record<string, string>>;
+}
+
+export const glossary = defineState<Glossary>("analytics.glossary", () => ({
+  terms: {},
+}));
+```
+
+## Tools to read and write it
+
+```ts title="agent/tools/define_metric.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { glossary } from "../lib/glossary.js";
+
+export default defineTool({
+  description: "Record the team's definition of a metric so it persists across turns.",
+  inputSchema: z.object({ term: z.string(), meaning: z.string() }),
+  async execute({ term, meaning }) {
+    glossary.update((g) => ({ terms: { ...g.terms, [term]: meaning } }));
+    return glossary.get();
+  },
+});
+```
+
+```ts title="agent/tools/recall_metrics.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { glossary } from "../lib/glossary.js";
+
+export default defineTool({
+  description: "Read the team's recorded metric definitions.",
+  inputSchema: z.object({}),
+  async execute() {
+    return glossary.get();
+  },
+});
+```
+
+## See it persist
+
+```text
+> For us, an active customer is one with a purchase in the last 30 days.
+  Remember that.
+  → calls define_metric("active customer", "purchase in the last 30 days")
+
+> How many active customers do we have?
+  → recalls the definition, writes the matching SQL, answers
+```
+
+The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
+
+State is scoped to a session and isolated per agent, so a subagent starts with fresh state and never sees the parent's. Need to reset something each turn? Call `update(() => fresh)` in a lifecycle hook. More in [State](../advanced/state).
+
+→ Next: [Step 7: Team playbooks](./team-playbooks)
+
+Depth: [State](../advanced/state)

package/dist/docs/public/tutorial/run-analysis.mdx

@@ -0,0 +1,86 @@
+---
+title: "Step 5: Run analysis"
+description: "Seed the warehouse schema into the sandbox workspace, then compute and chart beyond SQL."
+---
+
+SQL tells you the numbers, but a cohort curve, a forecast, or a chart needs real computation. That's what the sandbox is for: an isolated bash environment with a `/workspace` filesystem. Every agent gets exactly one.
+
+There are two pieces. First seed reference files the model can read, then compute against them.
+
+## Seed the schema into the workspace
+
+Mount the warehouse schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout: anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
+
+```text
+agent/sandbox/
+  workspace/
+    schema.sql        ← lands at /workspace/schema.sql
+    notes/grain.md    ← lands at /workspace/notes/grain.md
+```
+
+```sql
+-- agent/sandbox/workspace/schema.sql
+-- Reference only: table shapes the analyst can read before writing queries.
+CREATE TABLE orders     (id INT, customer_id INT, amount_cents INT, created_at DATE);
+CREATE TABLE customers  (id INT, name TEXT, plan TEXT, signed_up_at DATE);
+```
+
+Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. No `agent/sandbox/sandbox.ts` required. A `workspace/` folder keeps the default sandbox and just seeds your files into it.
+
+## Compute and chart in the sandbox
+
+The built-in `bash`, `read_file`, and `write_file` tools already target the sandbox. When you write your own analysis steps, grab a live handle with `ctx.getSandbox()`:
+
+```ts title="agent/tools/chart_series.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Plot a time series to a PNG in the workspace. Pass {date, value} points; " +
+    "returns the chart path.",
+  inputSchema: z.object({
+    title: z.string(),
+    points: z.array(z.object({ date: z.string(), value: z.number() })),
+  }),
+  async execute({ title, points }, ctx) {
+    const sandbox = await ctx.getSandbox();
+    await sandbox.writeTextFile({
+      path: "analysis/series.json",
+      content: JSON.stringify({ title, points }),
+    });
+    await sandbox.writeTextFile({
+      path: "analysis/plot.py",
+      content: [
+        "import json, matplotlib",
+        "matplotlib.use('Agg')",
+        "import matplotlib.pyplot as plt",
+        "d = json.load(open('series.json'))",
+        "plt.plot([p['date'] for p in d['points']], [p['value'] for p in d['points']])",
+        "plt.title(d['title']); plt.savefig('chart.png')",
+      ].join("\n"),
+    });
+    const root = sandbox.resolvePath("analysis");
+    await sandbox.run({ command: `cd ${JSON.stringify(root)} && python plot.py` });
+    return { chart: `${root}/chart.png` };
+  },
+});
+```
+
+Now ask for something past plain SQL:
+
+```text
+Plot weekly revenue for the last 8 weeks.
+```
+
+The model queries the warehouse (Step 4) for the numbers, checks `schema.sql` to get the grain right, then calls `chart_series` to render the PNG in `/workspace`.
+
+## Secrets stay out of the sandbox
+
+The sandbox has no `process.env` and no access to your app's secrets. Your warehouse token lives in the app runtime, and firewall brokering is the only path it takes to the warehouse host. It never enters the sandbox process.
+
+The local backend runs the sandbox on your laptop during `eve dev`; on Vercel it runs on Vercel Sandbox. Lifecycle, backends, and network policy are in [Sandbox](../sandbox).
+
+→ Next: [Step 6: Remember definitions](./remember-definitions)
+
+Depth: [Sandbox](../sandbox)

package/dist/docs/public/tutorial/ship-it.mdx

@@ -0,0 +1,100 @@
+---
+title: "Step 9: Ship it"
+description: "Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
+---
+
+The assistant runs fine in the TUI. Now ship it for real: a web dashboard your team logs into, behind actual auth, deployed on Vercel. Three pieces to wire up: a React UI, the channel's auth, and the deploy itself.
+
+## A dashboard with `useEveAgent`
+
+The dashboard talks to the built-in Eve HTTP channel (`agent/channels/eve.ts`). On the browser side, `useEveAgent` takes care of session creation, streaming, and HITL. In a Next.js app, wrap the config and the routes get wired automatically:
+
+```ts title="next.config.ts"
+import type { NextConfig } from "next";
+import { withEve } from "eve/next";
+
+export default withEve({} satisfies NextConfig);
+```
+
+```tsx title="app/dashboard/chat.tsx"
+"use client";
+
+import { useEveAgent } from "eve/react";
+
+export function AnalyticsChat() {
+  const agent = useEveAgent();
+  const isBusy = agent.status === "submitted" || agent.status === "streaming";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        const message = String(data.get("q") ?? "").trim();
+        if (message) void agent.send({ message });
+      }}
+    >
+      {agent.data.messages.map((message) => (
+        <article key={message.id}>
+          <header>{message.role}</header>
+          {message.parts.map((part, index) =>
+            part.type === "text" ? <p key={index}>{part.text}</p> : null,
+          )}
+        </article>
+      ))}
+      <input name="q" disabled={isBusy} placeholder="Ask about the data…" />
+      <button type="submit" disabled={isBusy}>
+        Ask
+      </button>
+    </form>
+  );
+}
+```
+
+`agent.data.messages` and `agent.status` cover most chat UIs. The hook also surfaces HITL prompts (the spend approval from [Step 8](./guard-the-spend)), so the dashboard can render approve/deny controls. Full API: [Frontend](../frontend/overview).
+
+## Replace `placeholderAuth`
+
+The scaffold's channel ships with `placeholderAuth()`, which fails closed: it rejects production traffic so an unauthenticated app can't go live by accident. Swap it for your app's real auth before you deploy. Order matters here. List your app auth first, ahead of the catch-all helpers, so any entry that doesn't recognize the caller falls through to the next one:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc, type AuthFn } from "eve/channels/auth";
+import { authenticate } from "../lib/auth.js";
+
+const appAuth: AuthFn<Request> = async (request) => {
+  const user = await authenticate(request); // your cookie/session/provider
+  if (!user) return null;
+  return {
+    attributes: { team: user.team }, // the claim Step 7's playbook reads
+    principalType: "user",
+    principalId: user.id,
+    authenticator: "app",
+    issuer: "analytics-dashboard",
+  };
+};
+
+export default eveChannel({
+  auth: [appAuth, localDev(), vercelOidc()],
+});
+```
+
+That `team` attribute is exactly what the dynamic playbook in [Step 7](./team-playbooks) reads from `ctx.session.auth`. Identity is set in this one place and flows out to every capability from there.
+
+## Deploy
+
+```bash
+vercel deploy
+```
+
+On Vercel, the web app stays public and the Eve runtime sits behind it on the same origin, with the sandbox running on Vercel Sandbox. You can smoke-test the deployment without leaving the CLI:
+
+```bash
+eve dev https://your-analytics-app.vercel.app
+```
+
+That's the full assistant, deployed and authed. It queries the warehouse, runs analysis in a sandbox, charts the results, remembers your team's definitions, loads the right playbook per team, and asks before it spends.
+
+Depth: [Frontend](../frontend/overview) · [Auth & route protection](../advanced/auth-and-route-protection) · [Deployment](../advanced/deployment)
+
+Go deeper on this same example in [Advanced](../advanced/dynamic-capabilities): schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows.

package/dist/docs/public/tutorial/team-playbooks.mdx

@@ -0,0 +1,63 @@
+---
+title: "Step 7: Team playbooks"
+description: "Load the caller's team playbook with a dynamic skill keyed on the principal."
+---
+
+The glossary from [Step 6](./remember-definitions) is per-session. But your teams have standing analysis conventions (Growth runs cohort retention a particular way, Finance has its own revenue-recognition rules), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
+
+A skill is an on-demand procedure: the model pulls it in with `load_skill` only when a turn actually needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` resolver reads the session and returns a `defineSkill` (or nothing). Here we key that decision on the caller's identity in `ctx.session.auth`.
+
+## A playbook per principal
+
+`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the claims your auth layer stamped on, team included. Read the team, look up that team's playbook, and emit a skill for it:
+
+```ts title="agent/skills/team-playbook.ts"
+import { defineDynamic, defineSkill } from "eve/skills";
+
+const PLAYBOOKS: Record<string, { title: string; markdown: string }> = {
+  growth: {
+    title: "Growth analysis playbook",
+    markdown:
+      "When analyzing retention, use weekly cohorts anchored on signup week, " +
+      "report curves not point estimates, and exclude trial accounts.",
+  },
+  finance: {
+    title: "Finance analysis playbook",
+    markdown:
+      "Report revenue net of refunds and recognized over the subscription term. " +
+      "Always reconcile against the close-of-month snapshot.",
+  },
+};
+
+export default defineDynamic({
+  events: {
+    "session.started": async (_event, ctx) => {
+      const team = ctx.session.auth.current?.attributes.team;
+      const key = Array.isArray(team) ? team[0] : team;
+      const playbook = key ? PLAYBOOKS[key] : undefined;
+      if (!playbook) return null;
+
+      return defineSkill({
+        description:
+          `Use when answering analysis questions for the ${key} team. ` +
+          `Contains that team's standing conventions.`,
+        markdown: `# ${playbook.title}\n\n${playbook.markdown}`,
+      });
+    },
+  },
+});
+```
+
+`session.started` fires once per session. The resolver reads the team a single time, and the resulting skill stays available for every turn that follows. Returning `null` produces no skill at all, so a caller with no team simply gets no playbook.
+
+## See it route
+
+A Growth user asks "what's our 8-week retention?" The model sees the playbook fits, calls `load_skill`, and applies the Growth conventions to that turn: weekly cohorts, no trial accounts. Ask the same question as a Finance user and you'll never see the Growth playbook. You get Finance's.
+
+The team comes from authenticated claims, not from the message, so one tenant can't borrow another's playbook by asking nicely. (Those `attributes` are set by the auth layer in [Step 9](./ship-it).)
+
+The same `defineDynamic` resolver drives dynamic tools and instructions too. For the full mechanism, see [Dynamic capabilities](../advanced/dynamic-capabilities).
+
+→ Next: [Step 8: Guard the spend](./guard-the-spend)
+
+Depth: [Skills](../skills) · [Dynamic capabilities](../advanced/dynamic-capabilities)

package/dist/src/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+import"node:module";var __create=Object.create,__defProp=Object.defineProperty,__getOwnPropDesc=Object.getOwnPropertyDescriptor,__getOwnPropNames=Object.getOwnPropertyNames,__getProtoOf=Object.getPrototypeOf,__hasOwnProp=Object.prototype.hasOwnProperty,__commonJSMin=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports),__exportAll=(e,n)=>{let r={};for(var i in e)__defProp(r,i,{get:e[i],enumerable:!0});return n||__defProp(r,Symbol.toStringTag,{value:`Module`}),r},__copyProps=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=__getOwnPropNames(i),l=0,u=c.length,d;l<u;l++)d=c[l],!__hasOwnProp.call(e,d)&&d!==o&&__defProp(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=__getOwnPropDesc(i,d))||s.enumerable});return e},__toESM=(n,r,a)=>(a=n==null?{}:__create(__getProtoOf(n)),__copyProps(r||!n||!n.__esModule?__defProp(a,`default`,{value:n,enumerable:!0}):a,n));import.meta.url;export{__commonJSMin,__exportAll,__toESM};

package/dist/src/channel/adapter-context.d.ts

@@ -0,0 +1,11 @@
+import type { ContextAccessor } from "#context/key.js";
+import type { ChannelAdapter, ChannelAdapterContext } from "#channel/adapter.js";
+/**
+ * Builds the {@link ChannelAdapterContext} the runtime hands to an
+ * adapter's `deliver` hook, event handlers, and attachment resolver.
+ *
+ * Populates `session` with a live {@link SessionHandle} backed by the
+ * supplied accessor so handlers can read identity / auth and call
+ * `setContinuationToken(...)` to re-key the parked session.
+ */
+export declare function buildAdapterContext<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext>(adapter: ChannelAdapter<TCtx>, accessor: ContextAccessor): TCtx;

package/dist/src/channel/adapter-context.js

@@ -0,0 +1 @@
+import{buildSessionHandle}from"#channel/session.js";function buildAdapterContext(e,t){let n={ctx:t,state:e.state??{},session:buildSessionHandle(t)};return e.createAdapterContext?e.createAdapterContext(n):n}export{buildAdapterContext};

package/dist/src/channel/adapter.d.ts

@@ -0,0 +1,160 @@
+import type { ContextAccessor } from "#context/key.js";
+import type { StepInput } from "#harness/types.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { SessionHandle } from "#channel/session.js";
+import type { DeliverPayload } from "#channel/types.js";
+/**
+ * Context available to every adapter handler (`deliver` and event handlers).
+ *
+ * `state` is a mutable reference to the adapter's durable state. The runtime
+ * auto-snapshots it at step boundaries — no manual `serialize()` needed.
+ *
+ * `ctx` provides read/write access to durable context keys (the same
+ * {@link ContextAccessor} that tools and providers use).
+ *
+ * `session` is a live handle to the current session — id, auth,
+ * continuation token, plus an imperative {@link SessionHandle.setContinuationToken}
+ * for channels that need to re-key the session mid-turn (e.g. Slack's
+ * auto-anchor on first post).
+ */
+export interface ChannelAdapterContext<TState = Record<string, unknown>> {
+    /**
+     * Mutable adapter state. Auto-serialized at step boundaries via
+     * JSON snapshot. The adapter reads and writes this directly.
+     */
+    state: TState;
+    /**
+     * Read/write access to durable context keys. Seed keys here for tools
+     * to read during the turn.
+     */
+    readonly ctx: ContextAccessor;
+    /**
+     * Live handle to the current session.
+     */
+    readonly session: SessionHandle;
+}
+/**
+ * Extracts the state type from a {@link ChannelAdapterContext} generic.
+ * Used internally so adapter-level types can declare their state shape
+ * once (via `TCtx`) and have helpers narrow consistently.
+ */
+type StateOf<TCtx> = TCtx extends ChannelAdapterContext<infer S> ? S : Record<string, unknown>;
+/**
+ * Extracts the `data` field type from a stream event by its `type` discriminant.
+ * Events that carry no `data` field (e.g. `session.completed`) resolve to `undefined`.
+ */
+type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
+    type: T;
+}> extends {
+    data: infer D;
+} ? D : undefined;
+/**
+ * A single outbound event handler. Receives the event's `data` (not the full
+ * envelope) and the adapter context. Void return — side effects only.
+ */
+type EventHandler<T extends HandleMessageStreamEvent["type"], TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> = (data: EventData<T>, ctx: TCtx) => void | Promise<void>;
+/**
+ * Map of outbound event handlers keyed by event type. The adapter declares
+ * handlers for the event types it cares about. For undeclared types, the
+ * framework's default handlers run.
+ */
+export type ChannelEventHandlers<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> = {
+    [K in HandleMessageStreamEvent["type"]]?: EventHandler<K, TCtx>;
+};
+/**
+ * Enriched return shape from a channel's {@link ChannelAdapter.fetchFile}
+ * function. Return a bare {@link Buffer} when only bytes are known, or
+ * this record when the fetch discovers a more accurate `mediaType` or
+ * `filename` (e.g. from an HTTP `Content-Type` header).
+ *
+ * When fields are provided, staging prefers them over the values the
+ * channel populated at ingestion time.
+ */
+export interface FetchFileResult {
+    readonly bytes: Buffer;
+    readonly mediaType?: string;
+    readonly filename?: string;
+}
+export type ChannelInstrumentationMetadata = Readonly<Record<string, unknown>>;
+export type ChannelInstrumentationMetadataProjector = (state: Record<string, unknown> | undefined) => ChannelInstrumentationMetadata;
+/**
+ * Plain-object channel adapter with durable state, an optional inbound
+ * delivery hook, event handlers, and optional attachment resolution.
+ */
+export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> = {
+    /**
+     * Stable durable identifier for serialization across step boundaries.
+     * Must be unique across all adapters visible to one runtime bundle.
+     *
+     * Defaults to {@link HTTP_ADAPTER_KIND} (`"http"`) for the canonical
+     * session channel and every behaviorless authored channel, or is derived
+     * from the route file path as `channel:<name>` once
+     * `runtime/resolve-channel.ts` rewrites authored adapters that carry
+     * behavior.
+     */
+    readonly kind: string;
+    /**
+     * Initial state shape. Auto-serialized at step boundaries via JSON
+     * snapshot. On rehydration, the runtime restores the serialized state
+     * and re-attaches the adapter's behavior functions from the registry.
+     */
+    readonly state?: Record<string, unknown>;
+    /**
+     * Inbound hook: fires once per delivery before the harness starts.
+     *
+     * Return a {@link StepInput} to override the input the harness sees, or
+     * return void to use the default payload projection.
+     */
+    deliver?(payload: DeliverPayload, ctx: TCtx): StepInput | void | Promise<StepInput | void>;
+    /**
+     * Optional factory that builds the adapter context for this adapter.
+     *
+     * @internal
+     */
+    createAdapterContext?(base: ChannelAdapterContext<StateOf<TCtx>>): TCtx;
+    /**
+     * Fetches bytes for a URL encountered in `FilePart.data`.
+     *
+     * Called by the staging pipeline when it encounters a `URL` object
+     * on a `FilePart`. Return `null` to let the URL pass through to the
+     * model provider (e.g. public images). Return bytes or
+     * {@link FetchFileResult} to stage the file to the sandbox.
+     *
+     * Credentials should be captured in the closure at channel
+     * construction time.
+     */
+    readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
+    /**
+     * Framework-owned observability projection for the active channel.
+     *
+     * Channel implementations decide which state fields are safe and
+     * meaningful to expose to instrumentation callbacks. The harness reads
+     * the resulting projection through a seed context key rather than
+     * inspecting adapter state directly.
+     */
+    readonly instrumentation?: {
+        readonly metadata?: ChannelInstrumentationMetadataProjector;
+    };
+} & ChannelEventHandlers<TCtx>;
+/**
+ * Produces the default {@link StepInput} when no custom adapter `deliver`
+ * hook is defined.
+ *
+ * Passes through both `message` and `inputResponses` from the delivery
+ * payload so tool-approval responses (and other HITL replies) reach the
+ * harness even when the channel has no bespoke deliver logic.
+ */
+export declare function defaultDeliverResult(payload: DeliverPayload): StepInput | undefined;
+/**
+ * Returns the durable kind for an adapter.
+ */
+export declare function getAdapterKind(adapter: ChannelAdapter): string;
+/**
+ * Calls an adapter's event handler for a given event. Returns the event
+ * unchanged (adapters don't transform events — they perform side effects).
+ *
+ * Throwing handlers are logged and swallowed so a downstream delivery
+ * failure does not corrupt the event stream write path.
+ */
+export declare function callAdapterEventHandler(adapter: ChannelAdapter, event: HandleMessageStreamEvent, ctx: ChannelAdapterContext): Promise<HandleMessageStreamEvent>;
+export {};

package/dist/src/channel/adapter.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";const log=createLogger(`channel.adapter`);function defaultDeliverResult(e){if(e.message!==void 0)return{inputResponses:e.inputResponses,message:e.message,context:e.context,outputSchema:e.outputSchema};if(e.inputResponses!==void 0&&e.inputResponses.length>0)return{inputResponses:e.inputResponses,context:e.context,outputSchema:e.outputSchema};if(e.context!==void 0&&e.context.length>0)return{context:e.context,outputSchema:e.outputSchema};if(e.outputSchema!==void 0)return{outputSchema:e.outputSchema}}function getAdapterKind(e){return e.kind}async function callAdapterEventHandler(e,t,n){let r=e[t.type];if(r===void 0)return t;try{await r(`data`in t?t.data:void 0,n)}catch(n){log.error(`adapter event handler threw — event swallowed`,{adapterKind:getAdapterKind(e),eventType:t.type,error:n})}return t}export{callAdapterEventHandler,defaultDeliverResult,getAdapterKind};

package/dist/src/channel/compiled-channel.d.ts

@@ -0,0 +1,21 @@
+import type { ChannelAdapter } from "#channel/adapter.js";
+import type { RouteDefinition, SendFn } from "#channel/routes.js";
+import type { Session } from "#channel/session.js";
+import type { SessionAuthContext } from "#channel/types.js";
+export declare const CHANNEL_SENTINEL: "eve:channel";
+export interface CompiledChannel<TState = undefined, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+    readonly __kind: typeof CHANNEL_SENTINEL;
+    readonly routes: readonly RouteDefinition<TState>[];
+    readonly adapter: ChannelAdapter<any>;
+    readonly __metadata?: TMetadata;
+    readonly receive?: (input: {
+        readonly message: string;
+        readonly target: Readonly<TReceiveTarget>;
+        readonly auth: SessionAuthContext | null;
+    }, args: {
+        send: SendFn<TState>;
+    }) => Promise<Session>;
+}
+export declare function isCompiledChannel(value: unknown): value is CompiledChannel;
+export declare function getChannelInstrumentationKind(value: unknown): string | undefined;
+export declare function setChannelInstrumentationKind(channel: CompiledChannel, kind: string): void;

package/dist/src/channel/compiled-channel.js

@@ -0,0 +1 @@
+const CHANNEL_SENTINEL=`eve:channel`,CHANNEL_INSTRUMENTATION_KIND=Symbol.for(`eve.channel.instrumentationKind`);function isCompiledChannel(e){return typeof e==`object`&&!!e&&e.__kind===`eve:channel`}function getChannelInstrumentationKind(e){if(!isCompiledChannel(e))return;let t=Reflect.get(e,CHANNEL_INSTRUMENTATION_KIND);if(typeof t==`string`&&t.length>0)return t;let n=e.adapter.kind;return typeof n==`string`&&n.startsWith(`channel:`)?n:void 0}function setChannelInstrumentationKind(e,t){Object.defineProperty(e,CHANNEL_INSTRUMENTATION_KIND,{configurable:!0,enumerable:!1,value:t})}export{CHANNEL_SENTINEL,getChannelInstrumentationKind,isCompiledChannel,setChannelInstrumentationKind};

package/dist/src/channel/cross-channel-receive.d.ts

@@ -0,0 +1,70 @@
+import type { UserContent } from "ai";
+import type { ChannelAdapter } from "#channel/adapter.js";
+import { type CompiledChannel } from "#channel/compiled-channel.js";
+import type { InferReceiveTarget } from "#channel/receive-target.js";
+import type { Session } from "#channel/session.js";
+import type { Runtime, SessionAuthContext } from "#channel/types.js";
+import type { ResolvedChannelDefinition } from "#runtime/types.js";
+/**
+ * Options accepted by {@link CrossChannelReceiveFn}. Mirrors the input
+ * argument of a channel's authored `receive(input, { send })` hook —
+ * the runtime constructs `send` internally so route-handler callers
+ * only supply the platform target, payload, and auth.
+ */
+export interface CrossChannelReceiveOptions<TTarget = Record<string, unknown>> {
+    readonly message: string | UserContent;
+    readonly target: TTarget;
+    readonly auth: SessionAuthContext | null;
+}
+/**
+ * Starts a session on a different channel from inside a route handler.
+ * The target channel's authored `receive` hook owns continuation-token
+ * format and initial state; `auth` is forwarded verbatim and becomes
+ * `session.initiatorAuth`.
+ */
+export type CrossChannelReceiveFn = <TChannel>(channel: TChannel, options: CrossChannelReceiveOptions<InferReceiveTarget<TChannel>>) => Promise<Session>;
+/**
+ * Channel record consumed by the receiver — keeps the public-facing
+ * `definition` reference so callers can identify a target by value
+ * (the same module-default they imported in their route file).
+ */
+export interface CrossChannelTarget {
+    readonly name: string;
+    readonly definition: CompiledChannel;
+    readonly receive?: CompiledChannel["receive"];
+    readonly adapter?: ChannelAdapter;
+}
+/**
+ * Projects an agent's resolved channels into the receiver-input shape.
+ *
+ * Framework-internal fetch-only channels carry no `definition` reference
+ * and are filtered out at this boundary — only authored channels backed
+ * by a `defineChannel` value can be receive targets.
+ */
+export declare function toCrossChannelTargets(channels: readonly ResolvedChannelDefinition[]): readonly CrossChannelTarget[];
+/**
+ * Builds the `args.receive` closure used by every route handler. The
+ * closure resolves the target channel by reference identity against
+ * the request-scoped channel bundle, then delegates to the target's
+ * authored `receive` hook with a per-target `send` factory.
+ */
+export declare function createCrossChannelReceiveFn(runtime: Runtime, channels: readonly CrossChannelTarget[]): CrossChannelReceiveFn;
+interface InvokeChannelReceiveInput {
+    readonly runtime: Runtime;
+    readonly target: Pick<CrossChannelTarget, "name" | "receive" | "adapter">;
+    readonly input: {
+        readonly message: string;
+        readonly target: Readonly<Record<string, unknown>>;
+        readonly auth: SessionAuthContext | null;
+    };
+    readonly describeMissingReceive: () => string;
+    readonly describeMissingAdapter: () => string;
+}
+/**
+ * Shared `receive(input, { send })` invocation used by both the route-
+ * handler cross-channel surface and the schedule dispatcher. Owns the
+ * receive/adapter precondition checks and the per-target `send`
+ * factory so both call sites stay byte-identical.
+ */
+export declare function invokeChannelReceive(args: InvokeChannelReceiveInput): Promise<Session>;
+export {};

package/dist/src/channel/cross-channel-receive.js

@@ -0,0 +1,2 @@
+import{isCompiledChannel}from"#channel/compiled-channel.js";import{createSendFn}from"#channel/send.js";function toCrossChannelTargets(e){return e.flatMap(e=>e.definition===void 0?[]:[{name:e.name,definition:e.definition,receive:e.receive,adapter:e.adapter}])}function createCrossChannelReceiveFn(e,t){return async(n,r)=>{let i=resolveTargetByReference(n,t);return await invokeChannelReceive({runtime:e,target:i,input:{message:r.message,target:r.target,auth:r.auth},describeMissingReceive:()=>`args.receive(): channel "${i.name}" does not implement receive(). Declare a receive hook on the channel to accept cross-channel sessions.`,describeMissingAdapter:()=>`args.receive(): channel "${i.name}" has no adapter — cannot build send().`})}}async function invokeChannelReceive(e){if(!e.target.receive)throw Error(e.describeMissingReceive());if(!e.target.adapter)throw Error(e.describeMissingAdapter());let n=createSendFn(e.runtime,e.target.adapter,e.target.name);return await e.target.receive(e.input,{send:n})}function resolveTargetByReference(e,t){for(let n of t)if(n.definition===e)return n;let n=resolveTargetByRouteFingerprint(e,t);if(n!==null)return n;throw Error(`args.receive(): the channel passed as the first argument is not registered in this agent's channels/. Import the channel module's default export from agent/channels/<name>.ts and pass that value.`)}function resolveTargetByRouteFingerprint(t,n){if(!isCompiledChannel(t))return null;let r=createRouteFingerprint(t);if(r===null)return null;let i=new Map;for(let e of n)createRouteFingerprint(e.definition)===r&&i.set(e.name,e);if(i.size===1)return[...i.values()][0];if(i.size>1)throw Error(`args.receive(): the channel passed as the first argument matches multiple registered channels by route shape. Import a channel with a unique route set from agent/channels/<name>.ts before passing it to args.receive().`);return null}function createRouteFingerprint(e){return e.routes.length===0?null:e.routes.map(e=>`${e.method.toUpperCase()} ${e.path}`).sort().join(`
+`)}export{createCrossChannelReceiveFn,invokeChannelReceive,toCrossChannelTargets};

package/dist/src/channel/http.d.ts

@@ -0,0 +1,29 @@
+import type { ChannelAdapter } from "#channel/adapter.js";
+/**
+ * Durable adapter kind for the canonical session channel and for every
+ * behaviorless user-authored channel returned by the `defineChannel`
+ * fast-path (no state, no `context()`, no event handlers, no `fetchFile`).
+ *
+ * The value is locked at `"http"` because it is persisted into durable
+ * workflow state under `serializedContext["eve.channel"].kind` and into
+ * sandbox telemetry tags as `channel: "http"`. Renaming the value would
+ * break rehydration for every in-flight session started under any prior
+ * build with "Unknown adapter kind: \"http\"". The `httpChannel` →
+ * `eveChannel` rename (commit `bd3d1b43`) intentionally renamed the
+ * channel identifier (file name, function name, framework constant) but
+ * deliberately left this adapter kind alone — the kind labels the
+ * adapter's transport class, not the channel's name, and the same slot
+ * is the rehydration target for every behaviorless authored channel
+ * regardless of which protocol it speaks.
+ */
+export declare const HTTP_ADAPTER_KIND = "http";
+/**
+ * Framework adapter installed for the canonical session channel and
+ * for every behaviorless user-authored channel.
+ *
+ * Carries no behavior — it is a bare discriminator that the runtime
+ * adapter registry uses to rehydrate `{ kind: "http" }` at every
+ * workflow step boundary. Registered in `FRAMEWORK_ADAPTERS`
+ * (`runtime/channels/registry.ts`).
+ */
+export declare const HTTP_ADAPTER: ChannelAdapter;

package/dist/src/channel/http.js

@@ -0,0 +1 @@
+const HTTP_ADAPTER_KIND=`http`,HTTP_ADAPTER={kind:HTTP_ADAPTER_KIND};export{HTTP_ADAPTER,HTTP_ADAPTER_KIND};

package/dist/src/channel/instrumentation.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelAdapter, ChannelInstrumentationMetadata } from "#channel/adapter.js";
+export interface ChannelInstrumentationProjection {
+    readonly kind: string;
+    readonly metadata: ChannelInstrumentationMetadata;
+}
+export declare function buildChannelInstrumentationProjection(input: {
+    readonly adapter: ChannelAdapter;
+    readonly channelName?: string;
+    readonly existingKind?: string;
+}): ChannelInstrumentationProjection;

package/dist/src/channel/instrumentation.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{getAdapterKind}from"#channel/adapter.js";import{isInstrumentationChannelKind,resolveInstrumentationProjection}from"#internal/instrumentation.js";const log=createLogger(`channel.instrumentation`);function buildChannelInstrumentationProjection(e){let{adapter:t,channelName:n,existingKind:r}=e;return{kind:resolveKind({adapter:t,channelName:n,existingKind:r}),metadata:resolveMetadata(t)}}function resolveKind(e){let{adapter:r,channelName:i,existingKind:a}=e;if(a!==void 0)return a;if(i!==void 0&&i.length>0)return`channel:${i}`;let o=getAdapterKind(r);return isInstrumentationChannelKind(o)?o:`channel:${o}`}function resolveMetadata(e){let n=e.instrumentation?.metadata;return n===void 0?{}:resolveInstrumentationProjection({invoke:()=>n(e.state),log,source:getAdapterKind(e)})??{}}export{buildChannelInstrumentationProjection};