auth-yes/tasks/complete/2026-0824.08.gem.feat.session-delegation.agent-spawner-and-scoped-permissions-2345.md

2.3 KiB

TASK METADATA

  • Target Files:
    • server/db.ts
    • server/main.ts
    • server/auth-session.ts
    • ui/components/SessionsPage.tsx
    • ui/mod.ts
    • server/main.test.ts
  • Core Objective: Implement frictionless Child Session Delegation with Agent Labeling, Scoped Permissions (read-only, operator, custom app grants), custom TTLs, and live observability cards.
  • Dependencies: server/auth-session.ts, server/db.ts, ui/components/SessionsPage.tsx
  • Additional Important Notes: Zero-dependency SDK compatibility; instant Valkey RESP3 push invalidation; progressive disclosure for advanced scope customization.

1. Architectural Considerations & Risks

  • Security & Session Isolation:
    • Child sessions must have isolated session IDs so revoking an agent session does not invalidate the user's primary interactive browser session.
    • When custom scopes are defined, getAuthenticatedUser(c) or AuthMiddleware verifies that the requested action/app matches the session's permitted scope list.
  • Progressive Disclosure UX:
    • Default simple presets: Lifespan (1h, 12h, 7d) and Access Mode (Read-Only, Operator, Full Admin).
    • Optional expandable drawer for granular app-level permissions.
  • Observability:
    • Track last_activity_at and last_activity_action for real-time visibility in the session cards.

2. Proposed Implementation

  1. Database Schema & Migrations (server/db.ts):
    • Add label, is_agent, custom_scopes, last_activity_at, last_activity_action to sessions table.
  2. Backend API Endpoints (server/main.ts):
    • POST /api/sessions/delegate: Mints a child session with custom label, lifespan, and scopes.
    • PUT /api/sessions/:id/scopes: Updates permissions on an active session.
    • POST /api/sessions/:id/extend: Extends session TTL.
  3. UI Implementation (ui/components/SessionsPage.tsx):
    • Add "Delegate Agent Session" top action and expandable modal.
    • Hand-off card with 1-tap copy for token, CLI export, and cURL header.
    • Distinct 🤖 Agent session cards with live countdown, [Extend +1h], [Edit Scopes], and [Revoke].
  4. Automated Tests (server/main.test.ts):
    • Verify delegation, custom scope restrictions, and extension.