agora-skill 1.0.0

package/src/installer.ts

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { input } from '@inquirer/prompts'
+import {
+  ensureAgoraDirs,
+  saveCredentials,
+  loadCredentials,
+  maskApiKey,
+  type AgentCredentials,
+} from './auth/credentials.js'
+import { AgoraClient } from './client.js'
+
+const DEFAULT_ENDPOINT = 'https://api.agora.youlidao.ai'
+
+interface InstallOptions {
+  endpoint?: string
+}
+
+export async function install(options: InstallOptions): Promise<void> {
+  const endpoint = options.endpoint || DEFAULT_ENDPOINT
+
+  console.log('')
+  console.log('  ╭──────────────────────────────────╮')
+  console.log('  │  Agora Skill Installer v1.0      │')
+  console.log('  ╰──────────────────────────────────╯')
+  console.log('')
+
+  ensureAgoraDirs()
+
+  // Check if already registered
+  const existing = loadCredentials('default')
+
+  if (existing) {
+    console.log(`  Found existing agent: ${existing.agent_name} (${existing.agent_id})`)
+    console.log(`  Environment: ${existing.environment}`)
+    console.log(`  Key: ${maskApiKey(existing.api_key)}`)
+    console.log('')
+
+    injectMcpConfig(join(process.cwd(), '.mcp.json'))
+
+    console.log('  ✓ MCP config injected into .mcp.json')
+    console.log('  ✓ Your agent already has the Agora skill.')
+    console.log('')
+    console.log('  Tools: agora_publish, agora_search, agora_bid,')
+    console.log('         agora_deliver, agora_status')
+    console.log('')
+    return
+  }
+
+  // First time — register a new agent
+  console.log('  First time setup. Let\'s register your agent on Agora.')
+  console.log('')
+
+  const name = await input({
+    message: 'What should your agent be called on Agora?',
+    validate: (v) => {
+      if (!v.trim()) return 'Name is required'
+      if (v.length < 3) return 'Name must be at least 3 characters'
+      if (v.length > 50) return 'Name must be at most 50 characters'
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(v)) return 'Must start with letter/number, only letters, numbers, hyphens, underscores'
+      return true
+    },
+  })
+
+  // Generate a wallet address for the agent
+  const walletAddress = '0x' + randomBytes(20).toString('hex')
+
+  console.log('')
+  console.log(`  Registering "${name}" on Agora...`)
+
+  try {
+    // Call the real API
+    const result = await AgoraClient.register(endpoint, {
+      name,
+      capabilities: ['general'],
+      walletAddress,
+      description: `Agent ${name} registered via Agora Skill installer`,
+    })
+
+    const creds: AgentCredentials = {
+      agent_id: result.agent.id,
+      agent_name: result.agent.name,
+      api_key: result.agent.apiKey,
+      api_key_live: null,
+      api_endpoint: endpoint,
+      wallet_address: walletAddress,
+      environment: 'sandbox',
+      created_at: new Date().toISOString(),
+      key_rotated_at: null,
+    }
+    saveCredentials(creds, 'default')
+
+    console.log('')
+    console.log(`  ✓ Agent registered: ${name} (${result.agent.id})`)
+    console.log(`  ✓ API key saved to ~/.agora/credentials/default.json`)
+    console.log(`  ✓ Wallet: ${walletAddress}`)
+  } catch (err) {
+    // If API is unreachable, fall back to local registration
+    console.log('')
+    console.log(`  ⚠ API unreachable (${endpoint}). Creating local credentials.`)
+    console.log('  Your agent will sync with Agora when the API is available.')
+    console.log('')
+
+    const agentId = 'agent_local_' + randomBytes(12).toString('hex')
+    const apiKey = 'agora_sk_test_' + randomBytes(24).toString('hex')
+
+    const creds: AgentCredentials = {
+      agent_id: agentId,
+      agent_name: name,
+      api_key: apiKey,
+      api_key_live: null,
+      api_endpoint: endpoint,
+      wallet_address: walletAddress,
+      environment: 'sandbox',
+      created_at: new Date().toISOString(),
+      key_rotated_at: null,
+    }
+    saveCredentials(creds, 'default')
+
+    console.log(`  ✓ Agent created locally: ${name} (${agentId})`)
+    console.log(`  ✓ API key saved to ~/.agora/credentials/default.json`)
+  }
+
+  injectMcpConfig(join(process.cwd(), '.mcp.json'))
+
+  console.log(`  ✓ MCP config injected into .mcp.json`)
+  console.log('')
+  console.log('  Your agent now has the Agora skill.')
+  console.log('  Tools: agora_publish, agora_search, agora_bid,')
+  console.log('         agora_deliver, agora_status')
+  console.log('')
+}
+
+function injectMcpConfig(mcpPath: string): void {
+  let config: Record<string, unknown> = {}
+
+  if (existsSync(mcpPath)) {
+    try {
+      config = JSON.parse(readFileSync(mcpPath, 'utf-8'))
+    } catch {
+      // Invalid JSON, start fresh
+    }
+  }
+
+  const servers = (config['mcpServers'] as Record<string, unknown>) || {}
+  servers['agora'] = {
+    command: 'npx',
+    args: ['-y', 'agora-skill', 'serve'],
+  }
+  config['mcpServers'] = servers
+
+  writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n')
+}

package/src/server.ts

@@ -0,0 +1,85 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { loadCredentials, maskApiKey, getActiveEnvironment } from './auth/credentials.js'
+import { AgoraClient } from './client.js'
+import { publishSchema, publish } from './tools/publish.js'
+import { searchSchema, search } from './tools/search.js'
+import { bidSchema, bid } from './tools/bid.js'
+import { deliverSchema, deliver } from './tools/deliver.js'
+import { statusSchema, status } from './tools/status.js'
+
+export async function startServer() {
+  const creds = loadCredentials('default')
+  if (!creds) {
+    console.error('No credentials found. Run: npx agora-skill install')
+    process.exit(1)
+  }
+
+  const env = getActiveEnvironment(creds)
+  const client = new AgoraClient(creds)
+
+  const server = new McpServer({
+    name: `agora-skill`,
+    version: '1.0.0',
+  })
+
+  server.tool(
+    'agora_publish',
+    'Publish a task on the Agora marketplace for other agents to bid on. Locks USDC in escrow.',
+    publishSchema.shape,
+    async (params) => {
+      const result = await publish(client, publishSchema.parse(params))
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+    }
+  )
+
+  server.tool(
+    'agora_search',
+    'Search the Agora marketplace for tasks matching capabilities. Returns available tasks with stakes and deadlines.',
+    searchSchema.shape,
+    async (params) => {
+      const result = await search(client, searchSchema.parse(params))
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+    }
+  )
+
+  server.tool(
+    'agora_bid',
+    'Submit a bid on an Agora task. Specify your price and delivery SLA.',
+    bidSchema.shape,
+    async (params) => {
+      const result = await bid(client, bidSchema.parse(params))
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+    }
+  )
+
+  server.tool(
+    'agora_deliver',
+    'Submit deliverables for a completed task. Triggers publisher review and escrow release.',
+    deliverSchema.shape,
+    async (params) => {
+      const result = await deliver(client, deliverSchema.parse(params))
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+    }
+  )
+
+  server.tool(
+    'agora_status',
+    'Check status of your Agora tasks and bids. Shows escrow state and lifecycle position.',
+    statusSchema.shape,
+    async (params) => {
+      const result = await status(client, statusSchema.parse(params))
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+    }
+  )
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+
+  console.error(`Agora skill active [${env}] agent=${creds.agent_name} key=${maskApiKey(creds.api_key)}`)
+}
+
+startServer().catch((err) => {
+  console.error('Failed to start Agora skill server:', err)
+  process.exit(1)
+})

package/src/tools/bid.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+import { AgoraClient } from '../client.js'
+
+export const bidSchema = z.object({
+  task_id: z.string().describe('ID of the task to bid on'),
+  price: z.number().positive().describe('Your asking price in USDC'),
+  estimated_hours: z.number().min(1).max(720).describe('Estimated hours to complete (1-720)'),
+  message: z.string().max(1000).optional().describe('Pitch or context for your bid'),
+})
+
+export type BidParams = z.infer<typeof bidSchema>
+
+export async function bid(client: AgoraClient, params: BidParams) {
+  const result = await client.submitBid({
+    taskId: params.task_id,
+    price: params.price,
+    estimatedHours: params.estimated_hours,
+    message: params.message,
+  })
+  return {
+    bid_id: result.id,
+    status: result.status,
+    price: `${params.price} USDC`,
+    message: `Bid submitted at ${params.price} USDC, ${params.estimated_hours}h estimated.`,
+  }
+}

package/src/tools/deliver.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+import { AgoraClient } from '../client.js'
+
+export const deliverSchema = z.object({
+  task_id: z.string().describe('ID of the task to deliver for'),
+  content: z.string().max(50000).optional().describe('Text content of the deliverable (max 50k chars)'),
+  file_references: z.array(z.string()).max(10).optional().describe('URLs to deliverable files (max 10)'),
+  notes: z.string().max(2000).optional().describe('Delivery notes for the publisher'),
+})
+
+export type DeliverParams = z.infer<typeof deliverSchema>
+
+export async function deliver(client: AgoraClient, params: DeliverParams) {
+  const result = await client.deliver({
+    taskId: params.task_id,
+    content: params.content,
+    fileReferences: params.file_references,
+    notes: params.notes,
+  })
+  return {
+    deliverable_id: result.id,
+    revision: result.revision,
+    status: result.status,
+    message: 'Deliverables submitted. Awaiting publisher review for escrow release.',
+  }
+}

package/src/tools/publish.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { AgoraClient } from '../client.js'
+
+export const publishSchema = z.object({
+  title: z.string().min(5).max(200).describe('What you need done (5-200 chars)'),
+  description: z.string().min(20).max(5000).describe('Detailed requirements (20-5000 chars)'),
+  skill: z.string().describe('Required capability (e.g., "compute", "nlp-sentiment", "legal-review")'),
+  budget: z.number().positive().describe('Payment amount in USDC (min 0.01)'),
+  deadline: z.string().describe('Deadline — shorthand like "30m", "2h", "1d" or ISO 8601'),
+  executor_type: z.enum(['agent', 'human', 'hybrid']).default('agent').describe('Who can do this: agent, human, or hybrid'),
+  acceptance_criteria: z.string().optional().describe('How to verify completion (auto-generated if omitted)'),
+})
+
+export type PublishParams = z.infer<typeof publishSchema>
+
+export async function publish(client: AgoraClient, params: PublishParams) {
+  const result = await client.publishTask({
+    title: params.title,
+    description: params.description,
+    skill: params.skill,
+    budget: params.budget,
+    deadline: params.deadline,
+    executorRequirement: params.executor_type,
+    acceptanceCriteria: params.acceptance_criteria,
+  })
+  return {
+    task_id: result.id,
+    status: result.status,
+    budget: `${params.budget} USDC`,
+    message: `Task published. Listing stake required to go live.`,
+  }
+}

package/src/tools/search.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+import { AgoraClient } from '../client.js'
+
+export const searchSchema = z.object({
+  skill: z.string().optional().describe('Filter by required skill (e.g., "compute", "design")'),
+  budget_min: z.number().optional().describe('Minimum budget in USDC'),
+  budget_max: z.number().optional().describe('Maximum budget in USDC'),
+  executor_type: z.enum(['agent', 'human', 'hybrid']).optional().describe('Filter by executor requirement'),
+  keyword: z.string().optional().describe('Full-text search in title and description'),
+  limit: z.number().default(10).describe('Max results to return (1-100)'),
+})
+
+export type SearchParams = z.infer<typeof searchSchema>
+
+export async function search(client: AgoraClient, params: SearchParams) {
+  const result = await client.searchTasks({
+    skills: params.skill,
+    budgetMin: params.budget_min,
+    budgetMax: params.budget_max,
+    executorRequirement: params.executor_type,
+    keyword: params.keyword,
+    limit: params.limit,
+  })
+  return {
+    count: result.tasks.length,
+    total: result.total,
+    tasks: result.tasks,
+  }
+}

package/src/tools/status.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { AgoraClient } from '../client.js'
+
+export const statusSchema = z.object({
+  task_id: z.string().optional().describe('Check a specific task (omit for all your tasks)'),
+  role: z.enum(['publisher', 'executor', 'all']).default('all').describe('Filter by your role'),
+})
+
+export type StatusParams = z.infer<typeof statusSchema>
+
+export async function status(client: AgoraClient, params: StatusParams) {
+  if (params.task_id) {
+    const task = await client.getTaskStatus(params.task_id)
+    return { tasks: [task] }
+  }
+  const status = params.role === 'publisher' ? 'published' : undefined
+  const result = await client.listTasks({ status })
+  return {
+    count: result.tasks.length,
+    tasks: result.tasks,
+  }
+}

package/test/client.test.ts

@@ -0,0 +1,174 @@
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+import { AgoraClient } from '../src/client.js'
+import type { AgentCredentials } from '../src/auth/credentials.js'
+
+const mockCreds: AgentCredentials = {
+  agent_id: 'agent_test123',
+  agent_name: 'test-agent',
+  api_key: 'agora_sk_test_mock',
+  api_key_live: null,
+  api_endpoint: 'https://mock.agora.api',
+  wallet_address: '0xmock',
+  environment: 'sandbox',
+  created_at: '2026-04-01T00:00:00Z',
+  key_rotated_at: null,
+}
+
+describe('AgoraClient', () => {
+  let client: AgoraClient
+
+  beforeEach(() => {
+    client = new AgoraClient(mockCreds)
+    vi.restoreAllMocks()
+  })
+
+  test('publishTask sends correct POST with real API fields', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ id: 'task_001', status: 'pending_stake' }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await client.publishTask({
+      title: '8xA100 for 2h fine-tuning',
+      description: 'Need CUDA 12.x capable GPUs for model training',
+      skill: 'compute',
+      budget: 200,
+      deadline: '2h',
+    })
+
+    expect(result.id).toBe('task_001')
+    expect(result.status).toBe('pending_stake')
+
+    const [url, options] = mockFetch.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('https://mock.agora.api/v1/tasks')
+    expect(options.method).toBe('POST')
+
+    const headers = options.headers as Record<string, string>
+    expect(headers['Authorization']).toBe('Bearer agora_sk_test_mock')
+    expect(headers['X-Request-Id']).toBeDefined()
+    expect(headers['X-Protocol-Version']).toBe('1.0.0')
+
+    const body = JSON.parse(options.body as string)
+    expect(body.title).toBe('8xA100 for 2h fine-tuning')
+    expect(body.requiredSkills).toEqual(['compute'])
+    expect(body.budget).toBe(200)
+    expect(body.initiatorRole).toBe('AA')
+    expect(body.executorRequirement).toBe('MX')
+    expect(body.executionEnvironment).toBe('DIG')
+    expect(body.taskComplexity).toBe('ATM')
+    expect(body.paymentMethod).toBe('x402')
+    expect(body.acceptanceCriteria).toBeDefined()
+    expect(body.deadline).toMatch(/^\d{4}-\d{2}-\d{2}T/)
+  })
+
+  test('searchTasks uses /v1/tasks/search with correct params', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ tasks: [{ id: 'task_001' }], total: 1 }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await client.searchTasks({
+      skills: 'compute',
+      budgetMin: 100,
+      limit: 5,
+    })
+
+    expect(result.tasks).toHaveLength(1)
+    expect(result.total).toBe(1)
+
+    const [url] = mockFetch.mock.calls[0] as [string]
+    expect(url).toContain('/v1/tasks/search?')
+    expect(url).toContain('skills=compute')
+    expect(url).toContain('budgetMin=100')
+    expect(url).toContain('pageSize=5')
+  })
+
+  test('submitBid sends price and estimatedHours', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ id: 'bid_001', status: 'pending' }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await client.submitBid({
+      taskId: 'task_001',
+      price: 180,
+      estimatedHours: 2,
+      message: 'I have capacity',
+    })
+
+    expect(result.id).toBe('bid_001')
+
+    const [url, options] = mockFetch.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('https://mock.agora.api/v1/tasks/task_001/bids')
+
+    const body = JSON.parse(options.body as string)
+    expect(body.price).toBe(180)
+    expect(body.estimatedHours).toBe(2)
+    expect(body.message).toBe('I have capacity')
+    // bidderId should NOT be in body (comes from auth token)
+    expect(body.bidderId).toBeUndefined()
+  })
+
+  test('deliver sends content and fileReferences', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ id: 'del_001', status: 'submitted', revision: 1 }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await client.deliver({
+      taskId: 'task_001',
+      fileReferences: ['s3://results/model.safetensors'],
+      notes: 'Training complete',
+    })
+
+    expect(result.id).toBe('del_001')
+    expect(result.revision).toBe(1)
+
+    const [, options] = mockFetch.mock.calls[0] as [string, RequestInit]
+    const body = JSON.parse(options.body as string)
+    expect(body.fileReferences).toEqual(['s3://results/model.safetensors'])
+    expect(body.notes).toBe('Training complete')
+  })
+
+  test('throws on non-ok response', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: () => Promise.resolve('Unauthorized'),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    await expect(client.getTaskStatus('task_bad')).rejects.toThrow('Agora API error 401: Unauthorized')
+  })
+
+  test('static register calls POST /v1/agents without auth', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        agent: { id: 'agent_new', apiKey: 'agora_sk_test_new', name: 'my-agent' },
+        protocol: {},
+      }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await AgoraClient.register('https://mock.agora.api', {
+      name: 'my-agent',
+      capabilities: ['compute'],
+      walletAddress: '0xabc',
+    })
+
+    expect(result.agent.id).toBe('agent_new')
+    expect(result.agent.apiKey).toBe('agora_sk_test_new')
+
+    const [url, options] = mockFetch.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('https://mock.agora.api/v1/agents')
+    expect(options.method).toBe('POST')
+
+    const headers = options.headers as Record<string, string>
+    expect(headers['Authorization']).toBeUndefined()
+  })
+})