Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): publish a local-dev capability for authored tools (#2638)

prhac72dc2efa2a8
diff --git a/.changeset/local-dev-capability.md b/.changeset/local-dev-capability.md
new file mode 100644
index 000000000..97bc6688a
--- /dev/null
+++ b/.changeset/local-dev-capability.md
@@ -0,0 +1,10 @@
+---
+"eve": patch
+---
+
+Adds `eve/local-dev`, whose `getLocalDevCapability()` gives authored code the
+authored application root and a lease-based way to pause the authored-source
+watcher while mutating that tree. The capability is scoped to executions
+initiated by same-machine requests to `eve dev` and remains available across
+durable workflow steps and local subagents; deployed runtimes and
+remote-attached clients receive `undefined`.
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index dd84b6870..ba0c35815 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -132,6 +132,7 @@ import template from "../../prompts/template.txt?raw";
| `eve/context` | `defineState`, session and state types |
| `eve/sandbox` | `defineSandbox`, backends |
| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |
+| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |
| `eve/models/openai` | `chatgpt`, deprecated `experimental_chatgpt` |
| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
@@ -143,6 +144,29 @@ import template from "../../prompts/template.txt?raw";
Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
+## Local development capability
+
+Use `getLocalDevCapability()` when an authored tool needs to modify the local application's source tree during an interactive development turn:
+
+```ts
+import { getLocalDevCapability } from "eve/local-dev";
+
+const localDev = getLocalDevCapability();
+if (localDev === undefined) {
+ throw new Error("This tool is available only from a local eve dev client.");
+}
+
+await localDev.withSuspendedSource(async () => {
+ // Write under localDev.appRoot here.
+});
+```
+
+The function returns `LocalDevCapability | undefined`. It returns a capability only while authored code handles a request from a client on the same machine as the `eve dev` server. Deployed runtimes and clients attached over the network receive `undefined`, even when the target is another development server. A local TUI that attaches to an existing headless server receives the capability because availability follows each request rather than the process that started the server.
+
+`appRoot` is the authored application directory containing `package.json` and `agent/`, not the temporary runtime snapshot. `interactiveClient` is `true` when the requesting local client is the dev TUI; check it before starting a flow that requires terminal interaction.
+
+Run source mutations inside `withSuspendedSource()`. It acquires a unique watcher lease, waits for your asynchronous callback to settle, and then releases the lease. Concurrent or nested calls cannot resume each other early, and releasing the final lease rebuilds the runtime artifacts. The callback's return value is returned, and its error is rethrown after release. If suspension cannot be acquired, the callback does not run. If the host cannot confirm release after a retry, the method throws an actionable error; restart `eve dev` before making more source changes.
+
## ChatGPT subscription models
`chatgpt()` from `eve/models/openai` serves an OpenAI model through the local Codex login and bills the ChatGPT subscription. With no argument, it selects `gpt-5.6-sol`:
diff --git a/packages/eve/package.json b/packages/eve/package.json
index a01ac1075..b95c21fd9 100644
--- a/packages/eve/package.json
+++ b/packages/eve/package.json
@@ -266,6 +266,11 @@
"import": "./dist/src/internal/programmatic-source-loader.js",
"default": "./dist/src/internal/programmatic-source-loader.js"
},
+ "./local-dev": {
+ "types": "./dist/src/public/local-dev.d.ts",
+ "import": "./dist/src/public/local-dev.js",
+ "default": "./dist/src/public/local-dev.js"
+ },
"./extension": {
"types": "./dist/src/public/extension/index.d.ts",
"import": "./dist/src/public/extension/index.js",
diff --git a/packages/eve/src/cli/dev/local-server-process.ts b/packages/eve/src/cli/dev/local-server-process.ts
index 64a5194f1..1fcca8483 100644
--- a/packages/eve/src/cli/dev/local-server-process.ts
+++ b/packages/eve/src/cli/dev/local-server-process.ts
@@ -100,7 +100,10 @@ export function createDevelopmentServer(
{
cwd: appRoot,
detached: true,
- env: { ...shellEnvironment, [EVE_DEV_ENV_FLAG]: "1" },
+ env: {
+ ...shellEnvironment,
+ [EVE_DEV_ENV_FLAG]: "1",
+ },
stdio: ["ignore", "pipe", "pipe", "ipc"],
},
);
diff --git a/packages/eve/src/cli/dev/run-interactive-ui.ts b/packages/eve/src/cli/dev/run-interactive-ui.ts
index 54b5d3e38..81691613b 100644
--- a/packages/eve/src/cli/dev/run-interactive-ui.ts
+++ b/packages/eve/src/cli/dev/run-interactive-ui.ts
@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+
import { devBootPhase, type DevBootProgressReporter } from "#internal/dev-boot-progress.js";
import {
resumeDevelopmentRuntimeArtifacts,
@@ -53,17 +55,40 @@ export async function runInteractiveDevelopmentUi(input: {
if (input.startup !== undefined) tuiInput.startup = input.startup;
if (target.kind === "local") {
tuiInput.withExclusiveTerminal = async <T>(task: () => Promise<T>): Promise<T> => {
- if (!(await suspendDevelopmentRuntimeArtifacts({ serverUrl: input.server.serverUrl }))) {
+ const leaseId = randomUUID();
+ if (
+ !(await suspendDevelopmentRuntimeArtifacts({
+ leaseId,
+ serverUrl: input.server.serverUrl,
+ }))
+ ) {
throw new Error("Could not pause the development server for integration setup.");
}
+ let outcome:
+ | { readonly error: unknown; readonly ok: false }
+ | { readonly ok: true; value: T };
try {
- return await task();
- } finally {
- await resumeDevelopmentRuntimeArtifacts({
- serverUrl: input.server.serverUrl,
- silent: true,
- });
+ outcome = { ok: true, value: await task() };
+ } catch (error) {
+ outcome = { error, ok: false };
+ }
+
+ const release = {
+ leaseId,
+ serverUrl: input.server.serverUrl,
+ silent: true,
+ } as const;
+ if (
+ (await resumeDevelopmentRuntimeArtifacts(release)) === undefined &&
+ (await resumeDevelopmentRuntimeArtifacts(release)) === undefined
+ ) {
+ throw new Error(
+ "Could not resume the eve development server after integration setup. Restart eve dev before making further source changes.",
+ outcome.ok ? undefined : { cause: outcome.error },
+ );
}
+ if (!outcome.ok) throw outcome.error;
+ return outcome.value;
};
}
diff --git a/packages/eve/src/cli/dev/tui/tui.ts b/packages/eve/src/cli/dev/tui/tui.ts
index 5467f1848..71700df71 100644
--- a/packages/eve/src/cli/dev/tui/tui.ts
+++ b/packages/eve/src/cli/dev/tui/tui.ts
@@ -155,6 +155,7 @@ export async function runDevelopmentTui(input: RunDevelopmentTuiInput): Promise<
prepared.kind === "local"
? resolveLocalDevelopmentClientOptions({
...headerOptions,
+ interactiveClient: true,
serverUrl,
token: () => resolveLinkedDevelopmentOidcToken(prepared.target.workspaceRoot),
})
diff --git a/packages/eve/src/context/container.ts b/packages/eve/src/context/container.ts
index a77878dc4..b2d509636 100644
--- a/packages/eve/src/context/container.ts
+++ b/packages/eve/src/context/container.ts
@@ -1,6 +1,7 @@
import { AsyncLocalStorage } from "node:async_hooks";
import { type ContextAccessor, type ContextKey, resolveKey } from "#context/key.js";
+import { LocalDevRequestKey, type LocalDevRequestProvenance } from "#context/keys.js";
const EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
@@ -15,6 +16,8 @@ const EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
* the serialization layer.
*/
export interface AlsContext extends ContextAccessor {
+ /** Verified local development provenance, inherited across durable execution contexts. */
+ readonly localDevRequest?: LocalDevRequestProvenance;
/** Removes a durable or step-local value from the context. */
delete<T>(key: ContextKey<T>): boolean;
/**
@@ -33,6 +36,17 @@ export class ContextContainer implements AlsContext {
private readonly _durableValues = new Map<string, unknown>();
private readonly _virtualValues = new Map<string, unknown>();
+ constructor(input?: { readonly localDevRequest?: LocalDevRequestProvenance }) {
+ const localDevRequest = input?.localDevRequest ?? contextStorage.getStore()?.localDevRequest;
+ if (localDevRequest !== undefined) {
+ this._durableValues.set(LocalDevRequestKey.name, localDevRequest);
+ }
+ }
+
+ get localDevRequest(): LocalDevRequestProvenance | undefined {
+ return this.get(LocalDevRequestKey);
+ }
+
get<T>(key: ContextKey<T>): T | undefined {
if (this._virtualValues.has(key.name)) {
return this._virtualValues.get(key.name) as T;
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index 966fc8118..cf959cd3c 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -74,6 +74,15 @@ export const InitiatorAuthKey = new ContextKey<SessionAuthContext | null>("eve.i
export const SessionIdKey = new ContextKey<string>("eve.sessionId");
export const ContinuationTokenKey = new ContextKey<string>("eve.continuationToken");
export const ChannelRequestIdKey = new ContextKey<string>("eve.channelRequestId");
+/** Parent-verified local client provenance, valid only for the current dev host secret. */
+export interface LocalDevRequestProvenance {
+ readonly address: string;
+ readonly interactiveClient: boolean;
+ readonly signature: string;
+}
+export const LocalDevRequestKey = new ContextKey<LocalDevRequestProvenance>(
+ "eve.internal.localDevRequest",
+);
/** Authored schedule whose dispatch created this session. */
export const ScheduleIdKey = new ContextKey<string>("eve.scheduleId");
export const ChannelDeliveryKey = new ContextKey<ChannelDeliveryMetadata>("eve.channelDelivery");
diff --git a/packages/eve/src/execution/dispatch-runtime-actions-shared.ts b/packages/eve/src/execution/dispatch-runtime-actions-shared.ts
index 43a705a3b..55fdac894 100644
--- a/packages/eve/src/execution/dispatch-runtime-actions-shared.ts
+++ b/packages/eve/src/execution/dispatch-runtime-actions-shared.ts
@@ -21,6 +21,7 @@ import {
ChannelInstrumentationKey,
InitiatorAuthKey,
SandboxKey,
+ type LocalDevRequestProvenance,
} from "#context/keys.js";
import { type AlsContext, ContextContainer } from "#context/container.js";
import { withContextScope } from "#context/run-step.js";
@@ -158,6 +159,7 @@ export interface PreparedRuntimeActionDispatch {
*/
readonly fanoutSize: number;
readonly initiatorAuth: Parameters<typeof buildSubagentRunInput>[0]["initiatorAuth"];
+ readonly localDevRequest?: LocalDevRequestProvenance;
readonly parentTraceContext: Parameters<typeof buildSubagentRunInput>[0]["parentTraceContext"];
readonly activityObserver?: ActivityObserverConfig & {
readonly workIdentity: ActivityWorkIdentityV1;
@@ -287,6 +289,7 @@ async function prepareActionDispatch(input: {
input.fanoutSize ??
plan.filter((entry) => entry.kind === "start" && entry.target.kind === "local").length,
initiatorAuth: ctx.get(InitiatorAuthKey) ?? null,
+ localDevRequest: ctx.localDevRequest,
parentTraceContext: readSessionTraceContext(input.serializedContext, session.sessionId),
plan,
activityObserver: resolvePreparedActivity(
@@ -581,6 +584,7 @@ export async function startSubagent(input: {
readonly currentSession: RuntimeSession;
readonly fanoutSize: number;
readonly initiatorAuth: Parameters<typeof buildSubagentRunInput>[0]["initiatorAuth"];
+ readonly localDevRequest?: LocalDevRequestProvenance;
readonly parentContinuationToken: string | undefined;
readonly parentTraceContext: Parameters<typeof buildSubagentRunInput>[0]["parentTraceContext"];
readonly activityObserver?: ActivityObserverConfig & {
@@ -613,6 +617,7 @@ export async function startSubagent(input: {
dynamicSubagentAgentConfig: input.target.dynamicSubagentAgentConfig,
fanoutSize: input.fanoutSize,
initiatorAuth: input.initiatorAuth,
+ localDevRequest: input.localDevRequest,
parentContinuationToken: input.parentContinuationToken,
parentTraceContext,
activityObserver: input.activityObserver,
diff --git a/packages/eve/src/execution/dispatch-runtime-actions-step.integration.test.ts b/packages/eve/src/execution/dispatch-runtime-actions-step.integration.test.ts
index aac2dfcf9..499c073f2 100644
--- a/packages/eve/src/execution/dispatch-runtime-actions-step.integration.test.ts
+++ b/packages/eve/src/execution/dispatch-runtime-actions-step.integration.test.ts
@@ -31,6 +31,7 @@ import {
CapabilitiesKey,
ChannelInstrumentationKey,
InitiatorAuthKey,
+ type LocalDevRequestProvenance,
SessionIdKey,
SessionKey,
} from "#context/keys.js";
@@ -319,6 +320,29 @@ describe("dispatchRuntimeActionsStep child starts", () => {
expect(writes).toHaveLength(1);
});
+ it("carries verified local-dev provenance into a local child start", async () => {
+ const session = createStartSession({ kind: "local" });
+ const localDevRequest: LocalDevRequestProvenance = {
+ address: "127.0.0.1",
+ interactiveClient: true,
+ signature: "parent-signed",
+ };
+ installContext(session, undefined, false, null, localDevRequest);
+ mocks.createSession.mockImplementation(async () => {
+ expect(loadContext().localDevRequest).toEqual(localDevRequest);
+ return { sessionId: CHILD_SESSION_ID };
+ });
+
+ await dispatchRuntimeActionsStep({
+ parentContinuationToken: "turn-inbox",
+ parentWritable: createWritable(),
+ serializedContext: {},
+ sessionState: BASE_STATE,
+ });
+
+ expect(mocks.createSession).toHaveBeenCalledOnce();
+ });
+
it("opens a shared parent sandbox with session context and durable backend tags", async () => {
const session = createStartSession({ kind: "local" });
const observedSessionIds: string[] = [];
@@ -1287,6 +1311,7 @@ function installContext(
remote?: { readonly definition: unknown; readonly nodeId: string },
tasks = false,
auth: SessionAuthContext | null = null,
+ localDevRequest?: LocalDevRequestProvenance,
): void {
const subagentsByNodeId = new Map<string, { definition: unknown }>();
if (remote !== undefined) {
@@ -1316,6 +1341,9 @@ function installContext(
[ChannelKey, ADAPTER],
]);
mocks.deserializeContext.mockResolvedValue({
+ get localDevRequest() {
+ return localDevRequest;
+ },
get: (key: unknown) => values.get(key),
require: (key: unknown) => {
if (!values.has(key)) throw new Error("missing context key");
diff --git a/packages/eve/src/execution/dispatch-runtime-actions-step.ts b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
index e31464520..2b9a3b242 100644
--- a/packages/eve/src/execution/dispatch-runtime-actions-step.ts
+++ b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
@@ -103,6 +103,7 @@ export async function dispatchRuntimeActionsStep(
currentSession: nextSession,
fanoutSize: prepared.fanoutSize,
initiatorAuth: prepared.initiatorAuth,
+ localDevRequest: prepared.localDevRequest,
parentContinuationToken: input.parentContinuationToken,
parentTraceContext: prepared.parentTraceContext,
activityObserver: prepared.activityObserver,
diff --git a/packages/eve/src/execution/subagent-start-local.ts b/packages/eve/src/execution/subagent-start-local.ts
index 7b9fc7a04..ca03b2619 100644
--- a/packages/eve/src/execution/subagent-start-local.ts
+++ b/packages/eve/src/execution/subagent-start-local.ts
@@ -1,4 +1,6 @@
import type { DispatchOutcome, RuntimeSession } from "#execution/agent-handle-dispatch.js";
+import { ContextContainer, contextStorage } from "#context/container.js";
+import type { LocalDevRequestProvenance } from "#context/keys.js";
import { deriveChildActivityObserverConfig } from "#execution/activity-work.js";
import { mintStartOperation } from "#execution/dispatch-start-operation.js";
import { isRuntimeSessionOwnershipConflictError } from "#execution/runtime-errors.js";
@@ -34,6 +36,7 @@ export async function startLocalSubagent(input: {
readonly dynamicSubagentAgentConfig?: DynamicSubagentAgentConfig;
readonly fanoutSize: number;
readonly initiatorAuth: Parameters<typeof buildSubagentRunInput>[0]["initiatorAuth"];
+ readonly localDevRequest?: LocalDevRequestProvenance;
readonly parentContinuationToken: string | undefined;
readonly parentTraceContext: Parameters<typeof buildSubagentRunInput>[0]["parentTraceContext"];
readonly activityObserver?: Parameters<typeof buildSubagentRunInput>[0]["activityObserver"];
@@ -94,7 +97,10 @@ export async function startLocalSubagent(input: {
let childSessionId: string;
try {
- const handle = await childRuntime.createSession(runInput);
+ const handle = await contextStorage.run(
+ new ContextContainer({ localDevRequest: input.localDevRequest }),
+ () => childRuntime.createSession(runInput),
+ );
childSessionId = handle.sessionId;
} catch (error) {
if (!isRuntimeSessionOwnershipConflictError(error)) {
diff --git a/packages/eve/src/execution/tasks/parent/dispatch-task-step.ts b/packages/eve/src/execution/tasks/parent/dispatch-task-step.ts
index 48e0d6d29..20591012b 100644
--- a/packages/eve/src/execution/tasks/parent/dispatch-task-step.ts
+++ b/packages/eve/src/execution/tasks/parent/dispatch-task-step.ts
@@ -179,6 +179,7 @@ export async function dispatchTaskStep(
currentSession: nextSession,
fanoutSize: prepared.fanoutSize,
initiatorAuth: prepared.initiatorAuth,
+ localDevRequest: prepared.localDevRequest,
parentContinuationToken: delegated.taskInboxToken,
parentTraceContext: prepared.parentTraceContext,
activityObserver: prepared.activityObserver,
diff --git a/packages/eve/src/execution/tools/subagent/local.ts b/packages/eve/src/execution/tools/subagent/local.ts
index 4219a2e55..82edccc0f 100644
--- a/packages/eve/src/execution/tools/subagent/local.ts
+++ b/packages/eve/src/execution/tools/subagent/local.ts
@@ -250,6 +250,7 @@ async function dispatchSubagent(input: SubagentDispatchInput): Promise<SubagentD
currentSession: prepared.session,
fanoutSize: prepared.fanoutSize,
initiatorAuth: prepared.initiatorAuth,
+ localDevRequest: prepared.localDevRequest,
parentContinuationToken: input.task.taskInboxToken,
parentTraceContext: prepared.parentTraceContext,
activityObserver: prepared.activityObserver,
diff --git a/packages/eve/src/internal/nitro/dev-client-address.ts b/packages/eve/src/internal/nitro/dev-client-address.ts
index 0f3b5b21f..e4d0556fc 100644
--- a/packages/eve/src/internal/nitro/dev-client-address.ts
+++ b/packages/eve/src/internal/nitro/dev-client-address.ts
@@ -45,16 +45,26 @@ export function readTrustedDevelopmentClientAddress(
): string | undefined {
const address = headers.get(DEVELOPMENT_CLIENT_ADDRESS_HEADER);
const signature = headers.get(DEVELOPMENT_CLIENT_ADDRESS_SIGNATURE_HEADER);
- if (
- address === null ||
- signature === null ||
- secret === undefined ||
- secret.length === 0 ||
- !timingSafeEqualStrings(signature, signClientAddress(address, secret))
- ) {
- return undefined;
- }
- return address;
+ return address !== null &&
+ signature !== null &&
+ isTrustedDevelopmentClientAddress(address, signature, secret)
+ ? address
+ : undefined;
+}
+
+/** Verifies parent-stamped client provenance carried beyond the original request. */
+export function isTrustedDevelopmentClientAddress(
+ address: string,
+ signature: string,
+ secret: string | undefined,
+): boolean {
+ return (
+ address.length > 0 &&
+ signature.length > 0 &&
+ secret !== undefined &&
+ secret.length > 0 &&
+ timingSafeEqualStrings(signature, signClientAddress(address, secret))
+ );
}
/**
diff --git a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
index 780a40371..562dcf7e4 100644
--- a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.scenario.test.ts
@@ -107,12 +107,12 @@ describe("startAuthoredSourceWatcher", () => {
const watcher = await startAuthoredSourceWatcher({ coordinator, preparedHost: host });
try {
- await watcher.suspend();
+ await watcher.suspend("setup");
mockedWatcher.emit("change", join(host.appRoot, "package.json"));
await vi.advanceTimersByTimeAsync(200);
expect(coordinator.rebuild).not.toHaveBeenCalled();
- await watcher.resume();
+ await watcher.resume("setup");
expect(coordinator.rebuild).toHaveBeenCalledOnce();
expect(coordinator.rebuild).toHaveBeenCalledWith({
changedPaths: [join(host.appRoot, "package.json")],
@@ -122,6 +122,29 @@ describe("startAuthoredSourceWatcher", () => {
}
});
+ it("keeps nested holders suspended and releases each lease idempotently", async () => {
+ const host = await createPreparedHost();
+ const coordinator = createCoordinator(host);
+ const watcher = await startAuthoredSourceWatcher({ coordinator, preparedHost: host });
+
+ try {
+ await watcher.suspend("first");
+ await watcher.suspend("second");
+ await watcher.suspend("second");
+
+ await watcher.resume("first");
+ expect(coordinator.rebuild).not.toHaveBeenCalled();
+
+ await watcher.resume("second");
+ expect(coordinator.rebuild).toHaveBeenCalledOnce();
+
+ await watcher.resume("second");
+ expect(coordinator.rebuild).toHaveBeenCalledOnce();
+ } finally {
+ await watcher.close();
+ }
+ });
+
it("ignores generated directories while watching authored roots", async () => {
const host = await createPreparedHost();
const watcher = await startAuthoredSourceWatcher({
diff --git a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.ts b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.ts
index 8edba3543..1afc5fec1 100644
--- a/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.ts
+++ b/packages/eve/src/internal/nitro/host/dev-authored-source-watcher.ts
@@ -46,8 +46,8 @@ export interface AuthoredSourceWatcherHandle {
close(): Promise<void>;
flush(): Promise<void>;
rebuild(): Promise<void>;
- suspend(): Promise<void>;
- resume(options?: { silent?: boolean }): Promise<void>;
+ suspend(leaseId: string): Promise<void>;
+ resume(leaseId: string, options?: { silent?: boolean }): Promise<void>;
}
/**
@@ -65,7 +65,7 @@ export async function startAuthoredSourceWatcher(input: {
let queue: Promise<void> = Promise.resolve();
let debounceTimer: NodeJS.Timeout | undefined;
let isWatcherReady = false;
- let suspensionCount = 0;
+ const suspensionLeases = new Set<string>();
const pendingEvents = new Map<string, WatcherChangeEvent>();
const pendingChangedPaths = new Set<string>();
const initialWatchPaths = await resolveAuthoredWatchPaths(currentHost);
@@ -83,7 +83,7 @@ export async function startAuthoredSourceWatcher(input: {
const watcherReady = waitForWatcherReady(watcher);
const rebuild = async (force: boolean, silent = false) => {
- if (closed || suspensionCount > 0) {
+ if (closed || suspensionLeases.size > 0) {
return;
}
@@ -180,18 +180,18 @@ export async function startAuthoredSourceWatcher(input: {
},
flush,
rebuild: forceRebuild,
- async suspend() {
- suspensionCount += 1;
+ async suspend(leaseId) {
+ if (suspensionLeases.has(leaseId)) return;
+ suspensionLeases.add(leaseId);
if (debounceTimer !== undefined) {
clearTimeout(debounceTimer);
debounceTimer = undefined;
}
await queue;
},
- async resume(options) {
- if (suspensionCount === 0) return;
- suspensionCount -= 1;
- if (suspensionCount === 0) await forceRebuild(options?.silent);
+ async resume(leaseId, options) {
+ if (!suspensionLeases.delete(leaseId)) return;
+ if (suspensionLeases.size === 0) await forceRebuild(options?.silent);
},
};
}
diff --git a/packages/eve/src/internal/nitro/host/start-development-server.test.ts b/packages/eve/src/internal/nitro/host/start-development-server.test.ts
index fef14764a..e6a4cdefe 100644
--- a/packages/eve/src/internal/nitro/host/start-development-server.test.ts
+++ b/packages/eve/src/internal/nitro/host/start-development-server.test.ts
@@ -603,6 +603,33 @@ describe("createDevelopmentServer", () => {
await server.close();
});
+ it("passes an acquisition lease through suspend and resume control requests", async () => {
+ const startDevelopmentServer = await loadStartDevelopmentServer();
+ const server = await startDevelopmentServer("/tmp/eve-test");
+
+ await callControlHandler(
+ "http://localhost/eve/v1/dev/runtime-artifacts/suspend?lease=install-1",
+ { method: "POST" },
+ );
+ await callControlHandler(
+ "http://localhost/eve/v1/dev/runtime-artifacts/resume?lease=install-1",
+ { method: "POST" },
+ );
+
+ expect(mocks.authoredSourceWatcher.suspend).toHaveBeenCalledWith("install-1");
+ expect(mocks.authoredSourceWatcher.resume).toHaveBeenCalledWith("install-1", {
+ silent: false,
+ });
+
+ const missingLease = await callControlHandler(
+ "http://localhost/eve/v1/dev/runtime-artifacts/suspend",
+ { method: "POST" },
+ );
+ expect(missingLease?.status).toBe(400);
+
+ await server.close();
+ });
+
it("registers a host-owned runtime rebuild handler that forces the live watcher", async () => {
const startDevelopmentServer = await loadStartDevelopmentServer();
const server = await startDevelopmentServer("/tmp/eve-test");
diff --git a/packages/eve/src/internal/nitro/host/start-development-server.ts b/packages/eve/src/internal/nitro/host/start-development-server.ts
index 223dcb936..21fd3c34a 100644
--- a/packages/eve/src/internal/nitro/host/start-development-server.ts
+++ b/packages/eve/src/internal/nitro/host/start-development-server.ts
@@ -44,6 +44,7 @@ import {
DEFAULT_DEVELOPMENT_SERVER_PORT,
MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS,
} from "#internal/nitro/host/ports.js";
+import { installLocalDevCapabilityEnvironment } from "#runtime/local-dev-capability.js";
import { detectPackageManager, type PackageManagerKind } from "#setup/package-manager.js";
import { eveDevArguments } from "#setup/primitives/index.js";
import { devBootPhase } from "#internal/dev-boot-progress.js";
@@ -232,12 +233,16 @@ function addDevelopmentControlHandler(input: {
if (watcher === undefined) {
return Response.json({ error: "The development server is still starting." }, { status: 503 });
}
+ const leaseId = url.searchParams.get("lease");
+ if ((isSuspendRequest || isResumeRequest) && (leaseId === null || leaseId.length === 0)) {
+ return Response.json({ error: "A suspension lease is required." }, { status: 400 });
+ }
if (isSuspendRequest) {
- await watcher.suspend();
+ await watcher.suspend(leaseId!);
return Response.json({ suspended: true });
}
if (isResumeRequest) {
- await watcher.resume({ silent: url.searchParams.get("silent") === "1" });
+ await watcher.resume(leaseId!, { silent: url.searchParams.get("silent") === "1" });
return handleDevRuntimeArtifactsRequest({ appRoot: input.appRoot });
}
if (url.searchParams.get("force") === "1") {
@@ -408,6 +413,7 @@ async function startNitroDevelopmentServer(
process.env[EVE_DEVELOPMENT_SANDBOX_RUN_ID_ENV] = developmentSandboxRunId;
let nitro: Nitro | undefined;
let devServer: NitroDevelopmentServer | undefined;
+ let restoreLocalDevCapabilityEnvironment: (() => void) | undefined;
let restoreWorkflowLocalQueueEnvironment: (() => void) | undefined;
let restoreWorkflowTransportEnvironment: (() => void) | undefined;
let workflowWorld: ParentDevelopmentWorkflowWorld | undefined;
@@ -479,6 +485,12 @@ async function startNitroDevelopmentServer(
const serverUrl = normalizeDevelopmentServerClientUrl(server.url);
restoreWorkflowLocalQueueEnvironment = installWorkflowLocalQueueEnvironment(serverUrl);
+ // Published before the first worker is created, so every runtime generation
+ // inherits it: workers copy `process.env` at construction.
+ restoreLocalDevCapabilityEnvironment = installLocalDevCapabilityEnvironment({
+ appRoot: project.appRoot,
+ serverUrl,
+ });
await devBootPhase(
"building dev bundle",
async () => {
@@ -535,6 +547,7 @@ async function startNitroDevelopmentServer(
const devServerOnClose = devServer;
const workflowWorldOnClose = workflowWorld;
const restoreWorkflowTransportEnvironmentOnClose = restoreWorkflowTransportEnvironment;
+ const restoreLocalDevCapabilityEnvironmentOnClose = restoreLocalDevCapabilityEnvironment;
let closePromise: Promise<void> | undefined;
const close = (): Promise<void> => {
closePromise ??= (async () => {
@@ -558,6 +571,7 @@ async function startNitroDevelopmentServer(
} finally {
restoreWorkflowLocalQueueEnvironmentOnClose();
restoreWorkflowTransportEnvironmentOnClose?.();
+ restoreLocalDevCapabilityEnvironmentOnClose?.();
restoreDevelopmentSandboxRunId(previousDevelopmentSandboxRunId);
}
})();
@@ -593,6 +607,7 @@ async function startNitroDevelopmentServer(
}
restoreWorkflowLocalQueueEnvironment?.();
restoreWorkflowTransportEnvironment?.();
+ restoreLocalDevCapabilityEnvironment?.();
if (cleanup.listenerClosed) {
await state.remove().catch(() => {});
}
diff --git a/packages/eve/src/internal/nitro/routes/channel-dispatch.ts b/packages/eve/src/internal/nitro/routes/channel-dispatch.ts
index d51fab0c5..f4d45a184 100644
--- a/packages/eve/src/internal/nitro/routes/channel-dispatch.ts
+++ b/packages/eve/src/internal/nitro/routes/channel-dispatch.ts
@@ -22,6 +22,7 @@ import { traceChannelRequest } from "#internal/nitro/routes/channel-request-inst
import { resolveNitroChannelRuntimeBundle } from "#internal/nitro/routes/runtime-stack.js";
import { readVercelProjectLink } from "#internal/vercel/project-link.js";
import { withVercelOidcProjectResolver } from "#channel/auth/vercel-oidc-project.js";
+import { withLocalDevRequestScope } from "#runtime/local-dev-capability.js";
const log = createLogger("channel.dispatch");
@@ -187,17 +188,21 @@ async function withDevelopmentVercelOidcContext<T>(
return await callback();
}
- return await withVercelOidcProjectResolver(
- {
- request,
- resolveCurrentProject: async () => {
- const link = await readVercelProjectLink(config.appRoot);
- return link === undefined
- ? undefined
- : { environment: "development", projectId: link.projectId };
- },
- },
- callback,
+ return await withLocalDevRequestScope(
+ request,
+ async () =>
+ await withVercelOidcProjectResolver(
+ {
+ request,
+ resolveCurrentProject: async () => {
+ const link = await readVercelProjectLink(config.appRoot);
+ return link === undefined
+ ? undefined
+ : { environment: "development", projectId: link.projectId };
+ },
+ },
+ callback,
+ ),
);
}
diff --git a/packages/eve/src/protocol/routes.ts b/packages/eve/src/protocol/routes.ts
index 1119342cf..d85aa8138 100644
--- a/packages/eve/src/protocol/routes.ts
+++ b/packages/eve/src/protocol/routes.ts
@@ -76,10 +76,10 @@ export const EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH = `${EVE_ROUTE_PREFIX}/dev/run
*/
export const EVE_DEV_RUNTIME_ARTIFACTS_REBUILD_ROUTE_PATH = `${EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH}/rebuild`;
-/** Dev-only route that pauses authored-source rebuilding while a setup subprocess owns the terminal. */
+/** Dev-only route that acquires an idempotent authored-source suspension lease. */
export const EVE_DEV_RUNTIME_ARTIFACTS_SUSPEND_ROUTE_PATH = `${EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH}/suspend`;
-/** Dev-only route that resumes authored-source rebuilding after setup subprocess completion. */
+/** Dev-only route that idempotently releases one authored-source suspension lease. */
export const EVE_DEV_RUNTIME_ARTIFACTS_RESUME_ROUTE_PATH = `${EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH}/resume`;
/**
diff --git a/packages/eve/src/public/local-dev.ts b/packages/eve/src/public/local-dev.ts
new file mode 100644
index 000000000..9d17a7c62
--- /dev/null
+++ b/packages/eve/src/public/local-dev.ts
@@ -0,0 +1,9 @@
+/**
+ * Runtime capabilities available to authored code handling a same-machine
+ * request to `eve dev`.
+ *
+ * A deployed runtime and a client attached to a development server over the
+ * network receive `undefined`. A local TUI attached to an existing headless
+ * server receives the capability because authorization follows its requests.
+ */
+export { getLocalDevCapability, type LocalDevCapability } from "#runtime/local-dev-capability.js";
diff --git a/packages/eve/src/runtime/local-dev-capability.test.ts b/packages/eve/src/runtime/local-dev-capability.test.ts
new file mode 100644
index 000000000..e4e93be66
--- /dev/null
+++ b/packages/eve/src/runtime/local-dev-capability.test.ts
@@ -0,0 +1,257 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+ LOCAL_DEV_INTERACTIVE_CLIENT_HEADER,
+ getLocalDevCapability,
+ installLocalDevCapabilityEnvironment,
+ withLocalDevRequestScope,
+} from "#runtime/local-dev-capability.js";
+import { stampDevelopmentClientAddress } from "#internal/nitro/dev-client-address.js";
+import { DEVELOPMENT_WORKFLOW_SECRET_ENV } from "#internal/workflow/development-world-protocol.js";
+import { ContextContainer, contextStorage } from "#context/container.js";
+import { deserializeContext, serializeContext } from "#context/serialize.js";
+
+const APP_ROOT = "/workspace/agent";
+const SERVER_URL = "http://127.0.0.1:3000";
+
+function environment(): Record<string, string> {
+ return {
+ EVE_DEV_APP_ROOT: APP_ROOT,
+ EVE_DEV_CONTROL_URL: SERVER_URL,
+ };
+}
+
+async function withClient<T>(
+ address: string,
+ callback: () => Promise<T> | T,
+ interactiveClient = false,
+): Promise<T> {
+ const secret = "test-secret";
+ const headers = new Headers();
+ stampDevelopmentClientAddress(headers, address, secret);
+ if (interactiveClient) headers.set(LOCAL_DEV_INTERACTIVE_CLIENT_HEADER, "1");
+ const previousSecret = process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV];
+ process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV] = secret;
+ try {
+ return await withLocalDevRequestScope(
+ new Request(SERVER_URL, { headers }),
+ async () => await callback(),
+ );
+ } finally {
+ if (previousSecret === undefined) delete process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV];
+ else process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV] = previousSecret;
+ }
+}
+
+describe("installLocalDevCapabilityEnvironment", () => {
+ const saved = { ...process.env };
+
+ afterEach(() => {
+ process.env = { ...saved };
+ });
+
+ it("publishes the authored app root and control origin, and restores them", () => {
+ delete process.env.EVE_DEV_APP_ROOT;
+ delete process.env.EVE_DEV_CONTROL_URL;
+
+ const restore = installLocalDevCapabilityEnvironment({
+ appRoot: APP_ROOT,
+ serverUrl: `${SERVER_URL}/`,
+ });
+
+ expect(process.env.EVE_DEV_APP_ROOT).toBe(APP_ROOT);
+ expect(process.env.EVE_DEV_CONTROL_URL).toBe(SERVER_URL);
+
+ restore();
+
+ expect(process.env.EVE_DEV_APP_ROOT).toBeUndefined();
+ expect(process.env.EVE_DEV_CONTROL_URL).toBeUndefined();
+ });
+});
+
+describe("getLocalDevCapability", () => {
+ it("is absent without both the dev environment and a local request", async () => {
+ expect(getLocalDevCapability(environment())).toBeUndefined();
+ await withClient("127.0.0.1", () => {
+ expect(getLocalDevCapability({})).toBeUndefined();
+ expect(getLocalDevCapability({ EVE_DEV_APP_ROOT: APP_ROOT })).toBeUndefined();
+ expect(getLocalDevCapability({ EVE_DEV_CONTROL_URL: SERVER_URL })).toBeUndefined();
+ });
+ });
+
+ it("is scoped to a parent-verified loopback client", async () => {
+ await withClient("127.0.0.1", () => {
+ expect(getLocalDevCapability(environment())?.appRoot).toBe(APP_ROOT);
+ });
+ await withClient("203.0.113.7", () => {
+ expect(getLocalDevCapability(environment())).toBeUndefined();
+ });
+ });
+
+ it("follows the request into nested authored execution contexts", async () => {
+ await withClient("127.0.0.1", async () => {
+ const nestedContext = new ContextContainer();
+ await contextStorage.run(nestedContext, () => {
+ expect(getLocalDevCapability(environment())?.appRoot).toBe(APP_ROOT);
+ });
+ });
+ });
+
+ it("survives durable workflow context serialization", async () => {
+ await withClient(
+ "127.0.0.1",
+ async () => {
+ const active = contextStorage.getStore();
+ expect(active).toBeDefined();
+ const restored = await deserializeContext(serializeContext(active!));
+
+ await contextStorage.run(restored, () => {
+ expect(getLocalDevCapability(environment())).toMatchObject({
+ appRoot: APP_ROOT,
+ interactiveClient: true,
+ });
+ });
+ },
+ true,
+ );
+ });
+
+ it("invalidates durable provenance when the dev host secret rotates", async () => {
+ await withClient("127.0.0.1", async () => {
+ const active = contextStorage.getStore();
+ expect(active).toBeDefined();
+ const restored = await deserializeContext(serializeContext(active!));
+ process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV] = "replacement-secret";
+
+ await contextStorage.run(restored, () => {
+ expect(getLocalDevCapability(environment())).toBeUndefined();
+ });
+ });
+ });
+
+ it("rejects tampered durable local provenance", async () => {
+ await withClient("127.0.0.1", async () => {
+ const active = contextStorage.getStore();
+ expect(active).toBeDefined();
+ const serialized = serializeContext(active!);
+ serialized["eve.internal.localDevRequest"] = {
+ address: "127.0.0.1",
+ interactiveClient: true,
+ signature: "forged",
+ };
+ const restored = await deserializeContext(serialized);
+
+ await contextStorage.run(restored, () => {
+ expect(getLocalDevCapability(environment())).toBeUndefined();
+ });
+ });
+ });
+
+ it("reports whether the requesting local client is interactive", async () => {
+ await withClient("::1", () => {
+ expect(getLocalDevCapability(environment())?.interactiveClient).toBe(false);
+ });
+ await withClient(
+ "::1",
+ () => {
+ expect(getLocalDevCapability(environment())?.interactiveClient).toBe(true);
+ },
+ true,
+ );
+ });
+});
+
+describe("withSuspendedSource", () => {
+ const fetchMock = vi.fn();
+
+ beforeEach(() => {
+ fetchMock.mockReset();
+ vi.stubGlobal("fetch", fetchMock);
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ function requestedPaths(): string[] {
+ return fetchMock.mock.calls.map((call) => new URL(String(call[0])).pathname);
+ }
+
+ it("suspends the watcher around the task and resumes it afterwards", async () => {
+ fetchMock.mockResolvedValue(new Response(JSON.stringify({ revision: "r2" }), { status: 200 }));
+ const order: string[] = [];
+ const result = await withClient(
+ "127.0.0.1",
+ async () =>
+ await getLocalDevCapability(environment())?.withSuspendedSource(async () => {
+ order.push(...requestedPaths());
+ return "installed";
+ }),
+ );
+
+ expect(result).toBe("installed");
+ expect(order).toEqual(["/eve/v1/dev/runtime-artifacts/suspend"]);
+ expect(requestedPaths()).toEqual([
+ "/eve/v1/dev/runtime-artifacts/suspend",
+ "/eve/v1/dev/runtime-artifacts/resume",
+ ]);
+ });
+
+ it("resumes even when the task throws", async () => {
+ fetchMock.mockResolvedValue(new Response(JSON.stringify({ revision: "r2" }), { status: 200 }));
+ await expect(
+ withClient(
+ "127.0.0.1",
+ async () =>
+ await getLocalDevCapability(environment())?.withSuspendedSource(async () => {
+ throw new Error("install failed");
+ }),
+ ),
+ ).rejects.toThrow("install failed");
+
+ expect(requestedPaths()).toEqual([
+ "/eve/v1/dev/runtime-artifacts/suspend",
+ "/eve/v1/dev/runtime-artifacts/resume",
+ ]);
+ });
+
+ it("refuses to run the task when the watcher cannot be suspended", async () => {
+ fetchMock.mockResolvedValue(new Response(null, { status: 503 }));
+ const task = vi.fn();
+
+ await expect(
+ withClient(
+ "127.0.0.1",
+ async () => await getLocalDevCapability(environment())?.withSuspendedSource(task),
+ ),
+ ).rejects.toThrow(/Could not pause the eve development server/u);
+ expect(task).not.toHaveBeenCalled();
+ });
+
+ it("retries the same lease when the first resume request does not reach the host", async () => {
+ let resumeCalls = 0;
+ fetchMock.mockImplementation((input: string | URL) => {
+ const { pathname } = new URL(String(input));
+ if (pathname.endsWith("/resume") && resumeCalls++ === 0) {
+ return Promise.reject(new Error("connection reset"));
+ }
+ return Promise.resolve(new Response(JSON.stringify({ revision: "r2" }), { status: 200 }));
+ });
+
+ await withClient(
+ "127.0.0.1",
+ async () =>
+ await getLocalDevCapability(environment())?.withSuspendedSource(async () => undefined),
+ );
+
+ expect(requestedPaths()).toEqual([
+ "/eve/v1/dev/runtime-artifacts/suspend",
+ "/eve/v1/dev/runtime-artifacts/resume",
+ "/eve/v1/dev/runtime-artifacts/resume",
+ ]);
+ const leases = fetchMock.mock.calls.map((call) =>
+ new URL(String(call[0])).searchParams.get("lease"),
+ );
+ expect(new Set(leases).size).toBe(1);
+ });
+});
diff --git a/packages/eve/src/runtime/local-dev-capability.ts b/packages/eve/src/runtime/local-dev-capability.ts
new file mode 100644
index 000000000..9d96e84a2
--- /dev/null
+++ b/packages/eve/src/runtime/local-dev-capability.ts
@@ -0,0 +1,184 @@
+import { randomUUID } from "node:crypto";
+
+import {
+ resumeDevelopmentRuntimeArtifacts,
+ suspendDevelopmentRuntimeArtifacts,
+} from "#services/dev-client/runtime-artifacts.js";
+import {
+ DEVELOPMENT_CLIENT_ADDRESS_SIGNATURE_HEADER,
+ isTrustedDevelopmentClientAddress,
+ readTrustedDevelopmentClientAddress,
+} from "#internal/nitro/dev-client-address.js";
+import { DEVELOPMENT_WORKFLOW_SECRET_ENV } from "#internal/workflow/development-world-protocol.js";
+import { isLoopbackHostname } from "#shared/network-address.js";
+import { ContextContainer, contextStorage } from "#context/container.js";
+
+/**
+ * Authored application root, published by the `eve dev` host that owns the
+ * authored-source watcher.
+ *
+ * The runtime's own `appRoot` can point at an immutable development snapshot
+ * (see `runtime/compiled-artifacts-source.ts`), so a tool that writes to it
+ * mutates a directory that is about to be discarded. This variable always names
+ * the directory the developer authored.
+ */
+const LOCAL_DEV_APP_ROOT_ENV = "EVE_DEV_APP_ROOT";
+/** Origin of the dev host's control plane, which owns the watcher handle. */
+const LOCAL_DEV_CONTROL_URL_ENV = "EVE_DEV_CONTROL_URL";
+export const LOCAL_DEV_INTERACTIVE_CLIENT_HEADER = "x-eve-dev-interactive-client";
+
+/**
+ * Capabilities available to authored code in an execution initiated by a
+ * same-machine request to `eve dev`.
+ *
+ * Absence is the signal, not a disabled flag: a deployed runtime has no
+ * authored tree to mutate or watcher to pause, and a request from a remote
+ * client is not authorized to mutate the server's authored tree.
+ * {@link getLocalDevCapability} returns `undefined` in both cases.
+ */
+export interface LocalDevCapability {
+ /**
+ * Absolute path of the authored application root — the directory holding
+ * `package.json` and the authored `agent/` tree, never a runtime snapshot.
+ */
+ readonly appRoot: string;
+ /**
+ * Whether the requesting client is the dev TUI and can therefore run a flow
+ * that asks questions in its terminal.
+ */
+ readonly interactiveClient: boolean;
+ /**
+ * Runs `task` with the authored-source watcher paused, then resumes it.
+ *
+ * Each suspension has an idempotent lease, so concurrent holders cannot
+ * resume each other early; the final release rebuilds authored
+ * artifacts instead of waiting for the watcher's change debounce.
+ */
+ withSuspendedSource<T>(task: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Publishes the local dev capability to the runtime for one dev server.
+ *
+ * Returns a restore function that reinstates the previous values, matching the
+ * other environment installers the dev host tears down on close.
+ */
+export function installLocalDevCapabilityEnvironment(input: {
+ readonly appRoot: string;
+ readonly serverUrl: string;
+}): () => void {
+ const previousAppRoot = process.env[LOCAL_DEV_APP_ROOT_ENV];
+ const previousControlUrl = process.env[LOCAL_DEV_CONTROL_URL_ENV];
+ process.env[LOCAL_DEV_APP_ROOT_ENV] = input.appRoot;
+ process.env[LOCAL_DEV_CONTROL_URL_ENV] = new URL(input.serverUrl).origin;
+ return () => {
+ restore(LOCAL_DEV_APP_ROOT_ENV, previousAppRoot);
+ restore(LOCAL_DEV_CONTROL_URL_ENV, previousControlUrl);
+ };
+}
+
+/**
+ * Seeds durable local-dev provenance only when the parent host signed a
+ * loopback peer address. Public address headers cannot grant access.
+ */
+export async function withLocalDevRequestScope<T>(
+ request: Request,
+ callback: () => Promise<T>,
+): Promise<T> {
+ const secret = process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV];
+ const address = readTrustedDevelopmentClientAddress(request.headers, secret);
+ const signature = request.headers.get(DEVELOPMENT_CLIENT_ADDRESS_SIGNATURE_HEADER);
+ if (address === undefined || signature === null || !isLoopbackHostname(address)) {
+ return await callback();
+ }
+
+ return await contextStorage.run(
+ new ContextContainer({
+ localDevRequest: {
+ address,
+ interactiveClient: request.headers.get(LOCAL_DEV_INTERACTIVE_CLIENT_HEADER) === "1",
+ signature,
+ },
+ }),
+ callback,
+ );
+}
+
+/**
+ * Resolves the local dev capability, or `undefined` outside an execution
+ * initiated by an authorized local request to `eve dev`.
+ *
+ * This is deliberately not a {@link import("#public/definitions/tool.js").ToolContext}
+ * field: both values are meaningless in a deployed runtime, and a capability
+ * that cannot exist there should be absent from the type rather than present
+ * and undefined.
+ */
+export function getLocalDevCapability(
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+): LocalDevCapability | undefined {
+ const appRoot = environment[LOCAL_DEV_APP_ROOT_ENV];
+ const controlUrl = environment[LOCAL_DEV_CONTROL_URL_ENV];
+ const requestScope = contextStorage.getStore()?.localDevRequest;
+ if (
+ requestScope === undefined ||
+ typeof requestScope.address !== "string" ||
+ typeof requestScope.signature !== "string" ||
+ typeof requestScope.interactiveClient !== "boolean" ||
+ !isLoopbackHostname(requestScope.address) ||
+ !isTrustedDevelopmentClientAddress(
+ requestScope.address,
+ requestScope.signature,
+ process.env[DEVELOPMENT_WORKFLOW_SECRET_ENV],
+ ) ||
+ appRoot === undefined ||
+ appRoot === "" ||
+ controlUrl === undefined ||
+ controlUrl === ""
+ ) {
+ return undefined;
+ }
+
+ return {
+ appRoot,
+ interactiveClient: requestScope.interactiveClient,
+ async withSuspendedSource<T>(task: () => Promise<T>): Promise<T> {
+ const leaseId = randomUUID();
+ if (!(await suspendDevelopmentRuntimeArtifacts({ leaseId, serverUrl: controlUrl }))) {
+ throw new Error(
+ "Could not pause the eve development server. Its authored-source watcher must be suspended before the authored tree is modified.",
+ );
+ }
+ let outcome:
+ | { readonly error: unknown; readonly ok: false }
+ | { readonly ok: true; value: T };
+ try {
+ outcome = { ok: true, value: await task() };
+ } catch (error) {
+ outcome = { error, ok: false };
+ }
+
+ // Release is keyed by this acquisition, so retrying after a lost
+ // response cannot release another concurrent holder.
+ if (
+ (await resumeDevelopmentRuntimeArtifacts({ leaseId, serverUrl: controlUrl })) ===
+ undefined &&
+ (await resumeDevelopmentRuntimeArtifacts({ leaseId, serverUrl: controlUrl })) === undefined
+ ) {
+ throw new Error(
+ "Could not resume the eve development server after modifying the authored tree. Restart eve dev before making further source changes.",
+ outcome.ok ? undefined : { cause: outcome.error },
+ );
+ }
+ if (!outcome.ok) throw outcome.error;
+ return outcome.value;
+ },
+ };
+}
+
+function restore(name: string, previous: string | undefined): void {
+ if (previous === undefined) {
+ delete process.env[name];
+ } else {
+ process.env[name] = previous;
+ }
+}
diff --git a/packages/eve/src/services/dev-client/client-options.test.ts b/packages/eve/src/services/dev-client/client-options.test.ts
index 30e2945bb..626796f5f 100644
--- a/packages/eve/src/services/dev-client/client-options.test.ts
+++ b/packages/eve/src/services/dev-client/client-options.test.ts
@@ -48,6 +48,21 @@ describe("resolveDevelopmentClientOptions", () => {
});
});
+ it("marks requests from an attached local TUI as interactive", async () => {
+ const options = resolveLocalDevelopmentClientOptions({
+ headers: { "x-eve-dev-interactive-client": "0" },
+ interactiveClient: true,
+ serverUrl: "http://127.0.0.1:3000",
+ token: async () => "user-oidc-token",
+ });
+
+ const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(null));
+ await new Client(options).fetch("/eve/v1/info");
+
+ const headers = new Headers(fetchMock.mock.calls[0]?.[1]?.headers);
+ expect(headers.get("x-eve-dev-interactive-client")).toBe("1");
+ });
+
it("does not override explicit local authorization with the linked Vercel bearer", async () => {
const token = vi.fn(async () => "user-oidc-token");
diff --git a/packages/eve/src/services/dev-client/client-options.ts b/packages/eve/src/services/dev-client/client-options.ts
index 290270978..73c983d4a 100644
--- a/packages/eve/src/services/dev-client/client-options.ts
+++ b/packages/eve/src/services/dev-client/client-options.ts
@@ -1,5 +1,6 @@
import type { ClientOptions } from "#client/index.js";
import { VERCEL_TRUSTED_OIDC_IDP_TOKEN_HEADER } from "#client/types.js";
+import { LOCAL_DEV_INTERACTIVE_CLIENT_HEADER } from "#runtime/local-dev-capability.js";
import type { DevelopmentCredentialGate } from "./credential-gate.js";
@@ -54,16 +55,21 @@ export function resolveDevelopmentClientOptions(serverUrl: string): ClientOption
/** Builds a non-redirecting local client, using ambient bearer auth only when it owns Authorization. */
export function resolveLocalDevelopmentClientOptions(input: {
readonly headers?: DevelopmentClientHeaders;
+ readonly interactiveClient?: boolean;
readonly serverUrl: string;
readonly token: () => Promise<string>;
}): ClientOptions {
+ const headers =
+ input.interactiveClient === true
+ ? { ...input.headers, [LOCAL_DEV_INTERACTIVE_CLIENT_HEADER]: "1" }
+ : input.headers;
const options = {
host: input.serverUrl,
redirect: "manual",
} satisfies ClientOptions;
- if (hasDevelopmentAuthorizationHeader(input.headers)) {
- return { ...options, headers: input.headers };
+ if (hasDevelopmentAuthorizationHeader(headers)) {
+ return { ...options, headers };
}
const authorizedOptions = {
@@ -71,8 +77,8 @@ export function resolveLocalDevelopmentClientOptions(input: {
auth: { bearer: input.token },
} satisfies ClientOptions;
- if (input.headers !== undefined) {
- return { ...authorizedOptions, headers: input.headers };
+ if (headers !== undefined) {
+ return { ...authorizedOptions, headers };
}
return authorizedOptions;
}
diff --git a/packages/eve/src/services/dev-client/runtime-artifacts.test.ts b/packages/eve/src/services/dev-client/runtime-artifacts.test.ts
index 95ee8a4b6..afbbca52b 100644
--- a/packages/eve/src/services/dev-client/runtime-artifacts.test.ts
+++ b/packages/eve/src/services/dev-client/runtime-artifacts.test.ts
@@ -54,19 +54,21 @@ describe("development runtime artifact suspension", () => {
const fetchMock = vi.fn(async () => new Response(JSON.stringify({ revision: "rev-3" })));
vi.stubGlobal("fetch", fetchMock);
- await expect(suspendDevelopmentRuntimeArtifacts({ serverUrl: SERVER_URL })).resolves.toBe(true);
- await expect(resumeDevelopmentRuntimeArtifacts({ serverUrl: SERVER_URL })).resolves.toBe(
- "rev-3",
- );
+ await expect(
+ suspendDevelopmentRuntimeArtifacts({ leaseId: "setup", serverUrl: SERVER_URL }),
+ ).resolves.toBe(true);
+ await expect(
+ resumeDevelopmentRuntimeArtifacts({ leaseId: "setup", serverUrl: SERVER_URL }),
+ ).resolves.toBe("rev-3");
expect(fetchMock).toHaveBeenNthCalledWith(
1,
- new URL("/eve/v1/dev/runtime-artifacts/suspend", SERVER_URL),
+ new URL("/eve/v1/dev/runtime-artifacts/suspend?lease=setup", SERVER_URL),
expect.objectContaining({ method: "POST" }),
);
expect(fetchMock).toHaveBeenNthCalledWith(
2,
- new URL("/eve/v1/dev/runtime-artifacts/resume", SERVER_URL),
+ new URL("/eve/v1/dev/runtime-artifacts/resume?lease=setup", SERVER_URL),
expect.objectContaining({ method: "POST" }),
);
});
diff --git a/packages/eve/src/services/dev-client/runtime-artifacts.ts b/packages/eve/src/services/dev-client/runtime-artifacts.ts
index 950ddd4a7..faf5dfa4b 100644
--- a/packages/eve/src/services/dev-client/runtime-artifacts.ts
+++ b/packages/eve/src/services/dev-client/runtime-artifacts.ts
@@ -40,20 +40,24 @@ export async function readDevelopmentRuntimeArtifactsRevision(input: {
}
export async function suspendDevelopmentRuntimeArtifacts(input: {
+ readonly leaseId: string;
readonly serverUrl: string;
}): Promise<boolean> {
return await changeDevelopmentRuntimeArtifacts(
input.serverUrl,
EVE_DEV_RUNTIME_ARTIFACTS_SUSPEND_ROUTE_PATH,
+ input.leaseId,
);
}
export async function resumeDevelopmentRuntimeArtifacts(input: {
+ readonly leaseId: string;
readonly serverUrl: string;
readonly silent?: boolean;
}): Promise<string | undefined> {
try {
const url = new URL(EVE_DEV_RUNTIME_ARTIFACTS_RESUME_ROUTE_PATH, input.serverUrl);
+ url.searchParams.set("lease", input.leaseId);
if (input.silent === true) url.searchParams.set("silent", "1");
const response = await fetch(url, { method: "POST" });
return await parseDevelopmentRuntimeArtifactsRevision(response);
@@ -65,9 +69,12 @@ export async function resumeDevelopmentRuntimeArtifacts(input: {
async function changeDevelopmentRuntimeArtifacts(
serverUrl: string,
path: string,
+ leaseId: string,
): Promise<boolean> {
try {
- const response = await fetch(new URL(path, serverUrl), { method: "POST" });
+ const url = new URL(path, serverUrl);
+ url.searchParams.set("lease", leaseId);
+ const response = await fetch(url, { method: "POST" });
return response.ok;
} catch {
return false;
diff --git a/packages/eve/test/scenarios/dev-server-rebuild.scenario.test.ts b/packages/eve/test/scenarios/dev-server-rebuild.scenario.test.ts
index ee632dea5..268c4312d 100644
--- a/packages/eve/test/scenarios/dev-server-rebuild.scenario.test.ts
+++ b/packages/eve/test/scenarios/dev-server-rebuild.scenario.test.ts
@@ -1,5 +1,5 @@
import { existsSync } from "node:fs";
-import { rm, writeFile } from "node:fs/promises";
+import { realpath, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
@@ -10,7 +10,10 @@ import {
resolveDevelopmentRuntimeArtifactsPointerPath,
} from "../../src/internal/nitro/dev-runtime-artifacts.js";
import { STRUCTURAL_RELOAD_LOG_LINE } from "../../src/internal/nitro/host/dev-watcher-log.js";
-import { useScenarioApp } from "../../src/internal/testing/scenario-app.js";
+import {
+ type ScenarioAppDescriptor,
+ useScenarioApp,
+} from "../../src/internal/testing/scenario-app.js";
import { sendDevelopmentMessage } from "../dev-client-harness/send-message.js";
import { createDevelopmentSessionState } from "../dev-client-harness/session.js";
import {
@@ -33,6 +36,37 @@ import {
const scenarioApp = useScenarioApp();
+const LOCAL_DEV_CAPABILITY_DESCRIPTOR: ScenarioAppDescriptor = {
+ ...DEV_SERVER_AGENT_DESCRIPTOR,
+ files: {
+ ...DEV_SERVER_AGENT_DESCRIPTOR.files,
+ "agent/channels/local-dev-capability.ts": [
+ 'import { writeFile } from "node:fs/promises";',
+ 'import { join } from "node:path";',
+ 'import { defineChannel, GET } from "eve/channels";',
+ 'import { getLocalDevCapability } from "eve/local-dev";',
+ "",
+ "export default defineChannel({",
+ " routes: [",
+ ' GET("/local-dev-capability", async () => {',
+ " const capability = getLocalDevCapability();",
+ " if (capability === undefined) return Response.json({ available: false });",
+ " return await capability.withSuspendedSource(async () => {",
+ ' await writeFile(join(capability.appRoot, "local-dev-capability.marker"), "updated\\n");',
+ " return Response.json({",
+ " appRoot: capability.appRoot,",
+ " available: true,",
+ " interactiveClient: capability.interactiveClient,",
+ " });",
+ " });",
+ " }),",
+ " ],",
+ "});",
+ "",
+ ].join("\n"),
+ },
+};
+
function createCandidateChannelSource(): string {
return createTransactionalChannelSource([
' GET("/candidate-only", () => new Response("candidate")),',
@@ -40,6 +74,37 @@ function createCandidateChannelSource(): string {
}
describe("eve dev server rebuild transactions", () => {
+ it(
+ "scopes a local-dev capability through the host and releases its watcher lease",
+ async () => {
+ const app = await scenarioApp(LOCAL_DEV_CAPABILITY_DESCRIPTOR);
+ const server = await startEveDev(app.appRoot);
+
+ try {
+ const initialRevision = await readDevelopmentRevision(server.url);
+ const response = await fetch(new URL("/local-dev-capability", server.url), {
+ headers: { "x-eve-dev-interactive-client": "1" },
+ });
+
+ await expect(response.json()).resolves.toEqual({
+ appRoot: await realpath(app.appRoot),
+ available: true,
+ interactiveClient: true,
+ });
+ expect(existsSync(join(app.appRoot, "local-dev-capability.marker"))).toBe(true);
+
+ await writeFile(join(app.appRoot, "agent", "instructions.md"), "Still watching.\n");
+ await waitForCondition(
+ async () => (await readDevelopmentRevision(server.url)) !== initialRevision,
+ `Timed out waiting for the released watcher.\n\nstdout:\n${server.stdout()}\n\nstderr:\n${server.stderr()}`,
+ );
+ } finally {
+ await server.stop();
+ }
+ },
+ DEV_SERVER_SCENARIO_TIMEOUT_MS,
+ );
+
it(
"publishes authored tool removals without replacing the active host",
async () => {