screenhand 0.1.1 → 0.2.0

package/dist/src/agent/loop.js

@@ -0,0 +1,274 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+/**
+ * ScreenHand Agent Loop
+ *
+ * Continuous observe → decide → act loop powered by Claude.
+ * Uses element_tree (accessibility tree) as the primary observation — not screenshots.
+ * ~50ms per observe, ~50ms per action. Only the LLM call adds latency.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+/**
+ * Compact AX tree representation for LLM consumption.
+ * Converts the full AXNode tree into a concise text format:
+ *   [button] "Send" (350,200)
+ *   [textField] "Search" value="hello" (100,50)
+ */
+function compactTree(node, depth = 0, maxDepth = 5) {
+    if (depth > maxDepth)
+        return "";
+    const indent = "  ".repeat(depth);
+    const parts = [];
+    // Role
+    const role = node.role.replace("AX", "").toLowerCase();
+    // Label — prefer title, then description, then identifier
+    const label = node.title || node.description || node.identifier || "";
+    // Value
+    const val = node.value ? ` value="${node.value.slice(0, 50)}"` : "";
+    // Position
+    const pos = node.position ? ` (${Math.round(node.position.x)},${Math.round(node.position.y)})` : "";
+    // Focused/enabled markers
+    const markers = [];
+    if (node.focused)
+        markers.push("focused");
+    if (node.enabled === false)
+        markers.push("disabled");
+    const markerStr = markers.length ? ` [${markers.join(",")}]` : "";
+    // Skip noise nodes with no useful info
+    const isNoise = !label && !val && !node.focused && (role === "group" || role === "splitgroup" || role === "scrollarea");
+    if (!isNoise) {
+        parts.push(`${indent}[${role}] "${label}"${val}${pos}${markerStr}`);
+    }
+    if (node.children) {
+        for (const child of node.children) {
+            const childStr = compactTree(child, isNoise ? depth : depth + 1, maxDepth);
+            if (childStr)
+                parts.push(childStr);
+        }
+    }
+    return parts.join("\n");
+}
+const SYSTEM_PROMPT = `You are a desktop automation agent. You control a computer through ScreenHand tools.
+
+On each turn you receive the current UI state as an accessibility tree. You must decide the SINGLE next action to take.
+
+Respond in this exact JSON format (no markdown, no explanation outside the JSON):
+{
+  "reasoning": "Brief explanation of what you see and why you're taking this action",
+  "action": { "tool": "...", ... },
+  "done": false
+}
+
+When the task is fully complete, respond with:
+{
+  "reasoning": "Task is complete because ...",
+  "action": { "tool": "done", "summary": "What was accomplished" },
+  "done": true
+}
+
+Available actions:
+- {"tool": "press", "target": "Button text or element name"}
+- {"tool": "type_into", "target": "Field name", "text": "text to type"}
+- {"tool": "navigate", "url": "https://..."}
+- {"tool": "scroll", "direction": "up|down|left|right", "amount": 3}
+- {"tool": "key_combo", "keys": ["cmd", "c"]}
+- {"tool": "menu_click", "menuPath": ["File", "Save"]}
+- {"tool": "app_launch", "bundleId": "com.apple.Safari"}
+- {"tool": "app_focus", "bundleId": "com.apple.Safari"}
+- {"tool": "extract", "target": "element name", "format": "text"}
+- {"tool": "wait", "ms": 1000}
+- {"tool": "done", "summary": "what was accomplished"}
+
+Rules:
+- Take ONE action per turn. After each action you'll see the updated UI.
+- Use the accessibility tree to find elements — look for roles and labels.
+- Target elements by their visible text/label, not coordinates (unless no label exists).
+- If an action fails, try an alternative approach — don't repeat the same failed action.
+- If you're stuck after 3 attempts, explain what's blocking you and mark done.
+- Be efficient. Don't take unnecessary actions.`;
+export async function runAgentLoop(runtime, sessionId, task, options = {}) {
+    const { maxSteps = 50, model = "claude-sonnet-4-20250514", maxTokens = 1024, onStep, screenshotOnStart = false, } = options;
+    const client = new Anthropic();
+    const steps = [];
+    const messages = [];
+    const startTime = Date.now();
+    // Optional initial screenshot for context
+    if (screenshotOnStart) {
+        await runtime.screenshot({ sessionId });
+    }
+    for (let i = 0; i < maxSteps; i++) {
+        const stepStart = Date.now();
+        // 1. OBSERVE — get accessibility tree (~50ms)
+        const treeResult = await runtime.elementTree({ sessionId, maxDepth: 5 });
+        let observation;
+        if (treeResult.ok) {
+            observation = compactTree(treeResult.data);
+            // Truncate if too large to keep tokens manageable
+            if (observation.length > 8000) {
+                observation = observation.slice(0, 8000) + "\n... (truncated)";
+            }
+        }
+        else {
+            observation = `[Error getting UI tree: ${treeResult.error.message}]`;
+        }
+        // Also get app context
+        let contextLine = "";
+        try {
+            const apps = await runtime.appList(sessionId);
+            if (apps.ok) {
+                const active = apps.data.find(a => a.isActive);
+                if (active)
+                    contextLine = `Active app: ${active.name} (${active.bundleId})`;
+            }
+        }
+        catch { /* ignore */ }
+        // 2. BUILD prompt
+        const userMsg = i === 0
+            ? `Task: ${task}\n\nCurrent UI state:\n${contextLine}\n${observation}`
+            : `Action result: ${steps[i - 1].result}\n\nUpdated UI state:\n${contextLine}\n${observation}`;
+        messages.push({ role: "user", content: userMsg });
+        // 3. DECIDE — ask Claude what to do next
+        let reasoning = "";
+        let action = null;
+        let done = false;
+        try {
+            const resp = await client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                system: SYSTEM_PROMPT,
+                messages,
+            });
+            const text = resp.content[0]?.type === "text" ? resp.content[0].text : "";
+            messages.push({ role: "assistant", content: text });
+            // Parse JSON response
+            const jsonMatch = text.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                reasoning = parsed.reasoning ?? "";
+                action = parsed.action ?? null;
+                done = parsed.done === true;
+            }
+            else {
+                reasoning = text;
+            }
+        }
+        catch (e) {
+            reasoning = `LLM error: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        // 4. ACT — execute the action (~50ms)
+        let result = "";
+        if (action) {
+            try {
+                result = await executeAction(runtime, sessionId, action);
+            }
+            catch (e) {
+                result = `Error: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        else {
+            result = "No action taken";
+        }
+        // Record step
+        const step = {
+            index: i,
+            observation: observation.slice(0, 500),
+            reasoning,
+            action,
+            result,
+            done,
+            durationMs: Date.now() - stepStart,
+        };
+        steps.push(step);
+        if (onStep)
+            onStep(step);
+        if (done)
+            break;
+    }
+    const lastStep = steps[steps.length - 1];
+    const summary = lastStep?.action?.tool === "done"
+        ? lastStep.action.summary
+        : `Stopped after ${steps.length} steps`;
+    return {
+        success: lastStep?.done ?? false,
+        summary,
+        steps,
+        totalMs: Date.now() - startTime,
+    };
+}
+async function executeAction(runtime, sessionId, action) {
+    switch (action.tool) {
+        case "press": {
+            const r = await runtime.press({
+                sessionId,
+                target: { type: "text", value: action.target },
+            });
+            return r.ok ? `Pressed "${action.target}"` : `Failed: ${r.error.message}`;
+        }
+        case "type_into": {
+            const r = await runtime.typeInto({
+                sessionId,
+                target: { type: "text", value: action.target },
+                text: action.text,
+            });
+            return r.ok ? `Typed "${action.text}" into "${action.target}"` : `Failed: ${r.error.message}`;
+        }
+        case "navigate": {
+            const r = await runtime.navigate({ sessionId, url: action.url });
+            return r.ok ? `Navigated to ${action.url}` : `Failed: ${r.error.message}`;
+        }
+        case "scroll": {
+            const input = { sessionId, direction: action.direction };
+            if (typeof action.amount === "number")
+                input.amount = action.amount;
+            const r = await runtime.scroll(input);
+            return r.ok ? `Scrolled ${action.direction}` : `Failed: ${r.error.message}`;
+        }
+        case "key_combo": {
+            const r = await runtime.keyCombo({ sessionId, keys: action.keys });
+            return r.ok ? `Key combo: ${action.keys.join("+")}` : `Failed: ${r.error.message}`;
+        }
+        case "menu_click": {
+            const r = await runtime.menuClick({ sessionId, menuPath: action.menuPath });
+            return r.ok ? `Menu: ${action.menuPath.join(" → ")}` : `Failed: ${r.error.message}`;
+        }
+        case "app_launch": {
+            const r = await runtime.appLaunch({ sessionId, bundleId: action.bundleId });
+            return r.ok ? `Launched ${action.bundleId}` : `Failed: ${r.error.message}`;
+        }
+        case "app_focus": {
+            const r = await runtime.appFocus({ sessionId, bundleId: action.bundleId });
+            return r.ok ? `Focused ${action.bundleId}` : `Failed: ${r.error.message}`;
+        }
+        case "extract": {
+            const r = await runtime.extract({
+                sessionId,
+                target: { type: "text", value: action.target },
+                format: action.format,
+            });
+            return r.ok ? `Extracted: ${JSON.stringify(r.data).slice(0, 500)}` : `Failed: ${r.error.message}`;
+        }
+        case "wait": {
+            await new Promise(resolve => setTimeout(resolve, action.ms));
+            return `Waited ${action.ms}ms`;
+        }
+        case "done": {
+            return `Task complete: ${action.summary}`;
+        }
+        default:
+            return `Unknown action: ${action.tool}`;
+    }
+}

package/{src/config.ts → dist/src/config.js}

@@ -14,17 +14,12 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
-
-import type { ActionBudget } from "./types.js";
-
-export const DEFAULT_ACTION_BUDGET: ActionBudget = {
-  locateMs: 800,
-  actMs: 200,
-  verifyMs: 2000,
-  maxRetries: 1,
+export const DEFAULT_ACTION_BUDGET = {
+    locateMs: 800,
+    actMs: 200,
+    verifyMs: 2000,
+    maxRetries: 1,
 };
-
 export const DEFAULT_NAVIGATE_TIMEOUT_MS = 10_000;
 export const DEFAULT_WAIT_TIMEOUT_MS = 2_000;
 export const DEFAULT_PROFILE = "automation";
-

package/{src/index.ts → dist/src/index.js}

@@ -14,18 +14,11 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
-
 import { TimelineLogger } from "./logging/timeline-logger.js";
 import { MvpMcpServer } from "./mcp/server.js";
-import {
-  type AppAdapter,
-  PlaceholderAppAdapter,
-} from "./runtime/app-adapter.js";
+import { PlaceholderAppAdapter, } from "./runtime/app-adapter.js";
 import { CdpChromeAdapter } from "./runtime/cdp-chrome-adapter.js";
 import { AutomationRuntimeService } from "./runtime/service.js";
-
-// Re-export types and adapters for external use
-export type { AppAdapter } from "./runtime/app-adapter.js";
 export { PlaceholderAppAdapter } from "./runtime/app-adapter.js";
 export { CdpChromeAdapter } from "./runtime/cdp-chrome-adapter.js";
 export { AccessibilityAdapter } from "./runtime/accessibility-adapter.js";
@@ -37,56 +30,43 @@ export { StateObserver } from "./runtime/state-observer.js";
 export { PlanningLoop } from "./runtime/planning-loop.js";
 export { AutomationRuntimeService } from "./runtime/service.js";
 export { MvpMcpServer } from "./mcp/server.js";
-
-export interface RuntimeApp {
-  runtime: AutomationRuntimeService;
-  mcp: MvpMcpServer;
+export { createMcpStdioServer, startMcpStdioServer } from "./mcp/mcp-stdio-server.js";
+export { runAgentLoop } from "./agent/loop.js";
+export function createRuntimeApp(adapter) {
+    const logger = new TimelineLogger();
+    const runtime = new AutomationRuntimeService(adapter, logger);
+    const mcp = new MvpMcpServer(runtime);
+    return { runtime, mcp };
 }
-
-export function createRuntimeApp(adapter: AppAdapter): RuntimeApp {
-  const logger = new TimelineLogger();
-  const runtime = new AutomationRuntimeService(adapter, logger);
-  const mcp = new MvpMcpServer(runtime);
-  return { runtime, mcp };
-}
-
-async function createDefaultAdapter(): Promise<AppAdapter> {
-  if (process.env.AUTOMATOR_ADAPTER === "placeholder") {
-    return new PlaceholderAppAdapter();
-  }
-  if (process.env.AUTOMATOR_ADAPTER === "composite") {
-    // Lazy import to avoid requiring Swift bridge for CDP-only usage
-    const { MacOSBridgeClient } = await import("./native/macos-bridge-client.js");
-    const { CompositeAdapter } = await import("./runtime/composite-adapter.js");
-    const bridge = new MacOSBridgeClient();
-    return new CompositeAdapter(bridge, {
-      headless: process.env.AUTOMATOR_HEADLESS === "1",
+async function createDefaultAdapter() {
+    if (process.env.AUTOMATOR_ADAPTER === "placeholder") {
+        return new PlaceholderAppAdapter();
+    }
+    if (process.env.AUTOMATOR_ADAPTER === "composite") {
+        // Lazy import to avoid requiring Swift bridge for CDP-only usage
+        const { MacOSBridgeClient } = await import("./native/macos-bridge-client.js");
+        const { CompositeAdapter } = await import("./runtime/composite-adapter.js");
+        const bridge = new MacOSBridgeClient();
+        return new CompositeAdapter(bridge, {
+            headless: process.env.AUTOMATOR_HEADLESS === "1",
+        });
+    }
+    if (process.env.AUTOMATOR_ADAPTER === "accessibility") {
+        const { MacOSBridgeClient } = await import("./native/macos-bridge-client.js");
+        const { AccessibilityAdapter } = await import("./runtime/accessibility-adapter.js");
+        const bridge = new MacOSBridgeClient();
+        return new AccessibilityAdapter(bridge);
+    }
+    return new CdpChromeAdapter({
+        headless: process.env.AUTOMATOR_HEADLESS === "1",
     });
-  }
-  if (process.env.AUTOMATOR_ADAPTER === "accessibility") {
-    const { MacOSBridgeClient } = await import("./native/macos-bridge-client.js");
-    const { AccessibilityAdapter } = await import("./runtime/accessibility-adapter.js");
-    const bridge = new MacOSBridgeClient();
-    return new AccessibilityAdapter(bridge);
-  }
-  return new CdpChromeAdapter({
-    headless: process.env.AUTOMATOR_HEADLESS === "1",
-  });
 }
-
 const app = createRuntimeApp(await createDefaultAdapter());
-
 if (process.argv.includes("--healthcheck")) {
-  const session = await app.runtime.sessionStart("automation");
-  console.log(
-    JSON.stringify(
-      {
+    const session = await app.runtime.sessionStart("automation");
+    console.log(JSON.stringify({
         status: "ok",
         session,
         note: "Runtime loaded with universal adapter support.",
-      },
-      null,
-      2,
-    ),
-  );
+    }, null, 2));
 }

package/dist/src/jobs/manager.js

@@ -0,0 +1,237 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+import { VALID_TRANSITIONS, JOB_STATES } from "./types.js";
+import { JobStore } from "./store.js";
+export class JobManager {
+    store;
+    memory;
+    supervisor;
+    constructor(opts) {
+        this.store = new JobStore(opts.jobDir);
+        this.memory = opts.memory ?? null;
+        this.supervisor = opts.supervisor ?? null;
+    }
+    init() {
+        this.store.init();
+    }
+    // ── Create ──────────────────────────────────────
+    create(opts) {
+        const now = new Date().toISOString();
+        const id = "job_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 8);
+        const steps = (opts.steps ?? []).map((s, i) => {
+            const step = { index: i, action: s.action, status: "pending" };
+            if (s.target !== undefined)
+                step.target = s.target;
+            if (s.description !== undefined)
+                step.description = s.description;
+            if (s.text !== undefined)
+                step.text = s.text;
+            if (s.keys !== undefined)
+                step.keys = s.keys;
+            if (s.value !== undefined)
+                step.value = s.value;
+            return step;
+        });
+        const job = {
+            id,
+            task: opts.task,
+            state: "queued",
+            playbookId: opts.playbookId ?? null,
+            sessionId: opts.sessionId ?? null,
+            bundleId: opts.bundleId ?? null,
+            windowId: opts.windowId ?? null,
+            lastStep: -1,
+            steps,
+            blockReason: null,
+            retries: 0,
+            maxRetries: opts.maxRetries ?? 3,
+            lastError: null,
+            tags: opts.tags ?? [],
+            priority: opts.priority ?? 10,
+            createdAt: now,
+            updatedAt: now,
+            startedAt: null,
+            completedAt: null,
+        };
+        this.store.add(job);
+        return job;
+    }
+    // ── State transitions ───────────────────────────
+    transition(id, to, opts) {
+        const job = this.store.get(id);
+        if (!job)
+            return { error: `Job ${id} not found` };
+        const allowed = VALID_TRANSITIONS[job.state];
+        if (!allowed.includes(to)) {
+            return { error: `Cannot transition from "${job.state}" to "${to}". Allowed: [${allowed.join(", ")}]` };
+        }
+        const patch = { state: to };
+        if (to === "running") {
+            if (!job.startedAt)
+                patch.startedAt = new Date().toISOString();
+            patch.blockReason = null;
+            if (opts?.sessionId)
+                patch.sessionId = opts.sessionId;
+        }
+        if (to === "blocked" || to === "waiting_human") {
+            patch.blockReason = opts?.blockReason ?? null;
+        }
+        if (to === "failed") {
+            patch.lastError = opts?.error ?? job.lastError;
+            this.recordOutcomeToMemory(job, false);
+        }
+        if (to === "done") {
+            patch.completedAt = new Date().toISOString();
+            this.recordOutcomeToMemory(job, true);
+        }
+        // Re-queue bumps retry count
+        if (job.state === "failed" && to === "queued") {
+            patch.retries = job.retries + 1;
+            if (patch.retries > job.maxRetries) {
+                return { error: `Job ${id} has exceeded max retries (${job.maxRetries})` };
+            }
+            patch.lastError = null;
+            patch.blockReason = null;
+        }
+        const updated = this.store.update(id, patch);
+        return updated ?? { error: `Failed to update job ${id}` };
+    }
+    // ── Step tracking ───────────────────────────────
+    /** Mark a step as completed and advance lastStep. */
+    completeStep(jobId, stepIndex, opts) {
+        const job = this.store.get(jobId);
+        if (!job)
+            return { error: `Job ${jobId} not found` };
+        if (job.state !== "running")
+            return { error: `Job is not running (state=${job.state})` };
+        const step = job.steps[stepIndex];
+        if (!step)
+            return { error: `Step ${stepIndex} does not exist (total: ${job.steps.length})` };
+        step.status = "done";
+        step.completedAt = new Date().toISOString();
+        if (opts?.durationMs !== undefined)
+            step.durationMs = opts.durationMs;
+        const newLastStep = Math.max(job.lastStep, stepIndex);
+        return this.store.update(jobId, { lastStep: newLastStep, steps: job.steps }) ?? { error: "Update failed" };
+    }
+    /** Mark a step as failed. Does NOT transition the job — caller decides (retry vs block vs fail). */
+    failStep(jobId, stepIndex, error) {
+        const job = this.store.get(jobId);
+        if (!job)
+            return { error: `Job ${jobId} not found` };
+        const step = job.steps[stepIndex];
+        if (!step)
+            return { error: `Step ${stepIndex} does not exist` };
+        step.status = "failed";
+        step.error = error;
+        return this.store.update(jobId, { steps: job.steps, lastError: error }) ?? { error: "Update failed" };
+    }
+    /** Skip a step (e.g., optional step or already done). */
+    skipStep(jobId, stepIndex) {
+        const job = this.store.get(jobId);
+        if (!job)
+            return { error: `Job ${jobId} not found` };
+        const step = job.steps[stepIndex];
+        if (!step)
+            return { error: `Step ${stepIndex} does not exist` };
+        step.status = "skipped";
+        return this.store.update(jobId, { steps: job.steps }) ?? { error: "Update failed" };
+    }
+    // ── Resume ──────────────────────────────────────
+    /** Get the resume point: next pending step after lastStep. */
+    getResumePoint(jobId) {
+        const job = this.store.get(jobId);
+        if (!job)
+            return null;
+        for (let i = job.lastStep + 1; i < job.steps.length; i++) {
+            if (job.steps[i].status === "pending") {
+                return { stepIndex: i, step: job.steps[i] };
+            }
+        }
+        return null;
+    }
+    // ── Queries ─────────────────────────────────────
+    get(id) {
+        return this.store.get(id);
+    }
+    list(state) {
+        return this.store.list(state);
+    }
+    /** Pop the next queued job and transition it to running. */
+    dequeue(sessionId) {
+        const next = this.store.nextQueued();
+        if (!next)
+            return null;
+        const opts = {};
+        if (sessionId !== undefined)
+            opts.sessionId = sessionId;
+        const result = this.transition(next.id, "running", opts);
+        if ("error" in result)
+            return null;
+        return result;
+    }
+    summary() {
+        const all = this.store.list();
+        const byState = Object.fromEntries(JOB_STATES.map((s) => [s, 0]));
+        for (const j of all)
+            byState[j.state]++;
+        const queued = all
+            .filter((j) => j.state === "queued")
+            .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+        return {
+            total: all.length,
+            byState,
+            oldestQueued: queued[0]?.createdAt ?? null,
+            runningJobIds: all.filter((j) => j.state === "running").map((j) => j.id),
+        };
+    }
+    /** Remove a job entirely. */
+    remove(id) {
+        return this.store.remove(id);
+    }
+    /** Prune old terminal jobs. */
+    prune() {
+        return this.store.prune();
+    }
+    // ── Private ─────────────────────────────────────
+    recordOutcomeToMemory(job, success) {
+        if (!this.memory)
+            return;
+        try {
+            const completedSteps = job.steps.filter((s) => s.status === "done");
+            if (completedSteps.length === 0)
+                return;
+            this.memory.appendStrategy({
+                id: "strat_" + job.id,
+                task: job.task,
+                steps: completedSteps.map((s) => ({
+                    tool: s.action,
+                    params: s.target ? { target: s.target } : {},
+                })),
+                totalDurationMs: completedSteps.reduce((sum, s) => sum + (s.durationMs ?? 0), 0),
+                successCount: success ? 1 : 0,
+                failCount: success ? 0 : 1,
+                lastUsed: new Date().toISOString(),
+                tags: job.tags,
+                fingerprint: completedSteps.map((s) => s.action).join("→"),
+            });
+        }
+        catch {
+            // Non-critical — don't let memory failures break job flow
+        }
+    }
+}