@magnitudedev/pi-extension 0.0.1-alpha.0 → 0.0.1-alpha.2

package/README.md

@@ -3,15 +3,42 @@
 This Pi package adds Magnitude model management commands and live local-inference progress to Pi's
 built-in working row above the editor.
 
-Requires Pi 0.83.0 or newer and a matching Magnitude CLI. Install a local model, then run:
+Requires Pi 0.83.0 or newer. Install from your terminal:
+
+```sh
+pi install npm:@magnitudedev/pi-extension
+```
+
+On the next fresh interactive Pi launch, Magnitude asks **“Set up local models with Magnitude now?”**
+Yes opens Magnitude's actual graphical setup in the same terminal, including its model rankings,
+radar, downloads, and loading progress. It connects Pi automatically at the final step, then returns
+to the same Pi conversation with the selected model active. No agent prompt or cloud credentials
+are needed. If Magnitude is missing, accepting setup installs the CLI with
+`npm install --global @magnitudedev/cli` before opening onboarding. Pi stays visible with its native
+spinner: “Installing Magnitude…”. Installer output is suppressed; failures
+show a concise diagnostic. Escape cancels preparation, and `/magnitude-setup` retries.
+An existing CLI is preserved and must support hosted setup; an incompatible version reports an
+update requirement rather than being silently replaced.
+
+No or Escape leaves “You can set up local models anytime with `/magnitude-setup`.” in the conversation.
+The offer is remembered per Pi profile across restarts, reloads, and package updates. Existing
+Magnitude model configurations, non-interactive modes, conversations, and startup prompts are left
+alone. Run `/magnitude-setup` whenever you want to start onboarding yourself.
+
+The package includes the Magnitude usage skill; an already-loaded skill of that name takes
+precedence without a collision warning. `--no-skills` disables this fallback too. No separate CLI
+installation is needed. npm must be available with a writable global prefix, as for a normal npm
+CLI installation. Merely loading the extension does not install software.
+
+If you already have Magnitude and a local model, connect directly:
 
 ```sh
 magnitude connections add pi
 ```
 
 Restart Pi or run `/reload` after connecting. `PI_CODING_AGENT_DIR`, if set, is honored.
-Installing the package directly with `pi install` does not configure provider models,
-install the Magnitude CLI, start its service, or install its agent skill; the connection command
+Installing the package directly does not configure provider models,
+install the Magnitude CLI, or start its service; the connection command
 does all connection configuration and can be run safely after a standalone package install.
 
 The extension bundles Magnitude's private SDK. Model status, loading, and stopping use the existing
@@ -28,6 +55,7 @@ latency, and token-weighted generation throughput. Pi extensions execute with yo
 
 Commands:
 
+- `/magnitude-setup` — open Magnitude's graphical model setup inside Pi
 - `/load-model [model-id]` — load an installed model
 - `/stop-model` — stop the active model
 
@@ -52,3 +80,16 @@ builds and runs the checkout's inference runtime,
 and keeps the current source CLI available until Pi exits. Exiting Pi stops the development runtime
 and restores the service state that existed before launch. The launcher inherits the current
 environment; it does not start or configure tracing.
+
+To test the first-run setup offer with no preconfigured Magnitude provider:
+
+```sh
+bun run dev:pi --setup
+```
+
+This installs only the checkout's package into the temporary Pi profile. Accept the setup offer,
+choose a model, and return to Pi to chat. Both development modes keep connection files and skills
+inside the temporary profile, and do not change login-startup registration. They share the machine's
+real model storage and inference service: downloads consume disk space and selected models use
+memory. The launcher restores the prior managed service after Pi exits. Ordinary installed setup
+does enable login startup.

package/dist/magnitude-plugin.json

@@ -1,10 +1,11 @@
 {
   "name": "@magnitudedev/pi-extension",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.2",
   "rpcVersion": 1,
-  "contentFingerprint": "0cae890db353d9f063a1298bd0f770259d18a27692c4c392fd7561c031e5792c",
+  "contentFingerprint": "5661646da7080511725cdef888b7ce04148c99b56fbe6454619754ebc5235718",
   "files": {
-    "README.md": "345dccd4bee3706cb2647d10185acd0a79de61baf002f9cfce587b35376d5b19",
-    "dist/magnitude.js": "0d59abfd9a959d5ea4a066a39bcb1cc072c957c778edcd7bd702cc5878a8403f"
+    "README.md": "0334364928717efd1b146486d6dc2d9ff0f28b77ff28b162d04351738170b581",
+    "dist/magnitude.js": "915f1d6bb080180a774b1bd009b3d7bc6c5cbab94fd7ab067dd3345d638538ad",
+    "dist/skills/magnitude/SKILL.md": "37de67f0c7b831415f6298c8785b7ae97d5cfe454dc778651d96114840d2ace2"
   }
 }

package/dist/magnitude.js

@@ -3364,13 +3364,14 @@ var makeClient = (options) => Effect6.gen(function* () {
       yield* Deferred2.fail(active, new ConnectionClosed({}));
   })).pipe(Effect6.zipRight(Scope2.close(scope, Exit.void))));
   const unavailable = (message) => new ServiceUnavailable({ origin, message });
+  const decodeHealth = Schema47.decodeUnknown(Schema47.Union(MagnitudeHealthResponseSchema, AcnHealthResponseSchema));
   const probe = http.get(`${origin}/health`).pipe(Effect6.timeoutFail({
     duration: "2 seconds",
     onTimeout: () => unavailable("Magnitude service health timed out")
   }), Effect6.mapError((error) => error instanceof ServiceUnavailable ? error : unavailable("Magnitude service is unavailable")), Effect6.flatMap((response) => response.status !== 200 && response.status !== 503 ? Effect6.fail(new InvalidServiceResponse({
     origin,
     message: `Health returned HTTP ${response.status}`
-  })) : response.json.pipe(Effect6.flatMap(Schema47.decodeUnknown(MagnitudeHealthResponseSchema)), Effect6.mapError(() => new InvalidServiceResponse({
+  })) : response.json.pipe(Effect6.flatMap(decodeHealth), Effect6.map((health) => ("rpcVersion" in health) ? health : { ...health, rpcVersion: 0 }), Effect6.mapError(() => new InvalidServiceResponse({
     origin,
     message: "Invalid Magnitude health response"
   })))));
@@ -3391,36 +3392,35 @@ var makeClient = (options) => Effect6.gen(function* () {
     version: health.version,
     rpcVersion: health.rpcVersion
   });
+  const startService = (start2) => Effect6.scoped(Effect6.gen(function* () {
+    yield* report({ _tag: "Starting", phase: "PreparingAcn" });
+    yield* probe.pipe(Effect6.flatMap((health) => Option13.match(serviceProgressFromHealth(health.state), {
+      onNone: () => Effect6.void,
+      onSome: report
+    })), Effect6.ignore, Effect6.zipRight(Effect6.sleep("250 millis")), Effect6.forever, Effect6.forkScoped);
+    yield* start2.pipe(Stream4.runForEach(report));
+  }));
   const acquire = Effect6.gen(function* () {
     let started = false;
     while (true) {
-      const observed = yield* Effect6.either(probe);
-      if (observed._tag === "Left") {
-        if (observed.left._tag !== "ServiceUnavailable")
-          return yield* observed.left;
-        if (!started && Option13.isSome(starter)) {
-          started = true;
-          yield* report({ _tag: "Starting", phase: "PreparingAcn" });
-          yield* Effect6.scoped(Effect6.gen(function* () {
-            yield* probe.pipe(Effect6.flatMap((health) => Option13.match(serviceProgressFromHealth(health.state), {
-              onNone: () => Effect6.void,
-              onSome: report
-            })), Effect6.ignore, Effect6.zipRight(Effect6.sleep("250 millis")), Effect6.forever, Effect6.forkScoped);
-            yield* starter.value.start.pipe(Stream4.runForEach(report));
-          }));
-          continue;
-        }
-        if (!started)
-          return yield* observed.left;
-      } else {
-        const health = observed.right;
-        const service = yield* validate(health);
+      const observed = yield* Effect6.either(probe.pipe(Effect6.flatMap((health) => validate(health).pipe(Effect6.map((service) => ({ health, service }))))));
+      if (observed._tag === "Right") {
+        const { health, service } = observed.right;
         if (health.state._tag === "Ready")
           return service;
         yield* Option13.match(serviceProgressFromHealth(health.state), {
           onNone: () => Effect6.void,
           onSome: report
         });
+      } else if (started) {
+        if (observed.left._tag !== "ServiceUnavailable")
+          return yield* observed.left;
+      } else if (Option13.isSome(starter)) {
+        started = true;
+        yield* startService(starter.value.start);
+        continue;
+      } else {
+        return yield* observed.left;
       }
       yield* Effect6.sleep("250 millis");
     }
@@ -5841,16 +5841,372 @@ var registerMagnitudeCommands = (pi, sdk = clientLayer2()) => {
   };
 };
 
+// extensions/onboarding.ts
+import * as FileSystem3 from "@effect/platform/FileSystem";
+import * as NodeFileSystem2 from "@effect/platform-node/NodeFileSystem";
+import { getAgentDir, parseArgs } from "@earendil-works/pi-coding-agent";
+import { Effect as Effect13, Exit as Exit4, Scope as Scope5 } from "effect";
+import { fileURLToPath } from "node:url";
+
+// extensions/setup.ts
+import * as Command2 from "@effect/platform/Command";
+import * as CommandExecutor3 from "@effect/platform/CommandExecutor";
+import * as FileSystem from "@effect/platform/FileSystem";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import { delimiter, join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { Context as Context7, Effect as Effect12, Exit as Exit3, Fiber as Fiber2, Layer as Layer6, ManagedRuntime as ManagedRuntime2, Schema as Schema53, Scope as Scope4, Stream as Stream7 } from "effect";
+import { CancellableLoader } from "@earendil-works/pi-tui";
+
+// ../../packages/utils/src/process/interactive-process.ts
+import { spawn } from "node:child_process";
+import { Deferred as Deferred3, Duration as Duration2, Effect as Effect11, Option as Option17, Schema as Schema51 } from "effect";
+
+class InteractiveProcessFailed extends Schema51.TaggedError()("InteractiveProcessFailed", {
+  operation: Schema51.Literal("spawn", "run"),
+  message: Schema51.String
+}) {
+}
+var messageFrom = (cause) => cause instanceof Error ? cause.message : String(cause);
+var definedEnvironment = (environment) => Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+var acquireInteractiveProcess = (input) => Effect11.gen(function* () {
+  const termination = yield* Deferred3.make();
+  const child = yield* Effect11.async((resume) => {
+    let acquired = false;
+    let handle;
+    try {
+      handle = spawn(input.executable, [...input.args], {
+        cwd: input.workingDirectory,
+        detached: false,
+        env: definedEnvironment(input.environment),
+        shell: false,
+        stdio: "inherit"
+      });
+    } catch (cause) {
+      resume(Effect11.fail(new InteractiveProcessFailed({
+        operation: "spawn",
+        message: messageFrom(cause)
+      })));
+      return;
+    }
+    const onError = (cause) => {
+      const failure = new InteractiveProcessFailed({
+        operation: acquired ? "run" : "spawn",
+        message: messageFrom(cause)
+      });
+      if (acquired) {
+        Deferred3.unsafeDone(termination, Effect11.fail(failure));
+      } else {
+        resume(Effect11.fail(failure));
+      }
+    };
+    const onExit = (code, signal) => {
+      Deferred3.unsafeDone(termination, Effect11.succeed(code === null ? { _tag: "Signaled", signal } : { _tag: "Exited", code }));
+    };
+    const onSpawn = () => {
+      acquired = true;
+      resume(Effect11.succeed(handle));
+    };
+    handle.once("error", onError);
+    handle.once("exit", onExit);
+    handle.once("spawn", onSpawn);
+    return Effect11.sync(() => {
+      if (!acquired) {
+        handle.removeListener("error", onError);
+        handle.removeListener("exit", onExit);
+        handle.removeListener("spawn", onSpawn);
+        if (handle.exitCode === null && handle.signalCode === null) {
+          try {
+            handle.kill("SIGTERM");
+          } catch {}
+        }
+      }
+    });
+  });
+  return { child, termination };
+});
+var FORWARDED_SIGNALS = process.platform === "win32" ? ["SIGINT", "SIGTERM", "SIGBREAK"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+var awaitWithSignalForwarding = ({ child, termination }) => Effect11.acquireUseRelease(Effect11.sync(() => {
+  const listeners = new Map;
+  for (const signal of FORWARDED_SIGNALS) {
+    const listener = () => {
+      try {
+        child.kill(signal);
+      } catch {}
+    };
+    listeners.set(signal, listener);
+    process.on(signal, listener);
+  }
+  return listeners;
+}), () => Deferred3.await(termination), (listeners) => Effect11.sync(() => {
+  for (const [signal, listener] of listeners) {
+    process.removeListener(signal, listener);
+  }
+}));
+var terminateAndReap = ({ child, termination }) => Effect11.gen(function* () {
+  if (yield* Deferred3.isDone(termination))
+    return;
+  yield* Effect11.sync(() => {
+    try {
+      child.kill("SIGTERM");
+    } catch {}
+  });
+  const graceful = yield* Deferred3.await(termination).pipe(Effect11.ignore, Effect11.timeoutOption(Duration2.seconds(2)));
+  if (Option17.isSome(graceful))
+    return;
+  yield* Effect11.sync(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {}
+  });
+  yield* Deferred3.await(termination).pipe(Effect11.ignore, Effect11.timeout(Duration2.seconds(2)), Effect11.ignore);
+});
+var runInteractiveProcess = (input) => Effect11.acquireUseRelease(acquireInteractiveProcess(input), awaitWithSignalForwarding, terminateAndReap);
+// ../../packages/client-common/src/harness-connections/hosted-setup.ts
+import { Schema as Schema52 } from "effect";
+var HOSTED_SETUP_PROTOCOL_VERSION = 1;
+var HOSTED_SETUP_MAX_RESULT_BYTES = 16 * 1024;
+var HostedSetupCapability = Schema52.Struct({
+  protocolVersion: Schema52.Literal(HOSTED_SETUP_PROTOCOL_VERSION)
+});
+var version = Schema52.Literal(HOSTED_SETUP_PROTOCOL_VERSION);
+var HostedSetupResult = Schema52.Union(Schema52.TaggedStruct("Completed", { protocolVersion: version, modelId: ModelIdSchema }), Schema52.TaggedStruct("Cancelled", { protocolVersion: version }), Schema52.TaggedStruct("Failed", {
+  protocolVersion: version,
+  message: Schema52.String.pipe(Schema52.filter((message) => new TextEncoder().encode(message).length <= 4096))
+}));
+
+// extensions/setup.ts
+class PiSetupFailed extends Schema53.TaggedError()("PiSetupFailed", {
+  message: Schema53.String
+}) {
+}
+var failure = (message) => new PiSetupFailed({ message });
+var prepareMagnitudeCli = (cwd, setMessage = () => Effect12.void) => Effect12.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const override = process.env.MAGNITUDE_CLI?.trim();
+  const executable = override || "magnitude";
+  const probe = Effect12.scoped(Effect12.gen(function* () {
+    const child = yield* Command2.make(executable, "setup", "--host-protocol").pipe(Command2.start);
+    const [code, output, stderr] = yield* Effect12.all([
+      child.exitCode,
+      child.stdout.pipe(Stream7.decodeText(), Stream7.runFold("", (text2, part) => (text2 + part).slice(0, 4097))),
+      child.stderr.pipe(Stream7.decodeText(), Stream7.runFold("", (text2, part) => (text2 + part).slice(-4096)))
+    ], { concurrency: "unbounded" });
+    if (code !== 0 || output.length > 4096)
+      return yield* failure(`Magnitude's setup capability check failed at ${executable} (exit ${code}). ${stripVTControlCharacters(stderr).trim().slice(-600)}${override ? " Check MAGNITUDE_CLI." : ""}`);
+    return output;
+  }));
+  const capability = yield* probe.pipe(Effect12.catchIf((error) => !override && error._tag === "SystemError" && error.reason === "NotFound", (error) => Effect12.gen(function* () {
+    for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+      if (yield* fs.exists(join(directory || cwd, executable)))
+        return yield* error;
+    }
+    yield* setMessage("Installing Magnitude…");
+    yield* Effect12.scoped(Effect12.gen(function* () {
+      const child = yield* Command2.make("npm", "install", "--global", "@magnitudedev/cli").pipe(Command2.workingDirectory(cwd), Command2.start);
+      const [code, , stderr] = yield* Effect12.all([
+        child.exitCode,
+        Stream7.runDrain(child.stdout),
+        child.stderr.pipe(Stream7.decodeText(), Stream7.runFold("", (text2, part) => (text2 + part).slice(-4096)))
+      ], { concurrency: "unbounded" });
+      if (code !== 0)
+        return yield* failure(`Magnitude installation failed (exit ${code}). ${stripVTControlCharacters(stderr).trim().slice(-600)} Run /magnitude-setup to retry.`);
+    }));
+    return yield* probe;
+  })), Effect12.timeout("10 minutes"), Effect12.mapError((error) => error instanceof PiSetupFailed ? error : failure(`Could not prepare Magnitude: ${String(error)}. Run /magnitude-setup to retry${override ? ", or check MAGNITUDE_CLI" : ""}.`)));
+  yield* Schema53.decodeUnknown(Schema53.parseJson(HostedSetupCapability))(capability).pipe(Effect12.mapError(() => failure(`The Magnitude CLI at ${executable} does not support hosted setup. Update @magnitudedev/cli${override ? ", or check MAGNITUDE_CLI" : ""}.`)));
+  return executable;
+});
+var withPiPreparation = (ctx, work) => Effect12.acquireUseRelease(Effect12.async((resume, signal) => {
+  let closed;
+  closed = ctx.ui.custom((tui, theme, _keys, done) => {
+    const loader = new CancellableLoader(tui, (text2) => theme.fg("accent", text2), (text2) => theme.fg("muted", text2), "Installing Magnitude…");
+    if (signal.aborted) {
+      loader.dispose();
+      done();
+    } else
+      resume(Effect12.succeed({ loader, finish: () => done(), closed: () => closed }));
+    return loader;
+  });
+  closed.catch((error) => resume(Effect12.fail(failure(`Could not open Pi setup: ${String(error)}`))));
+}), ({ loader }) => work((message) => Effect12.sync(() => loader.setMessage(message))).pipe(Effect12.raceFirst(Effect12.async((resume) => {
+  loader.onAbort = () => resume(Effect12.fail(failure("Magnitude setup cancelled. Run /magnitude-setup to retry.")));
+  if (loader.signal.aborted)
+    loader.onAbort();
+  return Effect12.sync(() => {
+    loader.onAbort = undefined;
+  });
+}))), ({ loader, finish, closed }) => Effect12.sync(() => {
+  loader.dispose();
+  finish();
+}).pipe(Effect12.zipRight(Effect12.promise(closed))));
+var restoreHostTerminal = (tui) => tui.terminal.write("\x1B[?2026l\x1B[?1003l\x1B[?1002l\x1B[?1000l\x1B[?1006l\x1B[?1004l" + "\x1B[?2004l\x1B[>4;0m\x1B[=0u\x1B[?1049l\x1B[0m\x1B[0 q");
+var withPiTerminal = (ctx, work) => Effect12.acquireUseRelease(Effect12.async((resume, signal) => {
+  let closed;
+  closed = ctx.ui.custom((tui, _theme, _keys, done) => {
+    if (signal.aborted)
+      done();
+    else
+      resume(Effect12.succeed({ tui, finish: () => done(), closed: () => closed }));
+    return { render: () => [], invalidate: () => {} };
+  });
+  closed.catch((error) => resume(Effect12.fail(failure(`Could not open Pi setup: ${String(error)}`))));
+}), ({ tui }) => Effect12.sync(() => tui.stop()).pipe(Effect12.zipRight(work)), ({ tui, finish, closed }) => Effect12.sync(() => {
+  try {
+    restoreHostTerminal(tui);
+    tui.start();
+    tui.requestRender(true);
+  } finally {
+    finish();
+  }
+}).pipe(Effect12.zipRight(Effect12.promise(closed))));
+var validateSetupTermination = (result, termination) => {
+  if (termination._tag !== "Exited" || termination.code === 0 !== (result._tag !== "Failed")) {
+    return Effect12.fail(failure("Magnitude setup exited without a consistent completion result. Run /magnitude-setup to retry."));
+  }
+  return result._tag === "Failed" ? Effect12.fail(failure(result.message)) : Effect12.succeed(result);
+};
+var PiSetup = Context7.GenericTag("pi/PiSetup");
+var PiSetupLive = Layer6.effect(PiSetup, Effect12.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const executor = yield* CommandExecutor3.CommandExecutor;
+  return {
+    run: (ctx) => Effect12.scoped(Effect12.gen(function* () {
+      const directory = yield* fs.makeTempDirectoryScoped({ prefix: "magnitude-pi-setup-" });
+      const resultPath = `${directory}/result.json`;
+      const executable = yield* withPiPreparation(ctx, (setMessage) => prepareMagnitudeCli(ctx.cwd, setMessage));
+      const termination = yield* withPiTerminal(ctx, runInteractiveProcess({
+        executable,
+        args: ["setup", "--host", "pi", "--result-file", resultPath],
+        environment: process.env,
+        workingDirectory: ctx.cwd
+      }));
+      if (termination._tag === "Signaled" && termination.signal === "SIGINT") {
+        return { protocolVersion: HOSTED_SETUP_PROTOCOL_VERSION, _tag: "Cancelled" };
+      }
+      if (termination._tag === "Signaled") {
+        return yield* failure(`Magnitude setup stopped unexpectedly (${termination.signal}). Run /magnitude-setup to retry.`);
+      }
+      const stat = yield* fs.stat(resultPath).pipe(Effect12.mapError(() => failure("Magnitude setup exited without a completion result. Run /magnitude-setup to retry.")));
+      if (stat.type !== "File" || stat.size > BigInt(HOSTED_SETUP_MAX_RESULT_BYTES)) {
+        return yield* failure("Magnitude setup returned an invalid or oversized result");
+      }
+      const result = yield* fs.readFileString(resultPath).pipe(Effect12.flatMap(Schema53.decodeUnknown(Schema53.parseJson(HostedSetupResult))), Effect12.mapError(() => failure("Magnitude setup did not return a valid completion result. Run /magnitude-setup to retry.")));
+      return yield* validateSetupTermination(result, termination);
+    })).pipe(Effect12.provideService(CommandExecutor3.CommandExecutor, executor), Effect12.provideService(FileSystem.FileSystem, fs), Effect12.mapError((error) => error instanceof PiSetupFailed ? error : failure(`Magnitude setup could not finish: ${String(error)}`)))
+  };
+}));
+var registerMagnitudeSetup = (pi, layer4 = PiSetupLive.pipe(Layer6.provide(NodeContext.layer))) => {
+  const runtime = ManagedRuntime2.make(layer4);
+  const scope = Effect12.runSync(Scope4.make());
+  const gate = Effect12.runSync(Effect12.makeSemaphore(1));
+  const action = (ctx) => Effect12.gen(function* () {
+    if (ctx.mode !== "tui")
+      return yield* failure("Run /magnitude-setup in Pi's interactive terminal.");
+    if (!ctx.isIdle() || ctx.hasPendingMessages())
+      return yield* failure("Wait for the current task to finish, then run /magnitude-setup.");
+    const setup = yield* PiSetup;
+    const result = yield* setup.run(ctx);
+    if (result._tag !== "Completed")
+      return false;
+    yield* Effect12.tryPromise({
+      try: async () => {
+        await ctx.modelRegistry.refresh();
+        const model2 = ctx.modelRegistry.find("magnitude", result.modelId);
+        if (!model2 || !await pi.setModel(model2))
+          throw new Error("The selected model is not available in Pi");
+      },
+      catch: (error) => failure(`Magnitude setup completed, but Pi could not activate the model: ${String(error)}. Run /reload and select it with /model.`)
+    });
+    return true;
+  });
+  const run = (ctx) => runtime.runPromise(Effect12.forkIn(gate.withPermitsIfAvailable(1)(action(ctx)).pipe(Effect12.flatMap((result) => result._tag === "Some" ? Effect12.succeed(result.value) : Effect12.fail(failure("Magnitude setup is already open."))), Effect12.catchAll((error) => Effect12.sync(() => {
+    ctx.ui.notify(error.message, "error");
+    return false;
+  }))), scope).pipe(Effect12.flatMap(Fiber2.join)));
+  pi.registerCommand("magnitude-setup", {
+    description: "Choose and set up a local Magnitude model",
+    handler: async (_args, ctx) => {
+      const reload = await run(ctx);
+      if (reload) {
+        try {
+          await ctx.reload();
+        } catch (error) {
+          throw failure(`Magnitude setup completed and selected the model, but Pi could not reload its resources: ${String(error)}. Run /reload to retry.`);
+        }
+      }
+    }
+  });
+  return {
+    run,
+    dispose: async () => {
+      await Effect12.runPromise(Scope4.close(scope, Exit3.void));
+      await runtime.dispose();
+    }
+  };
+};
+
+// extensions/onboarding.ts
+var SETUP_QUESTION = "Set up local models with Magnitude now?";
+var SETUP_REMINDER = "You can set up local models anytime with `/magnitude-setup`.";
+var claimSetupOffer = (agentDir) => Effect13.gen(function* () {
+  const fs = yield* FileSystem3.FileSystem;
+  const directory = `${agentDir}/magnitude`;
+  yield* fs.makeDirectory(directory, { recursive: true });
+  return yield* fs.writeFileString(`${directory}/setup-offered`, "", { flag: "wx" }).pipe(Effect13.as(true), Effect13.catchTag("SystemError", (error) => error.reason === "AlreadyExists" ? Effect13.succeed(false) : Effect13.fail(error)));
+});
+function canOfferSetup(ctx, argv) {
+  if (ctx.mode !== "tui" || !ctx.isIdle() || ctx.hasPendingMessages() || ctx.ui.getEditorText().trim())
+    return false;
+  if (ctx.sessionManager.getEntries().some((entry) => entry.type === "message"))
+    return false;
+  if (ctx.modelRegistry.getAll().some((model2) => model2.provider === "magnitude"))
+    return false;
+  const args = parseArgs([...argv]);
+  return args.messages.length === 0 && args.fileArgs.length === 0;
+}
+var offerSetup = (pi, ctx, agentDir, signal, runSetup) => Effect13.gen(function* () {
+  if (!(yield* claimSetupOffer(agentDir)) || signal.aborted)
+    return;
+  const accepted = yield* Effect13.tryPromise(() => ctx.ui.confirm(SETUP_QUESTION, "", { signal }));
+  if (signal.aborted)
+    return;
+  if (accepted && ctx.isIdle() && !ctx.hasPendingMessages()) {
+    yield* Effect13.tryPromise(() => runSetup(ctx));
+  } else
+    pi.sendMessage({ customType: "magnitude-setup", content: SETUP_REMINDER, display: true });
+});
+function registerMagnitudeOnboarding(pi) {
+  const abort = new AbortController;
+  const scope = Effect13.runSync(Scope5.make());
+  const setup = registerMagnitudeSetup(pi);
+  pi.on("resources_discover", () => {
+    if (parseArgs(process.argv.slice(2)).noSkills || pi.getCommands().some((command) => command.source === "skill" && command.name === "skill:magnitude"))
+      return;
+    return { skillPaths: [fileURLToPath(new URL("./skills/magnitude/SKILL.md", import.meta.url))] };
+  });
+  pi.on("session_start", (event, ctx) => {
+    if (event.reason !== "startup" || !canOfferSetup(ctx, process.argv.slice(2)))
+      return;
+    Effect13.runFork(Effect13.forkIn(offerSetup(pi, ctx, getAgentDir(), abort.signal, setup.run).pipe(Effect13.provide(NodeFileSystem2.layer), Effect13.catchAll(() => Effect13.sync(() => ctx.ui.notify(`Magnitude setup could not open. ${SETUP_REMINDER}`, "warning")))), scope));
+  });
+  return async () => {
+    abort.abort();
+    await Effect13.runPromise(Scope5.close(scope, Exit4.void));
+    await setup.dispose();
+  };
+}
+
 // extensions/observing-fetch.ts
-import { Effect as Effect11, Either as Either3, Schema as Schema52 } from "effect";
+import { Effect as Effect14, Either as Either3, Schema as Schema55 } from "effect";
 
 // extensions/protocol.ts
-import { Either as Either2, Schema as Schema51 } from "effect";
-var ProgressChunkSchema = Schema51.Struct({ progress: MagnitudeProgressSchema });
-var TimingsChunkSchema = Schema51.Struct({ timings: MagnitudeTimingsSchema });
+import { Either as Either2, Schema as Schema54 } from "effect";
+var ProgressChunkSchema = Schema54.Struct({ progress: MagnitudeProgressSchema });
+var TimingsChunkSchema = Schema54.Struct({ timings: MagnitudeTimingsSchema });
 var decodeMagnitudeObservation = (value) => {
-  const progress = Schema51.decodeUnknownEither(ProgressChunkSchema)(value);
-  const timings = Schema51.decodeUnknownEither(TimingsChunkSchema)(value);
+  const progress = Schema54.decodeUnknownEither(ProgressChunkSchema)(value);
+  const timings = Schema54.decodeUnknownEither(TimingsChunkSchema)(value);
   if (Either2.isLeft(progress) && Either2.isLeft(timings))
     return;
   return {
@@ -5861,7 +6217,7 @@ var decodeMagnitudeObservation = (value) => {
 
 // extensions/observing-fetch.ts
 var MAGNITUDE_PROGRESS_HEADER = "Magnitude-Include-Progress";
-var JsonDocumentSchema = Schema52.parseJson(Schema52.Unknown);
+var JsonDocumentSchema = Schema55.parseJson(Schema55.Unknown);
 
 class SseDataParser {
   #buffer = "";
@@ -5908,26 +6264,26 @@ class SseDataParser {
     this.#dataLines = [];
     if (data === "[DONE]")
       return;
-    const decoded = Schema52.decodeUnknownEither(JsonDocumentSchema)(data);
+    const decoded = Schema55.decodeUnknownEither(JsonDocumentSchema)(data);
     if (Either3.isRight(decoded))
       observe(decoded.right);
   }
 }
-var observeResponse = (response, request, signal) => Effect11.scoped(Effect11.gen(function* () {
+var observeResponse = (response, request, signal) => Effect14.scoped(Effect14.gen(function* () {
   if (!response.ok || response.body === null) {
     yield* request.fail;
     return;
   }
-  const reader = yield* Effect11.acquireRelease(Effect11.sync(() => response.body.getReader()), (reader2) => Effect11.promise(() => reader2.cancel()).pipe(Effect11.interruptible, Effect11.timeout("100 millis"), Effect11.ignore, Effect11.ensuring(Effect11.sync(() => reader2.releaseLock()))));
+  const reader = yield* Effect14.acquireRelease(Effect14.sync(() => response.body.getReader()), (reader2) => Effect14.promise(() => reader2.cancel()).pipe(Effect14.interruptible, Effect14.timeout("100 millis"), Effect14.ignore, Effect14.ensuring(Effect14.sync(() => reader2.releaseLock()))));
   if (signal.aborted) {
     yield* request.fail;
     return;
   }
   const decoder = new TextDecoder;
   const parser = new SseDataParser;
-  const drain = Effect11.gen(function* () {
+  const drain = Effect14.gen(function* () {
     while (true) {
-      const result = yield* Effect11.tryPromise(() => reader.read());
+      const result = yield* Effect14.tryPromise(() => reader.read());
       if (result.done)
         break;
       const values = [];
@@ -5940,35 +6296,35 @@ var observeResponse = (response, request, signal) => Effect11.scoped(Effect11.ge
     }
     yield* request.finish;
   });
-  const aborted = Effect11.async((resume) => {
-    const abort = () => resume(Effect11.interrupt);
+  const aborted = Effect14.async((resume) => {
+    const abort = () => resume(Effect14.interrupt);
     signal.addEventListener("abort", abort, { once: true });
     if (signal.aborted)
       abort();
-    return Effect11.sync(() => signal.removeEventListener("abort", abort));
+    return Effect14.sync(() => signal.removeEventListener("abort", abort));
   });
-  yield* Effect11.raceFirst(drain, aborted).pipe(Effect11.onError(() => request.fail));
-})).pipe(Effect11.catchAllCause(() => Effect11.void));
+  yield* Effect14.raceFirst(drain, aborted).pipe(Effect14.onError(() => request.fail));
+})).pipe(Effect14.catchAllCause(() => Effect14.void));
 var makeObservingFetch = (fetchImplementation, begin, scope) => {
   const observingFetch = async (input, init) => {
     const request = new Request(input, init);
     request.headers.set(MAGNITUDE_PROGRESS_HEADER, "true");
-    const progress = Effect11.runSync(Effect11.suspend(begin).pipe(Effect11.catchAllCause(() => Effect11.succeed({
-      observe: () => Effect11.void,
-      finish: Effect11.void,
-      fail: Effect11.void
+    const progress = Effect14.runSync(Effect14.suspend(begin).pipe(Effect14.catchAllCause(() => Effect14.succeed({
+      observe: () => Effect14.void,
+      finish: Effect14.void,
+      fail: Effect14.void
     }))));
     try {
       const response = await fetchImplementation(request);
       try {
         const observation = observeResponse(response.clone(), progress, request.signal);
-        Effect11.runFork(Effect11.forkIn(observation, scope));
+        Effect14.runFork(Effect14.forkIn(observation, scope));
       } catch {
-        Effect11.runSync(progress.fail.pipe(Effect11.catchAllCause(() => Effect11.void)));
+        Effect14.runSync(progress.fail.pipe(Effect14.catchAllCause(() => Effect14.void)));
       }
       return response;
     } catch (error) {
-      Effect11.runSync(progress.fail.pipe(Effect11.catchAllCause(() => Effect11.void)));
+      Effect14.runSync(progress.fail.pipe(Effect14.catchAllCause(() => Effect14.void)));
       throw error;
     }
   };
@@ -5979,9 +6335,9 @@ var makeObservingFetch = (fetchImplementation, begin, scope) => {
 
 // extensions/progress.ts
 import { Text } from "@earendil-works/pi-tui";
-import { Data as Data3, Effect as Effect12, Fiber as Fiber2, Option as Option17, Queue, Schema as Schema53 } from "effect";
+import { Data as Data3, Effect as Effect15, Fiber as Fiber3, Option as Option18, Queue, Schema as Schema56 } from "effect";
 var MAGNITUDE_SUMMARY_WIDGET_KEY = "magnitude-inference-summary";
-var RequestId = Schema53.Number.pipe(Schema53.int(), Schema53.brand("ProgressRequestId"));
+var RequestId = Schema56.Number.pipe(Schema56.int(), Schema56.brand("ProgressRequestId"));
 
 class Observing extends Data3.TaggedClass("Observing") {
 }
@@ -6036,31 +6392,31 @@ var formatLiveProgress = ({ progress, modelName, startedAt }, now) => {
     }
   }
 };
-var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(function* () {
+var makeProgressTracker = (ui, now = () => performance.now()) => Effect15.gen(function* () {
   let state = new Idle2;
   let nextId = 0;
   let active;
   let latest;
   let nextResponseId = 0;
   const wake = yield* Queue.sliding(1);
-  const present = (f) => Effect12.sync(f).pipe(Effect12.catchAllCause(() => Effect12.void));
+  const present = (f) => Effect15.sync(f).pipe(Effect15.catchAllCause(() => Effect15.void));
   const clearSummary = present(() => ui.setWidget(MAGNITUDE_SUMMARY_WIDGET_KEY, undefined));
   const resetRow = present(() => ui.setWorkingMessage());
   const render2 = present(() => {
     if (active)
       ui.setWorkingMessage(formatLiveProgress(active.phase, now()));
   });
-  const finalize = Effect12.gen(function* () {
+  const finalize = Effect15.gen(function* () {
     if (state._tag !== "Settled")
       return;
-    if ([...state.run.responses.values()].some(Option17.isNone))
+    if ([...state.run.responses.values()].some(Option18.isNone))
       return;
     if ([...state.run.requests.values()].some((r) => r._tag === "Observing"))
       return;
     const settled = state;
     state = runMachine.transition(settled, "Idle", {});
     const timings = [...settled.run.completed.entries()].filter(([id]) => settled.run.accepted.has(id)).sort(([a], [b]) => a - b).map(([, value]) => value);
-    if ([...settled.run.responses.values()].some((outcome) => !Option17.getOrElse(outcome, () => false)) || timings.length === 0) {
+    if ([...settled.run.responses.values()].some((outcome) => !Option18.getOrElse(outcome, () => false)) || timings.length === 0) {
       yield* clearSummary;
       return;
     }
@@ -6069,7 +6425,7 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
     const summary = `● ${settled.run.modelName} worked for ${duration(settled.settledAt - settled.run.startedAt)}` + ` · ${seconds(timings[0].time_to_first_token_ms)} TTFT` + (decodeMs > 0 && tokens > 0 ? ` · ${(tokens * 1000 / decodeMs).toFixed(1)} tok/s` : "");
     yield* present(() => ui.setWidget(MAGNITUDE_SUMMARY_WIDGET_KEY, (_tui, theme) => new Text(theme.fg("muted", summary), 0, 0)));
   });
-  const clear = Effect12.gen(function* () {
+  const clear = Effect15.gen(function* () {
     if (state._tag === "Disposed")
       return;
     if (state._tag !== "Idle")
@@ -6079,7 +6435,7 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
     yield* resetRow;
     yield* clearSummary;
   });
-  const startRun = (modelName) => Effect12.gen(function* () {
+  const startRun = (modelName) => Effect15.gen(function* () {
     if (state._tag === "Disposed")
       return;
     if (state._tag === "Settled")
@@ -6089,38 +6445,38 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
     state = runMachine.transition(state, "Working", { run: { startedAt: now(), modelName, requests: new Map, completed: new Map, responses: new Map, accepted: new Set } });
     yield* clearSummary;
   });
-  const timer = yield* Effect12.forever(Effect12.gen(function* () {
+  const timer = yield* Effect15.forever(Effect15.gen(function* () {
     yield* Queue.take(wake);
     while (active) {
-      yield* Effect12.sleep("100 millis");
+      yield* Effect15.sleep("100 millis");
       yield* render2;
     }
-  })).pipe(Effect12.forkScoped);
-  yield* Effect12.addFinalizer(() => Effect12.gen(function* () {
+  })).pipe(Effect15.forkScoped);
+  yield* Effect15.addFinalizer(() => Effect15.gen(function* () {
     yield* clear;
     if (state._tag !== "Disposed")
       state = runMachine.transition(state, "Disposed", {});
-    yield* Fiber2.interrupt(timer);
+    yield* Fiber3.interrupt(timer);
   }));
   return {
     startRun,
     clear,
-    settleRun: Effect12.gen(function* () {
+    settleRun: Effect15.gen(function* () {
       if (state._tag === "Working")
         state = runMachine.transition(state, "Settled", { settledAt: now() });
       yield* finalize;
     }),
-    beginResponse: (modelName) => Effect12.gen(function* () {
+    beginResponse: (modelName) => Effect15.gen(function* () {
       yield* startRun(modelName);
       const run = state._tag === "Working" ? state.run : undefined;
       const responseId = ++nextResponseId;
       const requests = [];
-      run?.responses.set(responseId, Option17.none());
+      run?.responses.set(responseId, Option18.none());
       const belongs = () => run !== undefined && (state._tag === "Working" || state._tag === "Settled") && state.run === run;
-      const end = (successful) => Effect12.gen(function* () {
-        if (!belongs() || Option17.isSome(run.responses.get(responseId)))
+      const end = (successful) => Effect15.gen(function* () {
+        if (!belongs() || Option18.isSome(run.responses.get(responseId)))
           return;
-        run.responses.set(responseId, Option17.some(successful));
+        run.responses.set(responseId, Option18.some(successful));
         const last = requests.at(-1);
         if (successful && last !== undefined)
           run.accepted.add(last);
@@ -6139,16 +6495,16 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
         }
         yield* finalize;
       });
-      const begin = Effect12.gen(function* () {
-        if (!belongs() || Option17.isSome(run.responses.get(responseId)))
-          return { observe: () => Effect12.void, finish: Effect12.void, fail: Effect12.void };
+      const begin = Effect15.gen(function* () {
+        if (!belongs() || Option18.isSome(run.responses.get(responseId)))
+          return { observe: () => Effect15.void, finish: Effect15.void, fail: Effect15.void };
         const id = RequestId.make(++nextId);
         requests.push(id);
         latest = id;
         active = undefined;
-        run?.requests.set(id, new Observing({ timings: Option17.none() }));
+        run?.requests.set(id, new Observing({ timings: Option18.none() }));
         yield* resetRow;
-        const close = (failed) => Effect12.gen(function* () {
+        const close = (failed) => Effect15.gen(function* () {
           if (!belongs())
             return;
           const request = run.requests.get(id);
@@ -6158,7 +6514,7 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
             run.requests.set(id, requestMachine.transition(request, "Closed", {}));
           else {
             run.requests.set(id, requestMachine.transition(request, "Observed", {}));
-            if (Option17.isSome(request.timings))
+            if (Option18.isSome(request.timings))
               run.completed.set(id, request.timings.value);
           }
           if (latest === id) {
@@ -6168,14 +6524,14 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
           yield* finalize;
         });
         return {
-          observe: (observation) => Effect12.gen(function* () {
+          observe: (observation) => Effect15.gen(function* () {
             if (!belongs())
               return;
             const request = run.requests.get(id);
             if (request._tag !== "Observing")
               return;
             if (observation.timings)
-              run.requests.set(id, requestMachine.hold(request, { timings: Option17.some(observation.timings) }));
+              run.requests.set(id, requestMachine.hold(request, { timings: Option18.some(observation.timings) }));
             if (latest !== id || !observation.progress)
               return;
             const progress = observation.progress;
@@ -6199,34 +6555,35 @@ var makeProgressTracker = (ui, now = () => performance.now()) => Effect12.gen(fu
 });
 
 // extensions/magnitude.ts
-import { Effect as Effect13, Exit as Exit3, Scope as Scope5 } from "effect";
+import { Effect as Effect16, Exit as Exit5, Scope as Scope7 } from "effect";
 function magnitudeExtension(pi) {
   const completions = openAICompletionsApi();
   let tracker;
   let scope;
   const disposeCommands = registerMagnitudeCommands(pi);
-  const perform = (effect) => Effect13.runSync((effect ?? Effect13.void).pipe(Effect13.catchAllCause(() => Effect13.void)));
+  const disposeOnboarding = registerMagnitudeOnboarding(pi);
+  const perform = (effect) => Effect16.runSync((effect ?? Effect16.void).pipe(Effect16.catchAllCause(() => Effect16.void)));
   pi.registerProvider("magnitude", {
     api: "openai-completions",
     streamSimple: (model2, context, options) => {
       if (model2.api !== "openai-completions") {
         throw new Error(`Magnitude for Pi requires openai-completions, received ${model2.api}`);
       }
-      const response = tracker && Effect13.runSync(tracker.beginResponse(model2.name));
+      const response = tracker && Effect16.runSync(tracker.beginResponse(model2.name));
       const stream = completions.streamSimple(model2, context, {
         ...options,
-        fetch: scope ? makeObservingFetch(options?.fetch ?? globalThis.fetch, () => response?.begin ?? Effect13.succeed({ observe: () => Effect13.void, finish: Effect13.void, fail: Effect13.void }), scope) : options?.fetch ?? globalThis.fetch
+        fetch: scope ? makeObservingFetch(options?.fetch ?? globalThis.fetch, () => response?.begin ?? Effect16.succeed({ observe: () => Effect16.void, finish: Effect16.void, fail: Effect16.void }), scope) : options?.fetch ?? globalThis.fetch
       });
       if (response && scope)
-        Effect13.runFork(Effect13.forkIn(Effect13.tryPromise(() => stream.result()).pipe(Effect13.flatMap((message) => response.end(message.stopReason !== "error" && message.stopReason !== "aborted")), Effect13.catchAllCause(() => response.end(false))), scope));
+        Effect16.runFork(Effect16.forkIn(Effect16.tryPromise(() => stream.result()).pipe(Effect16.flatMap((message) => response.end(message.stopReason !== "error" && message.stopReason !== "aborted")), Effect16.catchAllCause(() => response.end(false))), scope));
       return stream;
     }
   });
   pi.on("session_start", async (_event, ctx) => {
     if (scope)
-      await Effect13.runPromise(Scope5.close(scope, Exit3.void));
-    scope = Effect13.runSync(Scope5.make());
-    tracker = await Effect13.runPromise(makeProgressTracker(ctx.ui).pipe(Scope5.extend(scope)));
+      await Effect16.runPromise(Scope7.close(scope, Exit5.void));
+    scope = Effect16.runSync(Scope7.make());
+    tracker = await Effect16.runPromise(makeProgressTracker(ctx.ui).pipe(Scope7.extend(scope)));
   });
   pi.on("model_select", (event) => {
     if (event.model.provider !== "magnitude")
@@ -6238,8 +6595,9 @@ function magnitudeExtension(pi) {
   });
   pi.on("agent_settled", () => perform(tracker?.settleRun));
   pi.on("session_shutdown", async () => {
+    await disposeOnboarding();
     if (scope)
-      await Effect13.runPromise(Scope5.close(scope, Exit3.void));
+      await Effect16.runPromise(Scope7.close(scope, Exit5.void));
     tracker = undefined;
     scope = undefined;
     await disposeCommands();

package/dist/skills/magnitude/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: magnitude
+description: Set up and operate Magnitude local inference through its CLI, recommend hardware-fit local models, monitor acquisition and loading, and connect an agent harness. Use for Magnitude service, model, catalog, setup, or harness requests.
+---
+
+# Magnitude
+
+Magnitude profiles the local machine, assesses compatible model configurations, acquires and runs
+selected models, and connects them to supported agent harnesses.
+
+For agent-guided setup, read `magnitude docs onboarding` completely and follow it. It contains the
+current CLI-only workflow, model-selection evidence, progress semantics, and harness connection
+rules.
+
+For the general non-interactive command contract, read `magnitude docs cli`. Command output is
+designed to be read directly by both agents and people.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magnitudedev/pi-extension",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.2",
   "description": "Magnitude model controls and inference progress for Pi",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "@earendil-works/pi-tui": ">=0.83.0"
   },
   "devDependencies": {
+    "@magnitudedev/client-common": "workspace:*",
     "@effect/platform-bun": "^0.90.0",
     "@magnitudedev/release": "workspace:*",
     "@magnitudedev/utils": "workspace:*",