firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/drivers/types.js

@@ -0,0 +1,578 @@
+/**
+ * Driver interfaces and shared driver primitives (Plan20 W10, spec section 3.3).
+ *
+ * A driver turns one cloud-originated AssignmentStep into a real interaction with
+ * the user's locally running target, through that target's real surface. Only
+ * `AssignmentStep.payload` is ever sent to the target: persona goals, judge
+ * criteria and other cloud-side context are not part of a step and never reach
+ * a driver.
+ *
+ * Observation channels (each observation is reported exactly once):
+ *  - Observations tied to a step are returned in `StepResult.observations`.
+ *  - Observations outside any step (session opened, process exited, late or
+ *    unsolicited target output, browser-context reset) go to `ctx.observe`.
+ * Both carry bounded, redacted content built by `boundedObservation`.
+ *
+ * Unknown-outcome rule: once any byte of a step may have reached the target and
+ * the response did not complete (timeout, cancel, dropped connection, oversized
+ * or malformed stream, process exit), a non-idempotent step is reported
+ * `unknown` with `native_outcome_unknown` and is never retried by a driver.
+ */
+import { constants as fsConstants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+import path from 'node:path';
+import { CliError } from '../../http.js';
+import { NATIVE_ERRORS, SHA256_HEX, SecretValue, nativeError } from '../contracts.js';
+import { redact, redactSecrets } from '../redaction.js';
+import { sha256Hex } from '../canonical.js';
+export const DEFAULT_DRIVER_BOUNDS = Object.freeze({
+    maxResponseBytes: 1024 * 1024,
+    maxLineBytes: 1024 * 1024,
+    maxStreamEvents: 10_000,
+    defaultStepMs: 60_000,
+    maxStepMs: 10 * 60_000,
+    flowSetupMs: 60_000,
+    maxObservationBytes: 64 * 1024,
+    maxStringChars: 16 * 1024,
+    maxItems: 200,
+    maxDepth: 8,
+    maxStepObservations: 256,
+    maxAttachmentBytes: 2 * 1024 * 1024,
+    maxScreenshotsPerSession: 64,
+    stderrTailBytes: 64 * 1024,
+    maxEventRetries: 3,
+    maxWrapperRelaunches: 3,
+    stopTimeoutMs: 5_000,
+});
+/** Driver-specific stable error codes (supplementing NATIVE_ERRORS). */
+export const DRIVER_ERRORS = {
+    not_loopback: 'native_target_not_loopback',
+    step_unsupported: 'native_step_unsupported',
+    step_timeout: 'native_step_timeout',
+    step_cancelled: 'native_step_cancelled',
+    intent_missing: 'native_intent_missing',
+    session_mismatch: 'native_session_mismatch',
+    session_closed: 'native_session_closed',
+    session_failed: 'native_session_failed',
+    target_status: 'native_target_status',
+    target_error: 'native_target_error',
+    target_unreachable: 'native_target_unreachable',
+    response_malformed: 'native_response_malformed',
+    response_oversized: 'native_response_oversized',
+    response_pointer_missing: 'native_response_pointer_missing',
+    event_invalid: 'native_event_invalid',
+    driver_plan_invalid: 'native_driver_plan_invalid',
+    readiness_unattested: 'native_readiness_unattested',
+};
+/** The driver cannot attest the entry service's readiness the way root requires; nothing is claimed instead. */
+export function unattested(message) {
+    return new CliError(DRIVER_ERRORS.readiness_unattested, message);
+}
+// ---------------------------------------------------------------------------
+// Context helpers.
+export function driverBounds(ctx) {
+    const merged = { ...DEFAULT_DRIVER_BOUNDS };
+    for (const [key, value] of Object.entries(ctx.bounds ?? {})) {
+        if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+            merged[key] = value;
+    }
+    return merged;
+}
+export function clockOf(ctx) {
+    return ctx.now ?? Date.now;
+}
+export function planError(message) {
+    return new CliError(DRIVER_ERRORS.driver_plan_invalid, message);
+}
+/** Narrow ctx.driver to the expected profile or refuse. */
+export function driverPlanFor(ctx, profile) {
+    if (ctx.driver.profile !== profile)
+        throw planError(`The approved plan does not select the ${profile} driver, so it was not prepared.`);
+    return ctx.driver;
+}
+export function rootPath(ctx, alias) {
+    const value = ctx.roots.get(alias);
+    if (!value || !path.isAbsolute(value))
+        throw nativeError('root_outside', `The approved plan root "${alias}" is not resolved, so no file was read from it.`);
+    return value;
+}
+export function serviceHandle(ctx, alias) {
+    const handle = ctx.services.get(alias);
+    if (!handle)
+        throw nativeError('driver_unavailable', `The approved service "${alias}" is not running under this companion, so the driver was not prepared.`);
+    return handle;
+}
+// ---------------------------------------------------------------------------
+// Redaction and bounding.
+export function clipText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, Math.max(0, maxChars))}[truncated:${text.length - maxChars} chars]`;
+}
+function clipUtf8(text, maxBytes) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    return `${bytes.subarray(0, Math.max(0, maxBytes)).toString('utf8')}[truncated:${bytes.byteLength - maxBytes} bytes]`;
+}
+const DIGEST_VALUE = /^[0-9a-f]{64}$/;
+/**
+ * A sha256 digest this client computed itself from bytes it holds (a pinned
+ * adapter, the approved masking policy, a delivered event body). Only such a
+ * value keeps its hex through `sanitize`: target-controlled data is plain
+ * parsed JSON and can never hold one, so a target's own `*_sha256` string is
+ * redacted like any other long hex.
+ */
+export class OwnDigest {
+    hex;
+    constructor(hex) { this.hex = hex; }
+    toJSON() { return DIGEST_VALUE.test(this.hex) ? this.hex : null; }
+}
+/**
+ * Convert any value to JSON-safe, redacted, bounded data. Strings (and object
+ * keys) are redacted before clipping so a clipped secret cannot survive.
+ * An `OwnDigest` keeps its hex (the long-hex token shape would erase the
+ * digest a reviewer compares), but an exact secret value is still removed.
+ */
+export function sanitize(value, secrets, bounds, changes) {
+    const changed = (value) => { if (changes)
+        changes.changed = true; return value; };
+    const walk = (current, depth) => {
+        if (current === null || typeof current === 'boolean')
+            return current;
+        if (current === undefined)
+            return changed(null);
+        if (typeof current === 'number')
+            return Number.isFinite(current) ? current : changed(null);
+        if (typeof current === 'string') {
+            const clean = clipText(redact(current, secrets), bounds.maxStringChars);
+            return clean === current ? clean : changed(clean);
+        }
+        if (current instanceof OwnDigest) {
+            if (!DIGEST_VALUE.test(current.hex))
+                return changed(null);
+            const clean = redactSecrets(current.hex, secrets);
+            return clean === current.hex ? clean : changed(clean);
+        }
+        if (typeof current === 'bigint')
+            return changed(clipText(current.toString(), 64));
+        if (current instanceof SecretValue)
+            return changed(current.toJSON());
+        if (current instanceof Uint8Array)
+            return changed({ omitted_bytes: current.byteLength });
+        if (current instanceof Date)
+            return changed(Number.isFinite(current.getTime()) ? current.toISOString() : null);
+        if (typeof current !== 'object')
+            return changed(null);
+        if (depth >= bounds.maxDepth)
+            return changed('[truncated:depth]');
+        if (Array.isArray(current)) {
+            const kept = current.slice(0, bounds.maxItems).map((item) => walk(item, depth + 1));
+            if (current.length > bounds.maxItems) {
+                changed(null);
+                kept.push(`[truncated:${current.length - bounds.maxItems} items]`);
+            }
+            return kept;
+        }
+        const output = {};
+        const entries = Object.entries(current);
+        for (const [key, item] of entries.slice(0, bounds.maxItems)) {
+            const cleanKey = clipText(redact(key, secrets), 256);
+            if (cleanKey !== key)
+                changed(null);
+            Object.defineProperty(output, cleanKey, { value: walk(item, depth + 1), enumerable: true, configurable: true });
+        }
+        if (entries.length > bounds.maxItems) {
+            changed(null);
+            output['[truncated]'] = `${entries.length - bounds.maxItems} keys`;
+        }
+        return output;
+    };
+    return walk(value, 0);
+}
+/** Sanitize, then enforce the serialized byte bound of one observation/output. */
+export function boundedValue(value, secrets, bounds, changes) {
+    const clean = sanitize(value, secrets, bounds, changes);
+    const json = JSON.stringify(clean) ?? 'null';
+    const size = Buffer.byteLength(json, 'utf8');
+    if (size <= bounds.maxObservationBytes)
+        return clean;
+    if (changes)
+        changes.changed = true;
+    return { truncated: true, original_bytes: size, preview: clipUtf8(json, Math.max(0, bounds.maxObservationBytes - 256)) };
+}
+export function boundedObservation(kind, atMs, content, secrets, bounds, attachment) {
+    const bounded = boundedValue(content, secrets, bounds);
+    const record = (bounded && typeof bounded === 'object' && !Array.isArray(bounded) ? bounded : { value: bounded });
+    const observation = { kind, at_ms: atMs, content: record };
+    if (attachment) {
+        if (attachment.bytes.byteLength <= bounds.maxAttachmentBytes && /^[a-z]+\/[a-z0-9.+-]+$/.test(attachment.media_type))
+            observation.attachment = { media_type: attachment.media_type, bytes: attachment.bytes };
+        else
+            record.attachment_omitted = { bytes: attachment.bytes.byteLength, reason: 'attachment exceeds the local bound' };
+    }
+    return observation;
+}
+/** Report an out-of-step observation through ctx.observe (bounded, redacted). */
+export function emit(ctx, kind, content, extraSecrets = []) {
+    const bounds = driverBounds(ctx);
+    try {
+        ctx.observe(boundedObservation(kind, clockOf(ctx)(), content, [...ctx.secrets, ...extraSecrets], bounds));
+    }
+    catch { /* an observation sink failure never changes target interaction */ }
+}
+/** Report an out-of-step sanitized action trace segment through ctx.observe (its own `state.observed` record). */
+export function emitTrace(ctx, segment) {
+    try {
+        ctx.observe({ kind: 'state.observed', at_ms: clockOf(ctx)(), content: {}, trace_segment: segment });
+    }
+    catch { /* an observation sink failure never changes target interaction */ }
+}
+/** Bounded, redacted text tail of a process stream. */
+/** Extra bytes kept beyond the visible tail so a secret straddling the cut is still redacted whole. */
+const TAIL_REDACTION_MARGIN = 8192;
+export class OutputTail {
+    chunks = [];
+    size = 0;
+    dropped = 0;
+    limit;
+    visible;
+    constructor(limit) { this.visible = Math.max(0, limit); this.limit = this.visible + TAIL_REDACTION_MARGIN; }
+    push(chunk) {
+        this.chunks.push(chunk);
+        this.size += chunk.byteLength;
+        while (this.size > this.limit && this.chunks.length) {
+            const head = this.chunks[0];
+            const excess = this.size - this.limit;
+            if (head.byteLength <= excess) {
+                this.chunks.shift();
+                this.size -= head.byteLength;
+                this.dropped += head.byteLength;
+            }
+            else {
+                this.chunks[0] = head.subarray(excess);
+                this.size -= excess;
+                this.dropped += excess;
+            }
+        }
+    }
+    text(secrets) {
+        // Redact everything kept (tail plus margin), then show only the visible tail.
+        const whole = redact(Buffer.concat(this.chunks).toString('utf8'), secrets);
+        const body = whole.length > this.visible ? whole.slice(whole.length - this.visible) : whole;
+        const hidden = this.dropped + Math.max(0, this.size - this.visible);
+        return hidden ? `[earlier output dropped:${hidden} bytes]${body}` : body;
+    }
+}
+/** Collects step-scoped observations and builds the StepResult. */
+export class StepRecorder {
+    step;
+    startedMs;
+    now;
+    secrets;
+    bounds;
+    items = [];
+    /** Trace segments cut during the step, held until its capture is recorded (see `recordTrace`). */
+    traces = [];
+    dropped = 0;
+    interruption = false;
+    constructor(ctx, step, extraSecrets = []) {
+        this.step = step;
+        this.now = clockOf(ctx);
+        this.startedMs = this.now();
+        this.secrets = [...ctx.secrets, ...extraSecrets];
+        this.bounds = driverBounds(ctx);
+    }
+    record(kind, content, attachment, capture) {
+        if (this.items.length + this.traces.length >= this.bounds.maxStepObservations) {
+            this.dropped += 1;
+            return;
+        }
+        const observation = boundedObservation(kind, this.now(), { step_id: this.step.step_id, ...content }, this.secrets, this.bounds, attachment);
+        // An approved capture's result travels beside the observation that captured it (never inside its content).
+        if (capture && kind === 'action.observed')
+            observation.capture = { ...capture, step_id: this.step.step_id };
+        this.items.push(observation);
+        if (observation.capture)
+            this.flushTraces();
+    }
+    /**
+     * A sanitized action trace segment cut during this step, as its own record.
+     * It is held and queued after the step's capture (or at the step's end): the
+     * capture's interval frames were taken earlier than a segment cut mid-step,
+     * and elapsed time never goes back, so recording the segment first would move
+     * those frames to the cut time. The segment's own times are unchanged; its
+     * record is simply made later. Returns false when the step's observation bound
+     * dropped it.
+     */
+    recordTrace(segment) {
+        if (this.items.length + this.traces.length >= this.bounds.maxStepObservations) {
+            this.dropped += 1;
+            return false;
+        }
+        this.traces.push(segment);
+        return true;
+    }
+    flushTraces() {
+        for (const segment of this.traces.splice(0))
+            this.items.push({ kind: 'state.observed', at_ms: this.now(), content: {}, trace_segment: segment });
+    }
+    /**
+     * Record, once, that the step was interrupted, with the approved capture taken
+     * before it stopped. A driver calls it ahead of its own cleanup records so a
+     * capture's frames keep their times; `interrupted()` then adds nothing more.
+     */
+    noteInterrupted(cause, written, capture) {
+        if (this.interruption)
+            return;
+        this.interruption = true;
+        this.record('action.observed', { type: 'step.interrupted', cause, request_written: written }, undefined, capture);
+    }
+    /**
+     * `delivered`: the input reached the target (a request was written or the target answered).
+     * By default a completed step or one with the target's own output did; a refusal or an
+     * undelivered input carries no output and did not.
+     */
+    finish(outcome, output, errorCode, delivered = outcome === 'completed' || (output !== null && output !== undefined)) {
+        const changes = { changed: false };
+        const retainedOutput = boundedValue(output, this.secrets, this.bounds, changes);
+        this.flushTraces();
+        if (this.dropped)
+            this.items.push(boundedObservation('action.observed', this.now(), { step_id: this.step.step_id, type: 'observations.truncated', dropped: this.dropped }, this.secrets, this.bounds));
+        const kind = outcome === 'completed' ? 'driver.completed' : outcome === 'cancelled' ? 'driver.cancelled' : 'driver.failed';
+        this.items.push(boundedObservation(kind, this.now(), { step_id: this.step.step_id, outcome, error_code: errorCode }, this.secrets, this.bounds));
+        return {
+            step_id: this.step.step_id, intent_id: this.step.intent_id, outcome,
+            started_ms: this.startedMs, finished_ms: this.now(),
+            output: retainedOutput, output_coverage: changes.changed ? 'redacted' : 'complete',
+            error_code: errorCode, observations: this.items, delivered,
+        };
+    }
+    /** Interrupted step: applies the unknown-outcome rule. */
+    interrupted(cause, written, options = {}) {
+        const { outcome, error_code } = interruptedOutcome(this.step, written, cause, options);
+        this.noteInterrupted(cause, written);
+        return this.finish(outcome, null, error_code, written);
+    }
+}
+const CAUSE_CODES = {
+    timeout: DRIVER_ERRORS.step_timeout,
+    cancelled: DRIVER_ERRORS.step_cancelled,
+    dropped: DRIVER_ERRORS.target_unreachable,
+    oversized: DRIVER_ERRORS.response_oversized,
+    malformed: DRIVER_ERRORS.response_malformed,
+    refused: DRIVER_ERRORS.target_unreachable,
+    unreachable: DRIVER_ERRORS.target_unreachable,
+    exited: NATIVE_ERRORS.process_exited,
+    thrown: DRIVER_ERRORS.target_error,
+};
+/**
+ * Unknown-outcome rule. Nothing written: cancelled or failed. Written and the
+ * response incomplete: non-idempotent (or `unknownAfterWrite`) => unknown, never
+ * retried; idempotent => cancelled/failed with the specific cause code.
+ */
+export function interruptedOutcome(step, written, cause, options = {}) {
+    if (written && (!step.idempotent || options.unknownAfterWrite))
+        return { outcome: 'unknown', error_code: NATIVE_ERRORS.unknown_outcome };
+    if (cause === 'cancelled')
+        return { outcome: 'cancelled', error_code: CAUSE_CODES.cancelled };
+    return { outcome: 'failed', error_code: CAUSE_CODES[cause] };
+}
+/** Pre-invocation checks shared by all drivers. Returns an error code or null. */
+export function precheck(step, sessionKey, kinds) {
+    if (!step.idempotent && !step.intent_id)
+        return DRIVER_ERRORS.intent_missing;
+    if (!kinds.includes(step.kind) || step.payload.kind !== step.kind)
+        return DRIVER_ERRORS.step_unsupported;
+    if (step.payload.kind !== 'event' && step.payload.session_key !== sessionKey)
+        return DRIVER_ERRORS.session_mismatch;
+    return null;
+}
+/**
+ * Step timeout in milliseconds. `deadline_ms` is treated as a relative duration
+ * from invocation (pending root contract), capped by `maxStepMs`.
+ */
+export function stepTimeoutMs(step, bounds) {
+    const value = step.deadline_ms;
+    if (Number.isSafeInteger(value) && value > 0)
+        return Math.min(value, bounds.maxStepMs);
+    return Math.min(bounds.defaultStepMs, bounds.maxStepMs);
+}
+/** One abort signal for a step: step timeout, caller cancel and drill cancel. */
+export function stepAbort(ctx, signal, timeoutMs) {
+    const controller = new AbortController();
+    const state = { cause: null };
+    const fire = (cause) => { if (state.cause)
+        return; state.cause = cause; controller.abort(); };
+    const timer = setTimeout(() => fire('timeout'), timeoutMs);
+    // The runner aborts with a TimeoutError reason when the step budget, lease or
+    // elapsed budget runs out; that is a timeout, not a cancellation.
+    const onCancel = () => {
+        const reasons = [signal.reason, ctx.signal.reason];
+        fire(reasons.some((reason) => reason instanceof Error && reason.name === 'TimeoutError') ? 'timeout' : 'cancelled');
+    };
+    const sources = [signal, ctx.signal];
+    for (const source of sources) {
+        if (source.aborted)
+            onCancel();
+        else
+            source.addEventListener('abort', onCancel, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        cause: () => state.cause,
+        dispose() { clearTimeout(timer); for (const source of sources)
+            source.removeEventListener('abort', onCancel); },
+    };
+}
+/** Resolve when `ms` passes, or reject (with no value) when the signal aborts. */
+export function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error('aborted'));
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+// ---------------------------------------------------------------------------
+// Loopback targets.
+export function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (host === 'localhost')
+        return true;
+    if (isIP(host) === 4)
+        return host.startsWith('127.');
+    if (isIP(host) === 6)
+        return host === '::1' || host === '0:0:0:0:0:0:0:1';
+    return false;
+}
+/** Parse a service URL and require plain loopback http without credentials. */
+export function loopbackBase(raw, alias) {
+    let url;
+    try {
+        url = new URL(raw ?? '');
+    }
+    catch {
+        throw new CliError(DRIVER_ERRORS.not_loopback, `The approved service "${alias}" has no usable local URL, so no request was sent.`);
+    }
+    if (url.protocol !== 'http:' || !isLoopbackHost(url.hostname) || url.username || url.password || url.hash)
+        throw new CliError(DRIVER_ERRORS.not_loopback, `The approved service "${alias}" is not a plain loopback HTTP address, so no request was sent.`);
+    return url;
+}
+/** Join an approved path onto a loopback base; the origin must not change. */
+export function loopbackTarget(base, relative, alias) {
+    if (!relative.startsWith('/') || relative.startsWith('//') || /[\\\r\n#\0]/.test(relative))
+        throw planError(`The approved path for "${alias}" must be an absolute path on the same local service; no request was sent.`);
+    const target = new URL(relative, base);
+    if (target.origin !== base.origin)
+        throw new CliError(DRIVER_ERRORS.not_loopback, `The approved path for "${alias}" leaves the local service, so no request was sent.`);
+    return target;
+}
+/**
+ * Resolve the connect address for a loopback URL. Names resolve only to loopback
+ * addresses (a hostname mapped elsewhere is refused before connecting).
+ */
+export async function resolveLoopback(url) {
+    const name = url.hostname.replace(/^\[|\]$/g, '');
+    const port = url.port ? Number(url.port) : 80;
+    let host = name;
+    if (!isIP(name)) {
+        let addresses = [];
+        try {
+            addresses = await lookup(name, { all: true });
+        }
+        catch {
+            addresses = [];
+        }
+        const loopback = addresses.find((entry) => isLoopbackHost(entry.address));
+        if (!loopback)
+            throw new CliError(DRIVER_ERRORS.not_loopback, 'The local service name does not resolve to a loopback address, so no request was sent.');
+        host = loopback.address;
+    }
+    if (!isLoopbackHost(host))
+        throw new CliError(DRIVER_ERRORS.not_loopback, 'The local service address is not loopback, so no request was sent.');
+    return { host, port, hostHeader: url.host };
+}
+// ---------------------------------------------------------------------------
+// Headers.
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
+export function validHeaderName(name) { return HEADER_NAME.test(name); }
+/** Exactly the bytes Node's HTTP client accepts in a header value, so validation fails before any byte is sent. */
+export function validHeaderValue(value) { return typeof value === 'string' && value.length <= 8192 && /^[\t\x20-\x7e\x80-\xff]*$/.test(value); }
+// ---------------------------------------------------------------------------
+// Approved adapter files (resolve paths with roots.ts insideRoot first).
+/**
+ * Read a regular file and require its sha256 to equal the approved digest.
+ * A mismatch voids approval (`native_plan_changed`); the file is not used.
+ */
+export async function readPinned(file, expectedSha256, maxBytes = 8 * 1024 * 1024) {
+    if (!SHA256_HEX.test(expectedSha256))
+        throw nativeError('plan_changed', 'The approved adapter digest is missing or malformed, so the adapter was not loaded or run.');
+    const nofollow = fsConstants.O_NOFOLLOW ?? 0;
+    let handle = null;
+    try {
+        handle = await open(file, fsConstants.O_RDONLY | nofollow);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            throw new Error('unsupported');
+        const bytes = await handle.readFile();
+        const sha256 = sha256Hex(bytes);
+        if (sha256 !== expectedSha256)
+            throw nativeError('plan_changed', 'The approved adapter file changed since approval, so it was not loaded or run.');
+        return { bytes, sha256 };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw nativeError('plan_changed', 'The approved adapter file could not be read as a regular file, so it was not loaded or run.');
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON pointer (RFC 6901).
+export function parsePointer(pointer) {
+    if (pointer === null)
+        return null;
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/') || /~[^01]|~$/.test(pointer))
+        throw planError('The approved response pointer is not a valid JSON pointer, so the driver was not prepared.');
+    return pointer.slice(1).split('/').map((token) => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+/** Returns undefined when the pointer does not resolve. */
+export function readPointer(document, tokens) {
+    let current = document;
+    for (const token of tokens) {
+        if (Array.isArray(current)) {
+            if (!/^(0|[1-9][0-9]*)$/.test(token))
+                return undefined;
+            const index = Number(token);
+            if (index >= current.length)
+                return undefined;
+            current = current[index];
+        }
+        else if (current && typeof current === 'object') {
+            if (!Object.prototype.hasOwnProperty.call(current, token))
+                return undefined;
+            current = current[token];
+        }
+        else
+            return undefined;
+    }
+    return current;
+}
+/** Target-visible step input only (never anything beyond payload). */
+export function stepInput(step) {
+    if (step.payload.kind === 'message')
+        return { kind: 'message', input: step.payload.text };
+    if (step.payload.kind === 'task')
+        return { kind: 'task', input: step.payload.input };
+    return null;
+}