eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/client/messages.mdx

@@ -0,0 +1,152 @@
+---
+title: "Messages"
+description: "Send text, full turn payloads, client context, attachments, and HITL responses with eve/client."
+---
+
+`ClientSession` sends one turn at a time. A fresh session starts on the first send; later sends continue the same conversation as long as the previous turn left the session waiting.
+
+## Send text
+
+Pass a string to `send()` for plain text:
+
+```ts
+import { Client } from "eve/client";
+
+const client = new Client({ host: "http://127.0.0.1:3000" });
+const session = client.session();
+
+const response = await session.send("What is the weather in Brooklyn?");
+
+// Metadata is available as soon as the POST succeeds.
+console.log(response.sessionId, response.continuationToken);
+
+const result = await response.result();
+console.log(result.status, result.message);
+```
+
+`response.result()` consumes the event stream and returns a `MessageResult`:
+
+| Field       | Meaning                                                                        |
+| ----------- | ------------------------------------------------------------------------------ |
+| `message`   | Final assistant text for the turn, when one completed.                         |
+| `status`    | `"waiting"`, `"completed"`, or `"failed"`.                                     |
+| `events`    | All stream events observed during the turn.                                    |
+| `sessionId` | Session ID for streaming and inspection.                                       |
+| `data`      | Structured output when the turn requested an [output schema](./output-schema). |
+
+Failed runtime turns don't throw just because the stream includes `session.failed`. They return `status: "failed"`. Transport and route errors throw `ClientError`.
+
+## Send a full turn payload
+
+Use `send()` when you need more than plain text:
+
+```ts
+const response = await session.send({
+  message: "What should I do on this screen?",
+  clientContext: {
+    route: "/billing",
+    plan: "pro",
+    seatsUsed: 4,
+  },
+});
+
+await response.result();
+```
+
+`clientContext` is one-turn context for the next model call. Strings become user-role context messages, arrays of strings become multiple context messages, and objects are JSON-serialized into one context message. It isn't persisted to durable session history and doesn't dispatch a turn by itself.
+
+## Send attachments
+
+`send()` accepts AI SDK `UserContent`, so a message can mix text and file parts:
+
+```ts
+const response = await session.send({
+  message: [
+    { type: "text", text: "Summarize this report." },
+    {
+      type: "file",
+      data: reportDataUrl,
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ],
+});
+
+await response.result();
+```
+
+For local files, read the file and send a base64 `data:` URL:
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const bytes = await readFile("report.pdf");
+const reportDataUrl = `data:application/pdf;base64,${bytes.toString("base64")}`;
+
+const response = await session.send({
+  message: [
+    { type: "text", text: "Summarize this report." },
+    {
+      type: "file",
+      data: reportDataUrl,
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ],
+});
+
+await response.result();
+```
+
+## Answer human input requests
+
+Tools can pause for approval or ask the user a question. The stream emits `input.requested` with one or more requests. Reply through the same session with `inputResponses`:
+
+```ts
+import type { InputRequest } from "eve/client";
+
+let pendingRequests: readonly InputRequest[] = [];
+
+const response = await session.send("Run the deployment checks.");
+
+for await (const event of response) {
+  if (event.type === "input.requested") {
+    pendingRequests = event.data.requests;
+  }
+}
+
+const resumed = await session.send({
+  inputResponses: pendingRequests.map((request) => ({
+    requestId: request.requestId,
+    optionId: "approve",
+  })),
+});
+
+await resumed.result();
+```
+
+You can send `message`, `inputResponses`, and `clientContext` together when the resumed turn needs both a human answer and follow-up text.
+
+## Single-use responses
+
+`MessageResponse` is single-use. Either aggregate it:
+
+```ts
+const result = await response.result();
+```
+
+Or stream it:
+
+```ts
+for await (const event of response) {
+  console.log(event.type);
+}
+```
+
+Don't do both on the same response. Once the stream is consumed, the `ClientSession` advances its cursor for the next turn.
+
+## What to read next
+
+- [Continuations](./continuations): how the session cursor advances
+- [Streaming](./streaming): handle events live instead of using `result()`
+- [Tools](../tools): configure approvals and question prompts

package/dist/docs/public/client/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "TypeScript Client",
+  "pages": ["overview", "messages", "continuations", "streaming", "output-schema"]
+}

package/dist/docs/public/client/output-schema.mdx

@@ -0,0 +1,135 @@
+---
+title: "Output Schema"
+description: "Request structured results from Eve client turns and read typed data from MessageResult."
+---
+
+Pass `outputSchema` on a client turn when the caller needs structured data instead of only assistant text. The runtime makes the model satisfy the schema before the turn settles and emits the final payload as `result.completed`.
+
+## JSON Schema
+
+Raw JSON Schema objects work directly:
+
+```ts
+import { Client } from "eve/client";
+
+interface Summary {
+  title: string;
+  count: number;
+}
+
+const outputSchema = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    count: { type: "integer" },
+  },
+  required: ["title", "count"],
+} as const;
+
+const client = new Client({ host: "http://127.0.0.1:3000" });
+const session = client.session();
+
+const response = await session.send<Summary>({
+  message: "Summarize this turn.",
+  outputSchema,
+});
+
+const result = await response.result();
+
+console.log(result.data?.title);
+console.log(result.data?.count);
+```
+
+`result.data` is `undefined` when the turn did not produce a structured result.
+
+## Standard Schema
+
+The client also accepts Standard Schema implementations such as Zod, Valibot, and ArkType. The schema is lowered to JSON Schema before the request is sent:
+
+```ts
+import { z } from "zod";
+
+const summarySchema = z.object({
+  title: z.string(),
+  count: z.number().int(),
+});
+
+type Summary = z.infer<typeof summarySchema>;
+
+const response = await session.send<Summary>({
+  message: "Summarize this turn.",
+  outputSchema: summarySchema,
+});
+
+const { data } = await response.result();
+```
+
+The server is authoritative for validation. The client types `MessageResult.data` from your generic and schema, but it doesn't revalidate the streamed payload client-side.
+
+## Stream the result event
+
+If you consume events manually, read `result.completed`:
+
+```ts
+const response = await session.send<Summary>({
+  message: "Summarize this turn.",
+  outputSchema,
+});
+
+for await (const event of response) {
+  if (event.type === "result.completed") {
+    const summary = event.data.result as Summary;
+    console.log(summary.title);
+  }
+}
+```
+
+If more than one `result.completed` appears in the consumed event list, `result()` returns the most recent one as `data`.
+
+## Send payloads with output schema
+
+`outputSchema` works with string shorthand and object-form sends. Use object form when you need schema, headers, signal, context, attachments, or HITL responses:
+
+```ts
+const response = await session.send<Summary>({
+  message: "Summarize this PDF.",
+  clientContext: { reportId: "rpt_123" },
+  outputSchema,
+});
+
+const result = await response.result();
+```
+
+It also works on follow-up turns and HITL response turns:
+
+```ts
+const response = await session.send({
+  inputResponses: [{ requestId, optionId: "approve" }],
+  message: "Return the approved action as structured output.",
+  outputSchema,
+});
+
+const result = await response.result();
+```
+
+## Per-turn scope
+
+Client `outputSchema` is scoped to the turn that sends it. It doesn't become a permanent setting for the conversation:
+
+```ts
+const response = await session.send({ message: "Return a structured summary.", outputSchema });
+await response.result();
+
+const followUpResponse = await session.send("Now answer normally.");
+const followUp = await followUpResponse.result();
+
+console.log(followUp.data); // undefined unless this turn also requested a schema
+```
+
+For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../agent-config#outputschema) and [Subagents](../subagents).
+
+## What to read next
+
+- [Messages](./messages): send turns with `send()`
+- [Streaming](./streaming): handle `result.completed` live
+- [`agent.ts`](../agent-config#outputschema): configured task-mode output

package/dist/docs/public/client/overview.mdx

@@ -0,0 +1,116 @@
+---
+title: "TypeScript Client"
+description: "Call an Eve agent from TypeScript with Client, sessions, auth, and health checks."
+---
+
+The `eve/client` entrypoint is the typed client for Eve's default HTTP API. Use it from scripts, server-to-server integrations, tests, evals, backend jobs, or custom UIs that want the session protocol without hand-writing the POST and NDJSON stream loop.
+
+For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming). The client sits between those two: lower level than the frontend hooks, higher level than raw HTTP.
+
+## Create a client
+
+A `Client` binds one host, auth policy, header policy, and stream reconnection budget:
+
+```ts
+import { Client } from "eve/client";
+
+const client = new Client({
+  host: "http://127.0.0.1:3000",
+});
+```
+
+`host` is the origin where the Eve routes are mounted. In a same-origin browser integration this is often `""`, but scripts and backend services usually name the full URL.
+
+## Check health
+
+Use `health()` when a script needs to fail early before creating a session:
+
+```ts
+const health = await client.health();
+console.log(health.status, health.workflowId);
+```
+
+Non-2xx responses throw `ClientError`, which carries the HTTP `status` and response `body`.
+
+## Authentication
+
+Pass `auth` when the [Eve channel](../channels/eve) route requires credentials:
+
+```ts
+const client = new Client({
+  host: "https://agent.example.com",
+  auth: {
+    bearer: async () => await getAccessToken(),
+  },
+});
+```
+
+Bearer values and Basic auth passwords can be strings or functions. Functions run before every HTTP call, including stream reconnects:
+
+```ts
+const client = new Client({
+  host: "https://agent.example.com",
+  auth: {
+    basic: {
+      username: "agent-client",
+      password: async () => await getRotatingSecret(),
+    },
+  },
+});
+```
+
+Use `headers` for route-specific credentials such as bypass tokens or tenant hints. Like `auth`, it can be static or dynamic:
+
+```ts
+const client = new Client({
+  host: "https://agent.example.com",
+  headers: async () => ({
+    "x-vercel-protection-bypass": await getBypassToken(),
+  }),
+});
+```
+
+Per-request headers can be attached to an individual turn:
+
+```ts
+const response = await session.send({
+  message: "Run the check.",
+  headers: { "x-request-id": requestId },
+});
+
+await response.result();
+```
+
+## Sessions
+
+Create a `ClientSession` for each conversation:
+
+```ts
+const session = client.session();
+```
+
+A client can own many sessions at once. Each session tracks its own `sessionId`, `continuationToken`, and stream cursor:
+
+```ts
+const alice = client.session();
+const bob = client.session();
+
+const aliceResponse = await alice.send("Summarize account A.");
+await aliceResponse.result();
+
+const bobResponse = await bob.send("Summarize account B.");
+await bobResponse.result();
+```
+
+The next pages cover the session lifecycle:
+
+- [Messages](./messages): send turns and collect results
+- [Continuations](./continuations): persist and resume sessions
+- [Streaming](./streaming): render events as they arrive
+- [Output schema](./output-schema): request structured results
+
+## What to read next
+
+- [Eve channel](../channels/eve): the HTTP API this client calls
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming): the raw HTTP contract
+- [Frontend](../frontend/overview): browser UI with `useEveAgent`

package/dist/docs/public/client/streaming.mdx

@@ -0,0 +1,143 @@
+---
+title: "Streaming"
+description: "Consume Eve client stream events live, reconnect by event index, and aggregate turn results."
+---
+
+Every send starts with a POST and then reads the session's NDJSON event stream. `MessageResponse` gives you two ways to consume that stream: aggregate it with `result()` or iterate it live.
+
+## Aggregate a turn
+
+Use `result()` when you only need the final turn summary:
+
+```ts
+const response = await session.send("Summarize the latest forecast.");
+const result = await response.result();
+
+console.log(result.status);
+console.log(result.message);
+console.log(result.events.length);
+```
+
+This consumes the stream until the current turn boundary:
+
+- `session.waiting`
+- `session.completed`
+- `session.failed`
+
+## Stream events live
+
+Use `for await...of` when you want to render progress:
+
+```ts
+const response = await session.send("Draft a plan and show your work.");
+
+for await (const event of response) {
+  if (event.type === "message.appended") {
+    process.stdout.write(event.data.messageDelta);
+  }
+
+  if (event.type === "message.completed" && event.data.finishReason !== "tool-calls") {
+    console.log("\nfinal:", event.data.message);
+  }
+}
+```
+
+`message.appended` and `reasoning.appended` are incremental events. The completed forms, `message.completed` and `reasoning.completed`, are the compatibility path for clients that don't render deltas.
+
+## Handle event types
+
+Import event types from `eve/client` when you want exhaustiveness or helpers:
+
+```ts
+import type { HandleMessageStreamEvent } from "eve/client";
+import { isCurrentTurnBoundaryEvent } from "eve/client";
+
+function handleEvent(event: HandleMessageStreamEvent) {
+  if (isCurrentTurnBoundaryEvent(event)) {
+    console.log("turn settled:", event.type);
+  }
+}
+```
+
+The most common UI events are:
+
+| Event                | Use                                                              |
+| -------------------- | ---------------------------------------------------------------- |
+| `message.received`   | Confirm the user message landed.                                 |
+| `reasoning.appended` | Render reasoning deltas when the model provides them.            |
+| `message.appended`   | Render assistant text deltas.                                    |
+| `actions.requested`  | Show tool calls requested by the model.                          |
+| `action.result`      | Show tool call results.                                          |
+| `input.requested`    | Pause the UI for approval or a question answer.                  |
+| `result.completed`   | Read structured output from an [output schema](./output-schema). |
+| `session.waiting`    | Enable the composer for the next turn.                           |
+| `session.completed`  | Mark the conversation terminal.                                  |
+| `session.failed`     | Mark the conversation failed.                                    |
+
+For the complete event table, see [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming).
+
+## Reconnection
+
+The client reconnects after transient stream disconnects. It resumes from the number of events already consumed in the current session:
+
+```ts
+const client = new Client({
+  host: "https://agent.example.com",
+  maxReconnectAttempts: 5,
+});
+```
+
+`maxReconnectAttempts` is per turn. The default is `3`.
+
+## Open a stream manually
+
+Use `session.stream()` when you already have a session cursor and only need to attach to the existing stream:
+
+```ts
+const session = client.session({
+  continuationToken: "eve:6c8b1f2e-3d4a-4b9c-8e21-9f0a1b2c3d4e",
+  sessionId: "wrun_01ARYZ6S41TSV4RRFFQ69G5FAV",
+  streamIndex: 10,
+});
+
+for await (const event of session.stream()) {
+  console.log(event.type);
+}
+```
+
+Pass `startIndex` to override the stored cursor:
+
+```ts
+for await (const event of session.stream({ startIndex: 0 })) {
+  console.log(event.type);
+}
+```
+
+`stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
+
+## Abort a request
+
+Pass an `AbortSignal` to cancel the POST or stream:
+
+```ts
+const controller = new AbortController();
+
+const response = await session.send({
+  message: "Run a long analysis.",
+  signal: controller.signal,
+});
+
+setTimeout(() => controller.abort(), 10_000);
+
+for await (const event of response) {
+  console.log(event.type);
+}
+```
+
+Once a response is aborted, create a new send for the next turn. Don't reuse the same `MessageResponse`.
+
+## What to read next
+
+- [Messages](./messages): the send APIs that create streams
+- [Continuations](./continuations): how stream cursors are persisted
+- [Output schema](./output-schema): consume `result.completed`