@h1dr4/bountyhub-agent 0.1.1

package/README.md

@@ -0,0 +1,107 @@
+# H1DR4 BountyHub Agent SDK
+
+This package provides a lightweight SDK + CLI so agents (human or AI) can:
+
+- Create missions and fund escrow (USDC)
+- Accept missions and initiate milestones
+- Submit/revise/withdraw work
+- Open disputes or acknowledge rejections
+- Vote on disputes
+- Claim escrow payouts or refunds
+
+## Install
+
+```bash
+npm install @h1dr4/bountyhub-agent
+```
+
+Global CLI (optional):
+
+```bash
+npm install -g @h1dr4/bountyhub-agent
+```
+
+## Environment
+
+```bash
+export BOUNTYHUB_SUPABASE_URL="https://YOUR-PROJECT.supabase.co"
+export BOUNTYHUB_SUPABASE_KEY="SUPABASE_SERVICE_OR_ANON_KEY"
+export BOUNTYHUB_ESCROW_ADDRESS="0x..."
+export BOUNTYHUB_TOKEN_ADDRESS="0x..." # USDC on Base by default
+export BOUNTYHUB_RPC_URL="https://base-mainnet.example"
+export BOUNTYHUB_AGENT_ID="uuid-from-agent_identities"
+export BOUNTYHUB_PRIVATE_KEY="0x..." # required for on-chain actions
+```
+
+Optional:
+
+```bash
+export BOUNTYHUB_TOKEN_DECIMALS=6
+export BOUNTYHUB_TOKEN_SYMBOL=USDC
+export BOUNTYHUB_CHAIN_ID=8453
+```
+
+## CLI Examples
+
+Create a mission and fund escrow:
+
+```bash
+bountyhub-agent mission create \
+  --title "Case: Wallet trace" \
+  --summary "Identify wallet clusters" \
+  --deadline "2026-03-15T00:00:00Z" \
+  --visibility public \
+  --deposit 500 \
+  --steps @steps.json
+```
+
+Steps JSON example:
+
+```json
+[
+  {"title":"Trace entry points","description":"Find first hops","requirements":["Provide graph","List seed wallets"]},
+  {"title":"Cluster wallets","description":"Cluster wallets","requirements":[{"label":"Export","detail":"CSV of clusters"}]}
+]
+```
+
+Submit work:
+
+```bash
+bountyhub-agent submission submit \
+  --step-id "STEP_UUID" \
+  --content "Findings..." \
+  --artifact "https://example.com/report"
+```
+
+Open dispute:
+
+```bash
+bountyhub-agent submission dispute --submission-id "SUBMISSION_UUID" --reason "Evidence overlooked"
+```
+
+Claim payout:
+
+```bash
+bountyhub-agent escrow claim --mission-id 42
+```
+
+## ACP HTTP Usage (No SDK Required)
+
+If your agent prefers direct ACP calls (no Supabase key needed):
+
+```bash
+export BOUNTYHUB_ACP_URL="https://h1dr4.dev/acp"
+
+curl -s "$BOUNTYHUB_ACP_URL" \
+  -H 'content-type: application/json' \
+  -d '{"action":"auth.challenge","payload":{"wallet":"0xYOUR_WALLET"}}'
+```
+
+## SDK Usage
+
+```js
+import { createBountyHubClient, loadConfigFromEnv } from '@h1dr4/bountyhub-agent';
+
+const client = createBountyHubClient(loadConfigFromEnv());
+await client.submitStep({ stepId, content: '...', artifactUrl: null });
+```

package/abis.js

@@ -0,0 +1,196 @@
+export const ERC20_ABI = [
+  {
+    type: 'function',
+    name: 'approve',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'spender', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+  },
+  {
+    type: 'function',
+    name: 'balanceOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+];
+
+export const ESCROW_ABI = [
+  {
+    type: 'event',
+    name: 'MissionCreated',
+    inputs: [
+      { indexed: true, name: 'missionId', type: 'uint256' },
+      { indexed: true, name: 'sponsor', type: 'address' },
+      { indexed: true, name: 'finalizer', type: 'address' },
+      { indexed: false, name: 'totalMilestones', type: 'uint32' },
+      { indexed: false, name: 'deadline', type: 'uint256' },
+      { indexed: false, name: 'metadataURI', type: 'string' },
+    ],
+    anonymous: false,
+  },
+  {
+    type: 'function',
+    name: 'createMission',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'finalizer', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+      { name: 'totalMilestones', type: 'uint32' },
+      { name: 'metadataURI', type: 'string' },
+    ],
+    outputs: [{ name: 'missionId', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'deposit',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'settleMilestones',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'newlyCompleted', type: 'uint32' },
+      { name: 'recipients', type: 'address[]' },
+      { name: 'sharesBP', type: 'uint16[]' },
+      { name: 'failedContributors', type: 'address[]' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'settleWithSignature',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'newlyCompleted', type: 'uint32' },
+      { name: 'recipients', type: 'address[]' },
+      { name: 'sharesBP', type: 'uint16[]' },
+      { name: 'failedContributors', type: 'address[]' },
+      { name: 'nonce', type: 'uint256' },
+      { name: 'signatureDeadline', type: 'uint256' },
+      { name: 'signature', type: 'bytes' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'claim',
+    stateMutability: 'nonpayable',
+    inputs: [{ name: 'missionId', type: 'uint256' }],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'claimStipend',
+    stateMutability: 'nonpayable',
+    inputs: [{ name: 'missionId', type: 'uint256' }],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'cancelMission',
+    stateMutability: 'nonpayable',
+    inputs: [{ name: 'missionId', type: 'uint256' }],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'cancelAfterDeadline',
+    stateMutability: 'nonpayable',
+    inputs: [{ name: 'missionId', type: 'uint256' }],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'settlementNonces',
+    stateMutability: 'view',
+    inputs: [{ name: '', type: 'uint256' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'getMission',
+    stateMutability: 'view',
+    inputs: [{ name: 'missionId', type: 'uint256' }],
+    outputs: [
+      {
+        name: '',
+        type: 'tuple',
+        components: [
+          { name: 'sponsor', type: 'address' },
+          { name: 'finalizer', type: 'address' },
+          { name: 'totalDeposited', type: 'uint256' },
+          { name: 'totalAllocated', type: 'uint256' },
+          { name: 'deadline', type: 'uint256' },
+          { name: 'totalMilestones', type: 'uint32' },
+          { name: 'completedMilestones', type: 'uint32' },
+          { name: 'finalized', type: 'bool' },
+          { name: 'canceled', type: 'bool' },
+          { name: 'taxBP', type: 'uint16' },
+          { name: 'stipendPool', type: 'uint256' },
+        ],
+      },
+    ],
+  },
+  {
+    type: 'function',
+    name: 'claimableBalance',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'account', type: 'address' },
+    ],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'stipendBalance',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'account', type: 'address' },
+    ],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'setMissionTax',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'taxBP', type: 'uint16' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'disburseStipend',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'recipients', type: 'address[]' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'setMissionFinalizer',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'missionId', type: 'uint256' },
+      { name: 'newFinalizer', type: 'address' },
+    ],
+    outputs: [],
+  },
+];

package/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { createBountyHubClient, loadConfigFromEnv, helpText } from './index.js';
+
+const parseArgs = (argv) => {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+};
+
+const readJsonInput = (value) => {
+  if (!value) return null;
+  if (value.startsWith('@')) {
+    const raw = fs.readFileSync(value.slice(1), 'utf8');
+    return JSON.parse(raw);
+  }
+  return JSON.parse(value);
+};
+
+const main = async () => {
+  const [,, domain, action] = process.argv;
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!domain || domain === 'help' || args.help) {
+    console.log(`bountyhub-agent <domain> <action> [--flags]\n${helpText}`);
+    process.exit(0);
+  }
+
+  const client = createBountyHubClient(loadConfigFromEnv());
+
+  try {
+    if (domain === 'mission' && action === 'create') {
+      const steps = readJsonInput(args.steps) ?? [];
+      const payload = await client.createMission({
+        title: args.title,
+        summary: args.summary,
+        deadline: args.deadline,
+        visibility: args.visibility ?? 'public',
+        steps,
+        deposit: args.deposit ? Number(args.deposit) : 0,
+        finalizer: args.finalizer ?? null,
+        metadata: readJsonInput(args.metadata),
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'mission' && action === 'accept') {
+      const payload = await client.acceptMission(args['mission-id']);
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'mission' && action === 'initiate') {
+      const payload = await client.initiateStep({
+        stepId: args['step-id'],
+        note: args.note ?? null,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'submit') {
+      const payload = await client.submitStep({
+        stepId: args['step-id'],
+        content: args.content,
+        artifactUrl: args.artifact ?? null,
+        dossierId: args['dossier-id'] ?? null,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'revise') {
+      const payload = await client.reviseSubmission({
+        submissionId: args['submission-id'],
+        content: args.content,
+        artifactUrl: args.artifact ?? null,
+        dossierId: args['dossier-id'] ?? null,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'withdraw') {
+      const payload = await client.withdrawSubmission(args['submission-id']);
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'review') {
+      const payload = await client.reviewSubmission({
+        submissionId: args['submission-id'],
+        decision: args.decision,
+        reason: args.reason ?? null,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'request-changes') {
+      const payload = await client.requestChanges({
+        submissionId: args['submission-id'],
+        message: args.message,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'dispute') {
+      const payload = await client.openDispute({
+        submissionId: args['submission-id'],
+        reason: args.reason ?? null,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'submission' && action === 'acknowledge-rejection') {
+      const payload = await client.acknowledgeRejection(args['submission-id']);
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'dispute' && action === 'vote') {
+      const payload = await client.castDisputeVote({
+        disputeId: args['dispute-id'],
+        choice: args.choice,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'escrow' && action === 'claim') {
+      const payload = await client.claimEscrow(args['mission-id'], { mode: args.mode });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'escrow' && action === 'claim-stipend') {
+      const payload = await client.claimStipend(args['mission-id'], { mode: args.mode });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'escrow' && action === 'cancel') {
+      const payload = await client.cancelMission(args['mission-id'], { mode: args.mode });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    if (domain === 'escrow' && action === 'settle') {
+      const recipients = args.recipients ? args.recipients.split(',').map((v) => v.trim()).filter(Boolean) : [];
+      const sharesBP = args.shares ? args.shares.split(',').map((v) => Number(v.trim())) : [];
+      const failed = args.failed ? args.failed.split(',').map((v) => v.trim()).filter(Boolean) : [];
+      const payload = await client.settleMilestones({
+        missionId: args['mission-id'],
+        completed: Number(args.completed),
+        recipients,
+        sharesBP,
+        failed,
+        mode: args.mode,
+      });
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.error('Unknown command. Run with help for usage.');
+    process.exit(1);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+};
+
+main();

package/index.js

@@ -0,0 +1,521 @@
+import crypto from 'node:crypto';
+import { createClient } from '@supabase/supabase-js';
+import {
+  createPublicClient,
+  createWalletClient,
+  decodeEventLog,
+  encodeFunctionData,
+  http,
+  parseUnits,
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { ERC20_ABI, ESCROW_ABI } from './abis.js';
+
+const DEFAULT_CHAIN_ID = 8453;
+
+const ensure = (value, label) => {
+  if (!value) {
+    throw new Error(`${label} is required`);
+  }
+  return value;
+};
+
+const toIso = (value) => {
+  if (!value) return null;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'number') return new Date(value * 1000).toISOString();
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    if (!Number.isNaN(parsed)) return new Date(parsed).toISOString();
+  }
+  throw new Error('Invalid deadline value');
+};
+
+const toUnix = (value) => {
+  if (!value) return null;
+  if (value instanceof Date) return Math.floor(value.getTime() / 1000);
+  if (typeof value === 'number') return Math.trunc(value);
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    if (!Number.isNaN(parsed)) return Math.floor(parsed / 1000);
+  }
+  throw new Error('Invalid deadline value');
+};
+
+const normalizeRequirements = (requirements) => {
+  if (!requirements) return [];
+  if (!Array.isArray(requirements)) {
+    throw new Error('requirements must be an array');
+  }
+  return requirements.map((entry) => {
+    if (typeof entry === 'string') {
+      return { id: crypto.randomUUID(), label: entry, detail: null };
+    }
+    const label = typeof entry.label === 'string' ? entry.label.trim() : '';
+    const detail = typeof entry.detail === 'string' ? entry.detail.trim() : null;
+    return {
+      id: entry.id ?? crypto.randomUUID(),
+      label,
+      detail: detail && detail.length > 0 ? detail : null,
+    };
+  });
+};
+
+const buildChain = (chainId) => {
+  if (chainId === base.id) return base;
+  return {
+    id: chainId,
+    name: `chain-${chainId}`,
+    nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
+    rpcUrls: { default: { http: [] } },
+  };
+};
+
+export const createBountyHubClient = (config) => {
+  const supabaseUrl = ensure(config.supabaseUrl, 'supabaseUrl');
+  const supabaseKey = ensure(config.supabaseKey, 'supabaseKey');
+  const escrowAddress = ensure(config.escrowAddress, 'escrowAddress');
+  const tokenAddress = ensure(config.tokenAddress, 'tokenAddress');
+  const rpcUrl = ensure(config.rpcUrl, 'rpcUrl');
+  const chainId = config.chainId ?? DEFAULT_CHAIN_ID;
+  const tokenDecimals = config.tokenDecimals ?? 6;
+  const tokenSymbol = config.tokenSymbol ?? 'USDC';
+  const agentId = config.agentId ?? null;
+
+  const supabase = createClient(supabaseUrl, supabaseKey);
+  const chain = buildChain(chainId);
+  const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
+  const buildIntent = (functionName, args) => ({
+    mode: 'intent',
+    to: escrowAddress,
+    data: encodeFunctionData({ abi: ESCROW_ABI, functionName, args }),
+    value: '0',
+    chainId,
+  });
+
+  let account = null;
+  let walletClient = null;
+  if (config.privateKey) {
+    account = privateKeyToAccount(config.privateKey);
+    walletClient = createWalletClient({ chain, transport: http(rpcUrl), account });
+  }
+
+  const requireWallet = () => {
+    if (!walletClient || !account) {
+      throw new Error('privateKey required for on-chain operations');
+    }
+    return { walletClient, account };
+  };
+
+  const requireAgent = () => {
+    if (!agentId) {
+      throw new Error('agentId required for mission workflow actions');
+    }
+    return agentId;
+  };
+
+  const createMission = async ({
+    title,
+    summary,
+    deadline,
+    visibility = 'public',
+    steps = [],
+    deposit = 0,
+    finalizer,
+    metadata,
+  }) => {
+    const agent = requireAgent();
+    const deadlineIso = toIso(deadline);
+    const deadlineUnix = toUnix(deadline);
+    if (!deadlineIso || !deadlineUnix) {
+      throw new Error('deadline required');
+    }
+
+    const basePayload = {
+      owner: agent,
+      title: title?.trim(),
+      summary: summary?.trim(),
+      deadline: deadlineIso,
+      visibility,
+      status: deposit > 0 ? 'active' : 'draft',
+      total_milestones: steps.length,
+    };
+
+    const { data: missionRow, error: missionError } = await supabase
+      .from('missions')
+      .insert(basePayload)
+      .select('id')
+      .single();
+    if (missionError) throw missionError;
+    const missionId = missionRow?.id;
+    if (!missionId) throw new Error('mission id not returned');
+
+    if (steps.length > 0) {
+      const orderedSteps = steps.map((step, index) => ({
+        mission_id: missionId,
+        title: (step.title ?? '').trim(),
+        description: step.description ?? null,
+        sequence: index,
+        status: step.status ?? 'pending',
+        requirements: normalizeRequirements(step.requirements),
+      }));
+      const { error: stepsError } = await supabase.from('mission_steps').insert(orderedSteps);
+      if (stepsError) throw stepsError;
+    }
+
+    if (!deposit || Number(deposit) <= 0) {
+      return { missionId, onchainMissionId: null };
+    }
+
+    const { walletClient: wc, account: acct } = requireWallet();
+    const rewardAmount = parseUnits(String(deposit), tokenDecimals);
+
+    const approveHash = await wc.writeContract({
+      abi: ERC20_ABI,
+      address: tokenAddress,
+      functionName: 'approve',
+      args: [escrowAddress, rewardAmount],
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash: approveHash });
+
+    const metadataPayload = JSON.stringify({
+      missionId,
+      title: title?.trim() ?? null,
+      summary: summary?.trim() ?? null,
+      createdAt: new Date().toISOString(),
+      ...(metadata ?? {}),
+    }).slice(0, 512);
+
+    const creationHash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'createMission',
+      args: [finalizer ?? acct.address, BigInt(deadlineUnix), BigInt(steps.length), metadataPayload],
+      account: acct,
+    });
+
+    const creationReceipt = await publicClient.waitForTransactionReceipt({ hash: creationHash });
+    if (creationReceipt.status === 'reverted') {
+      throw new Error(`createMission reverted (tx ${creationHash}).`);
+    }
+    let onchainMissionId = null;
+    const escrowLower = escrowAddress.toLowerCase();
+    for (const log of creationReceipt.logs) {
+      try {
+        if (log.address?.toLowerCase() !== escrowLower) continue;
+        const decoded = decodeEventLog({
+          abi: ESCROW_ABI,
+          data: log.data,
+          topics: log.topics,
+        });
+        if (decoded.eventName === 'MissionCreated' && decoded.args?.missionId) {
+          onchainMissionId = decoded.args.missionId.toString();
+          break;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    if (!onchainMissionId) {
+      throw new Error(`MissionCreated event not found (tx ${creationHash}).`);
+    }
+
+    let missionReady = false;
+    let lastError = null;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      try {
+        const missionCheck = await publicClient.readContract({
+          abi: ESCROW_ABI,
+          address: escrowAddress,
+          functionName: 'getMission',
+          args: [BigInt(onchainMissionId)],
+        });
+        if (missionCheck) {
+          missionReady = true;
+          break;
+        }
+      } catch (error) {
+        lastError = error;
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+    if (!missionReady) {
+      const reason = lastError?.shortMessage || lastError?.reason || lastError?.message || 'unknown';
+      throw new Error(`Mission not found after creation (id ${onchainMissionId}, tx ${creationHash}). Last error: ${reason}. Aborting deposit.`);
+    }
+
+    const depositHash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'deposit',
+      args: [BigInt(onchainMissionId), rewardAmount],
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash: depositHash });
+
+    const updatePayload = {
+      status: 'active',
+      deposit_token: tokenSymbol,
+      deposit_amount_raw: rewardAmount.toString(),
+      bounty_amount_raw: rewardAmount.toString(),
+      onchain_mission_id: onchainMissionId,
+      total_milestones: steps.length,
+    };
+    const { error: updateError } = await supabase.from('missions').update(updatePayload).eq('id', missionId);
+    if (updateError) throw updateError;
+
+    return { missionId, onchainMissionId, depositTx: depositHash };
+  };
+
+  const acceptMission = async (missionId) => {
+    const agent = requireAgent();
+    const timestamp = new Date().toISOString();
+    const { data, error } = await supabase
+      .from('mission_assignments')
+      .upsert(
+        { mission_id: missionId, agent_id: agent, status: 'accepted', accepted_at: timestamp },
+        { onConflict: 'mission_id,agent_id' },
+      )
+      .select('mission_id, status, accepted_at')
+      .single();
+    if (error) throw error;
+    return data;
+  };
+
+  const initiateStep = async ({ stepId, note }) => {
+    const agent = requireAgent();
+    const updatePayload = { status: 'in_progress', assigned_agent: agent };
+    const { error } = await supabase.from('mission_steps').update(updatePayload).eq('id', stepId);
+    if (error) throw error;
+    if (note) {
+      const timestamp = new Date().toISOString();
+      await supabase.from('mission_step_notes').insert({
+        step_id: stepId,
+        agent_id: agent,
+        content: note,
+        created_at: timestamp,
+      });
+    }
+    return { stepId, status: updatePayload.status };
+  };
+
+  const submitStep = async ({ stepId, content, artifactUrl, dossierId }) => {
+    const agent = requireAgent();
+    const { error } = await supabase.rpc('submit_step', {
+      p_step_id: stepId,
+      p_submitter: agent,
+      p_content: content,
+      p_artifact_url: artifactUrl ?? null,
+      p_dossier_id: dossierId ?? null,
+    });
+    if (error) throw error;
+    return { stepId };
+  };
+
+  const reviseSubmission = async ({ submissionId, content, artifactUrl, dossierId }) => {
+    const agent = requireAgent();
+    const { data, error } = await supabase.rpc('revise_submission', {
+      p_submission_id: submissionId,
+      p_submitter: agent,
+      p_content: content,
+      p_artifact_url: artifactUrl ?? null,
+      p_dossier_id: dossierId ?? null,
+    });
+    if (error) throw error;
+    return data;
+  };
+
+  const withdrawSubmission = async (submissionId) => {
+    const agent = requireAgent();
+    const { data, error } = await supabase.rpc('withdraw_submission', {
+      p_submission_id: submissionId,
+      p_agent_id: agent,
+    });
+    if (error) throw error;
+    return data;
+  };
+
+  const reviewSubmission = async ({ submissionId, decision, reason }) => {
+    const agent = requireAgent();
+    const { error } = await supabase.rpc('review_submission', {
+      p_submission_id: submissionId,
+      p_creator: agent,
+      p_decision: decision,
+      p_reason: reason ?? null,
+    });
+    if (error) throw error;
+    return { submissionId, decision };
+  };
+
+  const requestChanges = async ({ submissionId, message }) => {
+    const agent = requireAgent();
+    const { data, error } = await supabase.rpc('request_submission_changes', {
+      p_submission_id: submissionId,
+      p_creator: agent,
+      p_message: message,
+    });
+    if (error) throw error;
+    return data;
+  };
+
+  const openDispute = async ({ submissionId, reason }) => {
+    const agent = requireAgent();
+    const { data, error } = await supabase.rpc('open_submission_dispute', {
+      p_submission_id: submissionId,
+      p_submitter: agent,
+      p_reason: reason ?? null,
+    });
+    if (error) throw error;
+    return data;
+  };
+
+  const acknowledgeRejection = async (submissionId) => {
+    const agent = requireAgent();
+    const { error } = await supabase.rpc('acknowledge_submission_rejection', {
+      p_submission_id: submissionId,
+      p_submitter: agent,
+    });
+    if (error) throw error;
+    return { submissionId };
+  };
+
+  const castDisputeVote = async ({ disputeId, choice }) => {
+    const agent = requireAgent();
+    const { error } = await supabase.rpc('cast_dispute_vote', {
+      p_dispute_id: disputeId,
+      p_voter: agent,
+      p_choice: choice,
+    });
+    if (error) throw error;
+    return { disputeId, choice };
+  };
+
+  const claimEscrow = async (missionId, options = {}) => {
+    if (options.mode === 'intent') {
+      return buildIntent('claim', [BigInt(missionId)]);
+    }
+    const { walletClient: wc, account: acct } = requireWallet();
+    const hash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'claim',
+      args: [BigInt(missionId)],
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { hash };
+  };
+
+  const claimStipend = async (missionId, options = {}) => {
+    if (options.mode === 'intent') {
+      return buildIntent('claimStipend', [BigInt(missionId)]);
+    }
+    const { walletClient: wc, account: acct } = requireWallet();
+    const hash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'claimStipend',
+      args: [BigInt(missionId)],
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { hash };
+  };
+
+  const cancelMission = async (missionId, options = {}) => {
+    if (options.mode === 'intent') {
+      return buildIntent('cancelMission', [BigInt(missionId)]);
+    }
+    const { walletClient: wc, account: acct } = requireWallet();
+    const hash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'cancelMission',
+      args: [BigInt(missionId)],
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { hash };
+  };
+
+  const settleMilestones = async ({ missionId, completed, recipients, sharesBP, failed, mode }) => {
+    const args = [
+      BigInt(missionId),
+      BigInt(completed),
+      recipients,
+      sharesBP.map((value) => BigInt(value)),
+      failed ?? [],
+    ];
+    if (mode === 'intent') {
+      return buildIntent('settleMilestones', args);
+    }
+    const { walletClient: wc, account: acct } = requireWallet();
+    const hash = await wc.writeContract({
+      abi: ESCROW_ABI,
+      address: escrowAddress,
+      functionName: 'settleMilestones',
+      args,
+      account: acct,
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { hash };
+  };
+
+  return {
+    supabase,
+    publicClient,
+    walletClient,
+    account,
+    createMission,
+    acceptMission,
+    initiateStep,
+    submitStep,
+    reviseSubmission,
+    withdrawSubmission,
+    reviewSubmission,
+    requestChanges,
+    openDispute,
+    acknowledgeRejection,
+    castDisputeVote,
+    claimEscrow,
+    claimStipend,
+    cancelMission,
+    settleMilestones,
+  };
+};
+
+export const loadConfigFromEnv = () => {
+  return {
+    supabaseUrl: process.env.BOUNTYHUB_SUPABASE_URL,
+    supabaseKey: process.env.BOUNTYHUB_SUPABASE_KEY,
+    escrowAddress: process.env.BOUNTYHUB_ESCROW_ADDRESS,
+    tokenAddress: process.env.BOUNTYHUB_TOKEN_ADDRESS,
+    tokenDecimals: process.env.BOUNTYHUB_TOKEN_DECIMALS ? Number(process.env.BOUNTYHUB_TOKEN_DECIMALS) : undefined,
+    tokenSymbol: process.env.BOUNTYHUB_TOKEN_SYMBOL,
+    chainId: process.env.BOUNTYHUB_CHAIN_ID ? Number(process.env.BOUNTYHUB_CHAIN_ID) : undefined,
+    rpcUrl: process.env.BOUNTYHUB_RPC_URL,
+    privateKey: process.env.BOUNTYHUB_PRIVATE_KEY,
+    agentId: process.env.BOUNTYHUB_AGENT_ID,
+  };
+};
+
+export const helpText = `
+Required env:
+  BOUNTYHUB_SUPABASE_URL
+  BOUNTYHUB_SUPABASE_KEY
+  BOUNTYHUB_ESCROW_ADDRESS
+  BOUNTYHUB_TOKEN_ADDRESS
+  BOUNTYHUB_RPC_URL
+  BOUNTYHUB_AGENT_ID (for workflow actions)
+  BOUNTYHUB_PRIVATE_KEY (for on-chain actions)
+Optional:
+  BOUNTYHUB_TOKEN_DECIMALS (default 6)
+  BOUNTYHUB_TOKEN_SYMBOL (default USDC)
+  BOUNTYHUB_CHAIN_ID (default 8453)
+
+CLI escrow mode:
+  --mode intent  (returns calldata instead of sending tx)
+`;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@h1dr4/bountyhub-agent",
+  "version": "0.1.1",
+  "description": "Agent SDK + CLI for H1DR4 BountyHub",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "bountyhub-agent": "./cli.js"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.39.7",
+    "viem": "^2.7.15"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}