@tomflow/proflow-execution-browser-extension 0.1.0

package/dist/src/task-observer.js

@@ -0,0 +1,105 @@
+/**
+ * Deterministic Task Observer.
+ *
+ * The Task Observer is a progression detector in the Extension application
+ * layer. It reads the bounded read-only drive projection exposed by the Task
+ * owner and, on a deterministic condition, requests a typed carrier action
+ * such as WAKE or RESUME. It never writes Task or Node state itself; the
+ * Worker performs formal work acceptance after being woken.
+ */
+const NODE_READY_TRIGGER = "NODE_READY";
+const REOPEN_TRIGGER = "REOPEN";
+export function createTaskObserver(options) {
+    const advance = async (taskId, resumeSignal, anomalySignal) => {
+        const projection = await options.owner.getTaskDriveProjection(taskId);
+        // Terminal Tasks stop driving; history and bindings are retained.
+        if (projection.terminal || projection.currentNode === null)
+            return { kind: "STOP_DRIVING", taskId, reason: "TERMINAL" };
+        const node = projection.currentNode;
+        if (anomalySignal) {
+            if (!options.diagnostic)
+                return { kind: "NOOP", taskId, reason: "DIAGNOSTIC_UNAVAILABLE" };
+            const assessment = await options.diagnostic.assess({
+                taskId,
+                nodeId: node.nodeId,
+                runNo: node.runNo,
+                anomaly: anomalySignal,
+            });
+            if ("ok" in assessment)
+                return {
+                    kind: "NOOP",
+                    taskId,
+                    reason: assessment.errorCode === "REASON_UNAVAILABLE"
+                        ? "DIAGNOSTIC_UNAVAILABLE"
+                        : `DIAGNOSTIC_DEFERRED:${assessment.errorCode}`,
+                };
+            return {
+                kind: "DIAGNOSTIC",
+                taskId,
+                nodeId: node.nodeId,
+                runNo: node.runNo,
+                anomalyRef: anomalySignal.ref,
+                assessment,
+            };
+        }
+        const binding = projection.roleBinding;
+        if (!projection.canDrive ||
+            !binding?.workerRef ||
+            !binding.conversationLocator)
+            return { kind: "NOOP", taskId, reason: "BINDING_NOT_READY" };
+        if (node.status === "READY") {
+            // WAKE the correct Worker with a minimal trigger; the Worker then
+            // performs formal work acceptance through the Task owner. A reopened
+            // run reuses the same TaskRoleBinding/Conversation but keeps the reason
+            // distinct from a first-run NODE_READY wake.
+            return {
+                kind: "WAKE",
+                taskId,
+                nodeId: node.nodeId,
+                runNo: node.runNo,
+                roleRef: binding.roleRef,
+                workerRef: binding.workerRef,
+                trigger: node.runNo > 1 ? REOPEN_TRIGGER : NODE_READY_TRIGGER,
+                conversationLocator: binding.conversationLocator,
+            };
+        }
+        if (resumeSignal) {
+            if (resumeSignal.targetWorkerRef !== binding.workerRef)
+                return {
+                    kind: "NOOP",
+                    taskId,
+                    reason: "RESUME_TARGET_NOT_CURRENT_WORKER",
+                };
+            return {
+                kind: "RESUME",
+                taskId,
+                nodeId: node.nodeId,
+                runNo: node.runNo,
+                roleRef: binding.roleRef,
+                workerRef: binding.workerRef,
+                trigger: resumeSignal.trigger,
+                conversationLocator: binding.conversationLocator,
+                underlyingRef: resumeSignal.ref,
+            };
+        }
+        return { kind: "NOOP", taskId, reason: "NO_NEXT_STEP" };
+    };
+    const drive = async (taskId, resumeSignal, anomalySignal) => {
+        const decision = await advance(taskId, resumeSignal, anomalySignal);
+        if (decision.kind === "WAKE" || decision.kind === "RESUME")
+            await options.carrier.requestWake({
+                taskId: decision.taskId,
+                nodeId: decision.nodeId,
+                runNo: decision.runNo,
+                roleRef: decision.roleRef,
+                workerRef: decision.workerRef,
+                trigger: decision.trigger,
+                conversationLocator: decision.conversationLocator,
+                ...(decision.kind === "RESUME"
+                    ? { underlyingRef: decision.underlyingRef }
+                    : {}),
+            });
+        return decision;
+    };
+    return Object.freeze({ advance, drive });
+}

package/dist/src/vision.d.ts

@@ -0,0 +1,73 @@
+import type { BrowserActivityKind, BrowserPageState } from "./index.ts";
+/**
+ * Browser screenshot → Model Vision fallback port.
+ *
+ * Deterministic DOM/URL/runtime observation is primary. Only when the page
+ * cannot be explained deterministically does the Carrier capture a screenshot
+ * and ask an injected `BrowserVisionPort` for a spec-ized semantic observation
+ * (see MODEL-DOC-03-05 §6: pageState / activityKind / confidence /
+ * recommendedNext / reasonCode). The port returns an OBSERVED interpretation or
+ * a typed DEFERRED fail-safe; it never decides Task/Execution/Approval truth
+ * and never fabricates a page state.
+ *
+ * Raw screenshot bytes (dataUrl/base64) never enter structured logs: only the
+ * bounded typed observation and image mimeType/size/hash are retained.
+ */
+export declare const visionMimeTypes: readonly ["image/png", "image/jpeg", "image/webp"];
+export type VisionMimeType = (typeof visionMimeTypes)[number];
+export declare const visionRecommendedNext: readonly ["NONE", "RECOVER", "WAIT", "REQUEST_HUMAN"];
+export type VisionRecommendedNext = (typeof visionRecommendedNext)[number];
+/** A runtime-validated screenshot payload ready to hand to a Vision port. */
+export interface BrowserVisionImage {
+    dataUrl: string;
+    base64: string;
+    mimeType: VisionMimeType;
+    hash: string;
+    sizeBytes: number;
+}
+/** Bounded deterministic facts that accompany the image for interpretation. */
+export interface BrowserVisionObservationContext {
+    targetRef: string;
+    pageState: BrowserPageState;
+    activityKind: BrowserActivityKind;
+    observedAt: string;
+}
+export interface BrowserVisionObservation {
+    status: "OBSERVED";
+    observationRef: string;
+    pageState: BrowserPageState;
+    activityKind: BrowserActivityKind;
+    confidence: number;
+    recommendedNext: VisionRecommendedNext;
+    reasonCode: string;
+    rationale: string;
+}
+export type BrowserVisionDeferralReason = "VISION_PORT_UNAVAILABLE" | "VISION_IMAGE_INVALID" | "VISION_INFERENCE_FAILED";
+export interface BrowserVisionDeferral {
+    status: "DEFERRED";
+    reasonCode: BrowserVisionDeferralReason;
+    message: string;
+}
+export type TypedVisionObservation = BrowserVisionObservation | BrowserVisionDeferral;
+export interface BrowserVisionPort {
+    inspect(input: {
+        image: BrowserVisionImage;
+        observationContext: BrowserVisionObservationContext;
+    }): Promise<TypedVisionObservation>;
+}
+export declare function deferVisionObservation(reasonCode: BrowserVisionDeferralReason, message: string): BrowserVisionDeferral;
+export declare const VISION_OBSERVATION_MIN_CONFIDENCE = 0.75;
+/**
+ * Deterministic Carrier policy for deciding whether a model observation is
+ * strong enough to count as a verified Browser observation. A successful
+ * model response is diagnostic evidence only; UNKNOWN, low-confidence, or
+ * explicit human-escalation recommendations remain unverified.
+ */
+export declare function isVisionObservationVerified(value: TypedVisionObservation): value is BrowserVisionObservation;
+/**
+ * Runtime-validate a raw screenshot capture into a trusted image payload before
+ * it may reach a Vision port. Only supported image MIME types are accepted; the
+ * MIME must match the dataUrl prefix, sizeBytes must be a positive integer, and
+ * the hash must be present. The raw dataUrl never leaves this boundary.
+ */
+export declare function parseCapturedScreenshot(value: unknown): BrowserVisionImage;

package/dist/src/vision.js

@@ -0,0 +1,82 @@
+/**
+ * Browser screenshot → Model Vision fallback port.
+ *
+ * Deterministic DOM/URL/runtime observation is primary. Only when the page
+ * cannot be explained deterministically does the Carrier capture a screenshot
+ * and ask an injected `BrowserVisionPort` for a spec-ized semantic observation
+ * (see MODEL-DOC-03-05 §6: pageState / activityKind / confidence /
+ * recommendedNext / reasonCode). The port returns an OBSERVED interpretation or
+ * a typed DEFERRED fail-safe; it never decides Task/Execution/Approval truth
+ * and never fabricates a page state.
+ *
+ * Raw screenshot bytes (dataUrl/base64) never enter structured logs: only the
+ * bounded typed observation and image mimeType/size/hash are retained.
+ */
+export const visionMimeTypes = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+];
+export const visionRecommendedNext = [
+    "NONE",
+    "RECOVER",
+    "WAIT",
+    "REQUEST_HUMAN",
+];
+export function deferVisionObservation(reasonCode, message) {
+    return Object.freeze({ status: "DEFERRED", reasonCode, message });
+}
+export const VISION_OBSERVATION_MIN_CONFIDENCE = 0.75;
+/**
+ * Deterministic Carrier policy for deciding whether a model observation is
+ * strong enough to count as a verified Browser observation. A successful
+ * model response is diagnostic evidence only; UNKNOWN, low-confidence, or
+ * explicit human-escalation recommendations remain unverified.
+ */
+export function isVisionObservationVerified(value) {
+    return (value.status === "OBSERVED" &&
+        value.pageState !== "UNKNOWN" &&
+        value.confidence >= VISION_OBSERVATION_MIN_CONFIDENCE &&
+        value.recommendedNext !== "REQUEST_HUMAN");
+}
+/**
+ * Runtime-validate a raw screenshot capture into a trusted image payload before
+ * it may reach a Vision port. Only supported image MIME types are accepted; the
+ * MIME must match the dataUrl prefix, sizeBytes must be a positive integer, and
+ * the hash must be present. The raw dataUrl never leaves this boundary.
+ */
+export function parseCapturedScreenshot(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError("screenshot capture must be an object");
+    const record = value;
+    const dataUrl = record.dataUrl;
+    const mimeType = record.mimeType;
+    const sizeBytes = record.sizeBytes;
+    const hash = record.hash;
+    if (typeof dataUrl !== "string" || dataUrl.length === 0)
+        throw new TypeError("screenshot dataUrl must be a non-empty string");
+    if (typeof mimeType !== "string" ||
+        !visionMimeTypes.includes(mimeType))
+        throw new TypeError("screenshot mimeType is not a supported image type");
+    if (typeof sizeBytes !== "number" ||
+        !Number.isInteger(sizeBytes) ||
+        sizeBytes <= 0)
+        throw new TypeError("screenshot sizeBytes must be a positive integer");
+    if (typeof hash !== "string" || hash.length === 0)
+        throw new TypeError("screenshot hash must be a non-empty string");
+    const prefix = `data:${mimeType};base64,`;
+    if (!dataUrl.startsWith(prefix))
+        throw new TypeError("screenshot dataUrl does not match its mimeType");
+    const base64 = dataUrl.slice(prefix.length);
+    if (base64.length === 0)
+        throw new TypeError("screenshot dataUrl has no base64 payload");
+    if (Buffer.from(base64, "base64").length === 0)
+        throw new TypeError("screenshot image payload is empty");
+    return Object.freeze({
+        dataUrl,
+        base64,
+        mimeType: mimeType,
+        hash,
+        sizeBytes,
+    });
+}