@opengeni/api-router 0.5.7 → 0.7.3

package/src/routes/sessions.ts

@@ -12,6 +12,7 @@ import {
   FsMoveRequest,
   FsReadRequest,
   FsWriteRequest,
+  HumanInputRequestStatus,
   GitDiffRequest,
   GitLogRequest,
   GitShowRequest,
@@ -22,6 +23,12 @@ import {
   PtyResizeRequest,
   PtyWriteRequest,
   SessionControlRequest,
+  SESSION_EVENT_RAW_DELTA_TYPES,
+  SessionEventPayloadMode,
+  SessionEventReadDirection,
+  SessionEventReadMode,
+  SessionEventSemanticClass,
+  SessionEventType,
   SaveComposerDraftRequest,
   SteerSessionQueueItemRequest,
   SteerSessionMessageRequest,
@@ -30,8 +37,12 @@ import {
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
   ViewerHeartbeatRequest,
+  WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  workspaceControlUtf8Bytes,
   type SandboxBackend,
   type Session,
+  type SessionAuthorizationOperation,
+  type SessionQueueSnapshot,
   type TerminalPtyExitedPayload,
   type TerminalPtyOutputDeltaPayload,
   type TerminalPtyStartedPayload,
@@ -39,6 +50,7 @@ import {
 import { streamTokenDegraded } from "@opengeni/config";
 import {
   acceptSessionApprovalDecision,
+  acceptSessionHumanInputResponse,
   clearSessionGoal,
   clearSessionContext,
   closePtySession,
@@ -47,13 +59,17 @@ import {
   getSession,
   getSessionForSubject,
   getSessionGoal,
+  getSessionHumanInputRequest,
   getSessionQueueSnapshot,
   getStreamAcknowledgment,
   insertPtySession,
-  listSessionEvents,
+  listSessionEventPage,
+  listSessionHumanInputRequests,
   listSessionIdsInGroup,
   listSessionsForSubject,
   listSessionTurns,
+  projectEffectiveControlForRelatedAccess,
+  projectSessionForRelatedAccess,
   recordStreamAcknowledgment,
   requestSessionCompaction,
   setSessionCodexPin,
@@ -71,21 +87,31 @@ import {
   SessionCommandIdempotencyError,
   SessionControlConflictError,
   SessionContextBusyError,
+  HumanInputResponseValidationError,
   latestWorkspaceCapture,
   workspaceCaptureAtRevision,
   type AppendEventInput,
 } from "@opengeni/db";
 import {
   appendAndPublishEvents,
+  boundSessionEventHttpPage,
   coalesceSessionEventDeltas,
   publishDurableSessionEvents,
 } from "@opengeni/events";
 import { z } from "zod";
 import { withChannelA } from "../sandbox/channel-a";
 import { negotiateCapabilities } from "@opengeni/runtime/sandbox";
-import type { Context, Hono } from "hono";
+import type { Context, Hono, MiddlewareHandler } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant } from "@opengeni/core";
+import {
+  requireAccessGrant,
+  requireSessionAuthorization,
+  requireSessionAuthorizationListScope,
+  SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  type ResolvedSessionAuthorization,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   attachViewer,
@@ -119,6 +145,60 @@ import { serveWorkspaceCapture, serveWorkspaceCaptureFile } from "./workspace-ca
 
 export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
+  const requestSessionAuthorization = new WeakMap<Request, ResolvedSessionAuthorization>();
+  const relatedSessionAccessFor = (c: Context): "target" | "root" =>
+    requestSessionAuthorization.get(c.req.raw)?.relatedSessionAccess ?? "root";
+  const projectQueueSnapshot = (
+    snapshot: SessionQueueSnapshot,
+    sessionId: string,
+    access: "target" | "root",
+  ): SessionQueueSnapshot => ({
+    ...snapshot,
+    effectiveControl: projectEffectiveControlForRelatedAccess(
+      snapshot.effectiveControl,
+      sessionId,
+      access,
+    ),
+  });
+
+  // A host-bound deployment has one fail-closed authorization seam for every
+  // HTTP session surface. Register it before the routes so a newly added path
+  // cannot accidentally inherit workspace access without an explicit operation
+  // classification. The long-lived event stream performs its own initial check
+  // and bounded reauthorization below.
+  const authorizeSessionHttp: MiddlewareHandler = async (c, next) => {
+    if (!deps.sessionAuthorization) {
+      await next();
+      return;
+    }
+    const workspaceId = c.req.param("workspaceId") ?? "";
+    const sessionId = c.req.param("sessionId") ?? "";
+    const operation = sessionAuthorizationOperationForHttp(
+      c.req.method,
+      new URL(c.req.url).pathname,
+      sessionId,
+    );
+    if (operation === "session.stream.read") {
+      await next();
+      return;
+    }
+    if (!operation) {
+      throw sessionAuthorizationHttpError(new SessionAuthorizationUnavailableError());
+    }
+    const grant = await requireAccessGrant(c, deps, workspaceId);
+    try {
+      const authorization = await requireSessionAuthorization(deps, grant, {
+        sessionId,
+        operation,
+        surface: "http",
+      });
+      if (authorization) requestSessionAuthorization.set(c.req.raw, authorization);
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
+    await next();
+  };
+  app.use("/v1/workspaces/:workspaceId/sessions/:sessionId/*", authorizeSessionHttp);
 
   app.post("/v1/workspaces/:workspaceId/sessions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -130,6 +210,12 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/sessions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    let authorizationScope;
+    try {
+      authorizationScope = await requireSessionAuthorizationListScope(deps, grant, "http");
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
     const pageView = c.req.query("view") === "page";
     const query = sessionListQuery(c.req.query(), pageView);
     let page: Awaited<ReturnType<typeof listSessionsForSubject>>;
@@ -140,6 +226,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         ...(query.cursor ? { cursor: query.cursor } : {}),
         ...(query.search ? { search: query.search } : {}),
         ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
+        ...(authorizationScope ? { authorizationScope } : {}),
       });
     } catch (error) {
       if (error instanceof SessionListAccessError) {
@@ -150,6 +237,10 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       throw error;
     }
+    // The page body carries this fact directly. Preserve the historical array
+    // body for older clients while still making its older-pin omission visible
+    // to raw HTTP consumers without changing that response shape.
+    c.header("x-opengeni-pinned-truncated", page.pinnedTruncated === true ? "true" : "false");
     if (pageView) {
       return c.json(page);
     }
@@ -168,7 +259,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!z.string().uuid().safeParse(sessionId).success) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    const session = await getSessionForSubject(db, workspaceId, sessionId, grant.subjectId);
+    const session = await getSessionForSubject(
+      db,
+      workspaceId,
+      sessionId,
+      grant.subjectId,
+      relatedSessionAccessFor(c),
+    );
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
@@ -199,14 +296,17 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (!session) {
         throw new HTTPException(404, { message: "session not found" });
       }
-      return c.json(session);
+      return c.json(projectSessionForRelatedAccess(session, relatedSessionAccessFor(c)));
     } catch (error) {
       if (error instanceof SessionPinAccessError) {
         throw new HTTPException(403, { message: error.message });
       }
       if (error instanceof SessionPinVersionConflictError) {
         return c.json(
-          { message: "session pin changed in another client", current: error.current },
+          {
+            message: "session pin changed in another client",
+            current: error.current,
+          },
           409,
         );
       }
@@ -216,8 +316,8 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/lineage", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
-    return c.json(await readSessionLineage(db, workspaceId, c.req.param("sessionId")));
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    return c.json(await readSessionLineage(deps, grant, c.req.param("sessionId")));
   });
 
   // Pin (or unpin) the session's Codex account. body { target: "auto" | "<id>" }:
@@ -232,7 +332,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const body = (await c.req.json()) as { target?: string };
     const target = typeof body.target === "string" ? body.target : "";
     if (!target) {
-      throw new HTTPException(400, { message: 'target is required ("auto" or an account id)' });
+      throw new HTTPException(400, {
+        message: 'target is required ("auto" or an account id)',
+      });
     }
     const pinned = target === "auto" ? null : target;
     const mutation = await withCodexCapacityMutation(
@@ -245,7 +347,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     const ok = mutation.result;
     if (!ok) {
-      throw new HTTPException(404, { message: "session or codex account not found" });
+      throw new HTTPException(404, {
+        message: "session or codex account not found",
+      });
     }
     await Promise.allSettled(
       mutation.wakeTargets.map((wake) =>
@@ -279,11 +383,17 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = UpdateSessionRequest.parse(await c.req.json());
-    await updateSessionTitle({ db, bus }, workspaceId, sessionId, payload.title, "user");
+    const titleUpdate = await updateSessionTitle(deps, grant, sessionId, payload.title, "user");
     // A session-returning member route must preserve the caller's private pin
     // projection. Returning the generic mapSession() default here would reset a
     // pinned React consumer to false/version 0 after a harmless rename.
-    const session = await getSessionForSubject(db, workspaceId, sessionId, grant.subjectId);
+    const session = await getSessionForSubject(
+      db,
+      workspaceId,
+      sessionId,
+      grant.subjectId,
+      titleUpdate.relatedSessionAccess,
+    );
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
@@ -464,7 +574,10 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       workflowId: requested.temporalWorkflowId,
       wakeRevision: requested.wakeRevision,
     });
-    return c.json({ status: "pending", message: "Compaction will run at the next safe boundary." });
+    return c.json({
+      status: "pending",
+      message: "Compaction will run at the next safe boundary.",
+    });
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events", async (c) => {
@@ -472,22 +585,136 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     await assertSessionExists(db, workspaceId, sessionId);
-    const after = eventSequence(c.req.query("after"), 0);
-    const before = optionalEventSequence(c.req.query("before"));
+    const rawAfter = c.req.query("after");
+    const rawBefore = c.req.query("before");
+    const after = eventSequence(rawAfter, 0);
+    const before = optionalEventSequence(rawBefore);
     const compact = compactEvents(c.req.query("compact"));
-    const limit = eventListLimit(c.req.query("limit"), compact ? 5000 : 2000);
-    const events = await listSessionEvents(db, workspaceId, sessionId, {
+    const explicitReplay = rawAfter !== undefined || rawBefore !== undefined || compact;
+    const mode = eventEnumValue(
+      c.req.query("mode"),
+      SessionEventReadMode,
+      "mode",
+      explicitReplay ? "forensic" : "monitoring",
+    );
+    const latestClass = eventEnumValue(
+      c.req.query("latest"),
+      SessionEventSemanticClass,
+      "latest",
+      undefined,
+    );
+    if (
+      latestClass &&
+      ["includeTypes", "excludeTypes", "includeClasses", "excludeClasses"].some(
+        (name) => c.req.query(name) !== undefined,
+      )
+    ) {
+      throw new HTTPException(400, {
+        message: "latest cannot be combined with event filters",
+      });
+    }
+    const direction = latestClass
+      ? "before"
+      : eventEnumValue(
+          c.req.query("direction"),
+          SessionEventReadDirection,
+          "direction",
+          before !== undefined
+            ? "before"
+            : rawAfter !== undefined
+              ? "after"
+              : mode === "monitoring"
+                ? "before"
+                : "after",
+        );
+    const payloadMode = eventEnumValue(
+      c.req.query("payloadMode"),
+      SessionEventPayloadMode,
+      "payloadMode",
+      mode === "monitoring" ? "summary" : "full",
+    );
+    const includeTypes = eventEnumList(
+      c.req.query("includeTypes"),
+      SessionEventType,
+      "includeTypes",
+    );
+    const excludeTypes = eventEnumList(
+      c.req.query("excludeTypes"),
+      SessionEventType,
+      "excludeTypes",
+    );
+    const includeClasses = eventEnumList(
+      c.req.query("includeClasses"),
+      SessionEventSemanticClass,
+      "includeClasses",
+    );
+    const excludeClasses = eventEnumList(
+      c.req.query("excludeClasses"),
+      SessionEventSemanticClass,
+      "excludeClasses",
+    );
+    const limit = latestClass
+      ? 1
+      : eventListLimit(
+          c.req.query("limit"),
+          compact ? 5000 : mode === "monitoring" ? 250 : 2000,
+          mode === "monitoring" ? 40 : 500,
+        );
+    const dbPage = await listSessionEventPage(db, workspaceId, sessionId, {
       after,
       ...(before !== undefined ? { before } : {}),
       limit,
+      direction,
+      payloadMode,
+      includeTypes,
+      excludeTypes,
+      includeClasses: latestClass ? [latestClass] : includeClasses,
+      excludeClasses,
+      ...(mode === "monitoring" ? { defaultExcludeTypes: SESSION_EVENT_RAW_DELTA_TYPES } : {}),
+    });
+    const events = dbPage.events;
+    const projected = compact ? coalesceSessionEventDeltas(events) : events;
+    const page = boundSessionEventHttpPage(projected, {
+      direction,
     });
-    return c.json(compact ? coalesceSessionEventDeltas(events) : events);
+    const hasMore = dbPage.hasMore || page.truncated;
+    c.header("X-OpenGeni-Page-Bytes", String(page.bytes));
+    c.header("X-OpenGeni-Page-Max-Bytes", String(1024 * 1024));
+    c.header("X-OpenGeni-Page-Truncated", String(hasMore));
+    c.header("X-OpenGeni-Has-More", String(hasMore));
+    c.header("X-OpenGeni-Event-Mode", mode);
+    c.header("X-OpenGeni-Event-Direction", direction);
+    c.header("X-OpenGeni-Payload-Mode", payloadMode);
+    c.header("X-OpenGeni-Forensic-Exact", String(mode === "forensic" && payloadMode === "full"));
+    const coveredFirst = page.events[0]?.sequence;
+    const coveredLast = page.events.at(-1)?.sequence;
+    if (coveredFirst !== undefined) c.header("X-OpenGeni-Covered-First", String(coveredFirst));
+    if (coveredLast !== undefined) c.header("X-OpenGeni-Covered-Last", String(coveredLast));
+    const truncatedBy = page.truncated ? "http_bytes" : dbPage.truncatedBy;
+    if (truncatedBy) c.header("X-OpenGeni-Truncated-By", truncatedBy);
+    if (page.nextSequence !== null) {
+      c.header(
+        direction === "before" ? "X-OpenGeni-Next-Before" : "X-OpenGeni-Next-After",
+        String(page.nextSequence),
+      );
+    }
+    return c.json(page.events);
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/events/stream", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
+    let authorization;
+    try {
+      authorization = await requireSessionAuthorization(deps, grant, {
+        sessionId,
+        operation: "session.stream.read",
+        surface: "stream",
+      });
+    } catch (error) {
+      throw sessionAuthorizationHttpError(error);
+    }
     await assertSessionExists(db, workspaceId, sessionId);
     const after = Number(c.req.query("after") ?? c.req.header("Last-Event-ID") ?? 0);
     return sseSessionStream(
@@ -497,6 +724,22 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       sessionId,
       Number.isFinite(after) ? after : 0,
       c.req.raw.signal,
+      {
+        observability: deps.observability,
+        ...(authorization
+          ? {
+              reauthorizeAfterMs:
+                authorization.reauthorizeAfterMs ?? SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
+              reauthorize: async () => {
+                await requireSessionAuthorization(deps, grant, {
+                  sessionId,
+                  operation: "session.stream.read",
+                  surface: "stream",
+                });
+              },
+            }
+          : {}),
+      },
     );
   });
 
@@ -516,7 +759,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const sessionId = c.req.param("sessionId");
     const snapshot = await getSessionQueueSnapshot(db, workspaceId, sessionId);
     if (!snapshot) throw new HTTPException(404, { message: "session not found" });
-    return c.json(snapshot);
+    return c.json(projectQueueSnapshot(snapshot, sessionId, relatedSessionAccessFor(c)));
   });
 
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/queue/:turnId/move", async (c) => {
@@ -526,14 +769,21 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = MoveSessionQueueItemRequest.parse(await c.req.json());
     try {
-      return c.json(
-        await moveHumanQueuePrompt(
-          { db, bus },
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
-          c.req.param("turnId"),
-          payload,
-        ),
+      const response = await moveHumanQueuePrompt(
+        deps,
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+        },
+        c.req.param("turnId"),
+        payload,
       );
+      return c.json({
+        ...response,
+        snapshot: projectQueueSnapshot(response.snapshot, sessionId, relatedSessionAccessFor(c)),
+      });
     } catch (error) {
       return commandConflictResponse(c, error);
     }
@@ -546,14 +796,21 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = EditSessionQueueItemRequest.parse(await c.req.json());
     try {
-      return c.json(
-        await editHumanQueuePrompt(
-          { db, bus },
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
-          c.req.param("turnId"),
-          payload,
-        ),
+      const response = await editHumanQueuePrompt(
+        deps,
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+        },
+        c.req.param("turnId"),
+        payload,
       );
+      return c.json({
+        ...response,
+        snapshot: projectQueueSnapshot(response.snapshot, sessionId, relatedSessionAccessFor(c)),
+      });
     } catch (error) {
       return commandConflictResponse(c, error);
     }
@@ -566,14 +823,21 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = SteerSessionQueueItemRequest.parse(await c.req.json());
     try {
-      return c.json(
-        await steerHumanQueuePrompt(
-          { db, bus },
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
-          c.req.param("turnId"),
-          payload,
-        ),
+      const response = await steerHumanQueuePrompt(
+        deps,
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+        },
+        c.req.param("turnId"),
+        payload,
       );
+      return c.json({
+        ...response,
+        snapshot: projectQueueSnapshot(response.snapshot, sessionId, relatedSessionAccessFor(c)),
+      });
     } catch (error) {
       return commandConflictResponse(c, error);
     }
@@ -586,14 +850,21 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     await assertSessionExists(db, workspaceId, sessionId);
     const payload = DeleteSessionQueueItemRequest.parse(await c.req.json());
     try {
-      return c.json(
-        await deleteHumanQueuePrompt(
-          { db, bus },
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
-          c.req.param("turnId"),
-          payload,
-        ),
+      const response = await deleteHumanQueuePrompt(
+        deps,
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+        },
+        c.req.param("turnId"),
+        payload,
       );
+      return c.json({
+        ...response,
+        snapshot: projectQueueSnapshot(response.snapshot, sessionId, relatedSessionAccessFor(c)),
+      });
     } catch (error) {
       return commandConflictResponse(c, error);
     }
@@ -604,7 +875,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:read");
     const sessionId = c.req.param("sessionId");
     return c.json(
-      await getHumanComposerDraft(db, {
+      await getHumanComposerDraft(deps, {
         accountId: grant.accountId,
         workspaceId,
         sessionId,
@@ -621,8 +892,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     try {
       return c.json(
         await saveHumanComposerDraft(
-          db,
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
+          deps,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            sessionId,
+            subjectId: grant.subjectId,
+          },
           payload,
         ),
       );
@@ -634,16 +910,33 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/control", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
+      throw new HTTPException(400, { message: "workspace-control actor is too large" });
+    }
     const sessionId = c.req.param("sessionId");
-    const payload = SessionControlRequest.parse(await c.req.json());
+    const parsed = SessionControlRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid session control request" });
+    }
     try {
-      return c.json(
-        await controlHumanSessionWorkstream(
-          { db, bus, workflowClient },
-          { accountId: grant.accountId, workspaceId, sessionId, subjectId: grant.subjectId },
-          payload,
-        ),
+      const response = await controlHumanSessionWorkstream(
+        deps,
+        {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          subjectId: grant.subjectId,
+        },
+        parsed.data,
       );
+      return c.json({
+        ...response,
+        effectiveControl: projectEffectiveControlForRelatedAccess(
+          response.effectiveControl,
+          sessionId,
+          relatedSessionAccessFor(c),
+        ),
+      });
     } catch (error) {
       return commandConflictResponse(c, error);
     }
@@ -658,6 +951,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const payload = SteerSessionMessageRequest.parse(raw);
     const result = await acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
       text: payload.text,
+      turnInstructions: payload.turnInstructions ?? null,
       resources: payload.resources,
       tools: payload.tools,
       toolsProvided: userMessagePayloadHasOwnProperty({ payload: raw }, "tools"),
@@ -681,9 +975,27 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const sessionId = c.req.param("sessionId");
     const rawEvent = await c.req.json();
     const event = ClientSessionEvent.parse(rawEvent);
+    const refinedOperation =
+      event.type === "user.approvalDecision"
+        ? "session.approval.write"
+        : event.type === "user.humanInputResponse"
+          ? "session.human_input.write"
+          : null;
+    if (refinedOperation) {
+      try {
+        await requireSessionAuthorization(deps, grant, {
+          sessionId,
+          operation: refinedOperation,
+          surface: "http",
+        });
+      } catch (error) {
+        throw sessionAuthorizationHttpError(error);
+      }
+    }
     if (event.type === "user.message") {
       const { accepted } = await acceptSessionUserMessage(deps, grant, workspaceId, sessionId, {
         text: event.payload.text,
+        turnInstructions: event.payload.turnInstructions ?? null,
         resources: event.payload.resources ?? [],
         tools: event.payload.tools ?? [],
         toolsProvided: userMessagePayloadHasOwnProperty(rawEvent, "tools"),
@@ -726,8 +1038,83 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       });
       return c.json(accepted.event, 202);
     }
+
+    if (event.type === "user.humanInputResponse") {
+      let accepted;
+      try {
+        accepted = await acceptSessionHumanInputResponse(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          requestId: event.payload.requestId,
+          response: event.payload.response,
+          respondedBy: grant.subjectId,
+          clientEventId: event.clientEventId ?? null,
+        });
+      } catch (error) {
+        if (error instanceof HumanInputResponseValidationError) {
+          throw new HTTPException(error.code === "SKIP_NOT_ALLOWED" ? 409 : 422, {
+            message: error.message,
+          });
+        }
+        throw error;
+      }
+      if (accepted.action === "not_found") {
+        throw new HTTPException(404, { message: "human-input request not found" });
+      }
+      await publishDurableSessionEvents(bus, workspaceId, sessionId, accepted.events);
+      if (accepted.workflowWakeRevision !== null) {
+        await workflowClient.signalApprovalDecision({
+          accountId: grant.accountId,
+          workspaceId,
+          sessionId,
+          eventId: accepted.events[0]?.id ?? event.payload.requestId,
+          workflowId: workflowIdForSession(sessionId),
+          workflowWakeRevision: accepted.workflowWakeRevision,
+        });
+      }
+      if (accepted.action === "conflict") {
+        throw new HTTPException(409, {
+          message: `human-input request is ${accepted.request.status}`,
+        });
+      }
+      return c.json(accepted.event, 202);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/human-input-requests", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    const sessionId = c.req.param("sessionId");
+    await assertSessionExists(db, workspaceId, sessionId);
+    const rawStatus = c.req.query("status");
+    const status = rawStatus ? HumanInputRequestStatus.safeParse(rawStatus) : null;
+    if (status && !status.success) {
+      throw new HTTPException(400, { message: "invalid human-input request status" });
+    }
+    const requests = await listSessionHumanInputRequests(db, workspaceId, sessionId, {
+      ...(status?.success ? { status: status.data } : {}),
+    });
+    return c.json({ requests });
   });
 
+  app.get(
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/human-input-requests/:requestId",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+      const sessionId = c.req.param("sessionId");
+      const request = await getSessionHumanInputRequest(
+        db,
+        workspaceId,
+        sessionId,
+        c.req.param("requestId"),
+      );
+      if (!request) throw new HTTPException(404, { message: "human-input request not found" });
+      return c.json(request);
+    },
+  );
+
   // ── API-direct stream capabilities + viewer attach (P1.4) ─────────────────
   //
   // All IN-PROCESS: capability negotiation reads the descriptor + the group
@@ -781,6 +1168,7 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       { workspaceId, sandboxGroupId: session.sandboxGroupId },
     );
     const { shared, sharedSessionIds } = await resolveSharedExposure(workspaceId, session);
+    const visibleSharedSessionIds = relatedSessionAccessFor(c) === "root" ? sharedSessionIds : [];
     // Per-principal acknowledgment: A acknowledging does not consent for B. The
     // un-redacted desktop stream ALWAYS requires the un-redacted ack; a shared box
     // ADDITIONALLY requires the shared-exposure ack. Both must match the POST
@@ -872,13 +1260,13 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       // tracks the desktop tier + a desktop-capable backend.
       computerUseEnabled: settings.computerUseEnabled,
       computerUseReadOnly: settings.computerUseReadOnly,
-      // Graceful degrade (I8/OD-8): if desktop is enabled but no stream-token
+      // Graceful degrade (stream-token availability contract): if desktop is enabled but no stream-token
       // secret is resolvable, the desktop cell reports transport:null rather
       // than advertising a plane we can never authorize.
       streamTokenSecretAvailable: !streamTokenDegraded(settings),
       desktopAcknowledged: acknowledged,
       shared,
-      sharedSessionIds,
+      sharedSessionIds: visibleSharedSessionIds,
       // The minted live address (null when not unlocked/degraded). The resolver
       // only folds it in when the desktop gates pass + the ack is present.
       ...(desktopStream
@@ -960,7 +1348,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       const parsed = AcknowledgeStreamRequest.safeParse(await c.req.json().catch(() => ({})));
       if (!parsed.success) {
-        throw new HTTPException(400, { message: "invalid stream acknowledgment request" });
+        throw new HTTPException(400, {
+          message: "invalid stream acknowledgment request",
+        });
       }
       const recorded = await recordStreamAcknowledgment(db, {
         accountId: grant.accountId,
@@ -996,7 +1386,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
     const parsed = AttachViewerRequest.safeParse(await c.req.json().catch(() => ({})));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid viewer attach request" });
+      throw new HTTPException(400, {
+        message: "invalid viewer attach request",
+      });
     }
     // Consent gate (P3.2 / addendum E.1): ONLY the un-redacted DESKTOP pixel plane
     // requires the calling principal's acknowledgment (recorded per group+subject;
@@ -1017,10 +1409,14 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         subjectId: grant.subjectId,
       });
       if (!ack?.acknowledgedUnredacted) {
-        throw new HTTPException(409, { message: "stream_acknowledgment_required" });
+        throw new HTTPException(409, {
+          message: "stream_acknowledgment_required",
+        });
       }
       if (shared && !ack.acknowledgedShared) {
-        throw new HTTPException(409, { message: "shared_acknowledgment_required" });
+        throw new HTTPException(409, {
+          message: "shared_acknowledgment_required",
+        });
       }
     }
     // SELFHOSTED ACTIVE: when the session's active sandbox is selfhosted, skip
@@ -1177,7 +1573,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       }
       const parsed = ViewerHeartbeatRequest.safeParse(await c.req.json().catch(() => ({})));
       if (!parsed.success) {
-        throw new HTTPException(400, { message: "viewer heartbeat requires { leaseEpoch }" });
+        throw new HTTPException(400, {
+          message: "viewer heartbeat requires { leaseEpoch }",
+        });
       }
       const alive = await heartbeatViewer(
         { db, settings },
@@ -1240,7 +1638,10 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         idleGraceMs: settings.sandboxIdleGraceMs,
       });
       // null ⇒ the lease was already cold-and-reaped (revoke is an idempotent no-op).
-      return c.json({ liveness: result?.liveness ?? null, refcount: result?.refcount ?? null });
+      return c.json({
+        liveness: result?.liveness ?? null,
+        refcount: result?.refcount ?? null,
+      });
     },
   );
 
@@ -1281,12 +1682,19 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    return { accountId: grant.accountId, workspaceId, session, subjectId: grant.subjectId };
+    return {
+      accountId: grant.accountId,
+      workspaceId,
+      session,
+      subjectId: grant.subjectId,
+    };
   }
 
   async function parseChannelABody<T>(
     c: Context,
-    schema: { safeParse: (v: unknown) => { success: true; data: T } | { success: false } },
+    schema: {
+      safeParse: (v: unknown) => { success: true; data: T } | { success: false };
+    },
   ): Promise<T> {
     const raw = await c.req.json().catch(() => undefined);
     const result = schema.safeParse(raw ?? {});
@@ -1416,7 +1824,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     const sessionId = c.req.param("sessionId") ?? "";
     const path = c.req.query("path");
     if (!path) {
-      throw new HTTPException(400, { message: "path query parameter is required" });
+      throw new HTTPException(400, {
+        message: "path query parameter is required",
+      });
     }
     const session = await getSession(db, workspaceId, sessionId);
     if (!session) {
@@ -1431,7 +1841,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (revisionParam !== undefined && revisionParam !== "") {
       const revision = Number(revisionParam);
       if (!Number.isInteger(revision) || revision < 0) {
-        throw new HTTPException(400, { message: "revision must be a non-negative integer" });
+        throw new HTTPException(400, {
+          message: "revision must be a non-negative integer",
+        });
       }
       row = await workspaceCaptureAtRevision(db, workspaceId, sessionId, revision);
     } else {
@@ -1503,7 +1915,9 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(404, { message: "pty not found or closed" });
     }
     if (pty.execSessionId === null) {
-      throw new HTTPException(409, { message: "interactive terminal unsupported on this backend" });
+      throw new HTTPException(409, {
+        message: "interactive terminal unsupported on this backend",
+      });
     }
     let seq = 1;
     await withChannelA({ db, settings, bus }, ctx, async ({ service }) => {
@@ -1565,7 +1979,11 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
         workspaceId: ctx.workspaceId,
         ptyId: req.ptyId,
       });
-      const exited: TerminalPtyExitedPayload = { ptyId: req.ptyId, exitCode: 0, reason: "exit" };
+      const exited: TerminalPtyExitedPayload = {
+        ptyId: req.ptyId,
+        exitCode: 0,
+        reason: "exit",
+      };
       await appendAndPublishEvents(db, bus, ctx.workspaceId, ctx.session.id, [
         { type: "terminal.pty.exited", payload: exited },
       ]);
@@ -1574,14 +1992,157 @@ export function registerSessionRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
-function eventListLimit(raw: string | undefined, max = 2000): number {
-  const limit = Number(raw ?? 500);
+function eventListLimit(raw: string | undefined, max = 2000, fallback = 500): number {
+  const limit = Number(raw ?? fallback);
   if (!Number.isFinite(limit)) {
-    return 500;
+    return fallback;
   }
   return Math.min(max, Math.max(1, Math.floor(limit)));
 }
 
+/**
+ * Map every mounted session-addressed HTTP path to the host-neutral operation
+ * the embedding port authorizes. Returning null is deliberately fail-closed in
+ * host-managed mode; standalone deployments never consult this classifier.
+ */
+export function sessionAuthorizationOperationForHttp(
+  method: string,
+  pathname: string,
+  sessionId: string,
+): SessionAuthorizationOperation | null {
+  const marker = `/sessions/${sessionId}`;
+  const markerAt = pathname.indexOf(marker);
+  if (markerAt < 0) return null;
+  const suffix = pathname.slice(markerAt + marker.length);
+  const verb = method.toUpperCase();
+
+  if (suffix === "") {
+    if (verb === "GET") return "session.read";
+    if (verb === "PATCH") return "session.title.write";
+    return null;
+  }
+  if (suffix === "/pin" && verb === "PUT") return "session.pin.write";
+  if (suffix === "/lineage" && verb === "GET") return "session.lineage.read";
+  if (suffix === "/codex-account" && verb === "POST") {
+    return "session.codex_account.write";
+  }
+  if (suffix === "/goal") {
+    return verb === "GET"
+      ? "session.goal.read"
+      : ["PATCH", "DELETE"].includes(verb)
+        ? "session.goal.write"
+        : null;
+  }
+  if (suffix === "/context/clear" || suffix === "/context/compact") {
+    return verb === "POST" ? "session.context.write" : null;
+  }
+  if (suffix === "/events/stream" && verb === "GET") return "session.stream.read";
+  if (suffix === "/events") {
+    if (verb === "GET") return "session.events.read";
+    if (verb === "POST") return "session.append";
+    return null;
+  }
+  if (suffix === "/turns" && verb === "GET") return "session.turns.read";
+  if (suffix === "/queue" && verb === "GET") return "session.queue.read";
+  if (suffix.startsWith("/queue/") && verb === "POST") return "session.queue.control";
+  if (suffix === "/composer-draft") {
+    if (verb === "GET") return "session.composer.read";
+    if (verb === "PUT") return "session.composer.write";
+    return null;
+  }
+  if (suffix === "/control" && verb === "POST") return "session.control";
+  if (suffix === "/steer" && verb === "POST") return "session.steer";
+  if (suffix === "/human-input-requests" && verb === "GET") {
+    return "session.human_input.read";
+  }
+  if (suffix.startsWith("/human-input-requests/") && verb === "GET") {
+    return "session.human_input.read";
+  }
+  if (suffix === "/stream-capabilities" && verb === "GET") return "session.viewer.read";
+  if (suffix === "/stream-capabilities/acknowledge" && verb === "POST") {
+    return "session.stream.acknowledge";
+  }
+  if (suffix === "/viewers" && verb === "POST") return "session.viewer.control";
+  if (suffix.startsWith("/viewers/") && ["POST", "DELETE"].includes(verb)) {
+    return "session.viewer.control";
+  }
+  if (suffix === "/fs/list" || suffix === "/fs/read") {
+    return verb === "POST" ? "session.files.read" : null;
+  }
+  if (["/fs/write", "/fs/delete", "/fs/move", "/fs/mkdir"].includes(suffix)) {
+    return verb === "POST" ? "session.files.write" : null;
+  }
+  if (suffix.startsWith("/git/") && verb === "POST") return "session.git.read";
+  if ((suffix === "/workspace/capture" || suffix === "/workspace/capture/file") && verb === "GET") {
+    return "session.capture.read";
+  }
+  if (suffix === "/terminal/exec" && verb === "POST") return "session.terminal.control";
+  if (suffix === "/terminal/pty" && verb === "POST") return "session.terminal.control";
+  if (suffix.startsWith("/terminal/pty/") && verb === "POST") {
+    return "session.terminal.control";
+  }
+  return null;
+}
+
+function sessionAuthorizationHttpError(error: unknown): HTTPException {
+  if (error instanceof SessionAuthorizationDeniedError) {
+    return new HTTPException(404, { message: "session not found" });
+  }
+  if (error instanceof SessionAuthorizationUnavailableError) {
+    return new HTTPException(503, { message: "session authorization is unavailable" });
+  }
+  if (error instanceof HTTPException) return error;
+  throw error;
+}
+
+function eventEnumValue<T extends string>(
+  raw: string | undefined,
+  schema: { safeParse(value: unknown): { success: boolean; data?: T } },
+  name: string,
+  fallback: T,
+): T;
+function eventEnumValue<T extends string>(
+  raw: string | undefined,
+  schema: { safeParse(value: unknown): { success: boolean; data?: T } },
+  name: string,
+  fallback: undefined,
+): T | undefined;
+function eventEnumValue<T extends string>(
+  raw: string | undefined,
+  schema: { safeParse(value: unknown): { success: boolean; data?: T } },
+  name: string,
+  fallback: T | undefined,
+): T | undefined {
+  if (raw === undefined) return fallback;
+  const parsed = schema.safeParse(raw);
+  if (!parsed.success) {
+    throw new HTTPException(400, { message: `${name} is invalid` });
+  }
+  return parsed.data as T;
+}
+
+function eventEnumList<T extends string>(
+  raw: string | undefined,
+  schema: { safeParse(value: unknown): { success: boolean; data?: T } },
+  name: string,
+): T[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  const values = raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (values.length > 100) {
+    throw new HTTPException(400, { message: `${name} accepts at most 100 values` });
+  }
+  return values.map((value) => {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: `${name} contains an invalid value` });
+    }
+    return parsed.data as T;
+  });
+}
+
 function sessionListQuery(
   query: Record<string, string>,
   allowCursor = true,
@@ -1611,7 +2172,9 @@ function sessionListQuery(
   }
   const search = query.search?.trim();
   if (search && search.length > 200) {
-    throw new HTTPException(400, { message: "search must be at most 200 characters" });
+    throw new HTTPException(400, {
+      message: "search must be at most 200 characters",
+    });
   }
   return {
     limit: query.limit,