@openscout/scout 0.2.63 → 0.2.65

package/README.md

@@ -9,7 +9,7 @@ bun add -g @openscout/scout
 scout --help
 ```
 
-`@openscout/scout` is the published package name. It installs the `scout` command and depends on `@openscout/runtime` for the local broker service.
+`@openscout/scout` is the public package name. It installs the `scout` command and carries the bundled broker/runtime and web UI. Installing it does not start services; commands such as `scout setup`, `scout up`, and `scout server start` activate them explicitly.
 
 ## Canonical Flow
 
@@ -29,7 +29,7 @@ scout ask --to dewey "can you review our docs?"
 - `~/Library/Application Support/OpenScout/relay-agents.json` for compatibility with the existing machine-local agent registry
 - `.openscout/project.json` for the current repo when needed
 
-It also discovers local and project-backed agents from your configured workspace roots, installs the broker service, and attempts to start it.
+It also discovers local and project-backed agents from your configured workspace roots, installs the base Scout service, attempts to start it, and ensures Caddy is available for the local `scout.local` edge. On macOS, setup installs missing Caddy with `brew install caddy`; otherwise install Caddy yourself or set `OPENSCOUT_CADDY_BIN`.
 
 `scout init` writes `~/.openscout/config.json` with the broker, web, and pairing ports that every Scout component reads. Run it once after install, or with `--force` to overwrite.
 
@@ -172,6 +172,33 @@ Aliases: `runtime:` = `harness:`, `persona:` = `profile:`, `branch:` / `worktree
 
 If direct send/ask still comes back unresolved, treat that as a routing problem, not a mere "target is offline" problem. The right follow-up is to disambiguate the target, inspect broker context with `scout who` / `scout latest`, or create/register the missing identity. Do not default to pushing the bring-up step back onto the operator for a known target.
 
+Local product handoffs use the public Scout address:
+
+```bash
+scout send --to scout "message for the local Scout inbox"
+```
+
+Broker names and concrete node or agent ids are diagnostic details. Normal send
+output should say whether the message was sent, not which broker or internal
+session handled it. Reusing an existing session is an explicit continuity
+choice, not the default.
+
+Session refs are separate route targets for continuing a concrete bound
+session. Use the bare `ref:<suffix>` form in receipts/history, and pass the
+suffix with `--ref`; do not encode refs into `@agent#harness?model` identity
+syntax.
+
+```bash
+scout ask --ref 7f3a9c21 "continue from that handoff"
+scout send --ref 7f3a9c21 "status for that same session"
+```
+
+Diagnostic views may show both layers, for example:
+
+```text
+sent to Scout via DM (ref:7f3a9c21)
+```
+
 ## Current Commands
 
 ```bash
@@ -227,10 +254,20 @@ scout server open
 scout server start
 scout server start --port 3200
 scout server open --path /agents/arc-codex-2.master.mini
+scout server start --public-origin https://scout.local
+scout server edge --local-name m1
 scout server start --vite-url http://127.0.0.1:43173   # SPA dev server
 scout server start --static --static-root /custom/client
 ```
 
 `scout server open` reuses an already-running matching Scout server on that port, or starts one in the background and opens the browser for you. Use `scout server` or `scout server help` for full flags.
 
-For the same web UI without the full `scout` CLI package, use **`@openscout/web`** (`openscout-web`): it ships its own `dist/client`, bundled Bun server, and pairing supervisor.
+The application server binds to `0.0.0.0` by default, treats `scout.local` as the local portal name, and derives the node URL as `<machine>.scout.local` unless the user configures a short alias such as `m1`. `scout server edge` publishes `scout.local` plus the node host with Bonjour/mDNS and runs Caddy against the active web port. The managed edge serves HTTP on port `80` for zero-cert local browsing and HTTPS on port `443` with Caddy's local CA; the HTTPS path needs the local CA trusted once by browsers that enforce their own trust store.
+
+`scout setup` verifies Caddy for this path. The setup command installs it with Homebrew on macOS when `caddy` is not already available, but Scout still runs Caddy directly with the generated `~/.scout/local-edge/Caddyfile` instead of registering a separate Homebrew service. The base LaunchAgent is labelled `dev.openscout` in source/dev installs and supervises the broker, local edge, web startup, and menu bar app; `scout doctor` prints the exact `launchctl bootout ...` command for the current mode.
+
+When the edge is up but the web app is down, Caddy serves a same-origin "Start Scout" page. The button calls Caddy's internal `/__openscout/web/start` path, which proxies to the always-on broker and starts the web server while keeping the user-facing URL at `scout.local` or `<name>.scout.local`.
+
+`packages/web` remains the internal web workspace. Published installs get that same server and client through `@openscout/scout`.
+
+For source development, `bun run dev:edge -- --local-name m1` starts the web dev stack and the local edge together. It generates Caddy config against the actual selected dev port, so worktree-specific ports and busy-port fallback still route through `scout.local`.

package/bin/openscout-runtime.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const runtimeDistDir = resolve(binDir, "../dist/runtime");
+
+const entrypoints = {
+  broker: resolve(runtimeDistDir, "broker-daemon.mjs"),
+  service: resolve(runtimeDistDir, "broker-process-manager.mjs"),
+  discover: resolve(runtimeDistDir, "mesh-discover.mjs"),
+};
+
+const [, , command = "service", ...args] = process.argv;
+const entrypoint = entrypoints[command];
+
+if (!entrypoint) {
+  console.error(`Unknown openscout-runtime command: ${command}`);
+  process.exit(1);
+}
+
+if (!existsSync(entrypoint)) {
+  console.error(
+    "Scout runtime dist entry is missing. Reinstall @openscout/scout or rebuild the package.",
+  );
+  process.exit(1);
+}
+
+const child = spawn(process.execPath, [entrypoint, ...args], {
+  stdio: "inherit",
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});