@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/server/routes/providers.js

@@ -0,0 +1,198 @@
+/**
+ * Provider surface routes: `GET /v1/models` (the merged chat-model
+ * catalog as picker entries — no provider internals: baseUrl, headers,
+ * and auth stay server-side) and `GET /v1/providers` (the secret-free
+ * per-provider readiness report, spec §6.4/§7.6).
+ *
+ * Core hardening W1 Task 6 (spec §5.7): the readiness report MOVED here
+ * from `/v1/auth/check` so `/v1/auth` is API auth only — the old path
+ * serves the identical body as a deprecated alias for one release,
+ * marking its responses with a `Deprecation: true` header.
+ *
+ * Core hardening W3 Task 6 (spec §7.6) adds the MUTATIONS: `POST
+ * /v1/providers/:id/refresh` (one bounded refresh, the entry back),
+ * `PUT /v1/providers/:id/credential {apiKey}` (admin) and `DELETE …
+ * /credential` (admin) — writes through `opened.auth` (the bridge stays
+ * read-only; the ROUTE is the writer), then ONE refresh, then the entry.
+ * Restart-free by the credential-precedence design: the auth bridge
+ * resolves auth.json per use, so the same in-process catalog picks the
+ * new key up on the next refresh — no provider restart, no re-boot.
+ */
+import { DEFAULT_AUTH_KEY } from "../../harness/auth.js";
+import { providerAuthStatus } from "../helpers.js";
+/**
+ * The per-provider readiness report (the shared derivation BOTH routes
+ * serve — one body, never two). The response carries ONLY a per-provider
+ * status (+ optional tracker detail) — no env values, no key material, no
+ * hints beyond the status itself (spec §6.4: "The API never accepts or
+ * returns credentials"). The status is a pure synchronous derivation over
+ * boot-retained state (same discipline as /v1/meta), per provider in
+ * catalog order (enumeration is over PROVIDERS — `getProviders()` — not
+ * models, so an empty-catalog boot contribution still appears):
+ *
+ *  1. readiness tracker registered by the owning contributor
+ *     (`contribution.readiness`): reported verbatim — the three-state
+ *     vocabulary `not_configured` (no credential resolved — an
+ *     unconfigured optional plugin, not a degraded process) |
+ *     `degraded` (configured, last refresh failed) | `ready` (refresh
+ *     succeeded / static catalog), plus its optional `detail`.
+ *  2. contributor-owned WITHOUT a tracker: the legacy producer mapping
+ *     is preserved — "ok" → `ready`, "degraded" → `invalid` (the §3
+ *     union is exactly ok | degraded; "degraded" is the known-bad
+ *     signal). A producer is per-contributor, not per-provider, so
+ *     every provider a contributor owns shares its status. No producer
+ *     → `not_ready` (nothing to verify).
+ *  3. env-degenerate provider (no contributor owns it — the collector's
+ *     ownership map has no entry): the legacy env-presence mapping is
+ *     preserved — `ready` iff a key resolves (`auth.json` `"default"`
+ *     or the provider's own entry, or a non-empty `OPENAI_API_KEY` in
+ *     the boot-retained provider env), else `not_ready`. (The
+ *     degenerate provider reports §3 health "ok" by absence, so key
+ *     presence is the honest readiness check for it; the three-state
+ *     vocabulary applies to plugin trackers only.)
+ */
+/** The per-request index of `opened.providerHealth` producers by name. */
+function producersIndex(opened) {
+    return new Map(opened.providerHealth.map((producer) => [producer.name, producer]));
+}
+/**
+ * One provider's report entry: the readiness derivation PLUS the W3
+ * Task 6 enrichment (spec §7.6) — the catalog `models` count
+ * (`models.getModels(id)`, pi-ai's best-effort count) and the owning
+ * contributor `owner` from the collector's ownership map (absent for
+ * the env-degenerate provider). The same entry serves every provider
+ * route: the report, the refresh response, and the credential
+ * write/delete responses — one shape, never two.
+ */
+function readinessEntry(opened, providerId, producersByName) {
+    const { status, detail } = providerAuthStatus(opened, providerId, producersByName);
+    const owner = opened.providerOwnership.get(providerId);
+    return {
+        provider: providerId,
+        status,
+        models: opened.models.getModels(providerId).length,
+        ...(owner === undefined ? {} : { owner }),
+        ...(detail === undefined ? {} : { detail }),
+    };
+}
+function providerReadinessReport(opened) {
+    // W2 Task 8's reconciliation: the per-provider derivation lives in ONE
+    // place — `providerAuthStatus` (helpers.ts, shared with the
+    // `sigrun_provider_ready{provider,status}` metric) — so this report and
+    // the metrics exposition can never drift. The response shape is W1's
+    // `/v1/providers` + deprecated-`/v1/auth/check` body plus the W3 Task 6
+    // enrichment (`models`, `owner`).
+    const producersByName = producersIndex(opened);
+    const providers = [];
+    for (const { id: providerId } of opened.models.getProviders()) {
+        providers.push(readinessEntry(opened, providerId, producersByName));
+    }
+    return { providers };
+}
+/** Register the model-catalog and provider-readiness routes. */
+export function registerProviderRoutes(app, ctx) {
+    const { opened } = ctx;
+    // The readiness home (spec §5.7/§7.6): the secret-free per-provider
+    // report, served from the one shared derivation above.
+    app.get("/v1/providers", async () => {
+        return providerReadinessReport(opened);
+    });
+    // The deprecated alias (spec §5.7: "The old path stays as a deprecated
+    // alias for one release"): the identical body plus the RFC 8594-style
+    // `Deprecation` header so clients can see the move on the wire.
+    app.get("/v1/auth/check", async (_request, reply) => {
+        reply.header("Deprecation", "true");
+        return providerReadinessReport(opened);
+    });
+    // The `:id` prelude shared by every mutation route: the provider must
+    // exist in the catalog (`getProviders()` is the enumeration the report
+    // serves, so the 404 vocabulary matches it). Key material never
+    // appears in any of these routes — statuses and counts only.
+    const isKnownProvider = (providerId) => opened.models.getProvider(providerId) !== undefined;
+    // One bounded refresh of the named provider (W3 Task 6, spec §7.6):
+    // the SAME policy the boot/interval/refresh-on-miss paths run — bounded
+    // by the deadline, failures warned (never the route's error), a
+    // flipped provider publishes `providers.changed`. Not admin-gated
+    // (spec §7.6 gates the credential writes only).
+    app.post("/v1/providers/:id/refresh", async (request, reply) => {
+        const { id } = request.params;
+        if (!isKnownProvider(id)) {
+            return await reply.code(404).send({ error: "provider_not_found" });
+        }
+        await opened.refreshProvider(id);
+        return readinessEntry(opened, id, producersIndex(opened));
+    });
+    // The auth.json key a credential write targets (spec §7.6): the magic
+    // `"default"` for the DEFAULT model's provider (the precedence fix
+    // makes that the winning key for exactly that provider), the
+    // provider's own id otherwise.
+    const credentialKey = (providerId) => providerId === opened.defaultModel.provider
+        ? DEFAULT_AUTH_KEY
+        : providerId;
+    // Write the provider's credential (admin): store write → one refresh
+    // (the bridge resolves per use, so the new key is live with NO restart)
+    // → the entry. The body is `{apiKey: string}` — a non-empty string,
+    // nothing else (errors name the field, never the value).
+    app.put("/v1/providers/:id/credential", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { id } = request.params;
+        if (!isKnownProvider(id)) {
+            return await reply.code(404).send({ error: "provider_not_found" });
+        }
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const apiKey = body.apiKey;
+        if (typeof apiKey !== "string" || apiKey === "") {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "apiKey" });
+        }
+        await opened.auth.setApiKey(credentialKey(id), apiKey);
+        await opened.refreshProvider(id);
+        return readinessEntry(opened, id, producersIndex(opened));
+    });
+    // Remove the provider's credential (admin): store delete of that SAME
+    // key → one refresh → the entry. Restart-free the same way — the
+    // tracker re-seeds `not_configured` on the refresh's auth resolution.
+    app.delete("/v1/providers/:id/credential", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { id } = request.params;
+        if (!isKnownProvider(id)) {
+            return await reply.code(404).send({ error: "provider_not_found" });
+        }
+        await opened.auth.deleteApiKey(credentialKey(id));
+        await opened.refreshProvider(id);
+        return readinessEntry(opened, id, producersIndex(opened));
+    });
+    // Models: the merged chat-model catalog as picker entries (no provider
+    // internals — baseUrl/headers/auth stay server-side).
+    app.get("/v1/models", async () => {
+        const models = opened.models.getModels().map((model) => ({
+            id: `${model.provider}/${model.id}`,
+            provider: model.provider,
+            modelId: model.id,
+            name: model.name,
+            contextWindow: model.contextWindow,
+            maxTokens: model.maxTokens,
+            reasoning: model.reasoning,
+            input: model.input,
+            // Project the four rate fields explicitly (ModelCostRates); `tiers` is
+            // dropped for v1 (the picker doesn't use them) — no unsound cast.
+            cost: {
+                input: model.cost.input,
+                output: model.cost.output,
+                cacheRead: model.cost.cacheRead,
+                cacheWrite: model.cost.cacheWrite,
+            },
+        }));
+        return { models };
+    });
+}

package/dist/server/routes/settings.js

@@ -0,0 +1,48 @@
+/**
+ * Settings routes over the file-backed store on the harness's live
+ * settings (pi parity): GET serves the current effective settings
+ * (absent file = `{}` — every default); PATCH validates + merges +
+ * persists through the store.
+ */
+import { SettingsValidationError } from "../../harness/settings.js";
+import { settingsResponse } from "../helpers.js";
+/** Register `GET`/`PATCH /v1/settings`. */
+export function registerSettingsRoutes(app, ctx) {
+    const { opened, config, env } = ctx;
+    // PATCH semantics: the harness picks a change up on the next resolution
+    // (steeringMode on the next submission's admission, because
+    // pi-durable re-reads `HarnessSettings` per boundary). Errors follow
+    // the repo's PATCH conventions: 400 `invalid_field` naming the key
+    // (unknown key, wrong type), 400 `invalid_body` for a non-object.
+    app.get("/v1/settings", async () => {
+        return settingsResponse(opened, config, env);
+    });
+    app.patch("/v1/settings", async (request, reply) => {
+        // Admin-only (spec §5.6): PATCH edits `extensions[]`, which is code
+        // execution at the next boot — a non-admin (any authenticated
+        // token-method user, a non-admin proxy user) gets 403 before the
+        // body is even read. GET stays ungated (spec lists only PATCH).
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const body = request.body;
+        if (body === undefined ||
+            body === null ||
+            typeof body !== "object" ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        try {
+            opened.settings.update(body);
+            return settingsResponse(opened, config, env);
+        }
+        catch (error) {
+            if (error instanceof SettingsValidationError) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: error.field });
+            }
+            throw error;
+        }
+    });
+}

package/dist/server/routes/stream.js

@@ -0,0 +1,131 @@
+/**
+ * The SSE view stream route: `GET /v1/conversations/:id/stream`. The
+ * conversation resolves through the `loadConversation` pre-handler, so the
+ * unknown-id 404 lands as plain JSON BEFORE the handler hijacks the reply —
+ * a hijacked stream has no error event. This endpoint is exercised over a
+ * REAL socket in tests: it writes raw frames, which `app.inject()` cannot
+ * observe (light-my-request settles only on `end()`).
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { loadConversation } from "../conversation-handler.js";
+import { ID_PARAMS_SCHEMA } from "../helpers.js";
+import { serializeConversationView, } from "../views.js";
+import { diffViews, isEmptyDelta, } from "@sigrun/shared/view-delta";
+/** Register the SSE view stream route. */
+export function registerStreamRoutes(app, ctx) {
+    // SSE view stream (spec §5 "Views + watch frames over SSE", §7.3 ruling
+    // 11): one Server-Sent Events stream per conversation, hand-rolled over
+    // `reply.raw` (no @fastify/sse dependency). Event shape: `event: snapshot`
+    // with the wire view on connect, then per watch revision the diff against
+    // the last-sent view: a representable change rides as `event: delta`
+    // (entry append/remove + changed docs; empty deltas are skipped), a
+    // NON-representable one (a compaction's new head marker, any reorder)
+    // falls back to a fresh `event: snapshot` — so a reconnect's snapshot and
+    // the fallback are the same frame, and the client's rule stays
+    // "snapshot REPLACES, delta folds" (see the Appendix C
+    // named-verification record). `Last-Event-ID` is therefore accepted and
+    // deliberately ignored. Heartbeat: a `: ping` comment every 15s (proxy/
+    // LB idle-timeout survival). Lifecycle: exactly one owner (`finish` below)
+    // stops the watch and clears the interval on client disconnect or watch
+    // termination.
+    app.get("/v1/conversations/:id/stream", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request, reply) => {
+        const conversation = request.conversation;
+        // Acquire the watch BEFORE hijacking: an acquisition failure then
+        // lands on Fastify's fail-loud 500 path — a hijacked stream has no
+        // error event. `value` is the acquisition revision (the snapshot
+        // source); frames published between here and start() are held by the
+        // watch's bounded pending delivery, so nothing is lost.
+        const watch = await conversation.watch(BACKGROUND_CONTEXT);
+        // Watcher bookkeeping (W5 Task 6, spec §9.6): one attached client.
+        // The exactly-once `finish` below decrements — the notifications
+        // surface's `"unwatched"` runSettled rule reads this count.
+        const watchers = ctx.watchersByConversation;
+        watchers.set(conversation.id, (watchers.get(conversation.id) ?? 0) + 1);
+        reply.hijack();
+        const raw = reply.raw;
+        raw.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            "connection": "keep-alive",
+            "x-accel-buffering": "no",
+        });
+        raw.flushHeaders();
+        // Socket-level write errors after teardown have no consumer (the
+        // close path owns teardown); swallow them so a mid-write disconnect
+        // cannot crash the process with an unhandled 'error' event.
+        raw.on("error", () => { });
+        let nextId = 1;
+        const send = (event, payload) => {
+            // Single data line: JSON.stringify escapes newlines in strings.
+            raw.write(`id: ${nextId++}\nevent: ${event}\ndata: ${JSON.stringify(payload)}\n\n`);
+        };
+        let finished = false;
+        const heartbeat = setInterval(() => {
+            raw.write(": ping\n\n");
+        }, 15_000);
+        // The single cleanup owner: client disconnect (response close =
+        // socket termination — NOT `request.raw.on("close")`, which on
+        // Node 26 fires at request-message completion, i.e. immediately for
+        // a bodyless GET) or watch termination (`watch.closed`). The flag
+        // makes it exactly-once even though both paths can race.
+        const finish = (fromWatchEnd) => {
+            if (finished)
+                return;
+            finished = true;
+            clearInterval(heartbeat);
+            // Watcher bookkeeping (W5 Task 6): the paired decrement — exactly
+            // once per increment by the `finished` guard, floored at removal
+            // so a stray double path can never drive the count negative.
+            const remaining = (watchers.get(conversation.id) ?? 1) - 1;
+            if (remaining <= 0)
+                watchers.delete(conversation.id);
+            else
+                watchers.set(conversation.id, remaining);
+            if (!fromWatchEnd) {
+                // stop() is idempotent upstream; fire-and-forget because the
+                // stream is ending regardless and a stop() rejection after a
+                // dead socket has no consumer to fail loud to.
+                void watch.stop().catch(() => { });
+            }
+            raw.end();
+        };
+        raw.on("close", () => finish(false));
+        // Upstream resolves `closed` with a WatchEnd for every terminal
+        // state (failures included); a rejection would be an upstream
+        // contract violation — catch it so one stream's anomaly ends that
+        // stream instead of taking the process down as an unhandled
+        // rejection.
+        void watch.closed.then(() => finish(true), () => finish(true));
+        // The client may have disconnected while the watch was being
+        // acquired (before the close listener existed): `destroyed` covers
+        // that window — stop the just-acquired watch instead of leaking it.
+        if (raw.destroyed) {
+            finish(false);
+            return;
+        }
+        // Snapshot FIRST (from the acquisition revision), then install the
+        // listener — pending frames flow after the snapshot because start
+        // never invokes the listener inline. `prev` is the last-sent wire
+        // view the diff loop measures against.
+        let prev = serializeConversationView(watch.value);
+        send("snapshot", prev);
+        watch.start(async (value) => {
+            if (finished)
+                return; // the stream is over; drop the frame
+            const next = serializeConversationView(value);
+            const delta = diffViews(prev, next);
+            prev = next;
+            // Not representable as entries append/remove + changed docs (a
+            // reorder or a compaction's new head marker) → a fresh snapshot.
+            if (delta === undefined) {
+                send("snapshot", next);
+                return;
+            }
+            // Nothing changed on the wire (a revision the serializer flattens
+            // away) — skip the frame entirely.
+            if (isEmptyDelta(delta))
+                return;
+            send("delta", delta);
+        });
+    });
+}