feat(core): implement v2 session shell execution

Author: See U

MERGE.md

@@ -167,6 +167,7 @@ fork 与上游改了同一处（常见于 TUI 视觉/UX、core 加固逻辑）
 | `packages/core/src/{session.ts,session/compaction.ts,session/history.ts,session/runner/*}` (v2 手动 compact 实现) | 中 | 保留：实现 `SessionV2.compact`（原 stub 恒 `OperationUnavailableError`），spec `specs/v2/session.md:105` 已列为 sanctioned improvement。`SessionCompaction.make` 抽出共享 `summarize` 核心（`reason: "auto"\|"manual"`），新增 `compactManually`（输出预算取 `model.route.defaults.limits?.output`，可选 `instructions` 折入 `buildPrompt`）；`SessionHistory.load` 改由新导出 `entries()`（读 epoch `baseline_seq` 只读，不触发 SystemContext 初始化）派生；`SessionRunner` 接口新增 `compact`，`SessionV2.compact` 经 `locations.get(session.location)` 路由，失败/无可压缩内容统一映射 `OperationUnavailableError`（HTTP 503 文案不变）。已知限制：手动 compact 不经 `SessionRunCoordinator` 串行化，与进行中 drain 并发时下一 turn 才生效；测试 `packages/core/test/session-runner.test.ts`（manually compacts on demand / returns false when nothing to compact）（上游实现 v2 手动 compact 后取上游版本） |
 | `packages/core/src/{session.ts,session/run-coordinator.ts,session/execution.ts,session/execution/local.ts}` (v2 `SessionV2.wait` 实现) | 低 | 保留：实现 `SessionV2.wait`（原 stub 恒 `OperationUnavailableError`）。逐字对齐上游 in-flight 提交 `5e90a68d6a`（wip(core): v2 subagent foundations）：`SessionRunCoordinator.awaitIdle`（await entry `done` + `Effect.exit` 吞掉失败/中断、循环复查 successor 直到 idle，空闲即 no-op、不发起 drain），`SessionExecution.awaitIdle` 透传，`SessionV2.wait` 委托并收窄为 `NotFoundError`，server handler 移除死的 503 映射，literals 移除 `"wait"`（对齐 `bd8d858bf7` 前态）。语义限制：仅覆盖本进程持有的执行；测试为 fork 补充（上游 wip 无测试）：`packages/core/test/session-run-coordinator.test.ts`（awaitIdle 4 例）+ `packages/opencode/test/server/httpapi-session.test.ts`（wait 改期望 204）（上游该分支合入后按上游版本对齐） |
 | `packages/{schema,core,protocol,server}/src/**` + `packages/sdk/js/src/v2/gen` (v2 `SessionV2.skill` 实现) | 中 | 保留：实现 `SessionV2.skill`（原 stub 恒 `OperationUnavailableError`）。逐字移植上游 in-flight 提交 `23adaaaeab`（feat(core): add native skill activation）：durable `SessionEvent.Skill.Activated` + `SessionMessage.Skill` + projector/message-updater/to-llm-message/compaction 全链路，`SessionV2.skill` 经 `locations.get(session.location)` 解析 `SkillV2.list()`、未命中报 `Session.SkillNotFoundError`、`resume !== false` 时 fork `execution.resume`，协议新增 `POST /api/session/:sessionID/skill`（404 `SkillNotFoundError`）+ server handler + SDK v2 重新生成。未移植部分：TUI skill UX（依赖上游更新的 useLocation 管线）、report skill、cli daemon、plugin skill.ts、packages/client gen。测试为 fork 补充：`packages/core/test/session-create.test.ts`（activates a known skill as a durable skill message）+ httpapi-exercise/httpapi-session 覆盖；manifest 计数随 durable 事件 +1（60/90/90/36）（上游该分支合入后按上游版本对齐） |
+| `packages/{core,protocol,server}/src/**` + `packages/sdk/js/src/v2/gen` (v2 `SessionV2.shell` 实现) | 中 | 保留：实现 `SessionV2.shell`（原 stub 恒 `OperationUnavailableError`）。结构逐字对齐上游提交 `bd8d858bf7`（feat(core): implement V2 session.shell）：`KeyedMutex` 按 Session 串行、`activeShells` 抑制 shell 期间 prompt wake、`execution.awaitIdle` 等待在跑 drain、durable `Shell.Started`/`Shell.Ended`（事件在 HEAD 已入 manifest，计数不变）、`Effect.ensuring` 清理 + `execution.wake`，协议新增 `POST /api/session/:sessionID/shell`（404 `SessionNotFoundError`）+ server handler + SDK v2 重新生成。唯一偏离：`runShellCommand` 内部用 HEAD 已有原语 `AppProcess.run` + `Shell.preferred`/`Shell.args`（v1 用户 shell 语义：config shell、TERM=dumb、extendEnv、stdin ignore、forceKillAfter 3s、合并输出、1MiB 截断、`AppProcessError` 捕获为输出文本）替代上游尚未移植的 location `Shell.Service`（`5ae93092aa`）；`core/src/shell.ts` 保持原样。测试为 fork 补充：`packages/core/test/session-create.test.ts`（shell 3 例）+ httpapi-exercise/httpapi-session 覆盖（上游 `5ae93092aa`+`bd8d858bf7` 移植后取上游版本） |
 
 ### TUI 偏离（四批 23 轮审计打磨，全域）
 

packages/core/src/session.ts

@@ -1,7 +1,8 @@
 export * as SessionV2 from "./session"
 export * from "./session/schema"
 
-import { DateTime, Effect, Layer, Schema, Context, Stream, Scope } from "effect"
+import { DateTime, Duration, Effect, Layer, Schema, Context, Stream, Scope } from "effect"
+import { ChildProcess } from "effect/unstable/process"
 import { ListAnchor } from "@opencode-ai/schema/session"
 import { and, asc, desc, eq, gt, like, lt, or, type SQL } from "drizzle-orm"
 import { ProjectV2 } from "./project"
@@ -38,6 +39,11 @@ import { Revert } from "@opencode-ai/schema/revert"
 import { FSUtil } from "./fs-util"
 import { SessionDurable } from "@opencode-ai/schema/durable-event-manifest"
 import { SkillV2 } from "./skill"
+import { Identifier } from "./util/identifier"
+import { Shell } from "./shell"
+import { KeyedMutex } from "./effect/keyed-mutex"
+import { AppProcess } from "./process"
+import { Config } from "./config"
 
 export const RevertState = Revert.State
 export type RevertState = Revert.State
@@ -96,7 +102,7 @@ export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Ses
 export class OperationUnavailableError extends Schema.TaggedErrorClass<OperationUnavailableError>()(
   "Session.OperationUnavailableError",
   {
-    operation: Schema.Literals(["move", "shell", "skill", "switchAgent", "compact"]),
+    operation: Schema.Literals(["move", "skill", "switchAgent", "compact"]),
   },
 ) {}
 
@@ -159,8 +165,7 @@ export interface Interface {
     id?: EventV2.ID
     sessionID: SessionSchema.ID
     command: string
-    resume?: boolean
-  }) => Effect.Effect<void, OperationUnavailableError>
+  }) => Effect.Effect<void, NotFoundError>
   readonly skill: (input: {
     id?: SessionMessage.ID
     sessionID: SessionSchema.ID
@@ -195,7 +200,10 @@ const layer = Layer.effect(
     const execution = yield* SessionExecution.Service
     const store = yield* SessionStore.Service
     const locations = yield* LocationServiceMap.Service
+    const appProcess = yield* AppProcess.Service
     const scope = yield* Scope.Scope
+    const activeShells = new Set<SessionSchema.ID>()
+    const shellLocks = KeyedMutex.makeUnsafe<SessionSchema.ID>()
     const decodeMessage = Schema.decodeUnknownEffect(SessionMessage.Message)
     const isDurableSessionEvent = Schema.is(SessionEvent.Durable)
     const decode = (row: typeof SessionMessageTable.$inferSelect) =>
@@ -209,6 +217,26 @@ const layer = Layer.effect(
         ),
       )
 
+    // Session shell is user-initiated and synchronous at the API boundary. The
+    // upstream location Shell service is not at this HEAD yet, so run through
+    // AppProcess with the v1 user-facing shell selection semantics.
+    const runShellCommand = (command: string, cwd: string) =>
+      Effect.gen(function* () {
+        const config = yield* Config.Service
+        const sh = Shell.preferred(Config.latest(yield* config.entries(), "shell"))
+        const result = yield* appProcess.run(
+          ChildProcess.make(sh, Shell.args(sh, command, cwd), {
+            cwd,
+            extendEnv: true,
+            env: { TERM: "dumb" },
+            stdin: "ignore",
+            forceKillAfter: Duration.seconds(3),
+          }),
+          { combineOutput: true, maxOutputBytes: SHELL_MAX_CAPTURE_BYTES },
+        )
+        return result.output?.toString("utf8") || "(no output)"
+      }).pipe(Effect.catchTag("AppProcessError", (error) => Effect.succeed(error.message)))
+
     const result = Service.of({
       create: Effect.fn("V2Session.create")(function* (input) {
         const sessionID = input.id ?? SessionSchema.ID.create()
@@ -384,13 +412,51 @@ const layer = Layer.effect(
             )
             if (!SessionInput.equivalent(admitted, expected))
               return yield* new PromptConflictError({ sessionID: input.sessionID, messageID })
-            if (input.resume !== false) yield* execution.wake(admitted.sessionID)
+            if (input.resume !== false) {
+              if (activeShells.has(admitted.sessionID)) return admitted
+              yield* execution.wake(admitted.sessionID)
+            }
             return admitted
           }),
         ),
       ),
-      shell: Effect.fn("V2Session.shell")(function* () {
-        return yield* new OperationUnavailableError({ operation: "shell" })
+      shell: Effect.fn("V2Session.shell")(function* (input) {
+        const session = yield* result.get(input.sessionID)
+        yield* shellLocks.withLock(input.sessionID)(
+          Effect.gen(function* () {
+            activeShells.add(input.sessionID)
+            if ((yield* execution.active).has(input.sessionID)) yield* execution.awaitIdle(input.sessionID)
+            const messageID = SessionMessage.ID.create()
+            const callID = Identifier.ascending()
+            yield* events.publish(
+              SessionEvent.Shell.Started,
+              {
+                sessionID: input.sessionID,
+                messageID,
+                callID,
+                command: input.command,
+                timestamp: yield* DateTime.now,
+              },
+              { id: input.id },
+            )
+            const output = yield* runShellCommand(input.command, session.location.directory).pipe(
+              Effect.provide(locations.get(session.location)),
+            )
+            yield* events.publish(SessionEvent.Shell.Ended, {
+              sessionID: input.sessionID,
+              callID,
+              output,
+              timestamp: yield* DateTime.now,
+            })
+          }).pipe(
+            Effect.ensuring(
+              Effect.gen(function* () {
+                activeShells.delete(input.sessionID)
+                yield* execution.wake(input.sessionID)
+              }),
+            ),
+          ),
+        )
       }),
       skill: Effect.fn("V2Session.skill")(function* (input) {
         const session = yield* result.get(input.sessionID)
@@ -497,6 +563,9 @@ const resolvePrompt = (input: PromptInput.Prompt) =>
     }),
   })
 
+// Mirrors the shell tool's in-memory preview safety limit.
+const SHELL_MAX_CAPTURE_BYTES = 1024 * 1024
+
 export const node = makeGlobalNode({
   service: Service,
   layer: layer.pipe(Layer.orDie),
@@ -508,5 +577,6 @@ export const node = makeGlobalNode({
     SessionStore.node,
     LocationServiceMap.node,
     SessionProjector.node,
+    AppProcess.node,
   ],
 })

packages/core/test/session-create.test.ts

@@ -314,19 +314,55 @@ describe("SessionV2.create", () => {
     }),
   )
 
-  it.effect("reports unfinished Session operations as unavailable", () =>
+  it.live("runs a shell command as a durable shell message", () =>
     Effect.gen(function* () {
       const session = yield* SessionV2.Service
-      const created = yield* session.create({ location })
-      const unavailable = (
-        effect: Effect.Effect<void, SessionV2.NotFoundError | SessionV2.OperationUnavailableError>,
-      ) =>
-        effect.pipe(
-          Effect.flip,
-          Effect.map((error) => (error instanceof SessionV2.OperationUnavailableError ? error.operation : "not-found")),
-        )
+      const tmp = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+      )
+      const created = yield* session.create({
+        location: Location.Ref.make({ directory: AbsolutePath.make(tmp.path) }),
+      })
+
+      yield* session.shell({ sessionID: created.id, command: "echo hello" })
 
-      expect(yield* unavailable(session.shell({ sessionID: created.id, command: "pwd" }))).toBe("shell")
+      const messages = yield* session.messages({ sessionID: created.id, order: "asc" })
+      expect(messages).toMatchObject([{ type: "shell", command: "echo hello", output: "hello\n" }])
+      expect(messages[0]?.type === "shell" && messages[0].time.completed !== undefined).toBe(true)
+    }),
+  )
+
+  it.live("records nonzero exits and empty output as a completed shell message", () =>
+    Effect.gen(function* () {
+      const session = yield* SessionV2.Service
+      const tmp = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+      )
+      const created = yield* session.create({
+        location: Location.Ref.make({ directory: AbsolutePath.make(tmp.path) }),
+      })
+
+      yield* session.shell({ sessionID: created.id, command: "exit 7" })
+
+      expect(yield* session.messages({ sessionID: created.id, order: "asc" })).toMatchObject([
+        { type: "shell", command: "exit 7", output: "(no output)" },
+      ])
+    }),
+  )
+
+  it.effect("rejects a shell command for a missing Session", () =>
+    Effect.gen(function* () {
+      const session = yield* SessionV2.Service
+      const missing = SessionV2.ID.make("ses_missing_shell")
+
+      expect(
+        yield* session.shell({ sessionID: missing, command: "pwd" }).pipe(
+          Effect.flip,
+          Effect.map((error) => error._tag),
+        ),
+      ).toBe("Session.NotFoundError")
     }),
   )
 

packages/opencode/test/server/httpapi-exercise/index.ts

@@ -1143,6 +1143,14 @@ const scenarios: Scenario[] = [
       body: { skill: "review" },
     }))
     .status(404, undefined, "status"),
+  http.protected
+    .post("/api/session/{sessionID}/shell", "v2.session.shell")
+    .at((ctx) => ({
+      path: route("/api/session/{sessionID}/shell", { sessionID: "ses_httpapi_missing" }),
+      headers: ctx.headers(),
+      body: { command: "pwd" },
+    }))
+    .status(404, undefined, "status"),
   http.protected
     .post("/api/session/{sessionID}/compact", "v2.session.compact")
     .at((ctx) => ({

packages/opencode/test/server/httpapi-session.test.ts

@@ -565,6 +565,14 @@ describe("session HttpApi", () => {
         })
         expect(skill.status).toBe(404)
         expect(yield* responseJson(skill)).toEqual(expected)
+
+        const shell = yield* request(`/api/session/${missing}/shell`, {
+          method: "POST",
+          headers: { ...headers, "content-type": "application/json" },
+          body: JSON.stringify({ command: "pwd" }),
+        })
+        expect(shell.status).toBe(404)
+        expect(yield* responseJson(shell)).toEqual(expected)
       }),
     { git: true, config: { formatter: false, lsp: false } },
   )

packages/protocol/src/groups/session.ts

@@ -22,6 +22,7 @@ import { Model } from "@opencode-ai/schema/model"
 import { Location } from "@opencode-ai/schema/location"
 import { Revert } from "@opencode-ai/schema/revert"
 import { SessionEvent } from "@opencode-ai/schema/session-event"
+import { Event } from "@opencode-ai/schema/event"
 
 const SessionsQueryFields = {
   workspace: Workspace.ID.pipe(Schema.optional),
@@ -223,6 +224,26 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
           }),
         ),
     )
+    .add(
+      HttpApiEndpoint.post("session.shell", "/api/session/:sessionID/shell", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({
+          id: Event.ID.pipe(Schema.optional),
+          command: Schema.String,
+        }),
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.shell",
+            summary: "Run shell command",
+            description:
+              "Execute one shell command in the session's working directory. Emits a shell.started event before execution and a shell.ended event with the merged output after.",
+          }),
+        ),
+    )
     .add(
       HttpApiEndpoint.post("session.skill", "/api/session/:sessionID/skill", {
         params: { sessionID: Session.ID },

packages/sdk/js/src/v2/gen/sdk.gen.ts

@@ -365,6 +365,8 @@ import type {
   V2SessionRevertCommitResponses,
   V2SessionRevertStageErrors,
   V2SessionRevertStageResponses,
+  V2SessionShellErrors,
+  V2SessionShellResponses,
   V2SessionSkillErrors,
   V2SessionSkillResponses,
   V2SessionSwitchAgentErrors,
@@ -5413,6 +5415,43 @@ export class Session3 extends HeyApiClient {
     })
   }
 
+  /**
+   * Run shell command
+   *
+   * Execute one shell command in the session's working directory. Emits a shell.started event before execution and a shell.ended event with the merged output after.
+   */
+  public shell<ThrowOnError extends boolean = false>(
+    parameters: {
+      sessionID: string
+      id?: string
+      command?: string
+    },
+    options?: Options<never, ThrowOnError>,
+  ) {
+    const params = buildClientParams(
+      [parameters],
+      [
+        {
+          args: [
+            { in: "path", key: "sessionID" },
+            { in: "body", key: "id" },
+            { in: "body", key: "command" },
+          ],
+        },
+      ],
+    )
+    return (options?.client ?? this.client).post<V2SessionShellResponses, V2SessionShellErrors, ThrowOnError>({
+      url: "/api/session/{sessionID}/shell",
+      ...options,
+      ...params,
+      headers: {
+        "Content-Type": "application/json",
+        ...options?.headers,
+        ...params.headers,
+      },
+    })
+  }
+
   /**
    * Activate skill
    *

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -11504,6 +11504,44 @@ export type V2SessionPromptResponses = {
 
 export type V2SessionPromptResponse = V2SessionPromptResponses[keyof V2SessionPromptResponses]
 
+export type V2SessionShellData = {
+  body: {
+    id?: string
+    command: string
+  }
+  path: {
+    sessionID: string
+  }
+  query?: never
+  url: "/api/session/{sessionID}/shell"
+}
+
+export type V2SessionShellErrors = {
+  /**
+   * InvalidRequestError
+   */
+  400: InvalidRequestError
+  /**
+   * UnauthorizedError
+   */
+  401: UnauthorizedError
+  /**
+   * SessionNotFoundError
+   */
+  404: SessionNotFoundError
+}
+
+export type V2SessionShellError = V2SessionShellErrors[keyof V2SessionShellErrors]
+
+export type V2SessionShellResponses = {
+  /**
+   * <No Content>
+   */
+  204: void
+}
+
+export type V2SessionShellResponse = V2SessionShellResponses[keyof V2SessionShellResponses]
+
 export type V2SessionSkillData = {
   body: {
     id?: string