feat(serve): add GET /workspace/env route (#4175 Wave 3 PR 13)

doudouOUC · doudouOUC · commit 8d03e5797334 · 2026-05-18T01:49:26.000+08:00
Wire `buildEnvStatusFromProcess` from the previous commit through the
bridge, server, and SDK so remote clients can pre-flight the daemon's
runtime environment without spawning an ACP child.

- `workspace_env` capability tag (always advertised on a current daemon).
- `bridge.getWorkspaceEnvStatus()` answers entirely from `process.*` —
  the route never consults ACP. `acpChannelLive` reflects whether a child
  exists but does not change the payload, so an idle daemon and a busy
  one return the same env shape.
- `app.get('/workspace/env', ...)` mirrors PR 12's one-liner pattern.
- SDK: `DaemonClient.workspaceEnv()` returning `DaemonWorkspaceEnvStatus`.
- Docs: bullet in `docs/users/qwen-serve.md` calling out the
  presence-only redaction policy and the no-ACP-spawn guarantee.

Tests: server-level (env returned + `'value' in env_var === false`
assertion), bridge-level (idle and live both answer locally without
hitting ACP extMethod), SDK-level (recording-fetch round-trip on
`/workspace/env`). The `workspace_env` tag is added to the
`EXPECTED_STAGE1_FEATURES` capability list assertion.
diff --git a/docs/users/qwen-serve.md b/docs/users/qwen-serve.md
@@ -40,9 +40,16 @@ The `workspaceCwd` field surfaces the bound workspace so clients can pre-flight
 
 The daemon also exposes read-only runtime snapshots for client UIs:
 `GET /workspace/mcp`, `GET /workspace/skills`, `GET /workspace/providers`,
-`GET /session/:id/context`, and `GET /session/:id/supported-commands`. The
-workspace routes report the live daemon runtime and do not start the ACP child
-when idle; an idle daemon returns `initialized: false` with an empty snapshot.
+`GET /workspace/env`, `GET /session/:id/context`, and
+`GET /session/:id/supported-commands`. The workspace routes report the live
+daemon runtime and do not start the ACP child when idle; an idle daemon
+returns `initialized: false` with an empty snapshot.
+
+`GET /workspace/env` reports the daemon process's runtime, platform, sandbox,
+proxy, and the **presence** (never the value) of whitelisted secret env vars
+such as `OPENAI_API_KEY`. Proxy URLs are stripped of credentials and reduced
+to `host:port` before they hit the wire. The route always answers from the
+daemon process directly and never spawns an ACP child.
 
 ### 3. Open a session
 
diff --git a/packages/cli/src/serve/capabilities.ts b/packages/cli/src/serve/capabilities.ts
@@ -54,6 +54,7 @@ export const SERVE_CAPABILITY_REGISTRY = {
   workspace_mcp: { since: 'v1' },
   workspace_skills: { since: 'v1' },
   workspace_providers: { since: 'v1' },
+  workspace_env: { since: 'v1' },
   session_context: { since: 'v1' },
   session_supported_commands: { since: 'v1' },
   session_close: { since: 'v1' },
diff --git a/packages/cli/src/serve/httpAcpBridge.test.ts b/packages/cli/src/serve/httpAcpBridge.test.ts
@@ -458,6 +458,41 @@ describe('createHttpAcpBridge', () => {
     await bridge.shutdown();
   });
 
+  it('answers /workspace/env from process state without consulting ACP, idle or live', async () => {
+    const handles: ChannelHandle[] = [];
+    const bridge = makeBridge({
+      channelFactory: async () => {
+        const h = makeChannel();
+        handles.push(h);
+        return h.channel;
+      },
+    });
+
+    // Idle path — daemon answers env from `process.*`; no ACP child spawn.
+    const idle = await bridge.getWorkspaceEnvStatus();
+    expect(idle).toMatchObject({
+      v: 1,
+      workspaceCwd: WS_A,
+      initialized: true,
+      acpChannelLive: false,
+    });
+    expect(idle.cells.length).toBeGreaterThan(0);
+    expect(handles).toHaveLength(0);
+
+    // Live path — bridge still answers locally; the ACP child sees no
+    // ext-method invocation for env.
+    await bridge.spawnOrAttach({ workspaceCwd: WS_A });
+    const live = await bridge.getWorkspaceEnvStatus();
+    expect(live.acpChannelLive).toBe(true);
+    expect(handles).toHaveLength(1);
+    expect(
+      handles[0]?.agent.extMethodCalls.some((c) =>
+        c.method.includes('/workspace/env'),
+      ),
+    ).toBe(false);
+
+    await bridge.shutdown();
+  });
   it('requests session status through the existing ACP channel', async () => {
     const handles: ChannelHandle[] = [];
     const bridge = makeBridge({
diff --git a/packages/cli/src/serve/httpAcpBridge.ts b/packages/cli/src/serve/httpAcpBridge.ts
@@ -29,10 +29,12 @@ import {
   createIdleWorkspaceSkillsStatus,
   type ServeSessionContextStatus,
   type ServeSessionSupportedCommandsStatus,
+  type ServeWorkspaceEnvStatus,
   type ServeWorkspaceMcpStatus,
   type ServeWorkspaceProvidersStatus,
   type ServeWorkspaceSkillsStatus,
 } from './status.js';
+import { buildEnvStatusFromProcess } from './envSnapshot.js';
 import type {
   CancelNotification,
   Client,
@@ -354,6 +356,14 @@ export interface HttpAcpBridge {
    */
   getWorkspaceProvidersStatus(): Promise<ServeWorkspaceProvidersStatus>;
 
+  /**
+   * Read the daemon-process environment snapshot for the bound workspace.
+   * Answered entirely from `process.*` state — does not consult ACP. Always
+   * returns `initialized: true`; `acpChannelLive` reports whether a child is
+   * currently up.
+   */
+  getWorkspaceEnvStatus(): Promise<ServeWorkspaceEnvStatus>;
+
   /** Read the current ACP context/config state for a live session. */
   getSessionContextStatus(
     sessionId: string,
@@ -3188,6 +3198,10 @@ export function createHttpAcpBridge(opts: BridgeOptions): HttpAcpBridge {
       );
     },
 
+    async getWorkspaceEnvStatus() {
+      return buildEnvStatusFromProcess(boundWorkspace, !!liveChannelInfo());
+    },
+
     async getSessionContextStatus(sessionId) {
       return requestSessionStatus(
         sessionId,
diff --git a/packages/cli/src/serve/server.test.ts b/packages/cli/src/serve/server.test.ts
@@ -52,6 +52,7 @@ import type { BridgeEvent, SubscribeOptions } from './eventBus.js';
 import type {
   ServeSessionContextStatus,
   ServeSessionSupportedCommandsStatus,
+  ServeWorkspaceEnvStatus,
   ServeWorkspaceMcpStatus,
   ServeWorkspaceProvidersStatus,
   ServeWorkspaceSkillsStatus,
@@ -94,6 +95,7 @@ const EXPECTED_STAGE1_FEATURES = [
   'workspace_mcp',
   'workspace_skills',
   'workspace_providers',
+  'workspace_env',
   'session_context',
   'session_supported_commands',
   'session_close',
@@ -149,6 +151,7 @@ interface FakeBridgeOpts {
   workspaceMcpImpl?: () => Promise<ServeWorkspaceMcpStatus>;
   workspaceSkillsImpl?: () => Promise<ServeWorkspaceSkillsStatus>;
   workspaceProvidersImpl?: () => Promise<ServeWorkspaceProvidersStatus>;
+  workspaceEnvImpl?: () => Promise<ServeWorkspaceEnvStatus>;
   sessionContextImpl?: (
     sessionId: string,
   ) => Promise<ServeSessionContextStatus>;
@@ -211,6 +214,7 @@ interface FakeBridge extends HttpAcpBridge {
   workspaceMcpCalls: number;
   workspaceSkillsCalls: number;
   workspaceProvidersCalls: number;
+  workspaceEnvCalls: number;
   sessionContextCalls: string[];
   sessionSupportedCommandsCalls: string[];
   setModelCalls: Array<{
@@ -252,6 +256,7 @@ function fakeBridge(opts: FakeBridgeOpts = {}): FakeBridge {
   let workspaceMcpCalls = 0;
   let workspaceSkillsCalls = 0;
   let workspaceProvidersCalls = 0;
+  let workspaceEnvCalls = 0;
   const sessionContextCalls: string[] = [];
   const sessionSupportedCommandsCalls: string[] = [];
   const setModelCalls: FakeBridge['setModelCalls'] = [];
@@ -317,6 +322,15 @@ function fakeBridge(opts: FakeBridgeOpts = {}): FakeBridge {
       initialized: false,
       providers: [],
     }));
+  const workspaceEnvImpl =
+    opts.workspaceEnvImpl ??
+    (async () => ({
+      v: 1 as const,
+      workspaceCwd: WS_BOUND,
+      initialized: true as const,
+      acpChannelLive: false,
+      cells: [],
+    }));
   const sessionContextImpl =
     opts.sessionContextImpl ??
     (async (sessionId) => ({
@@ -385,6 +399,9 @@ function fakeBridge(opts: FakeBridgeOpts = {}): FakeBridge {
     get workspaceProvidersCalls() {
       return workspaceProvidersCalls;
     },
+    get workspaceEnvCalls() {
+      return workspaceEnvCalls;
+    },
     get sessionCount() {
       return calls.length;
     },
@@ -466,6 +483,10 @@ function fakeBridge(opts: FakeBridgeOpts = {}): FakeBridge {
       workspaceProvidersCalls += 1;
       return workspaceProvidersImpl();
     },
+    async getWorkspaceEnvStatus() {
+      workspaceEnvCalls += 1;
+      return workspaceEnvImpl();
+    },
     async getSessionContextStatus(sessionId) {
       sessionContextCalls.push(sessionId);
       return sessionContextImpl(sessionId);
@@ -795,6 +816,44 @@ describe('createServeApp', () => {
       expect(bridge.workspaceProvidersCalls).toBe(1);
     });
 
+    it('returns workspace env status from the bridge', async () => {
+      const env: ServeWorkspaceEnvStatus = {
+        v: 1,
+        workspaceCwd: WS_BOUND,
+        initialized: true,
+        acpChannelLive: false,
+        cells: [
+          { kind: 'runtime', name: 'node', status: 'ok', value: '22.4.0' },
+          {
+            kind: 'env_var',
+            name: 'OPENAI_API_KEY',
+            status: 'ok',
+            present: true,
+          },
+        ],
+      };
+      const bridge = fakeBridge({ workspaceEnvImpl: async () => env });
+      const app = createServeApp(
+        { ...baseOpts, workspace: WS_BOUND },
+        undefined,
+        { bridge },
+      );
+      const res = await request(app)
+        .get('/workspace/env')
+        .set('Host', `127.0.0.1:${baseOpts.port}`);
+
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual(env);
+      expect(bridge.workspaceEnvCalls).toBe(1);
+      // Strict assertion: env_var cells never carry a value field, even
+      // when the env var is set, to preserve the presence-only contract.
+      const envVarCell = (res.body as ServeWorkspaceEnvStatus).cells.find(
+        (c) => c.kind === 'env_var',
+      );
+      expect(envVarCell).toBeDefined();
+      expect('value' in envVarCell!).toBe(false);
+    });
+
     it('returns session context and supported commands from the bridge', async () => {
       const context: ServeSessionContextStatus = {
         v: 1,
diff --git a/packages/cli/src/serve/server.ts b/packages/cli/src/serve/server.ts
@@ -73,6 +73,7 @@ export interface ServeAppDeps {
  *   - `GET  /workspace/mcp`
  *   - `GET  /workspace/skills`
  *   - `GET  /workspace/providers`
+ *   - `GET  /workspace/env`
  *   - `POST /session`
  *   - `POST /session/:id/load`
  *   - `POST /session/:id/resume`
@@ -288,6 +289,14 @@ export function createServeApp(
     }
   });
 
+  app.get('/workspace/env', async (_req, res) => {
+    try {
+      res.status(200).json(await bridge.getWorkspaceEnvStatus());
+    } catch (err) {
+      sendBridgeError(res, err, { route: 'GET /workspace/env' });
+    }
+  });
+
   app.post('/session', mutate(), async (req, res) => {
     const body = safeBody(req);
     // #3803 §02: 1 daemon = 1 workspace. Three input shapes:
diff --git a/packages/sdk-typescript/src/daemon/DaemonClient.ts b/packages/sdk-typescript/src/daemon/DaemonClient.ts
@@ -13,6 +13,7 @@ import type {
   DaemonSession,
   DaemonSessionSummary,
   DaemonSessionSupportedCommandsStatus,
+  DaemonWorkspaceEnvStatus,
   DaemonWorkspaceMcpStatus,
   DaemonWorkspaceProvidersStatus,
   DaemonWorkspaceSkillsStatus,
@@ -340,6 +341,17 @@ export class DaemonClient {
     );
   }
 
+  async workspaceEnv(): Promise<DaemonWorkspaceEnvStatus> {
+    return await this.fetchWithTimeout(
+      `${this.baseUrl}/workspace/env`,
+      { headers: this.headers() },
+      async (res) => {
+        if (!res.ok) throw await this.failOnError(res, 'GET /workspace/env');
+        return (await res.json()) as DaemonWorkspaceEnvStatus;
+      },
+    );
+  }
+
   // -- Sessions ----------------------------------------------------------
 
   async createOrAttachSession(
diff --git a/packages/sdk-typescript/test/unit/DaemonClient.test.ts b/packages/sdk-typescript/test/unit/DaemonClient.test.ts
@@ -19,6 +19,7 @@ import type {
   DaemonCapabilities,
   DaemonSessionContextStatus,
   DaemonSessionSupportedCommandsStatus,
+  DaemonWorkspaceEnvStatus,
   DaemonWorkspaceMcpStatus,
   DaemonWorkspaceProvidersStatus,
   DaemonWorkspaceSkillsStatus,
@@ -217,6 +218,31 @@ describe('DaemonClient', () => {
       ]);
     });
 
+    it('GETs /workspace/env and returns the env envelope unchanged', async () => {
+      const env: DaemonWorkspaceEnvStatus = {
+        v: 1,
+        workspaceCwd: '/work/a',
+        initialized: true,
+        acpChannelLive: false,
+        cells: [
+          { kind: 'runtime', name: 'node', status: 'ok', value: '22.4.0' },
+          {
+            kind: 'env_var',
+            name: 'OPENAI_API_KEY',
+            status: 'ok',
+            present: true,
+          },
+        ],
+      };
+      const { fetch, calls } = recordingFetch(() => jsonResponse(200, env));
+      const client = new DaemonClient({ baseUrl: 'http://daemon', fetch });
+
+      await expect(client.workspaceEnv()).resolves.toEqual(env);
+      expect(calls.map((c) => [c.method, c.url])).toEqual([
+        ['GET', 'http://daemon/workspace/env'],
+      ]);
+    });
+
     it('GETs session status routes with encoded session ids', async () => {
       const context: DaemonSessionContextStatus = {
         v: 1,
