firedrill-run 2.2.5 → 3.0.0

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

@@ -0,0 +1,442 @@
+/**
+ * http.v1 driver (Plan20 spec 3.3).
+ *
+ * Sends each message/task step to the approved service's loopback URL (from the
+ * supervisor's ServiceHandle) at the plan's path with POST or PUT:
+ *  - `message-text` template: `{"message": <text>, "session": <session key>}`
+ *  - `task-json` template: the task input itself as JSON.
+ * The session key goes into `session_header` when the plan names one. A
+ * synthetic session token from the identity grant goes into the grant's header
+ * (target-auth.ts `identityHeaders`); login flows are handled by target-auth.
+ *
+ * Responses are read with byte and time bounds. `sse` and `ndjson` streams are
+ * parsed incrementally; `response_pointer` (RFC 6901) extracts the reply from the
+ * JSON body or from each stream event (string pieces are concatenated).
+ *
+ * Requests use node:http directly (no redirects followed, no proxy, no pooling)
+ * so the driver knows whether any byte may have reached the target: a connection
+ * is treated as "written" from the moment it is established. The primitive
+ * `loopbackRequest` is shared with the signed-http-event driver.
+ */
+import { request as httpRequest } from 'node:http';
+import { CliError } from '../../http.js';
+import { redact } from '../redaction.js';
+import { identityHeaders } from '../target-auth.js';
+import { DRIVER_ERRORS, StepRecorder, clipText, driverBounds, driverPlanFor, emit, loopbackBase, loopbackTarget, parsePointer, planError, precheck, readPointer, resolveLoopback, serviceHandle, stepAbort, stepInput, stepTimeoutMs, unattested, validHeaderName, validHeaderValue, } from './types.js';
+/** A request that did not produce a complete response. `written` is conservative. */
+export class LoopbackFailure extends Error {
+    kind;
+    written;
+    status;
+    constructor(kind, written, status) {
+        super(`The local request did not complete (${kind}).`);
+        this.kind = kind;
+        this.written = written;
+        this.status = status;
+    }
+}
+/** Thrown by a stream consumer to stop reading. */
+export class StreamFault extends Error {
+    kind;
+    constructor(kind) { super(`The response stream was ${kind}.`); this.kind = kind; }
+}
+/**
+ * One HTTP request to a loopback address. Resolves only on a complete response.
+ * Rejects with LoopbackFailure otherwise (CliError before connecting when the
+ * address is not loopback). `refused` is reported only when the connection was
+ * refused before it was established, i.e. no byte was sent.
+ */
+export async function loopbackRequest(options) {
+    if (options.signal.aborted)
+        throw new LoopbackFailure('aborted', false, null);
+    const target = await resolveLoopback(options.url);
+    if (options.signal.aborted)
+        throw new LoopbackFailure('aborted', false, null);
+    return await new Promise((resolve, reject) => {
+        const state = { written: false, settled: false, status: null };
+        const chunks = [];
+        let size = 0;
+        const onAbort = () => fail('aborted');
+        const cleanup = () => options.signal.removeEventListener('abort', onAbort);
+        const fail = (kind) => {
+            if (state.settled)
+                return;
+            state.settled = true;
+            cleanup();
+            request.destroy();
+            reject(new LoopbackFailure(kind, state.written, state.status));
+        };
+        const request = httpRequest({
+            host: target.host, port: target.port, method: options.method,
+            path: `${options.url.pathname}${options.url.search}`,
+            headers: { ...options.headers, host: target.hostHeader, 'content-length': String(options.body.byteLength) },
+            agent: false,
+        });
+        options.signal.addEventListener('abort', onAbort, { once: true });
+        request.on('socket', (socket) => {
+            if (socket.connecting)
+                socket.once('connect', () => { state.written = true; });
+            else
+                state.written = true;
+        });
+        request.on('error', (error) => {
+            fail(state.written ? 'dropped' : error.code === 'ECONNREFUSED' ? 'refused' : 'unreachable');
+        });
+        request.on('response', (response) => {
+            state.written = true;
+            state.status = response.statusCode ?? 0;
+            const streaming = !!options.onChunk && state.status >= 200 && state.status < 300;
+            response.on('data', (chunk) => {
+                if (state.settled)
+                    return;
+                size += chunk.byteLength;
+                if (size > options.maxBytes) {
+                    fail('oversized');
+                    return;
+                }
+                if (!streaming) {
+                    chunks.push(chunk);
+                    return;
+                }
+                try {
+                    options.onChunk(chunk);
+                }
+                catch (error) {
+                    fail(error instanceof StreamFault ? error.kind : 'malformed');
+                }
+            });
+            response.on('end', () => {
+                if (state.settled)
+                    return;
+                state.settled = true;
+                cleanup();
+                resolve({ status: state.status ?? 0, headers: response.headers, body: Buffer.concat(chunks), streamed: streaming, bytes: size });
+            });
+            response.on('error', () => fail('dropped'));
+            response.on('close', () => { if (!response.complete)
+                fail('dropped'); });
+        });
+        request.end(Buffer.from(options.body.buffer, options.body.byteOffset, options.body.byteLength));
+    });
+}
+export function failureCause(failure, abortCause) {
+    return failure.kind === 'aborted' ? (abortCause ?? 'cancelled') : failure.kind;
+}
+// ---------------------------------------------------------------------------
+// Incremental stream parsing (SSE / NDJSON).
+export class StreamCollector {
+    mode;
+    pointer;
+    bounds;
+    decoder = new TextDecoder('utf-8');
+    line = '';
+    skipLineFeed = false;
+    dataLines = [];
+    pieces = [];
+    count = 0;
+    constructor(mode, pointer, bounds) {
+        this.mode = mode;
+        this.pointer = pointer;
+        this.bounds = bounds;
+    }
+    push(chunk) { this.consume(this.decoder.decode(chunk, { stream: true })); }
+    /**
+     * Flush the trailing line/event and return the extracted reply. With a
+     * `response_pointer` that no event held, the stream is malformed, exactly like
+     * a JSON body without it: never a completed step with no reply.
+     */
+    finish() {
+        this.consume(this.decoder.decode());
+        if (this.line) {
+            const last = this.line;
+            this.line = '';
+            this.handleLine(last);
+        }
+        if (this.mode === 'sse')
+            this.dispatch();
+        if (this.pointer && !this.pieces.length)
+            throw new StreamFault('malformed');
+        return this.output();
+    }
+    /** Reply assembled so far (used as evidence when a stream is interrupted). */
+    output() {
+        if (!this.pieces.length)
+            return null;
+        if (this.pieces.every((piece) => typeof piece === 'string'))
+            return this.pieces.join('');
+        return this.pieces.length === 1 ? this.pieces[0] : [...this.pieces];
+    }
+    consume(text) {
+        let start = 0;
+        if (this.skipLineFeed && text.charCodeAt(0) === 10)
+            start = 1;
+        this.skipLineFeed = false;
+        for (let index = start; index < text.length; index += 1) {
+            const code = text.charCodeAt(index);
+            if (code !== 10 && code !== 13)
+                continue;
+            const line = this.line + text.slice(start, index);
+            this.line = '';
+            if (code === 13) {
+                if (index + 1 < text.length && text.charCodeAt(index + 1) === 10)
+                    index += 1;
+                else if (index + 1 === text.length)
+                    this.skipLineFeed = true;
+            }
+            start = index + 1;
+            this.handleLine(line);
+        }
+        this.line += text.slice(start);
+        if (Buffer.byteLength(this.line, 'utf8') > this.bounds.maxLineBytes)
+            throw new StreamFault('oversized');
+    }
+    handleLine(line) {
+        if (this.mode === 'ndjson') {
+            const trimmed = line.trim();
+            if (trimmed)
+                this.addPiece(trimmed, true);
+            return;
+        }
+        if (line === '') {
+            this.dispatch();
+            return;
+        }
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'data')
+            this.dataLines.push(value);
+    }
+    dispatch() {
+        if (!this.dataLines.length)
+            return;
+        const data = this.dataLines.join('\n');
+        this.dataLines = [];
+        if (data === '[DONE]')
+            return;
+        this.addPiece(data, false);
+    }
+    addPiece(raw, jsonRequired) {
+        this.count += 1;
+        if (this.count > this.bounds.maxStreamEvents)
+            throw new StreamFault('oversized');
+        let document;
+        let parsed = false;
+        try {
+            document = JSON.parse(raw);
+            parsed = true;
+        }
+        catch {
+            parsed = false;
+        }
+        if (!parsed && (jsonRequired || this.pointer))
+            throw new StreamFault('malformed');
+        if (this.pointer) {
+            const value = readPointer(document, this.pointer);
+            if (value !== undefined)
+                this.pieces.push(value);
+            return;
+        }
+        this.pieces.push(parsed ? document : raw);
+    }
+}
+function parseBody(body, pointer) {
+    const text = body.toString('utf8');
+    let document;
+    try {
+        document = text ? JSON.parse(text) : null;
+    }
+    catch {
+        if (pointer)
+            return { ok: false, code: DRIVER_ERRORS.response_malformed };
+        return { ok: true, value: text };
+    }
+    if (!pointer)
+        return { ok: true, value: document };
+    const value = readPointer(document, pointer);
+    return value === undefined ? { ok: false, code: DRIVER_ERRORS.response_pointer_missing } : { ok: true, value };
+}
+/**
+ * Redact the whole (already size-bounded) body before clipping, so a secret
+ * that straddles the clip point is never left half-visible.
+ */
+export function bodyPreview(body, secrets, maxChars = 4096) {
+    return clipText(redact(body.toString('utf8'), secrets), maxChars);
+}
+const RESERVED_HEADERS = new Set(['host', 'content-length', 'content-type', 'accept', 'transfer-encoding', 'connection']);
+export class HttpDriver {
+    profile = 'http.v1';
+    prepared = null;
+    sessions = new Set();
+    async describe() {
+        return { available: true, reason: null };
+    }
+    async prepare(ctx) {
+        const plan = driverPlanFor(ctx, 'http.v1');
+        if (plan.method !== 'POST' && plan.method !== 'PUT')
+            throw planError('The approved HTTP method is not POST or PUT, so the driver was not prepared.');
+        if (plan.stream !== 'none' && plan.stream !== 'sse' && plan.stream !== 'ndjson')
+            throw planError('The approved stream mode is not supported, so the driver was not prepared.');
+        if (plan.request_template !== 'message-text' && plan.request_template !== 'task-json')
+            throw planError('The approved request template is not supported, so the driver was not prepared.');
+        if (plan.session_header !== null && (!validHeaderName(plan.session_header) || RESERVED_HEADERS.has(plan.session_header.toLowerCase())))
+            throw planError('The approved session header name is not allowed, so the driver was not prepared.');
+        const handle = serviceHandle(ctx, plan.service_alias);
+        const target = loopbackTarget(loopbackBase(handle.url, plan.service_alias), plan.path, plan.service_alias);
+        const pointer = parsePointer(plan.response_pointer);
+        for (const name of Object.keys(identityHeaders(ctx.identity))) {
+            const lower = name.toLowerCase();
+            if (RESERVED_HEADERS.has(lower) || (plan.session_header && lower === plan.session_header.toLowerCase()))
+                throw planError('The identity header collides with a header the driver sets, so the driver was not prepared.');
+        }
+        this.prepared = { plan, target, pointer };
+    }
+    async openSession(ctx, sessionKey) {
+        if (!this.prepared)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The HTTP driver was not prepared, so no session was opened.');
+        if (!sessionKey || !validHeaderValue(sessionKey) || sessionKey.length > 256)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The session key cannot be sent to the target, so no session was opened.');
+        const session = new HttpSession(ctx, this.prepared, sessionKey, () => this.sessions.delete(session));
+        this.sessions.add(session);
+        emit(ctx, 'action.observed', { type: 'session.opened', profile: this.profile, session_key: sessionKey });
+        return session;
+    }
+    /** The 2xx status the entry service's approved HTTP readiness check accepted. */
+    async readinessProbe(ctx) {
+        const plan = driverPlanFor(ctx, 'http.v1');
+        const ready = serviceHandle(ctx, plan.service_alias).ready();
+        if (ready?.kind !== 'http' || ready.status_code < 200 || ready.status_code > 299) {
+            throw unattested(`The HTTP target "${plan.service_alias}" needs an approved HTTP readiness check that answered 2xx before the service can admit the drill. Nothing was claimed.`);
+        }
+        return { kind: 'http', status_code: ready.status_code };
+    }
+    async dispose() {
+        for (const session of [...this.sessions])
+            await session.close();
+        this.prepared = null;
+    }
+}
+class HttpSession {
+    sessionKey;
+    ctx;
+    prepared;
+    onClose;
+    closed = false;
+    constructor(ctx, prepared, sessionKey, onClose) {
+        this.ctx = ctx;
+        this.prepared = prepared;
+        this.sessionKey = sessionKey;
+        this.onClose = onClose;
+    }
+    async invoke(step, signal) {
+        const { ctx } = this;
+        const { plan, target, pointer } = this.prepared;
+        const bounds = driverBounds(ctx);
+        const recorder = new StepRecorder(ctx, step);
+        if (this.closed)
+            return recorder.finish('failed', null, DRIVER_ERRORS.session_closed);
+        const refused = precheck(step, this.sessionKey, ['message', 'task']);
+        if (refused)
+            return recorder.finish('failed', null, refused);
+        const input = stepInput(step);
+        let text;
+        if (plan.request_template === 'message-text') {
+            if (typeof input.input !== 'string')
+                return recorder.finish('failed', null, DRIVER_ERRORS.step_unsupported);
+            text = JSON.stringify({ message: input.input, session: this.sessionKey });
+        }
+        else {
+            if (input.kind !== 'task')
+                return recorder.finish('failed', null, DRIVER_ERRORS.step_unsupported);
+            try {
+                text = JSON.stringify(input.input);
+            }
+            catch {
+                text = undefined;
+            }
+            if (text === undefined)
+                return recorder.finish('failed', null, DRIVER_ERRORS.step_unsupported);
+        }
+        const body = Buffer.from(text, 'utf8');
+        let headers;
+        try {
+            headers = {
+                'content-type': 'application/json',
+                accept: plan.stream === 'sse' ? 'text/event-stream' : plan.stream === 'ndjson' ? 'application/x-ndjson' : 'application/json',
+                ...identityHeaders(ctx.identity),
+            };
+        }
+        catch (error) {
+            return recorder.finish('failed', null, error instanceof CliError ? error.code : DRIVER_ERRORS.session_failed);
+        }
+        if (plan.session_header)
+            headers[plan.session_header] = this.sessionKey;
+        recorder.record('action.observed', { type: 'target.exchange',
+            direction: 'to_target', kind: input.kind, session_key: this.sessionKey, method: plan.method, path: target.pathname, content: input.input,
+        });
+        const collector = plan.stream === 'none' ? null : new StreamCollector(plan.stream, pointer, bounds);
+        const abort = stepAbort(ctx, signal, stepTimeoutMs(step, bounds));
+        try {
+            const response = await loopbackRequest({
+                url: target, method: plan.method, headers, body, signal: abort.signal, maxBytes: bounds.maxResponseBytes,
+                onChunk: collector ? (chunk) => collector.push(chunk) : undefined,
+            });
+            if (response.status < 200 || response.status > 299) {
+                recorder.record('action.observed', { type: 'target.exchange', direction: 'from_target', status: response.status, body_preview: bodyPreview(response.body, ctx.secrets) });
+                return recorder.finish('failed', { status: response.status }, DRIVER_ERRORS.target_status);
+            }
+            let output;
+            if (collector) {
+                try {
+                    output = collector.finish();
+                }
+                catch {
+                    recorder.record('action.observed', { type: 'target.exchange', direction: 'from_target', status: response.status, partial: collector.output(), events: collector.count });
+                    // The target accepted the request (2xx), so its effect may have happened:
+                    // a non-idempotent step is unknown, never a clean failure.
+                    return recorder.interrupted('malformed', true);
+                }
+            }
+            else {
+                const parsed = parseBody(response.body, pointer);
+                if (!parsed.ok) {
+                    recorder.record('action.observed', { type: 'target.exchange', direction: 'from_target', status: response.status, body_preview: bodyPreview(response.body, ctx.secrets) });
+                    // Accepted (2xx) but unusable: the effect may have happened, so a
+                    // non-idempotent step is unknown rather than failed.
+                    return recorder.interrupted('malformed', true);
+                }
+                output = parsed.value;
+            }
+            recorder.record('action.observed', { type: 'target.exchange',
+                direction: 'from_target', status: response.status, content: output, bytes: response.bytes,
+                ...(collector ? { events: collector.count } : {}),
+            });
+            return recorder.finish('completed', output, null);
+        }
+        catch (error) {
+            if (error instanceof LoopbackFailure) {
+                if (collector)
+                    recorder.record('action.observed', { type: 'target.exchange', direction: 'from_target', partial: collector.output(), events: collector.count, status: error.status });
+                return recorder.interrupted(failureCause(error, abort.cause()), error.written);
+            }
+            // Refused before connecting (not loopback / unresolvable): nothing was written.
+            if (error instanceof CliError)
+                return recorder.finish('failed', null, error.code);
+            // Anything else: treat conservatively as possibly written.
+            return recorder.interrupted('thrown', true);
+        }
+        finally {
+            abort.dispose();
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onClose();
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Driver registry and capability detection (Plan20 spec 3.3).
+ *
+ * `driverFor(profile)` returns a NEW driver instance on every call; a drill gets
+ * its own instance (and so its own driver-owned process or browser).
+ * `detectCapabilities(plan)` reports every supported profile with availability.
+ * Desktop, audio/voice and arbitrary queue interfaces are not driver profiles
+ * and are not listed; an unknown profile is refused with
+ * `native_driver_unavailable`.
+ */
+import { DRIVER_PROFILES, nativeError } from '../contracts.js';
+import { FunctionWrapperDriver } from './function-wrapper.js';
+import { HttpDriver } from './http.js';
+import { JsonlProcessDriver } from './jsonl-process.js';
+import { PlaywrightDriver } from './playwright.js';
+import { SignedEventDriver } from './signed-event.js';
+export { DEFAULT_DRIVER_BOUNDS, DRIVER_ERRORS } from './types.js';
+export { DELIVERY_ID_HEADER } from './signed-event.js';
+export function driverFor(profile, options = {}) {
+    switch (profile) {
+        case 'http.v1': return new HttpDriver();
+        case 'jsonl-process.v1': return new JsonlProcessDriver();
+        case 'function-wrapper.v1': return new FunctionWrapperDriver();
+        case 'playwright.v1': return new PlaywrightDriver({ plan: options.plan ?? null });
+        case 'signed-http-event.v1': return new SignedEventDriver();
+        default:
+            throw nativeError('driver_unavailable', 'The requested driver profile is not supported by this client, so no driver was prepared.');
+    }
+}
+/**
+ * Availability of every supported driver profile on this machine. A profile
+ * whose describe() fails is reported unavailable with a reason; nothing is
+ * started, installed or probed over the network.
+ */
+export async function detectCapabilities(plan) {
+    const report = [];
+    for (const profile of DRIVER_PROFILES) {
+        try {
+            const { available, reason } = await driverFor(profile, { plan }).describe();
+            report.push({ profile, available, reason: available ? null : reason ?? 'This driver is not available on this machine.' });
+        }
+        catch {
+            report.push({ profile, available: false, reason: 'This driver could not report its availability on this machine.' });
+        }
+    }
+    return report;
+}