ai-fly 0.4.0 → 0.6.0-alpha.1

package/README.md

@@ -8,7 +8,7 @@ Share any HTTP/WebSocket upstream (ollama / vllm / LM Studio, an internal gatewa
 Consumer machine                         Provider machine
 Agent ──► http://127.0.0.1:11434/…       ollama :11434 (or any HTTP/WS upstream)
        ──► ws://127.0.0.1:11434/…            ▲   provider engine
-           consumer engine                   │   match set + rewrite ($env keys)
+           consumer engine                   │   match set + lifecycle hooks (auth/headers)
                │  AUTH keyring / catalog     │   quotas (per key)
                └────── OpenDWeb fabric ──────┘   (identity / invites / QUIC + relay)
 ```
@@ -38,15 +38,122 @@ credential injection impossible without MITM).
 ```bash
 # Provider
 ai-fly serve   --upstream http://127.0.0.1:11434   # run + manage services/groups
+ai-fly service stop ollama                         # pause exposure (catalog drops it, config kept)
+ai-fly service start ollama                        # resume; consumers see it again
 ai-fly key     issue --group friends                # sk-aifly-… keys
 ai-fly share   --group friends --ttl 30m            # aifly1.… link (token + key)
 
 # Consumer
 ai-fly import  <link> --run                        # join + keyring + start gateway
 ai-fly key     add <sk-aifly-…> --provider <id>    # bare key into an existing ring
+ai-fly services                                     # list services across groups (state + ports)
+ai-fly services stop <provider>                     # stop ALL of a provider's services (revivable)
+ai-fly services stop <provider> <service>           # stop one service's local listener (live)
+ai-fly services rm <provider>                       # remove the whole provider (= forget: keyring + fabric identity)
+ai-fly services start <provider> [<service>]        # re-enable (per-service stops persist across ring stops)
 ai-fly status  --verbose                            # ports, providers, service details
 ```
 
+Service lifecycle: a stopped provider service disappears from the consumer catalog
+(local listener closes, in-flight requests abort, requests get 404); a stopped
+consumer service is "removed but revivable" — the provider's catalog sync still
+updates the entry, it just never re-materializes a local port until you start it
+back. The running gateway daemon picks these changes up live (keyring watch); the
+dashboard's port table exposes the same start/stop/remove actions.
+
+## Request lifecycle (hooks v2)
+
+Every service runs a four-stage pipeline around the upstream call:
+
+`onRequestBearerAuthentication (1) -> onRequestHeaders (2) -> onRequest (3) -> onResponse (4)`
+
+- `service.auth` (stage 1) — Authorization header source: `{secret: <name>}`,
+  `{script: <name>, args?}` or `{literal: <value>}` (literals accept `$env:<VAR>` /
+  `$secret:<name>` indirection, resolved per request), plus `bearer: false` to drop
+  the default `Bearer ` prefix.
+- `service.headers` (stage 2) — `remove: [...]`, `set: {name: literal}` and an
+  optional whole-stage `script: {name, args?}` returning `{set?, remove?}` (script
+  output wins over the declared set).
+- `service.request` (stage 3) — takes over the outbound call entirely; ctx is
+  `{url, method, headers, body, signal}`, returns `{status, headers, body?}`.
+- `service.response` (stage 4) — post-processes the response; ctx is
+  `{status, headers, body, signal}`, returns `{status?, headers?, body?}`.
+
+Hook scripts export one function per stage they implement — the export name is the
+stage name. Builtin library: `codex` (reads `$CODEX_HOME/auth.json`, falling back to
+`~/.codex/auth.json` — read-only, ai-fly never writes credential files; set
+`CODEX_HOME` when your `~/.codex` holds a different Codex CLI config), plus `env` /
+`file` / `secret` bridges for stage 1.
+All stage fns receive `{homedir, args, secrets, env}`; stages 1-2 additionally get
+the request-level `{method, path, headers}`. Returned streams (3/4 bodies) are
+cancelled when the engine aborts the request.
+
+```bash
+# --secret -> auth = {secret: mykey}; --headers-script -> stage-2 whole-stage
+# script; --request-script/--response-script -> stage 3/4 bindings
+ai-fly service add myapi --upstream https://api.example.com --match suffix:api.example.com \
+  --secret mykey \
+  --header-set x-org=acme --header-remove x-internal \
+  --headers-script hdrfix \
+  --request-script mock-up --response-script log
+ai-fly hooks list                                 # stage matrix per script
+ai-fly hooks run codex --stage onRequestBearerAuthentication
+```
+
+**Breaking changes (hooks-lifecycle v2)**
+
+- Old hook scripts must be rewritten, not just renamed: export names changed
+  (`authHeader` -> `onRequestBearerAuthentication`, etc.) and the runtime contract
+  is new — request-scoped ctx, 3/4 object return shapes, stream cancellation.
+- v1 `services.json` (pre-`version: 2`) is invalid: the store enters a legacy
+  read-only state (`ai-fly service list` and `status --verbose` show the stale
+  names); remove them with `ai-fly service remove <name>`, then re-add services
+  to rebuild a clean v2 store (groups and share keys are not carried over).
+- The v1 string form `--hooks "<script>"` became an object slot in preset mode:
+  `--hooks <name>` binds one whole-script lifecycle (see below), mutually
+  exclusive with per-stage flags; `--secret` fills `auth.secret`; `--header-set`
+  values accept literals and `$env:`/`$secret:` references only (per-header hook
+  objects are gone — bind a stage script with `--headers-script` instead).
+
+## Lifecycle binding modes & rust-fetch
+
+Lifecycle config has two **mutually exclusive** modes (Owner ruling 2026-09-15):
+
+- **custom** — pick per-stage scripts or inline config (auth secret/literal,
+  header set/remove, …). The default.
+- **preset** — bind one hook-js with `hooks: {script}` (CLI `--hooks <name>`);
+  the script's stage exports form the whole lifecycle. Stages without an export
+  fall back to defaults (stage 3 unbound = js-backend-fetch — the current JS
+  runtime backend's fetch, Node/Deno/Bun alike).
+
+The `codex` preset runs in preset mode: the built-in `codex` script provides the
+complete lifecycle — ① auth token from `$CODEX_HOME/auth.json` (falling back to
+`~/.codex/auth.json`, read-only), ② the codex CLI header set (`chatgpt-account-id`,
+`originator`, `openai-beta`, user-agent), ③ outbound via the **rust-fetch** sidecar.
+Launch e.g. `CODEX_HOME=~/.ai-fly/codex-home pnpm app:dev` to keep that credential
+copy fully isolated from your own `~/.codex`.
+
+`rust-fetch` (rustls TLS + HTTP/2, a client stack distinct from
+js-backend-fetch) replaces the outbound HTTPS call — empirical A/B against
+chatgpt.com: GET /rate_limits via js-backend-fetch → 403 (Cloudflare, 0/13
+historically) vs rust-fetch → 404 (passes CF, reaches the backend); POST
+/responses with a real subscription → 200 + SSE through the full pipeline.
+
+Build & install the sidecar (not shipped in the repo) — **required before the
+codex preset can serve**; without it every request fails with a masked
+`hook_failed` (the daemon logs a one-line install hint to its stderr):
+
+```bash
+pnpm sidecar:install   # cargo build --release + copy to ~/.aifly/sidecars/rust-fetch/
+# or point AIFLY_RUST_FETCH_BIN at the binary when starting the daemon
+```
+
+Bind it per service (custom mode, stage 3 only) with `--request-script
+rust-fetch` (or the stage-3 selector in the WebUI); the codex preset carries it
+automatically. Per-request process spawn (no pooling yet); env proxies
+(HTTPS_PROXY/…) follow the Rust stack's defaults. stdio protocol is frozen in
+`openspec/changes/rust-fetch-sidecar`.
+
 ## Development
 
 ```bash
@@ -61,6 +168,35 @@ Node >= 20. License: MIT OR Apache-2.0. The fabric dependency
 `@jixo/opendweb-client-sdk` ships native binaries for darwin-arm64 and win32-x64
 (no Linux yet).
 
+### Local link development against the opendweb kernel
+
+The consumer/provider data plane rides the opendweb session-continuity kernel
+(`Fabric.openSession` / `fetchHttp` / `serveHttp`; the aifly envelope wire
+protocol is retired). While iterating against the opendweb workspace, link the
+SDK instead of installing from the registry:
+
+```bash
+# one-time, inside the opendweb workspace
+cd /path/to/opendweb/packages/client-sdk && npm link
+
+# then in this repo (replaces the registry install with a symlink)
+npm link @jixo/opendweb-client-sdk
+```
+
+Notes:
+
+- Do **not** run `pnpm install` in this repo while the link is in place — it
+  resolves the symlink back to the registry version. Add new dependencies in a
+  separate step and re-link afterwards.
+- `test/e2e/kernel-migration.test.mjs` is the real-kernel acceptance suite
+  (dual in-process fabrics + serveHttp/fetchHttp; SSE mid-stream resume, dead
+  semantics, provider restart, WS tunnel). It runs via
+  `node --import tsx --test --test-force-exit ...` (the native runtime keeps
+  the event loop alive; force-exit is required, mirroring the SDK's own test
+  script).
+- The `package.json` version stays on the published semver (`^0.5.0` line once
+  the dual-release milestone lands); the link is a dev-time override only.
+
 ## Manual regression checklist
 
 Desktop-shell behaviors that automated suites do not cover. Run before any
@@ -95,7 +231,7 @@ strings below are exactly what the UI shows.
    plain browser tab the layout must look identical (zero inset fallback).
 9. **Secrets panel** — Advanced > secrets: add a key-value pair, pick it in
    the share wizard's "api key" selector, generate a service; the saved
-   rewrite shows `authorization: $secret:<name>`; values never re-display
+   service shows the auth slot `secret <name>`; values never re-display
    after saving; removing a secret referenced by a service is allowed but the
    service then fails with `secret_missing` until re-added.
 10. **Connectivity test** — in the share wizard (with a secret picked) or a
@@ -103,3 +239,26 @@ strings below are exactly what the UI shows.
     picked by default, the dropdown lists models sorted by price, and the
     result line shows `ok · <ms> · <model>` or the upstream error (an
     upstream 401 with an invalid key is a PASS — the network is proven).
+11. **Service lifecycle** — with a running gateway, stop a service from the
+    dashboard's port table (or `ai-fly services stop`): its local port
+    refuses connections within ~a second and the row flips to disabled;
+    start restores the same port. Stop it on the *provider* (`ai-fly service
+    stop <name>`): the consumer's row disappears (catalog sync); start brings
+    it back. Remove on the consumer keeps the entry hidden-but-revivable —
+    `ai-fly services` still lists it as `disabled`, and starting it again
+    works without re-importing.
+12. **Codex e2e through the gateway** — with a provider exposing a codex
+    subscription service and a consumer gateway running, point Codex CLI at
+    the mapped port (`OPENAI_BASE_URL=http://127.0.0.1:<port>/v1` with the
+    group key): a chat completion streams through, tool calls round-trip, and
+    `ai-fly status --verbose` shows the served count climbing.
+13. **SSE mid-stream connection swap (kernel continuity)** — start a long
+    streaming request through the gateway (e.g. a slow/long codex response),
+    then kill the provider's network path mid-stream (`ai-fly` fabric reset
+    injection or simply restart the provider process within the recovery
+    window): the stream continues in order with **no duplicated tokens**, the
+    upstream request is NOT re-executed (provider logs show one execution),
+    and `ai-fly status` shows the provider flipping to offline then back —
+    the client never sees an error. Kill the provider for longer than the
+    recovery window: in-flight requests fail with a network error and only
+    *new* requests get 503 `provider_offline`.

package/dist/ai-fly.js

@@ -37,6 +37,9 @@ Consumer:
   ai-fly test [--data <dir>] [--service <name>] [--form …] [--content <text>]
                                single AI request through the local gateway
   ai-fly key add <sk-aifly-key> --provider <id>         bare key into an existing ring
+  ai-fly services [list]                                services across groups (state + ports)
+  ai-fly services stop|start <provider> [<service>]         provider- or service-level lifecycle (live)
+  ai-fly services rm <provider> [<service>]                rm provider (= forget) or one service
   ai-fly forget <endpointId|8-char-prefix>              drop an imported provider
 
 Config:
@@ -63,7 +66,7 @@ async function dispatch(command, rest) {
 	const lazy = (load) => {
 		return (argv, ctx) => load().then((m) => m.run([...argv], ctx));
 	};
-	return match(command).with("serve", () => lazy(() => import("./serve-B51lmr9M.mjs"))(rest)).with("app", async () => {
+	return match(command).with("serve", () => lazy(() => import("./serve-DJ8id2Qo.mjs"))(rest)).with("app", async () => {
 		const { join, dirname } = await import("node:path");
 		const { fileURLToPath } = await import("node:url");
 		const { spawn } = await import("node:child_process");
@@ -78,17 +81,17 @@ async function dispatch(command, rest) {
 		return await new Promise((resolve) => {
 			child.once("exit", (c) => resolve(c ?? 0));
 		});
-	}).with("daemon", () => lazy(() => import("./daemon-BWgyJMyB.mjs"))(rest)).with("presets", () => lazy(() => import("./presets-DleOUQiT.mjs"))(rest)).with("hooks", () => lazy(() => import("./hooks-DUrXA7PL.mjs"))(rest)).with("secret", () => lazy(() => import("./secret-P2RgHy2h.mjs"))(rest)).with("settings", async () => (await import("./settings-Rq1zLoxY.mjs")).runAsSettings(rest, {})).with("relay", async () => (await import("./settings-Rq1zLoxY.mjs")).runAsRelay(rest, {})).with("test", () => lazy(() => import("./test-DW4BF7xJ.mjs"))(rest)).with("service", () => lazy(() => import("./service-D6TNolyh.mjs"))(rest)).with("group", () => lazy(() => import("./group-BdnvRD2t.mjs"))(rest)).with("share", () => lazy(() => import("./share-DdtbAylA.mjs"))(rest)).with("revoke", () => lazy(() => import("./revoke-DTFW_EF1.mjs"))(rest)).with("join", () => lazy(() => import("./join-d-pqyf8e.mjs"))(rest)).with("import", () => lazy(() => import("./import-CTkKGPsa.mjs"))(rest)).with("run", () => lazy(() => import("./run-D8kgXdId.mjs"))(rest)).with("ports", () => lazy(() => import("./ports-TQ4tWmiJ.mjs"))(rest)).with("forget", () => lazy(() => import("./forget-B3KRkHho.mjs"))(rest)).with("key", () => {
-		if (rest[0] === "add") return lazy(() => import("./key-D_66hrWW.mjs"))(rest);
-		return lazy(() => import("./key-CTL_AXOh.mjs"))(rest);
+	}).with("daemon", () => lazy(() => import("./daemon-D5J50r7U.mjs"))(rest)).with("presets", () => lazy(() => import("./presets-BwkVV7E2.mjs"))(rest)).with("hooks", () => lazy(() => import("./hooks-BztmB61b.mjs"))(rest)).with("secret", () => lazy(() => import("./secret-BrfkuRkP.mjs"))(rest)).with("settings", async () => (await import("./settings-15j9BB6j.mjs")).runAsSettings(rest, {})).with("relay", async () => (await import("./settings-15j9BB6j.mjs")).runAsRelay(rest, {})).with("test", () => lazy(() => import("./test-ChqaPwHA.mjs"))(rest)).with("service", () => lazy(() => import("./service-P-vz61tx.mjs"))(rest)).with("group", () => lazy(() => import("./group-Dh64zhKn.mjs"))(rest)).with("share", () => lazy(() => import("./share-mozydAfj.mjs"))(rest)).with("revoke", () => lazy(() => import("./revoke-DMx9hZUH.mjs"))(rest)).with("join", () => lazy(() => import("./join-CLD4fdCf.mjs"))(rest)).with("import", () => lazy(() => import("./import-DN8bNBJU.mjs"))(rest)).with("run", () => lazy(() => import("./run-C-CxjlLu.mjs"))(rest)).with("ports", () => lazy(() => import("./ports-DmBKgLSi.mjs"))(rest)).with("forget", () => lazy(() => import("./forget-DGJwF3Gy.mjs"))(rest)).with("services", () => lazy(() => import("./services-Deh7Gxwa.mjs"))(rest)).with("key", () => {
+		if (rest[0] === "add") return lazy(() => import("./key-JLJewbw9.mjs"))(rest);
+		return lazy(() => import("./key-Cpw-HzT4.mjs"))(rest);
 	}).with("status", async () => {
 		const [scope, ...tail] = rest;
 		const wantProvider = scope === "provider" || scope !== "consumer" && providerDirExists();
 		const wantConsumer = scope === "consumer" || scope !== "provider" && consumersRootExists();
 		const argv = scope === "provider" || scope === "consumer" ? tail : rest;
 		let code = 0;
-		if (wantProvider) code = Math.max(code, await lazy(() => import("./status-DSVQ3YHm.mjs"))(argv));
-		if (wantConsumer) code = Math.max(code, await lazy(() => import("./status-uE2-kOyK.mjs"))(argv));
+		if (wantProvider) code = Math.max(code, await lazy(() => import("./status-DsFpGrzC.mjs"))(argv));
+		if (wantConsumer) code = Math.max(code, await lazy(() => import("./status-BlvQvxGW.mjs"))(argv));
 		if (!wantProvider && !wantConsumer) process.stdout.write("nothing to report: no provider storage and no imported consumers\n");
 		return code;
 	}).otherwise(() => {