firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/contracts.js

@@ -0,0 +1,218 @@
+/**
+ * Native client contract types (Plan20 W09/W10, Claude lane).
+ *
+ * Two kinds of type live here and must not be confused:
+ *  1. Root-released wire contracts, mirrored exactly:
+ *     - backend/contracts/native/local-descriptor.v1.schema.json  (LocalDescriptor)
+ *     - backend/contracts/native/observation-batch.v1.schema.json (ObservationBatch)
+ *  2. Client-side expectations for producers root has NOT released yet
+ *     (assignment, step, binding, identity, completion, artifact intent). They are
+ *     the typed boundary the companion is implemented against. Phase B wiring maps
+ *     root's frozen wire format onto these; until then the HTTP adapter reports
+ *     `native_contract_pending` and never fabricates success or guesses routes.
+ *
+ * Nothing in this file is a claim that an endpoint exists or that a profile is
+ * runtime-qualified. No secret value may be serialized through these types except
+ * inside SecretValue, which refuses JSON/inspect disclosure.
+ */
+import { inspect } from 'node:util';
+import { CliError } from '../http.js';
+// ---------------------------------------------------------------------------
+// Root-released: local descriptor v1 (exact mirror of the JSON schema).
+export const LOCAL_DESCRIPTOR_SCHEMA = 'firedrill.local-descriptor.v1';
+export const DRIVER_PROFILES = ['http.v1', 'jsonl-process.v1', 'function-wrapper.v1', 'playwright.v1', 'signed-http-event.v1'];
+export const TARGET_AUTHENTICATIONS = ['anonymous', 'synthetic-session'];
+export const SERVICE_ROLES = ['agent', 'frontend', 'worker', 'database', 'queue', 'service'];
+export const STATE_KINDS = ['process', 'browser', 'files', 'database', 'vector', 'cache', 'queue', 'scheduler', 'session'];
+export const STATE_LOCATIONS = ['local', 'cloud-disposable', 'observation-only'];
+export const STATE_RESETS = ['fresh-session', 'fresh-process', 'approved-hook', 'unavailable'];
+// ---------------------------------------------------------------------------
+// Root-released: observation batch v1 (exact mirror of the JSON schema).
+export const OBSERVATION_KINDS = ['driver.started', 'conversation.observed', 'action.observed', 'state.observed',
+    'driver.completed', 'driver.failed', 'driver.cancelled'];
+export const OBSERVATION_BATCH_MAX_EVENTS = 128;
+/** Identifier pattern shared by observation-batch ids. */
+export const NATIVE_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+/** Root's server-issued ids (Python str(uuid.UUID)): lowercase canonical form. */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const SHA256_HEX = /^[a-f0-9]{64}$/;
+export const ALIAS = /^[a-z][a-z0-9_-]*$/;
+// ---------------------------------------------------------------------------
+// Secret handling. Values from the cloud (synthetic credentials, signing keys)
+// are wrapped immediately and only unwrapped at the exact injection point.
+const secretValues = new WeakMap();
+export class SecretValue {
+    label;
+    constructor(value, label = 'secret') {
+        if (typeof value !== 'string' || !value)
+            throw new CliError('native_secret_invalid', 'A required credential was empty or malformed.');
+        secretValues.set(this, value);
+        this.label = label;
+    }
+    /** Reveal only at the injection boundary (env, header, MCP config in private scratch). */
+    reveal() { return secretValues.get(this); }
+    toJSON() { return `[redacted:${this.label}]`; }
+    toString() { return `[redacted:${this.label}]`; }
+    [inspect.custom]() { return `[redacted:${this.label}]`; }
+}
+/**
+ * Root's target-action kinds. `participant_message` is the v1 dispatch (a cloud
+ * participant's turn); the others are v2 dispatches frozen from the approved
+ * scenario's explicit target input: a scripted message, a task or a signed event.
+ */
+export const TARGET_ACTION_KINDS = ['participant_message', 'scenario_message', 'task', 'event'];
+/** The signature header root names on every event dispatch. */
+export const EVENT_SIGNATURE_HEADER = 'x-firedrill-signature';
+export const TARGET_MESSAGE_MAX_CHARS = 16_000;
+/** Root's size bound for a retained task or event result document. */
+export const TARGET_RESULT_MAX_BYTES = 65_536;
+/**
+ * Root's credential check reads a task or event result document as one text and
+ * only its first 32,000 characters, so a longer document fails at completion
+ * (asked of root to scan the whole document). Until then results stay within it.
+ */
+export const TARGET_RESULT_SCAN_CHARS = 32_000;
+/**
+ * Screenshot capture coverage (`state.observed` records, agreed with root
+ * 2026-11-10): capture configuration and coverage, never target actions or tool
+ * state. `capture.requested` is recorded once per drill when the approved plan
+ * turns screenshots on; `capture.unavailable` at most once per step whose capture
+ * produced no image. Neither holds error text, selectors or page content. No
+ * `capture.requested` record means unknown (incomplete evidence or an older
+ * client), not that capture was off.
+ */
+export const CAPTURE_SCHEMA = 'firedrill.native-capture.v1';
+/** Why an approved screenshot produced no image for one step. Each reason is one distinct client branch. */
+export const CAPTURE_UNAVAILABLE_REASONS = [
+    /** The capture or its masking threw or timed out, or the step was stopped first: it fails closed, with no image. */
+    'capture_failed',
+    /** The raw capture was over the client's byte bound before re-encoding. */
+    'image_too_large',
+    /** The capture could not be re-encoded within the masked PNG profile (format, dimensions or encoded size). */
+    'image_unsupported',
+    /** The browser session had already taken its maximum number of screenshots. */
+    'session_limit',
+    /** The page or its session had closed. */
+    'page_closed',
+    /**
+     * The image did not fit, though this smaller record did. A capture may only use room left after the step's own
+     * record and its reply or result, and screenshots together at most half the drill's evidence budget.
+     */
+    'evidence_capacity',
+];
+/** Approved interval frames (plan `screenshots.frames`): bounds root's captured-frame playback accepts from this client. */
+export const FRAME_INTERVAL_MIN_MS = 1_000;
+export const FRAME_INTERVAL_MAX_MS = 10_000;
+export const MAX_FRAMES_PER_STEP = 30;
+/** Why an interval frame produced no record: a capture reason, or the plan's per-step frame count was reached while the step still ran. */
+export const FRAME_OMISSION_REASONS = [...CAPTURE_UNAVAILABLE_REASONS, 'step_limit'];
+/**
+ * Root's closed sanitized action trace (`firedrill.native-trace-segment.v1`,
+ * profile `sanitized-actions-v1`, 2026-11-10): which kind of browser operation
+ * the approved flow ran, how it ended and when. Never selectors, URLs, values,
+ * page text, arguments or errors. Not a Playwright trace, HAR or video.
+ */
+export const TRACE_SEGMENT_SCHEMA = 'firedrill.native-trace-segment.v1';
+export const TRACE_PROFILE = 'sanitized-actions-v1';
+export const TRACE_OPERATIONS = ['navigate', 'click', 'fill', 'press', 'select', 'check', 'uncheck', 'wait', 'assert', 'observe'];
+export const TRACE_OUTCOMES = ['completed', 'failed', 'cancelled'];
+/** Why a capture's coverage is partial. */
+export const TRACE_PARTIAL_REASONS = ['capture_failed', 'limit_reached', 'cancelled', 'driver_failed'];
+/** Root's bound on one segment's events. */
+export const TRACE_SEGMENT_MAX_EVENTS = 256;
+/** Root evidence caps per record and per assignment. */
+export const EVIDENCE_RECORD_MAX_BYTES = 262_144;
+export const EVIDENCE_MAX_RECORDS = 4_096;
+export const EVIDENCE_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+/** Root's limit on registered run services. */
+export const LOCAL_RUN_MAX_SERVICES = 128;
+/**
+ * Entry-service probe kind root requires per driver profile (execution-readiness.v1).
+ * Root defines no digest for the handshake kinds; the client's convention
+ * (readiness.ts) records what each driver actually observed.
+ */
+export const ENTRY_PROBE_KINDS = {
+    'http.v1': 'http', 'jsonl-process.v1': 'jsonl_handshake', 'function-wrapper.v1': 'function_import',
+    'playwright.v1': 'browser_document', 'signed-http-event.v1': 'signed_event_handshake',
+};
+/** execution-readiness.v1 list limits (root repairs its 100-item inspector cap for these lists; Slack 2026-11-10). */
+export const READINESS_MAX_SERVICES = 128;
+export const READINESS_MAX_RESETS = 256;
+/**
+ * Why root says the drill's input ended (target-actions page, 2026-11-10).
+ * Root derives it from the retained latest participant stop, the scenario's
+ * last turn once its reply completed, or the retained result of the scenario's
+ * task or event; never from an empty page or a score. An ending is not a pass.
+ * Root's frozen completion evidence decides coverage: a participant who gave
+ * up, a reached turn limit, a delivery-only event (the receiver answered; the
+ * work it started was not observed) or an unreached scheduled event is partial.
+ * `participant_unavailable` (reserved 2026-11-10) is root's own infrastructure
+ * ending: the simulated participant's next message was never generated, so the
+ * drill is incomplete and says nothing about the agent, pass or fail.
+ */
+export const ENDING_REASONS = ['participant_finished', 'participant_gave_up', 'turn_limit',
+    'inputs_exhausted', 'target_failed', 'target_cancelled', 'delivery_acknowledged', 'participant_unavailable'];
+/** Plain words for why root says a drill's input ended (never a result). */
+export const ENDING_TEXT = {
+    participant_finished: 'the participant finished',
+    participant_gave_up: 'the participant gave up',
+    turn_limit: 'the scenario reached its turn limit',
+    inputs_exhausted: 'every scenario input was delivered',
+    target_failed: 'the target reported a failure',
+    target_cancelled: 'the target reported a cancellation',
+    delivery_acknowledged: 'the receiver acknowledged the event; the work it started was not observed',
+    participant_unavailable: 'Firedrill could not generate the simulated participant\'s next message in time; the agent was not judged',
+};
+/** The only endings root can freeze as complete coverage (and only with no scheduled event left); every other ending is partial. */
+export const COMPLETE_ENDINGS = new Set(['participant_finished', 'inputs_exhausted']);
+/**
+ * Root `execution-close.v1` `client_summary.stop_reason` (2026-11-10): every input ending is a stop
+ * reason, `participant_unavailable` included (root's infrastructure ending, closed incomplete).
+ */
+export const STOP_REASONS = ['completed', 'user_cancelled', ...ENDING_REASONS, 'step_limit', 'deadline',
+    'driver_error', 'connection_lost', 'policy_denied'];
+/** Active schedule time in words, e.g. `1h 2m 3.5s` (root measures it; nothing is accelerated). */
+export function activeTime(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const fraction = ms % 1000 ? `.${String(ms % 1000).padStart(3, '0').replace(/0+$/, '')}` : '';
+    const rest = seconds % 60 || fraction || (!hours && !minutes) ? `${seconds % 60}${fraction}s` : '';
+    return [hours ? `${hours}h` : '', minutes ? `${minutes}m` : '', rest].filter(Boolean).join(' ');
+}
+// ---------------------------------------------------------------------------
+// Errors. Stable codes, no provider internals, no rejected values echoed.
+export const NATIVE_ERRORS = {
+    contract_pending: 'native_contract_pending',
+    plan_unapproved: 'native_plan_unapproved',
+    plan_changed: 'native_plan_changed',
+    root_outside: 'native_root_outside',
+    readiness_timeout: 'native_readiness_timeout',
+    process_exited: 'native_process_exited',
+    lease_expired: 'native_lease_expired',
+    stale_generation: 'native_stale_generation',
+    revoked: 'native_authorization_revoked',
+    disconnected: 'native_disconnected',
+    driver_unavailable: 'native_driver_unavailable',
+    binding_invalid: 'native_binding_invalid',
+    state_unsupported: 'native_state_unsupported',
+    budget_exhausted: 'native_budget_exhausted',
+    unknown_outcome: 'native_outcome_unknown',
+    credential_store_unavailable: 'credential_store_unavailable',
+    auth_unsupported: 'native_auth_unsupported',
+    identity_invalid: 'native_identity_invalid',
+    plan_invalid: 'native_plan_invalid',
+    root_invalid: 'native_root_invalid',
+    process_limit: 'native_process_limit',
+    process_start_failed: 'native_process_start_failed',
+    port_unavailable: 'native_port_unavailable',
+    assignment_invalid: 'native_assignment_invalid',
+    intent_missing: 'native_intent_missing',
+    companion_stopped: 'native_companion_stopped',
+    state_reset_failed: 'native_state_reset_failed',
+    step_report_failed: 'native_step_report_failed',
+    session_companion_required: 'session_companion_required',
+};
+export function nativeError(code, message, exitCode = 1) {
+    return new CliError(NATIVE_ERRORS[code], message, exitCode);
+}