oathbound 0.12.0 → 0.13.0

package/agent-push.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { intro, outro } from '@clack/prompts';
+import { parse as yamlParse } from 'yaml';
+import { BRAND, GREEN, DIM, BOLD, RESET, fail, spinner } from './ui';
+import { getAccessToken } from './auth';
+import { isValidSemver } from './semver';
+
+const API_BASE = process.env.OATHBOUND_API_URL ?? 'https://www.oathbound.ai';
+
+/** Parse YAML frontmatter from an agent .md file. */
+function parseAgentFrontmatter(content: string): {
+  meta: Record<string, unknown>;
+  body: string;
+} {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+  const parsed = yamlParse(match[1]);
+  const meta: Record<string, unknown> =
+    parsed && typeof parsed === 'object' ? parsed : {};
+  return { meta, body: match[2] };
+}
+
+/** Resolve agent .md file path from user argument or auto-detect. */
+function resolveAgentFile(pathArg?: string): string {
+  if (pathArg) {
+    const resolved = resolve(pathArg);
+    if (!existsSync(resolved)) {
+      fail('File not found', resolved);
+    }
+    if (statSync(resolved).isDirectory()) {
+      // Look for a single .md file with agent frontmatter in the directory
+      return findAgentInDir(resolved);
+    }
+    if (!resolved.endsWith('.md')) {
+      fail('Invalid file', 'Agent files must be .md files');
+    }
+    return resolved;
+  }
+
+  // No path — look in cwd for a single .md with agent frontmatter
+  return findAgentInDir(process.cwd());
+}
+
+/** Find a single agent .md file in a directory. */
+function findAgentInDir(dir: string): string {
+  const mdFiles = readdirSync(dir)
+    .filter(f => f.endsWith('.md') && !f.startsWith('.'))
+    .map(f => join(dir, f));
+
+  const agents: string[] = [];
+  for (const file of mdFiles) {
+    try {
+      const content = readFileSync(file, 'utf-8');
+      const { meta, body } = parseAgentFrontmatter(content);
+      if (meta.name && meta.description && body.trim()) {
+        agents.push(file);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (agents.length === 0) {
+    fail(
+      'No agent file found',
+      'Run from a directory with an agent .md file, or pass a path: oathbound agent push ./my-agent.md',
+    );
+  }
+
+  if (agents.length > 1) {
+    fail(
+      'Multiple agent files found',
+      `Found ${agents.length} .md files with agent frontmatter. Specify which one: oathbound agent push ./file.md`,
+    );
+  }
+
+  return agents[0];
+}
+
+export async function agentPush(pathArg?: string, options?: { private?: boolean }): Promise<void> {
+  intro(BRAND);
+
+  const agentFile = resolveAgentFile(pathArg);
+  const content = readFileSync(agentFile, 'utf-8');
+  const { meta, body } = parseAgentFrontmatter(content);
+
+  // Validate required fields
+  const name = String(meta.name ?? '');
+  const description = String(meta.description ?? '');
+  const license = String(meta.license ?? '');
+  if (!name) fail('Frontmatter missing: name');
+  if (!description) fail('Frontmatter missing: description');
+  if (!license) fail('Frontmatter missing: license');
+  if (!body.trim()) fail('No system prompt (markdown body) after frontmatter');
+
+  const rawVersion = meta.version != null ? String(meta.version) : null;
+  const version = rawVersion && isValidSemver(rawVersion) ? rawVersion : null;
+
+  console.log(`${DIM}   file: ${agentFile}${RESET}`);
+  console.log(`${DIM}   name: ${name}${RESET}`);
+  console.log(`${DIM}   version: ${version ?? 'auto (next)'}${RESET}`);
+  console.log(`${DIM}   license: ${license}${RESET}`);
+  if (meta.model) console.log(`${DIM}   model: ${meta.model}${RESET}`);
+  if (meta.permissionMode) console.log(`${DIM}   permissionMode: ${meta.permissionMode}${RESET}`);
+
+  const visibility = options?.private ? 'private' : 'public';
+  if (options?.private) {
+    console.log(`${DIM}   visibility: ${BOLD}private${RESET}`);
+  }
+
+  // Authenticate
+  const token = await getAccessToken();
+
+  // Build request body
+  const requestBody: Record<string, unknown> = {
+    name,
+    description,
+    license,
+    version,
+    systemPrompt: body,
+    tools: meta.tools != null ? String(meta.tools) : null,
+    disallowedTools: meta.disallowedTools != null ? String(meta.disallowedTools) : null,
+    model: meta.model != null ? String(meta.model) : null,
+    permissionMode: meta.permissionMode != null ? String(meta.permissionMode) : null,
+    maxTurns: meta.maxTurns != null ? Number(meta.maxTurns) : null,
+    memoryScope: meta.memory != null ? String(meta.memory) : null,
+    background: meta.background != null ? Boolean(meta.background) : null,
+    effort: meta.effort != null ? String(meta.effort) : null,
+    isolation: meta.isolation != null ? String(meta.isolation) : null,
+    config: {
+      hooks: meta.hooks ?? null,
+      mcpServers: meta.mcpServers ?? null,
+      skillsRefs: Array.isArray(meta.skills) ? meta.skills : null,
+      initialPrompt: meta.initialPrompt != null ? String(meta.initialPrompt) : null,
+    },
+    compatibility: meta.compatibility != null ? String(meta.compatibility) : null,
+    originalAuthor: meta['original-author'] != null ? String(meta['original-author']) : null,
+    visibility,
+  };
+
+  // Push to API
+  const spin = spinner('Pushing...');
+
+  const response = await fetch(`${API_BASE}/api/agents`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(requestBody),
+  });
+
+  spin.stop();
+
+  if (!response.ok) {
+    const resBody = await response.json().catch(() => ({ error: 'Unknown error' }));
+    const details = Array.isArray(resBody.details)
+      ? '\n' + resBody.details.map((d: string) => `   - ${d}`).join('\n')
+      : '';
+    fail(`Push failed (${response.status})`, `${resBody.error}${details}`);
+  }
+
+  const result = await response.json();
+
+  outro(`${GREEN}✓ Published ${BOLD}${result.namespace}/${result.name}${RESET}${GREEN} v${result.version}${RESET}`);
+  if (result.suiObjectId) {
+    console.log(`${DIM}   on-chain: ${result.suiObjectId}${RESET}`);
+  }
+}

package/agent-search.ts

@@ -0,0 +1,155 @@
+import { BRAND, TEAL, GREEN, DIM, BOLD, RESET, fail, spinner } from './ui';
+
+const API_BASE = process.env.OATHBOUND_API_URL ?? 'https://www.oathbound.ai';
+
+export interface AgentSearchOptions {
+  query?: string;
+  namespace?: string;
+  sparse?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export function parseAgentSearchArgs(args: string[]): AgentSearchOptions {
+  const opts: AgentSearchOptions = {};
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--user' || arg === '-u') {
+      opts.namespace = args[++i];
+    } else if (arg === '--sparse' || arg === '-s') {
+      opts.sparse = true;
+    } else if (arg === '--limit') {
+      opts.limit = parseInt(args[++i], 10);
+    } else if (arg === '--offset') {
+      opts.offset = parseInt(args[++i], 10);
+    } else if (!arg.startsWith('-')) {
+      opts.query = arg;
+    }
+
+    i++;
+  }
+
+  return opts;
+}
+
+interface AgentAuthor {
+  username: string;
+  display_name: string | null;
+  verified: boolean;
+}
+
+interface AgentResult {
+  name: string;
+  namespace: string;
+  description: string;
+  version: string;
+  license?: string;
+  visibility?: string;
+  model?: string | null;
+  tools?: string | null;
+  permission_mode?: string | null;
+  effort?: string | null;
+  author?: AgentAuthor;
+}
+
+interface AgentSearchResponse {
+  ok: boolean;
+  agents: AgentResult[];
+  total: number;
+  limit: number;
+  offset: number;
+  error?: string;
+}
+
+export async function agentSearch(opts: AgentSearchOptions): Promise<void> {
+  const params = new URLSearchParams();
+  if (opts.query) params.set('q', opts.query);
+  if (opts.namespace) params.set('namespace', opts.namespace);
+  if (opts.sparse) params.set('sparse', 'true');
+  if (opts.limit != null) params.set('limit', String(opts.limit));
+  if (opts.offset != null) params.set('offset', String(opts.offset));
+
+  const url = `${API_BASE}/api/agents?${params}`;
+
+  const sp = spinner('Searching agents...');
+
+  let res: Response;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    sp.stop();
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    fail('Search failed', msg);
+  }
+
+  sp.stop();
+
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try {
+      const body = await res.json() as { error?: string };
+      if (body.error) detail = body.error;
+    } catch { /* ignore parse errors */ }
+    fail('Search failed', detail);
+  }
+
+  const data = await res.json() as AgentSearchResponse;
+
+  if (!data.ok || !data.agents) {
+    fail('Search failed', data.error ?? 'Unexpected response');
+  }
+
+  const { agents, total, offset } = data;
+
+  if (agents.length === 0) {
+    console.log(`\n${BRAND} ${DIM}No agents found.${RESET}`);
+    return;
+  }
+
+  const showing = offset > 0
+    ? `Showing ${offset + 1}–${offset + agents.length} of ${total}`
+    : `${total} agent${total === 1 ? '' : 's'} found`;
+
+  console.log(`\n${BRAND} ${TEAL}${showing}${RESET}\n`);
+
+  for (const agent of agents) {
+    const id = `${agent.namespace}/${agent.name}`;
+    const ver = `v${agent.version}`;
+
+    // Line 1: name + version
+    console.log(`  ${BOLD}${id}${RESET} ${DIM}${ver}${RESET}`);
+
+    // Line 2: description
+    if (agent.description) {
+      console.log(`  ${DIM}${agent.description}${RESET}`);
+    }
+
+    // Line 3: agent-specific metadata (non-sparse only)
+    if (!opts.sparse) {
+      const parts: string[] = [];
+      if (agent.author) {
+        const name = agent.author.display_name || agent.author.username;
+        parts.push(`by ${name}${agent.author.verified ? ' ✓' : ''}`);
+      }
+      if (agent.license) parts.push(agent.license);
+      if (agent.model) parts.push(`model: ${agent.model}`);
+      if (agent.permission_mode) parts.push(`mode: ${agent.permission_mode}`);
+      if (agent.effort) parts.push(`effort: ${agent.effort}`);
+      if (agent.visibility === 'private') parts.push('private');
+      if (parts.length > 0) {
+        console.log(`  ${DIM}${parts.join(' · ')}${RESET}`);
+      }
+    }
+
+    console.log(); // blank line between agents
+  }
+
+  // Pagination hint
+  if (offset + agents.length < total) {
+    const nextOffset = offset + agents.length;
+    console.log(`${DIM}  Use --offset ${nextOffset} to see more${RESET}\n`);
+  }
+}

package/cli.ts

@@ -10,7 +10,7 @@ import { join, basename } from 'node:path';
 import { tmpdir } from 'node:os';
 import { intro, outro, select, confirm, cancel, isCancel } from '@clack/prompts';
 
-import { BRAND, TEAL, GREEN, RED, YELLOW, DIM, BOLD, RESET, usage, fail, spinner } from './ui';
+import { BRAND, TEAL, GREEN, RED, YELLOW, DIM, BOLD, RESET, usage, agentUsage, fail, spinner } from './ui';
 import {
   stripJsoncComments, writeOathboundConfig, mergeClaudeSettings,
   type EnforcementLevel, type MergeResult,
@@ -21,13 +21,15 @@ import { verify, verifyCheck, findSkillsDir } from './verify';
 import { login, logout, whoami } from './auth';
 import { push } from './push';
 import { search, parseSearchArgs } from './search';
+import { agentPush } from './agent-push';
+import { agentSearch, parseAgentSearchArgs } from './agent-search';
 
 // Re-exports for tests
 export { stripJsoncComments, writeOathboundConfig, mergeClaudeSettings, type MergeResult } from './config';
 export { isNewer } from './update';
 export { installDevDependency, type InstallResult, setup, addPrepareScript, type PrepareResult, addTrustedDependency, type TrustedDepResult };
 
-const VERSION = '0.12.0';
+const VERSION = '0.13.0';
 
 // --- Supabase ---
 const SUPABASE_URL = 'https://mjnfqagwuewhgwbtrdgs.supabase.co';
@@ -350,6 +352,131 @@ async function pull(skillArg: string): Promise<void> {
   console.log(`${DIM}   → ${join(skillsDir, name)}${RESET}`);
 }
 
+// --- Agent types ---
+interface AgentRow {
+  name: string;
+  namespace: string;
+  version: string;
+  content_hash: string;
+  storage_path: string;
+  config: Record<string, unknown> | null;
+}
+
+// --- Agent pull ---
+async function agentPull(agentArg: string): Promise<void> {
+  const parsed = parseSkillArg(agentArg); // Same namespace/name[@version] format
+  if (!parsed) usage();
+  const { namespace, name, version } = parsed;
+  const fullName = `${namespace}/${name}`;
+
+  console.log(`\n${BRAND} ${TEAL}↓ Pulling agent ${fullName}${version ? `@${version}` : ''}...${RESET}`);
+
+  const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+
+  // Query for the agent
+  let agent: AgentRow;
+
+  if (version !== null) {
+    const { data, error } = await supabase
+      .from('agents')
+      .select('name, namespace, version, content_hash, storage_path, config')
+      .eq('namespace', namespace)
+      .eq('name', name)
+      .eq('version', version)
+      .single<AgentRow>();
+
+    if (error || !data) {
+      fail(`Agent not found: ${fullName}@${version}`);
+    }
+    agent = data;
+  } else {
+    const { data, error } = await supabase
+      .from('agents')
+      .select('name, namespace, version, content_hash, storage_path, config')
+      .eq('namespace', namespace)
+      .eq('name', name);
+
+    if (error || !data || data.length === 0) {
+      fail(`Agent not found: ${fullName}`);
+    }
+    agent = (data as AgentRow[]).sort((a, b) => compareSemver(a.version, b.version)).at(-1)!;
+  }
+
+  // Download from storage
+  const { data: blob, error: downloadError } = await supabase
+    .storage
+    .from('agents')
+    .download(agent.storage_path);
+
+  if (downloadError || !blob) {
+    fail('Download failed', downloadError?.message ?? 'Unknown storage error');
+  }
+
+  const content = await blob.text();
+
+  // Verify content hash
+  const verifySpinner = spinner('Verifying...');
+  const hash = createHash('sha256').update(content).digest('hex');
+  verifySpinner.stop();
+
+  console.log(`${DIM}   content hash: ${hash}${RESET}`);
+
+  if (hash !== agent.content_hash) {
+    console.log(`${RED}   expected: ${agent.content_hash}${RESET}`);
+    fail('Verification failed', `Downloaded file does not match expected hash for ${fullName}`);
+  }
+
+  // Warn about hooks/mcpServers if present
+  const config = agent.config;
+  if (config?.hooks) {
+    console.log(`\n${YELLOW}${BOLD} ⚠ This agent defines hooks:${RESET}`);
+    console.log(`${DIM}${JSON.stringify(config.hooks, null, 2)}${RESET}\n`);
+  }
+  if (config?.mcpServers) {
+    console.log(`\n${YELLOW}${BOLD} ⚠ This agent defines MCP servers:${RESET}`);
+    console.log(`${DIM}${JSON.stringify(config.mcpServers, null, 2)}${RESET}\n`);
+  }
+
+  // Ensure .claude/agents/ directory exists
+  const agentsDir = join(process.cwd(), '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+
+  // Write agent file
+  const targetPath = join(agentsDir, `${name}.md`);
+  writeFileSync(targetPath, content);
+
+  console.log(`${BOLD}${GREEN} ✓ Agent verified${RESET}`);
+  console.log(`${DIM}   ${fullName} v${agent.version}${RESET}`);
+  console.log(`${DIM}   → ${targetPath}${RESET}`);
+}
+
+// --- Agent subcommand router ---
+async function handleAgent(agentArgs: string[]): Promise<void> {
+  const agentSub = agentArgs[0];
+
+  if (!agentSub || agentSub === '--help' || agentSub === '-h') {
+    agentUsage(agentSub ? 0 : 1);
+  }
+
+  if (agentSub === 'push') {
+    const pushArgs = agentArgs.slice(1);
+    const isPrivate = pushArgs.includes('--private');
+    const pushPath = pushArgs.find(a => !a.startsWith('--'));
+    await agentPush(pushPath, { private: isPrivate });
+  } else if (agentSub === 'pull' || agentSub === 'install' || agentSub === 'i') {
+    const target = agentArgs[1];
+    if (!target) {
+      fail('Missing agent name', 'Usage: oathbound agent pull <namespace/name[@version]>');
+    }
+    await agentPull(target);
+  } else if (agentSub === 'search' || agentSub === 'list' || agentSub === 'ls') {
+    const searchOpts = parseAgentSearchArgs(agentArgs.slice(1));
+    await agentSearch(searchOpts);
+  } else {
+    agentUsage();
+  }
+}
+
 // --- Entry ---
 if (!import.meta.main) {
   // Module imported for testing — skip CLI entry
@@ -417,6 +544,11 @@ if (subcommand === 'init') {
     const msg = err instanceof Error ? err.message : 'Unknown error';
     fail('Search failed', msg);
   });
+} else if (subcommand === 'agent') {
+  handleAgent(args.slice(1)).catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    fail('Agent command failed', msg);
+  });
 } else {
   const PULL_ALIASES = new Set(['pull', 'i', 'install']);
   const skillArg = args[1];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oathbound",
-  "version": "0.12.0",
-  "description": "Install verified Claude Code skills from the Oath Bound registry",
+  "version": "0.13.0",
+  "description": "Install verified Claude Code skills and agents from the Oath Bound registry",
   "license": "BUSL-1.1",
   "author": "Josh Anderson",
   "homepage": "https://oathbound.ai",
@@ -32,6 +32,8 @@
     "auth.ts",
     "push.ts",
     "search.ts",
+    "agent-push.ts",
+    "agent-search.ts",
     "semver.ts",
     "bin/cli.cjs",
     "install.cjs"

package/ui.ts

@@ -18,7 +18,7 @@ export const BRAND = brand();
 
 export function usage(exitCode = 1): never {
   console.log(`
-${BOLD}oathbound${RESET} — install, verify, and publish skills
+${BOLD}oathbound${RESET} — install, verify, and publish skills & agents
 
 ${DIM}Usage:${RESET}
   oathbound init                ${DIM}Setup wizard — configure project${RESET}
@@ -33,6 +33,12 @@ ${DIM}Usage:${RESET}
   oathbound verify              ${DIM}SessionStart hook — verify all skills${RESET}
   oathbound verify --check      ${DIM}PreToolUse hook — check skill integrity${RESET}
 
+${DIM}Agents:${RESET}
+  oathbound agent push [path] [--private]  ${DIM}Publish an agent .md file${RESET}
+  oathbound agent pull <namespace/name[@version]>
+  oathbound agent search [query]           ${DIM}Search agents in the registry${RESET}
+  oathbound agent list                     ${DIM}List all public agents${RESET}
+
 ${DIM}Options:${RESET}
   --help, -h      Show this help message
   --version, -v   Show version
@@ -40,6 +46,22 @@ ${DIM}Options:${RESET}
   process.exit(exitCode);
 }
 
+export function agentUsage(exitCode = 1): never {
+  console.log(`
+${BOLD}oathbound agent${RESET} — manage Claude Code agents
+
+${DIM}Usage:${RESET}
+  oathbound agent push [path] [--private]  ${DIM}Publish an agent .md file to the registry${RESET}
+  oathbound agent pull <namespace/name[@version]>  ${DIM}Download agent to .claude/agents/${RESET}
+  oathbound agent search [query]           ${DIM}Search agents in the registry${RESET}
+  oathbound agent list                     ${DIM}List all public agents${RESET}
+
+${DIM}Options:${RESET}
+  --help, -h      Show this help message
+`);
+  process.exit(exitCode);
+}
+
 export function fail(message: string, detail?: string): never {
   console.log(`\n${BOLD}${RED} ✗ ${message}${RESET}`);
   if (detail) {