humanish 0.104.3 → 0.106.0

package/dist/lab/init-templates.js

@@ -0,0 +1,416 @@
+export const DEFAULT_LOCAL_BROWSER_STARTER = {
+    appUrl: "http://127.0.0.1:3000",
+    mission: "Use the app's primary flow. Explain anything confusing and stop when the task is complete or you are stuck.",
+};
+function localBrowserLab(starter = DEFAULT_LOCAL_BROWSER_STARTER) {
+    return {
+        path: "humanish/labs/local-browser.yaml",
+        plane: "source",
+        contents: `schema: humanish.lab.v2
+id: local-browser
+title: Local browser · your app · Codex account
+description: >-
+  Run a Codex-account participant in an isolated local browser against your loopback app—no E2B
+  or OpenAI API key. Inference is remote and uses account quota. Before the first live run, use
+  humanish doctor --lab local-browser to check the supported Codex login and local runtime.
+subject:
+  source: app-url
+  appUrl: ${JSON.stringify(starter.appUrl)}
+actors:
+  - type: local-agent
+    localAgent: codex
+    persona: synthetic-new-user
+    mission: ${JSON.stringify(starter.mission)}
+execution:
+  target: local
+  concurrency: 1
+  timeoutMs: 120000
+scenario:
+  mode: live
+defaults:
+  open: true
+`,
+    };
+}
+/**
+ * The flagship live lab. A ChatGPT-account Codex participant has no API-dollar price, so preflight
+ * refuses a dollar cap on it (HUMANISH_CUA_LAB_UNPRICED_CAP); that variant is bounded by the
+ * session timeout instead of a cap it could never enforce.
+ */
+function tryLiveLab(actor, localAgent = "codex") {
+    const account = actor === "local-agent";
+    const cost = account
+        ? `  WHAT IT COSTS: one participant, one small task, a few E2B desktop minutes and your Codex
+  account's usage. Account usage has no dollar price humanish can enforce, so the ten-minute
+  session limit below bounds the run.`
+        : `  WHAT IT COSTS: one participant, one small task, and a $2 cap on estimated model spend. The
+  run stops before its next model request once the estimate passes $2, so the last request can take
+  it slightly over. Hosted desktop time is billed separately.`;
+    const participant = account
+        ? `  # Your machine has a coding agent signed in, so this lab uses it: no provider API key,
+  # only E2B. To use a provider key instead, swap to \`type: openai-computer-use\` and add
+  # execution.caps.maxUsd.
+  - type: local-agent
+    localAgent: ${localAgent}`
+        : `  - type: openai-computer-use
+    # Bounds each model reply. Under the cap below it also bounds what a stalled or lost request
+    # can cost, so the run can retry it instead of stopping.
+    maxOutputTokens: 8192`;
+    const bound = account
+        ? "  timeoutMs: 600000 # bounds the run; a dollar cap cannot be enforced on account usage"
+        : `  timeoutMs: 600000
+  caps:
+    maxUsd: 2 # estimated model spend; the run stops before its next request once it passes this`;
+    return {
+        path: "humanish/labs/try-live.yaml",
+        plane: "source",
+        contents: `schema: humanish.lab.v2
+id: try-live
+title: Your first REAL study — one participant, a real app, a hosted desktop
+description: >-
+  This lab runs live out of the box, on purpose. Every other starter file here is a template you
+  have to fill in first, and a first live run that cannot succeed is where most people stop.
+  THE SUBJECT IS A DEMO, NOT YOUR APP: it clones drawDB, a real public open-source diagram editor,
+  and serves it inside the sandbox. That is what makes this runnable with nothing to configure.
+  Once you have watched it work, point subject at your own app (see humanish/labs/cua-browser.yaml
+  for the shape) — that is the study you actually want.
+${cost}
+  WHAT A GOOD RESULT LOOKS LIKE: not necessarily a pass. A participant who gets stuck and says so
+  is the most useful thing this tool produces — humanish will refuse to call that a credible pass,
+  on purpose, and the friction they describe is the finding. A first run that ends in "I could not
+  do it, and here is where I got lost" worked exactly as intended.
+subject:
+  source: clone
+  repos:
+    - drawdb-io/drawdb
+  clone:
+    depth: 1
+  serve:
+    # Plain npm — humanish provides the Node runtime the stock desktop image does not ship.
+    install: npm install --no-audit --no-fund
+    build: npm run build
+    start: npx vite preview --host 127.0.0.1 --port 3000
+    url: http://127.0.0.1:3000/
+actors:
+${participant}
+    persona: synthetic-new-user
+    mission: >-
+      You have never seen this diagram tool before. Add two tables and give them meaningful names,
+      then stop and say what you did, what confused you, and where you hesitated.
+execution:
+  target: e2b-desktop
+${bound}
+scenario:
+  mode: live # the point of this lab — the others start as dry-run
+defaults:
+  open: true
+`,
+    };
+}
+export const starterFiles = [
+    {
+        path: "humanish/README.md",
+        plane: "source",
+        contents: `# humanish
+
+This directory is the committed source of persona simulation intent for this app.
+
+Keep this directory public-safe:
+
+- synthetic personas only;
+- synthetic fixtures only;
+- env var names only, never values;
+- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
+
+Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
+
+Labs:
+
+- committed reusable labs live in humanish/labs/*.yaml;
+- private or machine-local labs live in ignored .humanish/labs/*.yaml or .humanish/local/labs/*.yaml;
+- run a lab with \`humanish watch <lab>\` or \`humanish lab run <lab>\`.
+
+Format standard:
+
+- human-authored humanish source uses .yaml;
+- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
+- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
+`,
+    },
+    {
+        path: "humanish/personas/synthetic-new-user.yaml",
+        plane: "source",
+        contents: `schema: humanish.persona.v1
+id: synthetic-new-user
+name: Synthetic New User
+summary: A privacy-safe first-time user evaluating the app with realistic but synthetic needs.
+traits:
+  patience: medium
+  technical_confidence: medium
+constraints:
+  - Do not use real personal data.
+  - Do not use production accounts.
+  - Treat all credentials as env var names only.
+`,
+    },
+    {
+        path: "humanish/personas/skeptical-power-user.yaml",
+        plane: "source",
+        contents: `schema: humanish.persona.v1
+id: skeptical-power-user
+name: Skeptical Power User
+summary: A privacy-safe experienced user looking for speed, reversibility, and clear proof.
+traits:
+  patience: low
+  technical_confidence: high
+  accessibility_needs: keyboard_first
+constraints:
+  - Do not use real personal data.
+  - Prefer synthetic fixture inputs.
+  - Flag unclear recovery paths.
+`,
+    },
+    {
+        path: "humanish/scenarios/first-run-smoke.yaml",
+        plane: "source",
+        contents: `schema: humanish.scenario.v1
+id: first-run-smoke
+title: First-run smoke
+persona: synthetic-new-user
+goal: Reach the first meaningful product state without using private data.
+mode: dry-run
+steps:
+  - name: Open the app
+    expectation: The app shell is reachable.
+  - name: Complete the first synthetic action
+    expectation: The user sees a clear next state.
+  - name: Capture review notes
+    expectation: Notes are public-safe and evidence-backed.
+`,
+    },
+    {
+        path: "humanish/scenarios/onboarding-regression.yaml",
+        plane: "source",
+        contents: `schema: humanish.scenario.v1
+id: onboarding-regression
+title: Onboarding regression
+persona: skeptical-power-user
+goal: Exercise onboarding friction using synthetic inputs and explicit recovery checks.
+mode: dry-run
+steps:
+  - name: Start onboarding
+    expectation: Required information is clear.
+  - name: Use synthetic fixture data
+    expectation: No real user data is entered.
+  - name: Check recovery path
+    expectation: The user can back out or retry safely.
+`,
+    },
+    {
+        path: "humanish/labs/first-run.yaml",
+        plane: "source",
+        contents: `schema: humanish.lab.v2
+id: first-run
+title: First-run synthetic Observer
+description: Public-safe starter lab that generates a synthetic run bundle and Observer without provider spend.
+subject:
+  source: this-repo
+actors:
+  - type: synthetic-persona
+    count: 4
+scenario:
+  mode: dry-run
+defaults:
+  open: true
+`,
+    },
+    tryLiveLab("openai-computer-use"),
+    localBrowserLab(),
+    {
+        path: "humanish/labs/cua-browser.yaml",
+        plane: "source",
+        contents: `schema: humanish.lab.v2
+id: cua-browser
+title: Computer-use browser lab
+description: >-
+  A registered computer-use actor drives your app in a hosted desktop browser and emits an
+  evidence bundle into gitignored .humanish/. Screenshots are full-fidelity (raw) by default;
+  set policies.redactScreenshots: true to blur at capture for a share-as-is bundle. Typed
+  text is recorded as length only. Dry-run by default; switch scenario.mode to live (with
+  OPENAI_API_KEY + E2B_API_KEY via --env-file) for a real session. The clone subject below
+  serves your repo INSIDE the sandbox; declared subject env NAMES are provisioned from
+  --env-file (values are never persisted).
+subject:
+  source: clone
+  repos: [your-org/your-app]
+  serve:
+    install: pnpm install --frozen-lockfile
+    build: pnpm build
+    start: pnpm start
+    url: http://127.0.0.1:3000/
+    # installTimeoutMs: 1200000   # bump for monorepo-scale installs/builds (default 600000)
+    # buildTimeoutMs: 1800000
+  # env: [DATABASE_URL]
+  # state:                        # the subject's STATE story (recorded as provenance):
+  #   seed:                       # ordered, bounded seed/migration/fixture steps (commands are
+  #     - name: db-up             # author-trusted; evidence records sha256 digests, never text)
+  #       command: sudo service postgresql start && pg_isready -t 30
+  #       when: before-start      # before-build | before-start (default) | after-ready
+  #     - name: db-migrate
+  #       command: pnpm prisma migrate deploy
+  #       timeoutMs: 300000       # per-step budget (default 300000)
+  #     - name: admin-user        # after-ready steps run against the RUNNING app
+  #       command: curl -sf -X POST http://127.0.0.1:3000/api/test/bootstrap-admin
+  #       when: after-ready
+  #   # Or point at a shared DB you do NOT control — recorded as UNPINNED in provenance;
+  #   # each name must also be declared in subject.env:
+  #   # external: [DATABASE_URL]
+  # clone:
+  #   keep: true                  # leave the sandbox up on FAILURE so you can debug install/boot
+  # Alternative: drive a deployment you own (Vercel preview, staging) instead of a clone:
+  # source: app-url
+  # appUrl: https://your-preview.vercel.app/
+actors:
+  - type: openai-computer-use
+    persona: first-time-visitor
+    mission: >-
+      Explore the app as a brand-new user trying to complete its primary flow. Note anything
+      confusing. Stop when the flow completes or you are stuck.
+execution:
+  target: e2b-desktop
+  # 20 minutes: a session should end because the participant finished, not because a timer fired,
+  # so this is as long as the substrate allows rather than as long as seems reasonable. This route
+  # clones, installs, builds and serves the subject before the actor starts, so the sandbox deadline
+  # is this budget PLUS 40 minutes of provisioning and teardown headroom — and a sandbox may not
+  # live longer than 60. Raising this above 20 minutes fails the run closed before it starts; raise
+  # execution.desktop.sandboxTimeoutMs deliberately if you need more.
+  # Spend protection belongs to the dollar caps, not the clock.
+  timeoutMs: 1200000
+  desktop:
+    device: desktop             # mobile | small-mobile | narrow-mobile | tablet | desktop | wide
+    # browser: chrome            # default | chrome | chromium | firefox; concrete values fail closed
+    # Presets size the physical screen; Chrome's window width has a ~500px minimum.
+    # For mobile presets, opt into CSS viewport, touch, DPR and mobile user-agent emulation:
+    # fidelity: { mobileEmulation: true } # Chrome/Chromium only; desktop/tablet lanes unchanged
+    # The bundle records measured screen, page viewport and emulation fidelity separately.
+scenario:
+  mode: dry-run
+# policies:
+#   redactScreenshots: true       # blur persisted frames (default off — full fidelity for local use)
+#   allowPublicTargets: true      # required to drive a non-loopback app-url (a deployment you own)
+defaults:
+  open: true
+`,
+    },
+    {
+        path: "humanish/labs/lobby-trivia-3player.yaml",
+        plane: "source",
+        contents: `schema: humanish.lab.v2
+id: lobby-trivia-3player
+title: External-public shared world (N mobile personas share ONE public app at once)
+description: >-
+  A worked example of the EXTERNAL-PUBLIC shared-world route (#164 phase 2): N mobile-LAYOUT
+  personas play the SAME multiplayer lobby on a REAL public deployment AT ONCE. The public site is
+  the shared plane DIRECTLY — NO clone, NO getHost, NO subject sandbox, NO seed. A host-first barrier
+  extracts the shared-session code from the host seat's CDP-observed URL and threads it into the
+  follower join missions (followers go through the real Join flow). Dry-run (the default) emits ONE
+  external-public evidence bundle at $0. A live run needs OPENAI_API_KEY + E2B_API_KEY and
+  scenario.mode: live. Point appUrl + publicTarget at a public deployment YOU own/operate.
+  MOBILE FIDELITY: by default Chrome's physical window has a 500px minimum width, no touch
+  emulation and desktop DPR/user-agent behavior. Set execution.desktop.fidelity.mobileEmulation to true
+  to request the mobile preset's CSS viewport, touch, DPR and mobile user agent on Chrome/Chromium.
+  The bundle records measured geometry and emulation fidelity. HONESTY: attribution stays
+  shared-world, but every strength claim degrades honestly — provenance external-public (not seeded),
+  NO synthetic attestation (you cannot claim synthetic on a real site), NO authoritative shared-state
+  proof, concurrency by temporal co-occupancy + observed lobby convergence.
+subject:
+  source: app-url # the real public deployment IS the shared plane (no clone, no getHost)
+  topology: shared-world # the declared override of the per-lane-worlds default
+  appUrl: https://your-public-app.example/ # a deployment YOU own/operate
+  publicTarget: # REQUIRED ownership attestation (the honest analog of exposure: synthetic)
+    owner: your-org/your-app
+    authorized: true
+policies:
+  allowPublicTargets: true # REQUIRED: the shared plane is a real non-loopback public deployment
+actors:
+  - type: openai-computer-use
+    mission: You are one of several users on the same shared session at once. Play your role, then stop.
+    lanes: # the roster (>=2) with EXACTLY ONE host: true seat
+      - id: host
+        host: true # the designated host seat that creates the shared session
+        device: mobile # 414x896 preset; physical window width floors to 500 (see emulation above)
+        instruction: Create a shared lobby, wait for the others to join, then start and play.
+      - id: player-2
+        device: mobile
+        instruction: Join the lobby you're told the code for, then play.
+      - id: player-3
+        device: small-mobile
+        instruction: Join the lobby you're told the code for, then play.
+execution:
+  target: e2b-desktop
+  # PER-SEAT session budget; also caps the host-first handoff deadline. Budget for the WHOLE arc:
+  # seat provisioning + shared-session assembly + actual play. A first live run of the worked
+  # example died at 120000 with every seat expiring mid game and zero mission actions taken.
+  timeoutMs: 420000
+  concurrency: 3 # all 3 seats live at once (the default when omitted); lower only to cap paid desktops
+  # desktop:
+  #   fidelity: { mobileEmulation: true } # opt into mobile CSS viewport, touch, DPR and user agent
+scenario:
+  mode: dry-run # default; the live path opens N real mobile-layout seats against the public app
+defaults:
+  open: true
+`,
+    },
+    {
+        path: "humanish/coverage-map.md",
+        plane: "source",
+        contents: `# Coverage Map
+
+This file should enumerate screens, roles, states, and paths before scenarios are treated as complete.
+
+Current starter coverage is intentionally minimal and synthetic.
+`,
+    },
+    {
+        path: "humanish/coverage-matrix.md",
+        plane: "source",
+        contents: `# Coverage Matrix
+
+| Area | Persona | Happy Path | Sad Path | Status |
+| --- | --- | --- | --- | --- |
+| First run | synthetic-new-user | planned | planned | starter |
+| Onboarding | skeptical-power-user | planned | planned | starter |
+`,
+    },
+];
+export const runtimeDirectories = [
+    { path: ".humanish/runs", plane: "runtime" },
+    { path: ".humanish/cache", plane: "runtime" },
+    { path: ".humanish/tmp", plane: "runtime" },
+    { path: ".humanish/logs", plane: "runtime" },
+    { path: ".humanish/labs", plane: "runtime" },
+    { path: ".humanish/local/labs", plane: "runtime" },
+    { path: ".humanish/local/personas", plane: "runtime" },
+];
+export const humanishScripts = {
+    humanish: "humanish",
+    "humanish:doctor": "humanish doctor",
+    "humanish:run": "humanish run --dry-run",
+    "humanish:watch": "humanish watch",
+    "humanish:watch:ci": "humanish watch --json --no-open",
+    "humanish:verify": "humanish verify",
+};
+/**
+ * The starter files, with the live lab written for the brain this machine can use.
+ *
+ * `local-agent` is not a variant of the lab so much as a different participant: on a machine with
+ * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
+ * only E2B. Writing the other one there would hand someone homework instead of a first run.
+ */
+export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent) {
+    return starterFiles.map((file) => file.path === "humanish/labs/local-browser.yaml"
+        ? localBrowserLab(localBrowser)
+        : file.path === "humanish/labs/try-live.yaml"
+            ? tryLiveLab(actor, localAgent)
+            : file);
+}

package/dist/lab/init.d.ts

@@ -0,0 +1,39 @@
+declare const INIT_RESPONSE_SCHEMA = "humanish.init-result.v1";
+export interface InitOptions {
+    cwd: string;
+    dryRun?: boolean;
+    yes?: boolean;
+    /** Injected so a test can decide what credentials this machine appears to have. */
+    env?: NodeJS.ProcessEnv;
+    /** Configure the starter local-browser lab without making the operator edit YAML. */
+    localBrowser?: {
+        appUrl: string;
+        mission?: string;
+    };
+}
+type InitMode = "dry-run" | "applied" | "needs-confirmation";
+export interface InitChange {
+    path: string;
+    action: "create" | "mkdir" | "update" | "skip";
+    target: "source" | "runtime" | "gitignore" | "package-json";
+    reason: string;
+}
+export interface InitResult {
+    schema: typeof INIT_RESPONSE_SCHEMA;
+    ok: boolean;
+    mode: InitMode;
+    cwd: string;
+    changes: InitChange[];
+    warnings: string[];
+    /**
+     * The next one or two commands, already resolved against THIS machine's credentials. Present on
+     * an applied init; absent on a dry-run or a failure, where there is no "next" yet.
+     */
+    nextSteps?: string[];
+    error?: {
+        code: "HUMANISH_CONFIRMATION_REQUIRED" | "HUMANISH_INVALID_CWD" | "HUMANISH_INVALID_PACKAGE_JSON" | "HUMANISH_INVALID_LOCAL_BROWSER" | "HUMANISH_UNSAFE_PROJECT_PATH";
+        message: string;
+    };
+}
+export declare function runInit(options: InitOptions): Promise<InitResult>;
+export {};