eve 0.5.4 → 0.6.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# eve

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2013 Adobe Systems Incorporated
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,146 +1,158 @@
 # Eve
 
-Tiny event helping JavaScript library.
-
-## eve(name, scope, varargs)
-Fires event with given `name`, given scope and other parameters.
-
-### Parameters
-- _name_  **string**
-    name of the _event_, dot (`.`) or slash (`/`) separated
-- _scope_  **object**
-    context for the event handlers
-- _varargs_  **...**
-    the rest of arguments will be sent to event handlers
+Eve is a filesystem-first framework for durable backend agents on Vercel.
+
+You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.
+
+The framework is called Eve. The published npm package is `eve`. The CLI binary is `eve`.
+
+## What Eve Prioritizes
+
+- Markdown-first authoring for instructions and procedures
+- TypeScript where typed runtime behavior matters
+- Durable message runs and follow-up turns
+- Inspectable compiled artifacts under `.eve/`
+- Per-agent sandbox with optional authored overrides
+- A stable HTTP protocol with explicit `continuationToken` and `sessionId` contracts
+- A runtime model that keeps channels, harnesses, and workflow execution separate
+
+## Authored Directory
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+└── agent/
+    ├── agent.ts           # additive runtime config (model, name, build, compaction, …)
+    ├── instructions.md    # always-on instructions prompt
+    ├── tools/             # typed executable integrations
+    ├── skills/            # optional named procedures the model can load on demand
+    ├── hooks/             # lifecycle and stream-event subscribers
+    ├── channels/          # message ingress and delivery (HTTP, Slack, …)
+    ├── connections/       # external MCP server connections
+    ├── sandbox/           # the agent's single sandbox (optional override)
+    ├── workspace/         # files seeded into the sandbox on each session
+    ├── subagents/         # specialist child agents (reuse `defineAgent`)
+    ├── schedules/         # recurring jobs
+    └── lib/               # shared authored code imported by other files
+```
 
-**Returns:**  **object** array of returned values from the listeners. Array has two methods `.firstDefined()` and `.lastDefined()` to get first or last not `undefined` value.
+## Authoring Helpers
 
-## eve.listeners(name)
-Internal method which gives you array of all event handlers that will be triggered by the given `name`.
+Every authored directory has a typed helper. Import each from the matching subpath:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated
+| Helper                                                                                                              | Subpath                               | Authored Location                                |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------ |
+| `defineAgent(...)`                                                                                                  | `eve`                                 | `agent.ts`, `subagents/<id>/agent.ts`            |
+| `defineInstructions(...)`                                                                                           | `eve/instructions`                    | `instructions.ts` (or `instructions.md`)         |
+| `defineTool(...)`, `defineBeveTool(...)`, `defineReadFileTool(...)`, `defineWriteFileTool(...)`, `disableTool(...)` | `eve/tools`                           | `tools/<name>.ts`                                |
+| `defineSkill(...)`, `getSkill(...)`                                                                                 | `eve/skills`                          | `skills/<name>.ts` (or `skills/<name>.md`)       |
+| `defineHook(...)`                                                                                                   | `eve/hooks`                           | `hooks/<slug>.ts`                                |
+| `defineChannel(...)`, `POST`, `GET`                                                                                 | `eve/channels`                        | `channels/<name>.ts`                             |
+| `eveChannel(...)`, `slackChannel(...)`, `vercelOidc(...)`                                                           | `eve/channels/eve`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
+| `defineSandbox(...)`                                                                                                | `eve/sandbox`                         | `sandbox.ts` (or `sandbox/sandbox.ts`)           |
+| `defineSchedule(...)`                                                                                               | `eve/schedules`                       | `schedules/<name>.ts` (or `schedules/<name>.md`) |
+| `defineEvalSuite(...)`                                                                                              | `eve/evals`                           | `evals/<name>.eval.ts`                           |
 
-**Returns:**  **array** array of event handlers
+Runtime accessors live on the subpath that owns the concern:
 
-## eve.separator(separator)
-If for some reasons you don’t like default separators (`.` or `/`) you can specify yours
-here. Be aware that if you pass a string longer than one character it will be treated as
-a list of characters.
+- `getSession()` — current session, turn, auth, parent lineage (`eve/context`)
+- `getSandbox()` — live sandbox handle for the current agent (`eve/sandbox`)
+- `getSkill(identifier)` — handle for a named skill visible to the current agent (`eve/skills`)
+- `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`eve/context`)
 
-### Parameters
-- _separator_  **string**
-    new separator. Empty string resets to default: `.` or `/`.
+The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/reference/typescript-api.md`](./dist/docs/public/reference/typescript-api.md).
 
+## Tiny Example
 
-## eve.on(name, f, name, f)
-Binds given event handler with a given name. You can use wildcards “`*`” for the names:
+`agent/instructions.md`
 
-```js
-eve.on("*.under.*", f);
-eve("mouse.under.floor"); // triggers f
+```md
+You are a weather-focused assistant. Be concise, accurate, and explicit when you use a tool.
 ```
-Use <a href="#eve" class="dr-link">eve</a> to trigger the listener.
-
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
-- _name_  **array**
-    if you don’t want to use separators, you can use array of strings
-- _f_  **function**
-    event handler function
-
-**Returns:**  **function** returned function accepts a single numeric parameter that represents z-index of the handler. It is an optional feature and only used when you need to ensure that some subset of handlers will be invoked in a given order, despite of the order of assignment.
-
-### Example:
-```js
-eve.on("mouse", eatIt)(2);
-eve.on("mouse", scream);
-eve.on("mouse", catchIt)(1);
-```
-This will ensure that `catchIt` function will be called before `eatIt`.
 
-If you want to put your handler before non-indexed handlers, specify a negative value.
-Note: I assume most of the time you don’t need to worry about z-index, but it’s nice to have this feature “just in case”.
+`agent/tools/get_weather.ts`
+
+```ts
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  async execute(input) {
+    return {
+      city: input.city,
+      condition: "Sunny",
+      temperatureF: 72,
+    };
+  },
+});
+```
 
+`agent/agent.ts`
 
-## eve.f(event, varargs)
-Returns function that will fire given event with optional arguments.
-Arguments that will be passed to the result function will be also
-concated to the list of final arguments.
+```ts
+import { defineAgent } from "eve";
 
-```js
-el.onclick = eve.f("click", 1, 2);
-eve.on("click", function (a, b, c) {
-    console.log(a, b, c); // 1, 2, [event object]
+export default defineAgent({
+  model: "openai/gpt-5.4-mini",
 });
 ```
-### Parameters
-- _event_  **string**
-    event name
-- _varargs_  **…**
-    and any other arguments
-
-**Returns:**  **function** possible event handler function
 
-## eve.stop()
-Is used inside an event handler to stop the event, preventing any subsequent listeners from firing.
+## Quick Start
 
+```bash
+pnpm create eve
+cd my-agent
+pnpm dev
+```
 
-## eve.nt([subname])
-Could be used inside event handler to figure out actual name of the event.
+The wizard scaffolds the project, picks a model, and (for the REPL channel) installs dependencies and starts the dev server for you. To scaffold into the current empty directory, run `pnpm create eve .`.
 
-### Parameters
-- _subname_  **string**
-    subname of the event
+CLI commands:
 
-**Returns:**  **string** name of the event, if `subname` is not specified
-or
+- `eve info` — discovery results and compiled artifacts
+- `eve build` — compile `.eve/` and build the host output
+- `eve start` — serve the built `.output/` app
+- `eve dev` — start the local runtime and REPL
 
-**Returns:**  **boolean** `true`, if current event’s name contains `subname`
+## Deploying
 
-## eve.nts()
-Could be used inside event handler to figure out actual name of the event.
+Eve is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/advanced/deployment.md`](./dist/docs/public/advanced/deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
 
-**Returns:**  **array** names of the event
+## Read Next
 
-## eve.off(name, f)
-Removes given function from the list of event listeners assigned to given name.
-If no arguments specified all the events will be cleared.
+These files ship inside the installed package at `node_modules/eve/dist/docs/public/`:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
+- [Full docs index](./dist/docs/public/README.md) — recommended entry point
+- [Getting Started](./dist/docs/public/getting-started.mdx) — install, scaffold, and run locally
+- [Project Layout](./dist/docs/public/reference/project-layout.md) — every authored directory in depth
+- [`agent.ts`](./dist/docs/public/agent-config.md) — agent config reference
+- [TypeScript API](./dist/docs/public/reference/typescript-api.md) — complete `define*` and runtime helper reference
+- [Vercel Deployment](./dist/docs/public/advanced/deployment.md) — deploy to production
 
+By authoring concern: [Tools](./dist/docs/public/tools.mdx) · [Channels](./dist/docs/public/channels/overview.mdx) · [Hooks](./dist/docs/public/advanced/hooks.md) · [Skills](./dist/docs/public/skills.mdx) · [Sandbox](./dist/docs/public/sandbox.mdx) · [Connections](./dist/docs/public/connections.mdx) · [Subagents](./dist/docs/public/subagents.mdx) · [Schedules](./dist/docs/public/schedules.mdx) · [Evals](./dist/docs/public/advanced/evals.md)
 
-## eve.unbind()
-See <a href="#eve.off" class="dr-link">eve.off</a>
+By runtime concern: [Sessions and Streaming](./dist/docs/public/advanced/sessions-runs-and-streaming.md) · [Session Context](./dist/docs/public/advanced/session-context.md) · [Context Control](./dist/docs/public/advanced/context-control.md) · [Auth and Route Protection](./dist/docs/public/advanced/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/reference/cli.md) · [Instrumentation](./dist/docs/public/advanced/instrumentation.md)
 
+## Architecture (Internals)
 
-## eve.once(name, f)
-Binds given event handler with a given name to only run once then unbind itself.
+You do not need this section to author an Eve agent — it documents the public HTTP protocol contracts so Eve composes predictably with other systems.
 
-```js
-eve.once("login", f);
-eve("login"); // triggers f
-eve("login"); // no listeners
-```
-Use <a href="#eve" class="dr-link">eve</a> to trigger the listener.
+Eve's internal split is:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
+- the **channel** normalizes inbound transport, applies auth and delivery policy, and owns `continuationToken`
+- the **harness** does one unit of AI work and returns `{ session, next }`
+- the **runtime** persists state, follows `next`, streams events, and owns workflow primitives (`start()`, `resumeHook()`, `createHook()`, `getWritable()`)
 
-**Returns:**  **function** same return function as <a href="#eve.on" class="dr-link">eve.on</a>
+That split is why the public HTTP protocol separates two distinct identifiers:
 
-## eve.version()
-Current version of the library.
+- `continuationToken` — channel-owned handle the caller uses to start the next user turn
+- `sessionId` — runtime-owned handle for streaming and inspection
 
+## Changelog
 
+See [`./CHANGELOG.md`](./CHANGELOG.md) for the release history. The changelog ships inside the published package so agents can read it directly from `node_modules/eve/CHANGELOG.md` to evaluate upgrades.

package/bin/eve.d.ts

@@ -0,0 +1,66 @@
+export interface BootstrapOptions {
+  /**
+   * Absolute path to the compiled CLI module.
+   */
+  cliEntrypointPath?: string;
+
+  /**
+   * Absolute path to the eve package root.
+   */
+  packageRoot?: string;
+
+  /**
+   * Absolute paths to scripts that run after workspace bootstrap compilation.
+   */
+  postBuildScriptPaths?: readonly string[];
+
+  /**
+   * Absolute path to the tsgo CLI entrypoint used for bootstrap builds.
+   */
+  tsgoCliPath?: string;
+}
+
+export interface BootstrapCommandOptions {
+  cwd: string;
+}
+
+export interface BootstrapBuildDependencies {
+  exists?: (path: string) => Promise<boolean>;
+  getLatestBuildInputMtimeMs?: (input: { packageRoot: string }) => Promise<number>;
+  getPathMtimeMs?: (path: string) => Promise<number | undefined>;
+  runCommand?: (
+    command: string,
+    args: readonly string[],
+    options: BootstrapCommandOptions,
+  ) => Promise<void>;
+}
+
+export interface BootstrapCliModule {
+  runCli(argv?: string[]): Promise<void>;
+}
+
+export interface BootstrapDependencies extends BootstrapBuildDependencies {
+  importModule?: (specifier: string) => Promise<BootstrapCliModule>;
+
+  /**
+   * Node.js version string used by tests to exercise the bin version guard.
+   */
+  nodeVersion?: string;
+}
+
+/**
+ * Ensures the compiled CLI entrypoint exists before the workspace bin is executed.
+ */
+export function ensureBuiltCli(
+  overrides?: BootstrapOptions,
+  dependencies?: BootstrapBuildDependencies,
+): Promise<string>;
+
+/**
+ * Runs the compiled Eve CLI, building the workspace package on demand when needed.
+ */
+export function runEveCli(
+  argv?: string[],
+  overrides?: BootstrapOptions,
+  dependencies?: BootstrapDependencies,
+): Promise<void>;

package/bin/eve.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { access, readdir, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+const minimumNodeMajorVersion = 24;
+
+function createBootstrapOptions(overrides = {}) {
+  const packageRoot =
+    overrides.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+  return {
+    cliEntrypointPath:
+      overrides.cliEntrypointPath ?? resolve(packageRoot, "dist", "src", "cli", "run.js"),
+    packageRoot,
+    postBuildScriptPaths: overrides.postBuildScriptPaths ?? [
+      resolve(packageRoot, "scripts", "copy-compiled-assets.mjs"),
+      resolve(packageRoot, "scripts", "copy-docs.mjs"),
+      resolve(packageRoot, "scripts", "stamp-version-tokens.mjs"),
+    ],
+    tsgoCliPath: overrides.tsgoCliPath,
+  };
+}
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getPathMtimeMs(path) {
+  try {
+    return (await stat(path)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+async function getLatestDirectoryMtimeMs(path) {
+  const stats = await stat(path);
+  let latestMtimeMs = stats.mtimeMs;
+
+  if (!stats.isDirectory()) {
+    return latestMtimeMs;
+  }
+
+  const entries = await readdir(path, {
+    withFileTypes: true,
+  });
+
+  for (const entry of entries) {
+    const entryPath = resolve(path, entry.name);
+    const entryLatestMtimeMs = await getLatestDirectoryMtimeMs(entryPath);
+
+    if (entryLatestMtimeMs > latestMtimeMs) {
+      latestMtimeMs = entryLatestMtimeMs;
+    }
+  }
+
+  return latestMtimeMs;
+}
+
+async function getLatestBuildInputMtimeMs({ packageRoot }) {
+  let latestMtimeMs = 0;
+
+  for (const relativePath of ["src", "bin", "scripts"]) {
+    const path = resolve(packageRoot, relativePath);
+    const pathMtimeMs = await getPathMtimeMs(path);
+
+    if (pathMtimeMs === undefined) {
+      continue;
+    }
+
+    const latestPathMtimeMs = await getLatestDirectoryMtimeMs(path);
+
+    if (latestPathMtimeMs > latestMtimeMs) {
+      latestMtimeMs = latestPathMtimeMs;
+    }
+  }
+
+  return latestMtimeMs;
+}
+
+async function canBuildWorkspaceCli({ exists, packageRoot, postBuildScriptPaths }) {
+  for (const requiredPath of [
+    resolve(packageRoot, "bin"),
+    inputTsconfigPath({
+      packageRoot,
+    }),
+    resolve(packageRoot, "src"),
+    ...postBuildScriptPaths,
+  ]) {
+    if (!(await exists(requiredPath))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function inputTsconfigPath({ packageRoot }) {
+  return resolve(packageRoot, "tsconfig.json");
+}
+
+function parseNodeMajorVersion(version) {
+  const match = /^v?(\d+)/.exec(version);
+  return match ? Number(match[1]) : undefined;
+}
+
+function assertSupportedNodeVersion(version = process.version) {
+  const majorVersion = parseNodeMajorVersion(version);
+
+  if (majorVersion !== undefined && majorVersion >= minimumNodeMajorVersion) {
+    return;
+  }
+
+  throw new Error(
+    [
+      `Eve requires Node.js ${minimumNodeMajorVersion} or newer.`,
+      `You are running ${version}.`,
+      "Please upgrade Node.js and try again.",
+    ].join(" "),
+  );
+}
+
+function resolveTsgoCliPath({ tsgoCliPath }) {
+  if (tsgoCliPath) {
+    return tsgoCliPath;
+  }
+
+  // The `@typescript/native-preview` package only exports `./package.json`
+  // in its `exports` map, so `require.resolve("@typescript/native-preview/bin/tsgo.js")`
+  // fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Resolve the package.json
+  // (which is exported) and join to the binary path manually.
+  const packageJsonPath = require.resolve("@typescript/native-preview/package.json");
+  return resolve(dirname(packageJsonPath), "bin", "tsgo.js");
+}
+
+async function runCommand(command, args, options) {
+  await new Promise((resolveCommand, rejectCommand) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: "inherit",
+    });
+
+    child.once("error", rejectCommand);
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolveCommand();
+        return;
+      }
+
+      if (signal) {
+        rejectCommand(new Error(`Command "${command}" exited due to signal ${signal}.`));
+        return;
+      }
+
+      rejectCommand(new Error(`Command "${command}" exited with code ${code ?? "unknown"}.`));
+    });
+  });
+}
+
+/**
+ * Ensures the compiled CLI entrypoint exists before the workspace bin is executed.
+ */
+export async function ensureBuiltCli(overrides = {}, dependencies = {}) {
+  const options = createBootstrapOptions(overrides);
+  const exists = dependencies.exists ?? fileExists;
+  const getBuildInputMtimeMs =
+    dependencies.getLatestBuildInputMtimeMs ?? getLatestBuildInputMtimeMs;
+  const getEntrypointMtimeMs = dependencies.getPathMtimeMs ?? getPathMtimeMs;
+  const executeCommand = dependencies.runCommand ?? runCommand;
+  const packageCanBuildCli = await canBuildWorkspaceCli({
+    exists,
+    packageRoot: options.packageRoot,
+    postBuildScriptPaths: options.postBuildScriptPaths,
+  });
+
+  if (await exists(options.cliEntrypointPath)) {
+    if (!packageCanBuildCli) {
+      return options.cliEntrypointPath;
+    }
+
+    const [latestBuildInputMtimeMs, cliEntrypointMtimeMs] = await Promise.all([
+      getBuildInputMtimeMs({
+        packageRoot: options.packageRoot,
+      }),
+      getEntrypointMtimeMs(options.cliEntrypointPath),
+    ]);
+
+    if (cliEntrypointMtimeMs !== undefined && cliEntrypointMtimeMs >= latestBuildInputMtimeMs) {
+      return options.cliEntrypointPath;
+    }
+  }
+
+  if (!packageCanBuildCli) {
+    throw new Error(
+      `Eve package at ${options.packageRoot} does not include the sources required to rebuild the CLI.`,
+    );
+  }
+
+  await executeCommand(
+    process.execPath,
+    [resolveTsgoCliPath({ tsgoCliPath: options.tsgoCliPath }), "-p", "tsconfig.json"],
+    {
+      cwd: options.packageRoot,
+    },
+  );
+  for (const scriptPath of options.postBuildScriptPaths) {
+    await executeCommand(process.execPath, [scriptPath], {
+      cwd: options.packageRoot,
+    });
+  }
+
+  if (await exists(options.cliEntrypointPath)) {
+    return options.cliEntrypointPath;
+  }
+
+  throw new Error(`Building eve did not produce ${options.cliEntrypointPath}.`);
+}
+
+/**
+ * Runs the compiled Eve CLI, building the workspace package on demand when needed.
+ */
+export async function runEveCli(argv = process.argv.slice(2), overrides = {}, dependencies = {}) {
+  assertSupportedNodeVersion(dependencies.nodeVersion);
+
+  const cliEntrypointPath = await ensureBuiltCli(overrides, dependencies);
+  const importModule = dependencies.importModule ?? ((specifier) => import(specifier));
+  const cliModule = await importModule(pathToFileURL(cliEntrypointPath).href);
+
+  if (typeof cliModule.runCli !== "function") {
+    throw new Error(`The Eve CLI module at ${cliEntrypointPath} does not export runCli().`);
+  }
+
+  await cliModule.runCli(argv);
+}
+
+async function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  try {
+    const [currentPath, invokedPath] = await Promise.all([
+      realpath(fileURLToPath(import.meta.url)),
+      realpath(process.argv[1]),
+    ]);
+
+    return currentPath === invokedPath;
+  } catch {
+    return false;
+  }
+}
+
+if (await isDirectExecution()) {
+  try {
+    await runEveCli();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    // Walk the `cause` chain so wrapped errors (sandbox prewarm wraps the
+    // underlying Vercel SDK failure with remediation hints, etc.) still
+    // surface the original SDK message a user can search for.
+    let cause = error instanceof Error ? error.cause : undefined;
+    while (cause instanceof Error) {
+      console.error(`  Caused by: ${cause.message}`);
+      cause = cause.cause;
+    }
+    process.exitCode = 1;
+  } finally {
+    // The CLI bootstraps build/dev toolchains that can leave native service
+    // handles alive after the command has completed. Once the top-level
+    // command resolves, terminate the bin process explicitly so commands like
+    // `eve dev` + `/exit` do not hang on leaked implementation details.
+    process.exit(process.exitCode ?? 0);
+  }
+}