@skillcap/gdh 0.13.3 → 0.15.0

package/node_modules/@gdh/runtime/dist/index.js

@@ -1552,6 +1552,24 @@ const HOST_RUNTIME_BRIDGE_ENTRIES = [
         executionRoute: null,
         safetyLevel: "read_only",
     },
+    {
+        id: "state.node_presence.await",
+        summary: "Wait for one exact node path to become present or absent through bounded polling.",
+        kind: "waiter",
+        shape: "composite",
+        source: "core",
+        executionRoute: null,
+        safetyLevel: "read_only",
+    },
+    {
+        id: "state.signal.await",
+        summary: "Wait for one observed signal emission to occur after an optional observed-count baseline.",
+        kind: "waiter",
+        shape: "composite",
+        source: "core",
+        executionRoute: null,
+        safetyLevel: "read_only",
+    },
 ];
 export function createRuntimeBridgeManager() {
     const sessions = new Map();
@@ -1816,6 +1834,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" was not found.`,
                     reasons: ["bridge_session_not_found"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: null,
                 };
             }
@@ -1827,6 +1846,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" is no longer active.`,
                     reasons: ["bridge_session_not_active"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1838,6 +1858,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Runtime bridge session "${sessionId}" is already handling another invocation.`,
                     reasons: ["bridge_session_busy"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1864,6 +1885,7 @@ export function createRuntimeBridgeManager() {
                             : `Bridge entry "${entryId}" returned state "${syntheticResponse.state}".`,
                         reasons: syntheticResponse.error ? [syntheticResponse.error] : [],
                         result: syntheticResponse.result,
+                        waiterEvidence: syntheticResponse.waiterEvidence,
                         transcriptPath: session.transcriptPath,
                     };
                 }
@@ -1883,6 +1905,7 @@ export function createRuntimeBridgeManager() {
                         : `Bridge entry "${entryId}" returned state "${response.state}".`,
                     reasons: response.error ? [response.error] : [],
                     result: response.result,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1898,6 +1921,7 @@ export function createRuntimeBridgeManager() {
                     summary: `Bridge entry "${entryId}" failed: ${formatBridgeError(error)}.`,
                     reasons: ["bridge_invoke_failed"],
                     result: null,
+                    waiterEvidence: null,
                     transcriptPath: session.transcriptPath,
                 };
             }
@@ -1998,11 +2022,53 @@ function mergeRuntimeBridgeEntries(entries) {
     return merged;
 }
 async function invokeSyntheticBridgeEntry(session, entryId, inputValue) {
+    if (entryId === "screenshot.capture") {
+        return invokeScreenshotCaptureEntry(session, inputValue);
+    }
     if (entryId === "state.node_property.await") {
         return invokeNodePropertyAwaitEntry(session, inputValue);
     }
+    if (entryId === "state.node_presence.await") {
+        return invokeNodePresenceAwaitEntry(session, inputValue);
+    }
+    if (entryId === "state.signal.await") {
+        return invokeSignalAwaitEntry(session, inputValue);
+    }
     return null;
 }
+async function invokeScreenshotCaptureEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const label = typeof input["label"] === "string" ? input["label"] : "screenshot";
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const basename = `${stamp}-${sanitizeScreenshotLabel(label)}`;
+    const screenshotDirectory = path.join(session.artifactDirectory, "screenshots");
+    const imagePath = path.join(screenshotDirectory, `${basename}.png`);
+    const metadataPath = path.join(screenshotDirectory, `${basename}.json`);
+    await fs.mkdir(path.dirname(imagePath), { recursive: true });
+    await fs.mkdir(path.dirname(metadataPath), { recursive: true });
+    recordBridgeEvent(session, "screenshot_capture_requested", {
+        imagePath,
+        metadataPath,
+    });
+    const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "screenshot.capture", {
+        ...input,
+        imagePath,
+        metadataPath,
+    });
+    recordBridgeEvent(session, "screenshot_capture_response", {
+        state: response.state,
+        result: response.result,
+        error: response.error,
+        imagePath,
+        metadataPath,
+    });
+    return {
+        state: response.state,
+        result: response.result,
+        error: response.error,
+        waiterEvidence: null,
+    };
+}
 async function invokeNodePropertyAwaitEntry(session, inputValue) {
     const input = toJsonRecord(inputValue);
     const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
@@ -2016,6 +2082,7 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
             state: "failed",
             result: null,
             error: "state.node_property.await requires nodePath and property.",
+            waiterEvidence: null,
         };
     }
     if (!hasExpected) {
@@ -2023,12 +2090,20 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
             state: "failed",
             result: null,
             error: "state.node_property.await requires an expected value.",
+            waiterEvidence: null,
         };
     }
-    const startedAt = Date.now();
+    const target = {
+        nodePath,
+        property,
+        expected,
+    };
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    recordWaiterStarted(session, "state.node_property.await", target, timeoutMs, pollIntervalMs);
     let attempts = 0;
     let lastValue = null;
-    while (Date.now() - startedAt <= timeoutMs) {
+    while (Date.now() - startedAtMs <= timeoutMs) {
         attempts += 1;
         recordBridgeEvent(session, "invoke_expanded_leaf_step", {
             parentEntryId: "state.node_property.await",
@@ -2056,37 +2131,326 @@ async function invokeNodePropertyAwaitEntry(session, inputValue) {
                 state: response.state,
                 result: response.result,
                 error: response.error,
+                waiterEvidence: null,
             };
         }
         const payload = toJsonRecord(response.result);
         lastValue = (payload["value"] ?? null);
         if (jsonValuesEqual(lastValue, expected)) {
+            const result = {
+                nodePath,
+                property,
+                expected,
+                value: lastValue,
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.node_property.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.node_property.await", target, attempts, result);
             return {
                 state: "ok",
-                result: {
-                    nodePath,
-                    property,
-                    expected,
-                    value: lastValue,
-                    attempts,
-                    elapsedMs: Date.now() - startedAt,
-                },
+                result,
                 error: null,
+                waiterEvidence,
             };
         }
         await waitMs(pollIntervalMs);
     }
+    const result = {
+        nodePath,
+        property,
+        expected,
+        value: lastValue,
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.node_property.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.node_property.await", target, attempts, result);
     return {
         state: "unavailable",
-        result: {
+        result,
+        error: "Timed out waiting for the requested node property value.",
+        waiterEvidence,
+    };
+}
+async function invokeNodePresenceAwaitEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
+    const expected = typeof input["expected"] === "string" ? input["expected"] : "";
+    const timeoutMs = clampNumber(input["timeoutMs"], 1500, 100, 5000);
+    const pollIntervalMs = clampNumber(input["pollIntervalMs"], 50, 25, 250);
+    if (nodePath.length === 0) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.node_presence.await requires nodePath.",
+            waiterEvidence: null,
+        };
+    }
+    if (expected !== "present" && expected !== "absent") {
+        return {
+            state: "failed",
+            result: null,
+            error: 'state.node_presence.await requires expected = "present" or "absent".',
+            waiterEvidence: null,
+        };
+    }
+    const target = {
+        nodePath,
+        expected,
+    };
+    recordWaiterStarted(session, "state.node_presence.await", target, timeoutMs, pollIntervalMs);
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    let attempts = 0;
+    let lastSnapshot = null;
+    while (Date.now() - startedAtMs <= timeoutMs) {
+        attempts += 1;
+        recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+            parentEntryId: "state.node_presence.await",
+            leafEntryId: "state.node_presence.get",
+            attempt: attempts,
+            input: {
+                nodePath,
+            },
+        });
+        const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.node_presence.get", {
             nodePath,
-            property,
-            expected,
-            value: lastValue,
-            attempts,
-            elapsedMs: Date.now() - startedAt,
+        });
+        recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+            parentEntryId: "state.node_presence.await",
+            leafEntryId: "state.node_presence.get",
+            attempt: attempts,
+            state: response.state,
+            result: response.result,
+            error: response.error,
+        });
+        if (response.state !== "ok") {
+            return {
+                state: response.state,
+                result: response.result,
+                error: response.error,
+                waiterEvidence: null,
+            };
+        }
+        const payload = toJsonRecord(response.result);
+        lastSnapshot = payload;
+        const present = payload["present"] === true;
+        const matches = expected === "present" ? present : !present;
+        if (matches) {
+            const result = {
+                nodePath,
+                expected,
+                present,
+                name: (payload["name"] ?? null),
+                className: (payload["className"] ?? null),
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.node_presence.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.node_presence.await", target, attempts, result);
+            return {
+                state: "ok",
+                result,
+                error: null,
+                waiterEvidence,
+            };
+        }
+        await waitMs(pollIntervalMs);
+    }
+    const result = {
+        nodePath,
+        expected,
+        present: lastSnapshot?.["present"] === true,
+        name: (lastSnapshot?.["name"] ?? null),
+        className: (lastSnapshot?.["className"] ?? null),
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.node_presence.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.node_presence.await", target, attempts, result);
+    return {
+        state: "unavailable",
+        result,
+        error: "Timed out waiting for the requested node presence state.",
+        waiterEvidence,
+    };
+}
+async function invokeSignalAwaitEntry(session, inputValue) {
+    const input = toJsonRecord(inputValue);
+    const nodePath = typeof input["nodePath"] === "string" ? input["nodePath"] : "";
+    const signalName = typeof input["signalName"] === "string" ? input["signalName"] : "";
+    const afterCount = clampCount(input["afterCount"], 0);
+    const timeoutMs = clampNumber(input["timeoutMs"], 1500, 100, 5000);
+    const pollIntervalMs = clampNumber(input["pollIntervalMs"], 50, 25, 250);
+    if (nodePath.length === 0 || signalName.length === 0) {
+        return {
+            state: "failed",
+            result: null,
+            error: "state.signal.await requires nodePath and signalName.",
+            waiterEvidence: null,
+        };
+    }
+    const target = {
+        nodePath,
+        signalName,
+        afterCount,
+    };
+    recordWaiterStarted(session, "state.signal.await", target, timeoutMs, pollIntervalMs);
+    recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+        parentEntryId: "state.signal.await",
+        leafEntryId: "state.signal_observation.start",
+        attempt: 1,
+        input: {
+            nodePath,
+            signalName,
         },
-        error: "Timed out waiting for the requested node property value.",
+    });
+    const startResponse = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.signal_observation.start", {
+        nodePath,
+        signalName,
+    });
+    recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+        parentEntryId: "state.signal.await",
+        leafEntryId: "state.signal_observation.start",
+        attempt: 1,
+        state: startResponse.state,
+        result: startResponse.result,
+        error: startResponse.error,
+    });
+    if (startResponse.state !== "ok") {
+        return {
+            state: startResponse.state,
+            result: startResponse.result,
+            error: startResponse.error,
+            waiterEvidence: null,
+        };
+    }
+    const startedAt = new Date().toISOString();
+    const startedAtMs = Date.now();
+    let attempts = 0;
+    let lastSnapshot = null;
+    while (Date.now() - startedAtMs <= timeoutMs) {
+        attempts += 1;
+        recordBridgeEvent(session, "invoke_expanded_leaf_step", {
+            parentEntryId: "state.signal.await",
+            leafEntryId: "state.signal_observation.get",
+            attempt: attempts,
+            input: {
+                nodePath,
+                signalName,
+            },
+        });
+        const response = await invokeBridgeEntryOverSocket(session.ws, session.sessionId, "state.signal_observation.get", {
+            nodePath,
+            signalName,
+        });
+        recordBridgeEvent(session, "invoke_expanded_leaf_response", {
+            parentEntryId: "state.signal.await",
+            leafEntryId: "state.signal_observation.get",
+            attempt: attempts,
+            state: response.state,
+            result: response.result,
+            error: response.error,
+        });
+        if (response.state !== "ok") {
+            return {
+                state: response.state,
+                result: response.result,
+                error: response.error,
+                waiterEvidence: null,
+            };
+        }
+        const payload = toJsonRecord(response.result);
+        lastSnapshot = payload;
+        const count = clampCount(payload["count"], 0);
+        if (count > afterCount) {
+            const result = {
+                nodePath,
+                signalName,
+                afterCount,
+                count,
+                lastObservedAt: (payload["lastObservedAt"] ?? null),
+                lastPayload: (payload["lastPayload"] ?? null),
+                attempts,
+                elapsedMs: Date.now() - startedAtMs,
+            };
+            const waiterEvidence = buildWaiterEvidence({
+                waiterId: "state.signal.await",
+                outcome: "satisfied",
+                startedAt,
+                timeoutMs,
+                pollCount: attempts,
+                target,
+                result,
+            });
+            recordWaiterSatisfied(session, "state.signal.await", target, attempts, result);
+            return {
+                state: "ok",
+                result,
+                error: null,
+                waiterEvidence,
+            };
+        }
+        await waitMs(pollIntervalMs);
+    }
+    const result = {
+        nodePath,
+        signalName,
+        afterCount,
+        count: clampCount(lastSnapshot?.["count"], 0),
+        lastObservedAt: (lastSnapshot?.["lastObservedAt"] ?? null),
+        lastPayload: (lastSnapshot?.["lastPayload"] ?? null),
+        attempts,
+        elapsedMs: Date.now() - startedAtMs,
+    };
+    const waiterEvidence = buildWaiterEvidence({
+        waiterId: "state.signal.await",
+        outcome: "timed_out",
+        startedAt,
+        timeoutMs,
+        pollCount: attempts,
+        target,
+        result,
+    });
+    recordWaiterTimedOut(session, "state.signal.await", target, attempts, result);
+    return {
+        state: "unavailable",
+        result,
+        error: "Timed out waiting for the requested signal emission.",
+        waiterEvidence,
     };
 }
 function toJsonRecord(value) {
@@ -2101,6 +2465,16 @@ function clampNumber(value, fallback, minimum, maximum) {
     }
     return Math.max(minimum, Math.min(maximum, Math.trunc(value)));
 }
+function clampCount(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(0, Math.trunc(value));
+}
+function sanitizeScreenshotLabel(value) {
+    const sanitized = value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return (sanitized || "screenshot").slice(0, 80);
+}
 function jsonValuesEqual(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
@@ -2125,6 +2499,42 @@ function recordBridgeEvent(session, event, payload) {
         ...payload,
     });
 }
+function recordWaiterStarted(session, entryId, target, timeoutMs, pollIntervalMs) {
+    recordBridgeEvent(session, "invoke_waiter_started", {
+        entryId,
+        target,
+        timeoutMs,
+        pollIntervalMs,
+    });
+}
+function recordWaiterSatisfied(session, entryId, target, attempts, result) {
+    recordBridgeEvent(session, "invoke_waiter_satisfied", {
+        entryId,
+        target,
+        attempts,
+        result,
+    });
+}
+function recordWaiterTimedOut(session, entryId, target, attempts, result) {
+    recordBridgeEvent(session, "invoke_waiter_timed_out", {
+        entryId,
+        target,
+        attempts,
+        result,
+    });
+}
+function buildWaiterEvidence(input) {
+    return {
+        waiterId: input.waiterId,
+        outcome: input.outcome,
+        startedAt: input.startedAt,
+        finishedAt: new Date().toISOString(),
+        timeoutMs: input.timeoutMs,
+        pollCount: input.pollCount,
+        target: input.target,
+        result: input.result,
+    };
+}
 function bridgeMissing(reason) {
     return {
         required: true,