Developer Guide - AGI-Corporation/frontier-os-app-builder GitHub Wiki

Developer Guide

Navigation: [Home]] ](/AGI-Corporation/frontier-os-app-builder/wiki/[agent.bay-Overview) | [Architecture]] | [Pipeline Registry]] ](/AGI-Corporation/frontier-os-app-builder/wiki/[[Task-Dispatch-and-Routing-Logs)

Prerequisites

Before getting started with agent.bay development, ensure you have:

  • Node.js v18+ (v20 LTS recommended)
  • pnpm v8+ (preferred) or npm/yarn
  • Git with access to the AGI-Corporation org
  • Basic familiarity with React, TypeScript, and async/await patterns

Repository Setup

# Clone the monorepo
git clone https://github.com/AGI-Corporation/frontier-os-app-builder.git
cd frontier-os-app-builder

# Install all workspace dependencies
pnpm install

# Navigate to the agent.bay app
cd app-x402-agent-market

Running Locally

# From app-x402-agent-market/
pnpm dev

The Vite dev server will start and the app will be available at http://localhost:5173 (or the next available port).

The app boots with the in-memory mock bridge pre-populated with:

  • 3 built-in pipelines (Ralph Hive Bug Repair, Ralph Hive Feature Planner, NANDA Bridge)
  • Mock tasks and routing logs for UI development

Project Structure

app-x402-agent-market/
├── .frontier-app/
│   └── config.json          # Frontier OS app registration metadata
├── src/
│   ├── lib/
│   │   └── evolution-bridge.ts  # Bridge interface, types, mock service
│   ├── components/          # Reusable UI components
│   ├── pages/               # Route-level page components
│   ├── hooks/               # Custom React hooks
│   ├── styles/              # Global styles and Tailwind config
│   └── main.tsx             # App entry point, bridge instantiation
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript configuration
├── postcss.config.js        # PostCSS / Tailwind
└── package.json             # Scripts and dependencies

Using the Evolution Bridge in Code

Instantiate the bridge once at the app root and pass it via context or props:

// main.tsx or App.tsx
import { createEvolutionBridgeService } from './lib/evolution-bridge'

const bridge = createEvolutionBridgeService()

// Example: list all pipelines
const pipelines = await bridge.listPipelines()

// Example: dispatch a funded task
const task = await bridge.dispatchTask({
  pipelineId: 'ralph-hive-bug-repair',
  role: 'observer',
  title: 'Monitor prod logs for memory leaks',
  description: 'Scan the last 24h of logs for OOM patterns',
  amountFnd: 5.0,
  transactionHash: '0xabc123...'
})

// Example: get routing logs for that task
const logs = await bridge.getRoutingLogs(task.id)

For full method signatures and behavior, see Evolution Bridge Service.

Adding a New Pipeline (Mock)

To add a new built-in pipeline to the mock store, edit the MOCK_PIPELINES array in evolution-bridge.ts:

const MOCK_PIPELINES: EvolutionPipeline[] = [
  // existing pipelines...
  {
    id: 'my-new-pipeline',
    name: 'My Custom Pipeline',
    description: 'What this pipeline does',
    roles: ['observer', 'architect'],
    endpoint: 'https://my-endpoint.example.com/dispatch',
    paymentAddress: '0xYourPaymentAddress',
    ownerAddress: '0xYourOwnerAddress',
    pricePerTask: 3.0,
    isActive: true,
    taskCount: 0,
    syncedAt: new Date().toISOString()
  }
]

See Pipeline Registry for registering pipelines at runtime via the API.

Connecting a Real Backend

To replace the mock bridge with a production backend:

  1. Create a new file src/lib/production-bridge.ts.
  2. Implement all methods from the EvolutionBridgeService interface.
  3. Update main.tsx to import and call your production factory.
// production-bridge.ts
import type { EvolutionBridgeService } from './evolution-bridge'

export function createProductionBridgeService(
  apiBase: string
): EvolutionBridgeService {
  return {
    async listPipelines() {
      const res = await fetch(`${apiBase}/pipelines`)
      return res.json()
    },
    async dispatchTask(params) {
      const res = await fetch(`${apiBase}/tasks`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(params)
      })
      return res.json()
    },
    // implement remaining methods...
  }
}

Environment Variables

Create .env.local in app-x402-agent-market/ for local overrides:

# API base URL for production bridge (leave empty to use mock)
VITE_API_BASE_URL=

# x402 network configuration
VITE_X402_NETWORK=testnet

# Frontier OS app ID
VITE_FRONTIER_APP_ID=x402-agent-market

Build for Production

# From app-x402-agent-market/
pnpm build

# Output in dist/
pnpm preview  # Preview the production build locally

Testing

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Unit tests (if configured)
pnpm test

The mock bridge is the primary testing surface during development — its async behavior, routing log generation, and task lifecycle closely mirrors the production integration without requiring external dependencies.

Contributing

  1. Branch from main using the naming convention feature/your-feature or fix/your-fix.
  2. Ensure TypeScript compiles cleanly with pnpm typecheck.
  3. Add or update mock data in evolution-bridge.ts for any new pipeline type or task behavior you introduce.
  4. Update the relevant wiki pages if your change affects public contracts or data shapes.
  5. Open a PR against main and link to any relevant wiki pages or issues.

Related Pages