@e2edev/e2e 0.2.0

package/dist/agent/replay.js

@@ -0,0 +1,185 @@
+/**
+ * Zero-turn trace replay (RFC0001 layer 3, cache-in decision).
+ *
+ * Replays one recorded trace through the same action grammar the executor
+ * uses — every replayed action runs under the step's deadline, action budget,
+ * origin policy, secret authorization, and recording. No model is called.
+ *
+ * Adaptive, never fatal: any reason the trace cannot finish — a gap, a target
+ * that moved, an action the live app rejected — ends the replayed prefix and
+ * hands the step to the executor mid-step. Runtime hard stops (budget,
+ * timeout, cancellation) rethrow untouched; they are the step's truth, not a
+ * divergence.
+ */
+import { anchorsPresent } from '../cache/anchors.js';
+import { relocateDescriptor } from '../cache/relocate.js';
+import { sleep } from '../internal/time.js';
+import { isRuntimeHardStop, } from './executor.js';
+/** Backoff between looks at the screen while it settles. */
+const RETRY_DELAYS_MS = [100, 300, 600, 1_000, 3_000];
+/** Ceiling on one poll's total wait, inside whatever the deadline allows. */
+const RETRY_TIMEOUT_MS = 15_000;
+function planCall(action, actions) {
+    switch (action.name) {
+        case 'tool':
+            return { kind: 'gap' };
+        case 'tap':
+            return { kind: 'targeted', descriptor: action.target, invoke: (t) => actions.tap(t) };
+        case 'type':
+            return {
+                kind: 'targeted',
+                descriptor: action.target,
+                invoke: (t) => actions.type(t, action.value),
+            };
+        case 'typeSecret':
+            return {
+                kind: 'targeted',
+                descriptor: action.target,
+                invoke: (t) => actions.typeSecret(t, action.secret),
+            };
+        case 'press':
+            return {
+                kind: 'targeted',
+                descriptor: action.target,
+                invoke: (t) => actions.press(t, action.key),
+            };
+        case 'select':
+            return {
+                kind: 'targeted',
+                descriptor: action.target,
+                invoke: (t) => actions.select(t, action.value),
+            };
+        case 'scroll':
+            return action.target === undefined
+                ? { kind: 'free', invoke: () => actions.scroll(action.direction) }
+                : {
+                    kind: 'targeted',
+                    descriptor: action.target,
+                    invoke: (t) => actions.scroll(action.direction, t),
+                };
+        case 'navigate':
+            return { kind: 'free', invoke: () => actions.navigate(action.url) };
+    }
+}
+/** Replays one trace until it completes or diverges. */
+export async function replayTrace(host, trace) {
+    const summaries = [];
+    const total = trace.actions.length;
+    const stop = (stopReason) => ({
+        completed: false,
+        executed: summaries.length,
+        total,
+        summaries,
+        stopReason,
+    });
+    for (const action of trace.actions) {
+        const planned = planCall(action, host.actions);
+        if (planned.kind === 'gap')
+            return stop('gap');
+        try {
+            if (planned.kind === 'targeted') {
+                const relocated = await relocate(host, planned.descriptor);
+                if (relocated.kind === 'failed')
+                    return stop(relocated.failure);
+                await planned.invoke({ id: relocated.id });
+            }
+            else {
+                await planned.invoke();
+            }
+        }
+        catch (cause) {
+            if (isReplayFatal(cause, host.signal))
+                throw cause;
+            if (isUncertainCommit(cause)) {
+                // Input may have reached the app (spec 09): the hand-off must name
+                // the uncertain action so the executor verifies before re-acting —
+                // the runner never repeats an unknown-commit operation itself.
+                return { ...stop('action-uncertain'), uncertainAction: action.summary };
+            }
+            return stop('action-failed');
+        }
+        summaries.push(action.summary);
+    }
+    return { completed: true, executed: summaries.length, total, summaries };
+}
+/**
+ * Verifies a trace's recorded end anchors against the live screen: every
+ * anchor must be present again (`anchors.ts`, every recorded field equal) or
+ * the replay must not pass on its own. Waits on the same settling backoff
+ * relocation uses, because the recording run's final look came seconds of
+ * model latency after its last action and a replay's comes right away: a
+ * save still in flight is a wait, not a divergence. A surface that cannot be
+ * observed at all is a mismatch too — the executor gets the step and judges
+ * the live state; only runtime hard stops propagate.
+ */
+export async function verifyAnchors(host, anchors) {
+    if (anchors.length === 0)
+        return true;
+    try {
+        const present = await pollSettled(host, (nodes) => anchorsPresent(anchors, nodes, host) ? true : undefined);
+        return present === true;
+    }
+    catch (cause) {
+        if (isReplayFatal(cause, host.signal))
+            throw cause;
+        return false;
+    }
+}
+/**
+ * Relocates one descriptor against the settling screen. Only a missing target
+ * is worth another look; ambiguity never retries — two matching nodes will
+ * not become one by waiting, and acting on either would be a guess.
+ */
+async function relocate(host, descriptor) {
+    const options = { redact: host.redact, testIdAttribute: host.testIdAttribute };
+    const settled = await pollSettled(host, (nodes) => {
+        const result = relocateDescriptor(descriptor, nodes, options);
+        return result.kind === 'failed' && result.failure === 'target-not-found' ? undefined : result;
+    });
+    return settled ?? { kind: 'failed', failure: 'target-not-found' };
+}
+/**
+ * Probes a settled observation, then re-probes fresh raw captures on a fixed
+ * backoff until the probe answers or the wait runs out: a screen
+ * mid-transition gets a few looks before replay gives the step up. The first
+ * look settles because replay executes recorded actions far faster than the
+ * run that recorded them; without that wait an action can land while the app
+ * is still reacting to the previous one — a form mid-clear, a list mid-update
+ * — and commit something the recorded run never did.
+ */
+async function pollSettled(host, probe) {
+    const startedMs = Date.now();
+    let nodes = await host.observeSettled();
+    for (let attempt = 0;; attempt += 1) {
+        const answer = probe(nodes);
+        if (answer !== undefined)
+            return answer;
+        const delay = RETRY_DELAYS_MS[attempt];
+        if (delay === undefined ||
+            Date.now() - startedMs + delay > RETRY_TIMEOUT_MS ||
+            host.remainingMs() <= delay) {
+            return undefined;
+        }
+        await sleep(delay, host.signal);
+        nodes = await host.observe();
+    }
+}
+/** True when any error in the cause chain reports an unknown commit state. */
+function isUncertainCommit(cause) {
+    for (let error = cause, depth = 0; depth < 8; depth += 1) {
+        if (typeof error !== 'object' || error === null)
+            return false;
+        if (error.code === 'ACTION_MAY_HAVE_COMMITTED')
+            return true;
+        error = error.cause;
+    }
+    return false;
+}
+/**
+ * True for errors a replay must surface rather than absorb as divergence:
+ * runtime hard stops and cancellation are the step's own accounting.
+ */
+function isReplayFatal(cause, signal) {
+    return signal.aborted || isRuntimeHardStop(cause);
+}
+//# sourceMappingURL=replay.js.map

package/dist/agent/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/agent/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAyB,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EACL,iBAAiB,GAIlB,MAAM,eAAe,CAAC;AAEvB,4DAA4D;AAC5D,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAE/D,6EAA6E;AAC7E,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAkDhC,SAAS,QAAQ,CAAC,MAAsB,EAAE,OAAwB;IAChE,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACzB,KAAK,KAAK;YACR,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,KAAK,MAAM;YACT,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;aAC7C,CAAC;QACJ,KAAK,YAAY;YACf,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC;aACpD,CAAC;QACJ,KAAK,OAAO;YACV,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC;aAC5C,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;aAC/C,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS;gBAChC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;gBAClE,CAAC,CAAC;oBACE,IAAI,EAAE,UAAU;oBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;oBACzB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;iBACnD,CAAC;QACR,KAAK,UAAU;YACb,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACxE,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB,EAAE,KAAkB;IACpE,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,UAA+B,EAAiB,EAAE,CAAC,CAAC;QAChE,SAAS,EAAE,KAAK;QAChB,QAAQ,EAAE,SAAS,CAAC,MAAM;QAC1B,KAAK;QACL,SAAS;QACT,UAAU;KACX,CAAC,CAAC;IAEH,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC3D,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;gBAChE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC;gBAAE,MAAM,KAAK,CAAC;YACnD,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,mEAAmE;gBACnE,mEAAmE;gBACnE,+DAA+D;gBAC/D,OAAO,EAAE,GAAG,IAAI,CAAC,kBAAkB,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YAC1E,CAAC;YACD,OAAO,IAAI,CAAC,eAAe,CAAC,CAAC;QAC/B,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC3E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAgB,EAChB,OAAyC;IAEzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAChD,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CACxD,CAAC;QACF,OAAO,OAAO,KAAK,IAAI,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC;YAAE,MAAM,KAAK,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,QAAQ,CACrB,IAAgB,EAChB,UAAiC;IAEjC,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC;IAC/E,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QAChD,MAAM,MAAM,GAAG,kBAAkB,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,KAAK,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IAChG,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,WAAW,CACxB,IAAgB,EAChB,KAA8C;IAE9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,KAAK,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;IACxC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACvC,IACE,KAAK,KAAK,SAAS;YACnB,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,KAAK,GAAG,gBAAgB;YACjD,IAAI,CAAC,WAAW,EAAE,IAAI,KAAK,EAC3B,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAChC,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB,CAAC,KAAc;IACvC,KAAK,IAAI,KAAK,GAAG,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC9D,IAAK,KAA4B,CAAC,IAAI,KAAK,2BAA2B;YAAE,OAAO,IAAI,CAAC;QACpF,KAAK,GAAI,KAA6B,CAAC,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAc,EAAE,MAAmB;IACxD,OAAO,MAAM,CAAC,OAAO,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;AACpD,CAAC"}

package/dist/agent/secrets.d.ts

@@ -0,0 +1,22 @@
+/** Host-side secret fill authorization (spec 04-resources.md, 14-security.md). */
+import type { TargetSession, OperationContext, SemanticNode } from '../backend/surface.ts';
+import type { Secret } from '../types.ts';
+import type { AgentContext } from './invocation.ts';
+/**
+ * The narrow surface a secret fill needs from its step machinery: the act
+ * dispatch is its one caller today, and any future tier that fills secrets
+ * satisfies the same three members rather than re-deriving the policy.
+ */
+interface SecretFillHost {
+    readonly session: TargetSession;
+    operation(): OperationContext;
+    recordPolicy(name: string, decision: 'allowed' | 'denied', code?: string): void;
+}
+/**
+ * Authorizes one secret fill and resolves the plaintext only after every check
+ * passes. The value is returned to the caller for a single immediate handoff to
+ * the trusted backend and is never logged, cached, or sent to a model.
+ */
+export declare function authorizeSecretFill(host: SecretFillHost, runtime: AgentContext, secret: Secret, node: SemanticNode): Promise<string>;
+export {};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/agent/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/agent/secrets.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;GAIG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,SAAS,IAAI,gBAAgB,CAAC;IAC9B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjF;AAKD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,MAAM,CAAC,CA+CjB"}

package/dist/agent/secrets.js

@@ -0,0 +1,63 @@
+/** Host-side secret fill authorization (spec 04-resources.md, 14-security.md). */
+import { AgentError, toAgentError } from './error.js';
+/** Roles that expose an editable secure input sink. */
+const EDITABLE_ROLES = new Set(['textbox', 'searchbox', 'combobox']);
+/**
+ * Authorizes one secret fill and resolves the plaintext only after every check
+ * passes. The value is returned to the caller for a single immediate handoff to
+ * the trusted backend and is never logged, cached, or sent to a model.
+ */
+export async function authorizeSecretFill(host, runtime, secret, node) {
+    const credential = runtime.config.credentials.get(secret.name);
+    if (credential === undefined) {
+        host.recordPolicy('secret.registered', 'denied', 'AUTH_CREDENTIAL_UNAVAILABLE');
+        throw new AgentError('AUTH_CREDENTIAL_UNAVAILABLE', `credential "${secret.name}" is not configured`);
+    }
+    const origin = await currentOrigin(host);
+    const appAllows = runtime.config.app.allowedOrigins.includes(origin);
+    const credentialAllows = credential.allowedOrigins === undefined || credential.allowedOrigins.includes(origin);
+    if (!appAllows || !credentialAllows) {
+        host.recordPolicy('secret.origin', 'denied', 'POLICY_DENIED');
+        throw new AgentError('POLICY_DENIED', `origin ${origin} is not authorized for secret "${secret.name}"`);
+    }
+    if (node.states?.disabled === true) {
+        host.recordPolicy('secret.sink', 'denied', 'POLICY_DENIED');
+        throw new AgentError('POLICY_DENIED', 'the target field is disabled');
+    }
+    if (node.role === undefined || !EDITABLE_ROLES.has(node.role)) {
+        host.recordPolicy('secret.sink', 'denied', 'POLICY_DENIED');
+        throw new AgentError('POLICY_DENIED', `the target is not an editable input (role ${node.role ?? 'none'})`);
+    }
+    if (node.inputPurpose !== secret.purpose) {
+        host.recordPolicy('secret.purpose', 'denied', 'POLICY_DENIED');
+        throw new AgentError('POLICY_DENIED', `field purpose ${node.inputPurpose ?? 'none'} is incompatible with secret purpose ${secret.purpose}`);
+    }
+    host.recordPolicy('secret.fill', 'allowed');
+    try {
+        return await runtime.secrets.resolve(secret);
+    }
+    catch (cause) {
+        throw toAgentError(cause);
+    }
+}
+/** Reads the current top-level origin for origin policy checks. */
+async function currentOrigin(host) {
+    const url = host.session.url;
+    if (url === undefined) {
+        throw new AgentError('POLICY_DENIED', 'secret fills require a backend that exposes the current top-level URL');
+    }
+    let href;
+    try {
+        href = await url(host.operation());
+    }
+    catch (cause) {
+        throw toAgentError(cause);
+    }
+    try {
+        return new URL(href).origin;
+    }
+    catch {
+        throw new AgentError('POLICY_DENIED', `the current URL ${href} is not a valid origin`);
+    }
+}
+//# sourceMappingURL=secrets.js.map

package/dist/agent/secrets.js.map

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

package/dist/agent/step-cache.d.ts

@@ -0,0 +1,156 @@
+/**
+ * One step's trace-cache session (RFC0001 layer 3, cache-in decision): key
+ * derivation, the replay attempt, live recording, and the stage-or-evict
+ * decision once the step has settled — everything cache-shaped about one
+ * dispatched act step, kept beside the dispatch rather than threaded through
+ * it. The dispatch owns budgets, the grammar, and the verdict; this class owns
+ * nothing but the cache.
+ *
+ * Cost: in read-write mode the session takes two settled looks at the screen
+ * the executor never asked for — one before any action, one after the passing
+ * verdict — because the trace's end anchors are the delta between them. A
+ * read-only run pays neither.
+ */
+import type { AgentCacheContext } from '../cache/context.ts';
+import type { StepCacheInfo } from '../run/steps.ts';
+import type { JsonValue } from '../types.ts';
+import type { RecordableAction } from './actions.ts';
+import { type ReplayedPrefix, type StepVerdict } from './executor.ts';
+import { type ReplayHost } from './replay.ts';
+/**
+ * The replay host plus the one session-level probe replay itself never needs:
+ * the current location path, read at both ends of the step for the trace's
+ * start-path precondition and end-path postcondition.
+ */
+export interface StepCacheHost extends ReplayHost {
+    currentPath(): Promise<string | undefined>;
+}
+/** What the session needs from the dispatch beyond the host itself. */
+export interface StepCacheOptions {
+    readonly cache: AgentCacheContext;
+    readonly instruction: string;
+    readonly params: Readonly<Record<string, JsonValue>> | undefined;
+    readonly executor: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    readonly redact: (text: string) => string;
+    readonly testIdAttribute: string;
+    readonly maxActions: number;
+    /** Timeline index of the step being dispatched. */
+    readonly stepIndex: number;
+}
+/** How the step settled, as the write-side decision sees it. */
+export type StepOutcome = 'passed' | 'failed' | 'cancelled';
+export declare class StepTraceSession {
+    private readonly host;
+    private readonly cache;
+    private readonly keyHash;
+    private readonly recorder;
+    private readonly options;
+    private info;
+    private prefix;
+    private startPath;
+    /**
+     * The screen before any action, captured only when this step may write: the
+     * staged trace's end anchors are the delta between this and the passing
+     * observation, so a replay must reproduce the step's effect to pass alone.
+     * Undefined after `begin` when the surface could not be observed; the step
+     * still runs — an executor that never looks at the screen owes the cache
+     * nothing — but nothing is staged, because a trace without its baseline has
+     * no anchors and would replay on mechanics alone.
+     */
+    private startNodes;
+    /**
+     * The trace a full replay reproduced, kept for the re-stage: its executor
+     * is the write's provenance, and its summary is the original verdict prose.
+     * The step's own summary after a replay is the synthesized "replayed N
+     * actions…" wrapper; storing that would nest the summary one level deeper
+     * on every replay until the bound truncated it.
+     */
+    private replayed;
+    /** True once a cached entry's actions were run this step, fully or partly. */
+    private consumedReplay;
+    /** Grammar actions recorded so far when an end-mismatch hand-off happened. */
+    private actionsAtEndMismatch;
+    constructor(host: StepCacheHost, options: StepCacheOptions);
+    /** How the cache participated, for the step's report detail. */
+    get cacheInfo(): StepCacheInfo | undefined;
+    /** The mid-step hand-off, when a replay diverged after real progress. */
+    get replayedPrefix(): ReplayedPrefix | undefined;
+    /** Records one committed grammar action into the step trace. */
+    record(action: RecordableAction): void;
+    /** Records one mutating project-tool call as a replay-ending gap. */
+    recordGap(toolName: string): void;
+    /**
+     * Opens the step: captures the write-side preconditions — the start path
+     * and, when this step may write, the baseline screen — then attempts a
+     * zero-turn replay. Returns the self-finalized verdict on a full replay
+     * whose postcondition holds; undefined dispatches the executor — after a
+     * miss from the top, after a divergence mid-step with `replayedPrefix` set.
+     * Every failure to replay is a miss, never an error; only runtime hard stops
+     * propagate.
+     */
+    begin(): Promise<StepVerdict | undefined>;
+    /**
+     * Closes the session once the step has settled. The whole write-side
+     * decision lives here, in read-write mode only:
+     *
+     * - passed, after an end-mismatch the executor had to act to repair: evict.
+     *   Every recorded action ran and the effect was still missing, so the
+     *   recorded flow is proven not to produce it. Re-staging would freeze the
+     *   failed flow plus its repair — a typo, its deletion, the retype — as the
+     *   thing to replay forever; the next pass records a clean flow instead. A
+     *   hand-off the executor settled without acting is different: the flow was
+     *   fine and only the anchors were stale, so it heals by re-staging.
+     * - passed otherwise: stage the recorded trace for attempt-end settlement.
+     * - failed after consuming a replay: evict. Without this, a diverged replay
+     *   whose step then fails stages nothing — and the poisoned entry would
+     *   replay its bad prefix on every future first attempt.
+     * - cancelled: nothing, exactly like an interrupted attempt.
+     */
+    conclude(outcome: StepOutcome, verdictSummary: string | undefined): Promise<void>;
+    /**
+     * One store read, revalidated through the trace-1 framing whichever store
+     * produced it: a custom store's entry can never be trusted more loosely
+     * than a file entry, however the store author built their read path. A
+     * store outage is a slower run, never a failed test — every failure to read
+     * degrades to a miss.
+     */
+    private readEntry;
+    /**
+     * The trace's postcondition against the live screen: the recorded end path
+     * (pathname only, when the live location is known) and every recorded end
+     * anchor present again.
+     */
+    private endStateMatches;
+    private selfFinalize;
+    private handOff;
+    /**
+     * Stages the recorded trace for attempt-end settlement. The write is
+     * deferred, not immediate: the trace is confirmed or evicted at attempt end
+     * (`flushStagedTraces`), because the verification step after this one — not
+     * the verdict alone — is what proves the flow reached the right state. A
+     * replayed step re-stages its own entry with fresh descriptors, which is
+     * how staleness self-heals.
+     *
+     * The end path and a fresh settled observation are the trace's
+     * postcondition — the state the step passed in. The delta between the
+     * baseline and the passing observation becomes the end anchors. When the
+     * step moved to another pathname the whole screen is the delta and the path
+     * is the postcondition, so anchors are recorded only for a step that ended
+     * where it began (or on a surface without a location at all, where they are
+     * the only check). A postcondition that cannot be captured stages nothing:
+     * a trace without its check would replay on mechanics alone.
+     */
+    private stage;
+    /**
+     * Awaited so the step does not close — and a later read cannot be served
+     * the stale flow — before the eviction has settled. The cache is
+     * disposable; a failed eviction is a slower next run only.
+     */
+    private evict;
+    private repairedAfterEndMismatch;
+    private missed;
+}
+//# sourceMappingURL=step-cache.d.ts.map

package/dist/agent/step-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-cache.d.ts","sourceRoot":"","sources":["../../src/agent/step-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAS7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EAIL,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5C;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAQ5D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,SAAS,CAAqB;IACtC;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,CAA4B;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAA0B;IAC1C,8EAA8E;IAC9E,OAAO,CAAC,cAAc,CAAS;IAC/B,8EAA8E;IAC9E,OAAO,CAAC,oBAAoB,CAAqB;IAEjD,YAAY,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,EAYzD;IAED,gEAAgE;IAChE,IAAI,SAAS,IAAI,aAAa,GAAG,SAAS,CAEzC;IAED,yEAAyE;IACzE,IAAI,cAAc,IAAI,cAAc,GAAG,SAAS,CAE/C;IAED,gEAAgE;IAChE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAErC;IAED,qEAAqE;IACrE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEhC;IAED;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAsC9C;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CActF;IAED;;;;;;OAMG;YACW,SAAS;IAavB;;;;OAIG;YACW,eAAe;IAQ7B,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,OAAO;IAgBf;;;;;;;;;;;;;;;;OAgBG;YACW,KAAK;IAuBnB;;;;OAIG;YACW,KAAK;IAInB,OAAO,CAAC,wBAAwB;IAIhC,OAAO,CAAC,MAAM;CAGf"}