swipium 1.0.0

package/dist/lib/metroState.js

@@ -0,0 +1,45 @@
+// Shared Metro/dev-server readiness checks used by target preparation.
+import net from 'node:net';
+import { run } from './spawn.js';
+export const METRO_PORT = 8081;
+export function metroListening(port = METRO_PORT, host = '127.0.0.1', timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ port, host });
+        const done = (v) => {
+            socket.destroy();
+            resolve(v);
+        };
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+        socket.setTimeout(timeoutMs, () => done(false));
+    });
+}
+export async function reverseSet(serial, port = METRO_PORT) {
+    try {
+        const r = await run('adb', ['-s', serial, 'reverse', '--list'], { timeoutMs: 5000 });
+        return r.stdout.includes(`tcp:${port}`);
+    }
+    catch {
+        return false;
+    }
+}
+/** Is Metro actually SERVING (not just a port open)? Hits the host-side packager status. */
+export async function bundleServing(port = METRO_PORT) {
+    try {
+        const res = await fetch(`http://localhost:${port}/status`, { signal: AbortSignal.timeout(3000) });
+        const body = (await res.text()).trim();
+        return { serving: res.ok && /packager-status:running/.test(body), detail: `${res.status} ${body.slice(0, 40)}` };
+    }
+    catch (e) {
+        return { serving: false, detail: String(e) };
+    }
+}
+export async function metroReadiness(serial, port = METRO_PORT) {
+    const [listening, rev, srv] = await Promise.all([
+        metroListening(port),
+        serial ? reverseSet(serial, port) : Promise.resolve(false),
+        bundleServing(port),
+    ]);
+    return { listening, reverseSet: rev, serving: srv.serving, ready: listening && rev && srv.serving, detail: srv.detail };
+}
+//# sourceMappingURL=metroState.js.map

package/dist/lib/metroState.js.map

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

package/dist/lib/needsInput.js

@@ -0,0 +1,201 @@
+// NeedsInput protocol (roadmap §3.2) — a single, consistent shape for the missing-input
+// blockers a QA run hits, so an agent forwards ONE concise question to the user instead of
+// improvising. It is NOT an error: the run is paused, recoverable, and resumable. The payload
+// rides on a normal (ok:true) tool result with `needsInput:true`, and is also embeddable in a
+// blocker via `embedNeedsInput`.
+//
+// Secret fields (passwords, OTPs, tokens) are flagged so the caller redacts them everywhere:
+// once provided, the value goes into session.secrets and never appears in artifacts/logs.
+//
+// Developer 1 contract (Milestone B): EVERY NeedsInput response carries one concise question,
+// typed fields (with secret flags), safe fallback options, the EXACT resume call, what Swipium
+// already tried (`attempted`), and what happens if the user declines (`ifDeclined`). Agents ask
+// one question — never a bundle of guesses — and resume deterministically.
+import { currentResponseMode } from './result.js';
+/** Default resume: hand the answer to qa_continue_from_blocker, which routes by kind. */
+function resumeVia(kind) {
+    return { tool: 'qa_continue_from_blocker', args: { kind } };
+}
+/**
+ * The standardized QA questions (roadmap §3.2). Builders, not constants, so callers can splice
+ * in context (which app, which screen) while keeping the field/fallback/resume contract stable.
+ * `attempted` is left empty here and filled by qaNeedsInput from the live session.
+ */
+export const NeedsInput = {
+    credentials(context) {
+        return {
+            needsInput: true,
+            kind: 'credentials',
+            question: (context ? `${context} ` : '') +
+                'This app appears to require login. Provide test credentials, or ask Swipium to stay pre-login.',
+            fields: [
+                { name: 'email', secret: false, description: 'Test account email/username' },
+                { name: 'password', secret: true, description: 'Test account password' },
+            ],
+            fallbackOptions: ['test pre-login only', 'use saved session', 'seed login state'],
+            resume: resumeVia('credentials'),
+            attempted: [],
+            ifDeclined: 'Swipium tests pre-login coverage only; authenticated flows are reported as blocked, not failed.',
+        };
+    },
+    otp(context) {
+        return {
+            needsInput: true,
+            kind: 'otp_or_manual_verification',
+            question: (context ? `${context} ` : '') +
+                'A one-time code / manual verification step is required. Provide the code, or approve manual completion.',
+            fields: [{ name: 'otp', secret: true, description: 'One-time code from SMS/email/authenticator' }],
+            fallbackOptions: ['complete this step manually, then continue', 'skip flows requiring verification'],
+            resume: resumeVia('otp_or_manual_verification'),
+            attempted: [],
+            ifDeclined: 'Flows behind the verification step are skipped and reported as blocked.',
+        };
+    },
+    monorepoTarget(candidates) {
+        return {
+            needsInput: true,
+            kind: 'monorepo_target',
+            question: `This is a monorepo with multiple app targets. Which one should Swipium test?`,
+            fields: [{ name: 'target', secret: false, description: 'App package/directory to test', example: candidates[0] }],
+            fallbackOptions: candidates.slice(0, 6),
+            resume: { tool: 'qa_continue_from_blocker', args: { kind: 'monorepo_target' } },
+            attempted: [],
+            ifDeclined: 'Swipium cannot guess the intended app; the run does not start until a target is chosen.',
+        };
+    },
+    preferredPlatform(available) {
+        return {
+            needsInput: true,
+            kind: 'preferred_platform',
+            question: `More than one platform is available. Which should Swipium test first?`,
+            fields: [{ name: 'platform', secret: false, example: available[0] }],
+            fallbackOptions: available,
+            resume: resumeVia('preferred_platform'),
+            attempted: [],
+            ifDeclined: 'Swipium picks the first available platform automatically and records it as a workaround.',
+        };
+    },
+    destructiveExplorationApproval(what) {
+        return {
+            needsInput: true,
+            kind: 'destructive_exploration_approval',
+            question: `${what} Exploring it may trigger destructive actions (delete/reset/purchase). Approve, or keep exploration read-only?`,
+            fields: [{ name: 'approveDestructive', secret: false, description: 'true to allow potentially destructive exploration' }],
+            fallbackOptions: ['keep exploration non-destructive (skip risky controls)', 'approve destructive exploration', 'run destructive steps last'],
+            resume: resumeVia('destructive_exploration_approval'),
+            attempted: [],
+            ifDeclined: 'Swipium explores non-destructively and skips controls flagged as risky.',
+        };
+    },
+    signingTeam() {
+        return {
+            needsInput: true,
+            kind: 'signing_team',
+            question: 'A simulator build needs Xcode signing/build settings. Provide a development team if your project requires one, or adjust the simulator build.',
+            fields: [
+                { name: 'developmentTeam', secret: false, description: 'Apple Developer Team ID' },
+                { name: 'provisioningProfile', secret: false, description: 'Provisioning profile name (optional)' },
+            ],
+            fallbackOptions: ['test on simulator instead', 'set up signing in Xcode, then retry'],
+            resume: resumeVia('signing_team'),
+            attempted: [],
+            ifDeclined: 'Swipium reports simulator preparation as blocked until the build settings are fixed.',
+        };
+    },
+    artifactOutsideRoot(path) {
+        return {
+            needsInput: true,
+            kind: 'artifact_outside_root',
+            question: `The best artifact is outside the project root (${path}). Use it anyway?`,
+            fields: [{ name: 'allowOutsideRoot', secret: false }],
+            fallbackOptions: ['use it (allowOutsideRoot)', 'build inside the project instead', 'pass an explicit path'],
+            resume: resumeVia('artifact_outside_root'),
+            attempted: [],
+            ifDeclined: 'Swipium ignores the outside-root artifact and tries to build inside the project, or blocks if it cannot.',
+        };
+    },
+    externalServiceRequired(service) {
+        return {
+            needsInput: true,
+            kind: 'external_service_required',
+            question: `This run needs an external service: ${service}. Provide access/approval to use it, or choose a fallback.`,
+            fields: [
+                { name: 'serviceEndpoint', secret: false, description: 'URL/host of the required service (if applicable)' },
+                { name: 'serviceToken', secret: true, description: 'Access token/key for the service (if required)' },
+            ],
+            fallbackOptions: ['provide service access', 'mock/stub the service', 'skip flows that need it'],
+            resume: resumeVia('external_service_required'),
+            attempted: [],
+            ifDeclined: 'Flows depending on the external service are skipped and reported as blocked.',
+        };
+    },
+    // ---- retained legacy builders (backward compatibility) ----
+    destructiveResetApproval(what) {
+        return {
+            needsInput: true,
+            kind: 'destructive_reset_approval',
+            question: `${what} This is destructive. Approve it, or choose a non-destructive path.`,
+            fields: [{ name: 'approve', secret: false, description: 'true to approve the destructive reset' }],
+            fallbackOptions: ['use a release build for clean-state tests', 'run destructive steps last', 'do not reset'],
+            resume: resumeVia('destructive_reset_approval'),
+            attempted: [],
+            ifDeclined: 'Swipium skips the destructive reset and tests from the current app state.',
+        };
+    },
+    createTestData(what) {
+        return {
+            needsInput: true,
+            kind: 'create_test_data',
+            question: `${what} Should Swipium create the required account/test data, or will you provide it?`,
+            fields: [{ name: 'createTestData', secret: false, description: 'true to let Swipium seed it (consent-gated)' }],
+            fallbackOptions: ['provide existing test data', 'skip flows needing this data'],
+            resume: resumeVia('create_test_data'),
+            attempted: [],
+            ifDeclined: 'Flows needing the data are skipped and reported as blocked.',
+        };
+    },
+    visualOnlyFallback(screen) {
+        return {
+            needsInput: true,
+            kind: 'visual_only_fallback',
+            question: `${screen ? `Screen "${screen}" ` : 'This screen '}has no usable UI tree (canvas/map/webview). ` +
+                'Use visual-only verification (screenshots), which is weaker evidence?',
+            fields: [{ name: 'allowVisualOnly', secret: false }],
+            fallbackOptions: ['use visual-only fallback', 'skip this screen', 'add accessibility identifiers and retry'],
+            resume: resumeVia('visual_only_fallback'),
+            attempted: [],
+            ifDeclined: 'Swipium skips the screen and reports it as not verifiable via the UI tree.',
+        };
+    },
+};
+function renderQuestion(p) {
+    const fields = p.fields.map((f) => `${f.name}${f.secret ? ' (secret)' : ''}`).join(', ');
+    return [
+        `❓ ${p.question}`,
+        fields ? `provide: ${fields}` : '',
+        p.fallbackOptions.length ? `or: ${p.fallbackOptions.join(' | ')}` : '',
+        p.ifDeclined ? `if declined: ${p.ifDeclined}` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/**
+ * Return a NeedsInput result (not an error). The question text is shown in every mode; the
+ * full payload is always in structuredContent. `extra` lets a tool attach context (sessionId,
+ * what was already tried) the agent needs to resume. When `extra.sessionId` is present it is
+ * injected into `resume.args`; `extra.attempted` (string[]) populates `payload.attempted`.
+ */
+export function qaNeedsInput(p, extra) {
+    const sessionId = extra?.sessionId;
+    const attempted = Array.isArray(extra?.attempted) ? extra.attempted : p.attempted;
+    const resume = {
+        tool: p.resume.tool,
+        args: { ...(typeof sessionId === 'string' ? { sessionId } : {}), ...p.resume.args },
+    };
+    const enriched = { ...p, attempted, resume };
+    const payload = { ok: true, ...enriched, ...(extra ?? {}) };
+    const head = renderQuestion(enriched);
+    const text = currentResponseMode() === 'compact' ? head : `${head}\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+    return { content: [{ type: 'text', text }], structuredContent: payload };
+}
+//# sourceMappingURL=needsInput.js.map

package/dist/lib/needsInput.js.map

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

package/dist/lib/png.js

@@ -0,0 +1,103 @@
+// Minimal zero-dependency PNG decode (PHASE3-PLAN §8). Device screenshots come from
+// `screencap -p` as non-interlaced 8-bit truecolor(+alpha) PNGs, so we support exactly that
+// (color types 2 and 6, bit depth 8, interlace 0) and error clearly on anything else. Uses
+// Node's built-in zlib — no image library, no third-party code.
+import { inflateSync } from 'node:zlib';
+/** Read width/height from the IHDR without decoding pixels (for the coordinate-space audit). */
+export function pngSize(buf) {
+    if (buf.length < 24 || buf.readUInt32BE(0) !== 0x89504e47)
+        return null; // PNG signature
+    // IHDR data starts at byte 16 (after 8-byte sig + 4 len + 4 type)
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    return pb <= pc ? b : c;
+}
+export function decodePng(buf) {
+    if (buf.length < 8 || buf.readUInt32BE(0) !== 0x89504e47)
+        throw new Error('not a PNG');
+    let pos = 8;
+    let width = 0;
+    let height = 0;
+    let bitDepth = 0;
+    let colorType = 0;
+    let interlace = 0;
+    const idat = [];
+    while (pos + 8 <= buf.length) {
+        const len = buf.readUInt32BE(pos);
+        const type = buf.toString('ascii', pos + 4, pos + 8);
+        const dataStart = pos + 8;
+        if (type === 'IHDR') {
+            width = buf.readUInt32BE(dataStart);
+            height = buf.readUInt32BE(dataStart + 4);
+            bitDepth = buf[dataStart + 8];
+            colorType = buf[dataStart + 9];
+            interlace = buf[dataStart + 12];
+        }
+        else if (type === 'IDAT') {
+            idat.push(buf.subarray(dataStart, dataStart + len));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        pos = dataStart + len + 4; // skip data + CRC
+    }
+    if (bitDepth !== 8 || interlace !== 0 || (colorType !== 2 && colorType !== 6)) {
+        throw new Error(`unsupported PNG (bitDepth=${bitDepth}, colorType=${colorType}, interlace=${interlace}); expected 8-bit truecolor`);
+    }
+    const channels = colorType === 6 ? 4 : 3;
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = width * channels;
+    const out = Buffer.allocUnsafe(height * stride);
+    // Un-filter each scanline (PNG filter types 0..4), reconstructing in place.
+    let rp = 0;
+    for (let y = 0; y < height; y++) {
+        const filter = raw[rp++];
+        const o = y * stride;
+        const po = (y - 1) * stride;
+        for (let x = 0; x < stride; x++) {
+            const cur = raw[rp++];
+            const a = x >= channels ? out[o + x - channels] : 0; // left
+            const b = y > 0 ? out[po + x] : 0; // up
+            const c = x >= channels && y > 0 ? out[po + x - channels] : 0; // up-left
+            let val;
+            switch (filter) {
+                case 0:
+                    val = cur;
+                    break;
+                case 1:
+                    val = cur + a;
+                    break;
+                case 2:
+                    val = cur + b;
+                    break;
+                case 3:
+                    val = cur + ((a + b) >> 1);
+                    break;
+                case 4:
+                    val = cur + paeth(a, b, c);
+                    break;
+                default: throw new Error(`bad PNG filter ${filter} at row ${y}`);
+            }
+            out[o + x] = val & 0xff;
+        }
+    }
+    return { width, height, channels, data: out };
+}
+/** Convert a decoded image to a grayscale Uint8Array (one byte per pixel). */
+export function toGray(img) {
+    const { width, height, channels, data } = img;
+    const g = new Uint8Array(width * height);
+    for (let i = 0, p = 0; i < g.length; i++, p += channels) {
+        // Rec.601 luma
+        g[i] = (data[p] * 0.299 + data[p + 1] * 0.587 + data[p + 2] * 0.114) | 0;
+    }
+    return g;
+}
+//# sourceMappingURL=png.js.map

package/dist/lib/png.js.map

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

package/dist/lib/redact.js

@@ -0,0 +1,21 @@
+// Sensitive-mode redaction (DESIGN §9.7, M6). Two mechanisms:
+//  1. isSecureNode → a field whose VALUE must never be shown (password/OTP/etc.).
+//  2. makeRedactor → scrub known secret values (things typed into secure fields) from any
+//     string we emit (snapshots, inspect, report, dump-xml artifacts, logs).
+const SECRET_RE = /password|passwd|otp|one.?time|pin\b|cvv|card.?number|secret|token|security.?code/i;
+export function isSecureNode(n) {
+    return n.attrs?.password === 'true' || SECRET_RE.test(n.id) || SECRET_RE.test(n.desc);
+}
+export function makeRedactor(secrets) {
+    const list = [...secrets].filter((x) => x && x.length >= 2).sort((a, b) => b.length - a.length);
+    return (s) => {
+        if (!s || list.length === 0)
+            return s;
+        let out = s;
+        for (const sec of list)
+            if (out.includes(sec))
+                out = out.split(sec).join('«redacted»');
+        return out;
+    };
+}
+//# sourceMappingURL=redact.js.map

package/dist/lib/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/lib/redact.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,kFAAkF;AAClF,0FAA0F;AAC1F,6EAA6E;AAI7E,MAAM,SAAS,GAAG,mFAAmF,CAAC;AAEtG,MAAM,UAAU,YAAY,CAAC,CAAyC;IACpE,OAAO,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACxF,CAAC;AAID,MAAM,UAAU,YAAY,CAAC,OAAyB;IACpD,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAChG,OAAO,CAAC,CAAU,EAAE,EAAE;QACpB,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACtC,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACvF,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/result.js

@@ -0,0 +1,87 @@
+// Tool result envelopes (DESIGN §3 "Every tool is self-diagnosing", §2.1 contract).
+//
+// Recoverable failures are returned as isError:true with a structured, actionable
+// payload — NOT thrown. Thrown/JSON-RPC errors are reserved for malformed calls or a
+// broken server (the model can't act on those).
+//
+// Response modes (PHASE3-PLAN §2.1): a session can ask for `compact | normal | verbose`
+// output. The human-readable text is rendered per mode; `structuredContent` is ALWAYS the
+// full payload, so a client that reads structured data loses nothing in compact mode. The
+// active mode is carried in AsyncLocalStorage so EVERY tool inherits it without touching a
+// single call site, and concurrent JSON-RPC requests can't clobber each other's mode.
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const DEFAULT_RESPONSE_MODE = 'normal';
+const modeStore = new AsyncLocalStorage();
+/** Run `fn` with `mode` as the active response mode for everything it (asynchronously) calls. */
+export function runWithResponseMode(mode, fn) {
+    return modeStore.run(mode, fn);
+}
+/** The response mode in effect for the current tool call (default normal). */
+export function currentResponseMode() {
+    return modeStore.getStore() ?? DEFAULT_RESPONSE_MODE;
+}
+function fence(obj) {
+    return '```json\n' + JSON.stringify(obj, null, 2) + '\n```';
+}
+/** Pull any artifact/resource URIs out of a payload so compact mode can still surface them. */
+function uriLines(payload) {
+    const out = [];
+    const push = (label, v) => {
+        if (typeof v === 'string' && v.startsWith('swipium://'))
+            out.push(`${label}: ${v}`);
+    };
+    push('artifact', payload.artifactUri);
+    if (Array.isArray(payload.artifactUris)) {
+        for (const u of payload.artifactUris)
+            push('artifact', u);
+    }
+    push('screenshot', payload.screenshotUri);
+    push('report', payload.reportUri);
+    return out;
+}
+/**
+ * Compose the human text block for a result. compact = summary (+ any artifact URIs) only,
+ * dropping the fenced-JSON duplicate that structuredContent already carries; normal/verbose
+ * keep the fence for clients/humans reading the text channel.
+ */
+function renderText(summary, payload, mode) {
+    if (mode === 'compact') {
+        const uris = uriLines(payload);
+        return uris.length ? `${summary}\n${uris.join('\n')}` : summary;
+    }
+    return `${summary}\n\n${fence(payload)}`;
+}
+export function qaError(p, extra) {
+    const payload = { ok: false, ...p, ...(extra ?? {}) };
+    const mode = currentResponseMode();
+    const head = [
+        `❌ ${p.what}`,
+        p.commandAttempted ? `command: ${p.commandAttempted}` : '',
+        `changedState=${p.changedState} retrySafe=${p.retrySafe}`,
+        p.nextSteps.length ? `next: ${p.nextSteps.join(' | ')}` : '',
+        p.clientHint ? `hint: ${p.clientHint}` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    // Errors keep their actionable head in every mode; only the fenced JSON duplicate is
+    // dropped in compact (structuredContent still carries the full payload).
+    const text = mode === 'compact' ? head : `${head}\n${fence(payload)}`;
+    return { isError: true, content: [{ type: 'text', text }], structuredContent: payload };
+}
+export function qaOk(payload, summary) {
+    const structured = { ok: true, ...payload };
+    return {
+        content: [{ type: 'text', text: renderText(summary, structured, currentResponseMode()) }],
+        structuredContent: structured,
+    };
+}
+/** A deliberate, budgeted stop (not an error). The agent should call qa_report next. */
+export function qaStop(reason, payload) {
+    const structured = { ok: true, stopped: true, reason, ...payload };
+    const summary = `⏹ Stopped: ${reason}\nCall qa_report to summarize what was verified.`;
+    return {
+        content: [{ type: 'text', text: renderText(summary, structured, currentResponseMode()) }],
+        structuredContent: structured,
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/lib/result.js.map

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

package/dist/lib/schemaHash.js

@@ -0,0 +1,65 @@
+// Schema-hash freshness (Phase 3.3 Milestone A). A version bump tells a HUMAN the server changed,
+// but a client running a pre-upgrade build with the same tool COUNT can still look fresh after a
+// behavior/schema/description change (the 3.2.1 problem). The schema hash is a content fingerprint
+// of the registered tool surface — names + descriptions + input-parameter keys — so an agent/client
+// can detect "same count, different surface" and know to restart.
+import { createHash } from 'node:crypto';
+/** Deterministic hash of the tool surface (order-independent). */
+export function computeSchemaHash(entries) {
+    const normalized = entries
+        .map((e) => ({ name: e.name, description: e.description, inputKeys: [...e.inputKeys].sort() }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return createHash('sha256').update(JSON.stringify(normalized)).digest('hex').slice(0, 16);
+}
+/**
+ * Best-effort normalized descriptor of a single zod input field (Phase 3.3 §5 deeper hash). Encodes
+ * the type, enum options, optionality, and array/record element types so a NESTED change (e.g. a new
+ * enum value or a string→number switch) shifts the hash even when the field name is unchanged.
+ * Falls back to 'field' on any introspection surprise — the hash stays stable, never throws.
+ */
+export function describeZodField(schema, depth = 0) {
+    if (depth > 4 || !schema || typeof schema !== 'object')
+        return 'field';
+    const def = schema._def;
+    if (!def)
+        return 'field';
+    const typeName = String(def.typeName ?? '');
+    try {
+        switch (typeName) {
+            case 'ZodOptional':
+            case 'ZodNullable':
+                return `${describeZodField(def.innerType, depth + 1)}?`;
+            case 'ZodDefault':
+                return `${describeZodField(def.innerType, depth + 1)}=def`;
+            case 'ZodEnum':
+                return `enum(${[...(def.values ?? [])].sort().join('|')})`;
+            case 'ZodNativeEnum':
+                return `nenum(${Object.values(def.values ?? {}).sort().join('|')})`;
+            case 'ZodArray':
+                return `array<${describeZodField(def.type, depth + 1)}>`;
+            case 'ZodRecord':
+                return `record<${describeZodField(def.valueType, depth + 1)}>`;
+            case 'ZodUnion':
+                return `union(${(def.options ?? []).map((o) => describeZodField(o, depth + 1)).join('|')})`;
+            case 'ZodObject': {
+                const shape = typeof def.shape === 'function' ? def.shape() : def.shape ?? {};
+                return `obj{${Object.keys(shape).sort().join(',')}}`;
+            }
+            default:
+                return typeName.replace(/^Zod/, '').toLowerCase() || 'field';
+        }
+    }
+    catch {
+        return 'field';
+    }
+}
+let _hash;
+/** Set once after the server registers all tools. */
+export function setSchemaHash(hash) {
+    _hash = hash;
+}
+/** The current tool-surface hash, or 'unknown' if the server has not been built yet. */
+export function getSchemaHash() {
+    return _hash ?? 'unknown';
+}
+//# sourceMappingURL=schemaHash.js.map

package/dist/lib/schemaHash.js.map

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

package/dist/lib/sensitive.js

@@ -0,0 +1,13 @@
+// Sensitive-mode refusal (NEXT-PLAN: Security — sensitive-mode session option). A single, honest
+// refusal for any pixel/video/log capture when the session opted into sensitive mode, so a
+// privacy-sensitive project can run Swipium with no screen contents leaving the device.
+import { qaError } from './result.js';
+export function sensitiveRefusal(what) {
+    return qaError({
+        what: `${what} refused — this session is in sensitive mode (no screenshots/video/logs are captured)`,
+        changedState: false,
+        retrySafe: false,
+        nextSteps: ['Start a non-sensitive session (omit sensitive:true) to capture pixels, or rely on structured snapshot + health, which carry no screen contents.'],
+    });
+}
+//# sourceMappingURL=sensitive.js.map

package/dist/lib/sensitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive.js","sourceRoot":"","sources":["../../src/lib/sensitive.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,2FAA2F;AAC3F,wFAAwF;AAExF,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,OAAO,CAAC;QACb,IAAI,EAAE,GAAG,IAAI,uFAAuF;QACpG,YAAY,EAAE,KAAK;QACnB,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,CAAC,iJAAiJ,CAAC;KAC/J,CAAC,CAAC;AACL,CAAC"}