@saluzi/saluzi-edu 0.2.63 → 0.2.64

package/packages/remote-control-server/src/routes/v1/sessions.ts

@@ -1,19 +1,167 @@
 import { log, error as logError } from '../../logger'
 import { Hono } from 'hono'
 import {
+  archiveSession,
+  canManageSession,
   createSession,
   getSession,
-  updateSessionTitle,
-  archiveSession,
+  isSessionClosedStatus,
   resolveExistingSessionId,
+  updateSessionTitle,
 } from '../../services/session'
 import { createWorkItem } from '../../services/work-dispatch'
-import { apiKeyAuth, acceptCliHeaders } from '../../auth/middleware'
 import { publishSessionEvent } from '../../services/transport'
-import { storeBindSession, storeGetEnvironmentOwnership } from '../../store'
+import { loadPersistedEvents } from '../../services/event-persistence'
+import { getEventBus } from '../../transport/event-bus'
+import { acceptCliHeaders, apiKeyAuth } from '../../auth/middleware'
+import { bridgeAuth, resolveUserIdUuid } from '../../auth/bridge-auth'
+import { getDb } from '../../db/sqlite'
+import {
+  storeBindSession,
+  storeConsumeAttachCode,
+  storeGetEnvironment,
+  storeGetEnvironmentOwnership,
+  storeGetActiveWorkItemBySession,
+  storeListSessions,
+  storeListSessionsByEnvironment,
+  storeRebindSessionEnvironment,
+} from '../../store'
 
 const app = new Hono()
 
+// ---------------------------------------------------------------------------
+// Session Attach — bind an existing session to a CLI-registered environment
+// ---------------------------------------------------------------------------
+
+/** Caller identity resolved for attach endpoints. */
+type AttachCaller = {
+  /** Resolved users.id UUID — null for a bare admin API key. */
+  uuid: string | null
+  isApiAdmin: boolean
+  /** True when no identity at all was presented (bare admin API key). */
+  hasIdentity: boolean
+}
+
+/**
+ * Resolve the bridge caller identity for attach endpoints.
+ *
+ * bridgeAuth's userId may be a UUID (rct_* token), a username (in-memory
+ * token) or an arbitrary X-Username string (shared admin API key) — only
+ * users-table UUIDs can hold session management rights, so everything goes
+ * through resolveUserIdUuid (G9: the API layer must self-enforce
+ * canManageSession; the ingress WS accepting a global API key is not a
+ * boundary we may lean on).
+ */
+function resolveAttachCaller(c: import('hono').Context): AttachCaller {
+  const raw = c.get('userId') as string | undefined
+  const isApiAdmin = (c.get('isApiAdmin') as boolean | undefined) ?? false
+  if (!raw) {
+    return { uuid: null, isApiAdmin, hasIdentity: false }
+  }
+  return {
+    uuid: resolveUserIdUuid(getDb(), raw),
+    isApiAdmin,
+    hasIdentity: true,
+  }
+}
+
+/**
+ * Management check for attach endpoints. Returns an error Response, or null
+ * when the caller may manage the session:
+ * - rct (SQLite) or in-memory identity → must resolve to a user with manage
+ *   rights (canManageSession: direct owner, team owner/admin, system admin)
+ * - bare admin API key (no identity) → allowed with an audit trail
+ *   (RCS_API_KEYS are admin credentials — mirrors validateTeamBinding)
+ */
+function ensureAttachAccess(
+  c: import('hono').Context,
+  caller: AttachCaller,
+  sessionId: string,
+): Response | null {
+  if (caller.uuid) {
+    if (!canManageSession(sessionId, caller.uuid, getDb())) {
+      return c.json(
+        {
+          error: {
+            type: 'forbidden',
+            message: 'Not allowed to manage this session',
+          },
+        },
+        403,
+      )
+    }
+    return null
+  }
+  if (!caller.hasIdentity && caller.isApiAdmin) {
+    console.log(`[audit] Bare admin API key attached session ${sessionId}`)
+    return null
+  }
+  return c.json(
+    {
+      error: {
+        type: caller.hasIdentity ? 'forbidden' : 'unauthorized',
+        message: caller.hasIdentity
+          ? 'Identity does not resolve to a user'
+          : 'User identity required to attach sessions',
+      },
+    },
+    caller.hasIdentity ? 403 : 401,
+  )
+}
+
+/**
+ * Occupancy check shared by POST /:id/attach and GET /attachable.
+ * A session is occupied when:
+ * 1. A non-completed work item exists on a DIFFERENT, STILL-ACTIVE
+ *    environment (a live worker holds the lease). A work item on a
+ *    dead/deregistered env does NOT occupy: a crashed attach CLI's acked
+ *    item would otherwise block re-attach forever (deregisterEnvironment
+ *    completes that env's open items too, but a kill -9 that skips the
+ *    deregister leaves the item behind until the server restarts — the
+ *    env-status check is the recovery path).
+ * 2. No work item remains but the session is mid-turn (running /
+ *    requires_action) on a live, active, non-ACP environment.
+ * An active work item on the TARGET environment is not occupied — that is
+ * the idempotent re-entry path (CLI retry after a network blip).
+ */
+function isSessionOccupied(
+  sessionId: string,
+  targetEnvId: string | null,
+): boolean {
+  const active = storeGetActiveWorkItemBySession(sessionId)
+  if (active) {
+    if (active.environmentId === targetEnvId) return false
+    const holdingEnv = storeGetEnvironment(active.environmentId)
+    // No env record / not active → the lease holder is gone; the session is
+    // free to attach.
+    if (!holdingEnv || holdingEnv.status !== 'active') return false
+    return true
+  }
+  const session = getSession(sessionId)
+  if (!session) return false
+  if (session.status !== 'running' && session.status !== 'requires_action') {
+    return false
+  }
+  if (!session.environment_id || session.environment_id === targetEnvId) {
+    return false
+  }
+  const curEnv = storeGetEnvironment(session.environment_id)
+  return !!curEnv && curEnv.status === 'active' && curEnv.workerType !== 'acp'
+}
+
+/** Shape returned by GET /attachable and consumed by the CLI picker. */
+function toAttachableEntry(session: ReturnType<typeof getSession>) {
+  return {
+    id: session!.id,
+    title: session!.title,
+    status: session!.status,
+    source: session!.source,
+    environment_id: session!.environment_id ?? null,
+    updated_at: session!.updated_at,
+    busy: isSessionOccupied(session!.id, null),
+  }
+}
+
 /** POST /v1/sessions — Create session.
  *  Used by replBridge/ACP workers to auto-create their initial session.
  *  Session ownership: user owner = env.owner_user_id, team owner = env.team_id
@@ -84,6 +232,412 @@ app.post('/', acceptCliHeaders, apiKeyAuth, async c => {
   return c.json(session, 200)
 })
 
+/** GET /v1/sessions/attachable — List sessions the caller can attach to.
+ *  Must be registered BEFORE GET /:id so "attachable" is not captured as an
+ *  id. Visibility = canManageSession (direct owner, team owner/admin, system
+ *  admin); bare admin API key sees all. ACP sessions are excluded — their
+ *  transport is bound to the acp-link WS and cannot be driven by a bridge
+ *  worker. */
+app.get('/attachable', bridgeAuth, async c => {
+  const caller = resolveAttachCaller(c)
+  if (caller.uuid === null && caller.hasIdentity && !caller.isApiAdmin) {
+    return c.json(
+      {
+        error: {
+          type: 'forbidden',
+          message: 'Identity does not resolve to a user',
+        },
+      },
+      403,
+    )
+  }
+  if (caller.uuid === null && !caller.hasIdentity && !caller.isApiAdmin) {
+    return c.json(
+      { error: { type: 'unauthorized', message: 'User identity required' } },
+      401,
+    )
+  }
+
+  const db = getDb()
+  const attachable = storeListSessions()
+    .filter(s => !isSessionClosedStatus(s.status))
+    .filter(s => s.source !== 'acp')
+    .filter(
+      s => caller.uuid === null || canManageSession(s.id, caller.uuid, db),
+    )
+    .map(s => toAttachableEntry(getSession(s.id)))
+
+  return c.json(attachable, 200)
+})
+
+/** POST /v1/sessions/:id/attach — Bind an existing session to a CLI
+ *  environment (Session Attach). Re-points session.environment_id (ownership
+ *  in session_owners is NEVER touched) and dispatches a work item so the
+ *  polling worker picks the session up through the standard work path.
+ *  Idempotent: an active work item on the same environment returns 200 with
+ *  the existing binding instead of 409 (CLI network retries). */
+app.post('/:id/attach', bridgeAuth, async c => {
+  const caller = resolveAttachCaller(c)
+  const sessionId =
+    resolveExistingSessionId(c.req.param('id')!) ?? c.req.param('id')!
+  const body = await c.req.json().catch(() => ({}) as Record<string, unknown>)
+  const envId =
+    typeof body.environment_id === 'string' ? body.environment_id : undefined
+  if (!envId) {
+    return c.json(
+      {
+        error: {
+          type: 'bad_request',
+          message: 'environment_id is required',
+        },
+      },
+      400,
+    )
+  }
+  return performAttach(c, {
+    sessionId,
+    envId,
+    caller,
+    skipAccessCheck: false,
+  })
+})
+
+/**
+ * Core attach logic shared by POST /:id/attach (identity-based) and
+ * POST /attach-code/exchange (code-based — the one-time code replaces the
+ * caller's own manage rights, everything else is identical).
+ */
+async function performAttach(
+  c: import('hono').Context,
+  opts: {
+    sessionId: string
+    envId: string
+    caller: AttachCaller
+    skipAccessCheck: boolean
+  },
+): Promise<Response> {
+  const { sessionId, envId, caller, skipAccessCheck } = opts
+  const session = getSession(sessionId)
+  if (!session) {
+    return c.json(
+      { error: { type: 'not_found', message: 'Session not found' } },
+      404,
+    )
+  }
+
+  // Idempotent re-entry BEFORE authorization: a CLI retrying after a network
+  // blip re-presents the same session+env pair — returning the existing
+  // binding is not a new grant, so it must not depend on the caller still
+  // holding manage rights (e.g. a doReconnect re-bind where the bound
+  // session was assigned by a team admin, or an expired share). The check
+  // only matches an existing work item on the SAME environment — no state
+  // is created.
+  const activeItem = storeGetActiveWorkItemBySession(sessionId)
+  if (activeItem && activeItem.environmentId === envId) {
+    log(
+      `[RCS] Attach idempotent re-entry: session=${sessionId} env=${envId} work=${activeItem.id}`,
+    )
+    return c.json(
+      {
+        status: 'attached',
+        session_id: sessionId,
+        work_item_id: activeItem.id,
+        rebind: false,
+        idempotent: true,
+      },
+      200,
+    )
+  }
+
+  // Authorization: identity-based attach requires manage rights (G9). The
+  // code-based path skips this — presenting a valid unconsumed code IS the
+  // authorization (the code was minted by a session manager).
+  if (!skipAccessCheck) {
+    const accessError = ensureAttachAccess(c, caller, sessionId)
+    if (accessError) return accessError
+  }
+
+  if (isSessionClosedStatus(session.status)) {
+    return c.json(
+      {
+        error: {
+          type: 'session_closed',
+          message: `Session is ${session.status}`,
+        },
+      },
+      409,
+    )
+  }
+
+  // ACP sessions are transport-bound to the acp-link WebSocket.
+  if (session.source === 'acp') {
+    return c.json(
+      {
+        error: {
+          type: 'acp_session',
+          message: 'ACP sessions cannot be attached to a bridge worker',
+        },
+      },
+      409,
+    )
+  }
+
+  const env = storeGetEnvironment(envId)
+  if (!env || env.status === 'deregistered') {
+    return c.json(
+      { error: { type: 'not_found', message: 'Environment not found' } },
+      404,
+    )
+  }
+  if (env.status !== 'active') {
+    return c.json(
+      {
+        error: {
+          type: 'environment_inactive',
+          message: `Environment is ${env.status}`,
+        },
+      },
+      409,
+    )
+  }
+  if (env.workerType === 'acp') {
+    return c.json(
+      {
+        error: {
+          type: 'acp_environment',
+          message: 'ACP environments manage their own sessions',
+        },
+      },
+      409,
+    )
+  }
+
+  // Environment ownership: the attaching worker must be driving an env it
+  // owns (the env it just registered). Admin may attach on behalf.
+  const ownership = storeGetEnvironmentOwnership(envId)
+  if (!ownership?.ownerUserId) {
+    return c.json(
+      {
+        error: {
+          type: 'environment_unowned',
+          message:
+            'Environment has no owner yet; claim it via the printed URL before attaching sessions',
+        },
+      },
+      409,
+    )
+  }
+  if (!caller.isApiAdmin && ownership.ownerUserId !== caller.uuid) {
+    return c.json(
+      {
+        error: {
+          type: 'forbidden',
+          message: 'Cannot attach to an environment owned by another user',
+        },
+      },
+      403,
+    )
+  }
+
+  // In-process (replBridge) workers serve exactly one session at a time.
+  if (env.workerType === 'repl') {
+    const openOthers = storeListSessionsByEnvironment(envId).filter(
+      s => s.id !== sessionId && !isSessionClosedStatus(s.status),
+    )
+    if (openOthers.length > 0) {
+      return c.json(
+        {
+          error: {
+            type: 'worker_at_capacity',
+            message:
+              '该 worker 为 in-process 模式（slz 默认），只支持单会话。请用 `slz rc` 启动 spawn 模式 worker 支持多会话。',
+          },
+        },
+        409,
+      )
+    }
+  }
+
+  // Occupancy: a live worker elsewhere holds the session. Same-environment
+  // re-entry was already handled above (before authorization).
+  if (isSessionOccupied(sessionId, envId)) {
+    return c.json(
+      {
+        error: {
+          type: 'session_busy',
+          message: 'Session is being driven by another worker',
+        },
+      },
+      409,
+    )
+  }
+
+  const rebind = session.environment_id !== envId
+  if (rebind) {
+    storeRebindSessionEnvironment(sessionId, envId)
+  }
+
+  let workItemId: string
+  try {
+    workItemId = await createWorkItem(envId, sessionId)
+  } catch (err) {
+    // Roll the rebind back so a failed dispatch doesn't leave the session
+    // pointing at an environment that never picked it up.
+    if (rebind && session.environment_id) {
+      storeRebindSessionEnvironment(sessionId, session.environment_id)
+    }
+    return c.json(
+      {
+        error: {
+          type: 'work_dispatch_failed',
+          message: (err as Error).message,
+        },
+      },
+      409,
+    )
+  }
+
+  log(
+    `[RCS] Session ${sessionId} attached to env=${envId} (rebind=${rebind} work=${workItemId})`,
+  )
+  return c.json(
+    {
+      status: 'attached',
+      session_id: sessionId,
+      work_item_id: workItemId,
+      rebind,
+    },
+    200,
+  )
+}
+
+/** POST /v1/sessions/attach-code/exchange — Redeem a one-time attach code.
+ *  The code was minted by a session manager (POST /web/sessions/:id/attach-code)
+ *  and IS the authorization: the CLI holding it needs no manage rights of
+ *  its own (typical for shared admin API keys that can't enumerate
+ *  sessions). Single-use — the code is consumed on success AND on any
+ *  validation failure after redemption to prevent replay probing. */
+app.post('/attach-code/exchange', bridgeAuth, async c => {
+  const caller = resolveAttachCaller(c)
+  const body = await c.req.json().catch(() => ({}) as Record<string, unknown>)
+  const code = typeof body.code === 'string' ? body.code.trim() : ''
+  const envId =
+    typeof body.environment_id === 'string' ? body.environment_id : undefined
+  if (!code || !envId) {
+    return c.json(
+      {
+        error: {
+          type: 'bad_request',
+          message: 'code and environment_id are required',
+        },
+      },
+      400,
+    )
+  }
+
+  const record = storeConsumeAttachCode(code)
+  if (!record) {
+    return c.json(
+      {
+        error: {
+          type: 'invalid_attach_code',
+          message: 'Attach code is unknown, expired, or already used',
+        },
+      },
+      403,
+    )
+  }
+
+  return performAttach(c, {
+    sessionId: record.sessionId,
+    envId,
+    caller,
+    skipAccessCheck: true,
+  })
+})
+
+/** GET /v1/sessions/:id/events — Historical events for session (bridge auth).
+ *  CLI-side hydration for Session Attach: merges the durable SQLite log with
+ *  the in-memory bus window (same merge as the web /history route), deduped
+ *  by id, chronological.
+ *
+ *  Access: session management rights (canManageSession), a bare admin API
+ *  key, OR ownership of the environment the session is currently bound to.
+ *  The env-owner relaxation is what makes wait-mode hydration work: a
+ *  team-admin binds a session to someone else's CLI env, and that CLI must
+ *  read the history to hydrate — it already sees the live traffic through
+ *  the work-item ingress token, so refusing only the history would gate the
+ *  wrong layer (P0-1). */
+app.get('/:id/events', bridgeAuth, async c => {
+  const caller = resolveAttachCaller(c)
+  const sessionId =
+    resolveExistingSessionId(c.req.param('id')!) ?? c.req.param('id')!
+  const session = getSession(sessionId)
+  if (!session) {
+    return c.json(
+      { error: { type: 'not_found', message: 'Session not found' } },
+      404,
+    )
+  }
+
+  const db = getDb()
+  const manages =
+    (caller.uuid !== null && canManageSession(sessionId, caller.uuid, db)) ||
+    (!caller.hasIdentity && caller.isApiAdmin)
+  let envOwned = false
+  if (
+    !manages &&
+    caller.uuid !== null &&
+    session.environment_id !== null &&
+    session.environment_id !== undefined
+  ) {
+    const ownership = storeGetEnvironmentOwnership(session.environment_id)
+    envOwned = ownership?.ownerUserId === caller.uuid
+  }
+  if (!manages && !envOwned) {
+    return c.json(
+      {
+        error: {
+          type: caller.hasIdentity ? 'forbidden' : 'unauthorized',
+          message: caller.hasIdentity
+            ? 'Not allowed to read this session'
+            : 'User identity required to read session events',
+        },
+      },
+      caller.hasIdentity ? 403 : 401,
+    )
+  }
+
+  const persisted = loadPersistedEvents(sessionId)
+  const inMemory = getEventBus(sessionId).getEventsSince(0)
+  const byId = new Map<string, (typeof persisted)[number]>()
+  for (const event of persisted) byId.set(event.id, event)
+  for (const event of inMemory) {
+    if (!byId.has(event.id)) byId.set(event.id, event)
+  }
+  const events = [...byId.values()].sort(
+    (a, b) => a.createdAt - b.createdAt || a.seqNum - b.seqNum,
+  )
+  // models_state fallback — mirrors the web history route so a CLI attaching
+  // right after a /clear still receives the model selector snapshot.
+  if (!events.some(e => e.type === 'models_state')) {
+    const snapshot = getEventBus(sessionId).modelsStateSnapshot
+    if (snapshot) {
+      const lastCreated = events[events.length - 1]?.createdAt ?? Date.now()
+      events.push({
+        id: `models_state_snapshot_${sessionId}`,
+        sessionId,
+        seqNum: 0,
+        type: 'models_state',
+        payload: { models_state: snapshot },
+        direction: 'inbound',
+        createdAt: lastCreated + 1,
+      })
+    }
+  }
+  return c.json({ events }, 200)
+})
+
 /** GET /v1/sessions/:id — Get session */
 app.get('/:id', acceptCliHeaders, apiKeyAuth, async c => {
   const sessionId =

package/packages/remote-control-server/src/routes/web/sessions.ts

@@ -29,6 +29,7 @@ import {
   storeGetEnvironment,
   storeGetSessionWorker,
   storeGetActiveWorkItemBySession,
+  storeIssueAttachCode,
   storeListSessionsByEnvironment,
 } from '../../store'
 import { createWorkItem, stopWork } from '../../services/work-dispatch'
@@ -195,6 +196,72 @@ app.get('/sessions/all', sessionAuth, async c => {
   return c.json(sessions, 200)
 })
 
+/** POST /web/sessions/:id/attach-code — Mint a one-time attach code (P3).
+ *  The session manager shows/copies `slz rc --attach <code>`; the CLI
+ *  redeems it via POST /v1/sessions/attach-code/exchange. The code IS the
+ *  authorization (15-min TTL, single use) — the CLI needs no manage rights
+ *  of its own. */
+app.post('/sessions/:id/attach-code', sessionAuth, async c => {
+  const uuid = c.get('userId')!
+  const sessionId = resolveOwnedWebSessionId(c.req.param('id')!, uuid)
+  if (!sessionId) {
+    return c.json(
+      { error: { type: 'forbidden', message: 'Not your session' } },
+      403,
+    )
+  }
+  if (!canManageSession(sessionId, uuid, getDb())) {
+    return c.json(
+      {
+        error: {
+          type: 'forbidden',
+          message: 'Only session owner or team admin can mint attach codes',
+        },
+      },
+      403,
+    )
+  }
+  const session = getSession(sessionId)
+  if (!session) {
+    return c.json(
+      { error: { type: 'not_found', message: 'Session not found' } },
+      404,
+    )
+  }
+  if (isSessionClosedStatus(session.status)) {
+    return c.json(
+      {
+        error: {
+          type: 'session_closed',
+          message: `Session is ${session.status}`,
+        },
+      },
+      409,
+    )
+  }
+  if (session.source === 'acp') {
+    return c.json(
+      {
+        error: {
+          type: 'acp_session',
+          message: 'ACP sessions cannot be attached to a bridge worker',
+        },
+      },
+      409,
+    )
+  }
+
+  const record = storeIssueAttachCode(sessionId)
+  return c.json(
+    {
+      code: record.code,
+      expires_at: record.expiresAt.getTime(),
+      attach_command: `slz rc --attach ${record.code}`,
+    },
+    201,
+  )
+})
+
 /** GET /web/sessions/:id — Session detail */
 app.get('/sessions/:id', sessionAuth, async c => {
   const uuid = c.get('userId')!