@capekai/core 1.0.0

package/src/permission/contracts.ts

@@ -0,0 +1,135 @@
+/**
+ * C6 permission policy contracts.
+ *
+ * The agent-scoped permission surface is split into two contracts:
+ *
+ * - `AskPermissionPolicyService` (REPLACEABLE advice/config): frozen
+ *   timeouts, authority and value extraction, the response validators, the
+ *   auto-approval bound, permission-key derivation, and dangerous-shell
+ *   detection. A custom provider may replace all of these, but its advice
+ *   can never change a mandatory decision: the runtime owns denial and
+ *   grant construction.
+ * - `PermissionRuntimeService` (NON-REPLACEABLE lifecycle): request-id
+ *   routing, pending-ask and waiter registries, timeouts and cleanup,
+ *   response validation against the module-level validators, raw-audit
+ *   denial, waiter resolution, canonical grant construction and persistence
+ *   (module-level `buildGrantParams` with the dangerous-shell once
+ *   downgrade), and the persistence calls through the interaction host.
+ *
+ * The Jean2 adapters keep persistence, WebSocket delivery, notifications,
+ * and controller authority: every host-facing operation goes through the
+ * `InteractionHost` installed by the compatibility bindings.
+ */
+
+import type { Ask, AskApi, AskPermissionResponse } from '@capekai/tool';
+import type { PermissionRiskLevel } from '@capekai/tool';
+import type { AskAuthority, AskRequestMessage, AskTimedOutMessage, ClientCapability } from '@capekai/types';
+import type { PendingAskRecord } from '../runtime/host';
+
+/** Provider options translated at composition. The generic ask timeout has
+ * no current configuration source and stays the fixed 5-minute constant;
+ * the permission timeout translates from the composed runtime host's
+ * `getPermissionTimeoutMs()`. */
+export interface AskPermissionPolicyOptions {
+  askTimeoutMs: number;
+  permissionTimeoutMs: number;
+}
+
+export interface RequestPermissionParams {
+  sessionId: string;
+  rootSessionId?: string;
+  workspaceId?: string;
+  toolCallId: string;
+  toolName: string;
+  ask: Ask;
+  broadcastFn: PermissionBroadcastFn;
+  timeoutMs?: number;
+}
+
+export type AskBroadcastFn = (message: AskRequestMessage | AskTimedOutMessage) => void;
+export type PermissionBroadcastFn = (message: AskRequestMessage | AskTimedOutMessage) => void;
+
+/**
+ * Replaceable permission advice and configuration. Every method is pure
+ * advice over the injected interaction host; the runtime never trusts these
+ * methods for mandatory denial or grant decisions.
+ */
+export interface AskPermissionPolicyService {
+  readonly id: string;
+  /** Frozen provider options. */
+  readonly options: Readonly<AskPermissionPolicyOptions>;
+  readonly askTimeoutMs: number;
+  readonly permissionTimeoutMs: number;
+  /** Authority for a generic ask: capability asks targeting the client
+   * resolve to global/first_eligible with the required capability; every
+   * other ask keeps the controller-only default. */
+  resolveAskAuthority(request: Ask): AskAuthority;
+  /** Extracts the resolved value from a shaped generic response. */
+  extractResolutionValue(response: unknown): unknown;
+  /** A permission response is only valid when it is shaped
+   * `{ type: 'permission', grant: 'once' | 'session' | 'workspace' | 'deny' }`. */
+  isValidPermissionResponse(response: unknown): response is AskPermissionResponse;
+  /** True for a valid non-deny permission response. */
+  isPermissionApproved(response: unknown): boolean;
+  /** Risk ordering check used for auto-approval bounds. */
+  isRiskAtOrBelow(risk: PermissionRiskLevel, max: PermissionRiskLevel): boolean;
+  /** Server auto-approval advice: true when the session severity is above
+   * off/undefined and the ask's risk is within it. */
+  shouldAutoApprove(sessionId: string, ask: Ask): Promise<boolean>;
+  /** Permission key precedence: first pattern, then resource, then tool name. */
+  buildPermissionKey(
+    toolName: string,
+    resource: string | undefined,
+    patterns: string[] | undefined,
+  ): string;
+  /** Dangerous shell identity detection advice. */
+  isDangerousShellIdentity(identity: string | undefined): boolean;
+}
+
+/**
+ * Non-replaceable permission runtime and lifecycle. Owns the pending-ask
+ * and waiter registries, request-id routing, timeout/cleanup, response
+ * validation, raw-audit denial, waiter resolution, and canonical grant
+ * construction/persistence.
+ */
+export interface PermissionRuntimeService {
+  readonly id: string;
+  /** The advice provider currently active for this runtime (the scoped
+   * provider while a scope is entered, otherwise the bound provider). */
+  readonly provider: AskPermissionPolicyService;
+
+  // Generic ask lifecycle (former tools/ask-user-api.ts surface).
+  createAskApi(
+    sessionId: string,
+    toolCallId: string,
+    toolName: string,
+    broadcastFn: AskBroadcastFn,
+    workspaceId?: string,
+    rootSessionId?: string,
+  ): AskApi;
+  resolveAsk(toolCallId: string, response: unknown, requestId?: string): Promise<boolean>;
+  rejectAsk(toolCallId: string, error: Error): Promise<boolean>;
+  rejectPendingAsksByToolCallId(toolCallId: string, error?: Error): Promise<string[]>;
+  rejectPendingAsksBySession(sessionId: string, error?: Error): Promise<string[]>;
+  hasPendingAsk(toolCallId: string): boolean;
+  getAuthorityForPendingAsk(toolCallId: string): AskAuthority | undefined;
+  getSessionIdForPendingAsk(toolCallId: string, requestId?: string): Promise<string | null>;
+  listPendingAsksBySession(sessionId: string): Promise<PendingAskRecord[]>;
+  listPendingAsksByRootSession(rootSessionId: string): Promise<PendingAskRecord[]>;
+
+  // Permission lifecycle (former tools/permission-request-manager.ts surface).
+  requestPermission(params: RequestPermissionParams): Promise<unknown>;
+  resolvePermission(requestId: string, response: unknown): Promise<boolean>;
+  rejectPermission(requestId: string, error: Error): boolean;
+  rejectPermissionsByToolCallId(toolCallId: string, error?: Error): Promise<string[]>;
+  rejectPermissionsBySession(sessionId: string, error?: Error): Promise<string[]>;
+  getPendingRequestsByRootSession(rootSessionId: string): Promise<PendingAskRecord[]>;
+  expireOldRequests(maxAgeMs: number): Promise<number>;
+  hasPendingWaiter(requestId: string): boolean;
+  getPendingWaiterCount(): number;
+}
+
+/** Capability-ask authority carrying the required client capability. */
+export type CapabilityAskAuthority = AskAuthority & {
+  requiredCapabilities?: ClientCapability[];
+};

package/src/permission/permission-request-manager.ts

@@ -0,0 +1,58 @@
+/**
+ * C6 permission lifecycle surface over the NON-REPLACEABLE permission
+ * runtime. These exports preserve the exact pre-C6
+ * `tools/permission-request-manager.ts` identities; the waiters, timers,
+ * grant reuse, validation, and audit decisions resolve through
+ * `getPermissionRuntimeService()`.
+ *
+ * The runtime enforces the mandatory deny invariant from the module-level
+ * `isValidPermissionResponse` (never from provider advice), records the raw
+ * payload in the denied audit record (preserving the pre-C6 audit
+ * behavior), and persists only the canonical `buildGrantParams` output, so
+ * a replaced advice provider can never approve malformed responses or
+ * create grants outside the canonical allowed scopes.
+ */
+
+import type { PendingAskRecord } from '../runtime/host';
+import { getPermissionRuntimeService, } from './runtime';
+import { PERMISSION_TIMEOUT } from './policy';
+import type { PermissionBroadcastFn, RequestPermissionParams } from './contracts';
+
+export { PERMISSION_TIMEOUT };
+export type { PermissionBroadcastFn, RequestPermissionParams };
+
+export function requestPermission(params: RequestPermissionParams): Promise<unknown> {
+  return getPermissionRuntimeService().requestPermission(params);
+}
+
+export async function resolvePermission(requestId: string, response: unknown): Promise<boolean> {
+  return getPermissionRuntimeService().resolvePermission(requestId, response);
+}
+
+export function rejectPermission(requestId: string, error: Error): boolean {
+  return getPermissionRuntimeService().rejectPermission(requestId, error);
+}
+
+export async function rejectPermissionsByToolCallId(toolCallId: string, error?: Error): Promise<string[]> {
+  return getPermissionRuntimeService().rejectPermissionsByToolCallId(toolCallId, error);
+}
+
+export async function rejectPermissionsBySession(sessionId: string, error?: Error): Promise<string[]> {
+  return getPermissionRuntimeService().rejectPermissionsBySession(sessionId, error);
+}
+
+export async function getPendingRequestsByRootSession(rootSessionId: string): Promise<PendingAskRecord[]> {
+  return getPermissionRuntimeService().getPendingRequestsByRootSession(rootSessionId);
+}
+
+export async function expireOldRequests(maxAgeMs: number): Promise<number> {
+  return getPermissionRuntimeService().expireOldRequests(maxAgeMs);
+}
+
+export function hasPendingWaiter(requestId: string): boolean {
+  return getPermissionRuntimeService().hasPendingWaiter(requestId);
+}
+
+export function getPendingWaiterCount(): number {
+  return getPermissionRuntimeService().getPendingWaiterCount();
+}

package/src/permission/policy.ts

@@ -0,0 +1,277 @@
+/**
+ * C6 permission policy: REPLACEABLE advice and configuration only.
+ *
+ * The non-replaceable lifecycle (waiters, routing, validation enforcement,
+ * raw-audit denial, canonical grant construction and persistence) lives in
+ * `permission/runtime.ts`. This module owns:
+ *
+ * - The frozen provider options (generic ask timeout constant and the
+ *   composition-translated permission timeout).
+ * - Authority resolution and value extraction for generic asks.
+ * - The module-level validators and canonical grant builder that BOTH the
+ *   default provider and the runtime close over. A custom provider can
+ *   override the advice methods on its instance, but the runtime never
+ *   consults those overrides for mandatory decisions.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Ask } from '@capekai/tool';
+import type {
+  AskAuthority, AskPermissionResponse, ClientCapability, GrantScope, PermissionIntent,
+} from '@capekai/types';
+import type { PermissionAsk, PermissionRiskLevel } from '@capekai/tool';
+import { SHELL_FILESYSTEM_COMMANDS } from '@capekai/tool';
+import { SHELL_DANGEROUS_COMMANDS } from '@capekai/tool';
+import { getRuntimeHost } from '../runtime/host';
+import type {
+  CreateGrantParams,
+  PendingAskRecord,
+} from '../runtime/host';
+import type {
+  AskPermissionPolicyOptions,
+  AskPermissionPolicyService,
+} from './contracts';
+
+export const ASK_TIMEOUT = 5 * 60 * 1000;
+
+/** Legacy export from the pre-C6 permission-request-manager module. */
+export const PERMISSION_TIMEOUT = 30 * 60 * 1000;
+
+const DEFAULT_ASK_AUTHORITY: AskAuthority = {
+  visibilityScope: 'controller_only',
+  resolutionMode: 'controller_only',
+};
+
+const RISK_ORDER: PermissionRiskLevel[] = ['none', 'low', 'medium', 'high', 'critical'];
+const VALID_GRANT_SCOPES: GrantScope[] = ['once', 'session', 'workspace'];
+
+export interface AskPermissionServiceCreateOptions {
+  id?: string;
+  /** Frozen composition-time options. When omitted (the process-default
+   * fallback), the permission timeout resolves live from the installed
+   * interaction host exactly like the pre-C6 module code. */
+  options?: AskPermissionPolicyOptions;
+}
+
+function interaction() {
+  return getRuntimeHost().interaction;
+}
+
+function resolveOptionsLive(): AskPermissionPolicyOptions {
+  return {
+    askTimeoutMs: ASK_TIMEOUT,
+    permissionTimeoutMs: interaction().getPermissionTimeoutMs(),
+  };
+}
+
+// ── Module-level non-overridable validators and canonical grants ─────────
+
+export function isRiskAtOrBelow(risk: PermissionRiskLevel, max: PermissionRiskLevel): boolean {
+  return RISK_ORDER.indexOf(risk) <= RISK_ORDER.indexOf(max);
+}
+
+export function isValidPermissionResponse(response: unknown): response is AskPermissionResponse {
+  if (!response || typeof response !== 'object') return false;
+  const record = response as Record<string, unknown>;
+  return record.type === 'permission' && VALID_GRANT_SCOPES.includes(record.grant as GrantScope);
+}
+
+export function isPermissionApproved(response: unknown): boolean {
+  return isValidPermissionResponse(response) && response.grant !== 'deny';
+}
+
+export function buildPermissionKey(
+  toolName: string,
+  resource: string | undefined,
+  patterns: string[] | undefined,
+): string {
+  if (patterns && patterns.length > 0) return patterns[0];
+  if (resource) return resource;
+  return toolName;
+}
+
+export function isDangerousShellIdentity(identity: string | undefined): boolean {
+  if (!identity) return false;
+  const lower = identity.toLowerCase();
+  const dangerous = SHELL_DANGEROUS_COMMANDS.some(
+    command => lower === command || lower.startsWith(command + ' '),
+  );
+  if (dangerous) return true;
+  return SHELL_FILESYSTEM_COMMANDS.some(
+    command => lower === command || lower.startsWith(command + ' '),
+  );
+}
+
+/** Canonical grant construction: the only grant-shape source the runtime
+ * persists. Enforces allowed scopes, the session-duration default, the
+ * root binding, and the dangerous-shell once downgrade. */
+export function buildGrantParams(
+  record: PendingAskRecord,
+  response: AskPermissionResponse,
+): CreateGrantParams[] {
+  if (!record.workspaceId || response.grant === 'deny') return [];
+  const permAsk = record.ask as PermissionAsk;
+  let grantScope: GrantScope = response.grant;
+  const boundRootSessionId = record.rootSessionId ?? record.sessionId;
+
+  if (permAsk.intents && permAsk.intents.length > 0) {
+    const intent: PermissionIntent = permAsk.intents[0];
+    if (!intent.allowedScopes.includes(grantScope) || grantScope === 'once') return [];
+    const duration = response.duration || (grantScope === 'session' ? 30 * 60 * 1000 : undefined);
+
+    return intent.targets.map((target) => ({
+      workspaceId: record.workspaceId!,
+      toolName: record.toolName,
+      resource: intent.resource,
+      action: intent.action,
+      permissionKey: target.target,
+      grantOptions: {
+        scope: grantScope,
+        matcher: target.matcher === 'prefix' ? 'prefix' : 'exact',
+        patterns: [target.target],
+        action: intent.action,
+        duration: grantScope === 'session' ? duration : undefined,
+        description: permAsk.question,
+        boundRootSessionId: grantScope === 'session' ? boundRootSessionId : undefined,
+      },
+    }));
+  }
+
+  const metadata = permAsk.metadata as Record<string, unknown> | undefined;
+  const identity = typeof metadata?.baseCommand === 'string' ? metadata.baseCommand : undefined;
+  if (permAsk.resource === 'shell-command' && isDangerousShellIdentity(identity)) {
+    grantScope = 'once';
+  }
+  const duration = response.duration || (grantScope === 'session' ? 30 * 60 * 1000 : undefined);
+  return [{
+    workspaceId: record.workspaceId,
+    toolName: record.toolName,
+    resource: permAsk.resource ?? 'file',
+    action: permAsk.action,
+    permissionKey: buildPermissionKey(record.toolName, permAsk.resource ?? 'file', permAsk.patterns),
+    grantOptions: {
+      scope: grantScope,
+      matcher: (permAsk.resource ?? 'file') === 'shell-command' ? 'shell-command' : 'exact',
+      patterns: permAsk.patterns,
+      action: permAsk.action,
+      duration: grantScope === 'session' ? duration : undefined,
+      description: permAsk.question,
+      boundRootSessionId: grantScope === 'session' ? boundRootSessionId : undefined,
+    },
+  }];
+}
+
+export function resolveAskAuthority(request: Ask): AskAuthority {
+  if (
+    request.type === 'client_capability'
+    && 'target' in request
+    && request.target === 'client'
+  ) {
+    return {
+      visibilityScope: 'global',
+      resolutionMode: 'first_eligible',
+      requiredCapabilities: [request.capability as ClientCapability],
+    };
+  }
+  return DEFAULT_ASK_AUTHORITY;
+}
+
+export function extractResolutionValue(response: unknown): unknown {
+  if (!response || typeof response !== 'object') return response;
+  const record = response as Record<string, unknown>;
+
+  switch (record.type) {
+    case 'single_select':
+      return record.value;
+    case 'multi_select':
+      return record.values;
+    case 'text':
+      return record.value;
+    case 'confirm':
+      return record.confirmed;
+    case 'form':
+      return response;
+    case 'client_capability':
+      return record.result;
+    default:
+      return response;
+  }
+}
+
+/** The C6 default advice provider wrapping the exact pre-C6 behavior. */
+export function createAskPermissionService(
+  createOptions: AskPermissionServiceCreateOptions = {},
+): AskPermissionPolicyService {
+  const id = createOptions.id ?? 'permission.default';
+  const frozenOptions = createOptions.options;
+
+  function options(): AskPermissionPolicyOptions {
+    return frozenOptions ?? resolveOptionsLive();
+  }
+
+  return {
+    id,
+    get options(): Readonly<AskPermissionPolicyOptions> {
+      return options();
+    },
+    get askTimeoutMs(): number {
+      return options().askTimeoutMs;
+    },
+    get permissionTimeoutMs(): number {
+      return options().permissionTimeoutMs;
+    },
+    resolveAskAuthority,
+    extractResolutionValue,
+    isValidPermissionResponse,
+    isPermissionApproved,
+    isRiskAtOrBelow,
+    async shouldAutoApprove(sessionId: string, ask: Ask): Promise<boolean> {
+      if (ask.type !== 'permission') return false;
+      const risk = (ask as PermissionAsk).risk;
+      if (!risk) return false;
+
+      const maxSeverity = await interaction().getSessionAutoApproveSeverity(sessionId);
+      if (!maxSeverity || maxSeverity === 'off') return false;
+      if (!isRiskAtOrBelow(risk, maxSeverity)) return false;
+
+      console.log(
+        `[permissions] Server auto-approve: risk=${risk} maxSeverity=${maxSeverity} session=${sessionId}`,
+      );
+      return true;
+    },
+    buildPermissionKey,
+    isDangerousShellIdentity,
+  };
+}
+
+const scopedPolicy = new AsyncLocalStorage<AskPermissionPolicyService>();
+let processDefaultPolicy: AskPermissionPolicyService | undefined;
+
+/** Resolves the service seeded for the active agent scope, falling back to
+ * one lazily created process-default service for consumers that run outside
+ * a composed scope (the current Jean2 server path). */
+export function getAskPermissionPolicy(): AskPermissionPolicyService {
+  return scopedPolicy.getStore()
+    ?? (processDefaultPolicy ??= createAskPermissionService({ id: 'permission.process-default' }));
+}
+
+/** The scoped policy only (undefined outside a composed scope). Used by the
+ * runtime to prefer the actively seeded advice provider. */
+export function getActiveAskPermissionPolicy(): AskPermissionPolicyService | undefined {
+  return scopedPolicy.getStore();
+}
+
+/** Seeds a service for the callback duration. `enterAgentScope` seeds the
+ * composed agent scope's service here. */
+export function withAskPermissionPolicy<T>(
+  service: AskPermissionPolicyService,
+  callback: () => T,
+): T {
+  return scopedPolicy.run(service, callback);
+}
+
+/** Test-only reset of the lazily created process default. Exported from this
+ * module only; no package subpath re-exports it. */
+export function resetDefaultAskPermissionPolicyForTests(): void {
+  processDefaultPolicy = undefined;
+}