cueline 0.1.6 → 0.2.0

package/dist/src/observation/run-status-at.js

@@ -0,0 +1,65 @@
+import { CueLineError } from "../core/errors.js";
+import { loadPersistedRunStore } from "../core/persisted-run.js";
+import { initialRunState, reduceRunState } from "../core/state-machine.js";
+import { readEvents } from "../state/event-log.js";
+import { defaultCueLineHome, runPaths } from "../state/paths.js";
+import { readAuthoritativeRunEvents } from "../state/store.js";
+export async function loadCueLineRunStatusAt(runId, options) {
+    if (!Number.isSafeInteger(options.sequence) || options.sequence < 1) {
+        throw new CueLineError("RUN_STATUS_AT_SEQUENCE_INVALID", "Historical status requires a positive safe event sequence.");
+    }
+    const environment = options.environment ?? process.env;
+    const home = options.home ?? defaultCueLineHome(environment);
+    await loadPersistedRunStore(home, runId);
+    const [events, authoritativeEvents] = await Promise.all([
+        readEvents(runPaths(home, runId).events),
+        readAuthoritativeRunEvents(home, runId),
+    ]);
+    const latestSequence = events.at(-1)?.sequence ?? 0;
+    if (options.sequence > latestSequence) {
+        throw new CueLineError("RUN_STATUS_AT_SEQUENCE_AHEAD", `Run '${runId}' is at event ${latestSequence}, behind requested sequence ${options.sequence}.`);
+    }
+    const eventAt = events.find((event) => event.sequence === options.sequence);
+    if (eventAt === undefined) {
+        throw new CueLineError("RUN_STATUS_AT_SEQUENCE_MISSING", `Run '${runId}' has no durable event at sequence ${options.sequence}.`);
+    }
+    const applied = authoritativeEvents.filter((event) => event.sequence <= options.sequence);
+    let state = initialRunState(runId, "");
+    for (const event of applied)
+        state = reduceRunState(state, event);
+    const counts = {};
+    for (const job of Object.values(state.jobs)) {
+        counts[job.status] = (counts[job.status] ?? 0) + 1;
+    }
+    return {
+        schema: "cueline-status-at/0.1",
+        runId,
+        requestedSequence: options.sequence,
+        latestSequence,
+        latestAuthoritativeSequence: authoritativeEvents.at(-1)?.sequence ?? 0,
+        totalEvents: events.length,
+        authoritativeEvents: authoritativeEvents.length,
+        authoritativeEventsApplied: applied.length,
+        ignoredNonAuthoritativeEventsThroughSequence: events.filter((event) => event.sequence <= options.sequence).length - applied.length,
+        asOf: { type: eventAt.type, timestamp: eventAt.timestamp },
+        state: {
+            status: state.status,
+            executor: state.executor,
+            allowProcessExecution: state.allowProcessExecution,
+            round: state.round,
+            maxRounds: state.maxRounds,
+            conversationBound: state.conversationUrl !== null,
+            pendingControllerTurns: state.pendingControllerTurns.length,
+            abandonedControllerTurns: state.abandonedControllerTurns.length,
+            acceptedCommands: state.commandHashes.length,
+            pendingCommandExecution: state.pendingCommandExecution !== null,
+            jobs: { total: Object.keys(state.jobs).length, counts },
+            archiveStatus: state.controllerConversationArchive.status,
+            finalDeliveryAvailable: state.finalDeliveryText !== null,
+            blockedReasonAvailable: state.blockedReason !== null,
+            cancelledReasonAvailable: state.cancelledReason !== null,
+            lastFailureCode: state.lastFailure?.code ?? null,
+        },
+    };
+}
+//# sourceMappingURL=run-status-at.js.map

package/dist/src/observation/run-status-at.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-status-at.js","sourceRoot":"","sources":["../../../src/observation/run-status-at.ts"],"names":[],"mappings":"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"}

package/dist/src/observation/run-timeline.d.ts

@@ -0,0 +1,32 @@
+import type { CueLineRuntimeOptions } from "../api-contracts.js";
+import type { RunEvent } from "../state/event-log.js";
+export type CueLineTimelineCategory = "run" | "controller" | "job" | "runtime" | "caller_work" | "cancellation" | "other";
+export interface CueLineRunTimelineEntry {
+    sequence: number;
+    timestamp: string | null;
+    type: string;
+    category: CueLineTimelineCategory;
+    summary: string;
+    attributes: Record<string, string | number | boolean>;
+    payloadHash: string;
+    ownerFingerprint?: string;
+}
+export interface CueLineRunTimeline {
+    schema: "cueline-timeline/0.1";
+    runId: string;
+    sourceEventsPath: string;
+    afterSequence: number;
+    limit: number;
+    totalEvents: number;
+    latestSequence: number;
+    returnedEvents: number;
+    hasMore: boolean;
+    nextAfterSequence: number;
+    entries: CueLineRunTimelineEntry[];
+}
+export interface CueLineRunTimelineOptions extends Pick<CueLineRuntimeOptions, "home" | "environment"> {
+    afterSequence?: number;
+    limit?: number;
+}
+export declare function buildCueLineRunTimeline(runId: string, events: readonly RunEvent[], home: string, options?: Pick<CueLineRunTimelineOptions, "afterSequence" | "limit">): CueLineRunTimeline;
+export declare function loadCueLineRunTimeline(runId: string, options?: CueLineRunTimelineOptions): Promise<CueLineRunTimeline>;

package/dist/src/observation/run-timeline.js

@@ -0,0 +1,279 @@
+import { createHash } from "node:crypto";
+import { CueLineError } from "../core/errors.js";
+import { canonicalJson } from "../core/ids.js";
+import { loadPersistedRunStore } from "../core/persisted-run.js";
+import { defaultCueLineHome, runPaths } from "../state/paths.js";
+import { readAuthoritativeRunEvents } from "../state/store.js";
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1_000;
+const KNOWN_EVENT_TYPES = new Set([
+    "caller_job_result_submitted",
+    "caller_jobs_ready",
+    "caller_work_became_ambiguous",
+    "caller_work_claim_released",
+    "caller_work_claimed",
+    "caller_work_heartbeat",
+    "caller_work_result_submission_started",
+    "caller_work_result_submitted",
+    "caller_work_started",
+    "controller_command_accepted",
+    "controller_command_execution_completed",
+    "controller_conversation_archive_ambiguous",
+    "controller_conversation_archive_failed",
+    "controller_conversation_archive_preflight_failed",
+    "controller_conversation_archive_started",
+    "controller_conversation_archived",
+    "controller_conversation_bound",
+    "controller_repair_requested",
+    "controller_response_evidence_rejected",
+    "controller_response_received",
+    "controller_response_reconciled",
+    "controller_response_rejected",
+    "controller_submission_succeeded",
+    "controller_turn_abandoned",
+    "controller_turn_manual_submission_confirmed",
+    "controller_turn_requested",
+    "controller_turn_submission_started",
+    "controller_turn_submitted",
+    "job_cancellation_requested",
+    "job_registered",
+    "job_status",
+    "notice",
+    "run_blocked",
+    "run_cancellation_requested",
+    "run_cancelled",
+    "run_completed",
+    "run_created",
+    "run_failed",
+    "run_resumed",
+    "runtime_dead_owner_retired",
+    "runtime_owner_loss_reconciled",
+    "runtime_reconciliation_started",
+    "runtime_stale_caller_observer_recovered",
+    "runtime_stale_owner_takeover_confirmed",
+    "runtime_stale_owner_takeover_requested",
+]);
+const TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const STATUS_VALUES = new Set([
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "ambiguous",
+]);
+const ACTION_VALUES = new Set(["dispatch", "wait", "inspect", "complete", "blocked"]);
+const STAGE_VALUES = new Set([
+    "pre_submit",
+    "submitting",
+    "submitted",
+    "reconciling",
+    "runtime_reconciliation",
+    "job_cancellation",
+]);
+const SUBMISSION_STATE_VALUES = new Set([
+    "definitely_not_sent",
+    "requested",
+    "submitting",
+    "possibly_sent",
+    "submitted",
+]);
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,127}$/;
+const MODEL_PATTERN = /^gpt-[A-Za-z0-9.-]{1,123}$/;
+function safeRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function digest(value) {
+    try {
+        return createHash("sha256").update(canonicalJson(value)).digest("hex");
+    }
+    catch {
+        return createHash("sha256").update("[unhashable-payload]").digest("hex");
+    }
+}
+function fingerprint(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+function safeToken(value) {
+    return typeof value === "string" && TOKEN_PATTERN.test(value) ? value : undefined;
+}
+function safePrefixedToken(value, prefix) {
+    const token = safeToken(value);
+    return token?.startsWith(prefix) ? token : undefined;
+}
+function safeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function category(type) {
+    if (type.startsWith("controller_"))
+        return "controller";
+    if (type.startsWith("caller_work_"))
+        return "caller_work";
+    if (type.startsWith("job_cancellation_"))
+        return "cancellation";
+    if (type.startsWith("job_"))
+        return "job";
+    if (type.startsWith("runtime_"))
+        return "runtime";
+    if (type.includes("cancellation"))
+        return "cancellation";
+    if (type.startsWith("run_"))
+        return "run";
+    return "other";
+}
+function attributesFor(payloadValue) {
+    const payload = safeRecord(payloadValue);
+    const job = safeRecord(payload.job);
+    const command = safeRecord(payload.command);
+    const attributes = {};
+    const requestId = safePrefixedToken(payload.request_id, "msg_") ??
+        safePrefixedToken(command.request_id, "msg_");
+    const round = safeInteger(payload.round);
+    const jobId = safePrefixedToken(payload.job_id, "job_") ?? safePrefixedToken(job.jobId, "job_");
+    const jobKey = safeToken(payload.job_key) ?? safeToken(job.jobKey);
+    const status = safeToken(payload.status);
+    const action = safeToken(payload.action) ?? safeToken(command.action);
+    const rawCode = safeToken(payload.code);
+    const code = rawCode !== undefined && CODE_PATTERN.test(rawCode) ? rawCode : undefined;
+    const rawModel = safeToken(payload.response_model_slug) ?? safeToken(payload.selected_model_label);
+    const model = rawModel === "Pro" || (rawModel !== undefined && MODEL_PATTERN.test(rawModel))
+        ? rawModel
+        : undefined;
+    const runner = safeToken(payload.runner_id);
+    const rawStage = safeToken(payload.stage);
+    const stage = rawStage !== undefined && STAGE_VALUES.has(rawStage) ? rawStage : undefined;
+    const rawSubmissionState = safeToken(payload.submission_state);
+    const submissionState = rawSubmissionState !== undefined && SUBMISSION_STATE_VALUES.has(rawSubmissionState)
+        ? rawSubmissionState
+        : undefined;
+    const pid = safeInteger(payload.pid);
+    if (requestId !== undefined)
+        attributes.requestId = requestId;
+    if (round !== undefined)
+        attributes.round = round;
+    if (jobId !== undefined)
+        attributes.jobId = jobId;
+    if (jobKey !== undefined)
+        attributes.jobKey = jobKey;
+    if (status !== undefined && STATUS_VALUES.has(status))
+        attributes.status = status;
+    if (action !== undefined && ACTION_VALUES.has(action))
+        attributes.action = action;
+    if (code !== undefined)
+        attributes.code = code;
+    if (model !== undefined)
+        attributes.model = model;
+    if (runner !== undefined)
+        attributes.runner = runner;
+    if (stage !== undefined)
+        attributes.stage = stage;
+    if (submissionState !== undefined)
+        attributes.submissionState = submissionState;
+    if (pid !== undefined)
+        attributes.pid = pid;
+    if (Array.isArray(command.jobs))
+        attributes.jobCount = command.jobs.length;
+    return attributes;
+}
+function summary(type, attributes) {
+    switch (type) {
+        case "run_created":
+            return "Run created.";
+        case "controller_turn_requested":
+            return "Controller turn requested.";
+        case "controller_submission_succeeded":
+            return "Controller turn submission recorded.";
+        case "controller_response_received":
+            return "Matching controller response observed.";
+        case "controller_command_accepted":
+            return `Controller command accepted${attributes.action ? `: ${attributes.action}` : ""}.`;
+        case "controller_conversation_archive_started":
+            return "Controller conversation archive attempt started.";
+        case "controller_conversation_archived":
+            return "Controller conversation archived with navigation proof.";
+        case "controller_conversation_archive_ambiguous":
+            return `Controller conversation archive became ambiguous${attributes.code ? `: ${attributes.code}` : ""}.`;
+        case "controller_conversation_archive_failed":
+            return `Controller conversation archive preflight failed${attributes.code ? `: ${attributes.code}` : ""}.`;
+        case "controller_conversation_archive_preflight_failed":
+            return `Controller conversation archive remains retryable after a pre-click failure${attributes.code ? `: ${attributes.code}` : ""}.`;
+        case "job_registered":
+            return "Local job registered.";
+        case "job_status":
+            return `Job status recorded${attributes.status ? `: ${attributes.status}` : ""}.`;
+        case "run_failed":
+            return `Run failure recorded${attributes.code ? `: ${attributes.code}` : ""}.`;
+        case "run_completed":
+            return "Run completed.";
+        case "run_blocked":
+            return "Run blocked.";
+        case "run_cancelled":
+            return "Run cancelled.";
+        default:
+            return type === "unknown_event"
+                ? "Unknown event metadata omitted."
+                : `${type.replaceAll("_", " ")}.`;
+    }
+}
+function entryFor(event) {
+    const type = KNOWN_EVENT_TYPES.has(event.type) ? event.type : "unknown_event";
+    const attributes = attributesFor(event.payload);
+    return {
+        sequence: event.sequence,
+        timestamp: Number.isFinite(Date.parse(event.timestamp)) ? event.timestamp : null,
+        type,
+        category: category(type),
+        summary: summary(type, attributes),
+        attributes,
+        payloadHash: digest(event.payload),
+        ...(event.runtime_owner_id === undefined
+            ? {}
+            : { ownerFingerprint: fingerprint(event.runtime_owner_id) }),
+    };
+}
+function optionInteger(value, name, minimum, maximum) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new CueLineError("RUN_TIMELINE_OPTIONS_INVALID", `${name} must be an integer from ${minimum} to ${maximum}.`);
+    }
+    return value;
+}
+export function buildCueLineRunTimeline(runId, events, home, options = {}) {
+    const afterSequence = optionInteger(options.afterSequence ?? 0, "afterSequence", 0, Number.MAX_SAFE_INTEGER);
+    const limit = optionInteger(options.limit ?? DEFAULT_LIMIT, "limit", 1, MAX_LIMIT);
+    events.forEach((event, index) => {
+        if (event.sequence !== index + 1) {
+            throw new CueLineError("RUN_TIMELINE_EVENTS_INVALID", `Expected event sequence ${index + 1}, received ${event.sequence}.`);
+        }
+    });
+    const latestSequence = events.at(-1)?.sequence ?? 0;
+    if (afterSequence > latestSequence) {
+        throw new CueLineError("RUN_TIMELINE_CURSOR_AHEAD", `Run '${runId}' is at event ${latestSequence}, behind requested cursor ${afterSequence}.`);
+    }
+    const selected = events.filter((event) => event.sequence > afterSequence).slice(0, limit);
+    const entries = selected.map(entryFor);
+    const nextAfterSequence = entries.at(-1)?.sequence ?? afterSequence;
+    return {
+        schema: "cueline-timeline/0.1",
+        runId,
+        sourceEventsPath: runPaths(home, runId).events,
+        afterSequence,
+        limit,
+        totalEvents: events.length,
+        latestSequence,
+        returnedEvents: entries.length,
+        hasMore: latestSequence > nextAfterSequence,
+        nextAfterSequence,
+        entries,
+    };
+}
+export async function loadCueLineRunTimeline(runId, options = {}) {
+    const environment = options.environment ?? process.env;
+    const home = options.home ?? defaultCueLineHome(environment);
+    await loadPersistedRunStore(home, runId);
+    const events = await readAuthoritativeRunEvents(home, runId);
+    return buildCueLineRunTimeline(runId, events, home, options);
+}
+//# sourceMappingURL=run-timeline.js.map

package/dist/src/observation/run-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-timeline.js","sourceRoot":"","sources":["../../../src/observation/run-timeline.ts"],"names":[],"mappings":"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"}

package/dist/src/observation/run-watch.d.ts

@@ -0,0 +1,15 @@
+import type { CueLineRuntimeOptions } from "../api-contracts.js";
+import type { CueLineRunStatusSummary } from "../core/run-status.js";
+export interface CueLineRunWatchOptions extends Pick<CueLineRuntimeOptions, "home" | "environment" | "now" | "signal"> {
+    afterSequence: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+export interface CueLineRunWatchResult {
+    outcome: "changed" | "terminal" | "timed_out";
+    previousSequence: number;
+    currentSequence: number;
+    elapsedMs: number;
+    status: CueLineRunStatusSummary;
+}
+export declare function waitForCueLineRunChange(runId: string, options: CueLineRunWatchOptions): Promise<CueLineRunWatchResult>;

package/dist/src/observation/run-watch.js

@@ -0,0 +1,82 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { loadCueLineRunStatus } from "../api-runtime-lifecycle.js";
+import { CueLineError } from "../core/errors.js";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const MIN_POLL_INTERVAL_MS = 5;
+const MAX_POLL_INTERVAL_MS = 1_000;
+function boundedInteger(value, name, minimum, maximum) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new CueLineError("RUN_WATCH_OPTIONS_INVALID", `${name} must be a safe integer between ${minimum} and ${maximum}.`, { details: { option: name, value, minimum, maximum } });
+    }
+    return value;
+}
+function terminal(status) {
+    return (status.status === "complete" ||
+        status.status === "blocked" ||
+        status.status === "cancelled");
+}
+function assertCursorNotAhead(runId, afterSequence, status) {
+    if (afterSequence <= status.lastEventSequence)
+        return;
+    throw new CueLineError("RUN_WATCH_CURSOR_AHEAD", `Run '${runId}' is at event ${status.lastEventSequence}, behind requested cursor ${afterSequence}.`, {
+        details: {
+            run_id: runId,
+            after_sequence: afterSequence,
+            current_sequence: status.lastEventSequence,
+        },
+    });
+}
+function result(outcome, afterSequence, status, startedAt) {
+    return {
+        outcome,
+        previousSequence: afterSequence,
+        currentSequence: status.lastEventSequence,
+        elapsedMs: Math.max(0, Date.now() - startedAt),
+        status,
+    };
+}
+async function waitInterval(milliseconds, signal) {
+    try {
+        await delay(milliseconds, undefined, signal === undefined ? undefined : { signal });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw new CueLineError("RUN_WATCH_ABORTED", "Run observation was aborted without changing durable state.", { cause: error });
+        }
+        throw error;
+    }
+}
+export async function waitForCueLineRunChange(runId, options) {
+    const afterSequence = boundedInteger(options.afterSequence, "afterSequence", 0, Number.MAX_SAFE_INTEGER);
+    const timeoutMs = boundedInteger(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, "timeoutMs", 0, MAX_TIMEOUT_MS);
+    const pollIntervalMs = boundedInteger(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, "pollIntervalMs", MIN_POLL_INTERVAL_MS, MAX_POLL_INTERVAL_MS);
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    const loadOptions = {
+        ...(options.home === undefined ? {} : { home: options.home }),
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    };
+    let status = await loadCueLineRunStatus(runId, loadOptions);
+    assertCursorNotAhead(runId, afterSequence, status);
+    if (terminal(status))
+        return result("terminal", afterSequence, status, startedAt);
+    if (status.lastEventSequence > afterSequence) {
+        return result("changed", afterSequence, status, startedAt);
+    }
+    while (Date.now() < deadline) {
+        const remaining = deadline - Date.now();
+        await waitInterval(Math.min(pollIntervalMs, remaining), options.signal);
+        status = await loadCueLineRunStatus(runId, loadOptions);
+        assertCursorNotAhead(runId, afterSequence, status);
+        if (terminal(status))
+            return result("terminal", afterSequence, status, startedAt);
+        if (status.lastEventSequence > afterSequence) {
+            return result("changed", afterSequence, status, startedAt);
+        }
+    }
+    return result("timed_out", afterSequence, status, startedAt);
+}
+//# sourceMappingURL=run-watch.js.map

package/dist/src/observation/run-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-watch.js","sourceRoot":"","sources":["../../../src/observation/run-watch.ts"],"names":[],"mappings":"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"}

package/dist/src/protocol/limits.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_CONTROLLER_ENVELOPE_CHARS = 131072;
+export declare const MAX_CONTROLLER_DISPATCH_JOBS = 64;
+export declare const MAX_CONTROLLER_JOB_IDS = 256;

package/dist/src/protocol/limits.js

@@ -0,0 +1,4 @@
+export const MAX_CONTROLLER_ENVELOPE_CHARS = 131_072;
+export const MAX_CONTROLLER_DISPATCH_JOBS = 64;
+export const MAX_CONTROLLER_JOB_IDS = 256;
+//# sourceMappingURL=limits.js.map

package/dist/src/protocol/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/protocol/limits.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,6BAA6B,GAAG,OAAO,CAAC;AACrD,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC"}

package/dist/src/protocol/lint-command.d.ts

@@ -0,0 +1,24 @@
+import type { ControllerCommand, ExpectedControllerIdentity } from "./types.js";
+export type CueLineProtocolLintSeverity = "warning" | "error";
+export interface CueLineProtocolLintIssue {
+    code: string;
+    severity: CueLineProtocolLintSeverity;
+    message: string;
+    path?: string;
+    suggestion?: string;
+}
+export interface CueLineProtocolLintRouting {
+    lanes: readonly string[];
+    runnerLanes: Readonly<Record<string, string>>;
+}
+export interface CueLineProtocolLintOptions {
+    expected: ExpectedControllerIdentity;
+    routing?: CueLineProtocolLintRouting;
+}
+export interface CueLineProtocolLintResult {
+    valid: boolean;
+    format: "envelope" | "json" | "unknown";
+    command?: ControllerCommand;
+    issues: CueLineProtocolLintIssue[];
+}
+export declare function lintControllerCommandText(text: string, options: CueLineProtocolLintOptions): CueLineProtocolLintResult;