swipium 1.0.0

package/dist/tools/explore.js

@@ -0,0 +1,289 @@
+// qa_explore (Phase 3.3) — bounded, safe-by-default guided exploration as a background job. Drives
+// the runExplore service: observe → rank safe candidates → act → health → graph, writing a screen
+// graph artifact (JSON + Markdown) and recording qa_note outcomes. Returns a running jobId; the
+// terminal state + graphUri land in the job result (poll qa_job_status). Thin wrapper — all logic
+// is in src/explore/*.
+import { z } from 'zod';
+import { qaOk, qaError } from '../lib/result.js';
+import { requireConsent, consumeConsent } from '../consent/consent.js';
+import { getDriver } from '../session/attach.js';
+import { runExplore } from '../explore/runner.js';
+import { appendExploreMemory } from '../explore/memory.js';
+import { buildAppMap } from '../appMap/build.js';
+import { mergeFromExploration } from '../services/testSuiteKnowledge.js';
+import { hasDisposableState } from '../fixtures/catalog.js';
+import { generateAndCompileSuite } from '../services/suiteGenerate.js';
+import { startProgress } from '../session/progress.js';
+import { log } from '../lib/logger.js';
+const HIGH_IMPACT_CONFIRMATION_CLASSES = new Set([
+    'payment',
+    'message_send',
+    'external_invite',
+    'account_delete',
+    'bulk_delete',
+    'permission_change',
+    'data_export',
+    'generic_destructive',
+]);
+function needsHighImpactConfirmation(riskClass) {
+    return !!riskClass && HIGH_IMPACT_CONFIRMATION_CLASSES.has(riskClass);
+}
+function promotedActionsFor(session, graph, promotions) {
+    const promoted = promotions.find((p) => p.status === 'promote');
+    if (!promoted)
+        return [];
+    const edges = graph.allEdges();
+    const used = new Set();
+    const actions = [];
+    for (let i = 0; i < promoted.path.length - 1; i++) {
+        const from = promoted.path[i];
+        const to = promoted.path[i + 1];
+        const edge = edges.find((e) => e.from === from && e.to === to && e.outcome === 'changed_screen');
+        const locatorValue = edge?.action.locator?.value;
+        if (!edge || typeof locatorValue !== 'string')
+            continue;
+        const idx = session.recordedActions.findIndex((a, actionIdx) => (!used.has(actionIdx) &&
+            a.action === edge.action.type &&
+            a.selector === locatorValue &&
+            a.provenance?.originalScreenSignature === edge.preActionState));
+        if (idx >= 0) {
+            used.add(idx);
+            actions.push(session.recordedActions[idx]);
+        }
+    }
+    return actions;
+}
+export function registerExplore(server, sessions) {
+    server.registerTool('qa_explore', {
+        title: 'Guided exploration',
+        description: 'Explore a launched app like a practical QA engineer: bounded, safe-by-default crawl that observes screens, ranks safe actions, taps them, checks health after each, and builds a SCREEN GRAPH (JSON + Markdown artifacts). Skips destructive actions (delete/pay/send/logout) in strict mode; verifies map/canvas screens visually with qa_assert_visual; stops with NeedsInput on an auth wall when credentials are missing. Records durable taps so qa_suite_generate can promote paths. Runs as a JOB — the terminal state (completed/blocked) + graphUri are in the job result (poll qa_job_status). Requires a prepared device (qa_test_this / qa_prepare_target first).',
+        inputSchema: {
+            sessionId: z.string(),
+            goal: z.string().optional().describe('Optional natural-language focus (e.g. "exercise the main tabs").'),
+            depth: z.number().optional().describe('Max navigation depth (default 3).'),
+            maxActions: z.number().optional().describe('Max actions to try (default 20).'),
+            maxScreens: z.number().optional().describe('Max distinct screens to visit (default 12).'),
+            maxDurationMs: z.number().optional(),
+            strategy: z.enum(['crawl', 'task_planner', 'hybrid']).optional().describe('crawl (default): deterministic screen crawl; task_planner: infer semantic QA tasks before acting; hybrid: task planning plus crawl.'),
+            safeMode: z.enum(['strict', 'balanced', 'dry_run_destructive', 'approved_destructive_candidate', 'approved_destructive']).optional().describe('strict (default): safe actions only; balanced: unknown-risk allowed; dry_run_destructive: discover/list destructive candidates without tapping; approved_destructive_candidate: allow exactly one candidate-bound destructive action. approved_destructive is deprecated and refused.'),
+            destructiveCandidate: z
+                .object({
+                screenSignature: z.string(),
+                candidateSignature: z.string(),
+                label: z.string().optional(),
+                locator: z.object({ strategy: z.string().optional(), value: z.string().optional() }).optional(),
+                riskClass: z.string().optional(),
+            })
+                .optional()
+                .describe('Exact candidate returned by a dry_run_destructive exploration. Required with safeMode approved_destructive_candidate.'),
+            confirmHighImpact: z.boolean().optional().describe('Required true for high-impact destructive candidates such as payment, send/share, permission change, account delete, or bulk delete.'),
+            generateSuite: z.boolean().optional().describe('After exploration, score promotable paths and include suite-promotion guidance.'),
+            includeTextEntry: z.boolean().optional().describe('Allow typing into fields (only with a value source — default false).'),
+            stopOnAuth: z.boolean().optional().describe('Return NeedsInput when an auth wall blocks exploration and credentials are missing (default true).'),
+            accountCycle: z
+                .boolean()
+                .optional()
+                .describe('SWIPIUM-REQ-07 controlled account-cycle workflow: on a DISPOSABLE generated account, permit LOGOUT (and only logout) as an expected step; delete/pay/send stay refused. Requires allowGeneratedData. Off by default.'),
+            allowGeneratedData: z.boolean().optional().describe('Allow safe generated disposable-account data (test/staging) — required to use accountCycle.'),
+            consentId: z.string().optional(),
+            approve: z.boolean().optional(),
+        },
+    }, async ({ sessionId, goal, depth, maxActions, maxScreens, maxDurationMs, strategy, safeMode, destructiveCandidate, confirmHighImpact, generateSuite, includeTextEntry, stopOnAuth, accountCycle, allowGeneratedData, consentId, approve }) => {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+        const { driver } = await getDriver(session);
+        if (!driver) {
+            return qaError({ what: 'No device attached to this session', changedState: false, retrySafe: true, nextSteps: ['Prepare a device first: qa_test_this { mode:"execute" } or qa_prepare_target, then qa_explore.'] });
+        }
+        if (safeMode === 'approved_destructive') {
+            return qaError({
+                what: 'Blanket destructive exploration approval has been removed',
+                changedState: false,
+                retrySafe: false,
+                failureCode: 'DESTRUCTIVE_REFUSED',
+                nextSteps: ['Run qa_explore with safeMode:"dry_run_destructive" to discover candidates, then approve one exact candidate with safeMode:"approved_destructive_candidate" and disposable test state.'],
+            });
+        }
+        let destructiveApproval;
+        if (safeMode === 'approved_destructive_candidate') {
+            if (!destructiveCandidate) {
+                return qaError({
+                    what: 'approved_destructive_candidate requires an exact destructiveCandidate',
+                    changedState: false,
+                    retrySafe: false,
+                    failureCode: 'DESTRUCTIVE_REFUSED',
+                    nextSteps: ['Run safeMode:"dry_run_destructive" first and copy one candidate signature/screen/locator into destructiveCandidate.'],
+                });
+            }
+            if (!hasDisposableState(session)) {
+                return qaError({
+                    what: 'Destructive exploration requires disposable test state',
+                    changedState: false,
+                    retrySafe: false,
+                    failureCode: 'MISSING_FIXTURE',
+                    nextSteps: ['Declare a fixture with disposable:true or environment:"test" before approving delete/pay/send/logout workflows.'],
+                });
+            }
+            if (needsHighImpactConfirmation(destructiveCandidate.riskClass) && confirmHighImpact !== true) {
+                return qaError({
+                    what: `High-impact destructive candidate "${destructiveCandidate.label ?? destructiveCandidate.candidateSignature}" requires confirmHighImpact:true`,
+                    changedState: false,
+                    retrySafe: false,
+                    failureCode: 'DESTRUCTIVE_REFUSED',
+                    nextSteps: ['Re-run with confirmHighImpact:true only if this is disposable test state and the action can be safely verified or rolled back.'],
+                });
+            }
+            const approval = {
+                sessionId: session.id,
+                ...destructiveCandidate,
+                consentId,
+                confirmHighImpact: confirmHighImpact === true,
+                expiresAt: Date.now() + 5 * 60_000,
+                singleUse: true,
+                requiresDisposableState: true,
+            };
+            const affects = {
+                sessionId: session.id,
+                screenSignature: destructiveCandidate.screenSignature,
+                candidateSignature: destructiveCandidate.candidateSignature,
+                label: destructiveCandidate.label ?? null,
+                locator: destructiveCandidate.locator ?? null,
+                riskClass: destructiveCandidate.riskClass ?? null,
+                confirmHighImpact: confirmHighImpact === true,
+                requiresDisposableState: true,
+            };
+            const gate = consumeConsent(consentId, approve, { action: 'destructive_ui_candidate', affects });
+            if (!gate.approved) {
+                sessions.recordMutation(session, {
+                    tool: 'qa_explore',
+                    action: 'destructive_ui_candidate',
+                    risk: 'high',
+                    target: affects,
+                    consent: { required: true, approved: false },
+                    status: 'requested',
+                });
+                return requireConsent({
+                    action: 'destructive_ui_candidate',
+                    risk: 'high',
+                    affects,
+                    explain: `Approve exactly one destructive exploration candidate (${destructiveCandidate.label ?? destructiveCandidate.candidateSignature}) on the current screen signature? ` +
+                        'This approval is single-use, expires quickly, and requires disposable test state.',
+                });
+            }
+            sessions.addEnvChange(session, `CONSENT destructive candidate ${destructiveCandidate.candidateSignature} on ${destructiveCandidate.screenSignature}`);
+            sessions.recordMutation(session, {
+                tool: 'qa_explore',
+                action: 'destructive_ui_candidate',
+                risk: 'high',
+                target: affects,
+                consent: { required: true, consentId, approved: true },
+                status: 'approved',
+            });
+            destructiveApproval = approval;
+        }
+        const accountCycleCtx = accountCycle ? { enabled: true, disposableAccount: allowGeneratedData === true } : undefined;
+        const job = sessions.createJob(session, 'explore');
+        void runExploreJob(sessions, session, job, { goal, depth, maxActions, maxScreens, maxDurationMs, strategy, safeMode, destructiveApproval, generateSuite, includeTextEntry, stopOnAuth, accountCycle: accountCycleCtx, allowGeneratedData });
+        return qaOk({ sessionId: session.id, state: 'running', jobId: job.jobId, kind: job.kind }, `🧭 guided exploration started as job ${job.jobId}. Poll qa_job_status { sessionId:"${session.id}", jobId:"${job.jobId}" } for the screen graph + terminal state.`);
+    });
+}
+async function runExploreJob(sessions, session, job, opts) {
+    const signal = sessions.abortSignal(session, job.jobId);
+    const upd = (patch) => sessions.updateJobIfRunning(session, job, patch);
+    const prog = startProgress(sessions, session, job, 'exploring', { statusText: 'Exploring the app safely.', nextExpected: 'Build a screen graph.' });
+    try {
+        const { driver } = await getDriver(session);
+        if (!driver) {
+            upd({ status: 'failed', error: 'no driver', endedAt: Date.now() });
+            return;
+        }
+        const res = await runExplore(sessions, session, driver, opts, { signal, onProgress: (p) => prog.event(p) });
+        if (signal?.aborted)
+            return;
+        // Persist the screen graph as JSON + Markdown artifacts.
+        const at = Date.now();
+        const generatedAt = new Date(at).toISOString();
+        const serializedGraph = res.graph.serialize(generatedAt);
+        const graphUri = sessions.saveArtifact(session, 'explore', `graph-${at}.json`, JSON.stringify(serializedGraph, null, 2), 'application/json', 'exploration screen graph');
+        const graphMdUri = sessions.saveArtifact(session, 'explore', `graph-${at}.md`, res.graph.toMarkdown(new Date(at).toISOString()), 'text/markdown', 'exploration screen graph (readable)');
+        const historyPath = appendExploreMemory(session.root, session.appId, {
+            appId: session.appId ?? 'unknown-app',
+            sessionId: session.id,
+            at: generatedAt,
+            graphUri,
+            graphMdUri,
+            stoppedReason: res.stoppedReason,
+            state: res.state,
+            summary: res.summary,
+            tasks: serializedGraph.tasks,
+            hypotheses: serializedGraph.hypotheses,
+            coverageClaims: serializedGraph.coverageClaims,
+            blockedPreconditions: serializedGraph.blockedPreconditions,
+            reflection: serializedGraph.reflection,
+        });
+        const promotedActions = opts.generateSuite ? promotedActionsFor(session, res.graph, res.suitePromotion) : [];
+        const generatedSuite = opts.generateSuite
+            ? promotedActions.length
+                ? generateAndCompileSuite(sessions, session, { name: 'explore-promoted', actions: promotedActions, save: true, compile: true })
+                : {
+                    skipped: true,
+                    skippedReason: res.suitePromotion.some((p) => p.status === 'promote') ? 'promoted path did not map to recorded replay actions' : 'no promoted exploration path met the replay threshold',
+                    recommendation: 'Review suitePromotion reasons, improve locator readiness, then run qa_suite_generate after replayable actions are recorded.',
+                    written: [],
+                    compiledFlows: [],
+                    suiteRunnable: false,
+                    readinessLabels: [],
+                }
+            : undefined;
+        const record = { at, graphUri, graphMdUri, state: res.state, stoppedReason: res.stoppedReason, summary: res.summary };
+        sessions.setExploration(session, record);
+        // SWIPIUM-REQ-01: merge this exploration into the durable App Knowledge Map by default. Best-effort
+        // — a map failure must never fail the exploration job.
+        try {
+            buildAppMap(session.root, { mode: 'runtime_merge', at: generatedAt, sessionId: session.id, exploreGraph: serializedGraph, persist: true });
+        }
+        catch (e) {
+            log('warn', 'app map merge after explore failed', { jobId: job.jobId, err: String(e) });
+        }
+        // Fix 9: keep the persistent suite current directly after exploration — don't wait for a later
+        // qa_report. Best-effort: a suite-merge failure is a warning, never an exploration failure.
+        const suiteMerge = mergeFromExploration(session.root, record, { source: 'exploration', now: generatedAt, runId: `explore-${at}`, sourceUri: graphUri, appId: session.appId, sessionId: session.id });
+        prog.done(`explored ${res.summary.screensVisited} screens`);
+        const nextRecommendedAction = res.needsInput
+            ? { tool: 'qa_continue_from_blocker', args: { sessionId: session.id, kind: 'credentials' }, why: 'Provide credentials to explore authenticated screens' }
+            : { tool: 'qa_report', args: { sessionId: session.id }, why: 'Summarize the exploration with the screen graph' };
+        upd({
+            status: 'done',
+            progress: res.state,
+            result: {
+                state: res.state,
+                stoppedReason: res.stoppedReason,
+                summary: res.summary,
+                destructiveCandidates: res.destructiveCandidates,
+                graphUri,
+                graphMdUri,
+                historyPath,
+                needsInput: res.needsInput ?? null,
+                suitePromotion: res.suitePromotion,
+                generatedSuite: generatedSuite ?? null,
+                suiteDelta: suiteMerge.delta ?? null,
+                suiteUri: suiteMerge.suiteUri ?? null,
+                suiteWarning: suiteMerge.warning ?? null,
+                nextRecommendedAction,
+            },
+            resultText: `🧭 exploration ${res.state} — ${res.summary.screensVisited} screens, ${res.summary.actionsTried} actions, ${res.summary.workflowsFound} transitions, ${res.summary.visualOnlyScreens} visual-only, ${res.summary.unsafeActionsSkipped} unsafe skipped, ${res.summary.appErrors} app errors.\n` +
+                `reason: ${res.stoppedReason}\ngraph: ${graphUri}` +
+                (generatedSuite && !generatedSuite.skipped ? `\npromoted suite: ${generatedSuite.name}` : '') +
+                (res.needsInput ? `\n❓ ${res.needsInput.question}` : ''),
+            endedAt: Date.now(),
+        });
+    }
+    catch (e) {
+        if (signal?.aborted)
+            return;
+        log('error', 'explore job failed', { jobId: job.jobId, err: String(e) });
+        upd({ status: 'failed', error: String(e), resultText: `❌ exploration error: ${String(e)}`, endedAt: Date.now() });
+    }
+}
+//# sourceMappingURL=explore.js.map

package/dist/tools/explore.js.map

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

package/dist/tools/firstRun.js

@@ -0,0 +1,136 @@
+// SWIPIUM-REQ-02 — first-run MCP tools.
+//   qa_first_run_plan      read-only: classify the current screen + return the safe plan (no acting).
+//   qa_first_run_continue  execute one bounded step or a bounded first-run sequence (mode-driven).
+//
+// These drive the pure planning layer (src/firstRun/*) and the bounded driver loop (firstRunRunner).
+// Secrets (generated passwords) are added to the session redaction set and never appear in output;
+// generated emails are recorded as evidence so a developer can reproduce the throwaway account.
+import { z } from 'zod';
+import { qaOk, qaError } from '../lib/result.js';
+import { qaNeedsInput, NeedsInput } from '../lib/needsInput.js';
+import { getDriver } from '../session/attach.js';
+import { planFirstRun } from '../firstRun/firstRunPlanner.js';
+import { observeScreen, resolveFirstRunPolicy, runFirstRun } from '../firstRun/firstRunRunner.js';
+function needsInputPayload(kind, reason) {
+    if (kind === 'otp_or_manual_verification')
+        return NeedsInput.otp(reason);
+    if (kind === 'create_test_data')
+        return NeedsInput.createTestData(reason);
+    return NeedsInput.credentials(reason);
+}
+export function registerFirstRun(server, sessions) {
+    // ---- qa_first_run_plan (read-only) ----
+    server.registerTool('qa_first_run_plan', {
+        title: 'First-run plan (read-only)',
+        description: 'Read-only. Classifies the CURRENT screen of a launched app (login / create-account / login-or-create / OTP / onboarding / permissions / paywall / home / feature / error) using the UI snapshot + visible text + app-map/code context, then returns the SAFE first-run plan WITHOUT acting: the classification + confidence + evidence, the required inputs, the planned actions, the environment classification, and whether safe generated-account creation is allowed here. No taps, no typing, no secrets. Requires a prepared device (qa_test_this / qa_prepare_target first). To actually execute the plan, call qa_first_run_continue.',
+        inputSchema: {
+            sessionId: z.string(),
+            allowGeneratedAccount: z.boolean().optional().describe('Override the policy decision on creating a throwaway account (true to allow, false to forbid).'),
+            testDataPolicyPath: z.string().optional().describe('Path to a test-data policy JSON (default .swipium/test-data-policy.json).'),
+        },
+    }, async ({ sessionId, allowGeneratedAccount, testDataPolicyPath }) => {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+        const { driver } = await getDriver(session);
+        if (!driver)
+            return qaError({ what: 'No device attached to this session', changedState: false, retrySafe: true, nextSteps: ['Prepare a device first: qa_test_this { mode:"execute" } or qa_prepare_target, then qa_first_run_plan.'] });
+        const { policy, policySource, environment, decision } = resolveFirstRunPolicy(session, { testDataPolicyPath, allowGeneratedAccount });
+        const obs = await observeScreen(sessions, session, driver);
+        const plan = planFirstRun({ ...obs, screenSignature: obs.screenSignature, appError: obs.appError }, session, { policy, decision });
+        const summary = `🔎 first-run plan — screen: ${plan.classification.purpose} (confidence ${plan.classification.confidence})\n` +
+            `environment: ${environment.environment} (prodRisk=${environment.productionRisk}); generated account ${decision.allowed ? 'ALLOWED' : 'NOT allowed'} — ${decision.reason}\n` +
+            `state: ${plan.state}${plan.pathTaken ? ` [${plan.pathTaken}]` : ''}; planned actions: ${plan.actions.length}` +
+            (plan.needsInput ? `\n❓ ${plan.needsInput.reason}` : '') +
+            `\n→ execute with qa_first_run_continue { sessionId:"${session.id}", mode:"one_step" }`;
+        return qaOk({
+            sessionId: session.id,
+            classification: plan.classification,
+            state: plan.state,
+            pathTaken: plan.pathTaken,
+            actions: plan.actions, // no raw values — secrets stay in the secure store
+            expectedNextPurposes: plan.expectedNextPurposes,
+            stopConditions: plan.stopConditions,
+            appMapPatch: plan.mapUpdates,
+            environment,
+            generatedAccountDecision: decision,
+            policySource,
+            needsInput: plan.needsInput ?? null,
+            nextRecommendedTool: plan.nextRecommendedTool ?? 'qa_first_run_continue',
+            evidence: obs.screenshotUri ? [obs.screenshotUri] : [],
+        }, summary);
+    });
+    // ---- qa_first_run_continue (executes) ----
+    server.registerTool('qa_first_run_continue', {
+        title: 'First-run continue (execute)',
+        description: 'Executes the first-run plan as a practical QA engineer: classifies each screen and, in a TEST/STAGING environment, safely fills login/create-account forms with generated data (email swipium_<timestamp>@yopmail.com + a strong password stored as a secret), moves through onboarding via safe Next/Continue/Skip, records paywall coverage WITHOUT purchasing, and hands permission prompts to the guardrails. mode: one_step (one screen) | until_gate (until a paywall/OTP/permission gate) | until_home (until home/feature). Refuses automatic account creation in unknown/production-like environments and returns ONE NeedsInput question instead. Stops with NeedsInput on OTP/verification. Returns screen classifications, generated variables (secrets redacted), actions attempted, the resulting state, an appMapPatch, evidence URIs, and the next recommended tool. Requires a prepared device.',
+        inputSchema: {
+            sessionId: z.string(),
+            mode: z.enum(['one_step', 'until_gate', 'until_home']).optional().describe('one_step (default): one screen; until_gate: until a paywall/OTP/permission gate; until_home: until home/feature.'),
+            allowGeneratedAccount: z.boolean().optional().describe('Override the policy decision on creating a throwaway account.'),
+            testDataPolicyPath: z.string().optional().describe('Path to a test-data policy JSON (default .swipium/test-data-policy.json).'),
+            maxSteps: z.number().optional(),
+            maxDurationMs: z.number().optional(),
+        },
+    }, async ({ sessionId, mode, allowGeneratedAccount, testDataPolicyPath, maxSteps, maxDurationMs }) => {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+        const { driver } = await getDriver(session);
+        if (!driver)
+            return qaError({ what: 'No device attached to this session', changedState: false, retrySafe: true, nextSteps: ['Prepare a device first: qa_test_this { mode:"execute" } or qa_prepare_target, then qa_first_run_continue.'] });
+        const res = await runFirstRun(sessions, session, driver, {
+            mode: (mode ?? 'one_step'),
+            allowGeneratedAccount, testDataPolicyPath, maxSteps, maxDurationMs,
+        });
+        // Fix Group 5: fold first-run classifications into the durable app map (not just a detached
+        // artifact) so a runtime login/onboarding/paywall screen updates .swipium/app-map.json.
+        let appMapUri;
+        if (res.mapUpdates.length) {
+            try {
+                const { buildAppMap } = await import('../appMap/build.js');
+                const built = buildAppMap(session.root, { mode: 'runtime_merge', at: new Date().toISOString(), sessionId: session.id, firstRunPatches: res.mapUpdates, persist: true });
+                appMapUri = built.save?.resourceUri;
+            }
+            catch {
+                /* best-effort: the forward-compatible artifact still carries the patches */
+            }
+        }
+        const payload = {
+            sessionId: session.id,
+            state: res.state,
+            stoppedReason: res.stoppedReason,
+            steps: res.steps,
+            classifications: res.steps.map((s) => ({ purpose: s.purpose, confidence: s.confidence, state: s.state, screenSignature: s.screenSignature })),
+            environment: res.environment,
+            generatedAccountDecision: res.decision,
+            policySource: res.policySource,
+            generatedVariables: res.generatedVariables, // secrets already redacted
+            appMapPatch: res.mapUpdates,
+            appMapArtifactUri: res.mapArtifactUri ?? null,
+            appMapUri: appMapUri ?? null,
+            evidence: res.evidenceUris,
+            pathTaken: res.pathTaken,
+            accountOutcome: res.accountOutcome,
+            nextRecommendedTool: res.nextRecommendedTool ?? null,
+            needsInput: res.needsInput ?? null,
+        };
+        const summary = `🚦 first-run ${res.state} — ${res.steps.length} screen(s); path: ${res.pathTaken}; account: ${res.accountOutcome}\n` +
+            `environment: ${res.environment.environment} (prodRisk=${res.environment.productionRisk}); generated account ${res.decision.allowed ? 'allowed' : 'refused'}\n` +
+            `reason: ${res.stoppedReason}` +
+            (res.generatedVariables.length ? `\ngenerated: ${res.generatedVariables.map((g) => `${g.varName}=${g.value}`).join(', ')}` : '') +
+            (res.mapArtifactUri ? `\napp-map: ${res.mapArtifactUri}` : '') +
+            (res.nextRecommendedTool ? `\n→ next: ${res.nextRecommendedTool}` : '');
+        // A genuine pause → surface the single NeedsInput question (not an error).
+        if ((res.state === 'needs_input' || res.state === 'unsafe') && res.needsInput) {
+            return qaNeedsInput(needsInputPayload(res.needsInput.kind, res.needsInput.reason), {
+                sessionId: session.id,
+                state: res.state,
+                attempted: res.steps.map((s) => `classified "${s.purpose}" (confidence ${s.confidence})`),
+                firstRun: payload,
+            });
+        }
+        return qaOk(payload, summary);
+    });
+}
+//# sourceMappingURL=firstRun.js.map

package/dist/tools/firstRun.js.map

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