spawnfile 0.1.14 → 0.1.18

package/dist/runtime/openclaw/adapter.js

@@ -1,5 +1,5 @@
 import { listEffectiveExecutionModelTargets } from "../../compiler/modelEnv.js";
-import { createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles } from "../common.js";
+import { createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles, WORKSPACE_SKILL_BASE_DIRECTORY } from "../common.js";
 import { SpawnfileError } from "../../shared/index.js";
 import { applyOpenClawImportAuthConfig, resolveOpenClawImportAuthModes } from "./configAuth.js";
 import { prepareOpenClawRuntimeAuth } from "./runAuth.js";
@@ -137,6 +137,9 @@ const createContainerTargets = async (inputs) => inputs.map((input) => {
 });
 export const openClawAdapter = {
     assertSupportedModelTarget(target) {
+        if (target.reasoningEffort !== undefined) {
+            throw new SpawnfileError("validation_error", "OpenClaw runtime does not support reasoning_effort; only Daimon Codex and Grok engines support it");
+        }
         if (target.endpoint) {
             if (target.auth.method === "claude-code" || target.auth.method === "codex") {
                 throw new SpawnfileError("validation_error", `OpenClaw custom or local models do not support ${target.auth.method} auth`);
@@ -219,7 +222,7 @@ export const openClawAdapter = {
             ],
             files: [
                 ...createDocumentFiles("workspace", node.docs),
-                ...createSkillFiles("workspace/skills", node.skills),
+                ...createSkillFiles(WORKSPACE_SKILL_BASE_DIRECTORY, node.skills),
                 ...createOpenClawStateFiles(),
                 ...(cronStoreFile ? [cronStoreFile] : []),
                 {

package/dist/runtime/pi/adapter.d.ts

@@ -1,4 +1,3 @@
 import type { RuntimeAdapter } from "../types.js";
 export declare const piAdapter: RuntimeAdapter;
-export declare const daimonAdapter: RuntimeAdapter;
 export declare const PI_RUNTIME_PACKAGE = "@earendil-works/pi-coding-agent@0.79.10";

package/dist/runtime/pi/adapter.js

@@ -1,6 +1,6 @@
 import { readUtf8File, resolveProjectPath } from "../../filesystem/index.js";
 import { SpawnfileError } from "../../shared/index.js";
-import { createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles } from "../common.js";
+import { CLI_ENGINE_SKILL_BASE_DIRECTORIES, createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles } from "../common.js";
 import { resolveScriptedEngineCommandOption, resolveScriptedEngineStagedPath } from "./appScriptedEngine.js";
 import { isPiEveryScheduleValue, PI_BUILTIN_TOOLS, PI_ENGINE_KINDS, PI_PACKAGE_NAME, PI_PACKAGE_VERSION, PI_THINKING_FORMATS, PI_THINKING_LEVELS } from "./appTemplate.js";
 import { createPiContainerTargets, PI_CONFIG_FILE, PI_CONTROL_PORT, } from "./containerTargets.js";
@@ -85,6 +85,9 @@ const assertSupportedPiSurfaces = (surfaces) => {
 };
 export const piAdapter = {
     assertSupportedModelTarget(target) {
+        if (target.reasoningEffort !== undefined) {
+            throw new SpawnfileError("validation_error", "Pi runtime does not support reasoning_effort; only Daimon Codex and Grok engines support it");
+        }
         if (target.endpoint) {
             if (target.provider !== "custom" && target.provider !== "local") {
                 throw new SpawnfileError("validation_error", "Pi runtime only supports endpoints on custom or local model providers");
@@ -166,7 +169,7 @@ export const piAdapter = {
             ],
             files: [
                 ...createDocumentFiles("workspace", node.docs),
-                ...createSkillFiles("workspace/skills", node.skills),
+                ...createSkillFiles(CLI_ENGINE_SKILL_BASE_DIRECTORIES, node.skills),
                 ...(await createScriptedEngineFiles(node))
             ]
         };
@@ -224,8 +227,4 @@ export const piAdapter = {
         return diagnostics;
     }
 };
-export const daimonAdapter = {
-    ...piAdapter,
-    name: "daimon"
-};
 export const PI_RUNTIME_PACKAGE = `${PI_PACKAGE_NAME}@${PI_PACKAGE_VERSION}`;

package/dist/runtime/pi/appCliSource.js

@@ -189,7 +189,7 @@ const buildCliMemoryRequest = (event) => {
 };
 
 const createCliEnginePrompt = (config, paths, event, memoryPromptText) => [
-  createIdentityPrompt(config, paths.workspacePath),
+  createAgentInstructions(config, paths.workspacePath),
   "",
   memoryPromptText ?? formatCliWakePrompt(event),
   "",

package/dist/runtime/pi/appScheduleSource.js

@@ -46,8 +46,12 @@ export const installAgentSchedules = async (agents, timers, runOnce, clock = sys
   for (const agent of agents) {
     if (agent.config.schedule?.kind === "every" && agent.config.schedule.every) {
       const intervalMs = parseEveryMs(agent.config.schedule.every);
+      // Wake ids become mneme's wake_event_id, which must match the causal-id
+      // namespace /^(simfile|moltnet|mneme|daimon):.+$/. These wakes are
+      // delivered by the daimon runtime harness (as moltnet wakes carry a
+      // moltnet: id), so they carry the daimon: authority prefix.
       const createEvent = () => ({
-        id: "schedule-" + agent.config.id + "-" + clock.now(),
+        id: "daimon:schedule-" + agent.config.id + "-" + clock.now(),
         kind: "schedule",
         from: "scheduler",
         text: agent.config.schedule.prompt ?? "Run the scheduled Spawnfile task."
@@ -63,7 +67,7 @@ export const installAgentSchedules = async (agents, timers, runOnce, clock = sys
       const dreamEnvironments = await agent.listDreamEnvironmentKeys();
       for (const dreamEnvironment of dreamEnvironments) {
         const createEvent = () => ({
-          id: "dream-" + agent.config.id + "-" + bankId + "-" + dreamEnvironment + "-" + clock.now(),
+          id: "daimon:dream-" + agent.config.id + "-" + bankId + "-" + dreamEnvironment + "-" + clock.now(),
           kind: "dream",
           from: "mneme",
           dream_environment: dreamEnvironment,

package/dist/runtime/pi/appTemplateTypes.d.ts

@@ -20,7 +20,7 @@ export interface PiGeneratedAgent {
     id: string;
     instructions: string;
     model: {
-        auth_method: "api_key" | "claude-code" | "codex" | "none" | "unknown";
+        auth_method: "api_key" | "claude-code" | "codex" | "grok" | "none" | "unknown";
         name: string;
         provider: string;
     };

package/dist/runtime/pi/containerTargets.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { CLI_ENGINE_SKILL_BASE_DIRECTORIES } from "../common.js";
 import { listExecutionModelSecretNames } from "../../compiler/modelEnv.js";
 import { renderPiScheduleSource } from "./appScheduleSource.js";
 import { createPiAgentConfig, renderPiApp, renderPiAppConfig, renderPiModelsConfig, renderPiPackageJson, resolvePiEngine, } from "./appTemplate.js";
@@ -29,6 +30,11 @@ export const createPiContainerTargets = async (inputs) => {
         relativePath: `secrets/${secretName}`,
     }));
     return [{
+            agentPathsByNodeId: Object.fromEntries(agentInputs.map((input) => [input.id, {
+                    workspacePath: `<instance-root>/workspace/agents/${input.slug}`,
+                    homePath: `<instance-root>/runtime/agents/${input.slug}`,
+                    skillRoots: CLI_ENGINE_SKILL_BASE_DIRECTORIES.map((root) => `<instance-root>/workspace/agents/${input.slug}/${path.posix.relative("workspace", root)}`)
+                }])),
             engineByNodeId,
             envFiles,
             files: [

package/dist/runtime/picoclaw/adapter.js

@@ -1,6 +1,6 @@
 import { listEffectiveExecutionModelTargets, listExecutionModelSecretNames, resolveModelProviderEnvName } from "../../compiler/modelEnv.js";
 import { SpawnfileError } from "../../shared/index.js";
-import { createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles } from "../common.js";
+import { createAgentCapabilities, createDiagnostic, createDocumentFiles, createSkillFiles, WORKSPACE_SKILL_BASE_DIRECTORY } from "../common.js";
 import { preparePicoClawRuntimeAuth } from "./runAuth.js";
 import { createPicoClawAgentScaffold } from "./scaffold.js";
 import { createPicoClawCronStoreFile, createScheduleDiagnostics, hasPicoClawCronJobs, scheduleOutcomeFor } from "./schedules.js";
@@ -152,6 +152,9 @@ const createContainerTargets = async (inputs) => inputs.map((input) => {
 });
 export const picoClawAdapter = {
     assertSupportedModelTarget(target) {
+        if (target.reasoningEffort !== undefined) {
+            throw new SpawnfileError("validation_error", "PicoClaw runtime does not support reasoning_effort; only Daimon Codex and Grok engines support it");
+        }
         if (target.endpoint) {
             if (target.endpoint.compatibility === "anthropic" &&
                 target.auth.method === "none") {
@@ -220,7 +223,7 @@ export const picoClawAdapter = {
             diagnostics: createScheduleDiagnostics(node),
             files: [
                 ...createDocumentFiles("workspace", node.docs),
-                ...createSkillFiles("workspace/skills", node.skills),
+                ...createSkillFiles(WORKSPACE_SKILL_BASE_DIRECTORY, node.skills),
                 ...(cronStoreFile ? [cronStoreFile] : []),
                 {
                     content: buildPicoClawConfig(node),

package/dist/runtime/registry.d.ts

@@ -2,6 +2,11 @@ import type { DiagnosticReport } from "../report/index.js";
 import type { RuntimeLifecycleStatus } from "../shared/index.js";
 import type { RuntimeAdapter } from "./types.js";
 export type RuntimeRegistryInstall = {
+    capabilityReceipt?: string;
+    /** Per-architecture receipts embedded in a multi-architecture image index. */
+    capabilityReceipts?: DaimonCapabilityReceipts;
+    contractManifestSha256?: string;
+    digest?: string;
     image: string;
     kind: "container_image";
     tag: string;
@@ -18,6 +23,7 @@ export type RuntimeRegistryInstall = {
 } | {
     kind: "source_repo";
 };
+export type DaimonCapabilityReceipts = Partial<Record<"amd64" | "arm64", string>>;
 export interface RuntimeRegistryEntry {
     defaultBranch: string;
     install?: RuntimeRegistryInstall;

package/dist/runtime/registry.js

@@ -3,7 +3,8 @@ import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import { SpawnfileError } from "../shared/index.js";
 import { openClawAdapter } from "./openclaw/adapter.js";
-import { daimonAdapter, piAdapter } from "./pi/adapter.js";
+import { daimonAdapter } from "./daimon/adapter.js";
+import { piAdapter } from "./pi/adapter.js";
 import { picoClawAdapter } from "./picoclaw/adapter.js";
 const runtimeAdapters = new Map([
     [daimonAdapter.name, daimonAdapter],
@@ -14,11 +15,23 @@ const runtimeAdapters = new Map([
 const runtimeInstallSchema = z.discriminatedUnion("kind", [
     z
         .object({
+        capability_receipt: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+        capability_receipts: z
+            .object({
+            amd64: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+            arm64: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional()
+        })
+            .strict()
+            .refine((receipts) => Object.keys(receipts).length > 0, "capability_receipts must pin at least one architecture")
+            .optional(),
+        contract_manifest_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+        digest: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
         image: z.string().min(1),
         kind: z.literal("container_image"),
         tag: z.string().min(1)
     })
-        .strict(),
+        .strict()
+        .refine((install) => !(install.capability_receipt && install.capability_receipts), "capability_receipt and capability_receipts are mutually exclusive"),
     z
         .object({
         kind: z.literal("npm"),
@@ -62,7 +75,23 @@ export const parseRuntimeRegistry = (source) => {
         return Object.entries(parsed.runtimes)
             .map(([name, entry]) => ({
             defaultBranch: entry.default_branch,
-            install: entry.install,
+            install: entry.install?.kind === "container_image"
+                ? {
+                    ...(entry.install.capability_receipt
+                        ? { capabilityReceipt: entry.install.capability_receipt }
+                        : {}),
+                    ...(entry.install.capability_receipts
+                        ? { capabilityReceipts: { ...entry.install.capability_receipts } }
+                        : {}),
+                    ...(entry.install.contract_manifest_sha256
+                        ? { contractManifestSha256: entry.install.contract_manifest_sha256 }
+                        : {}),
+                    ...(entry.install.digest ? { digest: entry.install.digest } : {}),
+                    image: entry.install.image,
+                    kind: entry.install.kind,
+                    tag: entry.install.tag
+                }
+                : entry.install,
             name,
             ref: entry.ref,
             remote: entry.remote,

package/dist/runtime/scheduleUtils.d.ts

@@ -1,2 +1,3 @@
 export declare const isEveryScheduleValue: (value: string) => boolean;
+export declare const MAX_SCHEDULE_INTERVAL_MS = 31536000000;
 export declare const parseEveryScheduleMs: (value: string) => number | null;

package/dist/runtime/scheduleUtils.js

@@ -1,4 +1,5 @@
 export const isEveryScheduleValue = (value) => /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/u.test(value.trim());
+export const MAX_SCHEDULE_INTERVAL_MS = 31_536_000_000;
 export const parseEveryScheduleMs = (value) => {
     const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/u.exec(value.trim());
     if (!match) {
@@ -11,5 +12,8 @@ export const parseEveryScheduleMs = (value) => {
         ms: 1,
         s: 1000
     };
-    return Math.max(1, Math.round(Number(match[1]) * multipliers[match[2] ?? "ms"]));
+    const milliseconds = Math.round(Number(match[1]) * multipliers[match[2] ?? "ms"]);
+    return Number.isSafeInteger(milliseconds) && milliseconds >= 1 && milliseconds <= MAX_SCHEDULE_INTERVAL_MS
+        ? milliseconds
+        : null;
 };

package/dist/runtime/types.d.ts

@@ -27,8 +27,21 @@ export interface ContainerTargetEnvFile {
     envName: string;
     relativePath: string;
 }
+export interface ContainerTargetPersistentMount {
+    id: string;
+    lifecycle?: "exclusive-reattach";
+    mountPath: string;
+    reason: string;
+}
 export type RuntimeContainerConfigValueTransform = "bearer";
+export interface ContainerTargetAgentPaths {
+    workspacePath: string;
+    homePath: string | null;
+    skillRoots: string[];
+}
 export interface ContainerTarget {
+    /** Adapter-owned paths, using the same placeholders as emitted configuration. */
+    agentPathsByNodeId?: Record<string, ContainerTargetAgentPaths>;
     configEnvBindings?: RuntimeContainerConfigEnvBinding[];
     /**
      * Optional node id -> resolved engine kind map (currently only populated by
@@ -40,8 +53,21 @@ export interface ContainerTarget {
      */
     engineByNodeId?: Record<string, string>;
     envFiles?: ContainerTargetEnvFile[];
+    /** Daimon only: each brokered Grok agent's declared model and reasoning effort, which select its pinned worker config. */
+    grokModelByNodeId?: Record<string, {
+        model: string;
+        reasoningEffort: string;
+    }>;
+    /** Daimon only: each brokered Grok agent's declared per-turn budget, for its broker registration. */
+    grokTurnLimitsByNodeId?: Record<string, {
+        maxRequests?: number;
+        maxTokens?: number;
+        timeoutMs?: number;
+    }>;
     files: EmittedFile[];
     id: string;
+    opaqueMountTargets?: string[];
+    persistentMounts?: ContainerTargetPersistentMount[];
     sourceIds?: string[];
     /** World token env names actually lowered into this target's native config. */
     worldTokenEnvNames?: string[];
@@ -104,6 +130,14 @@ export interface RuntimeAuthPreparationInput {
      * `null` — only the profile-derived `imports` lookups are unavailable.
      */
     authProfile: ResolvedAuthProfile | null;
+    /**
+     * The uid the deployed container reads bind-mounted credential files as.
+     * Credential mounts carry their host owner through unchanged, so an adapter
+     * whose runtime validates a credential's owner in-container must refuse a
+     * mismatch here rather than at readiness. Omitted means "the uid the runtime
+     * is compiled to run as", which is what every real deployment uses.
+     */
+    containerCredentialUid?: number;
     env: Record<string, string>;
     instance: RuntimeAuthInstance;
     outputDirectory: string;
@@ -111,6 +145,10 @@ export interface RuntimeAuthPreparationInput {
 }
 export interface RuntimeAuthPreparationResult {
     coveredModelSecrets: string[];
+    launchIdentity?: {
+        kind: "daimon";
+        uid: number;
+    };
     mountArgs: string[];
 }
 export interface RuntimeProbeExecResult {
@@ -166,6 +204,8 @@ export interface RuntimeAdapter {
     compileTeam?(node: ResolvedTeamNode): Promise<AdapterCompileResult>;
     createContainerTargets?(inputs: ContainerTargetInput[]): Promise<ContainerTarget[]>;
     name: string;
+    /** Throws a SpawnfileError for what compile would refuse for this agent; run by `spawnfile validate`. */
+    preflightAgent?(node: ResolvedAgentNode, nodeId: string): void;
     prepareRuntimeAuth?(input: RuntimeAuthPreparationInput): Promise<RuntimeAuthPreparationResult>;
     scaffoldAgentProject?(): RuntimeAgentScaffold;
     statusProbes?: RuntimeStatusProbe[];

package/dist/runtime/usageLedger.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Pure reader/aggregator for Daimon's per-turn usage ledger
+ * (`noopolis.daimon.turn-usage.v1`, see `specs/USAGE_ACCOUNTING_DESIGN.md`). This
+ * module never touches Docker, the filesystem, or a deployment record — it
+ * only knows how to parse ledger text and window/group already-parsed
+ * records. The transport (deciding whether to `docker exec` or fall back to
+ * volume egress, and where the ledger actually lives) is a CLI-layer concern
+ * in `src/cli/usageCommandLive.ts`, which composes this module with
+ * `src/deployment`'s docker probe gateway and volume-egress helpers. Keeping
+ * that composition out of this folder avoids a value-level import cycle:
+ * `src/deployment` already imports real (non-type) exports from this folder
+ * (`dockerManager.ts`'s `resolveNoopolisRunId`), so this folder must not
+ * import real exports back from `src/deployment`.
+ *
+ * The read transport itself (`readUsageLedgerViaExec`, and the rule for when
+ * a failed `cat` means "empty" versus "unknown") lives beside this file in
+ * `usageLedgerRead.ts`, so this module performs no I/O at all.
+ */
+export declare const USAGE_TURN_RECORD_VERSION: "noopolis.daimon.turn-usage.v1";
+/** One parsed, validated line from the usage ledger. */
+export interface UsageRecord {
+    agent: string;
+    at: string;
+    cache_read: number;
+    cache_write: number;
+    calls: number;
+    complete: boolean;
+    engine: string;
+    input: number;
+    notional_usd: number;
+    output: number;
+    total: number;
+    v: typeof USAGE_TURN_RECORD_VERSION;
+    wake: string;
+    /** Broker rows: the sha256 turn id every reader dedupes on (a replay may re-append a sealed row). */
+    turn?: string;
+    /** Broker rows: which per-turn limit ended the turn (`none` when none did). */
+    limit_reason?: UsageLimitReason;
+    /** Broker rows: the declared model the broker verified the turn ran. */
+    model?: string;
+    /** Broker rows: requests charged a conservative estimate because the provider response carried no valid usage. */
+    estimated_requests?: number;
+    outcome?: "completed" | "failed";
+}
+export declare const USAGE_LIMIT_REASONS: readonly ["tokens", "requests", "timeout", "none"];
+export type UsageLimitReason = typeof USAGE_LIMIT_REASONS[number];
+/**
+ * Keeps the first row of every `turn` and every row without one.
+ *
+ * Daimon's broker seals a turn's ledger bytes into the turn record and appends
+ * them again on replay when it cannot see the row, so two replays of one sealed
+ * turn can both append identical bytes. The key exists precisely so such a turn
+ * is never counted twice; every aggregate here must see deduplicated rows.
+ * Readers keep every parsed row so {@link findConflictingUsageTurns} can see
+ * rows that share a key but differ.
+ */
+export declare const dedupeUsageRecordsByTurn: (records: UsageRecord[]) => UsageRecord[];
+/**
+ * `turn` keys whose rows are not byte-for-byte the same record. A replay
+ * re-appends identical sealed bytes, so differing rows under one key mean the
+ * ledger is not what the broker sealed; the first row is still the one counted,
+ * but the window is reported PARTIAL and the keys are named.
+ */
+export declare const findConflictingUsageTurns: (records: UsageRecord[]) => string[];
+/**
+ * Parses one ledger line. Returns `null` (never throws) for: blank lines,
+ * JSON that fails to parse (this is also how a torn trailing line left by a
+ * crash mid-append is skipped — a truncated JSON object fails to parse the
+ * same way a garbled line would), a schema version other than
+ * `noopolis.daimon.turn-usage.v1`, a missing/empty string field, an `at` that
+ * doesn't parse as a date, a non-boolean `complete`, or any numeric field
+ * that isn't a finite, non-negative number.
+ */
+export declare const parseUsageLedgerLine: (line: string) => UsageRecord | null;
+/**
+ * Parses a newline-delimited ledger file. Never throws: an unparseable line —
+ * including an unterminated trailing line left by a crash mid-append — is
+ * skipped, and the rest of the file still parses.
+ */
+export declare const parseUsageLedger: (text: string) => UsageRecord[];
+/** The default window `spawnfile usage` uses when `--since` is omitted. */
+export declare const DEFAULT_USAGE_SINCE = "24h";
+/** Parses a duration like `"24h"`, `"7d"`, or `"30m"` into milliseconds.
+ * Returns `null` for anything else — the caller is responsible for turning
+ * that into a user-facing input error. */
+export declare const parseUsageSinceDuration: (input: string) => number | null;
+/** Keeps only records at or after `now - sinceMs`. `now` defaults to the real
+ * clock; tests pass a fixed value. */
+export declare const filterUsageRecordsSince: (records: UsageRecord[], sinceMs: number, now?: number) => UsageRecord[];
+/** A roster entry: one agent the org compiled, and the engine it was
+ * assigned — independent of whether it ever produced a usage record (a
+ * Codex-engine agent is uninstrumented and will never appear in the ledger,
+ * but still belongs in the roster so coverage/grouping can show it with
+ * zeroes rather than silently omitting it). */
+export interface UsageRosterEntry {
+    agent: string;
+    /** `null` when the roster source cannot name the agent's engine — a
+     * deployment record lists agents but not engine assignment, so the engine is
+     * learned from the agent's own ledger records and stays `null` for an agent
+     * that never reports. */
+    engine: string | null;
+}
+export interface UsageAgentGroup {
+    agent: string;
+    engine: string | null;
+    /** Requests charged an estimate (no provider-reported usage); their tokens are a conservative charge, not a measurement. */
+    estimatedRequests: number;
+    estimatedTurns: number;
+    incompleteTurns: number;
+    notionalUsd: number;
+    tokens: number;
+    turns: number;
+}
+/** Groups records by agent. `roster`, when supplied, seeds a zero-usage row
+ * for every known agent (so an uninstrumented engine's agents still show up
+ * with dashes instead of vanishing from the table). */
+export declare const groupUsageByAgent: (records: UsageRecord[], roster?: UsageRosterEntry[]) => UsageAgentGroup[];
+export interface UsageEngineGroup {
+    engine: string;
+    estimatedRequests: number;
+    estimatedTurns: number;
+    incompleteTurns: number;
+    notionalUsd: number;
+    tokens: number;
+    turns: number;
+}
+/** Groups records by engine. `engines`, when supplied, seeds a zero-usage row
+ * for every known engine (so Codex — uninstrumented — shows up as a dashed
+ * row rather than being absent from the rollup). */
+export declare const groupUsageByEngine: (records: UsageRecord[], engines?: string[]) => UsageEngineGroup[];
+export interface UsageCoverage {
+    agentsReporting: number;
+    agentsTotal: number;
+    /** `turn` keys carrying differing rows (first row counted); nonzero forces `partial`. */
+    conflictingTurnCount: number;
+    /** Turns whose total includes an estimated charge for at least one request. */
+    estimatedTurnCount: number;
+    /** Count of `complete:false` records in the window — every count here is a
+     * lower bound regardless of this number (see module doc / design
+     * "Verification" — grok's `streaming-messages-json` carries no
+     * completeness marker for a partially zero-filled turn), but a nonzero
+     * count is at least a partial, observable signal of it. */
+    incompleteRecordCount: number;
+    /** True when at least one roster agent produced zero records in the
+     * window, or when at least one ledger could not be read — the resulting
+     * total must be labelled PARTIAL and never presented as the org's full
+     * cost. */
+    partial: boolean;
+    /** Ledgers (units or rotated generations) whose read failed outright. Zero
+     * records from an unreadable ledger is UNKNOWN usage, not free usage, so a
+     * nonzero count here forces `partial` regardless of the roster. */
+    unreadableUnitCount: number;
+}
+/** Coverage is computed against `totalAgents` (the full org roster size), not
+ * against however many distinct agents happen to appear in `records` — an
+ * uninstrumented engine's agents must count toward the shortfall, not
+ * disappear from the denominator. */
+export declare const computeUsageCoverage: (records: UsageRecord[], totalAgents: number, unreadableUnitCount?: number) => UsageCoverage;