reflectt-node 0.1.15 → 0.1.17

package/dist/agent-exec-guardrail.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-exec-guardrail.test.d.ts","sourceRoot":"","sources":["../src/agent-exec-guardrail.test.ts"],"names":[],"mappings":""}

package/dist/agent-exec-guardrail.test.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { checkActionAllowed, requiresApprovalGate } from './agent-exec-guardrail.js';
+describe('checkActionAllowed', () => {
+    it('allows github_issue_create with github.com domain', () => {
+        const result = checkActionAllowed('github_issue_create', 'https://github.com/owner/repo');
+        assert.equal(result.allowed, true);
+        assert.equal(result.reason, undefined);
+    });
+    it('allows github_issue_create with no target', () => {
+        const result = checkActionAllowed('github_issue_create');
+        assert.equal(result.allowed, true);
+    });
+    it('denies unknown action with reason', () => {
+        // @ts-expect-error testing unknown kind
+        const result = checkActionAllowed('unknown_action');
+        assert.equal(result.allowed, false);
+        assert.ok(result.reason?.includes('unknown_action'));
+        assert.ok(result.reason?.includes('approved action list'));
+    });
+    it('denies out-of-scope domain with reason', () => {
+        const result = checkActionAllowed('github_issue_create', 'https://evil.com/owner/repo');
+        assert.equal(result.allowed, false);
+        assert.ok(result.reason?.includes('evil.com'));
+        assert.ok(result.reason?.includes('approved domain list'));
+    });
+    it('allows subdomain of github.com', () => {
+        const result = checkActionAllowed('github_issue_create', 'https://api.github.com/repos/owner/repo/issues');
+        assert.equal(result.allowed, true);
+    });
+    it('does not match partial domain (githubx.com)', () => {
+        const result = checkActionAllowed('github_issue_create', 'https://githubx.com/owner/repo');
+        assert.equal(result.allowed, false);
+        assert.ok(result.reason?.includes('githubx.com'));
+    });
+    it('ignores non-URL target strings (no hostname to check)', () => {
+        // If target is not a URL, URL parsing returns null and no domain check is done
+        const result = checkActionAllowed('github_issue_create', 'owner/repo');
+        assert.equal(result.allowed, true);
+    });
+});
+describe('requiresApprovalGate', () => {
+    it('returns true for github_issue_create', () => {
+        assert.equal(requiresApprovalGate('github_issue_create'), true);
+    });
+    it('returns true for all v1 actions (always requires human approval)', () => {
+        // All v1 actions are irreversible — gate is always on
+        const kinds = ['github_issue_create'];
+        for (const kind of kinds) {
+            assert.equal(requiresApprovalGate(kind), true);
+        }
+    });
+});
+//# sourceMappingURL=agent-exec-guardrail.test.js.map

package/dist/agent-exec-guardrail.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-exec-guardrail.test.js","sourceRoot":"","sources":["../src/agent-exec-guardrail.test.ts"],"names":[],"mappings":"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"}

package/dist/agent-interface.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Agent Interface — browser-driven software actions on behalf of the human.
+ *
+ * v1 scope: GitHub issue creation with full approval gate + run log.
+ *
+ * Run lifecycle: queued → running → awaiting_approval → completed | failed
+ *
+ * Spec: process/agent-interface-mvp-execution-v1.md
+ * Task: task-1773257734617-6fvzfl52z
+ */
+export type RunKind = 'github_issue_create' | 'macos_ui_action';
+export type RunStatus = 'queued' | 'running' | 'awaiting_approval' | 'completed' | 'failed' | 'rejected' | 'aborted';
+/**
+ * Approval timeout in ms.
+ * In production: 10 minutes (never hardcoded — reads from env).
+ * In CI/tests: set APPROVAL_TIMEOUT_MS_TEST to a smaller value (e.g. 200).
+ * The test env var ONLY applies when running tests — never override in production code.
+ */
+export declare function getApprovalTimeoutMs(): number;
+export interface RunEvent {
+    type: 'state_changed' | 'step_started' | 'step_succeeded' | 'step_failed' | 'approval_requested' | 'approval_resolved';
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+export interface AgentInterfaceRun {
+    id: string;
+    kind: RunKind;
+    status: RunStatus;
+    createdAt: number;
+    updatedAt: number;
+    input: Record<string, unknown>;
+    log: RunEvent[];
+    result?: {
+        outcome: 'completed' | 'failed' | 'rejected';
+        issueUrl?: string;
+        errorMessage?: string;
+        recoveryHint?: string;
+    };
+}
+export declare function createRun(kind: RunKind, input: Record<string, unknown>): AgentInterfaceRun;
+export declare function getRun(runId: string): AgentInterfaceRun | null;
+export declare function subscribeRun(runId: string, cb: (event: RunEvent) => void): () => void;
+export interface GithubIssueInput {
+    repo: string;
+    title: string;
+    body: string;
+    dryRun?: boolean;
+}
+export interface PendingApproval {
+    runId: string;
+    resolve: (approved: boolean) => void;
+}
+/**
+ * Execute a github_issue_create run.
+ * Flow: validate → step:draft → request_approval → (approved) → step:submit → complete
+ *       or       → (rejected) → rejected
+ */
+export declare function executeGithubIssueCreate(runId: string, input: GithubIssueInput): Promise<void>;
+/**
+ * Approve a pending run (human confirms irreversible action).
+ * Returns false if no pending approval found.
+ */
+export declare function approveRun(runId: string): boolean;
+/**
+ * Reject a pending run (human declines the action).
+ */
+export declare function rejectRun(runId: string): boolean;
+/**
+ * Abort a run — emergency kill for kill-switch or out-of-band termination.
+ * Works on any active state: awaiting_approval (rejects pending gate),
+ * running (forces abort), or queued (cancels before execution).
+ *
+ * @param actor  identity invoking the abort (for audit log)
+ */
+export declare function abortRun(runId: string, actor?: string): boolean;
+/**
+ * List runs currently awaiting human approval — surfaced in /approval-queue
+ * so the presence canvas decision card can show them.
+ */
+export declare function listPendingRuns(): AgentInterfaceRun[];
+/**
+ * List all runs with optional status filter.
+ */
+export declare function listRuns(status?: string): AgentInterfaceRun[];
+export declare function _clearRunsForTest(): void;
+/**
+ * Structured audit packet for a completed run.
+ * Includes intent, step timeline, approval decisions, outcome, and rollback hints.
+ *
+ * task-1773486840057-e92leqnr1
+ */
+export interface ReplayPacket {
+    schema: 'agent-interface-replay-v1';
+    runId: string;
+    kind: string;
+    generatedAt: number;
+    run: {
+        id: string;
+        kind: string;
+        status: RunStatus;
+        createdAt: number;
+        completedAt: number | null;
+        durationMs: number | null;
+    };
+    intent: Record<string, unknown>;
+    stepTimeline: Array<{
+        type: string;
+        timestamp: number;
+        offsetMs: number;
+        payload: Record<string, unknown>;
+    }>;
+    approvals: Array<{
+        requestedAt: number;
+        resolvedAt: number | null;
+        approved: boolean | null;
+        timeoutMs: number;
+    }>;
+    outcome: {
+        status: RunStatus;
+        result: Record<string, unknown> | null;
+        errorMessage: string | null;
+    };
+    rollbackHints: string[];
+}
+/**
+ * Build an immutable audit/replay packet for the given run.
+ * Safe to call at any run lifecycle stage.
+ */
+export declare function buildReplayPacket(runId: string): ReplayPacket | null;
+/**
+ * Execute a macOS UI action run.
+ * Handles the awaiting_approval gate for irreversible intents.
+ *
+ * task-1773486840001-u0shj14v3 / task-1773486840036-8x0o76rmp
+ */
+export declare function executeMacOSUIAction(runId: string, intent: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=agent-interface.d.ts.map

package/dist/agent-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-interface.d.ts","sourceRoot":"","sources":["../src/agent-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,MAAM,OAAO,GAAG,qBAAqB,GAAG,iBAAiB,CAAA;AAC/D,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,mBAAmB,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAEpH;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EACA,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,oBAAoB,GACpB,mBAAmB,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,GAAG,EAAE,QAAQ,EAAE,CAAA;IACf,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAA;QAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAWD,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CA2B1F;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAE9D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI,CAIrF;AAwBD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAA;CACrC;AAID;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoJpG;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMjD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMhD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAgB,GAAG,OAAO,CAgBtE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,EAAE,CAMrD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAM7D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAID;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,2BAA2B,CAAA;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE;QACH,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,SAAS,CAAA;QACjB,SAAS,EAAE,MAAM,CAAA;QACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;QAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAC1B,CAAA;IACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACjC,CAAC,CAAA;IACF,SAAS,EAAE,KAAK,CAAC;QACf,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;QACzB,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;QACxB,SAAS,EAAE,MAAM,CAAA;KAClB,CAAC,CAAA;IACF,OAAO,EAAE;QACP,MAAM,EAAE,SAAS,CAAA;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;QACtC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAC5B,CAAA;IACD,aAAa,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA2DpE;AA2BD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAsEf"}

package/dist/agent-interface.js

@@ -0,0 +1,463 @@
+/**
+ * Agent Interface — browser-driven software actions on behalf of the human.
+ *
+ * v1 scope: GitHub issue creation with full approval gate + run log.
+ *
+ * Run lifecycle: queued → running → awaiting_approval → completed | failed
+ *
+ * Spec: process/agent-interface-mvp-execution-v1.md
+ * Task: task-1773257734617-6fvzfl52z
+ */
+import { checkActionAllowed } from "./agent-exec-guardrail.js";
+import { executeIntent as macOSExecuteIntent, requiresApproval as macOSRequiresApproval, validateIntent as macOSValidateIntent } from "./macos-accessibility.js";
+/**
+ * Approval timeout in ms.
+ * In production: 10 minutes (never hardcoded — reads from env).
+ * In CI/tests: set APPROVAL_TIMEOUT_MS_TEST to a smaller value (e.g. 200).
+ * The test env var ONLY applies when running tests — never override in production code.
+ */
+export function getApprovalTimeoutMs() {
+    const testOverride = process.env.APPROVAL_TIMEOUT_MS_TEST;
+    if (testOverride)
+        return Number(testOverride);
+    return 10 * 60 * 1000; // 10 minutes (production default)
+}
+// ── In-memory run store ───────────────────────────────────────────────────────
+const runs = new Map();
+const subscribers = new Map();
+function genRunId() {
+    return `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function createRun(kind, input) {
+    const run = {
+        id: genRunId(),
+        kind,
+        status: 'queued',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        input,
+        log: [],
+    };
+    runs.set(run.id, run);
+    // Guardrail check: deny non-approved actions or out-of-scope domains immediately
+    const target = typeof input.repo === 'string' ? input.repo : undefined;
+    const guard = checkActionAllowed(kind, target);
+    if (!guard.allowed) {
+        run.status = 'failed';
+        run.result = { outcome: 'failed', errorMessage: guard.reason, recoveryHint: 'Only approved actions and domains are permitted.' };
+        run.log.push({
+            type: 'step_failed',
+            timestamp: Date.now(),
+            payload: { step: 'guardrail', reason: guard.reason },
+        });
+        run.updatedAt = Date.now();
+    }
+    return run;
+}
+export function getRun(runId) {
+    return runs.get(runId) ?? null;
+}
+export function subscribeRun(runId, cb) {
+    if (!subscribers.has(runId))
+        subscribers.set(runId, new Set());
+    subscribers.get(runId).add(cb);
+    return () => subscribers.get(runId)?.delete(cb);
+}
+function emit(runId, event) {
+    const run = runs.get(runId);
+    if (run) {
+        run.log.push(event);
+        run.updatedAt = Date.now();
+    }
+    for (const cb of subscribers.get(runId) ?? []) {
+        try {
+            cb(event);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+function transition(runId, status, payload = {}) {
+    const run = runs.get(runId);
+    if (!run)
+        return;
+    const prev = run.status;
+    run.status = status;
+    run.updatedAt = Date.now();
+    emit(runId, { type: 'state_changed', timestamp: Date.now(), payload: { from: prev, to: status, ...payload } });
+}
+const pendingApprovals = new Map();
+/**
+ * Execute a github_issue_create run.
+ * Flow: validate → step:draft → request_approval → (approved) → step:submit → complete
+ *       or       → (rejected) → rejected
+ */
+export async function executeGithubIssueCreate(runId, input) {
+    const run = runs.get(runId);
+    if (!run)
+        return;
+    transition(runId, 'running');
+    // Step 1: Draft the issue content
+    emit(runId, {
+        type: 'step_started',
+        timestamp: Date.now(),
+        payload: { step: 'draft', repo: input.repo, title: input.title },
+    });
+    if (!input.repo || !input.title || !input.body) {
+        emit(runId, {
+            type: 'step_failed',
+            timestamp: Date.now(),
+            payload: { step: 'draft', error: 'repo, title, and body are required' },
+        });
+        run.result = { outcome: 'failed', errorMessage: 'Missing required fields', recoveryHint: 'Provide repo (owner/repo), title, and body.' };
+        transition(runId, 'failed');
+        return;
+    }
+    emit(runId, {
+        type: 'step_succeeded',
+        timestamp: Date.now(),
+        payload: { step: 'draft', title: input.title, bodyLen: input.body.length },
+    });
+    // Step 2: Request human approval before irreversible submit
+    transition(runId, 'awaiting_approval');
+    emit(runId, {
+        type: 'approval_requested',
+        timestamp: Date.now(),
+        payload: {
+            message: `Create GitHub issue in ${input.repo}: "${input.title}"`,
+            repo: input.repo,
+            title: input.title,
+            bodyPreview: input.body.slice(0, 200),
+            dryRun: input.dryRun ?? false,
+        },
+    });
+    // Wait for approval decision (max 10 minutes)
+    const approved = await new Promise((resolve) => {
+        pendingApprovals.set(runId, { runId, resolve });
+        setTimeout(() => {
+            if (pendingApprovals.has(runId)) {
+                pendingApprovals.delete(runId);
+                resolve(false); // auto-reject on timeout
+            }
+        }, getApprovalTimeoutMs());
+    });
+    emit(runId, {
+        type: 'approval_resolved',
+        timestamp: Date.now(),
+        payload: { approved, runId },
+    });
+    if (!approved) {
+        run.result = { outcome: 'rejected', recoveryHint: 'Re-submit when ready to approve.' };
+        transition(runId, 'rejected');
+        return;
+    }
+    // Step 3: Submit to GitHub
+    transition(runId, 'running');
+    emit(runId, {
+        type: 'step_started',
+        timestamp: Date.now(),
+        payload: { step: 'submit', dryRun: input.dryRun ?? false },
+    });
+    if (input.dryRun) {
+        // Dry run — simulate success, don't actually call GitHub API
+        emit(runId, {
+            type: 'step_succeeded',
+            timestamp: Date.now(),
+            payload: { step: 'submit', dryRun: true, issueUrl: `https://github.com/${input.repo}/issues/[dry-run]` },
+        });
+        run.result = { outcome: 'completed', issueUrl: `https://github.com/${input.repo}/issues/[dry-run]` };
+        transition(runId, 'completed');
+        return;
+    }
+    // Real GitHub API call
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        emit(runId, {
+            type: 'step_failed',
+            timestamp: Date.now(),
+            payload: { step: 'submit', error: 'GITHUB_TOKEN not configured' },
+        });
+        run.result = { outcome: 'failed', errorMessage: 'GITHUB_TOKEN not set', recoveryHint: 'Set GITHUB_TOKEN env var with repo write scope.' };
+        transition(runId, 'failed');
+        return;
+    }
+    try {
+        const [owner, repo] = input.repo.split('/');
+        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+                'Content-Type': 'application/json',
+                'X-GitHub-Api-Version': '2022-11-28',
+            },
+            body: JSON.stringify({ title: input.title, body: input.body }),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok) {
+            const errBody = await res.text();
+            emit(runId, {
+                type: 'step_failed',
+                timestamp: Date.now(),
+                payload: { step: 'submit', status: res.status, error: errBody.slice(0, 200) },
+            });
+            run.result = {
+                outcome: 'failed',
+                errorMessage: `GitHub API error ${res.status}`,
+                recoveryHint: 'Check GITHUB_TOKEN permissions (needs repo write scope).',
+            };
+            transition(runId, 'failed');
+            return;
+        }
+        const issue = await res.json();
+        emit(runId, {
+            type: 'step_succeeded',
+            timestamp: Date.now(),
+            payload: { step: 'submit', issueUrl: issue.html_url, issueNumber: issue.number },
+        });
+        run.result = { outcome: 'completed', issueUrl: issue.html_url };
+        transition(runId, 'completed');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        emit(runId, {
+            type: 'step_failed',
+            timestamp: Date.now(),
+            payload: { step: 'submit', error: message },
+        });
+        run.result = { outcome: 'failed', errorMessage: message, recoveryHint: 'Check network connectivity and retry.' };
+        transition(runId, 'failed');
+    }
+}
+/**
+ * Approve a pending run (human confirms irreversible action).
+ * Returns false if no pending approval found.
+ */
+export function approveRun(runId) {
+    const pending = pendingApprovals.get(runId);
+    if (!pending)
+        return false;
+    pendingApprovals.delete(runId);
+    pending.resolve(true);
+    return true;
+}
+/**
+ * Reject a pending run (human declines the action).
+ */
+export function rejectRun(runId) {
+    const pending = pendingApprovals.get(runId);
+    if (!pending)
+        return false;
+    pendingApprovals.delete(runId);
+    pending.resolve(false);
+    return true;
+}
+/**
+ * Abort a run — emergency kill for kill-switch or out-of-band termination.
+ * Works on any active state: awaiting_approval (rejects pending gate),
+ * running (forces abort), or queued (cancels before execution).
+ *
+ * @param actor  identity invoking the abort (for audit log)
+ */
+export function abortRun(runId, actor = 'kill-switch') {
+    const run = runs.get(runId);
+    if (!run)
+        return false;
+    if (['completed', 'failed', 'rejected', 'aborted', 'cancelled'].includes(run.status))
+        return false;
+    // If waiting for approval — resolve the gate with rejection first
+    const pending = pendingApprovals.get(runId);
+    if (pending) {
+        pendingApprovals.delete(runId);
+        pending.resolve(false);
+    }
+    run.result = { outcome: 'aborted', actor, abortedAt: Date.now() };
+    transition(runId, 'aborted', { actor, abortedAt: Date.now() });
+    emit(runId, { type: 'step_failed', timestamp: Date.now(), payload: { step: 'execute', error: `aborted by ${actor}` } });
+    return true;
+}
+/**
+ * List runs currently awaiting human approval — surfaced in /approval-queue
+ * so the presence canvas decision card can show them.
+ */
+export function listPendingRuns() {
+    const result = [];
+    for (const run of runs.values()) {
+        if (run.status === 'awaiting_approval')
+            result.push(run);
+    }
+    return result;
+}
+/**
+ * List all runs with optional status filter.
+ */
+export function listRuns(status) {
+    const result = [];
+    for (const run of runs.values()) {
+        if (!status || run.status === status)
+            result.push(run);
+    }
+    return result.sort((a, b) => b.createdAt - a.createdAt);
+}
+export function _clearRunsForTest() {
+    runs.clear();
+    subscribers.clear();
+    pendingApprovals.clear();
+}
+/**
+ * Build an immutable audit/replay packet for the given run.
+ * Safe to call at any run lifecycle stage.
+ */
+export function buildReplayPacket(runId) {
+    const run = runs.get(runId);
+    if (!run)
+        return null;
+    const startMs = run.createdAt;
+    // Find approval events
+    const approvals = [];
+    let pendingApproval = null;
+    for (const event of run.log) {
+        if (event.type === 'approval_requested') {
+            pendingApproval = { requestedAt: event.timestamp, resolvedAt: null, approved: null, timeoutMs: getApprovalTimeoutMs() };
+        }
+        else if (event.type === 'approval_resolved' && pendingApproval) {
+            pendingApproval.resolvedAt = event.timestamp;
+            pendingApproval.approved = event.payload.approved ?? null;
+            approvals.push(pendingApproval);
+            pendingApproval = null;
+        }
+    }
+    if (pendingApproval)
+        approvals.push(pendingApproval);
+    // Determine completion time
+    const terminalEvent = [...run.log].reverse().find(e => e.type === 'state_changed' && ['completed', 'failed', 'rejected'].includes(e.payload.to));
+    const completedAt = terminalEvent?.timestamp ?? null;
+    // Rollback hints based on intent action
+    const intent = run.input.intent ?? run.input;
+    const rollbackHints = buildRollbackHints(run.kind, intent);
+    return {
+        schema: 'agent-interface-replay-v1',
+        runId,
+        kind: run.kind,
+        generatedAt: Date.now(),
+        run: {
+            id: run.id,
+            kind: run.kind,
+            status: run.status,
+            createdAt: run.createdAt,
+            completedAt,
+            durationMs: completedAt ? completedAt - startMs : null,
+        },
+        intent,
+        stepTimeline: run.log.map(event => ({
+            type: event.type,
+            timestamp: event.timestamp,
+            offsetMs: event.timestamp - startMs,
+            payload: event.payload,
+        })),
+        approvals,
+        outcome: {
+            status: run.status,
+            result: run.result ? { ...run.result } : null,
+            errorMessage: run.result?.errorMessage ?? null,
+        },
+        rollbackHints,
+    };
+}
+function buildRollbackHints(kind, intent) {
+    if (kind === 'github_issue_create') {
+        return ['Close the created GitHub issue via the issue URL in the run result.'];
+    }
+    if (kind === 'macos_ui_action') {
+        const action = String(intent?.action ?? '');
+        switch (action) {
+            case 'create_reminder':
+                return ['Open Reminders app → find and delete the created reminder manually.'];
+            case 'draft_email':
+                return ['Open Mail app → Drafts → delete the draft before sending.'];
+            case 'summarize_note':
+                return ['Read-only — no rollback needed.'];
+            case 'open_app':
+            case 'focus_window':
+                return ['Reversible — close the application if needed.'];
+            case 'type_text':
+                return ['Undo via Cmd+Z in the focused application.'];
+            default:
+                return ['Review the target application manually for any unintended changes.'];
+        }
+    }
+    return ['Review output carefully; consult the run log for step-by-step details.'];
+}
+/**
+ * Execute a macOS UI action run.
+ * Handles the awaiting_approval gate for irreversible intents.
+ *
+ * task-1773486840001-u0shj14v3 / task-1773486840036-8x0o76rmp
+ */
+export async function executeMacOSUIAction(runId, intent) {
+    // Validate
+    const validation = macOSValidateIntent(intent);
+    if (!validation.ok) {
+        emit(runId, { type: 'step_failed', timestamp: Date.now(), payload: { step: 'validate', error: validation.reason } });
+        transition(runId, 'failed');
+        return;
+    }
+    transition(runId, 'running');
+    emit(runId, { type: 'step_started', timestamp: Date.now(), payload: { step: 'validate', action: intent.action } });
+    emit(runId, { type: 'step_succeeded', timestamp: Date.now(), payload: { step: 'validate', action: intent.action } });
+    // Irreversible: request human approval before executing
+    if (macOSRequiresApproval(intent)) {
+        transition(runId, 'awaiting_approval');
+        emit(runId, { type: 'approval_requested', timestamp: Date.now(), payload: {
+                message: `macOS action "${intent.action}" requires human approval (pilot safety gate)`,
+                action: intent.action,
+                app: intent.app,
+                preview: (intent.text ?? '').slice(0, 200),
+            } });
+        // Wait for approve/reject (10m timeout → auto-reject, matching github_issue_create pattern)
+        const approved = await new Promise((resolve) => {
+            pendingApprovals.set(runId, { runId, resolve });
+            setTimeout(() => {
+                if (pendingApprovals.has(runId)) {
+                    pendingApprovals.delete(runId);
+                    resolve(false);
+                }
+            }, getApprovalTimeoutMs());
+        });
+        emit(runId, { type: 'approval_resolved', timestamp: Date.now(), payload: { approved, runId } });
+        if (!approved) {
+            const run = runs.get(runId);
+            if (run)
+                run.result = { outcome: 'rejected', recoveryHint: 'Re-submit and approve when ready.' };
+            transition(runId, 'rejected');
+            return;
+        }
+        transition(runId, 'running');
+    }
+    // Execute
+    emit(runId, { type: 'step_started', timestamp: Date.now(), payload: { step: 'execute', action: intent.action } });
+    const result = await macOSExecuteIntent(intent);
+    // Check if aborted while executing — kill-switch may have fired during the await
+    const runAfterExec = runs.get(runId);
+    if (!runAfterExec || runAfterExec.status === 'aborted')
+        return;
+    if (result.ok) {
+        emit(runId, { type: 'step_succeeded', timestamp: Date.now(), payload: {
+                step: 'execute',
+                action: intent.action,
+                output: result.output?.slice(0, 200),
+                stepCount: result.steps.length,
+            } });
+        const run = runs.get(runId);
+        if (run)
+            run.result = { outcome: 'completed', output: result.output, steps: result.steps };
+        transition(runId, 'completed');
+    }
+    else {
+        emit(runId, { type: 'step_failed', timestamp: Date.now(), payload: { step: 'execute', error: result.error } });
+        const run = runs.get(runId);
+        if (run)
+            run.result = { outcome: 'failed', errorMessage: result.error };
+        transition(runId, 'failed');
+    }
+}
+//# sourceMappingURL=agent-interface.js.map