@volter/twin-runhuman 0.1.0

package/dist/src/runhuman-validate.d.ts

@@ -0,0 +1,40 @@
+import type { RunhumanTwinResponse } from './runhuman-twin.js';
+export type FieldKind = {
+    kind: 'string';
+} | {
+    kind: 'number';
+} | {
+    kind: 'boolean';
+} | {
+    kind: 'enum';
+    values: readonly string[];
+} | {
+    kind: 'object';
+} | {
+    kind: 'array';
+    of: FieldKind;
+} | {
+    kind: 'unknown';
+};
+export type FieldSpec = FieldKind & {
+    required?: boolean;
+    refine?: (value: unknown) => string | undefined;
+};
+/** Validate a parsed JSON body against a z.object-shaped field map (unknown keys are stripped, as
+ *  zod's default object does). Returns the 400 RH1 answers, or undefined when the body passes. */
+export declare function validateBody(body: unknown, fields: Record<string, FieldSpec>): RunhumanTwinResponse | undefined;
+/** A `z.custom` objectGuard over the whole body (RH1's PATCH /tester/jobs/:jobId schema). */
+export declare function validateObjectBody(body: unknown): RunhumanTwinResponse | undefined;
+export declare const DEVICE_CLASSES: readonly ["desktop", "mobile", "both"];
+export declare const TESTER_DEVICES: readonly ["ios", "android", "pc", "mac"];
+export declare const TESTER_LANGUAGES: readonly ["english", "spanish"];
+export declare const CLAIM_SOURCES: readonly ["tester-portal", "mobile-app", "slack", "discord-activity"];
+/** createTestJobRequestSchema (POST /api/jobs). */
+export declare const CREATE_JOB_FIELDS: Record<string, FieldSpec>;
+/** claimJobRequestSchema (POST /api/jobs/:jobId/claim): `claimSource` is REQUIRED by the schema
+ *  even though the handler carries a default. */
+export declare const CLAIM_JOB_FIELDS: Record<string, FieldSpec>;
+/** endJobRequestSchema (POST /api/tester/jobs/:jobId/end). */
+export declare const END_JOB_FIELDS: Record<string, FieldSpec>;
+/** processTestResultsBodySchema (POST /api/tester/jobs/:jobId/process-results). */
+export declare const PROCESS_RESULTS_FIELDS: Record<string, FieldSpec>;

package/dist/src/runhuman-validate.js

@@ -0,0 +1,161 @@
+function zodType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number' && Number.isNaN(value))
+        return 'nan';
+    return typeof value;
+}
+function checkKind(value, kind, path, issues) {
+    const at = (message) => issues.push(path ? `${path}: ${message}` : message);
+    switch (kind.kind) {
+        case 'unknown':
+            return;
+        case 'string':
+        case 'number':
+        case 'boolean':
+            if (typeof value !== kind.kind || (kind.kind === 'number' && Number.isNaN(value)))
+                at(`Expected ${kind.kind}, received ${zodType(value)}`);
+            return;
+        case 'enum':
+            if (typeof value !== 'string') {
+                at(`Expected ${kind.values.map((v) => `'${v}'`).join(' | ')}, received ${zodType(value)}`);
+            }
+            else if (!kind.values.includes(value)) {
+                at(`Invalid enum value. Expected ${kind.values.map((v) => `'${v}'`).join(' | ')}, received '${value}'`);
+            }
+            return;
+        case 'object':
+            if (typeof value !== 'object' || value === null || Array.isArray(value))
+                at('Invalid input');
+            return;
+        case 'array':
+            if (!Array.isArray(value)) {
+                at(`Expected array, received ${zodType(value)}`);
+                return;
+            }
+            value.forEach((el, i) => checkKind(el, kind.of, path ? `${path}.${i}` : String(i), issues));
+            return;
+    }
+}
+/** Validate a parsed JSON body against a z.object-shaped field map (unknown keys are stripped, as
+ *  zod's default object does). Returns the 400 RH1 answers, or undefined when the body passes. */
+export function validateBody(body, fields) {
+    const input = body === undefined || body === null ? {} : body;
+    const issues = [];
+    if (typeof input !== 'object' || Array.isArray(input)) {
+        issues.push(`Expected object, received ${zodType(input)}`);
+    }
+    else {
+        const record = input;
+        for (const [name, spec] of Object.entries(fields)) {
+            const value = record[name];
+            if (value === undefined) {
+                if (spec.required)
+                    issues.push(`${name}: Required`);
+                continue;
+            }
+            const before = issues.length;
+            checkKind(value, spec, name, issues);
+            if (issues.length === before && spec.refine) {
+                const message = spec.refine(value);
+                if (message)
+                    issues.push(`${name}: ${message}`);
+            }
+        }
+    }
+    if (issues.length === 0)
+        return undefined;
+    const error = `Invalid request body: ${issues.join('; ')}`;
+    return { status: 400, body: { error, statusCode: 400, code: 'FST_ERR_VALIDATION' } };
+}
+/** A `z.custom` objectGuard over the whole body (RH1's PATCH /tester/jobs/:jobId schema). */
+export function validateObjectBody(body) {
+    const input = body === undefined || body === null ? {} : body;
+    if (typeof input === 'object' && !Array.isArray(input))
+        return undefined;
+    return { status: 400, body: { error: 'Invalid request body: Invalid input', statusCode: 400, code: 'FST_ERR_VALIDATION' } };
+}
+const S = { kind: 'string' };
+const N = { kind: 'number' };
+const B = { kind: 'boolean' };
+const O = { kind: 'object' };
+const PREF = { kind: 'enum', values: ['inherit', 'always', 'never'] };
+// packages/shared/src/job/device-class.types.ts, tester/tester.types.ts (TESTER_DEVICES,
+// TESTER_LANGUAGES, CLAIM_SOURCES).
+export const DEVICE_CLASSES = ['desktop', 'mobile', 'both'];
+export const TESTER_DEVICES = ['ios', 'android', 'pc', 'mac'];
+export const TESTER_LANGUAGES = ['english', 'spanish'];
+export const CLAIM_SOURCES = ['tester-portal', 'mobile-app', 'slack', 'discord-activity'];
+/** createTestJobRequestSchema (POST /api/jobs). */
+export const CREATE_JOB_FIELDS = {
+    projectId: S,
+    organizationId: S,
+    url: S,
+    description: S,
+    template: S,
+    templateContent: S,
+    targetDurationMinutes: N,
+    maxExtensionMinutes: N,
+    outputSchema: O,
+    resultsTemplate: S,
+    deviceClass: { kind: 'enum', values: DEVICE_CLASSES },
+    screenSize: { kind: 'unknown' },
+    attachments: { kind: 'array', of: O },
+    metadata: {
+        kind: 'object',
+        refine: (value) => {
+            const captureMode = value.captureMode;
+            return captureMode === undefined || captureMode === 'supplier' || captureMode === 'external'
+                ? undefined
+                : 'metadata.captureMode must be supplier or external';
+        },
+    },
+    additionalValidationInstructions: S,
+    githubRepos: { kind: 'array', of: S },
+    githubRepo: S,
+    autoCreateGithubIssuesRepo: S,
+    githubToken: S,
+    commitSha: S,
+    enableCodeContext: B,
+    prNumbers: { kind: 'array', of: N },
+    issueNumbers: { kind: 'array', of: N },
+    checkTestability: B,
+    requiredDevices: { kind: 'array', of: { kind: 'enum', values: TESTER_DEVICES } },
+    requiredLanguages: { kind: 'array', of: { kind: 'enum', values: TESTER_LANGUAGES } },
+    requireSocialVideos: B,
+    requireSideload: B,
+    requiresRunhumanApkInstall: B,
+    autoCreateGithubIssues: B,
+    autoCreateGithubFeedback: B,
+    autoCreateJiraFeedback: B,
+    autoCreateJiraIssues: B,
+    autoCreateLinearIssues: B,
+    enhancedVideo: B,
+    enhanceInstructions: B,
+    autoCreateOnlyTesterSurfaced: B,
+    reopenIssuesOnDuplicate: B,
+    commentOnDuplicate: B,
+    slackNotification: O,
+    emailOnCompletion: PREF,
+    inAppOnCompletion: PREF,
+    emailOnFailure: PREF,
+    inAppOnFailure: PREF,
+};
+/** claimJobRequestSchema (POST /api/jobs/:jobId/claim): `claimSource` is REQUIRED by the schema
+ *  even though the handler carries a default. */
+export const CLAIM_JOB_FIELDS = {
+    claimSource: { kind: 'enum', values: CLAIM_SOURCES, required: true },
+};
+/** endJobRequestSchema (POST /api/tester/jobs/:jobId/end). */
+export const END_JOB_FIELDS = {
+    action: { kind: 'enum', values: ['clear_and_release', 'clear_and_cancel', 'save_and_cancel', 'platform_issue'], required: true },
+    note: { kind: 'string', required: true },
+};
+/** processTestResultsBodySchema (POST /api/tester/jobs/:jobId/process-results). */
+export const PROCESS_RESULTS_FIELDS = {
+    job: O,
+    prefillTemplate: S,
+    clientInfo: O,
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-runhuman",
+  "version": "0.1.0",
+  "description": "Local Runhuman 1 (runhuman.com/api) twin: job create/read/list, the tester claim-to-completion lifecycle, RH1-exact refusals. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/runhuman"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/runhuman#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-runhuman": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-runhuman CLI: serve the KERNEL-BACKED Runhuman 1 API twin, or run conformance. State lives
+// in the @volter/world-core action log under --root. Conformance is dev-only + lazy-imported.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createRunhumanTwinServer } from './runhuman-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createRunhumanTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`runhuman twin (Runhuman 1 jobs API + tester lifecycle)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkRunhumanConformance } = await import('./runhuman-conformance.ts');
+  const report = await checkRunhumanConformance(root ? { root } : {});
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-runhuman serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+import type { TwinPack } from '@volter/world-core';
+export { handleRunhumanTwinRequest, RUNHUMAN_RESOURCE_TYPES } from './runhuman-twin.ts';
+export type { RunhumanTwinRequest, RunhumanTwinResponse } from './runhuman-twin.ts';
+export { createRunhumanTwinFetch, createRunhumanTwinServer } from './runhuman-server.ts';
+export { liveRunhumanExecute, syncRunhumanFromReal, RUNHUMAN_API_BASE } from './runhuman-connector.ts';
+export {
+  RUNHUMAN_BUDGET_CEILING,
+  RUNHUMAN_BUDGET_MAX_RETRY_AFTER_S,
+  RUNHUMAN_BUDGET_WINDOW_MS,
+  RUNHUMAN_CALL_WEIGHTS,
+  RUNHUMAN_RATE_BUDGET,
+  RunhumanBudget,
+  RunhumanBudgetError,
+  runhumanBudgetPath,
+  runhumanCallWeight,
+} from './runhuman-budget.ts';
+export type { RunhumanBudgetErrorKind, RunhumanBudgetOptions, RunhumanBudgetReservation, RunhumanBudgetSnapshot } from './runhuman-budget.ts';
+import { RUNHUMAN_RATE_BUDGET as RATE_BUDGET } from './runhuman-budget.ts';
+
+// Registry descriptor (TwinPack) — the pack self-describes so tooling can discover it, and it is
+// the SINGLE HOME for this vendor's world-facing facts. `bun scripts/pack-facts.ts` compiles
+// `adoption` / `hosts` / `endpointEnv` into packages/world-core/generated/pack-facts.json;
+// re-run it after ANY edit below or the drift gate (scripts/pack-facts.test.ts) goes RED.
+export const pack: TwinPack = {
+  vendor: 'runhuman',
+  transport: 'rest',
+  protocol: '2', // the platform protocol major this package targets (runtime contract R16)
+  // The branch round trip: an organization, its project and an API key seeded (RH1 has no public API that makes them;
+  // the seeds refuse an id already held, so the branch's re-seed is refused and changes nothing), then a job created
+  // through RH1's own API, the write a branch repeats (each create is a new job).
+  roundTrip: [
+    { method: 'POST', path: '/_twin/organizations', body: { id: 'roundtrip-org', name: 'Round Trip' } },
+    { method: 'POST', path: '/_twin/projects', body: { id: 'roundtrip-proj', organizationId: 'roundtrip-org', name: 'Round Trip' } },
+    { method: 'POST', path: '/_twin/api-keys', body: { id: 'roundtrip-key', organizationId: 'roundtrip-org', key: 'rh_roundtripkey' } },
+    { method: 'POST', path: '/api/jobs', body: { projectId: 'roundtrip-proj', url: 'https://round.trip.test/', description: 'round trip' }, headers: { authorization: 'Bearer rh_roundtripkey' } },
+  ],
+  archetype: 'crud',
+  bin: 'world-runhuman',
+  rateBudget: RATE_BUDGET,
+  resources: ['organization', 'project', 'api_key', 'user', 'tester_profile', 'job', 'pipeline_run'],
+  specSource: 'RH1 source at volter-ai/runhuman origin/main 2f2fcb2c5 — packages/api/src/routes/jobs/** (create/get/claim/tester handlers), routes/projects.routes.ts, middleware/{auth,dual-auth,clerk-auth}.ts, packages/shared/src/contracts/{job,tester-job}.schema.ts; the vendor is our own product, so its source is the specification (no published OpenAPI).',
+  description: 'Runhuman 1 (runhuman.com/api) jobs twin — POST /api/jobs, GET /api/jobs/:id(/status), GET /api/projects/:id/jobs, the tester lifecycle (claim → testerToken PATCH → process-results → issue-review → complete, or end), RH1-exact refusals; the AI pipeline is folded into the status poll, timers and integrations are unmodelled (JSON 404 with x-twin-gap). Kernel-backed, no mirror.',
+
+  // ADOPTION — the RH1 CLI (npm `runhuman`, packages/cli) is the first-party client of this surface.
+  // No envStem and no scope: RH2 ships under the same brand (`RUNHUMAN`, `@runhuman/`), so a
+  // stem here would attribute RH2's code to RH1.
+  adoption: {
+    sdks: ['runhuman'],
+  },
+
+  // INTERCEPTION — RH1 serves its API under runhuman.com/api (the CLI's default apiUrl is
+  // https://runhuman.com; packages/cli/src/commands/auth/login.ts). Only /api/* is this twin's.
+  hosts: [{ host: 'runhuman.com', pathPattern: '^/api/' }],
+
+  // WORLD WIRING — the RH1 CLI reads RUNHUMAN_API_URL as its base URL
+  // (packages/cli/src/lib/config.ts: `if (process.env.RUNHUMAN_API_URL) config.apiUrl = …`).
+  endpointEnv: {
+    name: 'RUNHUMAN_API_URL',
+    note: 'grounded in volter-ai/runhuman packages/cli/src/lib/config.ts, which overrides the CLI apiUrl from RUNHUMAN_API_URL; RH2 reads its human-marketplace base URL from the provider row spec.url instead, which a rehearsal World sets to this same twin URL.',
+  },
+};

package/src/runhuman-budget.ts

@@ -0,0 +1,66 @@
+// Runhuman client-side rate budget. The mechanism is the kernel's shared RateBudget; only
+// Runhuman's declaration lives here.
+//
+// Vendor source (Runhuman is our own product; read-only checkout of volter-ai/runhuman):
+// packages/static-site/src/content/docs/api.mdx "Rate Limiting" and docs/rate-limiting.md. The API
+// enforces two PER-IP tiers: 200 requests/minute per route pattern and 500 requests/minute across
+// all routes, answering 429 with Retry-After past either. Both are per-IP, not per-API-key, so
+// callers behind one egress IP share them — a per-key ledger cannot see that sharing. This
+// declaration therefore stays AT the kernel fallback, far under both published tiers: 60 weighted
+// units per minute; reads cost 2 (30/min), writes 3 (20/min), and job creation 5 (12/min) because
+// every POST /api/jobs dispatches a PAID human tester.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'runhuman';
+export const RUNHUMAN_BUDGET_WINDOW_MS = 60_000;
+export const RUNHUMAN_BUDGET_CEILING = 60;
+export const RUNHUMAN_BUDGET_MAX_RETRY_AFTER_S = 300;
+export const RUNHUMAN_CALL_WEIGHTS = { createJob: 5, mutation: 3, read: 2 } as const;
+
+export const RUNHUMAN_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: RUNHUMAN_BUDGET_WINDOW_MS,
+  ceiling: RUNHUMAN_BUDGET_CEILING,
+  defaultWeight: RUNHUMAN_CALL_WEIGHTS.read,
+  maxRetryAfterSeconds: RUNHUMAN_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /api/jobs$', weight: RUNHUMAN_CALL_WEIGHTS.createJob },
+    { match: '^(POST|PUT|PATCH|DELETE) ', weight: RUNHUMAN_CALL_WEIGHTS.mutation },
+  ],
+  reason:
+    'Runhuman documents two per-IP limits (volter-ai/runhuman api.mdx "Rate Limiting", docs/rate-limiting.md): ' +
+    '200 requests/minute per route and 500 requests/minute aggregate, 429 + Retry-After past them. Per-IP, not ' +
+    'per-key, so a per-key ledger stays at the kernel fallback, well under both: 60 weighted units per minute; ' +
+    'reads 2, writes 3, job creation 5 (each dispatches a paid human tester).',
+};
+
+declareRateBudget(VENDOR, RUNHUMAN_RATE_BUDGET);
+
+export function runhumanCallWeight(method: string, path: string): number {
+  return rateBudgetWeight(VENDOR, `${method.toUpperCase()} ${path.split('?')[0] ?? path}`);
+}
+
+export function runhumanBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const value = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...value, vendor: VENDOR });
+}
+
+export type RunhumanBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+export class RunhumanBudget extends RateBudget {
+  constructor(opts: RunhumanBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export type { RateBudgetErrorKind as RunhumanBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as RunhumanBudgetError } from '@volter/world-core';
+export type RunhumanBudgetReservation = RateBudgetReservation;
+export type RunhumanBudgetSnapshot = RateBudgetSnapshot;