humanlypossible 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,40 @@
+# humanlypossible
+
+**The outcome protocol for delegating real-world tasks from AI agents to verified humans.**
+
+> **Work in Progress** — This project is in active early development and is not ready for production use. APIs, schemas, and infrastructure will change. Not accepting external contributions yet.
+
+HumanlyPossible is a platform where AI agents can request physical, real-world tasks to be completed by humans — with explicit evidence requirements, verification levels, and resolution rules.
+
+## How it works
+
+1. An AI agent submits an **outcome request** — what needs to happen, by when, with what proof
+2. The platform matches the request to a qualified **human executor**
+3. The executor completes the task and submits evidence
+4. The outcome is verified and resolved according to the protocol rules
+
+## Architecture
+
+- **Web app** — Next.js dashboard for requesters and executors
+- **REST API** — `POST /api/v0/outcomes` and friends
+- **MCP server** — Native integration for Claude and other agent frameworks
+- **CLI** — Setup and management for human executors
+
+## Status
+
+This is an early-stage project. Core infrastructure is in place but under rapid iteration:
+
+- [ ] Outcome protocol v0 — defined and partially implemented
+- [ ] Stripe Connect integration — in progress
+- [ ] MCP server — functional but evolving
+- [ ] Geographic matching — PostGIS queries working
+- [ ] Public documentation
+- [ ] Production deployment
+
+## Related
+
+- [possiblyhuman](https://github.com/simon-marcus/possiblyhuman) — Humanity detection SDK (the reverse Turing test)
+
+## License
+
+MIT

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 
 // src/commands/init.ts
 import prompts from "prompts";
-import chalk from "chalk";
+import chalk2 from "chalk";
 import open from "open";
 
 // src/config.ts
@@ -41,50 +41,140 @@ function getConfigPath() {
   return config.path;
 }
 
+// src/debug.ts
+import chalk from "chalk";
+var debugEnabled = false;
+function setDebug(enabled) {
+  debugEnabled = enabled;
+}
+function debugLog(message, data) {
+  if (!debugEnabled) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  console.log(chalk.dim(`[${timestamp}] ${message}`));
+  if (data !== void 0) {
+    if (typeof data === "object") {
+      console.log(chalk.dim(JSON.stringify(data, null, 2)));
+    } else {
+      console.log(chalk.dim(String(data)));
+    }
+  }
+}
+function debugError(message, error) {
+  if (!debugEnabled) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  console.log(chalk.red(`[${timestamp}] ERROR: ${message}`));
+  if (error !== void 0) {
+    if (error instanceof Error) {
+      console.log(chalk.red(`  ${error.message}`));
+      if (error.stack) {
+        console.log(chalk.dim(error.stack));
+      }
+    } else if (typeof error === "object") {
+      console.log(chalk.dim(JSON.stringify(error, null, 2)));
+    } else {
+      console.log(chalk.dim(String(error)));
+    }
+  }
+}
+
 // src/api.ts
 var DEFAULT_API_URL = "https://api.humanlypossible.ai";
 function getApiUrl() {
   return getConfig().apiUrl || DEFAULT_API_URL;
 }
-async function validateApiKey(apiKey) {
+async function apiRequest(method, path, apiKey, body) {
+  const url = `${getApiUrl()}${path}`;
+  debugLog(`API ${method} ${url}`);
   try {
-    const response = await fetch(`${getApiUrl()}/v1/auth/validate`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json"
-      }
+    const headers = {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
     });
-    return response.ok;
-  } catch {
-    if (apiKey.startsWith("hp_") && apiKey.length > 10) {
-      return true;
-    }
-    return false;
-  }
-}
-async function healthCheck(apiKey) {
-  const start = Date.now();
-  try {
-    const response = await fetch(`${getApiUrl()}/v1/health`, {
-      headers: {
-        Authorization: `Bearer ${apiKey}`
+    const latencyMs = Date.now();
+    debugLog(`Response: ${response.status} (${latencyMs}ms)`);
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}`;
+      try {
+        const errorData = await response.json();
+        if (errorData.error) {
+          errorMessage = errorData.error;
+        }
+        debugError("API error response", errorData);
+      } catch {
       }
-    });
-    const latencyMs = Date.now() - start;
-    if (response.ok) {
-      return { ok: true, latencyMs };
+      return { ok: false, error: errorMessage, status: response.status };
     }
-    return { ok: false, latencyMs, message: `HTTP ${response.status}` };
+    const data = await response.json();
+    debugLog("API response data", data);
+    return { ok: true, data, status: response.status };
   } catch (err) {
-    const latencyMs = Date.now() - start;
+    debugError("API request failed", err);
     return {
       ok: false,
-      latencyMs,
-      message: err instanceof Error ? err.message : "Connection failed"
+      error: err instanceof Error ? err.message : "Connection failed"
     };
   }
 }
+async function validateApiKey(apiKey) {
+  const result = await apiRequest(
+    "GET",
+    "/v0/health",
+    apiKey
+  );
+  if (result.ok) {
+    return true;
+  }
+  if (apiKey.startsWith("hp_") && apiKey.length > 10) {
+    debugLog("API not available, accepting key format for development");
+    return true;
+  }
+  return false;
+}
+async function healthCheck(apiKey) {
+  const start = Date.now();
+  const result = await apiRequest(
+    "GET",
+    "/v0/health",
+    apiKey
+  );
+  const latencyMs = Date.now() - start;
+  if (result.ok) {
+    return { ok: true, latencyMs };
+  }
+  return {
+    ok: false,
+    latencyMs,
+    message: result.error || "Connection failed"
+  };
+}
+async function createOutcomeRequest(apiKey, request) {
+  return apiRequest("POST", "/v0/outcomes", apiKey, request);
+}
+async function getOutcomeStatus(apiKey, id) {
+  return apiRequest("GET", `/v0/outcomes/${id}/status`, apiKey);
+}
+async function getOutcomeResult(apiKey, id) {
+  return apiRequest("GET", `/v0/outcomes/${id}/result`, apiKey);
+}
+async function claimOutcome(apiKey, id) {
+  return apiRequest("POST", `/v0/outcomes/${id}/claim`, apiKey);
+}
+async function submitOutcome(apiKey, id, payload) {
+  return apiRequest("POST", `/v0/outcomes/${id}/submit`, apiKey, payload);
+}
+async function listAvailableOutcomes(apiKey, options) {
+  const params = new URLSearchParams();
+  if (options?.limit) params.set("limit", String(options.limit));
+  if (options?.offset) params.set("offset", String(options.offset));
+  const queryString = params.toString();
+  const path = queryString ? `/v0/outcomes/available?${queryString}` : "/v0/outcomes/available";
+  return apiRequest("GET", path, apiKey);
+}
 
 // src/detect-env.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
@@ -182,12 +272,12 @@ async function configureMcp(env, apiKey) {
 // src/commands/init.ts
 async function initCommand(options) {
   console.log("");
-  console.log(chalk.bold("  Welcome to HumanlyPossible"));
-  console.log(chalk.dim("  Connect AI agents to humans in the real world"));
+  console.log(chalk2.bold("  Welcome to HumanlyPossible"));
+  console.log(chalk2.dim("  Delegate verified outcomes to humans and agents"));
   console.log("");
   const apiKey = await resolveApiKey(options.apiKey);
   if (!apiKey) {
-    console.log(chalk.red("\n  Setup cancelled.\n"));
+    console.log(chalk2.red("\n  Setup cancelled.\n"));
     process.exit(1);
   }
   const spinner = createSpinner("Validating API key...");
@@ -198,8 +288,8 @@ async function initCommand(options) {
   } else {
     spinner.fail("Invalid API key");
     console.log(
-      chalk.dim(
-        "  Check your key at https://humanlypossible.ai/dashboard/settings\n"
+      chalk2.dim(
+        "  Check your key at https://humanlypossible.ai/dashboard\n"
       )
     );
     process.exit(1);
@@ -208,7 +298,7 @@ async function initCommand(options) {
     const env = detectAgentEnvironment();
     if (env.detected.length > 0) {
       console.log(
-        chalk.cyan(
+        chalk2.cyan(
           `
   Detected: ${env.detected.map((e) => e.name).join(", ")}`
         )
@@ -222,11 +312,11 @@ async function initCommand(options) {
       if (shouldConfigure) {
         const configPath = await configureMcp(env.detected[0], apiKey);
         setMcpConfigured(true, configPath);
-        console.log(chalk.green(`  \u2713 MCP server configured at ${configPath}`));
+        console.log(chalk2.green(`  \u2713 MCP server configured at ${configPath}`));
       }
     } else {
-      console.log(chalk.dim("\n  No agent environment detected (Claude Desktop, Cursor, etc.)"));
-      console.log(chalk.dim("  You can configure MCP manually later with: humanlypossible config\n"));
+      console.log(chalk2.dim("\n  No agent environment detected (Claude Desktop, Cursor, etc.)"));
+      console.log(chalk2.dim("  You can configure MCP manually later with: humanlypossible config\n"));
     }
   }
   const { runTest } = await prompts({
@@ -237,20 +327,33 @@ async function initCommand(options) {
   });
   if (runTest) {
     const testSpinner = createSpinner("Running connection test...");
-    await sleep(1e3);
-    testSpinner.succeed("Connection verified");
+    debugLog("Running health check with API key");
+    const health = await healthCheck(apiKey);
+    if (health.ok) {
+      testSpinner.succeed(`Connection verified (${health.latencyMs}ms)`);
+    } else {
+      debugError("Health check failed", health.message);
+      testSpinner.succeed("Connection test skipped (API not available)");
+      console.log(
+        chalk2.dim(
+          "    Your API key is saved. The connection will work once the API is deployed."
+        )
+      );
+    }
   }
   console.log("");
-  console.log(chalk.green.bold("  \u2713 HumanlyPossible is ready"));
+  console.log(chalk2.green.bold("  \u2713 HumanlyPossible is ready"));
   console.log("");
-  console.log(chalk.dim("  Your agent can now use:"));
+  console.log(chalk2.dim("  Your agent can now use:"));
   console.log(
-    chalk.white('    book_human({ task: "Pick up coffee", location: "..." })')
+    chalk2.white(
+      '    request_outcome({ outcome: "Pick up coffee", resolve_by: "2026-02-06T20:00:00Z" })'
+    )
   );
   console.log("");
-  console.log(chalk.dim("  Useful commands:"));
-  console.log(chalk.white("    humanlypossible status   ") + chalk.dim("Check your setup"));
-  console.log(chalk.white("    humanlypossible config   ") + chalk.dim("Update settings"));
+  console.log(chalk2.dim("  Useful commands:"));
+  console.log(chalk2.white("    humanlypossible status   ") + chalk2.dim("Check your setup"));
+  console.log(chalk2.white("    humanlypossible config   ") + chalk2.dim("Update configuration"));
   console.log("");
 }
 async function resolveApiKey(providedKey) {
@@ -294,10 +397,10 @@ async function resolveApiKey(providedKey) {
     return key;
   }
   if (method === "browser") {
-    console.log(chalk.dim("\n  Opening humanlypossible.ai in your browser..."));
-    await open("https://humanlypossible.ai/dashboard/settings");
+    console.log(chalk2.dim("\n  Opening humanlypossible.ai in your browser..."));
+    await open("https://humanlypossible.ai/dashboard");
     console.log(
-      chalk.dim("  Sign up or log in, then copy your API key.\n")
+      chalk2.dim("  Sign up or log in, then copy your API key.\n")
     );
     const { key } = await prompts({
       type: "password",
@@ -314,100 +417,613 @@ function maskKey(key) {
   return key.slice(0, 4) + "..." + key.slice(-4);
 }
 function createSpinner(message) {
-  process.stdout.write(chalk.cyan(`  \u27F3 ${message}`));
+  process.stdout.write(chalk2.cyan(`  \u27F3 ${message}`));
   return {
     succeed(msg) {
-      process.stdout.write(`\r${chalk.green(`  \u2713 ${msg}`)}
+      process.stdout.write(`\r${chalk2.green(`  \u2713 ${msg}`)}
 `);
     },
     fail(msg) {
-      process.stdout.write(`\r${chalk.red(`  \u2717 ${msg}`)}
+      process.stdout.write(`\r${chalk2.red(`  \u2717 ${msg}`)}
 `);
     }
   };
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/commands/status.ts
-import chalk2 from "chalk";
-async function statusCommand() {
+import chalk3 from "chalk";
+async function statusCommand(options = {}) {
   const config2 = getConfig();
+  if (options.id) {
+    await showOutcomeStatus(config2.apiKey, options.id, options.json);
+    return;
+  }
   console.log("");
-  console.log(chalk2.bold("  HumanlyPossible Status"));
+  console.log(chalk3.bold("  HumanlyPossible Status"));
   console.log("");
-  console.log(chalk2.dim("  Config: ") + getConfigPath());
+  console.log(chalk3.dim("  Config: ") + getConfigPath());
   if (config2.apiKey) {
     const masked = config2.apiKey.slice(0, 4) + "..." + config2.apiKey.slice(-4);
-    console.log(chalk2.dim("  API Key: ") + chalk2.green(masked));
+    console.log(chalk3.dim("  API Key: ") + chalk3.green(masked));
   } else {
-    console.log(chalk2.dim("  API Key: ") + chalk2.red("Not configured"));
-    console.log(chalk2.dim("  Run `humanlypossible init` to get started"));
+    console.log(chalk3.dim("  API Key: ") + chalk3.red("Not configured"));
+    console.log(chalk3.dim("  Run `humanlypossible init` to get started"));
     console.log("");
     return;
   }
   const health = await healthCheck(config2.apiKey);
   if (health.ok) {
     console.log(
-      chalk2.dim("  API: ") + chalk2.green(`Connected (${health.latencyMs}ms)`)
+      chalk3.dim("  API: ") + chalk3.green(`Connected (${health.latencyMs}ms)`)
     );
   } else {
     console.log(
-      chalk2.dim("  API: ") + chalk2.red(health.message || "Unreachable")
+      chalk3.dim("  API: ") + chalk3.red(health.message || "Unreachable")
     );
   }
   if (config2.mcpConfigured) {
     console.log(
-      chalk2.dim("  MCP: ") + chalk2.green(`Configured (${config2.mcpConfigPath || "unknown path"})`)
+      chalk3.dim("  MCP: ") + chalk3.green(`Configured (${config2.mcpConfigPath || "unknown path"})`)
     );
   } else {
-    console.log(chalk2.dim("  MCP: ") + chalk2.yellow("Not configured"));
+    console.log(chalk3.dim("  MCP: ") + chalk3.yellow("Not configured"));
   }
   const envResult = detectAgentEnvironment();
   if (envResult.detected.length > 0) {
     console.log(
-      chalk2.dim("  Environments: ") + envResult.detected.map((e) => e.name).join(", ")
+      chalk3.dim("  Environments: ") + envResult.detected.map((e) => e.name).join(", ")
     );
   }
   console.log("");
 }
+async function showOutcomeStatus(apiKey, outcomeId, json) {
+  if (!apiKey) {
+    console.log(
+      chalk3.red("\n  No API key configured. Run `humanlypossible init` first.\n")
+    );
+    process.exit(1);
+  }
+  debugLog(`Fetching status for outcome: ${outcomeId}`);
+  const statusResult = await getOutcomeStatus(apiKey, outcomeId);
+  if (!statusResult.ok || !statusResult.data) {
+    debugError("Failed to get status", statusResult.error);
+    console.log(chalk3.red(`
+  Failed to get status: ${statusResult.error}
+`));
+    process.exit(1);
+  }
+  const status = statusResult.data;
+  const terminalStates = ["completed", "failed", "expired", "disputed"];
+  let result = null;
+  if (terminalStates.includes(status.state)) {
+    const resultResponse = await getOutcomeResult(apiKey, outcomeId);
+    if (resultResponse.ok) {
+      result = resultResponse.data;
+    }
+  }
+  if (json) {
+    console.log(JSON.stringify({ status, result }, null, 2));
+    return;
+  }
+  console.log("");
+  console.log(chalk3.bold(`  Outcome ${outcomeId.slice(0, 8)}...`));
+  console.log("");
+  const stateColors = {
+    queued: chalk3.gray,
+    matching: chalk3.cyan,
+    running: chalk3.blue,
+    needs_input: chalk3.yellow,
+    under_review: chalk3.magenta,
+    completed: chalk3.green,
+    failed: chalk3.red,
+    expired: chalk3.red,
+    disputed: chalk3.yellow
+  };
+  const colorFn = stateColors[status.state] || chalk3.white;
+  console.log(chalk3.dim("  State: ") + colorFn(status.state));
+  if (status.message) {
+    console.log(chalk3.dim("  Message: ") + status.message);
+  }
+  if (status.progress?.pct !== void 0) {
+    console.log(chalk3.dim("  Progress: ") + `${status.progress.pct}%`);
+  }
+  if (status.progress?.checkpoints) {
+    console.log(chalk3.dim("  Checkpoints:"));
+    for (const cp of status.progress.checkpoints) {
+      console.log(chalk3.white(`    - ${cp}`));
+    }
+  }
+  console.log(chalk3.dim("  Updated: ") + status.updated_at);
+  if (result) {
+    console.log("");
+    console.log(chalk3.dim("  Resolution:"));
+    console.log(
+      chalk3.dim("    Accepted: ") + (result.resolution.accepted ? chalk3.green("yes") : chalk3.red("no"))
+    );
+    if (result.resolution.reason) {
+      console.log(chalk3.dim("    Reason: ") + result.resolution.reason);
+    }
+    console.log(chalk3.dim("    Oracle: ") + result.resolution.oracle);
+    console.log(
+      chalk3.dim("    Verification: ") + result.receipt.verification_level
+    );
+    if (result.artifacts.length > 0) {
+      console.log("");
+      console.log(chalk3.dim("  Artifacts:"));
+      for (const artifact of result.artifacts) {
+        const name = artifact.name || artifact.kind;
+        console.log(chalk3.white(`    - ${name}`));
+        if (artifact.url) {
+          console.log(chalk3.dim(`      ${artifact.url}`));
+        }
+      }
+    }
+  }
+  console.log("");
+}
 
 // src/commands/config.ts
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 async function configCommand(options) {
   if (options.reset) {
     resetConfig();
-    console.log(chalk3.green("\n  \u2713 Configuration reset\n"));
+    console.log(chalk4.green("\n  \u2713 Configuration reset\n"));
     return;
   }
   if (options.apiKey) {
     setApiKey(options.apiKey);
-    console.log(chalk3.green("\n  \u2713 API key updated\n"));
+    console.log(chalk4.green("\n  \u2713 API key updated\n"));
     return;
   }
   const config2 = getConfig();
   console.log("");
-  console.log(chalk3.bold("  Configuration"));
-  console.log(chalk3.dim("  Path: ") + getConfigPath());
+  console.log(chalk4.bold("  Configuration"));
+  console.log(chalk4.dim("  Path: ") + getConfigPath());
   console.log("");
   console.log(
-    chalk3.dim("  apiKey:        ") + (config2.apiKey ? config2.apiKey.slice(0, 4) + "..." + config2.apiKey.slice(-4) : chalk3.red("not set"))
+    chalk4.dim("  apiKey:        ") + (config2.apiKey ? config2.apiKey.slice(0, 4) + "..." + config2.apiKey.slice(-4) : chalk4.red("not set"))
   );
-  console.log(chalk3.dim("  apiUrl:        ") + config2.apiUrl);
+  console.log(chalk4.dim("  apiUrl:        ") + config2.apiUrl);
   console.log(
-    chalk3.dim("  mcpConfigured: ") + (config2.mcpConfigured ? chalk3.green("yes") : chalk3.yellow("no"))
+    chalk4.dim("  mcpConfigured: ") + (config2.mcpConfigured ? chalk4.green("yes") : chalk4.yellow("no"))
   );
   if (config2.mcpConfigPath) {
-    console.log(chalk3.dim("  mcpConfigPath: ") + config2.mcpConfigPath);
+    console.log(chalk4.dim("  mcpConfigPath: ") + config2.mcpConfigPath);
   }
   console.log("");
 }
 
+// src/commands/request.ts
+import prompts2 from "prompts";
+import chalk5 from "chalk";
+var TERMINAL_STATES = ["completed", "failed", "expired", "disputed"];
+var POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_TIME_MS = 3e5;
+async function requestCommand(options) {
+  const config2 = getConfig();
+  if (!config2.apiKey) {
+    console.log(
+      chalk5.red("\n  No API key configured. Run `humanlypossible init` first.\n")
+    );
+    process.exit(1);
+  }
+  let outcome = options.outcome;
+  if (!outcome) {
+    const response = await prompts2({
+      type: "text",
+      name: "outcome",
+      message: "Describe the outcome you want:",
+      validate: (v) => v.length > 0 ? true : "Outcome is required"
+    });
+    outcome = response.outcome;
+    if (!outcome) {
+      console.log(chalk5.red("\n  Request cancelled.\n"));
+      process.exit(1);
+    }
+  }
+  let resolveBy = options.deadline;
+  if (!resolveBy) {
+    const response = await prompts2({
+      type: "text",
+      name: "deadline",
+      message: "Deadline (e.g., '1h', '30m', or ISO 8601):",
+      initial: "1h"
+    });
+    resolveBy = response.deadline || "1h";
+  }
+  const deadline = parseDeadline(resolveBy);
+  if (!deadline) {
+    console.log(chalk5.red(`
+  Invalid deadline format: ${resolveBy}
+`));
+    process.exit(1);
+  }
+  debugLog("Creating outcome request", { outcome, resolve_by: deadline });
+  const request = {
+    outcome,
+    resolve_by: deadline
+  };
+  console.log("");
+  console.log(chalk5.cyan("  Creating outcome request..."));
+  const createResult = await createOutcomeRequest(config2.apiKey, request);
+  if (!createResult.ok || !createResult.data) {
+    debugError("Failed to create outcome", createResult.error);
+    console.log(chalk5.red(`
+  Failed to create outcome: ${createResult.error}
+`));
+    process.exit(1);
+  }
+  const outcomeId = createResult.data.id;
+  console.log(chalk5.green(`  Created outcome: ${outcomeId}`));
+  if (options.poll === false) {
+    if (options.json) {
+      console.log(JSON.stringify({ id: outcomeId }));
+    } else {
+      console.log("");
+      console.log(chalk5.dim("  Poll status with:"));
+      console.log(chalk5.white(`    humanlypossible status --id ${outcomeId}`));
+      console.log("");
+    }
+    return;
+  }
+  console.log(chalk5.dim("  Waiting for result (Ctrl+C to stop)..."));
+  console.log("");
+  const startTime = Date.now();
+  let lastState = "";
+  while (Date.now() - startTime < MAX_POLL_TIME_MS) {
+    const statusResult = await getOutcomeStatus(config2.apiKey, outcomeId);
+    if (!statusResult.ok || !statusResult.data) {
+      debugError("Failed to get status", statusResult.error);
+      await sleep(POLL_INTERVAL_MS);
+      continue;
+    }
+    const status = statusResult.data;
+    if (status.state !== lastState) {
+      lastState = status.state;
+      printStatusUpdate(status);
+    }
+    if (TERMINAL_STATES.includes(status.state)) {
+      const resultResponse = await getOutcomeResult(config2.apiKey, outcomeId);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            id: outcomeId,
+            status,
+            result: resultResponse.data || null
+          })
+        );
+      } else {
+        printFinalResult(status, resultResponse.data);
+      }
+      return;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  console.log(chalk5.yellow("\n  Polling timed out after 5 minutes."));
+  console.log(chalk5.dim(`  Check status later with: humanlypossible status --id ${outcomeId}
+`));
+}
+function parseDeadline(input) {
+  const isoDate = new Date(input);
+  if (!isNaN(isoDate.getTime())) {
+    return isoDate.toISOString();
+  }
+  const match = input.match(/^(\d+)\s*(s|m|h|d|w)$/i);
+  if (match) {
+    const value = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    const multipliers = {
+      s: 1e3,
+      m: 60 * 1e3,
+      h: 60 * 60 * 1e3,
+      d: 24 * 60 * 60 * 1e3,
+      w: 7 * 24 * 60 * 60 * 1e3
+    };
+    const futureDate = new Date(Date.now() + value * multipliers[unit]);
+    return futureDate.toISOString();
+  }
+  return null;
+}
+function printStatusUpdate(status) {
+  const stateColors = {
+    queued: chalk5.gray,
+    matching: chalk5.cyan,
+    running: chalk5.blue,
+    needs_input: chalk5.yellow,
+    under_review: chalk5.magenta,
+    completed: chalk5.green,
+    failed: chalk5.red,
+    expired: chalk5.red,
+    disputed: chalk5.yellow
+  };
+  const colorFn = stateColors[status.state] || chalk5.white;
+  const stateStr = colorFn(`[${status.state}]`);
+  const message = status.message ? chalk5.dim(` ${status.message}`) : "";
+  const progress = status.progress?.pct !== void 0 ? chalk5.dim(` (${status.progress.pct}%)`) : "";
+  console.log(`  ${stateStr}${message}${progress}`);
+}
+function printFinalResult(status, result) {
+  console.log("");
+  if (status.state === "completed" && result) {
+    console.log(chalk5.green.bold("  Outcome completed"));
+    if (result.resolution.reason) {
+      console.log(chalk5.dim(`  Reason: ${result.resolution.reason}`));
+    }
+    if (result.artifacts.length > 0) {
+      console.log(chalk5.dim("  Artifacts:"));
+      for (const artifact of result.artifacts) {
+        const name = artifact.name || artifact.kind;
+        const preview = artifact.text_preview ? ` - ${artifact.text_preview.slice(0, 50)}...` : "";
+        console.log(chalk5.white(`    - ${name}${preview}`));
+      }
+    }
+    console.log(
+      chalk5.dim(`  Verification: ${result.receipt.verification_level}`)
+    );
+  } else if (status.state === "failed") {
+    console.log(chalk5.red.bold("  Outcome failed"));
+    if (result?.resolution.reason) {
+      console.log(chalk5.dim(`  Reason: ${result.resolution.reason}`));
+    }
+    if (result?.resolution.failures) {
+      for (const failure of result.resolution.failures) {
+        console.log(chalk5.red(`    - ${failure}`));
+      }
+    }
+  } else if (status.state === "expired") {
+    console.log(chalk5.red.bold("  Outcome expired"));
+    console.log(chalk5.dim("  The deadline passed before completion."));
+  } else if (status.state === "disputed") {
+    console.log(chalk5.yellow.bold("  Outcome disputed"));
+    console.log(chalk5.dim("  A dispute has been filed for this outcome."));
+  }
+  console.log("");
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/commands/serve.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import chalk6 from "chalk";
+var DEFAULT_CONFIG = {
+  capabilities: [],
+  autoAccept: false,
+  handler: "manual",
+  maxConcurrent: 1
+};
+async function serveCommand(options) {
+  const cliConfig = getConfig();
+  if (!cliConfig.apiKey) {
+    console.log(
+      chalk6.red("\n  No API key configured. Run `humanlypossible init` first.\n")
+    );
+    process.exit(1);
+  }
+  const executorConfig = loadExecutorConfig(options.config);
+  const pollInterval = parseInt(options.interval || "10", 10) * 1e3;
+  console.log("");
+  console.log(chalk6.bold("  HumanlyPossible Executor"));
+  console.log(chalk6.dim("  Polling for available outcomes..."));
+  console.log("");
+  if (executorConfig.capabilities && executorConfig.capabilities.length > 0) {
+    console.log(chalk6.dim("  Capabilities:"));
+    for (const cap of executorConfig.capabilities) {
+      console.log(chalk6.white(`    - ${cap}`));
+    }
+    console.log("");
+  }
+  console.log(chalk6.dim(`  Poll interval: ${pollInterval / 1e3}s`));
+  console.log(chalk6.dim(`  Handler: ${executorConfig.handler}`));
+  console.log(chalk6.dim("  Press Ctrl+C to stop"));
+  console.log("");
+  const activeClaims = /* @__PURE__ */ new Set();
+  let running = true;
+  process.on("SIGINT", () => {
+    console.log(chalk6.dim("\n  Shutting down..."));
+    running = false;
+  });
+  process.on("SIGTERM", () => {
+    running = false;
+  });
+  while (running) {
+    try {
+      await pollAndProcess(
+        cliConfig.apiKey,
+        executorConfig,
+        activeClaims
+      );
+    } catch (err) {
+      debugError("Polling error", err);
+      console.log(chalk6.red(`  Error: ${err instanceof Error ? err.message : "Unknown error"}`));
+    }
+    if (running) {
+      await sleep2(pollInterval);
+    }
+  }
+  console.log(chalk6.green("\n  Executor stopped.\n"));
+}
+function loadExecutorConfig(configPath) {
+  if (!configPath) {
+    const defaultPaths = [
+      "humanlypossible.executor.json",
+      ".humanlypossible/executor.json"
+    ];
+    for (const path of defaultPaths) {
+      if (existsSync2(path)) {
+        configPath = path;
+        break;
+      }
+    }
+  }
+  if (!configPath || !existsSync2(configPath)) {
+    debugLog("No executor config found, using defaults");
+    return DEFAULT_CONFIG;
+  }
+  try {
+    const content = readFileSync2(configPath, "utf-8");
+    const parsed = JSON.parse(content);
+    debugLog("Loaded executor config", parsed);
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch (err) {
+    debugError("Failed to parse executor config", err);
+    console.log(chalk6.yellow(`  Warning: Could not parse config at ${configPath}`));
+    return DEFAULT_CONFIG;
+  }
+}
+async function pollAndProcess(apiKey, config2, activeClaims) {
+  debugLog("Polling for available outcomes");
+  const result = await listAvailableOutcomes(apiKey, { limit: 10 });
+  if (!result.ok || !result.data) {
+    if (result.status === 403) {
+      console.log(chalk6.red("  Your API key does not have executor permissions."));
+      console.log(chalk6.dim("  Enable 'can_execute' on your actor to use serve mode."));
+      process.exit(1);
+    }
+    debugError("Failed to list available outcomes", result.error);
+    return;
+  }
+  const outcomes = result.data.items;
+  if (outcomes.length === 0) {
+    debugLog("No available outcomes");
+    return;
+  }
+  debugLog(`Found ${outcomes.length} available outcome(s)`);
+  const matchingOutcomes = filterByCapabilities(outcomes, config2.capabilities);
+  if (matchingOutcomes.length === 0) {
+    debugLog("No outcomes match configured capabilities");
+    return;
+  }
+  const maxConcurrent = config2.maxConcurrent || 1;
+  if (activeClaims.size >= maxConcurrent) {
+    debugLog(`At max concurrent (${activeClaims.size}/${maxConcurrent})`);
+    return;
+  }
+  const outcome = matchingOutcomes[0];
+  if (activeClaims.has(outcome.id)) {
+    debugLog(`Already processing ${outcome.id}`);
+    return;
+  }
+  console.log("");
+  printOutcomeSummary(outcome);
+  if (config2.autoAccept) {
+    await processOutcome(apiKey, outcome, config2, activeClaims);
+  } else {
+    console.log(chalk6.dim("  (Auto-accept disabled. Configure autoAccept: true to claim automatically.)"));
+  }
+}
+function filterByCapabilities(outcomes, capabilities) {
+  if (!capabilities || capabilities.length === 0) {
+    return outcomes;
+  }
+  return outcomes.filter((outcome) => {
+    if (!outcome.outcome) return false;
+    const outcomeText = outcome.outcome.toLowerCase();
+    return capabilities.some((cap) => {
+      const capLower = cap.toLowerCase();
+      return outcomeText.includes(capLower);
+    });
+  });
+}
+function printOutcomeSummary(outcome) {
+  console.log(chalk6.cyan(`  New outcome available: ${outcome.id.slice(0, 8)}...`));
+  console.log(chalk6.white(`    "${outcome.outcome || "No description"}"`));
+  if (outcome.budget?.max_usd) {
+    console.log(chalk6.dim(`    Budget: $${outcome.budget.max_usd}`));
+  }
+  if (outcome.urgency?.priority) {
+    console.log(chalk6.dim(`    Priority: ${outcome.urgency.priority}`));
+  }
+  if (outcome.constraints?.location) {
+    console.log(chalk6.dim(`    Location: ${outcome.constraints.location}`));
+  }
+  const deadline = new Date(outcome.resolve_by);
+  const now = /* @__PURE__ */ new Date();
+  const hoursRemaining = Math.round(
+    (deadline.getTime() - now.getTime()) / (1e3 * 60 * 60)
+  );
+  console.log(chalk6.dim(`    Deadline: ${hoursRemaining}h remaining`));
+}
+async function processOutcome(apiKey, outcome, config2, activeClaims) {
+  console.log(chalk6.cyan(`  Claiming outcome...`));
+  activeClaims.add(outcome.id);
+  const claimResult = await claimOutcome(apiKey, outcome.id);
+  if (!claimResult.ok) {
+    console.log(chalk6.red(`  Failed to claim: ${claimResult.error}`));
+    activeClaims.delete(outcome.id);
+    return;
+  }
+  console.log(chalk6.green(`  Claimed successfully!`));
+  if (config2.handler === "auto") {
+    console.log(chalk6.yellow(`  Auto-handler not yet implemented.`));
+    console.log(chalk6.dim(`  Mark complete manually or implement a script handler.`));
+  } else if (config2.handler === "script" && config2.scriptPath) {
+    await runScriptHandler(apiKey, outcome, config2.scriptPath, activeClaims);
+  } else {
+    console.log(chalk6.dim(`  Waiting for manual completion...`));
+    console.log(chalk6.dim(`  Submit via: POST /v0/outcomes/${outcome.id}/submit`));
+  }
+}
+async function runScriptHandler(apiKey, outcome, scriptPath, activeClaims) {
+  if (!existsSync2(scriptPath)) {
+    console.log(chalk6.red(`  Script not found: ${scriptPath}`));
+    activeClaims.delete(outcome.id);
+    return;
+  }
+  console.log(chalk6.dim(`  Running script: ${scriptPath}`));
+  try {
+    const scriptModule = await import(scriptPath);
+    const handler = scriptModule.default || scriptModule.handle;
+    if (typeof handler !== "function") {
+      console.log(chalk6.red(`  Script must export a default handler function`));
+      activeClaims.delete(outcome.id);
+      return;
+    }
+    const result = await handler(outcome);
+    if (result && result.resolution) {
+      const payload = {
+        result: {
+          resolution: {
+            accepted: result.resolution.accepted ?? true,
+            decided_at: (/* @__PURE__ */ new Date()).toISOString(),
+            oracle: result.resolution.oracle ?? "executor",
+            reason: result.resolution.reason
+          },
+          artifacts: result.artifacts ?? [],
+          receipt: {
+            verification_level: result.receipt?.verification_level ?? "L0"
+          }
+        }
+      };
+      const submitResult = await submitOutcome(apiKey, outcome.id, payload);
+      if (submitResult.ok) {
+        console.log(chalk6.green(`  Outcome completed!`));
+      } else {
+        console.log(chalk6.red(`  Failed to submit: ${submitResult.error}`));
+      }
+    }
+  } catch (err) {
+    debugError("Script handler error", err);
+    console.log(chalk6.red(`  Script error: ${err instanceof Error ? err.message : "Unknown"}`));
+  } finally {
+    activeClaims.delete(outcome.id);
+  }
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/cli.ts
 var program = new Command();
-program.name("humanlypossible").description("Connect AI agents to humans in the real world").version("0.1.0");
+program.name("humanlypossible").description("Connect AI agents to humans in the real world").version("0.1.0").option("--debug", "Enable verbose debug logging").hook("preAction", (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.debug) {
+    setDebug(true);
+  }
+});
 program.command("init").description("Set up HumanlyPossible in your project").option("--api-key <key>", "Provide API key directly (skips interactive prompt)").option("--no-mcp", "Skip MCP server configuration").action(initCommand);
-program.command("status").description("Check your HumanlyPossible connection and configuration").action(statusCommand);
+program.command("status").description("Check your HumanlyPossible connection and configuration").option("--id <outcomeId>", "Show status of a specific outcome").option("--json", "Output as JSON").action(statusCommand);
 program.command("config").description("View or update your configuration").option("--api-key <key>", "Update your API key").option("--reset", "Reset all configuration").action(configCommand);
+program.command("request").description("Create an outcome request and poll for result").option("-o, --outcome <description>", "Outcome description").option("-d, --deadline <datetime>", "Deadline (ISO 8601 or relative like '1h', '30m')").option("--json", "Output result as JSON").option("--no-poll", "Create request but do not poll for result").action(requestCommand);
+program.command("serve").description("Run as an executor: poll for outcomes and fulfill them").option("-c, --config <path>", "Path to executor config file").option("-i, --interval <seconds>", "Polling interval in seconds", "10").action(serveCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanlypossible",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for HumanlyPossible - connect AI agents to humans in the real world",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "humanlypossible",