Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.5 KB
Raw Blame
import { operations } from '../operations.ts';
import { BRAIN_TOOL_ALLOWLIST } from '../minions/tools/brain-allowlist.ts';
import { operationScopesAllowed } from '../scope.ts';
import { opAllowedForBoundClient } from '../ops/context.ts';
import { GrantError, type ClientGrant, type GrantPatch, type GrantProfileId, type GrantValidationContext } from './model.ts';
import { VERSION } from '../../version.ts';
import { INSTALL_SURFACE_SET_BY } from '../../mcp/surface.ts';

export const RENEWABLE_GRANT_TTL_SECONDS = 3600;

/** Harness and bot profiles: a new grant calls the full surface and lists the memory verbs (INSTALL_SURFACE_SET_BY). */
const VERBS_LISTED_PROFILES: ReadonlySet<GrantProfileId> = new Set(['memory-reader', 'memory-writer', 'coding-agent']);
export const STATIC_GRANT_TTL_SECONDS = 30 * 24 * 3600;

export function grantCatalog(): Pick<GrantValidationContext, 'operationNames' | 'delegateToolNames'> {
  return {
    operationNames: new Set(operations.filter(op => !op.localOnly).map(op => op.name)),
    // The local worker allowlist includes files helpers that are not confined
    // by a remote source grant. Local-only operations never enter remote grants.
    delegateToolNames: new Set(operations.filter(op => !op.localOnly && BRAIN_TOOL_ALLOWLIST.has(op.name)).map(op => op.name)),
  };
}

/**
 * The operation catalog an operation snapshot was written against. Stored on
 * the grant's audit record when a snapshot is written, so a later diagnosis can
 * tell operations added after the snapshot from ones left out of it. Grants
 * written before this existed have none, and none is ever synthesized for them.
 */
export interface CatalogProvenance { version: 1; gbrain_version: string; operations: string[] }

export function catalogProvenance(): CatalogProvenance {
  return { version: 1, gbrain_version: VERSION, operations: [...grantCatalog().operationNames].sort() };
}

/** Explicit profile application is a regrant; ordinary repair does not call this. */
export function resolveGrantProfile(opts: {
  profile: GrantProfileId;
  sourceId: string;
  federatedRead?: string[];
  boundSlugPrefixes?: string[] | null;
  delegatedSlugPrefixes?: string[] | null;
  boundTools?: string[];
  delegatedNamespace?: 'prefixes' | 'job';
  staticToken?: boolean;
  existing?: ClientGrant;
}): GrantPatch {
  const scopes = {
    'memory-reader': ['read'], 'memory-writer': ['read', 'write'],
    'coding-agent': ['read', 'write'], operator: ['admin'],
    'delegating-agent': ['read', 'write', 'agent'], full: ['admin', 'agent'],
  }[opts.profile];
  if (!scopes) throw new GrantError('invalid_grant', `Unknown profile: ${opts.profile}`);
  const delegated = scopes.includes('agent');
  if (delegated && !(opts.boundTools ?? opts.existing?.boundTools)?.length) throw new GrantError('invalid_grant', 'Delegating profiles require explicit non-empty --bound-tools');
  const directPrefixes = opts.boundSlugPrefixes !== undefined ? opts.boundSlugPrefixes : opts.existing?.boundSlugPrefixes ?? null;
  if (opts.profile === 'coding-agent' && !directPrefixes?.length) throw new GrantError('invalid_grant', 'coding-agent requires an explicit isolated write namespace');
  const allowedOperations = operations.filter(op => !op.localOnly
    && operationScopesAllowed(scopes, op)
    && opAllowedForBoundClient({ boundSlugPrefixes: directPrefixes ?? undefined }, op)).map(op => op.name).sort();
  return {
    profile: opts.profile, scopes, sourceId: opts.sourceId,
    federatedRead: opts.federatedRead ?? opts.existing?.federatedRead ?? [opts.sourceId],
    boundSlugPrefixes: directPrefixes, allowedOperations,
    surface: opts.profile === 'delegating-agent' ? 'starter' : 'full',
    surfaceSetBy: VERBS_LISTED_PROFILES.has(opts.profile) && (!opts.existing || opts.existing.surfaceSetBy === INSTALL_SURFACE_SET_BY)
      ? INSTALL_SURFACE_SET_BY : 'operator',
    boundTools: delegated ? opts.boundTools ?? opts.existing?.boundTools ?? null : null,
    boundSourceId: delegated ? opts.sourceId : null,
    boundBrainId: null,
    delegatedSlugPrefixes: delegated ? (opts.delegatedSlugPrefixes !== undefined ? opts.delegatedSlugPrefixes : opts.existing?.delegatedSlugPrefixes ?? null) : null,
    delegatedNamespace: opts.delegatedNamespace ?? (opts.delegatedSlugPrefixes ? 'prefixes' : opts.existing?.delegatedNamespace ?? 'job'),
    boundMaxConcurrent: opts.existing?.boundMaxConcurrent ?? 1,
    budgetUsdPerDay: opts.existing?.budgetUsdPerDay ?? null,
    tokenTtlSeconds: opts.existing?.tokenTtlSeconds ?? (opts.staticToken ? STATIC_GRANT_TTL_SECONDS : RENEWABLE_GRANT_TTL_SECONDS),
    repairReasons: [],
  };
}