Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

8.1 KB
Raw Blame
/**
 * Immutable per-agent permission contexts (ROADMAP P2.2, ADR-016).
 *
 * Before this, channel, sender role, allow-all, skill elevation and session
 * scopes were mutable fields on the single PermissionManager shared by the
 * main agent and every sub-agent. An internal (scheduled) turn switched
 * allow-all on for its duration, and a delegated worker whose tool call
 * landed inside that window inherited it (#75/#99 residual).
 *
 * Now each agent's view is a frozen `PermissionContext`. Sub-agents run
 * inside `AsyncLocalStorage` with a context derived from their parent's at
 * spawn time (child ⊆ parent), so any tool they invoke — however deep in
 * the AI SDK's promise chain — reads their own context, never the main
 * agent's current one.
 */
import { AsyncLocalStorage } from 'node:async_hooks';
import { resolve, sep } from 'node:path';
import { homedir } from 'node:os';

export interface ContextScope {
  readonly path: string;
  readonly read: boolean;
  readonly write: boolean;
  readonly execute?: boolean;
}

export interface PermissionContext {
  readonly channelType: string;
  readonly channelId: string;
  /** External event turns neither consume nor create remembered conversation approvals. */
  readonly rememberApprovals: boolean;
  /** Canonical repository session, supplied by the agent, never tool arguments. */
  readonly sessionId?: string;
  readonly senderRole: 'admin' | 'member' | undefined;
  /** Allow-all: approved-scope actions and non-blocked commands run without prompts. */
  readonly autoApprove: boolean;
  /**
   * Where allow-all came from. `session`: the user chose Allow All (CLI
   * /permissions, Telegram/Signal button) — inherited by children. `turn`:
   * the grant of one internal (scheduled/background) turn — never inherited.
   */
  readonly autoApproveOrigin: 'session' | 'turn' | null;
  /** Tool allowlist; `undefined` = unrestricted. */
  readonly allowedTools: readonly string[] | undefined;
  /** Session/turn scopes on top of the persisted manifest scopes. */
  readonly scopes: readonly ContextScope[];
  /** Skill elevation grants (`run_command`, `fs_read`, `fs_write`) — never inherited. */
  readonly elevated: readonly string[];
}

function freezeScopes(scopes: readonly ContextScope[]): readonly ContextScope[] {
  return Object.freeze(scopes.map((s) => Object.freeze({ ...s })));
}

export function makeContext(fields: Partial<PermissionContext> = {}): PermissionContext {
  return Object.freeze({
    channelType: fields.channelType ?? 'cli',
    channelId: fields.channelId ?? 'cli',
    ...(fields.sessionId ? { sessionId: fields.sessionId } : {}),
    senderRole: fields.senderRole,
    rememberApprovals: fields.rememberApprovals ?? true,
    autoApprove: fields.autoApprove ?? false,
    autoApproveOrigin: fields.autoApprove ? (fields.autoApproveOrigin ?? 'session') : null,
    allowedTools: fields.allowedTools ? Object.freeze([...fields.allowedTools]) : undefined,
    scopes: freezeScopes(fields.scopes ?? []),
    elevated: Object.freeze([...(fields.elevated ?? [])]),
  });
}

/** A new frozen context = `base` with `patch` applied. */
export function withChanges(base: PermissionContext, patch: Partial<PermissionContext>): PermissionContext {
  const merged = { ...base, ...patch };
  if (patch.autoApprove === false) merged.autoApproveOrigin = null;
  if (patch.autoApprove === true && !patch.autoApproveOrigin) merged.autoApproveOrigin = base.autoApproveOrigin ?? 'session';
  return makeContext(merged);
}

function expand(path: string): string {
  return resolve(path.replace(/^~/, homedir()));
}

function covers(parent: ContextScope, child: ContextScope): boolean {
  const p = expand(parent.path);
  const c = expand(child.path);
  const inside = c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
  return inside
    && (!child.read || parent.read)
    && (!child.write || parent.write)
    && (!child.execute || parent.execute === true);
}

export interface ChildContextRequest {
  channelType?: string;
  channelId?: string;
  allowedTools?: readonly string[];
  /** Requested scopes; each must be covered by one of the parent's. Defaults to the parent's. */
  scopes?: readonly ContextScope[];
}

/**
 * Derive a child's context. The child is a subset of the parent on every
 * privilege axis:
 * - allow-all only when the parent's is a user-chosen session grant (an
 *   internal turn's grant stays with that turn);
 * - allowedTools = parent ∩ requested;
 * - scopes = requested scopes the parent covers (default: parent's);
 * - no skill elevation.
 * Channel identity is a routing attribute (where prompts go), not a privilege.
 */
export function deriveChildContext(parent: PermissionContext, req: ChildContextRequest = {}): PermissionContext {
  let allowedTools: readonly string[] | undefined;
  if (parent.allowedTools && req.allowedTools && req.allowedTools.length > 0) {
    const p = new Set(parent.allowedTools);
    allowedTools = req.allowedTools.filter((t) => p.has(t));
  } else if (req.allowedTools && req.allowedTools.length > 0) {
    allowedTools = req.allowedTools;
  } else {
    allowedTools = parent.allowedTools;
  }
  const scopes = req.scopes
    ? req.scopes.filter((s) => parent.scopes.some((p) => covers(p, s)))
    : parent.scopes;
  const inheritAllow = parent.autoApprove && parent.autoApproveOrigin === 'session';
  return makeContext({
    channelType: req.channelType ?? parent.channelType,
    channelId: req.channelId ?? parent.channelId,
    senderRole: parent.senderRole,
    rememberApprovals: parent.rememberApprovals,
    autoApprove: inheritAllow,
    autoApproveOrigin: inheritAllow ? 'session' : null,
    allowedTools,
    scopes,
    elevated: [],
  });
}

/** True when `child` grants nothing `parent` does not (used by tests and assertions). */
export function isSubsetContext(child: PermissionContext, parent: PermissionContext): boolean {
  if (child.autoApprove && !parent.autoApprove) return false;
  if (child.rememberApprovals && !parent.rememberApprovals) return false;
  if (parent.allowedTools) {
    if (!child.allowedTools) return false;
    if (child.allowedTools.some((t) => !parent.allowedTools!.includes(t))) return false;
  }
  if (child.scopes.some((s) => !parent.scopes.some((p) => covers(p, s)))) return false;
  if (child.elevated.some((e) => !parent.elevated.includes(e))) return false;
  if (child.senderRole === 'admin' && parent.senderRole === 'member') return false;
  return true;
}

/**
 * The cell an agent's async tree carries. `owner` ties it to one
 * PermissionManager (bots have their own) so a bot dispatched from inside a
 * sub-agent never reads that sub-agent's context. `ctx` is replaced (never
 * mutated) when the agent itself is granted something mid-run, e.g. the
 * user answers "yes" to a scope request.
 */
export interface ContextCell {
  readonly owner: object;
  ctx: PermissionContext;
  /**
   * Set for a main-agent turn running alongside others (ADR-037). The turn
   * has no frozen context of its own: it reads the shared session context
   * with its own identity laid over it, so the owner's choices (Allow All,
   * approved scopes) apply to every chat at once, while who is asking,
   * from where, with which skill elevation or internal grant stays with
   * the turn. `ctx` is unused for such a cell.
   */
  turn?: TurnOverlay;
}

/** Context fields that belong to one turn, never to the shared session. */
export const TURN_OWNED_FIELDS = ['channelType', 'channelId', 'sessionId', 'senderRole', 'rememberApprovals', 'elevated'] as const;
export type TurnOwnedField = typeof TURN_OWNED_FIELDS[number];

export interface TurnOverlay {
  fields: { -readonly [K in TurnOwnedField]?: PermissionContext[K] };
  /** The internal turn's allow-all grant (beginTurnGrant), if any. */
  grant: { scopes: ContextScope[] } | null;
  /** Plugin tools pre-approved for this turn (a scheduled task's allowTools). */
  pluginGrants: Set<string>;
  /** Last computed context, valid while the session context is the same object. */
  cache: { session: PermissionContext; ctx: PermissionContext } | null;
}

export function newTurnOverlay(): TurnOverlay {
  return { fields: {}, grant: null, pluginGrants: new Set(), cache: null };
}

export const permissionContextStore = new AsyncLocalStorage<ContextCell>();