@tomflow/proflow-execution-browser-extension 0.1.0

package/dist/src/runtime-composition.d.ts

@@ -0,0 +1,97 @@
+import { type BrowserRealityBridgeOptions } from "./bridge.ts";
+import { type BrowserVisionPort } from "./index.ts";
+type LocalApplicationConfig = {
+    endpoint: string;
+    token: string;
+};
+export type BrowserExecutorCompositionOptions = {
+    platformHost: LocalApplicationConfig;
+    bridge: BrowserRealityBridgeOptions;
+    vision?: BrowserVisionPort;
+};
+export type BrowserExecutorCompositionFileConfig = {
+    platformHost: {
+        endpoint: string;
+        tokenFile: string;
+    };
+    bridge: {
+        extensionId: string;
+        tokenFile: string;
+        host?: string;
+        port?: number;
+    };
+};
+export declare function loadBrowserExecutorCompositionConfig(path: string): Promise<BrowserExecutorCompositionOptions>;
+/**
+ * Node-side Browser Executor composition. This deliberately does NOT create an
+ * Execution Runtime process. The single formal execution-runtime binary owns
+ * Execution truth and must inject `browserExecutor` from this composition.
+ */
+export declare function createBrowserExecutorComposition(options: BrowserExecutorCompositionOptions): Promise<Readonly<{
+    browserExecutor: Readonly<{
+        extensionInstanceId: string;
+        parseCarrierIdentity: (raw: string) => {
+            roleRef: string;
+            workerRef: string | null;
+        };
+        registerContentSession: (observation: import("./index.ts").BrowserPageObservation) => void;
+        isContentSessionCurrent(tabId: number, contentInstanceId: string): boolean;
+        classifyProgress(input: {
+            pageState: import("./index.ts").BrowserPageState;
+            nodeInProgress: boolean;
+            millisecondsWithoutProgress: number;
+            legitimateWait: boolean;
+        }): "EXPECTED_WAIT" | "NORMAL" | "PROGRESS_GAP" | "RUNTIME_STALL";
+        inspectScreenshot(tabId: number, observationContext: import("./vision.ts").BrowserVisionObservationContext): Promise<import("./vision.ts").TypedVisionObservation>;
+        handlePermissionFallback(tabId: number, continuationRef: string): Promise<{
+            status: "WAITING_HUMAN";
+            continuationRef: string;
+            evidenceRef: string;
+        }>;
+        getSidePanelSnapshot(): Readonly<{
+            extensionInstanceId: string;
+            observedAt: string;
+            sessions: {
+                tabId: number;
+                windowId: number;
+                url: string;
+                contentInstanceId: string;
+                pageState: import("./index.ts").BrowserPageState;
+                activityKind: import("./index.ts").BrowserActivityKind;
+            }[];
+            lanes: {
+                roleRef: string;
+                workerRef: string;
+                tabId: number;
+                pageState: import("./index.ts").BrowserPageState;
+                activityKind: import("./index.ts").BrowserActivityKind;
+                currentExecutionRef: string | null;
+                continuationRef: string | null;
+                lastProgressAt: string;
+            }[];
+        }>;
+        execute: (raw: import("@tomflow/proflow-execution-contracts").ExecutorInvocation) => Promise<import("@tomflow/proflow-execution-contracts").ExecutorResult>;
+        observePrecondition: (request: import("@tomflow/proflow-execution-contracts").ExecuteCapabilityRequest) => Promise<import("@tomflow/proflow-execution-contracts").ExecutorPrecondition | undefined>;
+        reconcile: (requestRaw: import("@tomflow/proflow-execution-contracts").ExecuteCapabilityRequest, preconditionRaw: import("@tomflow/proflow-execution-contracts").ExecutorPrecondition) => Promise<import("@tomflow/proflow-execution-contracts").ExecutorReconciliation>;
+        readArtifact(): Promise<never>;
+        recoveryScan(unfinished: Array<{
+            request: import("@tomflow/proflow-execution-contracts").ExecuteCapabilityRequest;
+            effectStarted: boolean;
+        }>): Promise<{
+            status: "ALREADY_COMPLETED";
+            reconciled: never[];
+        } | {
+            status: "COMPLETED";
+            reconciled: import("@tomflow/proflow-execution-contracts").ExecutorReconciliation[];
+        }>;
+    }>;
+    bridgeEndpoint: string;
+    bridgeStatus: () => {
+        online: boolean;
+        extensionInstanceId: string | null;
+        queuedCommands: number;
+        pendingCommands: number;
+    };
+    close: () => Promise<void>;
+}>>;
+export {};

package/dist/src/runtime-composition.js

@@ -0,0 +1,124 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createBrowserRealityBridgeServer, } from "./bridge.js";
+import { createExecutionBrowserExtension, } from "./index.js";
+function record(value, name) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError(`${name} must be an object`);
+    return value;
+}
+function nonEmpty(value, name) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`${name} must be a non-empty string`);
+    return value;
+}
+async function readSecret(path, name) {
+    const info = await stat(path);
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+        throw new TypeError(`${name} permissions must be owner-only`);
+    const value = (await readFile(path, "utf8")).trim();
+    if (value.length < 32)
+        throw new TypeError(`${name} must contain at least 32 characters`);
+    return value;
+}
+export async function loadBrowserExecutorCompositionConfig(path) {
+    const absolute = resolve(path);
+    const root = dirname(absolute);
+    const raw = record(JSON.parse(await readFile(absolute, "utf8")), "browser executor composition config");
+    const platformHost = record(raw.platformHost, "platformHost");
+    const bridge = record(raw.bridge, "bridge");
+    return {
+        platformHost: {
+            endpoint: nonEmpty(platformHost.endpoint, "platformHost.endpoint"),
+            token: await readSecret(resolve(root, nonEmpty(platformHost.tokenFile, "platformHost.tokenFile")), "platformHost token"),
+        },
+        bridge: {
+            extensionId: nonEmpty(bridge.extensionId, "bridge.extensionId"),
+            token: await readSecret(resolve(root, nonEmpty(bridge.tokenFile, "bridge.tokenFile")), "bridge token"),
+            ...(bridge.host === "127.0.0.1" ? { host: bridge.host } : {}),
+            ...(bridge.port !== undefined ? { port: Number(bridge.port) } : {}),
+        },
+    };
+}
+function applicationConfig(input) {
+    const endpoint = new URL(input.endpoint);
+    if (endpoint.protocol !== "http:" ||
+        !new Set(["127.0.0.1", "localhost", "::1", "[::1]"]).has(endpoint.hostname) ||
+        endpoint.pathname !== "/" ||
+        endpoint.search !== "" ||
+        endpoint.hash !== "")
+        throw new TypeError("platformHost endpoint must be loopback HTTP root");
+    if (input.token.length < 32)
+        throw new TypeError("platformHost token must contain at least 32 characters");
+    return { endpoint: input.endpoint.replace(/\/$/, ""), token: input.token };
+}
+async function invokeApplication(config, operation, input) {
+    const response = await fetch(`${config.endpoint}/application/observer`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ operation, input }),
+    });
+    const text = await response.text();
+    const body = text.length ? JSON.parse(text) : undefined;
+    if (!response.ok)
+        throw new Error(typeof body === "object" &&
+            body !== null &&
+            typeof Reflect.get(body, "error") === "string"
+            ? String(Reflect.get(body, "error"))
+            : "BROWSER_OWNER_TRANSPORT_FAILED");
+    return body;
+}
+/**
+ * Node-side Browser Executor composition. This deliberately does NOT create an
+ * Execution Runtime process. The single formal execution-runtime binary owns
+ * Execution truth and must inject `browserExecutor` from this composition.
+ */
+export async function createBrowserExecutorComposition(options) {
+    const platformHost = applicationConfig(options.platformHost);
+    const bridge = await createBrowserRealityBridgeServer(options.bridge);
+    try {
+        const browserExecutor = createExecutionBrowserExtension({
+            browser: bridge.browser,
+            ...(options.vision ? { vision: options.vision } : {}),
+            task: {
+                async getWorkerBinding(taskId, roleRef) {
+                    return (await invokeApplication(platformHost, "browser.binding", {
+                        taskId,
+                        roleRef,
+                    }));
+                },
+                async bindWorker(binding) {
+                    await invokeApplication(platformHost, "browser.bindWorker", binding);
+                },
+            },
+            agent: {
+                async getPendingMessage(messageRef) {
+                    return (await invokeApplication(platformHost, "collaboration.getPending", {
+                        messageRef,
+                    }));
+                },
+                async reportPhysicalDelivery(messageRef, evidenceRef, executionRef) {
+                    await invokeApplication(platformHost, "collaboration.reportDelivery", {
+                        messageRef,
+                        outcome: "DELIVERED",
+                        evidenceRef,
+                        executionRef,
+                    });
+                },
+            },
+        });
+        return Object.freeze({
+            browserExecutor,
+            bridgeEndpoint: bridge.endpoint,
+            bridgeStatus: bridge.status,
+            close: bridge.close,
+        });
+    }
+    catch (error) {
+        await bridge.close();
+        throw error;
+    }
+}

package/dist/src/system-observer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * System Observer: lowest-priority, read-only system assessment orchestration.
+ *
+ * Owner domains project bounded snapshots. This caller groups them into concern
+ * batches, carries unresolved findings forward explicitly, requests targeted
+ * drill-down only when the assessment asks for it, and performs one final
+ * global synthesis. It never mutates owner facts and it never owns model
+ * scheduling or business state.
+ */
+export declare const SYSTEM_OBSERVER_VIEWS: readonly ["task", "worker", "collaboration", "execution", "carrier", "model", "deployment", "artifact"];
+export type SystemObserverView = (typeof SYSTEM_OBSERVER_VIEWS)[number];
+export type SystemObserverPriority = "BACKGROUND" | "LOWEST" | "DEFERRED";
+export type SystemObserverHealth = "HEALTHY" | "DEGRADED" | "CRITICAL" | "UNKNOWN";
+export interface SystemObserverCarryForwardItem {
+    hypothesis: string;
+    risk?: string;
+    evidenceRef?: string;
+    confidence: number;
+}
+export interface SystemObserverAssessment {
+    scope: string;
+    observedAt: string;
+    health: SystemObserverHealth;
+    findings: string[];
+    risks: string[];
+    anomalies: string[];
+    hypotheses: string[];
+    unresolved: string[];
+    needsDrilldown: string[];
+    evidenceRefs: string[];
+    confidence: number;
+    carryForward: SystemObserverCarryForwardItem[];
+    rationale: string;
+}
+export interface SystemObserverSnapshotPort {
+    readView(view: SystemObserverView): Promise<unknown>;
+    readDrilldown?(request: {
+        topic: string;
+        views: readonly SystemObserverView[];
+    }): Promise<unknown>;
+}
+export interface SystemObserverReasonRequest {
+    assessmentRef: string;
+    kind: "CONCERN_BATCH" | "DRILLDOWN" | "GLOBAL_SYNTHESIS";
+    scope: string;
+    observedAt: string;
+    views: Partial<Record<SystemObserverView, unknown>>;
+    previousUnresolved: string[];
+    previousCarryForward: SystemObserverCarryForwardItem[];
+    batchAssessments?: SystemObserverAssessment[];
+    drilldown?: Array<{
+        topic: string;
+        data: unknown;
+    }>;
+}
+export interface SystemObserverReasonResult extends Omit<SystemObserverAssessment, "scope" | "observedAt"> {
+    scope?: string;
+}
+export type SystemObserverReasonFailure = {
+    ok: false;
+    errorCode: "CONTEXT_TOO_LARGE" | "REASON_UNAVAILABLE" | "REASON_FAILED";
+};
+export interface SystemObserverResult {
+    assessmentRef: string;
+    priority: SystemObserverPriority;
+    observedAt: string;
+    assessments: SystemObserverAssessment[];
+    drilldown: Array<{
+        topic: string;
+        data: unknown;
+    }>;
+    global: SystemObserverAssessment | null;
+    status: "ASSESSED" | "DEFERRED";
+    errorCode?: "CONTEXT_TOO_LARGE" | "REASON_UNAVAILABLE" | "REASON_FAILED";
+}
+export declare function createSystemObserver(options: {
+    snapshots: SystemObserverSnapshotPort;
+    reason?: (input: SystemObserverReasonRequest) => Promise<SystemObserverReasonResult | SystemObserverReasonFailure>;
+    idFactory?: () => string;
+    now?: () => Date;
+}): Readonly<{
+    synthesize: (input?: {
+        previousUnresolved?: string[];
+        previousCarryForward?: SystemObserverCarryForwardItem[];
+    }) => Promise<SystemObserverResult>;
+}>;

package/dist/src/system-observer.js

@@ -0,0 +1,252 @@
+/**
+ * System Observer: lowest-priority, read-only system assessment orchestration.
+ *
+ * Owner domains project bounded snapshots. This caller groups them into concern
+ * batches, carries unresolved findings forward explicitly, requests targeted
+ * drill-down only when the assessment asks for it, and performs one final
+ * global synthesis. It never mutates owner facts and it never owns model
+ * scheduling or business state.
+ */
+export const SYSTEM_OBSERVER_VIEWS = [
+    "task",
+    "worker",
+    "collaboration",
+    "execution",
+    "carrier",
+    "model",
+    "deployment",
+    "artifact",
+];
+const DEFAULT_CONCERN_BATCHES = [
+    { scope: "task-worker", views: ["task", "worker"] },
+    { scope: "execution-approval", views: ["execution", "artifact"] },
+    { scope: "collaboration-carrier", views: ["collaboration", "carrier"] },
+    { scope: "model-deployment-health", views: ["model", "deployment"] },
+];
+function normalizeAssessment(result, scope, observedAt) {
+    return {
+        scope: result.scope ?? scope,
+        observedAt,
+        health: result.health,
+        findings: [...result.findings],
+        risks: [...result.risks],
+        anomalies: [...result.anomalies],
+        hypotheses: [...result.hypotheses],
+        unresolved: [...result.unresolved],
+        needsDrilldown: [...result.needsDrilldown],
+        evidenceRefs: [...result.evidenceRefs],
+        confidence: result.confidence,
+        carryForward: result.carryForward.map((item) => ({ ...item })),
+        rationale: result.rationale,
+    };
+}
+function isReasonFailure(value) {
+    return "ok" in value && value.ok === false;
+}
+function compactView(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return value;
+    const source = value;
+    return {
+        summary: typeof source.summary === "string"
+            ? source.summary.slice(0, 600)
+            : "bounded view unavailable",
+        ...(typeof source.health === "string" ? { health: source.health } : {}),
+        ...(typeof source.projectionStatus === "string"
+            ? { projectionStatus: source.projectionStatus }
+            : {}),
+        ...(Array.isArray(source.findings)
+            ? {
+                findings: source.findings
+                    .filter((item) => typeof item === "string")
+                    .slice(0, 8)
+                    .map((item) => item.slice(0, 240)),
+            }
+            : {}),
+        ...(Array.isArray(source.evidenceRefs)
+            ? {
+                evidenceRefs: source.evidenceRefs
+                    .filter((item) => typeof item === "string")
+                    .slice(0, 8),
+            }
+            : {}),
+    };
+}
+function compactAssessment(value) {
+    return {
+        ...value,
+        findings: value.findings.slice(0, 8),
+        risks: value.risks.slice(0, 8),
+        anomalies: value.anomalies.slice(0, 8),
+        hypotheses: value.hypotheses.slice(0, 8),
+        unresolved: value.unresolved.slice(0, 8),
+        needsDrilldown: value.needsDrilldown.slice(0, 8),
+        evidenceRefs: value.evidenceRefs.slice(0, 8),
+        carryForward: value.carryForward.slice(0, 8),
+        rationale: value.rationale.slice(0, 240),
+    };
+}
+export function createSystemObserver(options) {
+    const priority = "LOWEST";
+    const now = options.now ?? (() => new Date());
+    const idFactory = options.idFactory ?? (() => crypto.randomUUID());
+    const readViews = async (views) => {
+        const entries = await Promise.all(views.map(async (view) => [view, await options.snapshots.readView(view)]));
+        return Object.fromEntries(entries);
+    };
+    const synthesize = async (input) => {
+        const observedAt = now().toISOString();
+        const assessmentRef = `assessment:${idFactory()}`;
+        const previousUnresolved = [...(input?.previousUnresolved ?? [])];
+        const previousCarryForward = (input?.previousCarryForward ?? []).map((item) => ({ ...item }));
+        if (!options.reason) {
+            return {
+                assessmentRef,
+                priority: "DEFERRED",
+                observedAt,
+                assessments: [],
+                drilldown: [],
+                global: null,
+                status: "DEFERRED",
+                errorCode: "REASON_UNAVAILABLE",
+            };
+        }
+        try {
+            const assessments = [];
+            for (const batch of DEFAULT_CONCERN_BATCHES) {
+                const views = await readViews(batch.views);
+                const result = await options.reason({
+                    assessmentRef,
+                    kind: "CONCERN_BATCH",
+                    scope: batch.scope,
+                    observedAt,
+                    views,
+                    previousUnresolved,
+                    previousCarryForward,
+                });
+                if (isReasonFailure(result) &&
+                    result.errorCode === "CONTEXT_TOO_LARGE" &&
+                    batch.views.length > 1) {
+                    for (const view of batch.views) {
+                        const singleViews = await readViews([view]);
+                        let single = await options.reason({
+                            assessmentRef,
+                            kind: "CONCERN_BATCH",
+                            scope: `${batch.scope}:${view}`,
+                            observedAt,
+                            views: singleViews,
+                            previousUnresolved,
+                            previousCarryForward,
+                        });
+                        if (isReasonFailure(single) &&
+                            single.errorCode === "CONTEXT_TOO_LARGE") {
+                            single = await options.reason({
+                                assessmentRef,
+                                kind: "CONCERN_BATCH",
+                                scope: `${batch.scope}:${view}:compact`,
+                                observedAt,
+                                views: Object.fromEntries(Object.entries(singleViews).map(([key, value]) => [
+                                    key,
+                                    compactView(value),
+                                ])),
+                                previousUnresolved: previousUnresolved.slice(0, 8),
+                                previousCarryForward: previousCarryForward.slice(0, 8),
+                            });
+                        }
+                        if (isReasonFailure(single))
+                            throw Object.assign(new Error(single.errorCode), {
+                                code: single.errorCode,
+                            });
+                        assessments.push(normalizeAssessment(single, `${batch.scope}:${view}`, observedAt));
+                    }
+                    continue;
+                }
+                if (isReasonFailure(result))
+                    throw Object.assign(new Error(result.errorCode), {
+                        code: result.errorCode,
+                    });
+                assessments.push(normalizeAssessment(result, batch.scope, observedAt));
+            }
+            const topics = [
+                ...new Set(assessments.flatMap((item) => item.needsDrilldown)),
+            ];
+            const drilldown = [];
+            if (options.snapshots.readDrilldown) {
+                for (const topic of topics) {
+                    drilldown.push({
+                        topic,
+                        data: await options.snapshots.readDrilldown({
+                            topic,
+                            views: SYSTEM_OBSERVER_VIEWS,
+                        }),
+                    });
+                }
+            }
+            const topLevelViews = await readViews(SYSTEM_OBSERVER_VIEWS);
+            let globalResult = await options.reason({
+                assessmentRef,
+                kind: "GLOBAL_SYNTHESIS",
+                scope: "global",
+                observedAt,
+                views: topLevelViews,
+                previousUnresolved,
+                previousCarryForward,
+                batchAssessments: assessments,
+                drilldown,
+            });
+            if (isReasonFailure(globalResult) &&
+                globalResult.errorCode === "CONTEXT_TOO_LARGE") {
+                globalResult = await options.reason({
+                    assessmentRef,
+                    kind: "GLOBAL_SYNTHESIS",
+                    scope: "global:compact",
+                    observedAt,
+                    views: Object.fromEntries(Object.entries(topLevelViews).map(([key, value]) => [
+                        key,
+                        compactView(value),
+                    ])),
+                    previousUnresolved: previousUnresolved.slice(0, 8),
+                    previousCarryForward: previousCarryForward.slice(0, 8),
+                    batchAssessments: assessments.slice(0, 8).map(compactAssessment),
+                    drilldown: drilldown.slice(0, 8).map((item) => ({
+                        topic: item.topic.slice(0, 240),
+                        data: compactView(item.data),
+                    })),
+                });
+            }
+            if (isReasonFailure(globalResult))
+                throw Object.assign(new Error(globalResult.errorCode), {
+                    code: globalResult.errorCode,
+                });
+            const global = normalizeAssessment(globalResult, "global", observedAt);
+            return {
+                assessmentRef,
+                priority,
+                observedAt,
+                assessments,
+                drilldown,
+                global,
+                status: "ASSESSED",
+            };
+        }
+        catch (error) {
+            const errorCode = typeof error === "object" && error !== null
+                ? Reflect.get(error, "code")
+                : undefined;
+            const code = errorCode === "CONTEXT_TOO_LARGE" || errorCode === "REASON_UNAVAILABLE"
+                ? errorCode
+                : "REASON_FAILED";
+            return {
+                assessmentRef,
+                priority: "DEFERRED",
+                observedAt,
+                assessments: [],
+                drilldown: [],
+                global: null,
+                status: "DEFERRED",
+                errorCode: code,
+            };
+        }
+    };
+    return Object.freeze({ synthesize });
+}

package/dist/src/task-observer.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+export type TaskDriveProjection = {
+    taskId: string;
+    taskStatus: string;
+    taskVersion: number;
+    terminal: boolean;
+    currentNode: {
+        nodeId: string;
+        status: string;
+        version: number;
+        runNo: number;
+        requiredAgentPackageRef: string;
+    } | null;
+    roleBinding: {
+        agentPackageRef: string;
+        roleRef: string;
+        workerRef: string | null;
+        conversationLocator: string | null;
+    } | null;
+    canDrive: boolean;
+    blockedReason: string | null;
+};
+export type TaskObserverResumeSignal = {
+    trigger: "EXECUTION_RESULT_READY" | "PEER_REPLY_READY" | "RECOVERY_RESUME";
+    ref: string;
+    targetWorkerRef: string;
+};
+export type TaskObserverAnomalySignal = {
+    kind: "FACT_CONFLICT" | "UNKNOWN_REALITY" | "STALLED" | "RECOVERY_FAILED";
+    ref: string;
+    facts: Record<string, string | number | boolean | null>;
+};
+export type TaskObserverDiagnosticAssessment = {
+    finding: string;
+    probableCause: string;
+    confidence: number;
+    recommendedNextObservation: string;
+    recommendedRecoveryAction: string;
+    needsHumanAttention: boolean;
+};
+export type TaskObserverDiagnosticFailure = {
+    ok: false;
+    errorCode: "REASON_UNAVAILABLE" | "CONTEXT_TOO_LARGE" | "REASON_FAILED";
+};
+export interface TaskObserverDiagnosticPort {
+    assess(input: {
+        taskId: string;
+        nodeId: string;
+        runNo: number;
+        anomaly: TaskObserverAnomalySignal;
+    }): Promise<TaskObserverDiagnosticAssessment | TaskObserverDiagnosticFailure>;
+}
+export interface TaskObserverOwnerPort {
+    getTaskDriveProjection(taskId: string): Promise<TaskDriveProjection>;
+}
+export interface TaskObserverCarrierPort {
+    requestWake(input: {
+        taskId: string;
+        nodeId: string;
+        runNo: number;
+        roleRef: string;
+        workerRef: string;
+        trigger: string;
+        conversationLocator: string | null;
+        underlyingRef?: string;
+    }): Promise<unknown>;
+}
+export type TaskObserverDecision = {
+    kind: "WAKE";
+    taskId: string;
+    nodeId: string;
+    runNo: number;
+    roleRef: string;
+    workerRef: string;
+    trigger: string;
+    conversationLocator: string | null;
+} | {
+    kind: "RESUME";
+    taskId: string;
+    nodeId: string;
+    runNo: number;
+    roleRef: string;
+    workerRef: string;
+    trigger: string;
+    conversationLocator: string;
+    underlyingRef: string;
+} | {
+    kind: "DIAGNOSTIC";
+    taskId: string;
+    nodeId: string;
+    runNo: number;
+    anomalyRef: string;
+    assessment: TaskObserverDiagnosticAssessment;
+} | {
+    kind: "STOP_DRIVING";
+    taskId: string;
+    reason: "TERMINAL";
+} | {
+    kind: "NOOP";
+    taskId: string;
+    reason: string;
+};
+export declare function createTaskObserver(options: {
+    owner: TaskObserverOwnerPort;
+    carrier: TaskObserverCarrierPort;
+    diagnostic?: TaskObserverDiagnosticPort;
+}): Readonly<{
+    advance: (taskId: string, resumeSignal?: TaskObserverResumeSignal, anomalySignal?: TaskObserverAnomalySignal) => Promise<TaskObserverDecision>;
+    drive: (taskId: string, resumeSignal?: TaskObserverResumeSignal, anomalySignal?: TaskObserverAnomalySignal) => Promise<TaskObserverDecision>;
+}>;