feat(server): headless 复用入口与 server-mode 加固 (server-v1 §13/§20.4)

- package.json 显式导出 ./server 子路径 (listen/openapi 稳定入口)
- /global/capabilities 增加 commit 字段 (DEEPAGENT_CODE_COMMIT, CI 注入)
- DEEPAGENT_SERVER_MODE=true 时 Auth.set/remove fail-close, 禁 key 落盘

Author: thomas-yanga

packages/core/src/flag/flag.ts

@@ -30,6 +30,12 @@ export const Flag = {
   DEEPAGENT_CODE_FAKE_VCS: process.env["DEEPAGENT_CODE_FAKE_VCS"],
   DEEPAGENT_CODE_SERVER_PASSWORD: process.env["DEEPAGENT_CODE_SERVER_PASSWORD"],
   DEEPAGENT_CODE_SERVER_USERNAME: process.env["DEEPAGENT_CODE_SERVER_USERNAME"],
+  // Server Edition: CI injects the deepagent-code commit into workspace images so
+  // the gateway can report/version-check the data plane (server-v1 §13.3).
+  DEEPAGENT_CODE_COMMIT: process.env["DEEPAGENT_CODE_COMMIT"],
+  // Server Edition: when running inside a gateway-managed workspace container,
+  // provider keys are injected via env and must not persist to the volume (§20.4).
+  DEEPAGENT_SERVER_MODE: truthy("DEEPAGENT_SERVER_MODE"),
 
   // Experimental
   DEEPAGENT_CODE_EXPERIMENTAL_FILEWATCHER: Config.boolean("DEEPAGENT_CODE_EXPERIMENTAL_FILEWATCHER").pipe(

packages/deepagent-code/package.json

@@ -21,6 +21,7 @@
     "deepagent": "./bin/deepagent"
   },
   "exports": {
+    "./server": "./src/server/server.ts",
     "./*": "./src/*.ts"
   },
   "imports": {

packages/deepagent-code/src/auth/index.ts

@@ -2,6 +2,7 @@ import path from "path"
 import { Effect, Layer, Record, Result, Schema, Context } from "effect"
 import { NonNegativeInt } from "@deepagent-code/core/schema"
 import { Global } from "@deepagent-code/core/global"
+import { Flag } from "@deepagent-code/core/flag/flag"
 import { FSUtil } from "@deepagent-code/core/fs-util"
 
 export const OAUTH_DUMMY_KEY = "deepagent-code-oauth-dummy-key"
@@ -70,6 +71,13 @@ export const layer = Layer.effect(
     })
 
     const set = Effect.fn("Auth.set")(function* (key: string, info: Info) {
+      // Server Edition (§20.4): gateway-managed containers receive provider keys
+      // via env injection; persisting them to the workspace volume is forbidden.
+      if (Flag.DEEPAGENT_SERVER_MODE)
+        return yield* new AuthError({
+          message:
+            "Provider credentials are managed by the gateway in server mode; persisting auth.json is disabled (DEEPAGENT_SERVER_MODE)",
+        })
       const norm = key.replace(/\/+$/, "")
       const data = yield* all()
       if (norm !== key) delete data[key]
@@ -80,6 +88,11 @@ export const layer = Layer.effect(
     })
 
     const remove = Effect.fn("Auth.remove")(function* (key: string) {
+      if (Flag.DEEPAGENT_SERVER_MODE)
+        return yield* new AuthError({
+          message:
+            "Provider credentials are managed by the gateway in server mode; modifying auth.json is disabled (DEEPAGENT_SERVER_MODE)",
+        })
       const norm = key.replace(/\/+$/, "")
       const data = yield* all()
       delete data[key]

packages/deepagent-code/src/server/routes/instance/httpapi/groups/global.ts

@@ -24,6 +24,9 @@ const GlobalHealth = Schema.Struct({
 const GlobalCapabilities = Schema.Struct({
   protocolVersion: Schema.String,
   version: Schema.String,
+  // deepagent-code commit the data plane was built from; only present when CI
+  // injected DEEPAGENT_CODE_COMMIT (workspace images), absent on local builds.
+  commit: Schema.optional(Schema.String),
   features: Schema.Struct({
     im: Schema.Boolean,
     sessions: Schema.Boolean,

packages/deepagent-code/src/server/routes/instance/httpapi/handlers/global.ts

@@ -6,6 +6,7 @@ import { EventV2 } from "@deepagent-code/core/event"
 import { Installation } from "@/installation"
 import { disposeAllInstancesAndEmitGlobalDisposed, disposeInstancesForDirectories } from "@/server/global-lifecycle"
 import { InstallationVersion } from "@deepagent-code/core/installation/version"
+import { Flag } from "@deepagent-code/core/flag/flag"
 import { IM_PROTOCOL_VERSION } from "@deepagent-code/core/im/protocol"
 import * as Log from "@deepagent-code/core/util/log"
 import { Effect, Queue, Schema } from "effect"
@@ -91,6 +92,7 @@ export const globalHandlers = HttpApiBuilder.group(RootHttpApi, "global", (handl
       return {
         protocolVersion: IM_PROTOCOL_VERSION,
         version: InstallationVersion,
+        commit: Flag.DEEPAGENT_CODE_COMMIT,
         features: {
           im: true,
           sessions: true,