@tomflow/proflow-platform-host 0.1.21 → 0.1.23

package/dist/src/reconciliation-coordinator.d.ts

@@ -0,0 +1,37 @@
+import { type TaskDriveProjection, type TaskResumeSignal } from "./task-observer.ts";
+export type ReconciliationCoordinatorOptions = {
+    listTaskPage(input: {
+        afterTaskId?: string;
+        limit: number;
+    }): Promise<{
+        taskIds: string[];
+        nextAfterTaskId?: string;
+    }>;
+    listExecutionSignals(): Promise<unknown[]>;
+    acknowledgeExecutionSignal(signalRef: string): Promise<void>;
+    ensureWorkers(taskId: string): Promise<void>;
+    getProjection(taskId: string): Promise<TaskDriveProjection>;
+    requestWake(input: {
+        taskId: string;
+        nodeId: string;
+        runNo: number;
+        roleRef: string;
+        workerRef: string;
+        trigger: string;
+        conversationLocator: string;
+        underlyingRef?: string;
+    }): Promise<unknown>;
+    intervalMs?: number;
+    pageSize?: number;
+    concurrency?: number;
+    maxPendingTasks?: number;
+    maxPendingSignals?: number;
+    now?: () => number;
+};
+export declare function createReconciliationCoordinator(options: ReconciliationCoordinatorOptions): Readonly<{
+    start(): void;
+    kick(taskId: string, signal?: TaskResumeSignal): void;
+    reconcile: (taskId: string, signal?: TaskResumeSignal) => Promise<void>;
+    sweep: () => Promise<void>;
+    stop(): void;
+}>;

package/dist/src/reconciliation-coordinator.js

@@ -0,0 +1,336 @@
+import { decideTaskProgression, } from "./task-observer.js";
+function positiveBound(value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > max)
+        throw new RangeError(`reconciliation bound must be between 1 and ${max}`);
+    return value;
+}
+export function createReconciliationCoordinator(options) {
+    const intervalMs = positiveBound(options.intervalMs, 10_000, 60_000);
+    const pageSize = positiveBound(options.pageSize, 100, 1_000);
+    const concurrency = positiveBound(options.concurrency, 4, 64);
+    const maxPendingTasks = positiveBound(options.maxPendingTasks, 1_024, 10_000);
+    const maxPendingSignals = positiveBound(options.maxPendingSignals, 4_096, 50_000);
+    const now = options.now ?? Date.now;
+    let taskCursor;
+    let stopped = false;
+    let started = false;
+    let timer;
+    let sweepInFlight = null;
+    let activeReconciliations = 0;
+    let pendingSignalCount = 0;
+    const slotWaiters = [];
+    const admittedTasks = new Set();
+    const taskInFlight = new Map();
+    const pendingSignals = new Map();
+    const failures = new Map();
+    const appliedIntents = new Map();
+    const retryTimers = new Map();
+    const acquireSlot = async () => {
+        if (stopped)
+            return false;
+        if (activeReconciliations < concurrency) {
+            activeReconciliations += 1;
+            return true;
+        }
+        return new Promise((resolve) => slotWaiters.push(resolve));
+    };
+    const releaseSlot = () => {
+        const next = stopped ? undefined : slotWaiters.shift();
+        if (next)
+            next(true);
+        else
+            activeReconciliations = Math.max(0, activeReconciliations - 1);
+    };
+    const intentKey = (decision) => JSON.stringify([
+        decision.taskId,
+        decision.nodeId,
+        decision.runNo,
+        decision.workerRef,
+        decision.trigger,
+        decision.underlyingRef ?? null,
+    ]);
+    const signalKey = (signal) => JSON.stringify([
+        signal.trigger,
+        signal.ref,
+        signal.targetWorkerRef,
+        signal.nodeId,
+        signal.runNo,
+    ]);
+    const hasApplied = (taskId, key) => appliedIntents.get(taskId)?.has(key) === true;
+    const rememberApplied = (taskId, key) => {
+        const keys = appliedIntents.get(taskId) ?? new Set();
+        keys.add(key);
+        // This is only a bounded cache. Execution owns durable effect deduplication.
+        if (keys.size > 128) {
+            const oldest = keys.values().next().value;
+            if (oldest !== undefined)
+                keys.delete(oldest);
+        }
+        appliedIntents.set(taskId, keys);
+    };
+    const consumePendingSignal = (taskId, signal) => {
+        if (!signal)
+            return;
+        const signals = pendingSignals.get(taskId);
+        if (signals?.delete(signalKey(signal)))
+            pendingSignalCount -= 1;
+        if (signals?.size === 0)
+            pendingSignals.delete(taskId);
+    };
+    const clearPendingSignals = (taskId) => {
+        pendingSignalCount -= pendingSignals.get(taskId)?.size ?? 0;
+        pendingSignals.delete(taskId);
+    };
+    const markFailure = (taskId) => {
+        const attempt = Math.min((failures.get(taskId)?.attempt ?? 0) + 1, 8);
+        const delay = Math.min(30_000, 500 * 2 ** Math.max(0, attempt - 1));
+        failures.set(taskId, { attempt, nextAt: now() + delay });
+    };
+    const canAttempt = (taskId) => (failures.get(taskId)?.nextAt ?? 0) <= now();
+    const schedulePendingRetry = (taskId) => {
+        if (stopped || !pendingSignals.has(taskId) || retryTimers.has(taskId))
+            return;
+        const delay = Math.max(1, (failures.get(taskId)?.nextAt ?? now()) - now());
+        const retry = setTimeout(() => {
+            retryTimers.delete(taskId);
+            if (!stopped)
+                void reconcile(taskId);
+        }, delay);
+        retry.unref?.();
+        retryTimers.set(taskId, retry);
+    };
+    const retainable = (reason) => reason === "BINDING_NOT_READY" ||
+        reason === "RESUME_TARGET_NOT_CURRENT_WORKER";
+    const reconcileOnce = async (taskId) => {
+        if (stopped || !canAttempt(taskId))
+            return;
+        try {
+            let projection = await options.getProjection(taskId);
+            if (stopped)
+                return;
+            if (projection.terminal) {
+                clearPendingSignals(taskId);
+                appliedIntents.delete(taskId);
+                failures.delete(taskId);
+                return;
+            }
+            await options.ensureWorkers(taskId);
+            if (stopped)
+                return;
+            projection = await options.getProjection(taskId);
+            if (stopped)
+                return;
+            const signals = pendingSignals.get(taskId);
+            const signal = signals?.values().next().value;
+            const decision = decideTaskProgression(projection, signal);
+            if (decision.kind === "STOP_DRIVING") {
+                clearPendingSignals(taskId);
+                appliedIntents.delete(taskId);
+                failures.delete(taskId);
+                return;
+            }
+            if (decision.kind === "NOOP") {
+                if (signal && retainable(decision.reason)) {
+                    // Retain blocked intent, rotating it so another signal can progress.
+                    const key = signalKey(signal);
+                    signals?.delete(key);
+                    signals?.set(key, signal);
+                    markFailure(taskId);
+                }
+                else {
+                    consumePendingSignal(taskId, signal);
+                    failures.delete(taskId);
+                }
+                return;
+            }
+            const key = intentKey(decision);
+            if (!hasApplied(taskId, key)) {
+                await options.requestWake(decision);
+                if (stopped)
+                    return;
+                rememberApplied(taskId, key);
+            }
+            consumePendingSignal(taskId, signal);
+            failures.delete(taskId);
+        }
+        catch {
+            if (!stopped)
+                markFailure(taskId);
+        }
+    };
+    const reconcile = (taskId, signal) => {
+        if (stopped)
+            return Promise.resolve();
+        const signals = pendingSignals.get(taskId);
+        const key = signal ? signalKey(signal) : undefined;
+        if (!admittedTasks.has(taskId) && admittedTasks.size >= maxPendingTasks)
+            throw new Error("TASK_RECONCILIATION_CAPACITY_EXCEEDED");
+        if (key && !signals?.has(key) && pendingSignalCount >= maxPendingSignals)
+            throw new Error("TASK_RECONCILIATION_SIGNAL_CAPACITY_EXCEEDED");
+        admittedTasks.add(taskId);
+        if (signal && key && !signals?.has(key)) {
+            const queue = signals ?? new Map();
+            queue.set(key, signal);
+            pendingSignals.set(taskId, queue);
+            pendingSignalCount += 1;
+        }
+        const retry = retryTimers.get(taskId);
+        if (retry) {
+            clearTimeout(retry);
+            retryTimers.delete(taskId);
+        }
+        const current = taskInFlight.get(taskId);
+        if (current)
+            return current;
+        const run = (async () => {
+            if (!(await acquireSlot()))
+                return;
+            try {
+                await reconcileOnce(taskId);
+            }
+            finally {
+                releaseSlot();
+            }
+        })().finally(() => {
+            taskInFlight.delete(taskId);
+            if (!stopped && pendingSignals.has(taskId))
+                schedulePendingRetry(taskId);
+            else
+                admittedTasks.delete(taskId);
+        });
+        taskInFlight.set(taskId, run);
+        return run;
+    };
+    const processExecutionSignal = async (raw) => {
+        if (stopped ||
+            typeof raw !== "object" ||
+            raw === null ||
+            Array.isArray(raw))
+            return;
+        const signal = raw;
+        if (typeof signal.signalRef !== "string")
+            return;
+        if (signal.kind === "UNKNOWN_REALITY") {
+            await options.acknowledgeExecutionSignal(signal.signalRef);
+            return;
+        }
+        if (signal.kind !== "RECOVERY_RESUME")
+            return;
+        if (typeof signal.executionRef !== "string" ||
+            typeof signal.taskId !== "string" ||
+            typeof signal.workerRef !== "string")
+            return;
+        if (typeof signal.nodeId !== "string" ||
+            !Number.isInteger(signal.runNo) ||
+            Number(signal.runNo) <= 0) {
+            await options.acknowledgeExecutionSignal(signal.signalRef);
+            return;
+        }
+        const resumeSignal = {
+            trigger: "RECOVERY_RESUME",
+            ref: signal.executionRef,
+            targetWorkerRef: signal.workerRef,
+            nodeId: signal.nodeId,
+            runNo: Number(signal.runNo),
+        };
+        await reconcile(signal.taskId, resumeSignal);
+        if (stopped)
+            return;
+        const projection = await options.getProjection(signal.taskId);
+        if (stopped)
+            return;
+        const decision = decideTaskProgression(projection, resumeSignal);
+        if (decision.kind === "STOP_DRIVING" ||
+            (decision.kind === "WAKE" &&
+                hasApplied(signal.taskId, intentKey(decision))) ||
+            (decision.kind === "NOOP" && !retainable(decision.reason)))
+            await options.acknowledgeExecutionSignal(signal.signalRef);
+    };
+    const processExecutionSignals = async () => {
+        if (stopped)
+            return;
+        const signals = (await options.listExecutionSignals()).slice(0, 100);
+        for (let index = 0; !stopped && index < signals.length; index += concurrency)
+            await Promise.all(signals
+                .slice(index, index + concurrency)
+                .map((signal) => processExecutionSignal(signal).catch(() => undefined)));
+    };
+    const sweep = () => {
+        if (stopped)
+            return Promise.resolve();
+        if (sweepInFlight)
+            return sweepInFlight;
+        sweepInFlight = (async () => {
+            await processExecutionSignals().catch(() => undefined);
+            if (stopped)
+                return;
+            let page = await options.listTaskPage({
+                ...(taskCursor ? { afterTaskId: taskCursor } : {}),
+                limit: pageSize,
+            });
+            if (stopped)
+                return;
+            if (page.taskIds.length === 0 && taskCursor !== undefined) {
+                taskCursor = undefined;
+                page = await options.listTaskPage({ limit: pageSize });
+                if (stopped)
+                    return;
+            }
+            taskCursor = page.nextAfterTaskId;
+            // A page uses the same bounded admission and slots as kicks and retries.
+            for (let index = 0; !stopped && index < page.taskIds.length; index += concurrency)
+                await Promise.all(page.taskIds.slice(index, index + concurrency).map(async (taskId) => {
+                    await reconcile(taskId);
+                }));
+        })()
+            .catch(() => undefined)
+            .finally(() => {
+            sweepInFlight = null;
+        });
+        return sweepInFlight;
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        timer = setTimeout(() => {
+            void sweep().finally(schedule);
+        }, intervalMs);
+        timer.unref?.();
+    };
+    return Object.freeze({
+        start() {
+            if (stopped)
+                throw new Error("RECONCILIATION_COORDINATOR_STOPPED");
+            if (started)
+                return;
+            started = true;
+            void sweep();
+            schedule();
+        },
+        kick(taskId, signal) {
+            // Capacity errors are synchronous: never report acceptance after dropping intent.
+            void reconcile(taskId, signal);
+        },
+        reconcile,
+        sweep,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            for (const retry of retryTimers.values())
+                clearTimeout(retry);
+            retryTimers.clear();
+            for (const waiter of slotWaiters.splice(0))
+                waiter(false);
+            pendingSignals.clear();
+            pendingSignalCount = 0;
+            admittedTasks.clear();
+            failures.clear();
+            appliedIntents.clear();
+        },
+    });
+}

package/dist/src/role-operations.d.ts

@@ -1,9 +1,7 @@
 export declare const rolePackageRefs: readonly ["@tomflow/proflow-agent-product", "@tomflow/proflow-agent-controller-dev", "@tomflow/proflow-agent-test-ops"];
 export type RolePackageRef = (typeof rolePackageRefs)[number];
-/**
- * Canonical platform-host authorization inventory for shipped Custom GPT
- * operations. This module is internal (not a package export); Role packages
- * continue to own the shipped OpenAPI documents while the Host owns runtime
- * authorization. Batch 6 mechanically reconciles the two inventories.
- */
+export declare const directToolActionIds: readonly ["repomix", "localDev", "codeGraph"];
+export type DirectToolActionId = (typeof directToolActionIds)[number];
+export declare function roleAllowsDirectToolOperation(role: RolePackageRef, tool: DirectToolActionId, operation: string, input: Record<string, unknown>): boolean;
+/** Canonical platform-host authorization inventory for shipped Custom GPT operations. */
 export declare const roleOperations: Record<RolePackageRef, ReadonlySet<string>>;

package/dist/src/role-operations.js

@@ -3,12 +3,40 @@ export const rolePackageRefs = [
     "@tomflow/proflow-agent-controller-dev",
     "@tomflow/proflow-agent-test-ops",
 ];
-/**
- * Canonical platform-host authorization inventory for shipped Custom GPT
- * operations. This module is internal (not a package export); Role packages
- * continue to own the shipped OpenAPI documents while the Host owns runtime
- * authorization. Batch 6 mechanically reconciles the two inventories.
- */
+export const directToolActionIds = [
+    "repomix",
+    "localDev",
+    "codeGraph",
+];
+const directToolOperations = {
+    "@tomflow/proflow-agent-product": {
+        repomix: new Set(["pack", "grep", "read"]),
+        localDev: new Set(["read", "list", "search", "process"]),
+        codeGraph: new Set(["explore"]),
+    },
+    "@tomflow/proflow-agent-controller-dev": {
+        repomix: new Set(["pack", "grep", "read"]),
+        localDev: new Set(["read", "list", "search", "mutate", "run", "process"]),
+        codeGraph: new Set(["explore"]),
+    },
+    "@tomflow/proflow-agent-test-ops": {
+        repomix: new Set(["pack", "grep", "read"]),
+        localDev: new Set(["read", "list", "search", "run", "process"]),
+        codeGraph: new Set(["explore"]),
+    },
+};
+const productProcessReads = new Set(["list", "ports", "status", "read"]);
+export function roleAllowsDirectToolOperation(role, tool, operation, input) {
+    if (!directToolOperations[role][tool].has(operation))
+        return false;
+    if (role === "@tomflow/proflow-agent-product" &&
+        tool === "localDev" &&
+        operation === "process") {
+        return (typeof input.action === "string" && productProcessReads.has(input.action));
+    }
+    return true;
+}
+/** Canonical platform-host authorization inventory for shipped Custom GPT operations. */
 export const roleOperations = {
     "@tomflow/proflow-agent-product": new Set([
         "getTask",
@@ -16,6 +44,7 @@ export const roleOperations = {
         "getTaskDocument",
         "askPeer",
         "replyPeer",
+        ...directToolActionIds,
     ]),
     "@tomflow/proflow-agent-controller-dev": new Set([
         "getTask",
@@ -29,9 +58,7 @@ export const roleOperations = {
         "putTaskDocument",
         "askPeer",
         "replyPeer",
-        "executeCapability",
-        "getExecution",
-        "readExecutionOutput",
+        ...directToolActionIds,
     ]),
     "@tomflow/proflow-agent-test-ops": new Set([
         "getTask",
@@ -44,8 +71,6 @@ export const roleOperations = {
         "putTaskDocument",
         "askPeer",
         "replyPeer",
-        "executeCapability",
-        "getExecution",
-        "readExecutionOutput",
+        ...directToolActionIds,
     ]),
 };

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

@@ -0,0 +1,49 @@
+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;
+    resumeSignalRef: string | null;
+};
+export type TaskResumeSignal = {
+    trigger: "EXECUTION_RESULT_READY" | "PEER_REPLY_READY" | "RECOVERY_RESUME" | "TASK_RESUMED";
+    ref: string;
+    targetWorkerRef: string;
+    nodeId: string;
+    runNo: number;
+};
+export type TaskProgressionDecision = {
+    kind: "WAKE";
+    taskId: string;
+    nodeId: string;
+    runNo: number;
+    roleRef: string;
+    workerRef: string;
+    trigger: string;
+    conversationLocator: string;
+    underlyingRef?: string;
+} | {
+    kind: "STOP_DRIVING";
+    taskId: string;
+    reason: "TERMINAL";
+} | {
+    kind: "NOOP";
+    taskId: string;
+    reason: string;
+};
+export declare function decideTaskProgression(projection: TaskDriveProjection, resumeSignal?: TaskResumeSignal): TaskProgressionDecision;

package/dist/src/task-observer.js

@@ -0,0 +1,90 @@
+export function decideTaskProgression(projection, resumeSignal) {
+    if (projection.terminal)
+        return {
+            kind: "STOP_DRIVING",
+            taskId: projection.taskId,
+            reason: "TERMINAL",
+        };
+    if (projection.currentNode === null)
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "NO_CURRENT_NODE",
+        };
+    const node = projection.currentNode;
+    const binding = projection.roleBinding;
+    if (!binding?.workerRef ||
+        !binding.conversationLocator ||
+        binding.agentPackageRef !== node.requiredAgentPackageRef)
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "BINDING_NOT_READY",
+        };
+    if (node.status === "READY") {
+        if (!projection.canDrive)
+            return {
+                kind: "NOOP",
+                taskId: projection.taskId,
+                reason: "BINDING_NOT_READY",
+            };
+        return {
+            kind: "WAKE",
+            taskId: projection.taskId,
+            nodeId: node.nodeId,
+            runNo: node.runNo,
+            roleRef: binding.roleRef,
+            workerRef: binding.workerRef,
+            trigger: node.runNo > 1 ? "REOPEN" : "NODE_READY",
+            conversationLocator: binding.conversationLocator,
+        };
+    }
+    const effectiveResumeSignal = resumeSignal ??
+        (projection.resumeSignalRef &&
+            projection.taskStatus === "ACTIVE" &&
+            node.status === "IN_PROGRESS"
+            ? {
+                trigger: "TASK_RESUMED",
+                ref: projection.resumeSignalRef,
+                targetWorkerRef: binding.workerRef,
+                nodeId: node.nodeId,
+                runNo: node.runNo,
+            }
+            : undefined);
+    if (!effectiveResumeSignal)
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "NO_PROGRESS_INTENT",
+        };
+    if (projection.taskStatus !== "ACTIVE" || node.status !== "IN_PROGRESS")
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "BINDING_NOT_READY",
+        };
+    if (effectiveResumeSignal.nodeId !== node.nodeId ||
+        effectiveResumeSignal.runNo !== node.runNo)
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "RESUME_GENERATION_MISMATCH",
+        };
+    if (effectiveResumeSignal.targetWorkerRef !== binding.workerRef)
+        return {
+            kind: "NOOP",
+            taskId: projection.taskId,
+            reason: "RESUME_TARGET_NOT_CURRENT_WORKER",
+        };
+    return {
+        kind: "WAKE",
+        taskId: projection.taskId,
+        nodeId: node.nodeId,
+        runNo: node.runNo,
+        roleRef: binding.roleRef,
+        workerRef: binding.workerRef,
+        trigger: effectiveResumeSignal.trigger,
+        conversationLocator: binding.conversationLocator,
+        underlyingRef: effectiveResumeSignal.ref,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-host",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -24,19 +24,19 @@
   ],
   "dependencies": {
     "zod": "4.1.12",
+    "@tomflow/proflow-execution-browser-extension": "^0.1.51",
     "@tomflow/proflow-agent-runtime": "^0.1.14",
-    "@tomflow/proflow-task-orchestration": "^0.1.11",
-    "@tomflow/proflow-execution-contracts": "^0.1.10",
     "@tomflow/proflow-module-contract": "^0.1.13",
-    "@tomflow/proflow-execution-browser-extension": "^0.1.50",
+    "@tomflow/proflow-task-orchestration": "^0.1.11",
     "@tomflow/proflow-task-migration-runner": "^0.1.11",
-    "@tomflow/proflow-task-store-sqlite": "^0.1.11"
+    "@tomflow/proflow-execution-contracts": "^0.1.11",
+    "@tomflow/proflow-task-store-sqlite": "^0.1.12"
   },
   "devDependencies": {
-    "@tomflow/proflow-agent-gateway": "^0.1.16",
+    "@tomflow/proflow-agent-gateway": "^0.1.17",
     "@tomflow/proflow-deployment-conformance": "^0.1.13",
     "@tomflow/proflow-model-runtime": "^0.1.24",
-    "@tomflow/proflow-execution-runtime": "^0.1.18"
+    "@tomflow/proflow-execution-runtime": "^0.1.19"
   },
   "description": "Provides the ProFlow local application composition root that binds Task, Agent, Execution and Model owner transports.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-host",
 	"packageName": "@tomflow/proflow-platform-host",
-	"moduleVersion": "0.1.21",
+	"moduleVersion": "0.1.23",
 	"kind": "service",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
@@ -19,19 +19,15 @@
 	],
 	"requires": [
 		{
-			"contractRef": "task-orchestration",
+			"contractRef": "local-tool-bridge",
 			"versionRange": ">=1.0.0 <2.0.0"
 		},
 		{
-			"contractRef": "agent-runtime",
-			"versionRange": ">=1.0.0 <2.0.0"
-		},
-		{
-			"contractRef": "execution",
+			"contractRef": "task-orchestration",
 			"versionRange": ">=1.0.0 <2.0.0"
 		},
 		{
-			"contractRef": "model-inference",
+			"contractRef": "agent-runtime",
 			"versionRange": ">=1.0.0 <2.0.0"
 		}
 	],