rea-agents 2.1.0 → 2.3.0

package/dist/application/ProcessReactiveCoordinator.js

@@ -0,0 +1,218 @@
+import { commitProcessReactiveProposal, createProcessReactiveSnapshot, reduceProcessReactiveScenario, } from "../domain/processReactiveRuntime.js";
+const systemTimerHost = {
+    schedule: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs);
+        return { cancel: () => clearTimeout(timer) };
+    },
+};
+/**
+ * Serializes live observations, deadlines, and effect commits for one run.
+ * Producer callbacks enqueue work without awaiting it, preventing reentrancy.
+ */
+export class ProcessReactiveCoordinator {
+    #scenario;
+    #executor;
+    #timerHost;
+    #now;
+    #scenarioDeadlineAt;
+    #onDecision;
+    #snapshot;
+    #pendingInputs = [];
+    #tail = Promise.resolve();
+    #running = false;
+    #failure;
+    #stateTimer;
+    #scenarioTimer;
+    #stateDeadlineAt = 0;
+    #effectAbort;
+    #accepting = true;
+    #closed = false;
+    constructor(options) {
+        this.#scenario = options.scenario;
+        this.#executor = options.executor;
+        this.#timerHost = options.timerHost ?? systemTimerHost;
+        this.#now = options.now ?? Date.now;
+        this.#scenarioDeadlineAt = this.#now() + options.scenario.deadline_ms;
+        this.#onDecision = options.onDecision;
+        this.#snapshot = createProcessReactiveSnapshot(options.scenario);
+        this.#scheduleScenarioDeadline();
+        this.#scheduleStateDeadline();
+    }
+    /** Current immutable reducer snapshot after all completed turns. */
+    get snapshot() {
+        return this.#snapshot;
+    }
+    /** Enqueue producer work without creating a floating promise. */
+    enqueue(input) {
+        if (!this.#accepting)
+            return;
+        if (this.#interruptsEffects(input))
+            this.#effectAbort?.abort();
+        this.#enqueueOwned(input);
+    }
+    /** Submit one input and wait until every turn queued before it completes. */
+    async submit(input) {
+        this.enqueue(input);
+        await this.drain();
+        return this.#snapshot;
+    }
+    /** Wait for currently queued reducer/effect work and surface host failures. */
+    async drain() {
+        for (;;) {
+            const observedTail = this.#tail;
+            await observedTail;
+            if (observedTail === this.#tail)
+                break;
+        }
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+    /** Stop owned deadlines after queued work settles. */
+    async close() {
+        this.#accepting = false;
+        this.#clearTimers();
+        await this.drain();
+        this.#closed = true;
+    }
+    #enqueueOwned(input) {
+        if (this.#closed || this.#failure !== undefined)
+            return;
+        this.#pendingInputs.push(input);
+        this.#startWorker();
+    }
+    #startWorker() {
+        if (this.#running || this.#pendingInputs.length === 0)
+            return;
+        this.#running = true;
+        this.#tail = this.#runQueue()
+            .catch((cause) => this.#fail(cause))
+            .finally(() => {
+            this.#running = false;
+            if (this.#pendingInputs.length > 0)
+                this.#startWorker();
+        });
+    }
+    async #runQueue() {
+        for (;;) {
+            const input = this.#nextInput();
+            if (input === undefined)
+                return;
+            await this.#advance(input);
+        }
+    }
+    #nextInput() {
+        const terminalIndex = this.#pendingInputs.findIndex(({ kind }) => kind === "cancelled" || kind === "cleanup_failed");
+        if (terminalIndex >= 0)
+            return this.#pendingInputs.splice(terminalIndex, 1)[0];
+        let observationIndex = -1;
+        let captureOrder = Number.POSITIVE_INFINITY;
+        for (const [index, input] of this.#pendingInputs.entries())
+            if (input.kind === "observation" &&
+                input.observation.capture_order < captureOrder) {
+                observationIndex = index;
+                captureOrder = input.observation.capture_order;
+            }
+        return observationIndex >= 0
+            ? this.#pendingInputs.splice(observationIndex, 1)[0]
+            : this.#pendingInputs.shift();
+    }
+    #fail(cause) {
+        this.#failure ??= cause;
+        this.#accepting = false;
+        this.#closed = true;
+        this.#effectAbort?.abort();
+        this.#pendingInputs.length = 0;
+        this.#clearTimers();
+    }
+    async #advance(input) {
+        const before = this.#snapshot;
+        let decision = reduceProcessReactiveScenario(this.#scenario, before, input);
+        let effectResults = [];
+        if (decision.kind === "proposal") {
+            const effectAbort = new AbortController();
+            this.#effectAbort = effectAbort;
+            try {
+                effectResults = await this.#executor.execute(decision.effects, effectAbort.signal);
+            }
+            catch (cause) {
+                if (effectAbort.signal.aborted)
+                    return;
+                throw cause;
+            }
+            finally {
+                if (this.#effectAbort === effectAbort)
+                    this.#effectAbort = undefined;
+            }
+            if (effectAbort.signal.aborted)
+                return;
+            const expired = this.#expiredDeadlineInput();
+            if (expired !== undefined) {
+                this.#enqueueOwned(expired);
+                return;
+            }
+            decision = commitProcessReactiveProposal(this.#scenario, decision, effectResults);
+        }
+        this.#snapshot = decision.snapshot;
+        this.#onDecision?.(decision);
+        if (this.#snapshot.status === "finished")
+            this.#clearTimers();
+        else if (this.#accepting &&
+            (before.active_state !== this.#snapshot.active_state ||
+                before.state_entry_capture_order !==
+                    this.#snapshot.state_entry_capture_order))
+            this.#scheduleStateDeadline();
+        for (const result of effectResults)
+            if (result.status === "succeeded")
+                this.#enqueueOwned({
+                    kind: "observation",
+                    observation: result.observation,
+                });
+    }
+    #interruptsEffects(input) {
+        if (input.kind === "cancelled" ||
+            input.kind === "cleanup_failed" ||
+            input.kind === "scenario_deadline")
+            return true;
+        return (input.kind === "state_deadline" &&
+            input.state_id === this.#snapshot.active_state &&
+            input.state_entry_capture_order ===
+                this.#snapshot.state_entry_capture_order);
+    }
+    #expiredDeadlineInput() {
+        const now = this.#now();
+        if (now >= this.#scenarioDeadlineAt)
+            return { kind: "scenario_deadline" };
+        if (now < this.#stateDeadlineAt)
+            return undefined;
+        return {
+            kind: "state_deadline",
+            state_id: this.#snapshot.active_state,
+            state_entry_capture_order: this.#snapshot.state_entry_capture_order,
+        };
+    }
+    #scheduleScenarioDeadline() {
+        if (!this.#accepting)
+            return;
+        this.#scenarioTimer = this.#timerHost.schedule(() => this.enqueue({ kind: "scenario_deadline" }), this.#scenario.deadline_ms);
+    }
+    #scheduleStateDeadline() {
+        if (!this.#accepting)
+            return;
+        this.#stateTimer?.cancel();
+        const state = this.#scenario.states.find(({ id }) => id === this.#snapshot.active_state);
+        if (state === undefined)
+            return;
+        this.#stateDeadlineAt = this.#now() + state.deadline_ms;
+        const identity = {
+            state_id: state.id,
+            state_entry_capture_order: this.#snapshot.state_entry_capture_order,
+        };
+        this.#stateTimer = this.#timerHost.schedule(() => this.enqueue({ kind: "state_deadline", ...identity }), state.deadline_ms);
+    }
+    #clearTimers() {
+        this.#stateTimer?.cancel();
+        this.#scenarioTimer?.cancel();
+        this.#stateTimer = undefined;
+        this.#scenarioTimer = undefined;
+    }
+}

package/dist/application/ProcessReactiveEffects.js

@@ -0,0 +1,133 @@
+import { createProcessObservation } from "../domain/processObservation.js";
+const elapsed = (host) => Math.max(0, host.now() - host.startedAtMs);
+const interactionData = (action) => {
+    if (action.type === "send_input")
+        return action.sensitive
+            ? `<redacted-input:${String(Buffer.byteLength(action.data))}-bytes>`
+            : action.data;
+    if (action.type === "resize")
+        return `${String(action.columns)}x${String(action.rows)}`;
+    return action.signal;
+};
+const interactionType = (action) => {
+    if (action.type === "send_input")
+        return "input";
+    if (action.type === "resize")
+        return "resize";
+    return "signal";
+};
+const performTerminalAction = (terminal, renderer, action, atMs) => {
+    if (action.type === "send_input")
+        terminal.write(action.data);
+    else if (action.type === "resize") {
+        terminal.resize(action.columns, action.rows);
+        renderer.resize(action.columns, action.rows, atMs);
+    }
+    else
+        terminal.kill(action.signal);
+};
+const recordInteraction = (host, action, atMs, outcome) => {
+    const index = host.interactions.length;
+    const event = {
+        sequence: index,
+        scheduled_at_ms: atMs,
+        dispatched_at_ms: atMs,
+        type: interactionType(action),
+        data: interactionData(action),
+        outcome,
+    };
+    host.interactions.push(event);
+    const location = host.journal.record("interaction_events", index);
+    if (outcome !== "dispatched")
+        return { status: "rejected" };
+    return {
+        status: "succeeded",
+        observation: createProcessObservation({
+            source: "interaction",
+            source_sequence: index,
+            captured_at_ms: atMs,
+            subject_id: null,
+            location,
+            payload: event,
+        }),
+    };
+};
+const executeTerminalAction = (host, action) => {
+    if (action.type === "send_signal" && action.target.kind !== "root")
+        return { status: "rejected" };
+    const terminal = host.terminal();
+    if (terminal === undefined)
+        return { status: "target_lost" };
+    const atMs = elapsed(host);
+    let outcome = "dispatched";
+    try {
+        performTerminalAction(terminal, host.renderer, action, atMs);
+    }
+    catch {
+        outcome = "failed";
+    }
+    return recordInteraction(host, action, atMs, outcome);
+};
+const executeCheckpoint = async (host, action, signal) => {
+    try {
+        const { index, checkpoint } = await host.checkpoints.captureAndRead(action.name, signal);
+        const location = host.journal.entries.findLast((entry) => entry.collection === "filesystem_checkpoints" && entry.index === index);
+        if (location === undefined)
+            return { status: "rejected" };
+        return {
+            status: "succeeded",
+            observation: createProcessObservation({
+                source: "filesystem",
+                source_sequence: index,
+                captured_at_ms: checkpoint.at_ms,
+                subject_id: `checkpoint:${checkpoint.name}`,
+                location,
+                payload: checkpoint,
+            }),
+        };
+    }
+    catch {
+        return { status: "rejected" };
+    }
+};
+/** Execute proposed effects in order and stop after the first failure. */
+export const executeProcessReactiveEffects = async (host, actions, signal) => {
+    const results = [];
+    for (const action of actions) {
+        if (signal.aborted)
+            return results;
+        const result = action.type === "checkpoint"
+            ? await executeCheckpoint(host, action, signal)
+            : executeTerminalAction(host, action);
+        results.push(result);
+        if (result.status !== "succeeded")
+            break;
+    }
+    return results;
+};
+const triggerSources = (trigger) => {
+    if (trigger.kind === "terminal_text")
+        return [];
+    if (trigger.kind === "event")
+        return ["terminal_raw", "interaction", "filesystem"].includes(trigger.source)
+            ? []
+            : [trigger.source];
+    return trigger.kind === "repeat"
+        ? triggerSources(trigger.trigger)
+        : trigger.triggers.flatMap(triggerSources);
+};
+/** Return unsupported sources, selectors, and checkpoint collisions pre-launch. */
+export const unsupportedProcessReactiveFeatures = (scenario, reservedCheckpointNames = new Set([
+    "before",
+    "after_settlement",
+])) => [
+    ...scenario.states.flatMap((state) => state.on.flatMap((transition) => triggerSources(transition.when).map((source) => `${transition.id}:source:${source}`))),
+    ...scenario.states.flatMap((state) => state.on.flatMap((transition) => transition.actions.flatMap((action) => {
+        if (action.type === "send_signal" && action.target.kind !== "root")
+            return [`${transition.id}:target:${action.target.kind}`];
+        if (action.type === "checkpoint" &&
+            reservedCheckpointNames.has(action.name))
+            return [`${transition.id}:checkpoint:${action.name}`];
+        return [];
+    }))),
+];

package/dist/application/ProcessReactiveObservations.js

@@ -0,0 +1,20 @@
+import { createProcessObservation } from "../domain/processObservation.js";
+/** Subscribe a reactive coordinator to normalized raw PTY journal records. */
+export const subscribeProcessReactiveTerminalObservations = (options) => options.journal.subscribe((entry) => {
+    if (entry.collection !== "frames")
+        return;
+    const frame = options.frames[entry.index];
+    if (frame === undefined)
+        return;
+    options.sink.enqueue({
+        kind: "observation",
+        observation: createProcessObservation({
+            source: "terminal_raw",
+            source_sequence: frame.sequence,
+            captured_at_ms: frame.at_ms,
+            subject_id: null,
+            location: entry,
+            payload: frame,
+        }),
+    });
+});

package/dist/application/ProcessSampling.js

@@ -366,7 +366,9 @@ export const startProcessSampler = (options) => {
                     continue;
                 }
                 lastObservations.set(value.pid, observation);
+                const index = samples.length;
                 samples.push(value);
+                options.recordEvent?.("process_samples", index);
             }
         })
             .catch((cause) => {

package/dist/application/SessionProviderRouter.js

@@ -86,7 +86,7 @@ export class SessionProviderRouter {
             compatibility: {},
             binding: null,
             selection: undefined,
-            createClient: (target) => createLegacyClient(runtime, target, undefined),
+            createClient: (target, context) => createLegacyClient(runtime, target, undefined, context),
         };
     }
     /** Resolve target routes before any provider client is created. */
@@ -122,7 +122,7 @@ export class SessionProviderRouter {
             compatibility: normalized.value.compatibility,
             binding: null,
             selection: undefined,
-            createClient: (openedTarget) => createLegacyClient(runtime, openedTarget, normalized.value.profile ?? undefined),
+            createClient: (openedTarget, context) => createLegacyClient(runtime, openedTarget, normalized.value.profile ?? undefined, context),
         });
     }
     /** Candidate status authoritative for the active or target-free route. */
@@ -156,12 +156,13 @@ const selectableRoute = (auxiliaryProviders, selection) => {
         compatibility: structuredClone(binding?.compatibility ?? {}),
         binding,
         selection,
-        createClient: (target) => provider?.createClient(target, binding?.profile) ?? emptyClient(identity),
+        createClient: (target, context) => provider?.createClient(target, binding?.profile, context) ??
+            emptyClient(identity),
     };
 };
-const createLegacyClient = (runtime, target, profile) => typeof runtime.provider === "function"
-    ? runtime.provider(target, profile)
-    : runtime.provider.createClient(target, profile);
+const createLegacyClient = (runtime, target, profile, context) => typeof runtime.provider === "function"
+    ? runtime.provider(target, profile, context)
+    : runtime.provider.createClient(target, profile, context);
 const emptyClient = (identity) => ({
     execute: (operation) => operation === "health"
         ? Promise.resolve(ok({

package/dist/application/Setup.js

@@ -13,16 +13,18 @@ import { discoverSetupActions } from "./SetupPlan.js";
 import { clientConfigurationAligned, configureJsonClient, configureTomlClient, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
 export { configureJsonClient, configureTomlClient };
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
+import { providerRegistrationEnvironment, registrationPermissionEnvironment, } from "./SetupRegistrationEnvironment.js";
+export { registrationPermissionEnvironment } from "./SetupRegistrationEnvironment.js";
 export { canonicalSkillNeedsInstall, installCanonicalSkill };
 const registrationCommand = () => process.env.npm_command === "exec"
-    ? ["npx", "-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]
+    ? PRODUCT_IDENTITY.mcpCommand.split(" ")
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const appliedActions = [];
     let plannedActions = [];
     const clients = {};
-    const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients]);
+    const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients], options.readinessScope);
     const unsupported = await hostRemediation(host, options.installHopper);
     if (unsupported !== undefined)
         return fail(unsupported);
@@ -36,6 +38,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         proposeHopper: options.proposeHopper ?? true,
         selectedClientIds: options.clientIds,
         installSkillSelection: options.installSkill,
+        doctorScope: options.readinessScope,
     });
     if (discovery.blocker !== undefined)
         return fail(discovery.blocker);
@@ -47,7 +50,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             plannedActions,
             appliedActions,
             clients,
-            doctor: await host.doctor(),
+            doctor: discovery.initialDoctor,
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
     let detectedClients = selection.detectedClients;
@@ -61,6 +64,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             clients,
             detectedClients,
             providerEnvironment,
+            doctorScope: options.readinessScope,
         });
         if ("failure" in install)
             return install.failure;
@@ -82,7 +86,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (selection.installSkill &&
         !(await installSkillAction(host, options, appliedActions)))
         return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
-    const doctor = await host.doctor();
+    const doctor = await host.doctor(options.readinessScope);
     const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
         status: remediation === undefined ? "ready" : "needs_human",
@@ -110,7 +114,7 @@ const resolveSetupSelection = async (options, discovery, confirm) => {
             installSkill = plannedActions.some(({ kind }) => kind === "install_skill");
             detectedClients = detectedClients.filter((client) => selected.has(`configure_client:${client.name}`));
             interactiveApproval = decision.approved;
-            approved = decision.approved || plannedActions.length === 0;
+            approved = decision.approved;
         }
     }
     return {
@@ -143,7 +147,7 @@ const installHopperAction = async (input) => {
                 plannedActions: input.plannedActions,
                 appliedActions: input.appliedActions,
                 clients: input.clients,
-                doctor: await input.host.doctor(),
+                doctor: await input.host.doctor(input.doctorScope),
                 code: installed.code,
                 remediation: installed.remediation,
             },
@@ -192,12 +196,12 @@ const installSkillAction = async (host, options, appliedActions) => {
     });
     return true;
 };
-const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients]) => ({
+const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients], scope) => ({
     status: "needs_human",
     plannedActions,
     appliedActions,
     clients,
-    doctor: await host.doctor(),
+    doctor: await host.doctor(scope),
     remediation,
 });
 const emitProgress = (options, event) => options.onProgress?.(event);
@@ -250,6 +254,7 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
             const diagnosis = await runDoctor(undefined, doctorHost);
             return {
                 ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                ...registrationPermissionEnvironment(process.env),
                 ...(diagnosis.hopperPath === undefined
                     ? {}
                     : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
@@ -273,7 +278,7 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
         inspectClientConfiguration: inspectClientConfiguration,
         skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
         installSkill: () => installCanonicalSkill(homedir()),
-        doctor: () => runDoctor(undefined, doctorHost),
+        doctor: (scope) => runDoctor(undefined, doctorHost, scope),
     };
 };
 /** Detect supported agents from stable per-user installation markers. */
@@ -294,7 +299,3 @@ const exists = async (path) => {
         return false;
     }
 };
-const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
-    .filter(({ available }) => available)
-    .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))
-    .sort(([left], [right]) => left.localeCompare(right)));

package/dist/application/SetupClientConfiguration.js

@@ -9,9 +9,10 @@ import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 const defaultCommand = () => [
     "npx",
     "-y",
-    PRODUCT_IDENTITY.packageSpecifier,
+    PRODUCT_IDENTITY.registrationPackageSpecifier,
     "mcp",
 ];
+const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
 export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
@@ -34,7 +35,7 @@ export const configureJsonClient = async (client, environment = {}, command = de
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
     if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
         return { status: "unchanged" };
     let backupPath;
@@ -95,7 +96,7 @@ export const configureTomlClient = async (client, environment = {}, command = de
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
     if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
@@ -127,7 +128,7 @@ export const configureTomlClient = async (client, environment = {}, command = de
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
     try {
         const original = await readFile(client.configPath, "utf8");
         const document = client.format === "toml"
@@ -162,7 +163,7 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
         };
     }
-    const desired = clientConfigurationDesired(providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
     try {
         const document = client.format === "toml"
             ? objectSchema.parse(parseToml(original))
@@ -207,11 +208,14 @@ const restoreConfig = async (path, original) => {
         // The backup remains available for the remediation reported by setup.
     }
 };
-const clientConfigurationDesired = (providerEnvironment, command) => {
+const clientConfigurationDesired = (client, providerEnvironment, command) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     return {
         command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
         args: command.slice(1),
+        ...(client.name === "codex"
+            ? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
+            : {}),
         ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
     };
 };

package/dist/application/SetupPlan.js

@@ -48,8 +48,8 @@ const setupPlan = (input) => [
                 id: "install_skill",
                 kind: "install_skill",
                 label: "REA reverse-engineering skill",
-                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
-                detail: "Install or update the bundled REA reverse-engineering skill.",
+                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName),
+                detail: "Install or update the bundled REA reverse-engineering skill and on-demand references.",
                 external: false,
                 operation: "install",
             },
@@ -59,7 +59,7 @@ const setupPlan = (input) => [
 /** Discover and preflight the complete set of selectable setup actions. */
 export const discoverSetupActions = async (input) => {
     const { host, providerEnvironment, command } = input;
-    const initialDoctor = await host.doctor();
+    const initialDoctor = await host.doctor(input.doctorScope);
     const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
         (name === "hopper-demo-runtime" ||
             (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
@@ -112,6 +112,7 @@ export const discoverSetupActions = async (input) => {
         : []);
     const linuxDistribution = host.platform === "linux" ? await host.linuxDistribution() : undefined;
     return {
+        initialDoctor,
         installHopper,
         installSkill,
         detectedClients: clientPlans.map(({ client }) => client),

package/dist/application/SetupRegistrationEnvironment.js

@@ -0,0 +1,12 @@
+/** Select explicit non-secret permission settings safe for managed MCP registrations. */
+export const registrationPermissionEnvironment = (environment) => {
+    const investigationRoots = environment.REA_INVESTIGATION_INPUT_ROOTS_JSON;
+    return investigationRoots === undefined
+        ? {}
+        : { REA_INVESTIGATION_INPUT_ROOTS_JSON: investigationRoots };
+};
+/** Select exact non-secret settings published by available providers. */
+export const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
+    .filter(({ available }) => available)
+    .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))
+    .sort(([left], [right]) => left.localeCompare(right)));