agent-device-lab 0.0.0-stage → 0.3.1

package/dist/cli/signals.js

@@ -0,0 +1,38 @@
+const EXIT_CODES = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
+let terminating = false;
+/**
+ * Call before a command exits by itself: when a termination signal is already being handled, wait for
+ * its handler to finish and exit with the signal's code instead of the command's own.
+ */
+export async function holdIfTerminating() {
+    if (terminating)
+        await new Promise(() => undefined);
+}
+/**
+ * Commands that run a Lab in this process (`run`, `scan --project`) own a browser and services. On the
+ * first SIGINT, SIGTERM or SIGHUP, run `cleanup` (close the lab: stops what it started) and exit with the
+ * conventional 128 + signal code. A second signal exits at once with 1 and says what may be left running.
+ * Returns a function that removes the handlers.
+ */
+export function onTermination(cleanup, opts = {}) {
+    let received;
+    const handler = (signal) => {
+        if (received) {
+            process.stderr.write(`agentlab: ${signal} again; exiting now. The browser and the services this run started may still be running; ` +
+                `run \`agentlab clean\`${opts.stateDir ? ` (state: ${opts.stateDir})` : ''} to stop what is left.\n`);
+            process.exit(1);
+        }
+        received = signal;
+        terminating = true;
+        process.stderr.write(`agentlab: ${signal} received; stopping what this run started (send it again to exit immediately)\n`);
+        void cleanup(signal)
+            .catch((err) => process.stderr.write(`agentlab: cleanup failed: ${err instanceof Error ? err.message : String(err)}\n`))
+            .finally(() => process.exit(EXIT_CODES[signal] ?? 1));
+    };
+    const signals = Object.keys(EXIT_CODES);
+    for (const s of signals)
+        process.on(s, handler);
+    return () => { for (const s of signals)
+        process.off(s, handler); };
+}
+//# sourceMappingURL=signals.js.map

package/dist/core/action-log.js

@@ -0,0 +1,125 @@
+import { consequentialWord } from './explore-safety.js';
+import { redactSecrets } from './feed.js';
+import { formatChanges } from './format.js';
+// The structured, replay-oriented log of what an agent did in a session (kept in memory, non-child sessions
+// only) and a compact copy of its last observations. Bundles (bundle.ts) and replay (replay.ts) read it.
+// Pure apart from the log's own state, so it is unit-tested without a browser.
+export const SECRET_MASK = '‹secret›';
+export const ACTION_LOG_LIMIT = 500;
+export const OBSERVATION_LOG_LIMIT = 10;
+const CONTROLS_PER_OBSERVATION = 40;
+const CHANGE_LINES = 10;
+const VALUE_MAX = 2000;
+/** Shorter typed secrets are not tracked for redaction passes: replacing a 2-character string everywhere would wreck the text. */
+const MIN_TRACKED_SECRET = 4;
+/** Fallback when an action failed before the field could be inspected: names that suggest a secret. */
+const SECRETISH_NAME = /pass|secret|token|otp|pin|cvv|cvc/i;
+/** The path of a route (query and hash dropped, they often carry tokens). */
+export function routePath(route) {
+    return route === undefined ? undefined : route.split(/[?#]/)[0] || '/';
+}
+const recordedTarget = (c) => c ? { role: c.role, name: c.name, ...(c.context ? { context: c.context } : {}) } : undefined;
+export function summariseObservation(o) {
+    return {
+        gen: o.gen, route: routePath(o.route) ?? '/', title: o.title.slice(0, 120), ...(o.dialog ? { dialog: o.dialog } : {}),
+        headings: o.headings.slice(0, 20),
+        controls: o.controls.slice(0, CONTROLS_PER_OBSERVATION).map((c) => ({
+            role: c.role, name: c.name, ...(c.context ? { context: c.context } : {}), ...(c.value !== undefined ? { value: c.value } : {}),
+        })),
+        omitted: Math.max(0, o.controls.length - CONTROLS_PER_OBSERVATION) + o.omitted,
+    };
+}
+/**
+ * One agent action as it is recorded. `secret` is what the Lab knows (a password-like field was filled or
+ * typed into); a masked field the observation shows as "••••" and, when the action failed before the field
+ * was inspected, a secret-looking name are treated the same. A value is never kept for a secret field.
+ */
+export function recordAction(input) {
+    const { request: r, before, result, index } = input;
+    const target = before && r.ref ? before.controls.find((c) => c.ref === r.ref) : undefined;
+    const to = before && r.toRef ? before.controls.find((c) => c.ref === r.toRef) : undefined;
+    const typed = r.action === 'fill' || (r.action === 'press' && r.key !== undefined && r.key.split('+').at(-1).length === 1);
+    const secret = typed && (input.secret || target?.value === '••••' || (result.outcome === 'error' && !!target && SECRETISH_NAME.test(target.name)));
+    const args = {};
+    let truncated = false;
+    if (r.value !== undefined) {
+        if (secret)
+            args.value = SECRET_MASK;
+        else {
+            args.value = r.value.slice(0, VALUE_MAX);
+            truncated = r.value.length > VALUE_MAX;
+        }
+    }
+    if (r.key !== undefined)
+        args.key = secret ? SECRET_MASK : r.key;
+    if (r.values !== undefined)
+        args.values = r.values.slice(0, 100).map((v) => v.slice(0, VALUE_MAX));
+    for (const k of ['direction', 'amount', 'dx', 'dy', 'files', 'tab', 'path'])
+        if (r[k] !== undefined)
+            args[k] = r[k];
+    const after = result.observation ?? before;
+    const t = recordedTarget(target);
+    const tt = recordedTarget(to);
+    return {
+        index, at: (input.now ?? new Date()).toISOString(), actor: 'agent', action: r.action,
+        ...(t ? { target: t } : {}), ...(tt ? { toTarget: tt } : {}), args,
+        ...(secret ? { secret: true } : {}), ...(truncated ? { truncated: true } : {}),
+        ...(before ? { routeBefore: routePath(before.route), ...(before.dialog ? { dialogBefore: before.dialog } : {}) } : {}),
+        ...(after ? { routeAfter: routePath(after.route), ...(after.dialog ? { dialogAfter: after.dialog } : {}) } : {}),
+        outcome: result.outcome,
+        ...(result.error ? { error: { code: result.error.code, message: redactSecrets(result.error.message).slice(0, 300) } } : {}),
+        changes: result.changes ? formatChanges(result.changes).slice(0, CHANGE_LINES).map((l) => redactSecrets(l).slice(0, 200)) : [],
+        newFindings: result.newFindings.map((f) => f.id),
+        consequential: [t?.name, tt?.name].some((n) => n !== undefined && !!consequentialWord(n)),
+    };
+}
+export class ActionLog {
+    entries = [];
+    omitted = 0;
+    next = 1;
+    recent = [];
+    secrets = new Set();
+    typedKeys = '';
+    /** Route of the first observation of the session. */
+    startRoute = '/';
+    /** The agent's next action. Values typed into password-like fields are remembered (in memory only) for redaction. */
+    agent(input) {
+        const entry = recordAction({ ...input, index: this.next });
+        if (entry.secret && input.request.action === 'fill' && input.request.value !== undefined)
+            this.remember(input.request.value);
+        if (entry.secret && input.request.action === 'press' && input.request.key) {
+            this.typedKeys += input.request.key;
+            this.remember(this.typedKeys);
+        }
+        else
+            this.typedKeys = '';
+        this.push(entry);
+    }
+    person(description, now = new Date()) {
+        this.typedKeys = '';
+        this.push({ index: this.next, at: now.toISOString(), actor: 'person', description: redactSecrets(description).slice(0, 200) });
+    }
+    observation(o) {
+        this.recent.push(summariseObservation(o));
+        if (this.recent.length > OBSERVATION_LOG_LIMIT)
+            this.recent.shift();
+    }
+    push(entry) {
+        this.next++;
+        this.entries.push(entry);
+        if (this.entries.length > ACTION_LOG_LIMIT) {
+            this.entries.shift();
+            this.omitted++;
+        }
+    }
+    remember(value) {
+        if (value.length >= MIN_TRACKED_SECRET)
+            this.secrets.add(value);
+    }
+    get actions() { return structuredClone(this.entries); }
+    get actionsOmitted() { return this.omitted; }
+    get observations() { return structuredClone(this.recent); }
+    /** Values the agent typed into password-like fields. For redaction passes only: never logged, never returned to a caller outside the process. */
+    secretValues() { return [...this.secrets]; }
+}
+//# sourceMappingURL=action-log.js.map

package/dist/core/auth.js

@@ -0,0 +1,175 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, relative } from 'node:path';
+import { LabError } from './schema.js';
+/** Load and check the saved state. Throws auth_missing, or auth_invalid after invalidating an unusable file. */
+export function loadAuthState(policy) {
+    if (!existsSync(policy.file)) {
+        throw new LabError('auth_missing', `No saved sign-in state at ${policy.file}`, {
+            hint: 'Start a fresh session, sign in, then run `agentlab auth save` (MCP: auth_save).',
+        });
+    }
+    const mode = statSync(policy.file).mode & 0o777;
+    if (mode & 0o077) {
+        throw new LabError('auth_invalid', `Saved sign-in state ${policy.file} is readable by other users (mode ${mode.toString(8)})`, {
+            hint: `Run \`chmod 600 ${policy.file}\`, or \`agentlab auth clear\` and save it again.`,
+        });
+    }
+    let state;
+    try {
+        state = JSON.parse(readFileSync(policy.file, 'utf8'));
+        if (!Array.isArray(state.cookies) || !Array.isArray(state.origins))
+            throw new Error('missing cookies/origins');
+    }
+    catch (err) {
+        invalidate(policy);
+        throw new LabError('auth_invalid', `Saved sign-in state was unreadable (${err.message.split('\n')[0]}) and has been removed`, {
+            hint: 'Start a fresh session, sign in, then save the state again.',
+        });
+    }
+    if (isExpired(state)) {
+        invalidate(policy);
+        throw new LabError('auth_invalid', 'Saved sign-in state had expired (every cookie is past its expiry) and has been removed', {
+            hint: 'Start a fresh session, sign in, then save the state again.',
+        });
+    }
+    return state;
+}
+/** The environment variable CI mode reads a sign-in state from (JSON or base64 JSON). */
+export const AUTH_STATE_ENV = 'AGENTLAB_AUTH_STATE';
+/**
+ * A sign-in state from an environment variable value (Playwright storageState as JSON or base64 JSON), with
+ * the same shape and expiry checks as `loadAuthState`. It never touches the disk, and no message here
+ * quotes the value (a JSON parser's own message would).
+ */
+export function authStateFromEnv(value) {
+    const text = value.trim();
+    const bad = (why) => {
+        throw new LabError('auth_invalid', `${AUTH_STATE_ENV} is not a usable sign-in state: ${why}`, {
+            hint: `Set it to a Playwright storageState as JSON or base64-encoded JSON (\`agentlab auth save\` writes one; base64 -w0 encodes it).`,
+        });
+    };
+    if (!text)
+        return bad('it is empty');
+    let raw;
+    try {
+        raw = JSON.parse(text.startsWith('{') ? text : Buffer.from(text, 'base64').toString('utf8'));
+    }
+    catch {
+        return bad('it is neither JSON nor base64-encoded JSON');
+    }
+    const obj = raw;
+    if (!obj || typeof obj !== 'object' || !Array.isArray(obj.cookies) || !Array.isArray(obj.origins))
+        return bad('it needs "cookies" and "origins" lists');
+    const cookies = obj.cookies.map((c, i) => {
+        const k = c;
+        if (!k || typeof k !== 'object' || typeof k.name !== 'string' || typeof k.value !== 'string' || typeof k.domain !== 'string') {
+            return bad(`cookie ${i + 1} needs a string name, value and domain`);
+        }
+        return { ...k, path: typeof k.path === 'string' ? k.path : '/', expires: typeof k.expires === 'number' ? k.expires : -1 };
+    });
+    const origins = obj.origins.map((o, i) => {
+        const k = o;
+        if (!k || typeof k !== 'object' || typeof k.origin !== 'string')
+            return bad(`origin ${i + 1} needs a string origin`);
+        if (k.localStorage !== undefined && !Array.isArray(k.localStorage))
+            return bad(`origin ${i + 1}: localStorage must be a list`);
+        return { ...k, localStorage: (k.localStorage ?? []) };
+    });
+    const state = { ...obj, cookies, origins };
+    if (isExpired(state))
+        return bad('every cookie is past its expiry');
+    return state;
+}
+/**
+ * The values of a state that must never be printed or written (cookie values and storage values), for the
+ * caller's redaction set. Values shorter than 6 characters are left out: they would match ordinary text.
+ */
+export function authStateSecrets(state) {
+    const out = new Set();
+    for (const c of state.cookies)
+        if (typeof c.value === 'string' && c.value.length >= 6)
+            out.add(c.value);
+    for (const o of state.origins)
+        for (const e of o.localStorage ?? [])
+            if (typeof e.value === 'string' && e.value.length >= 6)
+                out.add(e.value);
+    return [...out];
+}
+/** Whether a saved state exists and is usable, without changing anything (unlike `loadAuthState`, which removes an unusable file). */
+export function savedStateProblem(policy, root) {
+    const s = authStatus(policy, root);
+    if (!s.exists)
+        return `no saved sign-in state at ${policy.file}`;
+    if (s.problem)
+        return `saved sign-in state ${policy.file} is ${s.problem}`;
+    if (s.ownerOnly === false)
+        return `saved sign-in state ${policy.file} is readable by other users (mode ${s.mode})`;
+    if (s.expired)
+        return `saved sign-in state ${policy.file} has expired`;
+    return undefined;
+}
+/** Remove a saved state that has proved unusable. */
+export function invalidate(policy) {
+    rmSync(policy.file, { force: true });
+}
+/**
+ * Write state owner-only (0600) under a 0700 directory, atomically. Refuses when the project is a git
+ * repository that would track the file.
+ */
+export function saveAuthState(policy, root, state) {
+    if (gitIgnores(root, policy.file) === false) {
+        throw new LabError('auth_not_ignored', `git would track ${relative(root, policy.file)}, so the sign-in state was not saved`, {
+            hint: 'Run `agentlab init` (it adds .agentlab/ to .gitignore) or add the file to .gitignore yourself.',
+        });
+    }
+    const dir = dirname(policy.file);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const tmp = `${policy.file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, policy.file);
+    return { cookies: state.cookies.length, origins: state.origins.length, file: policy.file };
+}
+export function authStatus(policy, root) {
+    const status = { file: policy.file, exists: existsSync(policy.file) };
+    const ignored = gitIgnores(root, policy.file);
+    if (ignored !== undefined)
+        status.ignored = ignored;
+    if (!status.exists)
+        return status;
+    const mode = statSync(policy.file).mode & 0o777;
+    status.mode = mode.toString(8);
+    status.ownerOnly = !(mode & 0o077);
+    try {
+        const state = JSON.parse(readFileSync(policy.file, 'utf8'));
+        status.cookies = state.cookies?.length ?? 0;
+        status.origins = state.origins?.length ?? 0;
+        status.expired = isExpired(state);
+    }
+    catch {
+        status.problem = 'unreadable JSON';
+    }
+    return status;
+}
+function isExpired(state) {
+    const now = Date.now() / 1000;
+    const hasStorage = state.origins.some((o) => o.localStorage?.length);
+    const session = state.cookies.filter((c) => !(c.expires > 0));
+    return !hasStorage && !session.length && state.cookies.length > 0 && state.cookies.every((c) => c.expires > 0 && c.expires < now);
+}
+/** true/false from `git check-ignore`; undefined outside a git repository or without git. */
+export function gitIgnores(root, file) {
+    try {
+        execFileSync('git', ['check-ignore', '-q', '--no-index', file], { cwd: root, stdio: 'ignore' });
+        return true;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 1)
+            return false;
+        return undefined;
+    }
+}
+//# sourceMappingURL=auth.js.map