@awak-app/simy-cli 0.5.33 → 0.5.35

package/src/workflow-observation-sender.js

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import { webApiHeaders, webApiUrl } from "./web-api.js";
 
 const DIGEST = /^sha256:[0-9a-f]{64}$/;
@@ -5,16 +7,56 @@ const SOURCE_REF = /^(codex|claude):[0-9a-f]{64}$/;
 const WORKFLOW_UUID =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
+export const WORKFLOW_START_PATH = "workflow-dev-work-events/start";
+export const WORKFLOW_TERMINAL_PATH = "workflow-dev-work-events/terminal";
+export const TERMINAL_CONTRACT_VERSION = "independent_workflow_terminal_observation.v1";
+const REQUEST_TIMEOUT_MS = 10_000;
+const START_ATTEMPTS = 3;
+const TERMINAL_ATTEMPTS = 2;
+
+export function normalizeWorkflowStartIntent(value, { provider = null } = {}) {
+  if (value === undefined || value === null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw bindingError();
+  const keys = Object.keys(value).sort();
+  const expected = ["idempotency_key", "source_ref", "workflow_id"];
+  if (
+    keys.length !== expected.length ||
+    keys.some((key, index) => key !== expected[index]) ||
+    typeof value.workflow_id !== "string" ||
+    !WORKFLOW_UUID.test(value.workflow_id) ||
+    typeof value.source_ref !== "string" ||
+    !SOURCE_REF.test(value.source_ref) ||
+    typeof value.idempotency_key !== "string" ||
+    value.idempotency_key.length < 8 ||
+    value.idempotency_key.length > 200 ||
+    (provider !== null && !value.source_ref.startsWith(`${provider}:`))
+  ) throw bindingError();
+  // UUIDs are validated case-insensitively, so they are compared only in the
+  // canonical lowercase form that crew/Web return (Python str(UUID)).
+  return Object.freeze({
+    workflow_id: value.workflow_id.toLowerCase(),
+    source_ref: String(value.source_ref),
+    idempotency_key: String(value.idempotency_key),
+  });
+}
+
 export function normalizeWorkflowObservationBinding(value, { provider = null } = {}) {
   if (value === undefined || value === null) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw bindingError();
   }
+  // `terminal_contract` is optional: Web adds it only for independent WorkFlow
+  // runs whose terminal must use the typed dev-work event intake (G2). Its only
+  // allowed value is the typed terminal contract version.
+  const typed = Object.hasOwn(value, "terminal_contract");
   const keys = Object.keys(value).sort();
-  const expected = ["action_digest", "source_ref", "workflow_id", "workflow_run_id"];
+  const expected = typed
+    ? ["action_digest", "source_ref", "terminal_contract", "workflow_id", "workflow_run_id"]
+    : ["action_digest", "source_ref", "workflow_id", "workflow_run_id"];
   if (
     keys.length !== expected.length ||
     keys.some((key, index) => key !== expected[index]) ||
+    (typed && value.terminal_contract !== TERMINAL_CONTRACT_VERSION) ||
     !WORKFLOW_UUID.test(String(value.workflow_id || "")) ||
     !WORKFLOW_UUID.test(String(value.workflow_run_id || "")) ||
     !DIGEST.test(String(value.action_digest || "")) ||
@@ -24,34 +66,271 @@ export function normalizeWorkflowObservationBinding(value, { provider = null } =
     throw bindingError();
   }
   return Object.freeze({
-    workflow_id: String(value.workflow_id),
-    workflow_run_id: String(value.workflow_run_id),
+    workflow_id: String(value.workflow_id).toLowerCase(),
+    workflow_run_id: String(value.workflow_run_id).toLowerCase(),
     action_digest: String(value.action_digest),
     source_ref: String(value.source_ref),
+    ...(typed ? { terminal_contract: TERMINAL_CONTRACT_VERSION } : {}),
   });
 }
 
 export function createWorkflowObservationSender({
   binding,
+  startIntent = null,
   backend,
   session,
   apiOrigin,
   fetchImpl = globalThis.fetch,
   now = () => new Date(),
 }) {
-  const normalizedBinding = normalizeWorkflowObservationBinding(binding, { provider: backend });
-  if (!normalizedBinding) return null;
+  let normalizedBinding = normalizeWorkflowObservationBinding(binding, { provider: backend });
+  const normalizedIntent = normalizeWorkflowStartIntent(startIntent, { provider: backend });
+  if (!normalizedBinding && !normalizedIntent) return null;
+  if (normalizedBinding && normalizedIntent) throw bindingError();
   if (backend !== "codex" && backend !== "claude") {
     throw new Error("WorkFlow observation provider must be codex or claude.");
   }
 
   let providerSessionId = null;
   let terminal = null;
+  let startPromise = null;
+  let admittedAtMs = null;
+
+  async function post(path, body, attempts) {
+    let response = null;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        response = await fetchImpl(
+          webApiUrl(path, { webOrigin: apiOrigin, apiBaseUrl: session.api_base_url }),
+          {
+            method: "POST",
+            headers: webApiHeaders(
+              { token: session.token },
+              { "Content-Type": "application/json" },
+            ),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+          },
+        );
+      } catch {
+        // Network failure or timeout: the idempotency key makes a resend safe.
+        response = null;
+        continue;
+      }
+      if (response.status < 500) break;
+    }
+    if (!response) return { response: null, payload: null };
+    const payload = await response.json().catch(() => null);
+    return { response, payload };
+  }
+
+  async function startFromEvent(eventType) {
+    if (!session?.token || !session?.api_base_url) {
+      return { ok: false, reason_code: "device_session_unavailable" };
+    }
+    const { response, payload } = await post(
+      WORKFLOW_START_PATH,
+      { provider: backend, event_type: eventType, ...normalizedIntent },
+      START_ATTEMPTS,
+    );
+    if (!response) return { ok: false, reason_code: "workflow_start_service_unavailable" };
+    if (!response.ok) {
+      return {
+        ok: false,
+        reason_code: httpReasonCode(response.status, "workflow_start_not_admitted"),
+        http_status: response.status,
+      };
+    }
+    const invalid = { ok: false, reason_code: "invalid_workflow_start_response" };
+    const admissionTime = Date.parse(payload?.admitted_at);
+    if (!Number.isFinite(admissionTime)) return invalid;
+    const runId = lowerUuid(payload?.workflow_run_id);
+    if (!runId || lowerUuid(payload?.workflow_id) !== normalizedIntent.workflow_id) return invalid;
+    if (payload.status === "already_recorded") {
+      return payload.workflow_observation_binding === null
+        ? { ok: true, alreadyRecorded: true, workflowRunId: runId }
+        : invalid;
+    }
+    if (payload.status !== "observation_pending") return invalid;
+    let admitted;
+    try {
+      admitted = normalizeWorkflowObservationBinding(
+        payload.workflow_observation_binding,
+        { provider: backend },
+      );
+    } catch {
+      return invalid;
+    }
+    if (
+      admitted?.workflow_id !== normalizedIntent.workflow_id ||
+      admitted.source_ref !== normalizedIntent.source_ref ||
+      admitted.workflow_run_id !== runId
+    ) return invalid;
+    normalizedBinding = admitted;
+    admittedAtMs = admissionTime;
+    return { ok: true, alreadyRecorded: false };
+  }
+
+  async function flushStarted() {
+    const started = startPromise ? await startPromise : null;
+    if (!started) {
+      return intentState("failed", null, { reason_code: "provider_start_event_missing" });
+    }
+    if (!started.ok) {
+      const { ok: _ok, ...reason } = started;
+      return intentState("failed", null, reason);
+    }
+    if (started.alreadyRecorded) {
+      return intentState("already_recorded", started.workflowRunId);
+    }
+    if (!terminal) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "provider_terminal_event_missing",
+      });
+    }
+    // A very short provider turn can finish before the start RPC commits.
+    // For a new run, record when the terminal event is submitted after
+    // admission; the event itself remains the real provider event.
+    const observedAt = new Date(Math.max(now().getTime(), admittedAtMs + 1)).toISOString();
+    return sendTypedTerminal({
+      idempotencyKey: terminalIdempotencyKey(normalizedIntent, normalizedBinding),
+      observedAt,
+    });
+  }
+
+  // The typed terminal intake takes one flat 9-key body. It is used for runs
+  // started from a start intent and for Web-bound runs whose binding declares
+  // `terminal_contract` (independent_workflow_terminal_observation.v1).
+  async function sendTypedTerminal({ idempotencyKey, observedAt }) {
+    const body = {
+      provider: backend,
+      event_type: terminal.eventType,
+      outcome: terminal.outcome,
+      workflow_id: normalizedBinding.workflow_id,
+      workflow_run_id: normalizedBinding.workflow_run_id,
+      action_digest: normalizedBinding.action_digest,
+      source_ref: normalizedBinding.source_ref,
+      idempotency_key: idempotencyKey,
+      observed_at: observedAt,
+    };
+    const { response, payload } = await post(WORKFLOW_TERMINAL_PATH, body, TERMINAL_ATTEMPTS);
+    if (!response) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "observation_service_unavailable",
+      });
+    }
+    if (!response.ok) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: httpReasonCode(response.status, "observation_not_accepted"),
+        http_status: response.status,
+      });
+    }
+    if (!validTerminalReceipt(payload, normalizedBinding)) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "invalid_observation_receipt",
+      });
+    }
+    return observationState("accepted", normalizedBinding, {
+      observation_id: payload.observation_id.toLowerCase(),
+      receipt_outcome: payload.outcome,
+    });
+  }
+
+  async function flushBound() {
+    if (!terminal) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "provider_terminal_event_missing",
+      });
+    }
+    if (!providerSessionId) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "provider_session_identity_missing",
+      });
+    }
+    if (!session?.token || !session?.api_base_url) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "device_session_unavailable",
+      });
+    }
+
+    if (normalizedBinding.terminal_contract === TERMINAL_CONTRACT_VERSION) {
+      return sendTypedTerminal({
+        idempotencyKey: boundTerminalIdempotencyKey(normalizedBinding),
+        observedAt: terminal.observedAt,
+      });
+    }
+
+    // Legacy bindings (no terminal_contract) keep the original observations route.
+    const body = {
+      action_digest: normalizedBinding.action_digest,
+      source_ref: normalizedBinding.source_ref,
+      observed_at: terminal.observedAt,
+      event: {
+        provider: backend,
+        type: terminal.eventType,
+        outcome: terminal.outcome,
+      },
+    };
+    const { response, payload } = await post(
+      `workflows/${encodeURIComponent(normalizedBinding.workflow_id)}/runs/${encodeURIComponent(normalizedBinding.workflow_run_id)}/observations`,
+      body,
+      2,
+    );
+    if (!response) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "observation_service_unavailable",
+      });
+    }
+    if (!response.ok) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: httpReasonCode(response.status, "observation_not_accepted", { legacy: true }),
+        http_status: response.status,
+      });
+    }
+    const receipt = payload?.receipt;
+    if (!validReceipt(receipt, normalizedBinding)) {
+      return observationState("failed", normalizedBinding, {
+        reason_code: "invalid_observation_receipt",
+      });
+    }
+    return observationState("accepted", normalizedBinding, {
+      observation_id: receipt.observation_id,
+    });
+  }
+
+  function intentState(status, workflowRunId, extra = {}) {
+    return {
+      status,
+      workflow_id: normalizedIntent.workflow_id,
+      workflow_run_id: workflowRunId,
+      development_outcome: "unverified",
+      ...extra,
+    };
+  }
 
   return {
+    // The Provider's own terminal outcome ("succeeded" | "failed"), or null
+    // before a terminal event. Deliverable upload is gated on "succeeded".
+    terminalOutcome() {
+      return terminal?.outcome ?? null;
+    },
+
+    // The binding the terminal was sent for (admitted binding for start intents).
+    binding() {
+      return normalizedBinding;
+    },
+
     observe(event) {
       if (!event || typeof event !== "object" || terminal) return;
       providerSessionId ||= providerSessionIdentifier(backend, event);
+      if (normalizedIntent && providerSessionId && !startPromise) {
+        const eventType = backend === "codex" ? "thread.started" : "system.init";
+        // startFromEvent never rejects; it resolves to a typed outcome.
+        startPromise = startFromEvent(eventType).catch(() => ({
+          ok: false,
+          reason_code: "workflow_start_service_unavailable",
+        }));
+      }
       const terminalEvent = terminalProviderState(backend, event);
       if (!terminalEvent) return;
       terminal = {
@@ -60,88 +339,72 @@ export function createWorkflowObservationSender({
       };
     },
 
+    // Never rejects: an observation failure must not change the Provider
+    // result or block the run from completing.
     async flush() {
-      if (!terminal) {
-        return observationState("failed", normalizedBinding, {
-          reason_code: "provider_terminal_event_missing",
-        });
-      }
-      if (!providerSessionId) {
-        return observationState("failed", normalizedBinding, {
-          reason_code: "provider_session_identity_missing",
-        });
-      }
-      if (!session?.token || !session?.api_base_url) {
-        return observationState("failed", normalizedBinding, {
-          reason_code: "device_session_unavailable",
-        });
+      try {
+        return normalizedIntent ? await flushStarted() : await flushBound();
+      } catch {
+        return normalizedBinding
+          ? observationState("failed", normalizedBinding, {
+              reason_code: "observation_sender_error",
+            })
+          : intentState("failed", null, { reason_code: "observation_sender_error" });
       }
+    },
+  };
+}
 
-      const body = {
-        action_digest: normalizedBinding.action_digest,
-        source_ref: normalizedBinding.source_ref,
-        observed_at: terminal.observedAt,
-        event: {
-          provider: backend,
-          type: terminal.eventType,
-          outcome: terminal.outcome,
-        },
-      };
+function httpReasonCode(status, fallback, { legacy = false } = {}) {
+  if (status === 401 || status === 403) return "device_or_source_not_authorized";
+  if (status === 404 || status === 410) return "workflow_binding_unavailable";
+  // The pre-bound route keeps its established reason codes.
+  if (status === 409 && !legacy) return "workflow_run_not_current";
+  return fallback;
+}
 
-      let response;
-      for (let attempt = 1; attempt <= 2; attempt += 1) {
-        try {
-          response = await fetchImpl(
-            webApiUrl(
-              `workflows/${encodeURIComponent(normalizedBinding.workflow_id)}/runs/${encodeURIComponent(normalizedBinding.workflow_run_id)}/observations`,
-              {
-              webOrigin: apiOrigin,
-              apiBaseUrl: session.api_base_url,
-              },
-            ),
-            {
-              method: "POST",
-              headers: webApiHeaders(
-                { token: session.token },
-                { "Content-Type": "application/json" },
-              ),
-              body: JSON.stringify(body),
-              signal: AbortSignal.timeout(10_000),
-            },
-          );
-        } catch {
-          if (attempt === 2) {
-            return observationState("failed", normalizedBinding, {
-              reason_code: "observation_service_unavailable",
-            });
-          }
-          continue;
-        }
-        if (response.status < 500 || attempt === 2) break;
-      }
+function terminalIdempotencyKey(intent, binding) {
+  // Stable per started run so a retried or re-flushed terminal event replays
+  // the same observation instead of recording a second one.
+  const digest = createHash("sha256")
+    .update(`${intent.idempotency_key}\u0000${binding.workflow_run_id}`)
+    .digest("hex");
+  return `terminal:${digest}`;
+}
 
-      const payload = await response.json().catch(() => null);
-      if (!response.ok) {
-        return observationState("failed", normalizedBinding, {
-          reason_code: response.status === 401 || response.status === 403
-            ? "device_or_source_not_authorized"
-            : response.status === 404 || response.status === 410
-              ? "workflow_binding_unavailable"
-              : "observation_not_accepted",
-          http_status: response.status,
-        });
-      }
-      const receipt = payload?.receipt;
-      if (!validReceipt(receipt, normalizedBinding)) {
-        return observationState("failed", normalizedBinding, {
-          reason_code: "invalid_observation_receipt",
-        });
-      }
-      return observationState("accepted", normalizedBinding, {
-        observation_id: receipt.observation_id,
-      });
-    },
-  };
+function boundTerminalIdempotencyKey(binding) {
+  // A Web-bound run has no start intent key; the binding identity is stable for
+  // the run attempt, so a resend replays the same observation.
+  const digest = createHash("sha256")
+    .update(
+      `bound\u0000${binding.workflow_run_id}\u0000${binding.action_digest}\u0000${binding.source_ref}`,
+    )
+    .digest("hex");
+  return `terminal:${digest}`;
+}
+
+function validTerminalReceipt(receipt, binding) {
+  const keys = [
+    "action_digest", "contract_version", "observation_id",
+    "outcome", "workflow_id", "workflow_run_id",
+  ];
+  return Boolean(
+    receipt &&
+      typeof receipt === "object" &&
+      !Array.isArray(receipt) &&
+      Object.keys(receipt).length === keys.length &&
+      keys.every((key) => Object.hasOwn(receipt, key)) &&
+      receipt.contract_version === TERMINAL_CONTRACT_VERSION &&
+      (receipt.outcome === "recorded" || receipt.outcome === "idempotent_replay") &&
+      lowerUuid(receipt.workflow_id) === binding.workflow_id &&
+      lowerUuid(receipt.workflow_run_id) === binding.workflow_run_id &&
+      receipt.action_digest === binding.action_digest &&
+      lowerUuid(receipt.observation_id) !== null,
+  );
+}
+
+function lowerUuid(value) {
+  return typeof value === "string" && WORKFLOW_UUID.test(value) ? value.toLowerCase() : null;
 }
 
 function providerSessionIdentifier(backend, event) {
@@ -179,10 +442,9 @@ function validReceipt(receipt, binding) {
     receipt &&
       typeof receipt === "object" &&
       receipt.accepted === true &&
-      receipt.workflow_id === binding.workflow_id &&
-      receipt.workflow_run_id === binding.workflow_run_id &&
-      typeof receipt.observation_id === "string" &&
-      WORKFLOW_UUID.test(receipt.observation_id),
+      lowerUuid(receipt.workflow_id) === binding.workflow_id &&
+      lowerUuid(receipt.workflow_run_id) === binding.workflow_run_id &&
+      lowerUuid(receipt.observation_id) !== null,
   );
 }