Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.4 KB
Raw Blame
import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
import { opError, OperationError, type OperationContext } from '../ops/contract.ts';
import { hostFix } from '../ops/op-fix.ts';
import { catalogFix, skillHeadFix } from './fixes.ts';
import { sourceScopeOpts } from '../ops/context.ts';
import { stableJson } from '../persistence/digest.ts';
import { approvedFiles, authorizeSkillRead, legacySharedSkillPolicy, normalizePolicy, publicationEnabled, readSharedSkillPolicy, skillPrincipal } from './policy.ts';
import { skillName, skillPath, skillToolsDeclared } from './manifest.ts';
import { SHARED_SKILL_LIMITS, type SharedSkillDetail, type SharedSkillKey, type SharedSkillList, type SharedSkillSelector,
  type SharedSkillSummary, type SharedSkillPolicy, type StoredSkillRevision } from './model.ts';

export function qualifiedSkillId(key: SharedSkillKey): string {
  return `skill:${[key.brain_id, key.source_id, key.source_incarnation, key.pack_id, key.name].map(encodeURIComponent).join(':')}`;
}
const QUALIFIED_ID_HINT = 'Pass qualified_id exactly as list_skills (schema_version 2) returned it; it is an opaque, URL-encoded key, never built by hand.';
export function parseQualifiedSkillId(value: string): SharedSkillKey {
  const parts = value.split(':');
  if (parts.length !== 6 || parts.shift() !== 'skill') throw opError('invalid_params', 'Invalid qualified skill key.', QUALIFIED_ID_HINT, { fix: catalogFix() });
  try {
    const [brain_id, source_id, source_incarnation, pack_id, name] = parts.map(decodeURIComponent);
    skillName(pack_id, 'pack_id'); skillName(name);
    return { brain_id, source_id, source_incarnation, pack_id, name };
  } catch { throw opError('invalid_params', 'Invalid qualified skill key.', QUALIFIED_ID_HINT, { fix: catalogFix() }); }
}
async function identity(ctx: OperationContext) {
  const [row] = await ctx.engine.executeRaw<{ brain_id: string; token_secret: string; serving_epoch: string }>(
    'SELECT b.brain_id,s.token_secret,s.serving_epoch FROM persistence_brain b CROSS JOIN shared_skill_state s WHERE b.singleton=1 AND s.singleton=1');
  if (!row) throw new OperationError('catalog_unavailable', 'Shared skill storage is not initialized.', 'Apply host migrations before retrying.');
  return row;
}
function opaque(secret: string, value: unknown): string { return createHmac('sha256', Buffer.from(secret, 'hex')).update(stableJson(value)).digest('base64url'); }
function encodeCursor(secret: string, value: unknown): string {
  const nonce = randomBytes(12);
  const cipher = createCipheriv('aes-256-gcm', Buffer.from(secret, 'hex'), nonce, { authTagLength: 16 });
  const content = Buffer.concat([cipher.update(stableJson(value), 'utf8'), cipher.final()]);
  return Buffer.concat([nonce, cipher.getAuthTag(), content]).toString('base64url');
}
function decodeCursor(secret: string, value: string): { auth: string; view: string; offset: number; limit: number; expires: number } {
  try {
    if (value.length > 4096) throw new Error();
    const data = Buffer.from(value, 'base64url');
    if (data.length < 28) throw new Error();
    const decipher = createDecipheriv('aes-256-gcm', Buffer.from(secret, 'hex'), data.subarray(0, 12), { authTagLength: 16 });
    decipher.setAuthTag(data.subarray(12, 28));
    return JSON.parse(Buffer.concat([decipher.update(data.subarray(28)), decipher.final()]).toString());
  } catch {
    throw opError('full_resync_required', 'The catalog cursor is invalid or expired.',
      'Restart enumeration: call list_skills with schema_version 2 and no cursor, and replace every page read so far with the new snapshot.', { fix: catalogFix() });
  }
}
async function readSnapshot(ctx: OperationContext, selector: SharedSkillSelector = {}) {
  const ids = sourceScopeOpts(ctx);
  const sourceIds = ids.sourceIds ?? (ids.sourceId ? [ids.sourceId] : null);
  const rows = await ctx.engine.executeRaw<Omit<StoredSkillRevision, 'files'> & { current_policy: SharedSkillPolicy | null; current_epoch: string | null }>(`SELECT h.*,p.policy AS current_policy,p.epoch AS current_epoch FROM shared_skill_heads h
    JOIN sources s ON s.id=h.source_id AND s.incarnation=h.source_incarnation
    LEFT JOIN shared_skill_policies p ON p.source_id=h.source_id AND p.source_incarnation=h.source_incarnation
    WHERE NOT h.deleted AND NOT s.archived AND ($1::text[] IS NULL OR h.source_id=ANY($1::text[]))
    AND ($3::text IS NULL OR h.source_id=$3) AND ($4::text IS NULL OR h.source_incarnation::text=$4)
    AND ($5::text IS NULL OR h.pack_id=$5) AND ($6::text IS NULL OR h.name=$6)
    AND ($7::boolean=false OR COALESCE((h.metadata->>'private')::boolean,false)=false)
    ORDER BY h.source_id,h.source_incarnation,h.pack_id,h.name LIMIT $2`,
  [sourceIds, SHARED_SKILL_LIMITS.catalogSkills + 1, selector.source_id ?? null, selector.source_incarnation ?? null, selector.pack_id ?? null, selector.name ?? null, ctx.remote !== false]);
  if (rows.length > SHARED_SKILL_LIMITS.catalogSkills) {
    throw opError('catalog_unavailable', 'The authorized catalog exceeds its bounded snapshot limit.',
      `More than ${SHARED_SKILL_LIMITS.catalogSkills} skills match; narrow the request to one source with source_id (and pack_id or name where known).`);
  }
  const brain = await identity(ctx);
  const enabled = await publicationEnabled(ctx);
  if (ctx.remote !== false && !enabled) {
    throw opError('permission_denied', 'Shared skills are not published by this brain.',
      'The brain owner has not enabled mcp.publish_skills, so connections like this one see no shared skills. Ask the user whether the owner wants to publish them; only the brain host can turn it on.',
      { fix: hostFix(ctx, ['gbrain', 'config', 'set', 'mcp.publish_skills', 'true'], 'Publishes the owner-approved shared skills to authenticated MCP connections; each source\'s publication policy still limits what they see.', { consent: ['egress'] }) });
  }
  const principal = skillPrincipal(ctx);
  const { sharedSkillToolAccess } = await import('./tool-access.ts');
  const availableTools = new Set(await sharedSkillToolAccess(ctx));
  const skills: SharedSkillSummary[] = [];
  for (const row of rows) {
    const policy = row.current_policy ? { epoch: row.current_epoch!, policy: normalizePolicy(row.current_policy) } : legacySharedSkillPolicy(enabled);
    if (!policy.policy.enabled || ctx.remote !== false && row.metadata.private ||
      !row.metadata.audience.some(a => (a === 'readers' || a === principal) && policy!.policy.audiences.includes(a))) continue;
    const skillKey = { brain_id: brain.brain_id, source_id: row.source_id, source_incarnation: row.source_incarnation, pack_id: row.pack_id, name: row.name };
    const { file_policy, tools_declared: _toolsDeclared, ...metadata } = row.metadata;
    const inherits = !skillToolsDeclared(row.metadata, null);
    const complete = file_policy.every(f => policy!.policy.classes.includes(f.file_class) && f.audience.some(a => (a === 'readers' || a === principal) && policy!.policy.audiences.includes(a)));
    const tools = metadata.requirements.filter(r => r.startsWith('tool:')).map(r => r.slice(5));
    const unavailable = metadata.requirements.filter(r => !r.startsWith('tool:') || !availableTools.has(r.slice(5)) ||
      row.current_policy !== null && !policy.policy.requirements.includes(r));
    skills.push({ ...skillKey, ...metadata, audience: metadata.audience.filter(a => a === 'readers' || a === principal), qualified_id: qualifiedSkillId(skillKey), revision: row.revision,
      policy_epoch: policy.epoch, allow_follow: policy.policy.allow_follow,
      delivery: complete ? 'complete' : 'prose_only', usable: complete && unavailable.length === 0,
      usable_tools: inherits ? [...availableTools] : tools.filter(t => availableTools.has(t)), unavailable_tools: inherits ? [] : tools.filter(t => !availableTools.has(t)), unavailable_requirements: unavailable });
  }
  const auth = opaque(brain.token_secret, { principal, sources: sourceIds, scopes: ctx.auth?.scopes,
    operations: ctx.auth?.allowedOperations, surface: ctx.auth?.effectiveSurface, grant_revision: ctx.auth?.grantRevision, serving_epoch: brain.serving_epoch });
  const view = opaque(brain.token_secret, { auth, skills });
  return { brain, auth, view, skills, enabled, principal };
}
async function catalogRead<T>(ctx: OperationContext, operation: string, run: (ctx: OperationContext) => Promise<T>): Promise<T> {
  try {
    return await ctx.engine.transaction(async tx => run(await authorizeSkillRead({ ...ctx, engine: tx }, operation)));
  } catch (error) {
    if (error instanceof OperationError) throw error;
    throw new OperationError('catalog_unavailable', 'The authoritative catalog could not be read.', 'Retry without advancing a cursor or deleting installed files.');
  }
}
export async function listSharedSkills(ctx: OperationContext, params: { limit?: number; cursor?: string; source_id?: string } = {}): Promise<SharedSkillList> {
  return catalogRead(ctx, 'list_skills', async active => {
    const snapshot = await readSnapshot(active, { source_id: params.source_id });
    const limit = params.limit ?? 50;
    if (!Number.isInteger(limit) || limit < 1 || limit > SHARED_SKILL_LIMITS.pageSize) {
      throw opError('invalid_params', 'Catalog limit must be 1-100.', `Pass limit as a whole number from 1 to ${SHARED_SKILL_LIMITS.pageSize}, or omit it for 50.`);
    }
    const skills = params.source_id ? snapshot.skills.filter(s => s.source_id === params.source_id) : snapshot.skills;
    const view = opaque(snapshot.brain.token_secret, { view: snapshot.view, source: params.source_id ?? null });
    let offset = 0;
    if (params.cursor) {
      const cursor = decodeCursor(snapshot.brain.token_secret, params.cursor);
      if (cursor.auth !== snapshot.auth || cursor.view !== view || cursor.limit !== limit || cursor.expires < Date.now() || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0) {
        throw opError('full_resync_required', 'The authorized catalog changed; restart enumeration.',
          'The catalog or this connection\'s grant changed since the cursor was issued (or it expired after 15 minutes). Restart with list_skills schema_version 2, the same limit and no cursor, and replace every page read so far.',
          { fix: catalogFix(params.source_id) });
      }
      offset = cursor.offset;
    }
    return { schema_version: 2, brain_id: snapshot.brain.brain_id, view_token: view, skills: skills.slice(offset, offset + limit),
      ...(offset + limit < skills.length ? { next_cursor: encodeCursor(snapshot.brain.token_secret,
        { auth: snapshot.auth, view, offset: offset + limit, limit, expires: Date.now() + 15 * 60_000 }) } : {}) };
  });
}
function selectSkill(skills: SharedSkillSummary[], params: SharedSkillSelector): SharedSkillSummary {
  const supplied: SharedSkillSelector = params.qualified_id ? parseQualifiedSkillId(params.qualified_id) : params;
  if (!supplied.name) {
    throw opError('invalid_params', 'name or qualified_id is required.',
      'Pass the qualified_id list_skills (schema_version 2) returned, or name with pack_id and source_id.', { fix: catalogFix(params.source_id) });
  }
  skillName(supplied.name);
  if (params.qualified_id && Object.entries(supplied).some(([key, value]) => params[key as keyof SharedSkillSelector] !== undefined && params[key as keyof SharedSkillSelector] !== value)) {
    throw opError('invalid_params', 'Qualified key disagrees with selector fields.',
      'Pass qualified_id alone, or selector fields (source_id, source_incarnation, pack_id, name) that match it; drop the conflicting fields.');
  }
  const matches = skills.filter(skill => ['brain_id', 'source_id', 'source_incarnation', 'pack_id', 'name'].every(key =>
    supplied[key as keyof SharedSkillSelector] === undefined || supplied[key as keyof SharedSkillSelector] === skill[key as keyof SharedSkillSummary]));
  if (!matches.length) {
    throw opError('skill_not_found', 'No authorized published skill matches this key.',
      'No published skill this connection may read matches the selector. List the catalog for the exact name, pack_id and source_id.', { fix: catalogFix(supplied.source_id) });
  }
  if (matches.length > 1) throw new OperationError('ambiguous_skill', 'This name belongs to multiple authorized sources.', 'Use a qualified_id from list_skills schema_version=2.');
  return matches[0];
}
async function detail(active: OperationContext, params: SharedSkillSelector) {
  const selector = params.qualified_id ? parseQualifiedSkillId(params.qualified_id) : params;
  const snapshot = await readSnapshot(active, selector);
  const selected = selectSkill(snapshot.skills, params);
  const revision = params.revision ?? selected.revision;
  if (typeof revision !== 'string' || !/^[0-9a-f-]{36}$/i.test(revision)) {
    throw opError('invalid_params', 'Invalid skill revision.', 'Pass revision as the UUID list_skills or get_skill returned, or omit it for the current head.',
      { fix: skillHeadFix(selected.source_id, selected.pack_id, selected.name) });
  }
  const [row] = await active.engine.executeRaw<StoredSkillRevision>(`SELECT * FROM shared_skill_revisions
    WHERE source_id=$1 AND source_incarnation=$2::uuid AND pack_id=$3 AND name=$4 AND revision=$5::uuid AND NOT deleted`,
  [selected.source_id, selected.source_incarnation, selected.pack_id, selected.name, revision]);
  if (!row || active.remote !== false && row.metadata.private) {
    throw opError('revision_unavailable', 'The exact authorized revision is unavailable.',
      `That revision of ${selected.pack_id}/${selected.name} was deleted, pruned or is private. Read the current head instead (omit revision).`,
      { fix: skillHeadFix(selected.source_id, selected.pack_id, selected.name) });
  }
  const { epoch, policy } = await readSharedSkillPolicy(active.engine, selected.source_id, selected.source_incarnation, snapshot.enabled);
  const files = approvedFiles(row.files, policy, snapshot.principal);
  const main = files.find(f => f.path === `skills/${selected.name}/SKILL.md`);
  if (!main) {
    throw opError('skill_not_found', 'This skill is not published to the current audience.',
      `${selected.pack_id}/${selected.name}'s SKILL.md is not approved for this connection's audience under source ${selected.source_id}'s policy; only the publisher can change that.`,
      { fix: catalogFix(selected.source_id) });
  }
  const visible = new Set(files.map(f => f.path));
  const complete = files.length === row.files.length && files.every(f => f.depends_on.every(d => visible.has(d)));
  const { file_policy: _filePolicy, tools_declared: _toolsDeclared, ...metadata } = row.metadata;
  const { sharedSkillToolAccess } = await import('./tool-access.ts');
  const access = await sharedSkillToolAccess(active);
  const tools = new Set(access);
  const body = Buffer.from(main.content, 'base64').toString('utf8');
  const inherits = !skillToolsDeclared(row.metadata, body);
  const declaredTools = metadata.requirements.filter(r => r.startsWith('tool:')).map(r => r.slice(5));
  const unavailable = metadata.requirements.filter(r => !r.startsWith('tool:') || !tools.has(r.slice(5)) ||
    !['legacy-prose', 'consent-required'].includes(epoch) && !policy.requirements.includes(r));
  const result: SharedSkillDetail = { ...selected, ...metadata, audience: metadata.audience.filter(a => a === 'readers' || a === snapshot.principal), revision: row.revision, schema_version: 2,
    delivery: complete ? 'complete' : 'prose_only', body,
    usable_tools: inherits ? access : declaredTools.filter(t => tools.has(t)), unavailable_tools: inherits ? [] : declaredTools.filter(t => !tools.has(t)),
    unavailable_requirements: unavailable, usable: complete && unavailable.length === 0,
    files: files.map(({ content: _content, ...file }) => ({ ...file, audience: file.audience.filter(a => a === 'readers' || a === snapshot.principal), depends_on: file.depends_on.filter(d => visible.has(d)) })) };
  return { result, files };
}
export async function getSharedSkill(ctx: OperationContext, params: SharedSkillSelector): Promise<SharedSkillDetail> {
  return catalogRead(ctx, 'get_skill', async active => (await detail(active, params)).result);
}
export async function getSharedSkillAsset(ctx: OperationContext, params: SharedSkillSelector & { path: string }) {
  return catalogRead(ctx, 'get_skill_asset', async active => {
    if (!params.revision) {
      throw opError('invalid_params', 'Asset reads require the exact approved revision.',
        'Pass revision from get_skill (schema_version 2) for this skill; asset reads never follow the moving head.',
        params.source_id && params.pack_id && params.name ? { fix: skillHeadFix(params.source_id, params.pack_id, params.name) } : {});
    }
    skillPath(params.path);
    const { result, files } = await detail(active, params);
    const file = files.find(f => f.path === params.path);
    if (!file) {
      throw opError('skill_asset_not_found', 'The requested file is not in the approved revision manifest.',
        `Request one of the paths in the files list get_skill returns for revision ${result.revision} of ${result.pack_id}/${result.name}; other paths are not approved for this connection.`,
        { fix: skillHeadFix(result.source_id, result.pack_id, result.name, result.revision) });
    }
    return { schema_version: 2 as const, brain_id: result.brain_id, source_id: result.source_id, source_incarnation: result.source_incarnation,
      pack_id: result.pack_id, name: result.name, revision: result.revision, path: file.path,
      encoding: 'base64' as const, content: file.content, sha256: file.sha256, size: file.size, media_type: file.media_type };
  });
}
export { submitSharedSkillMutation, adoptSharedSkillpack, importSharedSkillProposal } from './publication.ts';