@iamu-dev/iamu 0.2.0-beta.10 → 0.2.0-beta.11

package/dist/commands/live-run-client.d.ts

@@ -0,0 +1,127 @@
+import type { RunStep } from "@iamu-dev/protocol";
+/** Timeout for run registration on start-run (3 seconds). */
+export declare const REGISTER_TIMEOUT_MS = 3000;
+/** Timeout for per-step and phase event dispatches (1.5 seconds). */
+export declare const EVENT_TIMEOUT_MS = 1500;
+/** Cap screenshot base64 at 5 MB raw binary (~6.7 MB base64, under the 8 MB payload cap). */
+export declare const MAX_LIVE_SCREENSHOT_BYTES: number;
+export type LiveRunPhase = "walking" | "completing" | "matching" | "judging" | "publishing";
+export interface LiveRunMeta {
+    walkthrough_id: string;
+    viewer_url: string;
+    project_id: string;
+    api_url: string;
+    last_seq: number;
+}
+export interface RegisterLiveRunParams {
+    projectRoot: string;
+    runId: string;
+    scenarioSlug: string;
+    targetUrl: string;
+    startedAt?: string;
+    lenses?: string[];
+    fetchFn?: typeof fetch;
+}
+export interface RegisterLiveRunResult {
+    walkthroughId: string;
+    viewerUrl: string;
+    status: "created" | "resumed";
+}
+export interface LiveStepEvent {
+    seq: number;
+    type: "step";
+    step: {
+        number: number;
+        title: string;
+        persona_reasoning?: string | null;
+        grounding?: string | null;
+        page_url?: string | null;
+        surface?: string | null;
+        screenshot_base64?: string;
+    };
+}
+export interface LiveActionEvent {
+    seq: number;
+    type: "action";
+    step_number: number;
+    action_type: string;
+    target?: string | null;
+}
+export interface LiveFindingEvent {
+    seq: number;
+    type: "finding";
+    finding: {
+        id: string;
+        title: string;
+        type: "helps" | "hinders" | "missing" | "irrelevant" | "incorrect";
+        severity: "critical" | "major" | "minor" | "observation";
+        ui_fact?: string | null;
+        consequence?: string | null;
+        step_number?: number | null;
+        task_impact?: string | null;
+        confidence?: string | null;
+    };
+}
+export interface LivePhaseEvent {
+    seq: number;
+    type: "phase";
+    phase: LiveRunPhase;
+}
+export interface LiveAbandonEvent {
+    seq: number;
+    type: "abandon";
+    reason?: string;
+}
+export type LiveRunEvent = LiveStepEvent | LiveActionEvent | LiveFindingEvent | LivePhaseEvent | LiveAbandonEvent;
+export interface LiveEventsResponse {
+    accepted_seq?: number;
+    cancelled?: boolean;
+}
+/**
+ * Reads `<runDir>/live.json`. Returns null when absent or malformed.
+ */
+export declare function loadLiveRunMeta(runDirPath: string): Promise<LiveRunMeta | null>;
+/**
+ * Saves `<runDir>/live.json` atomically.
+ */
+export declare function saveLiveRunMeta(runDirPath: string, meta: LiveRunMeta): Promise<void>;
+/**
+ * Register a running walkthrough with Iamu Cloud (POST /api/projects/:id/live-runs).
+ *
+ * Runs only when the project is cloud-linked, IAMU_LIVE != "0", and valid
+ * credentials exist. Never throws: network errors or 4xx/5xx silently return null.
+ */
+export declare function registerLiveRun(params: RegisterLiveRunParams): Promise<RegisterLiveRunResult | null>;
+/**
+ * Dispatch ordered events to POST /api/projects/:id/live-runs/:runId/events.
+ *
+ * Reads `<runDir>/live.json`. If absent or not cloud-linked, makes 0 network
+ * requests. Increments `last_seq` and catches all network errors silently.
+ */
+export declare function sendLiveEvents(projectRoot: string, runId: string, buildEvents: (startSeq: number) => LiveRunEvent[] | LiveRunEvent, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a step event with optional base64 screenshot.
+ */
+export declare function sendLiveStep(projectRoot: string, runId: string, step: RunStep, screenshotPath?: string | null, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a phase transition event (completing, matching, judging, publishing).
+ */
+export declare function sendLivePhase(projectRoot: string, runId: string, phase: LiveRunPhase, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post a finding event.
+ */
+export declare function sendLiveFinding(projectRoot: string, runId: string, finding: {
+    id: string;
+    title: string;
+    type: "helps" | "hinders" | "missing" | "irrelevant" | "incorrect";
+    severity: "critical" | "major" | "minor" | "observation";
+    ui_fact?: string | null;
+    consequence?: string | null;
+    step_number?: number | null;
+    task_impact?: string | null;
+    confidence?: string | null;
+}, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;
+/**
+ * Post an abandon event if a run was discarded or failed locally.
+ */
+export declare function sendLiveAbandon(projectRoot: string, runId: string, reason?: string, fetchFn?: typeof fetch): Promise<LiveEventsResponse>;

package/dist/commands/step.d.ts

@@ -37,6 +37,7 @@ export interface RecordStepResult {
     step: RunStep;
     stepPath: string;
     screenshotPath: string | null;
+    cancelled?: boolean;
 }
 /**
  * Record a single step into `<runDir>/steps/NNN.json`.