Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve)!: skills - serve dynamic skills without a sandbox and remove getSkill (#3669)

Andrew Barbada906b62480c
diff --git a/.changeset/remove-get-skill.md b/.changeset/remove-get-skill.md
new file mode 100644
index 000000000..1bc9c8d30
--- /dev/null
+++ b/.changeset/remove-get-skill.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Breaking: `ctx.getSkill()` and the `SkillHandle` and `SkillFile` types from `eve/skills` are removed. The model still reads skill supporting files with its sandbox tools; if your own tool or hook code needs that data, import it from a module in `lib/` instead. Existing extension builds keep loading unless they call `ctx.getSkill()`.
diff --git a/.changeset/sandbox-free-dynamic-skills.md b/.changeset/sandbox-free-dynamic-skills.md
new file mode 100644
index 000000000..072638fc7
--- /dev/null
+++ b/.changeset/sandbox-free-dynamic-skills.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Dynamic skills no longer start a sandbox to announce or load instructions. Skills that return supporting files are written only when their contents or sandbox change, and a changed package replaces its previous files instead of leaving stale ones behind.
diff --git a/docs/README.md b/docs/README.md
index 459d02d58..c0c065419 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -97,7 +97,7 @@ eve then gives you:
- a reconnectable session stream
- durable session state across turns
- a per-agent sandbox with a shared runtime workspace
-- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`)
+- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`)
## The runtime shape
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index b6125ad94..b723ca52e 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -422,6 +422,8 @@ The caller's team gets its own playbook advertised as a loadable skill; everyone
Skills follow the same naming rule as tools: a single `defineSkill(...)` is named after the file slug, while a map names each entry by its bare key (namespace the key yourself if it might collide). A dynamic skill overrides a same-named authored one; two dynamic resolvers emitting the same name throws.
+A dynamic skill that returns only `markdown` never starts a sandbox: eve keeps its instructions in session state and serves them from `load_skill`. When the skill also returns `files`, eve writes the package to the sandbox skill root when the resolver first returns it, and again only when its contents change or the session gets a new sandbox. A changed package replaces the previous directory, so files omitted from the new result are removed.
+
## Dynamic instructions
A dynamic instructions file returns `defineInstructions({ content, role? })` built from the principal, tenant, channel, or external data. Omit `role` for system context:
diff --git a/docs/guides/session-context.md b/docs/guides/session-context.md
index 0c9ebc5b8..89ca38620 100644
--- a/docs/guides/session-context.md
+++ b/docs/guides/session-context.md
@@ -5,12 +5,11 @@ description: "Use ctx.session and runtime accessors inside eve-managed execution
eve passes a runtime `ctx` to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.
-| Accessor | Provides | Full guide |
-| ---------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
-| `ctx.session` | Session identity, turn metadata, auth, and parent lineage | This page |
-| `ctx.getSandbox()` | The current agent's live sandbox handle | [Sandbox](../sandbox) |
-| `ctx.getSkill(identifier)` | A handle for a skill visible to the current agent | [Skills](../skills#read-skill-files-at-runtime) |
-| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state) |
+| Accessor | Provides | Full guide |
+| ---------------------------- | --------------------------------------------------------- | -------------------------- |
+| `ctx.session` | Session identity, turn metadata, auth, and parent lineage | This page |
+| `ctx.getSandbox()` | The current agent's live sandbox handle | [Sandbox](../sandbox) |
+| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state) |
These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.
@@ -61,17 +60,6 @@ const result = await sandbox.run({ command: "npm test" });
The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
-## `ctx.getSkill(identifier)`
-
-Call `ctx.getSkill(identifier)` to read a packaged skill's supporting files:
-
-```ts
-const skill = ctx.getSkill("research");
-const notes = await skill.file("references/checklist.md").text();
-```
-
-The accessor is synchronous; file content is read lazily from the active sandbox. Visibility follows the current agent. See [Skills](../skills#read-skill-files-at-runtime) for the complete handle behavior.
-
## Custom state with `defineState`
Use `defineState` for durable per-session values that tools, hooks, and channel handlers share. Unlike the `ctx` accessors, import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still require active eve execution. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 8431c1478..adb2352bc 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -105,7 +105,6 @@ import template from "../../prompts/template.txt?raw";
| --------------------------- | ---------------------------------------------------------------------------- |
| `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) |
| `ctx.getSandbox()` | Live sandbox handle; `stop()` releases compute but preserves durable state |
-| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent |
| `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` |
| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
diff --git a/docs/skills.mdx b/docs/skills.mdx
index a13355faf..82f198c83 100644
--- a/docs/skills.mdx
+++ b/docs/skills.mdx
@@ -9,7 +9,7 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
eve scans the files under `agent/skills/` and exposes each one's description to the model alongside a framework-owned `load_skill` tool. When a request matches a skill's description (or you name the skill outright), the model calls `load_skill`, and eve appends that skill's markdown to the active turn's context.
-Static skills do not require a sandbox: `load_skill` returns their instructions directly from the compiled agent. Dynamic skills and access to supporting package files require a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+Listing skills and loading their instructions do not require a sandbox: `load_skill` returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
The description is a routing hint, not a label. Write it as the task that should trigger activation:
@@ -76,16 +76,9 @@ skills.sh skills are community-authored project files. Review their source and t
Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. To share one skill definition across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.
-## Read skill files at runtime
+## Supporting files
-Loading a skill adds its `SKILL.md` to context. To reach a packaged skill's sibling files (references, assets, scripts) from inside a tool or hook, use `ctx.getSkill(id)`:
-
-```ts
-const research = ctx.getSkill("research");
-const checklist = await research.file("references/checklist.md").text();
-```
-
-The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox, relative to that skill package directory.
+Supporting files are for the model. After loading a skill, the model reads its references, assets, and scripts with sandbox filesystem tools such as `read_file` and `bash`. Tools and hooks have no skill file API; when your code needs the same data, import it from a module in `lib/` so it ships with the agent.
## Dynamic skills
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index d1099b842..982777147 100644
--- a/docs/tools/overview.mdx
+++ b/docs/tools/overview.mdx
@@ -199,7 +199,6 @@ examples.
- `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
-- `ctx.getSkill(id)`: read a packaged [skill](/docs/skills)'s metadata and files.
Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.
diff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdx
index bc1d47a11..d0c7d2fdd 100644
--- a/docs/tools/workflows.mdx
+++ b/docs/tools/workflows.mdx
@@ -82,7 +82,7 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
`session`, `callId`, `toolName`, `abortSignal`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
`ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
- `getSandbox` and `getSkill` remain unavailable.
+ `getSandbox` remains unavailable.
- The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
not tools returned from `defineDynamic` resolvers.
diff --git a/e2e/fixtures/agent-skills/agent/skills/house-rules-override.ts b/e2e/fixtures/agent-skills/agent/skills/house-rules-override.ts
index b1a6c16da..a0b155955 100644
--- a/e2e/fixtures/agent-skills/agent/skills/house-rules-override.ts
+++ b/e2e/fixtures/agent-skills/agent/skills/house-rules-override.ts
@@ -3,9 +3,8 @@ import { defineDynamic, defineSkill } from "eve/skills";
export const HOUSE_RULES_OVERRIDE_TOKEN = "house-rules-dynamic-ok-M5T8";
// Emits a skill named `house-rules`, the same name as the authored skill
-// (house-rules.md). A dynamic skill overrides a same-named authored one — the
-// dynamic write overwrites the authored skill's sandbox file — so load_skill
-// returns this body, not the authored one.
+// (house-rules.md). A dynamic skill overrides a same-named authored one, so
+// load_skill returns this body, not the authored one.
export default defineDynamic({
events: {
"session.started": async () => {
diff --git a/e2e/fixtures/agent-skills/evals/skills/dynamic-skill-file.eval.ts b/e2e/fixtures/agent-skills/evals/skills/dynamic-skill-file.eval.ts
new file mode 100644
index 000000000..cc1e20263
--- /dev/null
+++ b/e2e/fixtures/agent-skills/evals/skills/dynamic-skill-file.eval.ts
@@ -0,0 +1,23 @@
+import { defineEval } from "eve/evals";
+
+const DYNAMIC_REFERENCE = "Dynamic policy reference fixture.";
+
+/**
+ * Skill smoke eval:
+ * the dynamic tenant policy package (skills/dynamic-tenant-policy.ts) ships a
+ * supporting file. Its markdown is served from session state, while the file
+ * must still be written to the sandbox skill root for the model to read.
+ */
+export default defineEval({
+ tags: ["real-model"],
+ description: "Skills smoke: dynamic skill supporting file access.",
+ async test(t) {
+ await t.send(
+ "Alice is reviewing the tenant setup. Please use the read_file tool to read " +
+ "$HOME/.agents/skills/dynamic-tenant-policy/references/policy.md, then tell her what it says.",
+ );
+
+ t.succeeded();
+ t.calledTool("read_file", { output: new RegExp(DYNAMIC_REFERENCE, "u") });
+ },
+});
diff --git a/packages/eve/README.md b/packages/eve/README.md
index a17e5db1c..771ece399 100644
--- a/packages/eve/README.md
+++ b/packages/eve/README.md
@@ -61,7 +61,7 @@ Every authored directory has a typed helper. Import each from the matching subpa
| `defineInstructions(...)` | `eve/instructions` | `instructions.ts` (or `instructions.md`) |
| `defineTool(...)`, `defineDynamic(...)`, `disableTool(...)` | `eve/tools` | `tools/<name>.ts` |
| `bash`, `readFile`, `writeFile`, and other provided definitions | `eve/tools/<name>` | `tools/<name>.ts` |
-| `defineSkill(...)`, `getSkill(...)` | `eve/skills` | `skills/<name>.ts` (or `skills/<name>.md`) |
+| `defineSkill(...)` | `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` |
@@ -73,7 +73,6 @@ Runtime accessors live on the subpath that owns the concern:
- `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`)
The complete API reference, including types and lower-level runtime primitives, is in the [TypeScript API Reference](https://eve.dev/docs/reference/typescript-api).
diff --git a/packages/eve/extension-contracts/compatibility/channel/v29.ts b/packages/eve/extension-contracts/compatibility/channel/v29.ts
new file mode 100644
index 000000000..5b53f3769
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v29.ts
@@ -0,0 +1,17 @@
+import { defineChannel, POST } from "#public/channels/index.js";
+
+// Epoch 29 channel event contexts also exposed getSkill(); routes are unchanged.
+export default defineChannel({
+ routes: [
+ POST("/continue/:sessionId", async (_request, { attachSession, params }) => {
+ const result = await attachSession(params.sessionId!).send("Continue.", {
+ auth: null,
+ turnPolicy: "queue",
+ });
+ if (result.status === "session_not_active") {
+ return Response.json({ accepted: false }, { status: 409 });
+ }
+ return Response.json({ sessionId: result.sessionId });
+ }),
+ ],
+});
diff --git a/packages/eve/extension-contracts/compatibility/connection/v24.ts b/packages/eve/extension-contracts/compatibility/connection/v24.ts
new file mode 100644
index 000000000..aae0bc4f3
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v24.ts
@@ -0,0 +1,10 @@
+import { defineMcpClientConnection } from "#public/connections/index.js";
+
+// Epoch 24 resolver contexts also exposed getSkill(); connection options are unchanged.
+export default defineMcpClientConnection({
+ description: "Search the support knowledge base.",
+ url: "https://support.example.com/mcp",
+ approval({ toolName }) {
+ return toolName.startsWith("search") ? "approved" : "user-approval";
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v52.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v52.ts
new file mode 100644
index 000000000..a427a5f1c
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v52.ts
@@ -0,0 +1,14 @@
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+
+// Epoch 52 tool contexts also exposed getSkill(); the remaining members are unchanged.
+export default defineDynamic({
+ events: {
+ "session.started": () => ({
+ session_id: defineTool({
+ description: "Return the current session id.",
+ inputSchema: { type: "object", properties: {} },
+ execute: (_input, ctx) => ctx.session.id,
+ }),
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/hook/v25.ts b/packages/eve/extension-contracts/compatibility/hook/v25.ts
new file mode 100644
index 000000000..74dcef47c
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/hook/v25.ts
@@ -0,0 +1,11 @@
+import { defineHook } from "#public/hooks/index.js";
+
+// Epoch 25 hook contexts also exposed getSkill(); hooks that never called it keep working.
+export default defineHook({
+ events: {
+ async "turn.started"(event, ctx) {
+ const sandbox = await ctx.getSandbox();
+ await sandbox.writeTextFile({ content: event.data.turnId, path: "last-turn.txt" });
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/skill/v1.ts b/packages/eve/extension-contracts/compatibility/skill/v1.ts
new file mode 100644
index 000000000..acd50ca83
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/skill/v1.ts
@@ -0,0 +1,9 @@
+import { defineSkill } from "#public/skills/index.js";
+
+// Epoch 1 also exported SkillHandle and SkillFile for ctx.getSkill(); skill
+// packages themselves never depended on them at runtime.
+export default defineSkill({
+ description: "Follow the incident response checklist.",
+ markdown: "# Incident response\n\nRead `references/checklist.md` before paging anyone.\n",
+ files: { "references/checklist.md": "1. Confirm impact.\n2. Page the owner.\n" },
+});
diff --git a/packages/eve/extension-contracts/compatibility/state/v7.ts b/packages/eve/extension-contracts/compatibility/state/v7.ts
new file mode 100644
index 000000000..54f6b91d0
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/state/v7.ts
@@ -0,0 +1,10 @@
+import { defineState } from "#public/context/index.js";
+
+// Epoch 7 state callers could reach ctx.getSkill() through session context;
+// state handles are unchanged.
+export const visits = defineState("compatibility.visits", () => ({ count: 0 }));
+
+export function recordVisit(): number {
+ visits.update((current) => ({ count: current.count + 1 }));
+ return visits.get().count;
+}
diff --git a/packages/eve/extension-contracts/compatibility/tool/v55.ts b/packages/eve/extension-contracts/compatibility/tool/v55.ts
new file mode 100644
index 000000000..8af1a6b71
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v55.ts
@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { defineTool } from "#public/tools/index.js";
+
+// Epoch 55 tool contexts also exposed getSkill(). Tools that never called it
+// keep working; the remaining context members are unchanged.
+export default defineTool({
+ description: "Count entries in the sandbox working directory.",
+ inputSchema: z.object({}),
+ async execute(_input, ctx) {
+ const sandbox = await ctx.getSandbox();
+ const result = await sandbox.run({ command: "ls -1 | wc -l" });
+ return { count: Number(result.stdout.trim()), sessionId: ctx.session.id };
+ },
+});
diff --git a/packages/eve/extension-contracts/entrypoints/skill.ts b/packages/eve/extension-contracts/entrypoints/skill.ts
index 8ad11e15e..2e91feebd 100644
--- a/packages/eve/extension-contracts/entrypoints/skill.ts
+++ b/packages/eve/extension-contracts/entrypoints/skill.ts
@@ -1,6 +1 @@
-export {
- type NamedSkillDefinition,
- type SkillFile,
- type SkillHandle,
- defineSkill,
-} from "../../src/public/skills/index.ts";
+export { type NamedSkillDefinition, defineSkill } from "../../src/public/skills/index.ts";
diff --git a/packages/eve/extension-contracts/reports/channel/v30.json b/packages/eve/extension-contracts/reports/channel/v30.json
new file mode 100644
index 000000000..f822dcfa6
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v30.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 30,
+ "sha256": "9621e11a9c544806a7626f42b927dd37baab7f7041adc84fea0deb33b9e92414",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v25.json b/packages/eve/extension-contracts/reports/connection/v25.json
new file mode 100644
index 000000000..1571b2e5d
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v25.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 25,
+ "sha256": "613559bd15ad3b9d43798e605ee1f1e9aa3708413598d9b8959dd84522abf593",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v53.json b/packages/eve/extension-contracts/reports/dynamicTool/v53.json
new file mode 100644
index 000000000..c3930eb28
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v53.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 53,
+ "sha256": "d2f698126aadc550cd9b8c8a46da72f190c03330922aac5216ab6ab15fd57f4c",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "auto",
+ "defineDurableCallback",
+ "defineDurableSchema",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v26.json b/packages/eve/extension-contracts/reports/hook/v26.json
new file mode 100644
index 000000000..c25b6b720
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v26.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 26,
+ "sha256": "910565b0a731f68b2906176febc39175e4c593916a4b358b6d2015451da2379a",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/extension-contracts/reports/skill/v2.json b/packages/eve/extension-contracts/reports/skill/v2.json
new file mode 100644
index 000000000..97672bafd
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/skill/v2.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "skill",
+ "epoch": 2,
+ "sha256": "d2de71a9816d0789bb7f3260f11eb380a11f034fe4e75a1ddac060007ec0e399",
+ "exports": ["NamedSkillDefinition", "defineSkill"]
+}
diff --git a/packages/eve/extension-contracts/reports/state/v8.json b/packages/eve/extension-contracts/reports/state/v8.json
new file mode 100644
index 000000000..7397dc37e
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/state/v8.json
@@ -0,0 +1,15 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "state",
+ "epoch": 8,
+ "sha256": "96e71531170a9954fd262d144d7179b5da871f4cfa22b483fea0876a344f651d",
+ "exports": [
+ "Session",
+ "SessionAuth",
+ "SessionAuthContext",
+ "SessionContext",
+ "SessionParent",
+ "SessionTurn",
+ "defineState"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v56.json b/packages/eve/extension-contracts/reports/tool/v56.json
new file mode 100644
index 000000000..c0a89cd6a
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v56.json
@@ -0,0 +1,27 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 56,
+ "sha256": "2ec4f509ff61e63e6033de488f66ccddd541affe6334caac4c9de295ca50097f",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "evaluate",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/src/approval/definition.test.ts b/packages/eve/src/approval/definition.test.ts
index eaebad1dc..1247f8118 100644
--- a/packages/eve/src/approval/definition.test.ts
+++ b/packages/eve/src/approval/definition.test.ts
@@ -36,6 +36,5 @@ describe("approval definitions", () => {
session: { id: string; initiator: unknown; turn: unknown };
}>();
expectTypeOf<ApprovalResponseContext["auth"]>().not.toHaveProperty("getSandbox");
- expectTypeOf<ApprovalResponseContext["auth"]>().not.toHaveProperty("getSkill");
});
});
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index e0d2f0b14..9c116100e 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,8 +22,8 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 55,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55],
+ current: 56,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 56],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
15: "TaskExec replaces stageEffect with send",
@@ -62,9 +62,9 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
dynamicTool: {
- current: 52,
+ current: 53,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52,
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 53,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -97,8 +97,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
channel: {
- current: 29,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29],
+ current: 30,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 30],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
19: "Continuation rekey was removed; channel extensions must use additive continuation.alias instead.",
@@ -132,8 +132,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 24,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24],
+ current: 25,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 25],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -141,8 +141,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
hook: {
- current: 25,
- supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 25],
+ current: 26,
+ supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 25, 26],
dropped: {
1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
@@ -157,7 +157,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
24: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
},
},
- skill: { current: 1, supported: [1], dropped: {} },
+ skill: { current: 2, supported: [1, 2], dropped: {} },
dynamicSkill: {
current: 21,
supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21],
@@ -175,8 +175,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
config: { current: 1, supported: [1], dropped: {} },
state: {
- current: 7,
- supported: [1, 2, 3, 4, 5, 7],
+ current: 8,
+ supported: [1, 2, 3, 4, 5, 7, 8],
dropped: {
6: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",
},
diff --git a/packages/eve/src/context/accessors.integration.test.ts b/packages/eve/src/context/accessors.integration.test.ts
index e70c374f1..900b50ee1 100644
--- a/packages/eve/src/context/accessors.integration.test.ts
+++ b/packages/eve/src/context/accessors.integration.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
import { buildCallbackContext } from "#context/build-callback-context.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import { mockSkill } from "#internal/testing/mocks/mock-skill.js";
import type { RuntimeSandboxSession, SandboxSession } from "#public/definitions/sandbox.js";
/**
@@ -12,8 +11,7 @@ import type { RuntimeSandboxSession, SandboxSession } from "#public/definitions/
*
* Each case runs in-memory through the AppHarness.
* `runtime.runAsSession(init, fn)` binds the authored context and
- * invokes `fn`. `mockSkill()` owns its own tmpdir cleanup via an
- * internally-registered `afterEach`.
+ * invokes `fn`.
*/
describe("buildCallbackContext – session", () => {
@@ -156,51 +154,3 @@ describe("buildCallbackContext – getSandbox", () => {
expect(deletions).toBe(1);
});
});
-
-describe("buildCallbackContext – getSkill", () => {
- it("throws when no authored runtime context is active", () => {
- expect(() => buildCallbackContext()).toThrow("No active eve context");
- });
-
- it("throws when authored runtime execution does not include skill access", async () => {
- const runtime = await createTestRuntime();
-
- await expect(
- runtime.runAsSession({}, () => buildCallbackContext().getSkill("semantic-model")),
- ).rejects.toThrow("eve sandbox runtime access is unavailable in the current async context.");
- });
-
- it("resolves visible skill files across async boundaries", async () => {
- const skill = await mockSkill({
- name: "semantic-model",
- description: "Inspect the semantic model.",
- markdown: "Inspect the semantic model.",
- references: { "catalog.yml": "entities: []\n" },
- });
-
- const sandbox = mockSandbox({
- initialFiles: {
- "/workspace/skills/semantic-model/SKILL.md": "Inspect the semantic model.",
- "/workspace/skills/semantic-model/references/catalog.yml": "entities: []\n",
- },
- });
- const runtime = await createTestRuntime({ skills: [skill.source] });
-
- const result = await runtime.runAsSession({ sandbox }, async () => {
- await Promise.resolve();
- const ctx = buildCallbackContext();
-
- return {
- skill: ctx.getSkill("semantic-model"),
- text: await ctx.getSkill("semantic-model").file("references/catalog.yml").text(),
- };
- });
-
- expect(result.skill.name).toBe("semantic-model");
- await expect(result.skill.file("SKILL.md").text()).resolves.toBe("Inspect the semantic model.");
- await expect(result.skill.file("references/catalog.yml").text()).resolves.toBe(
- "entities: []\n",
- );
- expect(result.text).toBe("entities: []\n");
- });
-});
diff --git a/packages/eve/src/context/build-callback-context.ts b/packages/eve/src/context/build-callback-context.ts
index 3d5c969e2..b516776f9 100644
--- a/packages/eve/src/context/build-callback-context.ts
+++ b/packages/eve/src/context/build-callback-context.ts
@@ -1,9 +1,7 @@
import type { SessionContext } from "#context/session-context.js";
-import type { SkillHandle } from "#shared/skill-types.js";
import type { RuntimeSandboxSession, SandboxSession } from "#shared/sandbox-session.js";
-import { createSandboxSkillHandle } from "#runtime/skills/sandbox-access.js";
import { loadContext } from "#context/container.js";
-import { SandboxKey, SessionKey } from "#context/keys.js";
+import { DynamicSkillSandboxKey, SandboxKey, SessionKey } from "#context/keys.js";
/**
* Builds a {@link SessionContext} from the active ALS scope.
@@ -42,22 +40,13 @@ export function buildCallbackContext(): SessionContext {
throw new Error("The active sandbox runtime does not support deletion.");
}
await access.delete(options);
+ // A recreated sandbox can reuse the same persisted identity.
+ ctx.delete(DynamicSkillSandboxKey);
},
async () => await access.stop(),
);
});
},
-
- getSkill(identifier: string): SkillHandle {
- const access = ctx.get(SandboxKey);
- if (access === undefined) {
- throw new Error(
- "eve sandbox runtime access is unavailable in the current async context. " +
- "Call ctx.getSkill() only from authored runtime functions such as tools, hooks, and channel events.",
- );
- }
- return createSandboxSkillHandle(access, identifier);
- },
};
}
diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
index dcf83268e..4edb4925d 100644
--- a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
@@ -8,17 +8,21 @@ import {
import {
StaticModelReferenceKey,
DynamicSkillManifestKey,
+ DynamicSkillSandboxKey,
SessionIdKey,
SandboxKey,
} from "#context/keys.js";
+import { deserializeContext } from "#context/serialize.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { defineSkill } from "#public/definitions/skill.js";
import { BundleKey, type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
import type { ResolvedDynamicSkillResolver } from "#runtime/types.js";
+import type { SandboxSessionState } from "#sandbox/state.js";
import type { SkillPackageDefinition } from "#shared/skill-definition.js";
const HOME_PROBE_COMMAND = `printf '%s\\n' "$HOME"`;
+const SKILL_ROOT = "/home/agent/.agents/skills";
function createMockBundle(authoredSkillNames: readonly string[] = []): CompiledBundle {
return {
@@ -38,6 +42,11 @@ function createMockBundle(authoredSkillNames: readonly string[] = []): CompiledB
};
}
+function persistedSandbox(id: string): SandboxSessionState {
+ return { providerName: "mock", state: { id }, stateProtocolVersion: 1 };
+}
+
+/** Mirrors ensureSandboxAccess: the persisted state appears once the sandbox starts. */
function createCtx(authoredSkillNames: readonly string[] = []) {
const ctx = new ContextContainer();
const sandbox = mockSandbox({
@@ -45,11 +54,24 @@ function createCtx(authoredSkillNames: readonly string[] = []) {
[HOME_PROBE_COMMAND]: { exitCode: 0, stderr: "", stdout: "/home/agent\n" },
},
});
+ const state: { session: SandboxSessionState | null; next: string } = {
+ next: "sandbox-1",
+ session: null,
+ };
+ const get = vi.fn(async () => {
+ state.session ??= persistedSandbox(state.next);
+ return sandbox.session;
+ });
ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });
ctx.set(SessionIdKey, "test-session");
- ctx.setVirtualContext(SandboxKey, sandbox.access);
+ const access = {
+ captureState: async () => ({ session: state.session }),
+ get,
+ stop: async () => {},
+ };
+ ctx.setVirtualContext(SandboxKey, access);
ctx.set(BundleKey, createMockBundle(authoredSkillNames));
- return { ctx, sandbox };
+ return { access, ctx, get, sandbox, state };
}
function createResolver(
@@ -79,11 +101,20 @@ function makeEvent(): UnstampedMessageStreamEvent {
return { type: "session.started", data: {} } as UnstampedMessageStreamEvent;
}
-function makeSkill(description: string, markdown = description): SkillPackageDefinition {
- return defineSkill({
- description,
- markdown,
- });
+function makeSkill(
+ description: string,
+ markdown = description,
+ files?: Record<string, string>,
+): SkillPackageDefinition {
+ return defineSkill({ description, files, markdown });
+}
+
+async function dispatch(ctx: ContextContainer, ...resolvers: ResolvedDynamicSkillResolver[]) {
+ await dispatchDynamicSkillEvent({ ctx, event: makeEvent(), messages: [], resolvers });
+}
+
+function writtenPaths(sandbox: ReturnType<typeof mockSandbox>): string[] {
+ return sandbox.writes.map((write) => write.path);
}
describe("dispatchDynamicSkillEvent", () => {
@@ -91,7 +122,9 @@ describe("dispatchDynamicSkillEvent", () => {
"does not access the sandbox to rebuild announcements on %s",
async (type) => {
const ctx = new ContextContainer();
- const manifest = { policy: [{ name: "policy", description: "Tenant policy" }] };
+ const manifest = {
+ policy: [{ name: "policy", description: "Tenant policy", markdown: "Tenant policy" }],
+ };
ctx.set(DynamicSkillManifestKey, manifest);
await dispatchDynamicSkillEvent({
@@ -107,7 +140,7 @@ describe("dispatchDynamicSkillEvent", () => {
);
it("restores the skill announcement at the next model step without resolving skills again", async () => {
- const { ctx, sandbox } = createCtx();
+ const { access, ctx } = createCtx();
const handler = vi.fn(() => makeSkill("Tenant policy"));
const resolver = createResolver("policy", handler);
await dispatchDynamicSkillEvent({
@@ -119,7 +152,7 @@ describe("dispatchDynamicSkillEvent", () => {
const announcement = ctx.get(PendingSkillAnnouncementKey);
expect(announcement).toContain("policy: Tenant policy");
ctx.clearVirtualContext();
- ctx.setVirtualContext(SandboxKey, sandbox.access);
+ ctx.setVirtualContext(SandboxKey, access);
await dispatchDynamicSkillEvent({
ctx,
@@ -132,36 +165,61 @@ describe("dispatchDynamicSkillEvent", () => {
expect(handler).toHaveBeenCalledOnce();
});
- it("announces when all dynamic skills are withdrawn", async () => {
- const { ctx, sandbox } = createCtx();
+ it("announces when all dynamic skills are withdrawn without opening the sandbox", async () => {
+ const { ctx, get } = createCtx();
let enabled = true;
const resolver = createResolver("tenant", () =>
enabled ? makeSkill("Tenant policy", "Follow tenant policy.") : null,
);
- await dispatchDynamicSkillEvent({
- ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [resolver],
- });
+ await dispatch(ctx, resolver);
- expect(ctx.get(PendingSkillAnnouncementKey)).toContain("tenant: Tenant policy");
+ expect(ctx.get(PendingSkillAnnouncementKey)).toContain("- tenant: Tenant policy");
+ expect(ctx.get(PendingSkillAnnouncementKey)).not.toContain("tenant/SKILL.md");
expect(ctx.get(DynamicSkillManifestKey)).toEqual({
- tenant: [{ description: "Tenant policy", name: "tenant" }],
+ tenant: [{ description: "Tenant policy", markdown: "Follow tenant policy.", name: "tenant" }],
});
enabled = false;
+ await dispatch(ctx, resolver);
+
+ expect(ctx.get(DynamicSkillManifestKey)).toEqual({});
+ expect(ctx.get(PendingSkillAnnouncementKey)).toBe("Available skills: none");
+ expect(get).not.toHaveBeenCalled();
+ });
+
+ it("rebuilds the announcement after a step boundary without opening the sandbox", async () => {
+ const { ctx, get } = createCtx();
+ await dispatch(
+ ctx,
+ createResolver("tenant", () => makeSkill("Tenant policy", "Body", { "a.md": "a" })),
+ );
+ get.mockClear();
+ ctx.clearVirtualContext();
+
await dispatchDynamicSkillEvent({
ctx,
- event: makeEvent(),
+ event: { type: "step.started", data: {} } as UnstampedMessageStreamEvent,
messages: [],
- resolvers: [resolver],
+ resolvers: [],
});
- expect(ctx.get(DynamicSkillManifestKey)).toEqual({});
- expect(ctx.get(PendingSkillAnnouncementKey)).toBe("Available skills: none");
- expect(sandbox.removedPaths).toEqual(["/home/agent/.agents/skills/tenant"]);
+ expect(ctx.get(PendingSkillAnnouncementKey)).toContain(
+ `- tenant: Tenant policy (path: $HOME/.agents/skills/tenant/SKILL.md)`,
+ );
+ expect(get).not.toHaveBeenCalled();
+ });
+
+ it("stores SKILL.md as authored, including frontmatter", async () => {
+ const { ctx } = createCtx();
+ await dispatch(
+ ctx,
+ createResolver("tenant", () => makeSkill("Tenant", "---\nname: tenant\n---\n# Body\n")),
+ );
+
+ expect(ctx.get(DynamicSkillManifestKey)?.tenant?.[0]?.markdown).toBe(
+ "---\nname: tenant\n---\n# Body\n",
+ );
});
it("keeps remaining dynamic skills in the announcement when one resolver removes its skill", async () => {
@@ -172,20 +230,9 @@ describe("dispatchDynamicSkillEvent", () => {
);
const support = createResolver("support", () => makeSkill("Support policy"));
- await dispatchDynamicSkillEvent({
- ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [tenant, support],
- });
-
+ await dispatch(ctx, tenant, support);
tenantEnabled = false;
- await dispatchDynamicSkillEvent({
- ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [tenant, support],
- });
+ await dispatch(ctx, tenant, support);
const announcement = ctx.get(PendingSkillAnnouncementKey);
expect(announcement).not.toContain("tenant: Tenant policy");
@@ -193,92 +240,69 @@ describe("dispatchDynamicSkillEvent", () => {
});
it("names map entries by their bare key", async () => {
- const { ctx, sandbox } = createCtx();
- const resolver = createResolver("custom", () => ({
- "talk-like-a-dog": makeSkill("Talk like a dog", "Woof."),
- }));
-
- await dispatchDynamicSkillEvent({
+ const { ctx } = createCtx();
+ await dispatch(
ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [resolver],
- });
+ createResolver("custom", () => ({
+ "talk-like-a-dog": makeSkill("Talk like a dog", "Woof."),
+ })),
+ );
expect(ctx.get(DynamicSkillManifestKey)).toEqual({
- custom: [{ description: "Talk like a dog", name: "talk-like-a-dog" }],
+ custom: [{ description: "Talk like a dog", markdown: "Woof.", name: "talk-like-a-dog" }],
});
expect(ctx.get(PendingSkillAnnouncementKey)).toContain("talk-like-a-dog: Talk like a dog");
- expect(
- sandbox.writes.some((w) => w.path.includes("/home/agent/.agents/skills/talk-like-a-dog/")),
- ).toBe(true);
});
it("prefixes map entries with the mount namespace for an extension resolver", async () => {
- const { ctx, sandbox } = createCtx();
- const resolver = createResolver(
- "crm__playbooks",
- () => ({ triage: makeSkill("Triage an account", "Triage.") }),
- "crm",
- );
-
- await dispatchDynamicSkillEvent({
+ const { ctx } = createCtx();
+ await dispatch(
ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [resolver],
- });
+ createResolver(
+ "crm__playbooks",
+ () => ({ triage: makeSkill("Triage an account", "Triage.") }),
+ "crm",
+ ),
+ );
expect(ctx.get(DynamicSkillManifestKey)).toEqual({
- crm__playbooks: [{ description: "Triage an account", name: "crm__triage" }],
+ crm__playbooks: [
+ { description: "Triage an account", markdown: "Triage.", name: "crm__triage" },
+ ],
});
expect(ctx.get(PendingSkillAnnouncementKey)).toContain("crm__triage: Triage an account");
- expect(
- sandbox.writes.some((w) => w.path.includes("/home/agent/.agents/skills/crm__triage/")),
- ).toBe(true);
});
it("lets a dynamic skill override a same-named authored skill instead of throwing", async () => {
const { ctx, sandbox } = createCtx(["talk-like-a-dog"]);
- const resolver = createResolver("custom", () => ({
- "talk-like-a-dog": makeSkill("Dynamic override", "Woof."),
- }));
-
- await dispatchDynamicSkillEvent({
+ await dispatch(
ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [resolver],
- });
+ createResolver("custom", () => ({
+ "talk-like-a-dog": makeSkill("Dynamic override", "Woof.", { "notes.md": "Bark." }),
+ })),
+ );
- // No throw; the dynamic skill is written to the authored skill's path.
- expect(ctx.get(DynamicSkillManifestKey)).toEqual({
- custom: [{ description: "Dynamic override", name: "talk-like-a-dog" }],
+ expect(ctx.get(DynamicSkillManifestKey)?.custom?.[0]).toMatchObject({
+ description: "Dynamic override",
+ markdown: "Woof.",
+ name: "talk-like-a-dog",
});
- expect(
- sandbox.writes.some((w) =>
- w.path.includes("/home/agent/.agents/skills/talk-like-a-dog/SKILL.md"),
- ),
- ).toBe(true);
+ expect(writtenPaths(sandbox)).toEqual([
+ `${SKILL_ROOT}/talk-like-a-dog/SKILL.md`,
+ `${SKILL_ROOT}/talk-like-a-dog/notes.md`,
+ ]);
});
it("collapses a directly-returned single defineSkill to the bare slug", async () => {
- const { ctx, sandbox } = createCtx();
- const resolver = createResolver("tenant", () => makeSkill("Tenant policy"));
-
- await dispatchDynamicSkillEvent({
+ const { ctx } = createCtx();
+ await dispatch(
ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [resolver],
- });
+ createResolver("tenant", () => makeSkill("Tenant policy")),
+ );
expect(ctx.get(DynamicSkillManifestKey)).toEqual({
- tenant: [{ description: "Tenant policy", name: "tenant" }],
+ tenant: [{ description: "Tenant policy", markdown: "Tenant policy", name: "tenant" }],
});
- expect(sandbox.writes.some((w) => w.path.includes("/home/agent/.agents/skills/tenant/"))).toBe(
- true,
- );
});
it("throws and recommends manual namespacing when two resolvers emit the same name", async () => {
@@ -286,17 +310,146 @@ describe("dispatchDynamicSkillEvent", () => {
const alpha = createResolver("alpha", () => ({ shared: makeSkill("From alpha") }));
const beta = createResolver("beta", () => ({ shared: makeSkill("From beta") }));
- await expect(
- dispatchDynamicSkillEvent({
- ctx,
- event: makeEvent(),
- messages: [],
- resolvers: [alpha, beta],
- }),
- ).rejects.toThrow(/Dynamic skill "shared".*Namespace the map key manually/u);
+ await expect(dispatch(ctx, alpha, beta)).rejects.toThrow(
+ /Dynamic skill "shared".*Namespace the map key manually/u,
+ );
expect(sandbox.writes).toEqual([]);
expect(ctx.get(DynamicSkillManifestKey)).toBeUndefined();
expect(ctx.get(PendingSkillAnnouncementKey)).toBeUndefined();
});
});
+
+describe("dynamic skill supporting files", () => {
+ it("writes a package with supporting files once and skips unchanged refreshes", async () => {
+ const { ctx, get, sandbox } = createCtx();
+ const resolver = createResolver("policy", () =>
+ makeSkill("Policy", "# Policy", { "references/rules.md": "Rules" }),
+ );
+
+ await dispatch(ctx, resolver);
+
+ expect(get).toHaveBeenCalledOnce();
+ expect(writtenPaths(sandbox)).toEqual([
+ `${SKILL_ROOT}/policy/SKILL.md`,
+ `${SKILL_ROOT}/policy/references/rules.md`,
+ ]);
+ expect(ctx.get(DynamicSkillManifestKey)?.policy?.[0]?.revision).toMatch(/^[0-9a-f]{64}$/u);
+
+ await dispatch(ctx, resolver);
+
+ expect(get).toHaveBeenCalledOnce();
+ expect(sandbox.writes).toHaveLength(2);
+ });
+
+ it("skips unchanged refreshes after durable state is resumed", async () => {
+ const first = createCtx();
+ const resolver = createResolver("policy", () =>
+ makeSkill("Policy", "# Policy", { "rules.md": "Rules" }),
+ );
+ await dispatch(first.ctx, resolver);
+
+ const resumed = await deserializeContext(
+ JSON.parse(
+ JSON.stringify({
+ [DynamicSkillManifestKey.name]: first.ctx.get(DynamicSkillManifestKey),
+ [DynamicSkillSandboxKey.name]: first.ctx.get(DynamicSkillSandboxKey),
+ }),
+ ),
+ );
+ const get = vi.fn(async () => first.sandbox.session);
+ resumed.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });
+ resumed.set(SandboxKey, {
+ captureState: async () => ({ session: first.state.session }),
+ get,
+ stop: async () => {},
+ });
+ await dispatch(resumed, resolver);
+
+ expect(get).not.toHaveBeenCalled();
+ });
+
+ it("replaces a changed package so omitted files disappear", async () => {
+ const { ctx, sandbox } = createCtx();
+ let files: Record<string, string> = { "a.md": "A", "b.md": "B" };
+ const resolver = createResolver("policy", () => makeSkill("Policy", "# Policy", files));
+
+ await dispatch(ctx, resolver);
+ files = { "a.md": "A2" };
+ await dispatch(ctx, resolver);
+
+ expect(sandbox.removedPaths).toEqual([`${SKILL_ROOT}/policy`, `${SKILL_ROOT}/policy`]);
+ expect(sandbox.files.get(`${SKILL_ROOT}/policy/a.md`)).toBe("A2");
+ expect(sandbox.files.has(`${SKILL_ROOT}/policy/b.md`)).toBe(false);
+ });
+
+ it("rewrites unchanged packages for a different sandbox or after the sandbox is deleted", async () => {
+ const { ctx, sandbox, state } = createCtx();
+ const resolver = createResolver("policy", () =>
+ makeSkill("Policy", "# Policy", { "rules.md": "Rules" }),
+ );
+
+ await dispatch(ctx, resolver);
+ state.session = persistedSandbox("sandbox-2");
+ await dispatch(ctx, resolver);
+ expect(sandbox.writes).toHaveLength(4);
+
+ ctx.delete(DynamicSkillSandboxKey);
+ await dispatch(ctx, resolver);
+ expect(sandbox.writes).toHaveLength(6);
+ });
+
+ it("removes files when a package is withdrawn or loses its supporting files", async () => {
+ const { ctx, sandbox } = createCtx();
+ let result: SkillPackageDefinition | null = makeSkill("Policy", "# Policy", { "a.md": "A" });
+ const resolver = createResolver("policy", () => result);
+
+ await dispatch(ctx, resolver);
+ result = makeSkill("Policy", "# Inline policy");
+ await dispatch(ctx, resolver);
+
+ expect(sandbox.removedPaths).toEqual([`${SKILL_ROOT}/policy`, `${SKILL_ROOT}/policy`]);
+ expect(sandbox.files.has(`${SKILL_ROOT}/policy/a.md`)).toBe(false);
+ expect(ctx.get(DynamicSkillSandboxKey)).toEqual({});
+
+ result = null;
+ await dispatch(ctx, resolver);
+ expect(sandbox.removedPaths).toHaveLength(2);
+ });
+
+ it("does not remove withdrawn files from a sandbox that never received them", async () => {
+ const { ctx, get, sandbox, state } = createCtx();
+ let enabled = true;
+ const resolver = createResolver("policy", () =>
+ enabled ? makeSkill("Policy", "# Policy", { "a.md": "A" }) : null,
+ );
+
+ await dispatch(ctx, resolver);
+ state.session = persistedSandbox("replacement");
+ enabled = false;
+ await dispatch(ctx, resolver);
+
+ expect(get).toHaveBeenCalledOnce();
+ expect(sandbox.removedPaths).toEqual([`${SKILL_ROOT}/policy`]);
+ });
+
+ it("keeps the previous manifest and rewrites a package after a failed write", async () => {
+ const { ctx, sandbox } = createCtx();
+ let content = "A";
+ const resolver = createResolver("policy", () =>
+ makeSkill("Policy", "# Policy", { "a.md": content }),
+ );
+ await dispatch(ctx, resolver);
+ const manifest = ctx.get(DynamicSkillManifestKey);
+
+ content = "B";
+ vi.spyOn(sandbox.session, "writeBinaryFile").mockRejectedValueOnce(new Error("disk full"));
+ await expect(dispatch(ctx, resolver)).rejects.toThrow("disk full");
+ expect(ctx.get(DynamicSkillManifestKey)).toBe(manifest);
+ expect(ctx.get(DynamicSkillSandboxKey)).toEqual({});
+
+ content = "A";
+ await dispatch(ctx, resolver);
+ expect(sandbox.files.get(`${SKILL_ROOT}/policy/a.md`)).toBe("A");
+ });
+});
diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.ts b/packages/eve/src/context/dynamic-skill-lifecycle.ts
index b005fb800..909750b3b 100644
--- a/packages/eve/src/context/dynamic-skill-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-skill-lifecycle.ts
@@ -6,6 +6,7 @@ import {
type MaterializableSkillPackage,
normalizeSkillPackage,
removeSkillPackageFromSandbox,
+ skillPackageRevision,
writeSkillPackageToSandbox,
} from "#shared/skill-package.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
@@ -16,11 +17,13 @@ import { toErrorMessage } from "#shared/errors.js";
import type { ContextContainer } from "#context/container.js";
import {
type DurableDynamicSkillMetadata,
+ type DynamicSkillManifest,
DynamicSkillManifestKey,
+ DynamicSkillSandboxKey,
SandboxKey,
} from "#context/keys.js";
import { buildResolveContext } from "#context/dynamic-resolve-context.js";
-import { resolveSandboxSkillRoot } from "#shared/skill-paths.js";
+import type { SandboxState } from "#sandbox/state.js";
const log = createLogger("dynamic-skills");
@@ -66,16 +69,81 @@ interface DynamicSkillResolution {
readonly named: readonly { name: string; entry: SkillPackageDefinition }[];
}
-async function formatDynamicSkillAnnouncement(input: {
+interface SandboxSkillPackage {
+ readonly revision: string;
+ readonly skill: MaterializableSkillPackage;
+}
+
+function formatDynamicSkillAnnouncement(manifest: DynamicSkillManifest): string {
+ const skills = Object.values(manifest)
+ .flat()
+ .map(({ description, name, revision }) => ({
+ description,
+ hasFiles: revision !== undefined,
+ name,
+ }));
+ return formatAvailableSkillsSection(skills) ?? "Available skills: none";
+}
+
+function toDurableSkill(skill: MaterializableSkillPackage): DurableDynamicSkillMetadata {
+ return {
+ description: skill.description,
+ markdown: skill.markdown,
+ name: skill.name,
+ ...(skill.files.length > 1 ? { revision: skillPackageRevision(skill) } : {}),
+ };
+}
+
+function sandboxIdentity(state: SandboxState): string | null {
+ return state.session === null ? null : JSON.stringify(state.session);
+}
+
+/**
+ * Writes only packages with supporting files. Markdown-only skills are served
+ * from durable context, so they never need a sandbox. A package is skipped when
+ * its revision is unchanged and was written to the same persisted sandbox.
+ */
+async function syncDynamicSkillFiles(input: {
readonly ctx: ContextContainer;
- readonly manifest: Readonly<Record<string, readonly DurableDynamicSkillMetadata[]>>;
-}): Promise<string> {
- const sandbox = await input.ctx.require(SandboxKey).get();
- const skillRoot = sandbox === null ? undefined : await resolveSandboxSkillRoot({ sandbox });
- return (
- formatAvailableSkillsSection(Object.values(input.manifest).flat(), { skillRoot }) ??
- "Available skills: none"
+ readonly previous: ReadonlyMap<string, string>;
+ readonly next: ReadonlyMap<string, SandboxSkillPackage>;
+}): Promise<void> {
+ const { ctx, previous, next } = input;
+ if (previous.size === 0 && next.size === 0) return;
+
+ const access = ctx.require(SandboxKey);
+ const written = ctx.get(DynamicSkillSandboxKey) ?? {};
+ const identity = sandboxIdentity(await access.captureState());
+ const isWritten = (name: string) => identity !== null && written[name] === identity;
+
+ const stale = [...previous.keys()].filter((name) => !next.has(name) && isWritten(name));
+ const pending = [...next.values()].filter(
+ ({ revision, skill }) => previous.get(skill.name) !== revision || !isWritten(skill.name),
);
+ if (stale.length === 0 && pending.length === 0) return;
+
+ const sandbox = await access.get();
+ if (sandbox === null) return;
+
+ // Forget touched packages first so a failed write is never skipped later.
+ const nextWritten = { ...written };
+ for (const name of previous.keys()) {
+ if (!next.has(name)) delete nextWritten[name];
+ }
+ for (const { skill } of pending) delete nextWritten[skill.name];
+ ctx.set(DynamicSkillSandboxKey, { ...nextWritten });
+
+ for (const name of stale) {
+ await removeSkillPackageFromSandbox({ name, sandbox });
+ }
+ const current = sandboxIdentity(await access.captureState());
+ for (const { skill } of pending) {
+ // Replace the directory so files omitted from the new revision disappear.
+ await removeSkillPackageFromSandbox({ name: skill.name, sandbox });
+ await writeSkillPackageToSandbox({ sandbox, skill });
+ if (current !== null) nextWritten[skill.name] = current;
+ }
+ ctx.set(DynamicSkillSandboxKey, nextWritten);
}
// ---------------------------------------------------------------------------
@@ -102,9 +170,9 @@ export const PendingSkillAnnouncementKey = new ContextKey<string>("eve.pendingSk
/**
* Dispatches a stream event to dynamic skill resolvers. On a matching
- * event: runs handlers, materializes resolved skills to the sandbox,
- * cleans up removed skills, and stores a pending announcement for the
- * tool-loop to inject.
+ * event: runs handlers, stores instructions in durable context, syncs
+ * changed supporting files to the sandbox, and stores a pending
+ * announcement for the tool-loop to inject.
*/
export async function dispatchDynamicSkillEvent(input: {
readonly ctx: ContextContainer;
@@ -119,15 +187,11 @@ export async function dispatchDynamicSkillEvent(input: {
if (!ALLOWED_DYNAMIC_SKILL_EVENTS.has(event.type) && event.type !== "step.started") return;
// Build phase: rebuild announcement from durable manifest when the
- // virtual key is empty (step boundary crossed). Sandbox files persist;
- // only the announcement needs rebuilding.
+ // virtual key is empty (step boundary crossed).
if (ctx.get(PendingSkillAnnouncementKey) === undefined) {
const manifest = ctx.get(DynamicSkillManifestKey);
if (manifest !== undefined && Object.keys(manifest).length > 0) {
- ctx.setVirtualContext(
- PendingSkillAnnouncementKey,
- await formatDynamicSkillAnnouncement({ ctx, manifest }),
- );
+ ctx.setVirtualContext(PendingSkillAnnouncementKey, formatDynamicSkillAnnouncement(manifest));
}
}
@@ -181,22 +245,32 @@ export async function dispatchDynamicSkillEvent(input: {
if (updates.length === 0) return;
+ // Only resolvers that just ran are synced; package bytes for the others
+ // are not retained across steps.
const newManifest = { ...manifest };
+ const previous = new Map<string, string>();
+ const next = new Map<string, SandboxSkillPackage>();
for (const { resolver, skills } of updates) {
+ for (const { name, revision } of manifest[resolver.slug] ?? []) {
+ if (revision !== undefined) previous.set(name, revision);
+ }
if (skills.length === 0) {
delete newManifest[resolver.slug];
- } else {
- newManifest[resolver.slug] = skills.map((skill) => ({
- description: skill.description,
- name: skill.name,
- }));
+ continue;
}
+ newManifest[resolver.slug] = skills.map((skill) => {
+ const durable = toDurableSkill(skill);
+ if (durable.revision !== undefined) {
+ next.set(skill.name, { revision: durable.revision, skill });
+ }
+ return durable;
+ });
}
- // A dynamic skill whose name matches an authored skill overrides it: the
- // dynamic write overwrites the authored file at the same sandbox path, so
- // load_skill returns the dynamic body. Two dynamic resolvers emitting the
- // same name is a genuine ambiguity and still throws.
+ // A dynamic skill whose name matches an authored skill overrides it:
+ // load_skill prefers the dynamic body, and supporting files replace the
+ // authored package at the same sandbox path. Two dynamic resolvers
+ // emitting the same name is a genuine ambiguity and still throws.
const dynamicSkillOwners = new Map<string, string>();
for (const [resolverSlug, skills] of Object.entries(newManifest)) {
for (const { name } of skills) {
@@ -210,38 +284,8 @@ export async function dispatchDynamicSkillEvent(input: {
}
}
- const sandbox = await ctx.require(SandboxKey).get();
-
- if (sandbox !== null) {
- const finalDynamicSkillNames = new Set(
- Object.values(newManifest)
- .flat()
- .map((skill) => skill.name),
- );
- const removedSkillNames = new Set<string>();
-
- for (const { resolver } of updates) {
- for (const skill of manifest[resolver.slug] ?? []) {
- if (!finalDynamicSkillNames.has(skill.name)) {
- removedSkillNames.add(skill.name);
- }
- }
- }
-
- for (const name of removedSkillNames) {
- await removeSkillPackageFromSandbox({ name, sandbox });
- }
-
- for (const { skills } of updates) {
- for (const skill of skills) {
- await writeSkillPackageToSandbox({ sandbox, skill });
- }
- }
- }
+ await syncDynamicSkillFiles({ ctx, next, previous });
ctx.set(DynamicSkillManifestKey, newManifest);
- ctx.setVirtualContext(
- PendingSkillAnnouncementKey,
- await formatDynamicSkillAnnouncement({ ctx, manifest: newManifest }),
- );
+ ctx.setVirtualContext(PendingSkillAnnouncementKey, formatDynamicSkillAnnouncement(newManifest));
}
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 1fdd359cc..187f43df8 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -418,7 +418,6 @@ function createApprovalContext(input: {
approvedTools: new Set(),
callId: "call_1",
getSandbox: vi.fn(),
- getSkill: vi.fn(),
session: {
auth: { current: null, initiator: null },
id: "test-session",
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index 17da3de7a..8273d7cc8 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -326,21 +326,39 @@ export const DynamicSubagentAgentConfigKey = new ContextKey<DynamicSubagentAgent
// ---------------------------------------------------------------------------
/**
- * Durable metadata for one session-scoped dynamic skill.
+ * Durable state for one session-scoped dynamic skill.
*/
export interface DurableDynamicSkillMetadata {
readonly name: string;
readonly description: string;
+ /** `SKILL.md` content as authored; `load_skill` strips any frontmatter. */
+ readonly markdown: string;
+ /**
+ * Content hash of the package files. Present only for packages with
+ * supporting files, which are the only packages written to the sandbox.
+ */
+ readonly revision?: string;
}
+export type DynamicSkillManifest = Readonly<Record<string, readonly DurableDynamicSkillMetadata[]>>;
+
/**
* Durable map from resolver slug to the qualified skills it last produced.
- * Used to diff on re-resolution, clean up removed skills from the sandbox,
- * and rebuild the model-visible announcement across turns.
+ * Used to diff on re-resolution, serve `load_skill`, and rebuild the
+ * model-visible announcement across turns without a sandbox.
+ */
+export const DynamicSkillManifestKey = new ContextKey<DynamicSkillManifest>(
+ "eve.dynamicSkillManifest",
+);
+
+/**
+ * Durable map from dynamic skill name to the serialized sandbox session state
+ * that holds its current manifest revision. Refreshes skip writes when the
+ * revision and sandbox are unchanged; deleting the sandbox clears it.
*/
-export const DynamicSkillManifestKey = new ContextKey<
- Record<string, readonly DurableDynamicSkillMetadata[]>
->("eve.dynamicSkillManifest");
+export const DynamicSkillSandboxKey = new ContextKey<Readonly<Record<string, string>>>(
+ "eve.dynamicSkillSandbox",
+);
// ---------------------------------------------------------------------------
// Dynamic instruction keys
diff --git a/packages/eve/src/context/session-context.ts b/packages/eve/src/context/session-context.ts
index cae3cd5c4..78fc6ee9d 100644
--- a/packages/eve/src/context/session-context.ts
+++ b/packages/eve/src/context/session-context.ts
@@ -1,4 +1,3 @@
-import type { SkillHandle } from "#shared/skill-types.js";
import type { RuntimeSandboxSession } from "#shared/sandbox-session.js";
import type { SessionAuth, SessionParent, SessionTurn } from "#context/keys.js";
@@ -28,9 +27,4 @@ export interface SessionContext {
* in the current authored runtime context.
*/
getSandbox(): Promise<RuntimeSandboxSession>;
-
- /**
- * Returns a {@link SkillHandle} for the named authored skill.
- */
- getSkill(identifier: string): SkillHandle;
}
diff --git a/packages/eve/src/execution/harness-tool-execution.integration.test.ts b/packages/eve/src/execution/harness-tool-execution.integration.test.ts
index e95fbfede..2c32912e5 100644
--- a/packages/eve/src/execution/harness-tool-execution.integration.test.ts
+++ b/packages/eve/src/execution/harness-tool-execution.integration.test.ts
@@ -2,19 +2,15 @@ import { describe, expect, it } from "vitest";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import { mockSkill } from "#internal/testing/mocks/mock-skill.js";
import { mockTool } from "#internal/testing/mocks/mock-tool.js";
/**
* Integration coverage for authored tool execution through the harness.
*
* Replaces the `test/harness-tool-execution.integration.test.ts` fixture —
- * the seven cases here exercise the same seam (tool execute, error
- * propagation, session/skill/sandbox exposure) through the AppHarness.
- * No test body touches `mkdtemp`, `installBundledCompiledArtifacts`, or
- * real sandboxes. The skill test delegates materialization to
- * `mockSkill()`, which manages its own temp directory and cleanup
- * automatically via an internally-registered `afterEach` hook.
+ * these cases exercise the same seam (tool execute, error propagation,
+ * session and sandbox exposure) through the AppHarness. No test body
+ * touches `mkdtemp`, `installBundledCompiledArtifacts`, or real sandboxes.
*/
const WEATHER_INPUT_SCHEMA = {
@@ -141,41 +137,6 @@ describe("authored tool execution", () => {
});
});
- it("exposes visible skill files to authored tool execution", async () => {
- const semanticModel = await mockSkill({
- name: "semantic-model",
- description: "Inspect the semantic model.",
- markdown: "Inspect the semantic model.",
- references: {
- "catalog.yml": "entities: []\n",
- },
- });
-
- const skillReader = mockTool({
- name: "skill_reader",
- async execute(_input, ctx) {
- return await ctx.getSkill("semantic-model").file("references/catalog.yml").text();
- },
- });
- const runtime = await createTestRuntime({
- tools: [skillReader],
- skills: [semanticModel.source],
- });
-
- const sandbox = mockSandbox({
- initialFiles: {
- "/workspace/skills/semantic-model/SKILL.md": "Inspect the semantic model.",
- "/workspace/skills/semantic-model/references/catalog.yml": "entities: []\n",
- },
- });
-
- const result = await runtime.runAsSession({ sandbox }, async () =>
- runtime.executeTool(skillReader, {}),
- );
-
- expect(result).toBe("entities: []\n");
- });
-
it("allows authored tools to lazily resolve the sandbox through ctx.getSandbox()", async () => {
const sandbox = mockSandbox({ id: "sbx_tool" });
const sandboxTool = mockTool({
diff --git a/packages/eve/src/execution/session/handoff-steps.test.ts b/packages/eve/src/execution/session/handoff-steps.test.ts
index 9cb9b6472..550a3f47d 100644
--- a/packages/eve/src/execution/session/handoff-steps.test.ts
+++ b/packages/eve/src/execution/session/handoff-steps.test.ts
@@ -64,7 +64,7 @@ describe("validateSessionCheckpointStep", () => {
);
});
- it.each([4, 5, 6, 8])(
+ it.each([5, 6, 7, 9])(
"rejects checkpoint version %s before reading nested state",
async (version) => {
const checkpoint = createCheckpoint();
@@ -93,7 +93,7 @@ describe("validateSessionCheckpointStep", () => {
function createCheckpoint(): SessionCheckpoint {
return {
- version: 7,
+ version: 8,
sessionTimeoutMs: false,
mode: "conversation",
serializedContext: {},
diff --git a/packages/eve/src/execution/session/handoff.test.ts b/packages/eve/src/execution/session/handoff.test.ts
index 32b9edcf7..2937ec509 100644
--- a/packages/eve/src/execution/session/handoff.test.ts
+++ b/packages/eve/src/execution/session/handoff.test.ts
@@ -44,7 +44,7 @@ describe("SessionHandoff", () => {
checkpoint: expect.objectContaining({
mode: "conversation",
sessionTimeoutMs: 60_000,
- version: 7,
+ version: 8,
}),
delivery: trigger.delivery,
targetDeploymentId: "deployment-b",
diff --git a/packages/eve/src/execution/session/handoff.ts b/packages/eve/src/execution/session/handoff.ts
index cfaf1f734..6c75e03ec 100644
--- a/packages/eve/src/execution/session/handoff.ts
+++ b/packages/eve/src/execution/session/handoff.ts
@@ -18,9 +18,9 @@ import type { RunMode } from "#shared/run-mode.js";
* Cross-deployment checkpoint contract. The successor may run a different eve
* build than the owner that produced it; bump when any field changes shape so
* an incompatible successor rejects the handoff instead of misreading state.
- * The shared workflow tool run registry replaces the separate task and waiting-run records.
+ * Dynamic skill manifests retain instruction bodies and package revisions.
*/
-export const SESSION_CHECKPOINT_VERSION = 7;
+export const SESSION_CHECKPOINT_VERSION = 8;
/** Everything a successor needs to continue an idle session. Hooks are derived from the state. */
export interface SessionCheckpoint {
diff --git a/packages/eve/src/execution/skills/instructions.test.ts b/packages/eve/src/execution/skills/instructions.test.ts
index 6048a27a7..e4b25b8ec 100644
--- a/packages/eve/src/execution/skills/instructions.test.ts
+++ b/packages/eve/src/execution/skills/instructions.test.ts
@@ -49,21 +49,12 @@ describe("formatAvailableSkillsSection", () => {
);
});
- it("formats skill line with the resolved skill root", () => {
- const skill = createTestSkill({
- logicalPath: "skills/my-skill/SKILL.md",
- name: "my-skill",
- });
+ it("omits the path for skills without sandbox files", () => {
+ const result = formatAvailableSkillsSection([
+ { description: "Inline only", hasFiles: false, name: "inline" },
+ ]);
- const result = formatAvailableSkillsSection([skill], {
- skillRoot: "/home/agent/.agents/skills",
- });
-
- expect(result).toContain("Skill files live under `/home/agent/.agents/skills/<skill>/`.");
- expect(result).toContain(
- "- my-skill: A test skill (path: /home/agent/.agents/skills/my-skill/SKILL.md)",
- );
- expect(result).not.toContain("fallback");
+ expect(result?.split("\n").at(-1)).toBe("- inline: Inline only");
});
it("always lists all skills in the menu regardless of activation state", () => {
diff --git a/packages/eve/src/execution/skills/instructions.ts b/packages/eve/src/execution/skills/instructions.ts
index 65dedaced..af3f13f57 100644
--- a/packages/eve/src/execution/skills/instructions.ts
+++ b/packages/eve/src/execution/skills/instructions.ts
@@ -3,10 +3,8 @@ import { FALLBACK_SKILL_ROOT, MODEL_SKILL_ROOT } from "#shared/skill-paths.js";
export interface AvailableSkillDescription {
readonly description: string;
readonly name: string;
-}
-
-interface FormatAvailableSkillsSectionOptions {
- readonly skillRoot?: string;
+ /** False when the skill has no sandbox files; its path is omitted. */
+ readonly hasFiles?: boolean;
}
/**
@@ -14,9 +12,9 @@ interface FormatAvailableSkillsSectionOptions {
*
* All skills are always listed regardless of activation state. Active skill
* instructions are never injected into the system prompt — the model already
- * has them from the `load_skill` tool result. Without an active sandbox root,
- * the formatter uses the canonical symbolic skill root so supporting files
- * remain discoverable without provisioning a sandbox.
+ * has them from the `load_skill` tool result. The formatter uses the canonical
+ * symbolic skill root so supporting files remain discoverable without
+ * provisioning a sandbox.
*
* Authored skills call this at graph resolution time so the section is
* part of the turn agent's static instructions. Dynamic skills
@@ -25,7 +23,6 @@ interface FormatAvailableSkillsSectionOptions {
*/
export function formatAvailableSkillsSection(
skills: readonly AvailableSkillDescription[],
- options: FormatAvailableSkillsSectionOptions = {},
): string | null {
if (skills.length === 0) {
return null;
@@ -38,28 +35,16 @@ export function formatAvailableSkillsSection(
"If the user names a skill or the request clearly matches one of the descriptions below, call load_skill before proceeding.",
"If multiple skills match, activate the minimal set that covers the task. After activation, follow the returned instructions instead of improvising around them.",
"If activation fails, say so briefly and continue with the best available alternative.",
- formatSkillLocationLine(options),
+ `Skill files live under \`${MODEL_SKILL_ROOT}/<skill>/\`, with \`${FALLBACK_SKILL_ROOT}/<skill>/\` as the fallback when \`$HOME\` is unavailable.`,
"When a loaded SKILL.md mentions sibling files such as `references/foo.md`, resolve them relative to the directory containing that specific SKILL.md.",
- ...skills.map((skill) => formatAvailableSkillLine({ skill, skillRoot: options.skillRoot })),
+ ...skills.map(formatAvailableSkillLine),
];
return lines.join("\n");
}
-function formatSkillLocationLine(options: FormatAvailableSkillsSectionOptions): string {
- if (options.skillRoot !== undefined) {
- return `Skill files live under \`${options.skillRoot}/<skill>/\`.`;
- }
-
- return `Skill files live under \`${MODEL_SKILL_ROOT}/<skill>/\`, with \`${FALLBACK_SKILL_ROOT}/<skill>/\` as the fallback when \`$HOME\` is unavailable.`;
-}
-
-function formatAvailableSkillLine(input: {
- readonly skill: AvailableSkillDescription;
- readonly skillRoot?: string;
-}): string {
- const prefix = `- ${input.skill.name}: ${input.skill.description}`;
-
- const skillRoot = input.skillRoot ?? MODEL_SKILL_ROOT;
- return `${prefix} (path: ${skillRoot}/${input.skill.name}/SKILL.md)`;
+function formatAvailableSkillLine(skill: AvailableSkillDescription): string {
+ const prefix = `- ${skill.name}: ${skill.description}`;
+ if (skill.hasFiles === false) return prefix;
+ return `${prefix} (path: ${MODEL_SKILL_ROOT}/${skill.name}/SKILL.md)`;
}
diff --git a/packages/eve/src/execution/tools/load-skill.test.ts b/packages/eve/src/execution/tools/load-skill.test.ts
index 2c4b7d9eb..009d39d7a 100644
--- a/packages/eve/src/execution/tools/load-skill.test.ts
+++ b/packages/eve/src/execution/tools/load-skill.test.ts
@@ -6,7 +6,6 @@ import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
import { BundleKey } from "#runtime/sessions/runtime-context-keys.js";
-import { createSandboxSkillHandle } from "#runtime/skills/sandbox-access.js";
import type { ResolvedSkillDefinition } from "#runtime/types.js";
import { readToolBehavior } from "#tools/behavior.js";
import { loadSkill } from "#tools/provided/load-skill.js";
@@ -65,18 +64,9 @@ describe("load_skill executor", () => {
).resolves.toBe("# Research\n\nFollow the evidence.\n");
});
- it("opens the sandbox only when a loaded static skill's sibling file is read", async () => {
- const sandbox = mockSandbox({
- initialFiles: {
- "/workspace/skills/incident-response/references/services/api/owners.md": "# API owners\n",
- },
- });
- const get = vi.fn(async () => sandbox.session);
- const access = {
- captureState: vi.fn(async () => ({ initialized: false, session: null })),
- get,
- stop: vi.fn(async () => {}),
- };
+ it("loads an authored package skill without opening the sandbox", async () => {
+ const get = vi.fn(async () => null);
+ const access = { captureState: async () => ({ session: null }), get, stop: async () => {} };
const ctx = new ContextContainer();
ctx.set(SandboxKey, access);
const execute = skillToolExecutor(ctx, [
@@ -103,24 +93,24 @@ describe("load_skill executor", () => {
"# Incident response\n\nConsult `references/services/api/owners.md` when needed.\n",
);
expect(get).not.toHaveBeenCalled();
-
- const skill = createSandboxSkillHandle(access, "incident-response");
- await expect(skill.file("references/services/api/owners.md").text()).resolves.toBe(
- "# API owners\n",
- );
- expect(get).toHaveBeenCalledOnce();
});
- it("loads an active dynamic skill from the sandbox instead of a same-named authored skill", async () => {
- const sandbox = mockSandbox({
- initialFiles: {
- "/workspace/skills/policy/SKILL.md": "# Dynamic policy\n",
- },
- });
+ it("loads an active dynamic skill from durable context without frontmatter or the sandbox", async () => {
+ const get = vi.fn(async () => null);
const ctx = new ContextContainer();
- ctx.set(SandboxKey, sandbox.access);
+ ctx.set(SandboxKey, {
+ captureState: async () => ({ session: null }),
+ get,
+ stop: async () => {},
+ });
ctx.set(DynamicSkillManifestKey, {
- policy: [{ description: "Apply the dynamic policy", name: "policy" }],
+ policy: [
+ {
+ description: "Apply the dynamic policy",
+ markdown: "---\nname: policy\n---\n# Dynamic policy\n",
+ name: "policy",
+ },
+ ],
});
const execute = skillToolExecutor(ctx, [
{
@@ -136,6 +126,7 @@ describe("load_skill executor", () => {
await expect(
contextStorage.run(ctx, () => execute({ skill: "policy" }, {} as never)),
).resolves.toBe("# Dynamic policy\n");
+ expect(get).not.toHaveBeenCalled();
});
it("surfaces dynamic skill names when the requested id is missing", async () => {
@@ -143,8 +134,8 @@ describe("load_skill executor", () => {
ctx.set(SandboxKey, mockSandbox().access);
ctx.set(DynamicSkillManifestKey, {
custom: [
- { description: "Talk like a dog", name: "custom__talk-like-a-dog" },
- { description: "Bark", name: "custom__bark" },
+ { description: "Talk like a dog", markdown: "# Woof", name: "custom__talk-like-a-dog" },
+ { description: "Bark", markdown: "# Bark", name: "custom__bark" },
],
});
const execute = skillToolExecutor(ctx);
diff --git a/packages/eve/src/execution/tools/load-skill.ts b/packages/eve/src/execution/tools/load-skill.ts
index 0c4cf57ce..7bca1d98e 100644
--- a/packages/eve/src/execution/tools/load-skill.ts
+++ b/packages/eve/src/execution/tools/load-skill.ts
@@ -1,10 +1,10 @@
import { z } from "#compiled/zod/index.js";
import { loadContext } from "#context/container.js";
-import { DynamicSkillManifestKey, SandboxKey } from "#context/keys.js";
+import { DynamicSkillManifestKey } from "#context/keys.js";
import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
import { BundleKey } from "#runtime/sessions/runtime-context-keys.js";
-import { loadSkillFromSandbox } from "#runtime/skills/sandbox-access.js";
+import { stripSkillFrontmatter } from "#shared/skill-package.js";
/**
* Typed input accepted by {@link executeLoadSkillTool}.
@@ -14,57 +14,34 @@ type LoadSkillInput = z.infer<typeof SKILL_INPUT_SCHEMA>;
/**
* Executes the `load_skill` tool.
*
- * Returns authored skill instructions directly from the resolved agent.
- * Active dynamic skills take precedence and remain sandbox-backed because
- * their full package content is currently materialized there at runtime.
+ * Returns instructions from memory without a sandbox: authored skills from the
+ * resolved agent and dynamic skills from durable context. Dynamic skills take
+ * precedence over authored skills with the same name.
*/
async function executeLoadSkillTool(args: LoadSkillInput): Promise<unknown> {
const ctx = loadContext();
const { skill } = args;
+ const dynamicSkills = Object.values(ctx.get(DynamicSkillManifestKey) ?? {}).flat();
const authoredSkills = ctx.require(BundleKey).resolvedAgent.skills;
- const dynamicSkillNames = availableDynamicSkillNames(ctx);
+ const dynamicSkill = dynamicSkills.find((entry) => entry.name === skill);
+ if (dynamicSkill !== undefined) return stripSkillFrontmatter(dynamicSkill.markdown);
+ const authoredSkill = authoredSkills.find((entry) => entry.name === skill);
+ if (authoredSkill !== undefined) return authoredSkill.markdown;
+
const availableSkills = [
- ...new Set([...authoredSkills.map((entry) => entry.name), ...dynamicSkillNames]),
+ ...new Set([...dynamicSkills, ...authoredSkills].map((entry) => entry.name)),
].sort();
+ const message = formatSkillNotFoundError(skill, availableSkills);
+ const connectionName = ctx
+ .get(ConnectionRegistryKey)
+ ?.getConnectionNames()
+ .find((name) => name.toLowerCase() === skill.toLowerCase());
+ if (connectionName === undefined) throw new Error(message);
- try {
- if (dynamicSkillNames.includes(skill)) {
- const sandbox = ctx.get(SandboxKey);
- if (sandbox === undefined) {
- throw new Error(
- `The dynamic skill "${skill}" requires sandbox access on the runtime context.`,
- );
- }
- return await loadSkillFromSandbox(sandbox, skill, availableSkills);
- }
-
- const authoredSkill = authoredSkills.find((entry) => entry.name === skill);
- if (authoredSkill !== undefined) {
- return authoredSkill.markdown;
- }
-
- throw new Error(formatSkillNotFoundError(skill, availableSkills));
- } catch (error) {
- const connectionName = ctx
- .get(ConnectionRegistryKey)
- ?.getConnectionNames()
- .find((name) => name.toLowerCase() === skill.toLowerCase());
- if (connectionName === undefined || availableSkills.includes(skill)) throw error;
-
- const message = error instanceof Error ? error.message : String(error);
- throw new Error(
- `${message} "${connectionName}" is an installed connection, not a skill. ` +
- `Use connection_search with connection "${connectionName}" to find its tools.`,
- { cause: error },
- );
- }
-}
-
-function availableDynamicSkillNames(ctx: ReturnType<typeof loadContext>): string[] {
- const dynamic = Object.values(ctx.get(DynamicSkillManifestKey) ?? {})
- .flat()
- .map((entry) => entry.name);
- return [...new Set(dynamic)].sort();
+ throw new Error(
+ `${message} "${connectionName}" is an installed connection, not a skill. ` +
+ `Use connection_search with connection "${connectionName}" to find its tools.`,
+ );
}
function formatSkillNotFoundError(skill: string, availableSkills: readonly string[]): string {
diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
index c1b404b26..8cf5a2758 100644
--- a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts
@@ -63,7 +63,13 @@ it.each(
ctx.set(SessionIdKey, "parent");
ctx.set(AuthKey, null);
ctx.set(DynamicSkillManifestKey, {
- policy: [{ name: "policy", description: "Parent delegation policy" }],
+ policy: [
+ {
+ name: "policy",
+ description: "Parent delegation policy",
+ markdown: "Delegate carefully.",
+ },
+ ],
});
// SessionKey is virtual: a production deserializer cannot restore it.
expect(ctx.has(SessionKey)).toBe(false);
diff --git a/packages/eve/src/execution/tools/workflow/body.ts b/packages/eve/src/execution/tools/workflow/body.ts
index b8bf63100..02680b7f7 100644
--- a/packages/eve/src/execution/tools/workflow/body.ts
+++ b/packages/eve/src/execution/tools/workflow/body.ts
@@ -155,7 +155,6 @@ function createWorkflowBodyContext(
abortSignal: signal,
callId: input.callId,
getSandbox: () => unavailable("getSandbox()", "the session sandbox belongs to the turn"),
- getSkill: () => unavailable("getSkill()", "skills are read through the session sandbox"),
getToken: () =>
unavailable("getToken()", 'pass ctx directly to a "use step" helper to resolve credentials'),
requireAuth: () =>
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index 517ee870c..83f4bb5a6 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -160,7 +160,7 @@ describe("session owner starts", () => {
getRunMock.mockReturnValue({ getWritable: () => sessionWritable });
startMock.mockResolvedValue({ runId: "owner-2" });
const checkpoint = {
- version: 7,
+ version: 8,
mode: "conversation",
serializedContext: {},
sessionState: { continuationToken: "continuation-1", sessionId: "session-1" },
diff --git a/packages/eve/src/harness/tools.test.ts b/packages/eve/src/harness/tools.test.ts
index 43522659d..0045c0153 100644
--- a/packages/eve/src/harness/tools.test.ts
+++ b/packages/eve/src/harness/tools.test.ts
@@ -1120,7 +1120,6 @@ describe("buildToolSet", () => {
});
expect(capturedCtx?.session.auth.current?.principalId).toBe("user_current");
expect(capturedCtx?.getSandbox).toBeTypeOf("function");
- expect(capturedCtx?.getSkill).toBeTypeOf("function");
});
it("uses the active principal for schedule approval", async () => {
diff --git a/packages/eve/src/public/channels/linear/defaults.test.ts b/packages/eve/src/public/channels/linear/defaults.test.ts
index 83666c2f6..2d3a172c4 100644
--- a/packages/eve/src/public/channels/linear/defaults.test.ts
+++ b/packages/eve/src/public/channels/linear/defaults.test.ts
@@ -10,7 +10,6 @@ import type {
function sessionContext(): SessionContext {
return {
getSandbox: vi.fn(),
- getSkill: vi.fn(),
session: {
auth: {
current: {
diff --git a/packages/eve/src/public/channels/slack/defaults.test.ts b/packages/eve/src/public/channels/slack/defaults.test.ts
index a3e489db9..15251619e 100644
--- a/packages/eve/src/public/channels/slack/defaults.test.ts
+++ b/packages/eve/src/public/channels/slack/defaults.test.ts
@@ -9,7 +9,6 @@ function sessionContext(
): SessionContext {
return {
getSandbox: vi.fn(),
- getSkill: vi.fn(),
session: {
auth: { current, initiator: null },
id: "test-session",
diff --git a/packages/eve/src/public/definitions/channel.test.ts b/packages/eve/src/public/definitions/channel.test.ts
index 2bbc84ad8..c1a94dec9 100644
--- a/packages/eve/src/public/definitions/channel.test.ts
+++ b/packages/eve/src/public/definitions/channel.test.ts
@@ -480,7 +480,7 @@ describe("defineChannel", () => {
expect(capturedCtx).toBeDefined();
expect(typeof capturedCtx.getSandbox).toBe("function");
- expect(typeof capturedCtx.getSkill).toBe("function");
+ expect(capturedCtx).not.toHaveProperty("getSkill");
expect(capturedCtx.session.id).toBe("sess-channel-test");
expect(capturedCtx.session.turn).toEqual({ id: "turn-1", sequence: 0 });
expect(capturedChannel.session).toBeUndefined();
diff --git a/packages/eve/src/public/memory/file/provider.test.ts b/packages/eve/src/public/memory/file/provider.test.ts
index b3667893c..ce7f11f1e 100644
--- a/packages/eve/src/public/memory/file/provider.test.ts
+++ b/packages/eve/src/public/memory/file/provider.test.ts
@@ -407,9 +407,6 @@ function operationContext() {
getSandbox: async () => {
throw new Error("not available");
},
- getSkill: () => {
- throw new Error("not available");
- },
memory: {
scope: { key: "mem_scope", namespace: "test", value: "scope-1" },
slot: "facts",
diff --git a/packages/eve/src/public/skills/index.ts b/packages/eve/src/public/skills/index.ts
index a67cdde89..fb2babcf2 100644
--- a/packages/eve/src/public/skills/index.ts
+++ b/packages/eve/src/public/skills/index.ts
@@ -1,8 +1,7 @@
/**
- * Skill authoring helpers and runtime accessors.
+ * Skill authoring helpers.
*/
-export type { SkillFile, SkillHandle } from "#shared/skill-types.js";
export {
defineSkill,
type NamedSkillDefinition,
diff --git a/packages/eve/src/runtime/skills/sandbox-access.test.ts b/packages/eve/src/runtime/skills/sandbox-access.test.ts
deleted file mode 100644
index a70da8aef..000000000
--- a/packages/eve/src/runtime/skills/sandbox-access.test.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
- assertSafeSkillId,
- createSandboxSkillHandle,
- loadSkillFromSandbox,
-} from "#runtime/skills/sandbox-access.js";
-import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-
-const HOME_PROBE_COMMAND = `printf '%s\\n' "$HOME"`;
-
-describe("assertSafeSkillId", () => {
- it("accepts path-derived skill ids", () => {
- expect(() => assertSafeSkillId("research-skill")).not.toThrow();
- expect(() => assertSafeSkillId("research_skill")).not.toThrow();
- });
-
- it("rejects unsafe path segments", () => {
- for (const value of ["", " skill", ".skill", "../skill", "a/b", "a\\b", "C:skill"]) {
- expect(() => assertSafeSkillId(value)).toThrow("Expected skill id");
- }
- });
-});
-
-describe("loadSkillFromSandbox", () => {
- it("reads SKILL.md from the sandbox and strips frontmatter", async () => {
- const sandbox = mockSandbox({
- commands: {
- [HOME_PROBE_COMMAND]: { exitCode: 0, stderr: "", stdout: "/home/agent\n" },
- },
- initialFiles: {
- "/home/agent/.agents/skills/research/SKILL.md":
- "---\nname: research\ndescription: x\n---\n# Research\n",
- },
- });
-
- await expect(loadSkillFromSandbox(sandbox.access, "research")).resolves.toBe("# Research\n");
- });
-
- it("does not read an ordinary workspace skills subtree when HOME is usable", async () => {
- const sandbox = mockSandbox({
- commands: {
- [HOME_PROBE_COMMAND]: { exitCode: 0, stderr: "", stdout: "/home/agent\n" },
- },
- initialFiles: {
- "/workspace/skills/research/SKILL.md": "# Research\n",
- },
- });
-
- await expect(loadSkillFromSandbox(sandbox.access, "research")).rejects.toThrow(
- 'No skill named "research" at /home/agent/.agents/skills/research/SKILL.md.',
- );
- });
-
- it("reads the legacy workspace skill path when HOME is unavailable", async () => {
- const sandbox = mockSandbox({
- initialFiles: {
- "/workspace/skills/research/SKILL.md": "# Research\n",
- },
- });
-
- await expect(loadSkillFromSandbox(sandbox.access, "research")).resolves.toBe("# Research\n");
- });
-
- it("throws when the skill is missing", async () => {
- const sandbox = mockSandbox();
-
- await expect(loadSkillFromSandbox(sandbox.access, "missing")).rejects.toThrow(
- 'No skill named "missing"',
- );
- });
-
- it("lists available skill names when the requested id is missing", async () => {
- const sandbox = mockSandbox();
-
- await expect(
- loadSkillFromSandbox(sandbox.access, "talk-like-a-dog", [
- "custom__talk-like-a-dog",
- "research",
- ]),
- ).rejects.toThrow("Available skills: custom__talk-like-a-dog, research.");
- });
-});
-
-describe("createSandboxSkillHandle", () => {
- it("reads text and bytes relative to the skill root", async () => {
- const sandbox = mockSandbox({
- commands: {
- [HOME_PROBE_COMMAND]: { exitCode: 0, stderr: "", stdout: "/home/agent\n" },
- },
- initialFiles: {
- "/home/agent/.agents/skills/research/references/catalog.yml": "entities: []\n",
- },
- });
- const handle = createSandboxSkillHandle(sandbox.access, "research");
-
- expect(handle.name).toBe("research");
- await expect(handle.file("references/catalog.yml").text()).resolves.toBe("entities: []\n");
- await expect(handle.file("references/catalog.yml").bytes()).resolves.toEqual(
- Buffer.from("entities: []\n"),
- );
- });
-});
diff --git a/packages/eve/src/runtime/skills/sandbox-access.ts b/packages/eve/src/runtime/skills/sandbox-access.ts
deleted file mode 100644
index 7314f5bc5..000000000
--- a/packages/eve/src/runtime/skills/sandbox-access.ts
+++ /dev/null
@@ -1,132 +0,0 @@
-import type { SandboxSession } from "#public/definitions/sandbox.js";
-import type { SandboxAccess } from "#sandbox/state.js";
-import type { SkillHandle } from "#shared/skill-types.js";
-import { resolveSandboxSkillReadPaths } from "#shared/skill-paths.js";
-
-const FRONTMATTER_PATTERN = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
-
-/**
- * Validates a skill id before it is used as one path segment under
- * the sandbox skill root.
- */
-export function assertSafeSkillId(id: string): asserts id is string {
- if (
- id.length === 0 ||
- id.trim() !== id ||
- id.startsWith(".") ||
- id.includes("/") ||
- id.includes("\\") ||
- id.includes("..") ||
- /^[A-Za-z]:/.test(id)
- ) {
- throw new Error(
- 'Expected skill id to be a non-empty safe path segment without whitespace, separators, "." prefix, or "..".',
- );
- }
-}
-
-/**
- * Reads one skill's instruction markdown from the current sandbox.
- *
- * Returns the SKILL.md body with any YAML frontmatter stripped, so the
- * model receives plain markdown as the tool result. Throws when the id
- * is unsafe or the file does not exist; the AI SDK forwards the error
- * to the model as a tool-error result. `availableNames`, when given, is
- * listed in the not-found error so the model can correct a wrong id.
- */
-export async function loadSkillFromSandbox(
- access: SandboxAccess,
- id: string,
- availableNames: readonly string[] = [],
-): Promise<string> {
- assertSafeSkillId(id);
- const sandbox = await requireSandboxSession(access);
- const paths = await resolveSandboxSkillReadPaths({
- name: id,
- relativePath: "SKILL.md",
- sandbox,
- });
-
- for (const path of paths) {
- const instructions = await sandbox.readTextFile({ path });
- if (instructions !== null) {
- return instructions.replace(FRONTMATTER_PATTERN, "");
- }
- }
-
- const hint = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}.` : "";
- throw new Error(`No skill named "${id}" at ${paths[0]}.${hint}`);
-}
-
-/**
- * Creates the public runtime skill handle. Existence is checked lazily by
- * each file read against the sandbox.
- */
-export function createSandboxSkillHandle(access: SandboxAccess, id: string): SkillHandle {
- assertSafeSkillId(id);
-
- return {
- name: id,
- file(relativePath: string) {
- assertSafeSkillRelativePath(relativePath);
-
- return {
- async bytes(): Promise<Uint8Array> {
- const sandbox = await requireSandboxSession(access);
- const paths = await resolveSandboxSkillReadPaths({
- name: id,
- relativePath,
- sandbox,
- });
-
- for (const path of paths) {
- const content = await sandbox.readBinaryFile({ path });
- if (content !== null) {
- return content;
- }
- }
-
- throw new Error(`Skill file not found: ${paths[0]}`);
- },
- async text(): Promise<string> {
- const sandbox = await requireSandboxSession(access);
- const paths = await resolveSandboxSkillReadPaths({
- name: id,
- relativePath,
- sandbox,
- });
-
- for (const path of paths) {
- const content = await sandbox.readTextFile({ path });
- if (content !== null) {
- return content;
- }
- }
-
- throw new Error(`Skill file not found: ${paths[0]}`);
- },
- };
- },
- };
-}
-
-function assertSafeSkillRelativePath(relativePath: string): void {
- if (
- relativePath.length === 0 ||
- relativePath.startsWith("/") ||
- relativePath.includes("\\") ||
- relativePath
- .split("/")
- .some((segment) => segment.length === 0 || segment === "." || segment === "..")
- ) {
- throw new Error("Expected skill file path to be a relative path inside the skill directory.");
- }
-}
-
-async function requireSandboxSession(access: SandboxAccess): Promise<SandboxSession> {
- const sandbox = await access.get();
- if (sandbox === null) {
- throw new Error("The sandbox is not available in the current authored runtime context.");
- }
- return sandbox;
-}
diff --git a/packages/eve/src/shared/skill-package.ts b/packages/eve/src/shared/skill-package.ts
index 0c7f1af01..952bc26e7 100644
--- a/packages/eve/src/shared/skill-package.ts
+++ b/packages/eve/src/shared/skill-package.ts
@@ -1,4 +1,5 @@
import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
import { mkdir, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
@@ -20,6 +21,19 @@ export interface MaterializableSkillPackage {
readonly name: string;
}
+export function stripSkillFrontmatter(markdown: string): string {
+ return markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+
+/** Content hash over every package file, including `SKILL.md`. */
+export function skillPackageRevision(skill: MaterializableSkillPackage): string {
+ const hash = createHash("sha256");
+ for (const file of skill.files) {
+ hash.update(`${file.relativePath}\0${file.content.byteLength}\0`).update(file.content);
+ }
+ return hash.digest("hex");
+}
+
/**
* Normalizes one named skill package into the concrete files eve writes to
* workspace resources or the live sandbox.
diff --git a/packages/eve/src/shared/skill-types.ts b/packages/eve/src/shared/skill-types.ts
deleted file mode 100644
index 5987d8e17..000000000
--- a/packages/eve/src/shared/skill-types.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-/**
- * A reference to one file inside a sandbox-backed skill directory.
- */
-export interface SkillFile {
- /** Reads the file content as bytes. */
- bytes(): Promise<Uint8Array>;
- /** Reads the file content as UTF-8 text. */
- text(): Promise<string>;
-}
-
-/**
- * Public handle to one authored skill, returned by `ctx.getSkill()`.
- *
- * Exposes skill metadata and reads files from a skill package.
- */
-export interface SkillHandle {
- /** The skill identifier passed to `ctx.getSkill()`, used as the skill directory segment under the sandbox skills root. */
- readonly name: string;
-
- /**
- * Returns a file accessor for a path relative to the skill root.
- */
- file(relativePath: string): SkillFile;
-}
diff --git a/packages/eve/src/tools/approval/policies.test.ts b/packages/eve/src/tools/approval/policies.test.ts
index 7da0940f3..b3c05bccf 100644
--- a/packages/eve/src/tools/approval/policies.test.ts
+++ b/packages/eve/src/tools/approval/policies.test.ts
@@ -13,7 +13,6 @@ function approvalContext(overrides: Partial<ApprovalContext> = {}): ApprovalCont
approvedTools: new Set(),
callId: "call-1",
getSandbox: vi.fn(),
- getSkill: vi.fn(),
session: {
auth: { current: null, initiator: null },
id: "session-1",
diff --git a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
index a7d66939a..2d3f1ec03 100644
--- a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
+++ b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
@@ -810,7 +810,7 @@ describe("app runtime dependency tracing", () => {
expect(serverModuleSource).toContain(
"Execute a shell command in the shared workspace environment.",
);
- expect(serverModuleSource).toContain("The dynamic skill");
+ expect(serverModuleSource).toContain("is an installed connection, not a skill.");
expect(serverModuleSource).toContain("URL must start with https://");
}, 30_000);