From b55d051af3af44b5d0ec89950dea432f42026ee4 Mon Sep 17 00:00:00 2001 From: "upstash-tag[bot]" <313023939+upstash-tag[bot]@users.noreply.github.com> Date: Tue, 25 Aug 2026 11:49:18 +0000 Subject: [PATCH] docs: correct what eve extensions can contribute MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extensions can contribute channels, schedules, and subagents (eve >=0.41, per eve's docs/extensions.md) — this was previously stated as excluded in several places. The actual exclusions at the extension root are: sandbox, agent config, and nested extensions. Fixes CLAUDE.md (two spots) and the same repeated claim in packages/eve-extension/AGENTS.md, packages/eve-extension/README.md, and packages/eve/README.md. --- CLAUDE.md | 16 ++++++++++++---- packages/eve-extension/AGENTS.md | 14 +++++++++----- packages/eve-extension/README.md | 8 ++++---- packages/eve/README.md | 5 +++-- 4 files changed, 28 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 12211a6..dd23c6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -155,8 +155,13 @@ and `eve-extension-demo` (a minimal eve scaffold that mounts the extension). enable `chatHistory` and `disableTool()` the two history slots). Static memory tools are importable from `@upstash/agentkit-eve-extension/tools` for `toolResultFrom`/overrides; the dynamic search and chat-history tools are not. -- What an extension **cannot** contribute (stays in `@upstash/agentkit-eve`): sandbox, channels/auth - (rate limiting), schedules, agent config. `defineCachedTool` also stays there (wraps user tools). +- What an extension **can** contribute (eve ≥0.41, per eve's `docs/extensions.md`): tools, channels, + connections, skills, schedules, subagents, instruction fragments, hooks — channels, schedules and + subagents **are** allowed, and a contributed subagent may own its own agent config and sandbox. + What the extension **root** cannot declare: agent configuration, a sandbox, or nested extensions. + What stays in `@upstash/agentkit-eve` is therefore a packaging choice, not a framework limit: the + Box sandbox backend (an extension root can't declare a sandbox), the rate-limit `AuthFn` (you drop + it into your own channel's `auth` walk), and `defineCachedTool` (wraps user tools). ## Naming history (so you don't resurrect old names) - ai-sdk caching: `cacheTools` → `cachedTool`+`cachedTools` → now **`cachedTools` only** (singular `cachedTool` removed; toolName = map key, `userId` scopes). @@ -315,8 +320,11 @@ and `eve-extension-demo` (a minimal eve scaffold that mounts the extension). `SandboxSession`, `SandboxNetworkPolicy`, etc. (`eve` is a devDep of `packages/eve` for these types.) - `ToolDefinition` = `{ description, inputSchema, execute(input, ctx: ToolContext), … }`. - **Extensions** (eve ≥0.24): agent-shaped packages mounted under `agent/extensions/.ts`; contributions - compose as `__`. They may contribute tools/connections/skills/hooks/instructions — NOT sandbox, - channels, schedules, or agent config. Config binds at runtime (mount evaluation), not at discovery. + compose as `__`. They may contribute tools, channels, connections, skills, schedules, + subagents, hooks and instruction fragments (eve ≥0.41; channels keep their declared route paths and + schedules their cron expressions). The extension **root** cannot declare agent configuration, a + sandbox, or nested extensions — but a contributed subagent may own its own config and sandbox. + Config binds at runtime (mount evaluation), not at discovery. Hooks are observe-only (can't inject context or short-circuit); a thrown hook fails the turn. - Stream events for transcripts: `message.received` (`data.message`: flattened user text) and `message.completed` (`data.message: string | null`, fires multiple times per turn — interim text before diff --git a/packages/eve-extension/AGENTS.md b/packages/eve-extension/AGENTS.md index 3b266b0..875b8d2 100644 --- a/packages/eve-extension/AGENTS.md +++ b/packages/eve-extension/AGENTS.md @@ -16,11 +16,15 @@ unavailable, use https://eve.dev/docs/extensions as a fallback. `eve/extension`. Config is optional; read bound values via the handle's `.config` in tools and hooks. - Add contributions under `extension/` the same way as in an agent: - `tools/`, `connections/`, `skills/`, `hooks/`, and optional instruction - fragments. Names come from file paths; the mount supplies the namespace, so - name tools for what they do (`search`, not `crm_search`). -- An extension cannot declare `agent.ts`, `sandbox`, `schedules`, or nested - `extensions/` — those belong to the consuming agent. + `tools/`, `channels/`, `connections/`, `skills/`, `schedules/`, `subagents/`, + `hooks/`, and optional instruction fragments (eve ≥0.41 supports the full set; + channels keep their route paths and schedules their cron expressions). Names + come from file paths; the mount supplies the namespace, so name tools for what + they do (`search`, not `crm_search`). +- The extension **root** cannot declare agent configuration (`agent.ts`), a + `sandbox/`, or nested `extensions/` — those belong to the consuming agent. A + subagent contributed under `extension/subagents//` may still own its own + agent config and sandbox. ## Build and publish diff --git a/packages/eve-extension/README.md b/packages/eve-extension/README.md index 2cfb7c1..fafc880 100644 --- a/packages/eve-extension/README.md +++ b/packages/eve-extension/README.md @@ -158,10 +158,10 @@ importable as static definitions. ## When to use this vs `@upstash/agentkit-eve` Use the extension when you want the batteries-included bundle under one mount. Use -[`@upstash/agentkit-eve`](../eve) when you need the pieces the extension can't carry — the Upstash -Box **sandbox backend** and the **rate-limit channel auth** (extensions can't contribute sandbox or -channel config) — or its `defineCachedTool` wrapper for your own tools. The two compose fine in one -agent. +[`@upstash/agentkit-eve`](../eve) when you need the pieces this extension doesn't ship — the Upstash +Box **sandbox backend** (an extension root can't declare a sandbox) and the **rate-limit channel +auth** (an `AuthFn` you drop into your own channel's `auth` walk) — or its `defineCachedTool` wrapper +for your own tools. The two compose fine in one agent. ## Telemetry diff --git a/packages/eve/README.md b/packages/eve/README.md index a65fc67..911ea92 100644 --- a/packages/eve/README.md +++ b/packages/eve/README.md @@ -14,8 +14,9 @@ your `agent/` tree: > **Prefer one mount file over per-tool files?** > [`@upstash/agentkit-eve-extension`](../eve-extension) packages the memory + search tools (plus > durable chat-history capture) as an [eve extension](https://eve.dev/docs/extensions) — mount it once -> in `agent/extensions/`. This package remains the home of the sandbox backend, the rate-limit auth -> gate, and `defineCachedTool`, which extensions can't carry. +> in `agent/extensions/`. This package remains the home of the sandbox backend (an extension root +> can't declare a sandbox), the rate-limit auth gate, and `defineCachedTool` — the pieces you wire +> into your own `agent/` tree. Start from an eve project. Scaffold one (it installs `eve` and an AI-SDK provider for you):