@lumenflow/surfaces 5.1.0

package/http/ag-ui-adapter.ts

@@ -0,0 +1,352 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  KERNEL_EVENT_KINDS,
+  TOOL_TRACE_KINDS,
+  type KernelEvent,
+  type PolicyDecision,
+  type TaskState,
+  type ToolTraceEntry,
+} from '@lumenflow/kernel';
+
+const SOURCE = {
+  KERNEL_EVENT: 'kernel_event',
+  POLICY: 'policy',
+  STATE_SYNC: 'state_sync',
+  TOOL_TRACE: 'tool_trace',
+} as const;
+
+const JSON_POINTER_PREFIX = '/';
+
+export const AG_UI_EVENT_TYPES = {
+  RUN_STARTED: 'RUN_STARTED',
+  STEP_STARTED: 'STEP_STARTED',
+  STEP_BLOCKED: 'STEP_BLOCKED',
+  STEP_UNBLOCKED: 'STEP_UNBLOCKED',
+  STEP_WAITING: 'STEP_WAITING',
+  STEP_RESUMED: 'STEP_RESUMED',
+  RUN_COMPLETED: 'RUN_COMPLETED',
+  RUN_RELEASED: 'RUN_RELEASED',
+  RUN_DELEGATED: 'RUN_DELEGATED',
+  STEP_PAUSED: 'STEP_PAUSED',
+  STEP_FAILED: 'STEP_FAILED',
+  STEP_SUCCEEDED: 'STEP_SUCCEEDED',
+  WORKSPACE_UPDATED: 'WORKSPACE_UPDATED',
+  WORKSPACE_WARNING: 'WORKSPACE_WARNING',
+  SPEC_TAMPERED: 'SPEC_TAMPERED',
+  CHECKPOINT: 'CHECKPOINT',
+  TOOL_CALL_START: 'TOOL_CALL_START',
+  TOOL_CALL_END: 'TOOL_CALL_END',
+  TOOL_CALL_RESULT: 'TOOL_CALL_RESULT',
+  GOVERNANCE_DECISION: 'GOVERNANCE_DECISION',
+  STATE_SNAPSHOT: 'StateSnapshot',
+  STATE_DELTA: 'StateDelta',
+  MESSAGES_SNAPSHOT: 'MessagesSnapshot',
+} as const;
+
+type AgUiEventType = (typeof AG_UI_EVENT_TYPES)[keyof typeof AG_UI_EVENT_TYPES];
+
+interface EventMetadata {
+  source: string;
+  kernel_kind?: KernelEvent['kind'];
+}
+
+export interface AgUiEvent {
+  type: AgUiEventType | string;
+  timestamp: string;
+  task_id?: string;
+  run_id?: string;
+  payload: Record<string, unknown>;
+  metadata: EventMetadata;
+}
+
+interface PolicyEventContext {
+  task_id: string;
+  run_id?: string;
+  timestamp: string;
+}
+
+interface StateDeltaOperation {
+  op: 'add' | 'remove' | 'replace';
+  path: string;
+  value?: unknown;
+}
+
+function hasTaskId(event: KernelEvent): event is Extract<KernelEvent, { task_id: string }> {
+  return 'task_id' in event;
+}
+
+function hasRunId(event: KernelEvent): event is Extract<KernelEvent, { run_id: string }> {
+  return 'run_id' in event;
+}
+
+const KERNEL_KIND_TO_AG_UI_TYPE: Record<KernelEvent['kind'], AgUiEventType> = {
+  [KERNEL_EVENT_KINDS.TASK_CREATED]: AG_UI_EVENT_TYPES.RUN_STARTED,
+  [KERNEL_EVENT_KINDS.TASK_CLAIMED]: AG_UI_EVENT_TYPES.STEP_STARTED,
+  [KERNEL_EVENT_KINDS.TASK_BLOCKED]: AG_UI_EVENT_TYPES.STEP_BLOCKED,
+  [KERNEL_EVENT_KINDS.TASK_UNBLOCKED]: AG_UI_EVENT_TYPES.STEP_UNBLOCKED,
+  [KERNEL_EVENT_KINDS.TASK_WAITING]: AG_UI_EVENT_TYPES.STEP_WAITING,
+  [KERNEL_EVENT_KINDS.TASK_RESUMED]: AG_UI_EVENT_TYPES.STEP_RESUMED,
+  [KERNEL_EVENT_KINDS.TASK_COMPLETED]: AG_UI_EVENT_TYPES.RUN_COMPLETED,
+  [KERNEL_EVENT_KINDS.TASK_RELEASED]: AG_UI_EVENT_TYPES.RUN_RELEASED,
+  [KERNEL_EVENT_KINDS.TASK_DELEGATED]: AG_UI_EVENT_TYPES.RUN_DELEGATED,
+  [KERNEL_EVENT_KINDS.RUN_STARTED]: AG_UI_EVENT_TYPES.STEP_STARTED,
+  [KERNEL_EVENT_KINDS.RUN_PAUSED]: AG_UI_EVENT_TYPES.STEP_PAUSED,
+  [KERNEL_EVENT_KINDS.RUN_FAILED]: AG_UI_EVENT_TYPES.STEP_FAILED,
+  [KERNEL_EVENT_KINDS.RUN_SUCCEEDED]: AG_UI_EVENT_TYPES.STEP_SUCCEEDED,
+  [KERNEL_EVENT_KINDS.WORKSPACE_UPDATED]: AG_UI_EVENT_TYPES.WORKSPACE_UPDATED,
+  [KERNEL_EVENT_KINDS.WORKSPACE_WARNING]: AG_UI_EVENT_TYPES.WORKSPACE_WARNING,
+  [KERNEL_EVENT_KINDS.SPEC_TAMPERED]: AG_UI_EVENT_TYPES.SPEC_TAMPERED,
+  [KERNEL_EVENT_KINDS.CHECKPOINT]: AG_UI_EVENT_TYPES.CHECKPOINT,
+};
+
+function createEventFromKernel(
+  event: KernelEvent,
+  type: AgUiEventType,
+  payload: Record<string, unknown>,
+): AgUiEvent {
+  const mapped: AgUiEvent = {
+    type,
+    timestamp: event.timestamp,
+    payload,
+    metadata: {
+      source: SOURCE.KERNEL_EVENT,
+      kernel_kind: event.kind,
+    },
+  };
+
+  if (hasTaskId(event)) {
+    mapped.task_id = event.task_id;
+  }
+  if (hasRunId(event)) {
+    mapped.run_id = event.run_id;
+  }
+
+  return mapped;
+}
+
+export function mapKernelEventToAgUiEvent(event: KernelEvent): AgUiEvent {
+  const type = KERNEL_KIND_TO_AG_UI_TYPE[event.kind];
+  return createEventFromKernel(event, type, {
+    event,
+  });
+}
+
+export function mapToolTraceEntryToAgUiEvents(entry: ToolTraceEntry): AgUiEvent[] {
+  if (entry.kind === TOOL_TRACE_KINDS.TOOL_CALL_STARTED) {
+    return [
+      {
+        type: AG_UI_EVENT_TYPES.TOOL_CALL_START,
+        timestamp: entry.timestamp,
+        task_id: entry.task_id,
+        run_id: entry.run_id,
+        payload: {
+          receipt_id: entry.receipt_id,
+          tool_name: entry.tool_name,
+          execution_mode: entry.execution_mode,
+          input_ref: entry.input_ref,
+          input_hash: entry.input_hash,
+          scope_requested: entry.scope_requested,
+          scope_allowed: entry.scope_allowed,
+          scope_enforced: entry.scope_enforced,
+        },
+        metadata: {
+          source: SOURCE.TOOL_TRACE,
+        },
+      },
+    ];
+  }
+
+  if (entry.kind === TOOL_TRACE_KINDS.TOOL_CALL_PROGRESS) {
+    return [
+      {
+        type: AG_UI_EVENT_TYPES.TOOL_CALL_RESULT,
+        timestamp: entry.timestamp,
+        payload: {
+          receipt_id: entry.receipt_id,
+          state: entry.state,
+          sequence: entry.sequence,
+          snapshot_hash: entry.snapshot_hash,
+          snapshot_ref: entry.snapshot_ref,
+          streaming: true,
+        },
+        metadata: {
+          source: SOURCE.TOOL_TRACE,
+        },
+      },
+    ];
+  }
+
+  const common: AgUiEvent = {
+    type: AG_UI_EVENT_TYPES.TOOL_CALL_END,
+    timestamp: entry.timestamp,
+    payload: {
+      receipt_id: entry.receipt_id,
+      result: entry.result,
+      duration_ms: entry.duration_ms,
+      policy_decisions: entry.policy_decisions,
+      artifacts_written: entry.artifacts_written,
+    },
+    metadata: {
+      source: SOURCE.TOOL_TRACE,
+    },
+  };
+
+  const resultEvent: AgUiEvent = {
+    type: AG_UI_EVENT_TYPES.TOOL_CALL_RESULT,
+    timestamp: entry.timestamp,
+    payload: {
+      receipt_id: entry.receipt_id,
+      output_hash: entry.output_hash,
+      output_ref: entry.output_ref,
+      redaction_summary: entry.redaction_summary,
+      scope_enforcement_note: entry.scope_enforcement_note,
+      result: entry.result,
+    },
+    metadata: {
+      source: SOURCE.TOOL_TRACE,
+    },
+  };
+
+  return [common, resultEvent];
+}
+
+export function mapPolicyDecisionToAgUiEvent(
+  decision: PolicyDecision,
+  context: PolicyEventContext,
+): AgUiEvent {
+  return {
+    type: AG_UI_EVENT_TYPES.GOVERNANCE_DECISION,
+    timestamp: context.timestamp,
+    task_id: context.task_id,
+    run_id: context.run_id,
+    payload: {
+      policy_id: decision.policy_id,
+      decision: decision.decision,
+      reason: decision.reason,
+      governance: true,
+    },
+    metadata: {
+      source: SOURCE.POLICY,
+    },
+  };
+}
+
+function toStateDeltaOperations(previous: TaskState, next: TaskState): StateDeltaOperation[] {
+  const previousRecord = previous as Record<string, unknown>;
+  const nextRecord = next as Record<string, unknown>;
+  const keys = new Set([...Object.keys(previousRecord), ...Object.keys(nextRecord)]);
+  const operations: StateDeltaOperation[] = [];
+
+  for (const key of keys) {
+    const previousValue = previousRecord[key];
+    const nextValue = nextRecord[key];
+
+    const unchanged = JSON.stringify(previousValue) === JSON.stringify(nextValue);
+    if (unchanged) {
+      continue;
+    }
+
+    if (previousValue === undefined) {
+      operations.push({
+        op: 'add',
+        path: `${JSON_POINTER_PREFIX}${key}`,
+        value: nextValue,
+      });
+      continue;
+    }
+
+    if (nextValue === undefined) {
+      operations.push({
+        op: 'remove',
+        path: `${JSON_POINTER_PREFIX}${key}`,
+      });
+      continue;
+    }
+
+    operations.push({
+      op: 'replace',
+      path: `${JSON_POINTER_PREFIX}${key}`,
+      value: nextValue,
+    });
+  }
+
+  return operations;
+}
+
+export function createStateSyncEvents(
+  previousState: TaskState | undefined,
+  nextState: TaskState,
+  timestamp: string,
+): AgUiEvent[] {
+  const snapshotEvent: AgUiEvent = {
+    type: AG_UI_EVENT_TYPES.STATE_SNAPSHOT,
+    timestamp,
+    task_id: nextState.task_id,
+    payload: {
+      state: nextState,
+    },
+    metadata: {
+      source: SOURCE.STATE_SYNC,
+    },
+  };
+
+  if (!previousState) {
+    return [snapshotEvent];
+  }
+
+  const operations = toStateDeltaOperations(previousState, nextState);
+  if (operations.length === 0) {
+    return [snapshotEvent];
+  }
+
+  const deltaEvent: AgUiEvent = {
+    type: AG_UI_EVENT_TYPES.STATE_DELTA,
+    timestamp,
+    task_id: nextState.task_id,
+    payload: {
+      patch: operations,
+      from_status: previousState.status,
+      to_status: nextState.status,
+    },
+    metadata: {
+      source: SOURCE.STATE_SYNC,
+    },
+  };
+
+  return [snapshotEvent, deltaEvent];
+}
+
+function isEventForTask(event: KernelEvent, taskId: string): boolean {
+  if (!hasTaskId(event)) {
+    // Global events (workspace_updated, workspace_warning, spec_tampered) are
+    // included because they affect all tasks.
+    return true;
+  }
+  return event.task_id === taskId;
+}
+
+export function createMessagesSnapshot(
+  taskId: string,
+  kernelEvents: KernelEvent[],
+  timestamp: string,
+): AgUiEvent {
+  const relevantEvents = kernelEvents.filter((event) => isEventForTask(event, taskId));
+
+  const sorted = [...relevantEvents].sort((left, right) => {
+    return left.timestamp < right.timestamp ? -1 : left.timestamp > right.timestamp ? 1 : 0;
+  });
+
+  return {
+    type: AG_UI_EVENT_TYPES.MESSAGES_SNAPSHOT,
+    timestamp,
+    task_id: taskId,
+    payload: {
+      messages: sorted,
+    },
+    metadata: {
+      source: SOURCE.STATE_SYNC,
+    },
+  };
+}

package/http/auth.ts

@@ -0,0 +1,294 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingHttpHeaders } from 'node:http';
+import {
+  issueControlPlaneIdentity,
+  parseControlPlaneToken,
+  type ControlPlaneAuthProfileConfig,
+  type ScopedControlPlaneIdentity,
+} from '../../control-plane-sdk/src/authenticate.js';
+import {
+  createToolScopeForToolName,
+  isToolScopeMatch,
+} from '../../control-plane-sdk/src/scope-grammar.js';
+import { loadWorkspaceSoftwareDeliveryConfig } from '../../host/src/workspace-config/index.js';
+
+const HEADER = {
+  AUTHORIZATION: 'authorization',
+} as const;
+const BEARER_PREFIX = 'Bearer ';
+const DEFAULT_PROFILE = 'privileged';
+const DEFAULT_ALLOW_LEGACY_UNSCOPED_TOKENS = true;
+
+const DEFAULT_PROFILES = {
+  mobile: {
+    ttl_seconds: 60 * 60 * 24,
+    scopes: ['tool:orchestrate:initiative', 'tool:delegation:list'],
+  },
+  privileged: {
+    ttl_seconds: 60 * 60 * 24 * 7,
+    scopes: ['tool:*'],
+  },
+  /**
+   * Phone-device profile (WU-2731, ADR-013 §5). Issued to phone endpoints
+   * that POST /tools/:name or /sidekick/channel. Scopes deliberately narrow:
+   * phone devices invoke tool dispatch through the mobile allowlist; they do
+   * NOT hold workspace-wide `tool:*` authority.
+   */
+  phone: {
+    ttl_seconds: 60 * 60 * 24 * 30,
+    scopes: ['tool:orchestrate:initiative', 'tool:delegation:list', 'tool:sidekick:channel:send'],
+  },
+} satisfies Record<string, ControlPlaneAuthProfileConfig>;
+
+export interface WorkspaceSurfaceAuthConfig {
+  allow_legacy_unscoped_tokens: boolean;
+  profiles: Record<string, ControlPlaneAuthProfileConfig>;
+}
+
+/**
+ * WU-2779 (P0 security): Discriminator for authorization failures. Callers
+ * use this to map deny outcomes to the correct HTTP status:
+ *   - `missing_authorization` → 401 (no Authorization header at all)
+ *   - `missing_scope`         → 403 (token present but lacks the scope)
+ * `allowed` results do not carry a reason.
+ */
+export type ToolAuthorizationDenyReason = 'missing_authorization' | 'missing_scope';
+
+export interface ToolAuthorizationResult {
+  allowed: boolean;
+  required: string[];
+  granted: string[];
+  identity?: ScopedControlPlaneIdentity;
+  reason?: ToolAuthorizationDenyReason;
+}
+
+interface WorkspaceSurfaceAuthConfigRecord {
+  allow_legacy_unscoped_tokens?: unknown;
+  profiles?: Record<string, unknown>;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function asPositiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function asScopeList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const scopes = value.filter((scope): scope is string => typeof scope === 'string');
+  return scopes.length === value.length ? scopes : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function normalizeProfileConfig(
+  value: unknown,
+  fallback: ControlPlaneAuthProfileConfig,
+): ControlPlaneAuthProfileConfig {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return fallback;
+  }
+
+  const record = value as Record<string, unknown>;
+  return {
+    scopes: asScopeList(record.scopes) ?? fallback.scopes,
+    ttl_seconds: asPositiveInteger(record.ttl_seconds) ?? fallback.ttl_seconds,
+  };
+}
+
+function readWorkspaceAuthConfigRecord(
+  workspaceRoot: string,
+): WorkspaceSurfaceAuthConfigRecord | undefined {
+  const softwareDeliveryConfig = loadWorkspaceSoftwareDeliveryConfig(workspaceRoot);
+  const surfacesConfig = asRecord(softwareDeliveryConfig?.surfaces);
+  const authConfig = asRecord(surfacesConfig?.auth);
+
+  if (!authConfig) {
+    return undefined;
+  }
+
+  return {
+    allow_legacy_unscoped_tokens: authConfig.allow_legacy_unscoped_tokens,
+    profiles: asRecord(authConfig.profiles),
+  };
+}
+
+export function readWorkspaceSurfaceAuthConfig(
+  workspaceRoot: string = process.cwd(),
+): WorkspaceSurfaceAuthConfig {
+  const configuredAuth = readWorkspaceAuthConfigRecord(workspaceRoot);
+  const configuredProfiles = configuredAuth?.profiles ?? {};
+
+  return {
+    allow_legacy_unscoped_tokens:
+      asBoolean(configuredAuth?.allow_legacy_unscoped_tokens) ??
+      DEFAULT_ALLOW_LEGACY_UNSCOPED_TOKENS,
+    profiles: {
+      mobile: normalizeProfileConfig(configuredProfiles.mobile, DEFAULT_PROFILES.mobile),
+      privileged: normalizeProfileConfig(
+        configuredProfiles.privileged,
+        DEFAULT_PROFILES.privileged,
+      ),
+      phone: normalizeProfileConfig(configuredProfiles.phone, DEFAULT_PROFILES.phone),
+    },
+  };
+}
+
+function readBearerToken(headers: IncomingHttpHeaders): string | undefined {
+  const rawHeader = headers[HEADER.AUTHORIZATION];
+  const value = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+
+  if (typeof value !== 'string' || !value.startsWith(BEARER_PREFIX)) {
+    return undefined;
+  }
+
+  const token = value.slice(BEARER_PREFIX.length).trim();
+  return token.length > 0 ? token : undefined;
+}
+
+function toIdentityFromToken(token: string): ScopedControlPlaneIdentity | undefined {
+  const payload = parseControlPlaneToken(token);
+  if (!payload) {
+    return undefined;
+  }
+
+  return {
+    workspace_id: payload.workspace_id,
+    org_id: payload.org_id,
+    agent_id: payload.agent_id,
+    token,
+    scopes: payload.scopes,
+    expires_at: payload.expires_at,
+    ...(payload.profile ? { profile: payload.profile } : {}),
+    ...(payload.subject ? { subject: payload.subject } : {}),
+  };
+}
+
+export function issueWorkspaceProfileIdentity(
+  input: {
+    workspace_id: string;
+    org_id: string;
+    agent_id: string;
+  },
+  options: {
+    profile?: string;
+    now?: Date | string;
+    workspaceRoot?: string;
+  } = {},
+): ScopedControlPlaneIdentity {
+  const config = readWorkspaceSurfaceAuthConfig(options.workspaceRoot);
+
+  return issueControlPlaneIdentity(input, {
+    profile: options.profile ?? DEFAULT_PROFILE,
+    profiles: config.profiles,
+    now: options.now,
+  });
+}
+
+export function createMissingScopesPayload(
+  result: ToolAuthorizationResult,
+  toolName: string,
+): {
+  error: 'missing_scopes';
+  required: string[];
+  granted: string[];
+  requested: string;
+  held: string[];
+  hint: string;
+} {
+  const requestedScope = result.required[0] ?? createToolScopeForToolName(toolName);
+  return {
+    error: 'missing_scopes',
+    required: result.required,
+    granted: result.granted,
+    requested: requestedScope,
+    held: result.granted,
+    hint: `Token lacks scope for ${requestedScope}. Re-authenticate with an allowlist that includes it.`,
+  };
+}
+
+/**
+ * WU-2731 (ADR-013 §5 Identity): Resolve the authoritative `from` claim for an
+ * inbound HTTP request from the bearer token. Only tokens that carry an
+ * explicit `subject` claim participate — phone-device enrollments set
+ * `subject = {workspace_id}:phone:{device_id}`, so those requests get a
+ * per-device authoritative `from`. Workspace-scoped tokens (no subject) keep
+ * their existing `workspace_id`-derived identity at the runtime layer; we do
+ * not synthesise a `from` for them because cloud's audit layer already
+ * derives workspace attribution from the session record.
+ *
+ * Returns `undefined` when the request carries no recognisable scoped token
+ * OR when the token has no subject claim.
+ */
+export function resolveAuthoritativeFrom(
+  headers: IncomingHttpHeaders,
+): { from: string; identity: ScopedControlPlaneIdentity } | undefined {
+  const token = readBearerToken(headers);
+  if (!token) {
+    return undefined;
+  }
+
+  const identity = toIdentityFromToken(token);
+  if (!identity?.subject) {
+    return undefined;
+  }
+
+  return { from: identity.subject, identity };
+}
+
+export function authorizeToolRequest(
+  headers: IncomingHttpHeaders,
+  toolName: string,
+  workspaceRoot: string = process.cwd(),
+): ToolAuthorizationResult {
+  const required = [createToolScopeForToolName(toolName)];
+  const config = readWorkspaceSurfaceAuthConfig(workspaceRoot);
+  const token = readBearerToken(headers);
+
+  // WU-2779 (P0 security): Reject requests with no bearer credential. Prior
+  // behaviour returned `allowed: true` for missing tokens, letting unauth
+  // clients dispatch POST /tools/:name. There is no public-allowlist at this
+  // layer — /tools/:name is always privileged — so default deny.
+  if (!token) {
+    return {
+      allowed: false,
+      required,
+      granted: [],
+      reason: 'missing_authorization',
+    };
+  }
+
+  const identity = toIdentityFromToken(token);
+  if (!identity) {
+    const allowed = config.allow_legacy_unscoped_tokens;
+    return {
+      allowed,
+      required,
+      granted: [],
+      ...(allowed ? {} : { reason: 'missing_scope' }),
+    };
+  }
+
+  const granted = identity.scopes;
+  const allowed = granted.some((scope) => isToolScopeMatch(scope, toolName));
+
+  return {
+    allowed,
+    required,
+    granted,
+    ...(allowed ? { identity } : { reason: 'missing_scope' }),
+  };
+}