@knpkv/herdr-usage 0.0.0-stage → 0.1.1

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("@knpkv/hub-app").AppClient;
+export default _default;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":""}

package/dist/client.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The Usage app's client: the same {@link UsagePage} the hub renders, in the app's own React root, given a
+ * {@link UsageShell} made from the {@link ShellContext} its shell passes. Bundled to `dist/client/client.js`.
+ *
+ * Reads go to the app's own routes (`ctx.api("/limits")`, `ctx.api("/usage")`), with the shell's request headers.
+ *
+ * @module
+ */
+import { FleetLimits, FleetReadLoadError, FleetUsage } from "@knpkv/herdr-connect/usage";
+import { defineAppClient } from "@knpkv/hub-app";
+import { Icon } from "@knpkv/rly/foundations";
+import { Clock, Effect, Exit, ManagedRuntime, Option, Schema } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import { useMemo } from "react";
+import { createRoot } from "react-dom/client";
+import { UsagePage, UsagePageId } from "./views.js";
+const runtime = ManagedRuntime.make(FetchHttpClient.layer);
+/** One read of an app route, stamped with when this page received it. */
+const load = Effect.fn("UsageClient.load")(function* (context, path, schema) {
+    const url = context.api(path);
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client
+        .execute(HttpClientRequest.get(new URL(url, window.location.href)).pipe(HttpClientRequest.setHeaders(context.requestHeaders())))
+        .pipe(Effect.mapError((cause) => new FleetReadLoadError({ path: url, reason: "network", cause })));
+    if (response.status < 200 || response.status >= 300) {
+        return yield* new FleetReadLoadError({ path: url, reason: "status", cause: response.status });
+    }
+    const fleet = yield* response.json.pipe(Effect.flatMap(Schema.decodeUnknownEffect(schema)), Effect.mapError((cause) => new FleetReadLoadError({ path: url, reason: "decode", cause })));
+    return { fleet, receivedAt: yield* Clock.currentTimeMillis };
+});
+/** Run a read on this page's runtime; unmounting or leaving the page aborts its request. */
+const onRuntime = (effect) => Effect.callback((resume, signal) => {
+    runtime.runCallback(effect, {
+        signal,
+        onExit: (exit) => resume(Exit.isSuccess(exit) ? Effect.succeed(exit.value) : Effect.failCause(exit.cause))
+    });
+});
+/** The header chrome the shell lends, when it lends an outlet and the means to group around it. */
+const chromeOf = (context) => {
+    const { headerOutlet, setHeaderMode } = context;
+    return headerOutlet === undefined || headerOutlet === null || setHeaderMode === undefined
+        ? null
+        : {
+            host: context.caller.login,
+            headerOutlet,
+            setEmpty: context.setEmpty,
+            setGrouped: (grouped) => setHeaderMode(grouped ? "grouped" : "shell")
+        };
+};
+const UsageApp = ({ context }) => {
+    const reads = useMemo(() => ({
+        limits: onRuntime(load(context, "/limits", FleetLimits)),
+        usage: (query) => onRuntime(load(context, `/usage?${new URLSearchParams({ range: query.range, timeZone: query.timeZone }).toString()}`, FleetUsage))
+    }), [context.api, context.requestHeaders]);
+    const shell = useMemo(() => ({
+        active: context.active,
+        navigate: (href) => context.navigate(href, "replace", null),
+        href: (page, search) => {
+            const query = new URLSearchParams(search);
+            query.delete("tab");
+            return `?${query.toString()}#usage/${page}`;
+        },
+        // The shell's header outlet, when it lends one; standalone it has no grouped header, so no chrome.
+        chrome: chromeOf(context),
+        nextIcon: _jsx(Icon, { name: "chevron-right", decorative: true })
+    }), [context]);
+    const page = Option.getOrElse(Schema.decodeUnknownOption(UsagePageId)(context.page), () => "limits");
+    return (_jsx(UsagePage, { content: {
+            host: context.caller.login,
+            reads,
+            viewerTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            now: Date.now(),
+            onHubMachine: false
+        }, shell: shell, page: page, search: context.search }));
+};
+export default defineAppClient({
+    contract: 1,
+    mount: (root, context) => {
+        const react = createRoot(root);
+        react.render(_jsx(UsageApp, { context: context }));
+        return {
+            update: (next) => react.render(_jsx(UsageApp, { context: next })),
+            unmount: () => react.unmount()
+        };
+    }
+});
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"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"}

package/dist/host/failure.d.ts

@@ -0,0 +1,15 @@
+import { Effect, Schema } from "effect";
+declare const CommandFailed_base: Schema.Class<CommandFailed, Schema.TaggedStruct<"CommandFailed", {
+    readonly kind: Schema.Literals<readonly ["exit", "spawn", "too_large"]>;
+    /** Host-local text: stderr, or the spawn error. Logged, never sent. */
+    readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** agent-usage could not answer: it exited nonzero (with its stderr), could not be started, or printed too much. */
+export declare class CommandFailed extends CommandFailed_base {
+}
+/** The fixed sentence a failure is reported by off this host. Never contains the failure's own text. */
+export declare const failureSentence: (failure: CommandFailed) => string;
+/** Logs the failure's host-local text here and answers the sentence that may leave the host. */
+export declare const reportFailure: (what: string, failure: CommandFailed) => Effect.Effect<string>;
+export {};
+//# sourceMappingURL=failure.d.ts.map

package/dist/host/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/host/failure.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;;;IAKrC,uEAAuE;;;AAHzE,oHAAoH;AACpH,qBAAa,aAAc,SAAQ,kBAIjC;CAAG;AAeL,wGAAwG;AACxG,eAAO,MAAM,eAAe,YAAa,aAAa,KAAG,MASxD,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,aAAa,SAAU,MAAM,WAAW,aAAa,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAGtF,CAAA"}

package/dist/host/failure.js

@@ -0,0 +1,44 @@
+/**
+ * What a failed agent-usage command may say off this host. agent-usage explains itself on stderr,
+ * and its sentences can name host paths (the control socket under the user's home, the store
+ * directory, the executable); a peer's reading crosses the tailnet to the hub and reaches the
+ * browser. So the raw text is logged here, on this host, and the reading carries only one of a fixed
+ * set of sentences, chosen by recognising agent-usage's own wording.
+ *
+ * @module
+ */
+import { failureSentences } from "@knpkv/herdr-connect";
+import { Effect, Schema } from "effect";
+/** agent-usage could not answer: it exited nonzero (with its stderr), could not be started, or printed too much. */
+export class CommandFailed extends Schema.TaggedError()("CommandFailed", {
+    kind: Schema.Literals(["exit", "spawn", "too_large"]),
+    /** Host-local text: stderr, or the spawn error. Logged, never sent. */
+    detail: Schema.String
+}) {
+}
+/** agent-usage's own sentences, recognised by wording that holds no path, and what is said instead. */
+const knownFailures = [
+    [/is not running on this store/u, failureSentences.notRunning],
+    [/older version without (?:limits|usage)/u, failureSentences.olderVersion],
+    [/could not read its store/u, failureSentences.storeUnreadable],
+    [/control socket/u, failureSentences.controlSocket],
+    [/does not know the time zone/u, failureSentences.unknownTimeZone],
+    [/does not offer the range/u, failureSentences.unknownRange],
+    [/request was malformed/u, failureSentences.malformed],
+    [/configuration could not be read/u, failureSentences.configuration],
+    [/answered with something that is not/u, failureSentences.unexpectedAnswer]
+];
+/** The fixed sentence a failure is reported by off this host. Never contains the failure's own text. */
+export const failureSentence = (failure) => {
+    switch (failure.kind) {
+        case "spawn":
+            return failureSentences.spawn;
+        case "too_large":
+            return failureSentences.tooLarge;
+        case "exit":
+            return knownFailures.find(([pattern]) => pattern.test(failure.detail))?.[1] ?? failureSentences.other;
+    }
+};
+/** Logs the failure's host-local text here and answers the sentence that may leave the host. */
+export const reportFailure = (what, failure) => Effect.logWarning(`${what}: agent-usage failed (${failure.kind})`, failure.detail).pipe(Effect.as(failureSentence(failure)));
+//# sourceMappingURL=failure.js.map

package/dist/host/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../src/host/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEvC,oHAAoH;AACpH,MAAM,OAAO,aAAc,SAAQ,MAAM,CAAC,WAAW,EAAiB,CAAC,eAAe,EAAE;IACtF,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IACrD,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CAAC;CAAG;AAEL,uGAAuG;AACvG,MAAM,aAAa,GAA6C;IAC9D,CAAC,+BAA+B,EAAE,gBAAgB,CAAC,UAAU,CAAC;IAC9D,CAAC,yCAAyC,EAAE,gBAAgB,CAAC,YAAY,CAAC;IAC1E,CAAC,2BAA2B,EAAE,gBAAgB,CAAC,eAAe,CAAC;IAC/D,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,aAAa,CAAC;IACnD,CAAC,8BAA8B,EAAE,gBAAgB,CAAC,eAAe,CAAC;IAClE,CAAC,2BAA2B,EAAE,gBAAgB,CAAC,YAAY,CAAC;IAC5D,CAAC,wBAAwB,EAAE,gBAAgB,CAAC,SAAS,CAAC;IACtD,CAAC,kCAAkC,EAAE,gBAAgB,CAAC,aAAa,CAAC;IACpE,CAAC,sCAAsC,EAAE,gBAAgB,CAAC,gBAAgB,CAAC;CAC5E,CAAA;AAED,wGAAwG;AACxG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAsB,EAAU,EAAE;IAChE,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,OAAO;YACV,OAAO,gBAAgB,CAAC,KAAK,CAAA;QAC/B,KAAK,WAAW;YACd,OAAO,gBAAgB,CAAC,QAAQ,CAAA;QAClC,KAAK,MAAM;YACT,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAA;IACzG,CAAC;AACH,CAAC,CAAA;AAED,gGAAgG;AAChG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,OAAsB,EAAyB,EAAE,CAC3F,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,yBAAyB,OAAO,CAAC,IAAI,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CACrF,MAAM,CAAC,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CACpC,CAAA"}

package/dist/host/limits.d.ts

@@ -0,0 +1,59 @@
+import { Duration, Effect, type Scope } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { CommandFailed } from "./failure.js";
+/** agent-usage's answer is a few KiB; anything near this is not it. */
+export declare const hostLimitsOutputMaxBytes: number;
+export declare const hostLimitsTimeout = "10 seconds";
+/** Runs an agent-usage command and answers its stdout, failing with its stderr when it exits nonzero. */
+export declare const runCommand: (command: readonly [string, ...string[]], maxBytes?: number | undefined) => Effect.Effect<string, CommandFailed, ChildProcessSpawner.ChildProcessSpawner>;
+/**
+ * Runs the configured command once and reports what it said. Never fails: no command, a crash, a
+ * timeout, a newer format (`unsupported_version`) or output that is not agent-usage's each become
+ * `Unavailable` with its own reason, so one broken host cannot blank the fleet view.
+ */
+export declare const readHostLimits: (host: string, command: readonly string[] | undefined) => Effect.Effect<{
+    host: string;
+    readAt: number;
+    reading: {
+        readonly _tag: "Read";
+        readonly limits: {
+            readonly v: 1;
+            readonly machine: string;
+            readonly observedAt: number;
+            readonly latest: readonly {
+                readonly agent: "claude" | "codex";
+                readonly machine: string;
+                readonly source: "claude-oauth-usage" | "claude-statusline" | "codex-rollout";
+                readonly label: string;
+                readonly windowMinutes: number | null;
+                readonly observedAt: number;
+                readonly reading: {
+                    readonly _tag: "Known";
+                    readonly usedPercent: number;
+                    readonly resetsAt: number | null;
+                } | {
+                    readonly _tag: "Unknown";
+                    readonly reason: "AuthExpired" | "Fetch" | "KeychainDenied" | "NoAuth" | "NoData" | "NotSupported" | "Parse";
+                    readonly detail?: string;
+                };
+            }[];
+        };
+        readonly skipped: number;
+    } | {
+        readonly _tag: "Unavailable";
+        readonly reason: "failed" | "invalid_output" | "not_configured" | "timeout" | "unsupported_version";
+        readonly detail: string;
+    };
+}, never, ChildProcessSpawner.ChildProcessSpawner>;
+/** A value read through a cache: `read` answers at once after the first call. */
+export interface StaleWhileRevalidate<A> {
+    readonly read: Effect.Effect<A>;
+}
+/**
+ * Serves `read`'s last value and refreshes it in the background once it is older than `ttl`, so a
+ * caller never waits on a slow read after the first. Only the first call blocks, and concurrent
+ * first calls share that one read. At most one refresh runs at a time; it lives in the caller's
+ * scope, so closing the scope stops it.
+ */
+export declare const staleWhileRevalidate: <A>(read: Effect.Effect<A, never, never>, ttl: Duration.Duration) => Effect.Effect<StaleWhileRevalidate<A>, never, Scope.Scope>;
+//# sourceMappingURL=limits.d.ts.map

package/dist/host/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/host/limits.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAS,QAAQ,EAAE,MAAM,EAAuB,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAA;AACjF,OAAO,EAAgB,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,aAAa,EAAiB,MAAM,cAAc,CAAA;AAE3D,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAAa,CAAA;AAClD,eAAO,MAAM,iBAAiB,eAAe,CAAA;AAI7C,yGAAyG;AACzG,eAAO,MAAM,UAAU,2JA8BrB,CAAA;AA+BF;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAMzB,CAAA;AAEF,iFAAiF;AACjF,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;CAChC;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAA0D,CAAC,6HAyB1F,CAAA"}

package/dist/host/limits.js

@@ -0,0 +1,96 @@
+/**
+ * This host's Claude and Codex limits for Connect: hostd runs the configured
+ * `agent-usage limits` command and serves its answer, refreshed in the background. The command
+ * reads agent-usage's own store over its owner-only control socket, so no provider credential and
+ * no session cookie passes through hostd.
+ *
+ * @module
+ */
+import { collectBoundedText } from "@knpkv/bounded-io";
+import { decodeLimitsTolerantly, limitsUnavailable, notConfiguredSentences, RawLimits, readingOf, reasonSentences } from "@knpkv/herdr-connect";
+import { Clock, Duration, Effect, Ref, Result, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { CommandFailed, reportFailure } from "./failure.js";
+/** agent-usage's answer is a few KiB; anything near this is not it. */
+export const hostLimitsOutputMaxBytes = 256 * 1024;
+export const hostLimitsTimeout = "10 seconds";
+const decodeRawLimits = Schema.decodeUnknownResult(Schema.fromJsonString(RawLimits));
+/** Runs an agent-usage command and answers its stdout, failing with its stderr when it exits nonzero. */
+export const runCommand = Effect.fn("HostLimits.run")(function* (command, maxBytes = hostLimitsOutputMaxBytes) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(ChildProcess.make(command[0], command.slice(1)));
+        const { exitCode, stderr, stdout } = yield* Effect.all({
+            exitCode: handle.exitCode,
+            stderr: collectBoundedText(handle.stderr, hostLimitsOutputMaxBytes),
+            stdout: collectBoundedText(handle.stdout, maxBytes)
+        }, { concurrency: "unbounded" });
+        if (Number(exitCode) !== 0) {
+            return yield* new CommandFailed({
+                kind: "exit",
+                detail: stderr.trim() === "" ? `exited with code ${String(exitCode)}` : stderr
+            });
+        }
+        return stdout;
+    })).pipe(Effect.catchTags({
+        ByteLimitExceeded: () => Effect.fail(new CommandFailed({ kind: "too_large", detail: "output over the size limit" }))
+    }), Effect.mapError((error) => error._tag === "CommandFailed" ? error : new CommandFailed({ kind: "spawn", detail: String(error) })));
+});
+const readReading = (command) => {
+    const executable = command?.[0];
+    if (command === undefined || executable === undefined) {
+        return Effect.succeed(limitsUnavailable("not_configured", notConfiguredSentences.noCommand));
+    }
+    return runCommand([executable, ...command.slice(1)]).pipe(Effect.timeoutOrElse({ duration: hostLimitsTimeout, orElse: () => Effect.succeed(null) }), Effect.map((stdout) => {
+        if (stdout === null)
+            return limitsUnavailable("timeout", reasonSentences.timeout);
+        const json = decodeRawLimits(stdout.trim());
+        if (Result.isFailure(json)) {
+            return limitsUnavailable("invalid_output", reasonSentences.invalid_output);
+        }
+        // A newer agent-usage may add sources or reasons: what this hostd can't read is skipped and counted.
+        return readingOf(decodeLimitsTolerantly(json.success));
+    }), 
+    // agent-usage's own sentence can name host paths: it is logged here, and a fixed sentence leaves.
+    Effect.catchTag("CommandFailed", (failure) => Effect.map(reportFailure("Connect limits", failure), (sentence) => limitsUnavailable("failed", sentence))));
+};
+/**
+ * Runs the configured command once and reports what it said. Never fails: no command, a crash, a
+ * timeout, a newer format (`unsupported_version`) or output that is not agent-usage's each become
+ * `Unavailable` with its own reason, so one broken host cannot blank the fleet view.
+ */
+export const readHostLimits = Effect.fn("HostLimits.read")(function* (host, command) {
+    const reading = yield* readReading(command);
+    return { host, readAt: yield* Clock.currentTimeMillis, reading };
+});
+/**
+ * Serves `read`'s last value and refreshes it in the background once it is older than `ttl`, so a
+ * caller never waits on a slow read after the first. Only the first call blocks, and concurrent
+ * first calls share that one read. At most one refresh runs at a time; it lives in the caller's
+ * scope, so closing the scope stops it.
+ */
+export const staleWhileRevalidate = Effect.fn("HostLimits.staleWhileRevalidate")(function* (read, ttl) {
+    const scope = yield* Effect.scope;
+    const ttlMillis = Duration.toMillis(ttl);
+    const latest = yield* Ref.make(null);
+    const refreshing = yield* Ref.make(false);
+    const refresh = Effect.gen(function* () {
+        const value = yield* read;
+        yield* Ref.set(latest, { value, at: yield* Clock.currentTimeMillis });
+        return value;
+    });
+    const first = yield* Effect.cached(refresh);
+    const cached = {
+        read: Effect.gen(function* () {
+            const current = yield* Ref.get(latest);
+            if (current === null)
+                return yield* first;
+            if ((yield* Clock.currentTimeMillis) - current.at >= ttlMillis && !(yield* Ref.getAndSet(refreshing, true))) {
+                yield* Effect.forkIn(refresh.pipe(Effect.ensuring(Ref.set(refreshing, false))), scope);
+            }
+            return current.value;
+        })
+    };
+    return cached;
+});
+//# sourceMappingURL=limits.js.map

package/dist/host/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/host/limits.ts"],"names":[],"mappings":"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"}

package/dist/host/usage.d.ts

@@ -0,0 +1,93 @@
+/**
+ * This host's usage for the hub's Usage tab: hostd runs `agent-usage usage` for the asked range and
+ * zone and serves its answer, refreshed in the background. Like limits, the command reads
+ * agent-usage's own store over its owner-only control socket, and its answer holds tokens per agent
+ * and model and the limit series only: agent-usage leaves cost, balances, Bookings and paths out at
+ * the source.
+ *
+ * **The command.** It is the configured `agentUsageLimitsCommand` with its final `limits` word
+ * replaced by `usage`, so a host set up for Connect's limits needs nothing new. A command that does
+ * not end in `limits` (a wrapper script) has no usage, and says so.
+ *
+ * @module
+ */
+import { type HostUsage, type UsageQuery } from "@knpkv/herdr-connect";
+import { Duration, Effect, Scope } from "effect";
+import type { ChildProcessSpawner } from "effect/process";
+export declare const hostUsageTimeout = "20 seconds";
+/** How long a read is served before it is refreshed in the background: usage is history, not a live gauge. */
+export declare const hostUsageTtl: Duration.Duration;
+/** At most this many range and zone pairs are cached; the oldest is dropped for a new one. */
+export declare const hostUsageCacheEntries = 16;
+/** The `agent-usage usage` command for a configured limits command, or undefined when it has none. */
+export declare const usageCommandFor: (limitsCommand: ReadonlyArray<string> | undefined) => readonly [string, ...Array<string>] | undefined;
+/**
+ * Runs the usage command once for `query` and reports what it said. Never fails: no command, a
+ * crash, a timeout, a newer format or output that is not agent-usage's each become `Unavailable`
+ * with its own reason.
+ */
+export declare const readHostUsage: (host: string, limitsCommand: readonly string[] | undefined, query: {
+    readonly range: "24h" | "30d" | "7d";
+    readonly timeZone: string;
+}) => Effect.Effect<{
+    host: string;
+    readAt: number;
+    reading: {
+        readonly _tag: "Read";
+        readonly usage: {
+            readonly v: 1;
+            readonly machine: string;
+            readonly observedAt: number;
+            readonly range: {
+                readonly preset: "24h" | "30d" | "7d";
+                readonly timeZone: string;
+                readonly from: number;
+                readonly to: number;
+                readonly bucket: "day" | "hour" | "week";
+            };
+            readonly periods: readonly {
+                readonly key: string;
+                readonly start: number;
+            }[];
+            readonly tokens: readonly {
+                readonly period: number;
+                readonly agent: "claude" | "codex";
+                readonly model: string;
+                readonly tokens: number;
+            }[];
+            readonly limits: readonly {
+                readonly agent: "claude" | "codex";
+                readonly label: string;
+                readonly windowMinutes: number | null;
+                readonly points: readonly {
+                    readonly at: number;
+                    readonly reading: {
+                        readonly _tag: "Known";
+                        readonly usedPercent: number;
+                        readonly resetsAt: number | null;
+                    } | {
+                        readonly _tag: "Unknown";
+                        readonly reason: "AuthExpired" | "Fetch" | "KeychainDenied" | "NoAuth" | "NoData" | "NotSupported" | "Parse";
+                        readonly detail?: string;
+                    };
+                }[];
+            }[];
+        };
+        readonly skipped: number;
+    } | {
+        readonly _tag: "Unavailable";
+        readonly reason: "failed" | "invalid_output" | "not_configured" | "timeout" | "unsupported_version";
+        readonly detail: string;
+    };
+}, never, ChildProcessSpawner.ChildProcessSpawner>;
+/** At most this many agent-usage reads run at once across every range and zone. */
+export declare const hostUsageConcurrentReads = 2;
+/**
+ * One {@link staleWhileRevalidate} per range and zone, at most {@link hostUsageCacheEntries} of
+ * them: a new pair beyond that drops the least recently asked one. Finding or creating a pair's
+ * entry is atomic, so concurrent first asks share one read; and at most
+ * {@link hostUsageConcurrentReads} reads run at once, so a burst of new pairs queues rather than
+ * starting a command each. Refreshes live in `scope`.
+ */
+export declare const usageCache: (read: (query: UsageQuery) => Effect.Effect<HostUsage>, ttl?: Duration.Duration | undefined, entries?: number | undefined) => Effect.Effect<(query: UsageQuery) => Effect.Effect<HostUsage>, never, Scope.Scope>;
+//# sourceMappingURL=usage.d.ts.map

package/dist/host/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/host/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,KAAK,SAAS,EAId,KAAK,UAAU,EAIhB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAS,QAAQ,EAAE,MAAM,EAAkB,KAAK,EAA8B,MAAM,QAAQ,CAAA;AACnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAKzD,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C,8GAA8G;AAC9G,eAAO,MAAM,YAAY,mBAAsB,CAAA;AAE/C,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,KAAK,CAAA;AAIvC,sGAAsG;AACtG,eAAO,MAAM,eAAe,kBACX,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,KAC/C,SAAS,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,SAKxC,CAAA;AAiCD;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAOxB,CAAA;AAEF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,iBACP,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,8FA8BtC,UAAU,KAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,qBACpD,CAAA"}

package/dist/host/usage.js

@@ -0,0 +1,95 @@
+/**
+ * This host's usage for the hub's Usage tab: hostd runs `agent-usage usage` for the asked range and
+ * zone and serves its answer, refreshed in the background. Like limits, the command reads
+ * agent-usage's own store over its owner-only control socket, and its answer holds tokens per agent
+ * and model and the limit series only: agent-usage leaves cost, balances, Bookings and paths out at
+ * the source.
+ *
+ * **The command.** It is the configured `agentUsageLimitsCommand` with its final `limits` word
+ * replaced by `usage`, so a host set up for Connect's limits needs nothing new. A command that does
+ * not end in `limits` (a wrapper script) has no usage, and says so.
+ *
+ * @module
+ */
+import { decodeUsageTolerantly, notConfiguredSentences, RawUsage, reasonSentences, usageReadingOf, usageResponseMaxBytes, usageUnavailable } from "@knpkv/herdr-connect";
+import { Clock, Duration, Effect, Result, Schema, Scope, Semaphore, SynchronizedRef } from "effect";
+import { reportFailure } from "./failure.js";
+import { runCommand, staleWhileRevalidate } from "./limits.js";
+// A 30-day read scans a month of the store; give it longer than limits' 10 seconds.
+export const hostUsageTimeout = "20 seconds";
+/** How long a read is served before it is refreshed in the background: usage is history, not a live gauge. */
+export const hostUsageTtl = Duration.minutes(5);
+/** At most this many range and zone pairs are cached; the oldest is dropped for a new one. */
+export const hostUsageCacheEntries = 16;
+const decodeRawUsage = Schema.decodeUnknownResult(Schema.fromJsonString(RawUsage));
+/** The `agent-usage usage` command for a configured limits command, or undefined when it has none. */
+export const usageCommandFor = (limitsCommand) => {
+    const executable = limitsCommand?.[0];
+    if (limitsCommand === undefined || executable === undefined || limitsCommand.length < 2)
+        return undefined;
+    if (limitsCommand.at(-1) !== "limits")
+        return undefined;
+    return [executable, ...limitsCommand.slice(1, -1), "usage"];
+};
+const readReading = (limitsCommand, query) => {
+    const command = usageCommandFor(limitsCommand);
+    if (command === undefined) {
+        return Effect.succeed(usageUnavailable("not_configured", limitsCommand === undefined ? notConfiguredSentences.noCommand : notConfiguredSentences.noUsage));
+    }
+    return runCommand([...command, "--range", query.range, "--time-zone", query.timeZone], usageResponseMaxBytes).pipe(Effect.timeoutOrElse({ duration: hostUsageTimeout, orElse: () => Effect.succeed(null) }), Effect.map((stdout) => {
+        if (stdout === null)
+            return usageUnavailable("timeout", reasonSentences.timeout);
+        const json = decodeRawUsage(stdout.trim());
+        if (Result.isFailure(json)) {
+            return usageUnavailable("invalid_output", reasonSentences.invalid_output);
+        }
+        return usageReadingOf(decodeUsageTolerantly(json.success));
+    }), 
+    // agent-usage's own sentence can name host paths: it is logged here, and a fixed sentence leaves.
+    Effect.catchTag("CommandFailed", (failure) => Effect.map(reportFailure("Usage tab", failure), (sentence) => usageUnavailable("failed", sentence))));
+};
+/**
+ * Runs the usage command once for `query` and reports what it said. Never fails: no command, a
+ * crash, a timeout, a newer format or output that is not agent-usage's each become `Unavailable`
+ * with its own reason.
+ */
+export const readHostUsage = Effect.fn("HostUsage.read")(function* (host, limitsCommand, query) {
+    const reading = yield* readReading(limitsCommand, query);
+    return { host, readAt: yield* Clock.currentTimeMillis, reading };
+});
+/** At most this many agent-usage reads run at once across every range and zone. */
+export const hostUsageConcurrentReads = 2;
+/**
+ * One {@link staleWhileRevalidate} per range and zone, at most {@link hostUsageCacheEntries} of
+ * them: a new pair beyond that drops the least recently asked one. Finding or creating a pair's
+ * entry is atomic, so concurrent first asks share one read; and at most
+ * {@link hostUsageConcurrentReads} reads run at once, so a burst of new pairs queues rather than
+ * starting a command each. Refreshes live in `scope`.
+ */
+export const usageCache = Effect.fn("HostUsage.cache")(function* (read, ttl = hostUsageTtl, entries = hostUsageCacheEntries) {
+    const scope = yield* Effect.scope;
+    const reads = yield* Semaphore.make(hostUsageConcurrentReads);
+    const caches = yield* SynchronizedRef.make(new Map());
+    const entryFor = (query) => SynchronizedRef.modifyEffect(caches, (current) => Effect.gen(function* () {
+        const key = `${query.range} ${query.timeZone}`;
+        const next = new Map(current);
+        const known = next.get(key);
+        // Re-inserted on every ask, so the Map's order is least recently asked first.
+        next.delete(key);
+        const cache = known ?? (yield* staleWhileRevalidate(reads.withPermits(1)(read(query)), ttl).pipe(Effect.provideService(Scope.Scope, scope)));
+        next.set(key, cache);
+        while (next.size > entries) {
+            const oldest = next.keys().next().value;
+            if (oldest === undefined)
+                break;
+            next.delete(oldest);
+        }
+        const updated = [
+            cache,
+            next
+        ];
+        return updated;
+    }));
+    return (query) => Effect.flatMap(entryFor(query), (cache) => cache.read);
+});
+//# sourceMappingURL=usage.js.map

package/dist/host/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/host/usage.ts"],"names":[],"mappings":"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"}

package/dist/host.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@knpkv/herdr-usage/host` — this machine's agent-usage readings: `readHostLimits` and `readHostUsage` run the
+ * configured `agent-usage` command, bounded and cached, and say why in plain sentences when it can't answer.
+ * hostd serves them to the hub as each peer's `/v1/connect/{limits,usage}/local`; the standalone Usage app
+ * reads them directly.
+ *
+ * @module
+ */
+export { CommandFailed, failureSentence, reportFailure } from "./host/failure.js";
+export { hostLimitsOutputMaxBytes, hostLimitsTimeout, readHostLimits, runCommand, type StaleWhileRevalidate, staleWhileRevalidate } from "./host/limits.js";
+export { hostUsageCacheEntries, hostUsageConcurrentReads, hostUsageTimeout, hostUsageTtl, readHostUsage, usageCache, usageCommandFor } from "./host/usage.js";
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjF,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,KAAK,oBAAoB,EACzB,oBAAoB,EACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EAChB,MAAM,iBAAiB,CAAA"}

package/dist/host.js

@@ -0,0 +1,12 @@
+/**
+ * `@knpkv/herdr-usage/host` — this machine's agent-usage readings: `readHostLimits` and `readHostUsage` run the
+ * configured `agent-usage` command, bounded and cached, and say why in plain sentences when it can't answer.
+ * hostd serves them to the hub as each peer's `/v1/connect/{limits,usage}/local`; the standalone Usage app
+ * reads them directly.
+ *
+ * @module
+ */
+export { CommandFailed, failureSentence, reportFailure } from "./host/failure.js";
+export { hostLimitsOutputMaxBytes, hostLimitsTimeout, readHostLimits, runCommand, staleWhileRevalidate } from "./host/limits.js";
+export { hostUsageCacheEntries, hostUsageConcurrentReads, hostUsageTimeout, hostUsageTtl, readHostUsage, usageCache, usageCommandFor } from "./host/usage.js";
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjF,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,UAAU,EAEV,oBAAoB,EACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EAChB,MAAM,iBAAiB,CAAA"}

package/dist/options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `herdr-usage` executable's options, read from its environment. `HERDR_USAGE_LIMITS_COMMAND` (a JSON array)
+ * overrides the agent-usage command a standalone run reads this machine with. Unset, it is the installed
+ * `@knpkv/agent-usage` run by the same node: no PATH lookup and no `.cmd` shim, which Windows can't spawn without a
+ * shell. Set but malformed, it is refused rather than quietly replaced by the default.
+ *
+ * @module
+ */
+import { Result, Schema } from "effect";
+import type { UsageAppOptions } from "./app.js";
+declare const UsageLimitsCommandInvalid_base: Schema.Class<UsageLimitsCommandInvalid, Schema.TaggedStruct<"UsageLimitsCommandInvalid", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** `HERDR_USAGE_LIMITS_COMMAND` is set but isn't a non-empty JSON array of strings. */
+export declare class UsageLimitsCommandInvalid extends UsageLimitsCommandInvalid_base {
+}
+/** Where the default command comes from: the running node and a module resolver next to this package. */
+export interface UsageRuntime {
+    readonly execPath: string;
+    readonly resolve: (specifier: string) => string;
+}
+export declare const readUsageOptions: (env: Readonly<Record<string, string | undefined>>, runtime: UsageRuntime) => Result.Result<UsageAppOptions, UsageLimitsCommandInvalid>;
+export {};
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;;;;AAE/C,uFAAuF;AACvF,qBAAa,yBAA0B,SAAQ,8BAG9C;CAAG;AAEJ,yGAAyG;AACzG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;CAChD;AAID,eAAO,MAAM,gBAAgB,QACtB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,WACxC,YAAY,KACpB,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,yBAAyB,CAc1D,CAAA"}