spawnfile 0.1.13 → 0.1.17

package/dist/runtime/picoclaw/adapter.js

@@ -1,12 +1,14 @@
 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, scheduleOutcomeFor } from "./schedules.js";
+import { createPicoClawCronStoreFile, createScheduleDiagnostics, hasPicoClawCronJobs, scheduleOutcomeFor } from "./schedules.js";
 import { assertSupportedPicoClawSurfaces, buildPicoClawChannelConfig, buildPicoClawSurfaceEnvBindings } from "./surfaces.js";
 import { PICOCLAW_GATEWAY_BASE_PORT, PICOCLAW_INTERNAL_PICO_TOKEN } from "./pico.js";
 import { picoClawStatusProbes } from "./statusProbes.js";
+import { buildPicoClawMemoryMcpServers, picoClawMemoryCapabilityFor, PICOCLAW_MNEME_PACKAGE } from "./memory.js";
+import { buildPicoClawAuthoredMcpServers, buildPicoClawMcpEnvBindings } from "./mcp.js";
 const formatModelName = (node) => {
     const primary = node.execution?.model?.primary;
     if (!primary)
@@ -75,31 +77,9 @@ const buildModelList = (node) => {
         };
     });
 };
-const buildMcpServers = (servers) => {
-    const result = {};
-    for (const server of servers) {
-        const entry = { enabled: true };
-        if (server.transport === "stdio") {
-            entry.command = server.command;
-            if (server.args)
-                entry.args = server.args;
-            if (server.env)
-                entry.env = server.env;
-        }
-        else {
-            entry.type = server.transport === "streamable_http" ? "http" : server.transport;
-            entry.url = server.url;
-        }
-        if (server.auth) {
-            entry.headers = { [server.auth.secret]: "" };
-        }
-        result[server.name] = entry;
-    }
-    return result;
-};
 const buildPicoClawToolsConfig = (node) => {
     const tools = {};
-    if (node.schedule?.kind === "cron") {
+    if (hasPicoClawCronJobs(node)) {
         tools.cron = {
             enabled: true
         };
@@ -112,7 +92,17 @@ const buildPicoClawToolsConfig = (node) => {
     if (node.mcpServers.length > 0) {
         tools.mcp = {
             enabled: true,
-            servers: buildMcpServers(node.mcpServers)
+            servers: buildPicoClawAuthoredMcpServers(node.mcpServers)
+        };
+    }
+    const memoryMcpServers = buildPicoClawMemoryMcpServers(node);
+    if (Object.keys(memoryMcpServers).length > 0) {
+        tools.mcp = {
+            enabled: true,
+            servers: {
+                ...(tools.mcp?.servers ?? {}),
+                ...memoryMcpServers
+            }
         };
     }
     return Object.keys(tools).length > 0 ? tools : undefined;
@@ -148,7 +138,10 @@ const createContainerTargets = async (inputs) => inputs.map((input) => {
         envName: secretName,
         relativePath: createSecretPath(secretName)
     }));
-    const configEnvBindings = buildPicoClawSurfaceEnvBindings(agent.surfaces);
+    const configEnvBindings = [
+        ...(buildPicoClawSurfaceEnvBindings(agent.surfaces) ?? []),
+        ...buildPicoClawMcpEnvBindings(agent.mcpServers)
+    ];
     return {
         configEnvBindings,
         envFiles,
@@ -190,7 +183,7 @@ export const picoClawAdapter = {
     container: {
         configFileName: "config.json",
         configPathEnv: "PICOCLAW_CONFIG",
-        globalNpmPackages: ["@anthropic-ai/claude-code", "@openai/codex"],
+        globalNpmPackages: ["@anthropic-ai/claude-code", "@openai/codex", PICOCLAW_MNEME_PACKAGE],
         homeEnv: "PICOCLAW_HOME",
         instancePaths: {
             configPathTemplate: "<instance-root>/picoclaw/<config-file>",
@@ -216,15 +209,18 @@ export const picoClawAdapter = {
     async compileAgent(node) {
         const scheduleOutcome = scheduleOutcomeFor(node);
         const cronStoreFile = createPicoClawCronStoreFile(node);
+        const memoryCapability = picoClawMemoryCapabilityFor(node);
         return {
             capabilities: createAgentCapabilities(node, {
+                memoryMessage: memoryCapability.message,
+                memoryOutcome: memoryCapability.outcome,
                 scheduleMessage: scheduleOutcome.message,
                 scheduleOutcome: scheduleOutcome.outcome
             }),
             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/picoclaw/mcp.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "../../manifest/index.js";
+import type { RuntimeContainerConfigEnvBinding } from "../types.js";
+export declare const buildPicoClawAuthoredMcpServers: (servers: McpServer[]) => Record<string, Record<string, unknown>>;
+export declare const buildPicoClawMcpEnvBindings: (servers: McpServer[]) => RuntimeContainerConfigEnvBinding[];

package/dist/runtime/picoclaw/mcp.js

@@ -0,0 +1,43 @@
+export const buildPicoClawAuthoredMcpServers = (servers) => {
+    const result = Object.create(null);
+    for (const server of servers) {
+        if (server.transport === "stdio" && server.auth?.mode === "bearer") {
+            throw new Error("PicoClaw stdio MCP servers do not support bearer auth");
+        }
+        const entry = { enabled: true };
+        if (server.transport === "stdio") {
+            entry.command = server.command;
+            if (server.args)
+                entry.args = server.args;
+            if (server.env)
+                entry.env = server.env;
+        }
+        else {
+            entry.type = server.transport === "streamable_http" ? "http" : server.transport;
+            entry.url = server.url;
+        }
+        if (server.auth) {
+            entry.headers = {
+                [server.auth.mode === "bearer" ? "Authorization" : server.auth.secret]: ""
+            };
+        }
+        result[server.name] = entry;
+    }
+    return result;
+};
+export const buildPicoClawMcpEnvBindings = (servers) => servers.flatMap((server) => server.auth
+    ? [
+        {
+            envName: server.auth.secret,
+            jsonPath: [
+                "tools",
+                "mcp",
+                "servers",
+                server.name,
+                "headers",
+                server.auth.mode === "bearer" ? "Authorization" : server.auth.secret
+            ],
+            ...(server.auth.mode === "bearer" ? { transform: "bearer" } : {})
+        }
+    ]
+    : []);

package/dist/runtime/picoclaw/memory.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedAgentNode } from "../../compiler/types.js";
+export declare const buildPicoClawMemoryMcpServers: (node: ResolvedAgentNode) => Record<string, Record<string, unknown>>;
+export declare const picoClawMemoryCapabilityFor: (node: ResolvedAgentNode) => {
+    message: string;
+    outcome: "degraded" | "supported";
+};
+export declare const PICOCLAW_MNEME_PACKAGE = "@noopolis/mneme@0.1.1";

package/dist/runtime/picoclaw/memory.js

@@ -0,0 +1,17 @@
+import { buildMnemeMemoryMcpServers, hasScheduledMemoryConsolidation, hasUnsupportedMnemeMemoryAccess, MNEME_PACKAGE } from "../mnemeMcp.js";
+export const buildPicoClawMemoryMcpServers = (node) => buildMnemeMemoryMcpServers(node, {
+    modes: hasScheduledMemoryConsolidation(node) ? ["awake", "dream"] : ["awake"]
+});
+export const picoClawMemoryCapabilityFor = (node) => {
+    if (hasUnsupportedMnemeMemoryAccess(node)) {
+        return {
+            message: "PicoClaw lowers file-backed Mneme memory through generated MCP servers; non-file stores are not lowered",
+            outcome: "degraded"
+        };
+    }
+    return {
+        message: "PicoClaw accesses Mneme memory through generated MCP servers",
+        outcome: "supported"
+    };
+};
+export const PICOCLAW_MNEME_PACKAGE = MNEME_PACKAGE;

package/dist/runtime/picoclaw/runAuth.js

@@ -10,7 +10,7 @@ export const preparePicoClawRuntimeAuth = async (input) => {
     if (!input.instance.home_path) {
         return { coveredModelSecrets: [], mountArgs: [] };
     }
-    const claudeCode = input.authProfile.imports["claude-code"]
+    const claudeCode = input.authProfile?.imports["claude-code"]
         ? await loadImportedClaudeCodeCredential(input.authProfile.imports["claude-code"].path)
         : null;
     const useClaudeCode = input.instance.model_auth_methods.anthropic === "claude-code" && claudeCode;

package/dist/runtime/picoclaw/scaffold.js

@@ -11,7 +11,7 @@ export const createPicoClawAgentScaffold = () => ({
             path: "SOUL.md"
         },
         {
-            content: loadRuntimeScaffoldAsset(import.meta.url, "AGENTS.md"),
+            content: loadRuntimeScaffoldAsset(import.meta.url, "WORKSPACE_AGENTS.md"),
             path: "AGENTS.md"
         }
     ],

package/dist/runtime/picoclaw/schedules.d.ts

@@ -1,9 +1,35 @@
 import type { ResolvedAgentNode } from "../../compiler/types.js";
 import type { CapabilityReport } from "../../report/index.js";
 import type { EmittedFile } from "../types.js";
+type PicoClawCronSchedule = {
+    expr?: string;
+    kind: "cron";
+    tz?: string;
+} | {
+    everyMs: number;
+    kind: "every";
+};
+interface PicoClawCronJob {
+    createdAtMs: number;
+    deleteAfterRun: boolean;
+    enabled: boolean;
+    id: string;
+    name: string;
+    payload: {
+        deliver: boolean;
+        kind: "agent_turn";
+        message: string;
+    };
+    schedule: PicoClawCronSchedule;
+    state: Record<string, never>;
+    updatedAtMs: number;
+}
+export declare const createPicoClawCronJobs: (node: ResolvedAgentNode) => PicoClawCronJob[];
 export declare const createPicoClawCronStoreFile: (node: ResolvedAgentNode) => EmittedFile | null;
+export declare const hasPicoClawCronJobs: (node: ResolvedAgentNode) => boolean;
 export declare const scheduleOutcomeFor: (node: ResolvedAgentNode) => {
     message?: string;
     outcome?: CapabilityReport["outcome"];
 };
 export declare const createScheduleDiagnostics: (node: ResolvedAgentNode) => import("../../report/types.js").DiagnosticReport[];
+export {};

package/dist/runtime/picoclaw/schedules.js

@@ -1,4 +1,7 @@
+import { slugify } from "../../compiler/helpers.js";
 import { createDiagnostic } from "../common.js";
+import { isMnemeMemoryAccessSupported, mnemeMemoryServerName } from "../mnemeMcp.js";
+import { parseEveryScheduleMs } from "../scheduleUtils.js";
 const createPicoClawCronJob = (node) => {
     if (!node.schedule || node.schedule.kind !== "cron") {
         return null;
@@ -23,13 +26,68 @@ const createPicoClawCronJob = (node) => {
         updatedAtMs: 0
     };
 };
+const dreamPrompt = (bankId, serverName) => [
+    `Dream over Mneme memory bank ${bankId}.`,
+    "This is an isolated memory-maintenance session, not normal conversation.",
+    `Prefer the ${serverName} MCP tools when available.`,
+    "Search the active dream scope and read-only global scope for stale, duplicate, noisy, or important memories.",
+    "Use memory_summarize, memory_register, or memory_forget only when consolidation is evidence-backed."
+].join(" ");
+const scheduleFromMemoryConsolidation = (schedule) => {
+    const everyMs = parseEveryScheduleMs(schedule);
+    if (everyMs !== null) {
+        return { everyMs, kind: "every" };
+    }
+    return { expr: schedule, kind: "cron" };
+};
+const createPicoClawMemoryDreamJobs = (node) => {
+    const jobs = [];
+    const seen = new Set();
+    for (const access of node.memoryAccess ?? []) {
+        const schedule = access.bank.consolidation.schedule;
+        if (!isMnemeMemoryAccessSupported(access) ||
+            access.bank.consolidation.mode !== "scheduled" ||
+            !schedule) {
+            continue;
+        }
+        const key = `${access.source}:${access.bank.id}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const dreamServerName = mnemeMemoryServerName(node, access, "dream");
+        const bankSlug = dreamServerName.replace(/^mneme-/u, "").replace(/-dream$/u, "");
+        const agentSlug = slugify(node.name) || "agent";
+        const id = `spawnfile-dream-${agentSlug}-${bankSlug}`;
+        jobs.push({
+            createdAtMs: 0,
+            deleteAfterRun: false,
+            enabled: true,
+            id,
+            name: id,
+            payload: {
+                deliver: false,
+                kind: "agent_turn",
+                message: dreamPrompt(access.bank.id, dreamServerName)
+            },
+            schedule: scheduleFromMemoryConsolidation(schedule),
+            state: {},
+            updatedAtMs: 0
+        });
+    }
+    return jobs;
+};
+export const createPicoClawCronJobs = (node) => [
+    createPicoClawCronJob(node),
+    ...createPicoClawMemoryDreamJobs(node)
+].filter((job) => job !== null);
 export const createPicoClawCronStoreFile = (node) => {
-    const job = createPicoClawCronJob(node);
-    if (!job) {
+    const jobs = createPicoClawCronJobs(node);
+    if (jobs.length === 0) {
         return null;
     }
     const store = {
-        jobs: [job],
+        jobs,
         version: 1
     };
     return {
@@ -37,6 +95,7 @@ export const createPicoClawCronStoreFile = (node) => {
         path: "workspace/cron/jobs.json"
     };
 };
+export const hasPicoClawCronJobs = (node) => createPicoClawCronJobs(node).length > 0;
 export const scheduleOutcomeFor = (node) => {
     if (!node.schedule) {
         return {};

package/dist/runtime/registry.d.ts

@@ -2,6 +2,9 @@ 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;
+    contractManifestSha256?: string;
+    digest?: string;
     image: string;
     kind: "container_image";
     tag: string;

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,6 +15,9 @@ const runtimeAdapters = new Map([
 const runtimeInstallSchema = z.discriminatedUnion("kind", [
     z
         .object({
+        capability_receipt: z.string().regex(/^sha256:[a-f0-9]{64}$/).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)
@@ -62,7 +66,20 @@ 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.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

@@ -0,0 +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

@@ -0,0 +1,19 @@
+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) {
+        return null;
+    }
+    const multipliers = {
+        d: 24 * 60 * 60 * 1000,
+        h: 60 * 60 * 1000,
+        m: 60 * 1000,
+        ms: 1,
+        s: 1000
+    };
+    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

@@ -1,4 +1,5 @@
 import type { EffectiveModelTarget, ResolvedAgentNode, ResolvedAgentSurfaces, ResolvedTeamNode } from "../compiler/types.js";
+import type { SimfileWorldBindingV1 } from "../compiler/worldBindings.js";
 import type { ResolvedAuthProfile } from "../auth/index.js";
 import type { AgentManifest } from "../manifest/index.js";
 import type { CapabilityReport, DiagnosticReport } from "../report/index.js";
@@ -20,17 +21,43 @@ export interface ContainerTargetInput {
     kind: "agent" | "team";
     slug: string;
     value: ResolvedAgentNode | ResolvedTeamNode;
+    worldBinding?: SimfileWorldBindingV1;
 }
 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 ContainerTarget {
     configEnvBindings?: RuntimeContainerConfigEnvBinding[];
+    /**
+     * Optional node id -> resolved engine kind map (currently only populated by
+     * `src/runtime/pi/adapter.ts`'s `createContainerTargets`, e.g. `{"agent:
+     * eleanor": "scripted"}`). Threaded through `RuntimeTargetPlan` into
+     * `ContainerRuntimeInstanceReport.engine_by_node_id` for compile-report
+     * disclosure (Piece 5, Slice B) — adapters with no engine concept simply
+     * omit it.
+     */
+    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;
+    }>;
     files: EmittedFile[];
     id: string;
+    opaqueMountTargets?: string[];
+    persistentMounts?: ContainerTargetPersistentMount[];
     sourceIds?: string[];
+    /** World token env names actually lowered into this target's native config. */
+    worldTokenEnvNames?: string[];
 }
 export interface RuntimeContainerInstancePaths {
     configPathTemplate: string;
@@ -41,7 +68,9 @@ export interface RuntimeContainerInstancePaths {
 export interface RuntimeContainerConfigEnvBinding {
     envName: string;
     generated?: boolean;
-    jsonPath: string;
+    /** Legacy dot paths remain supported; structured paths address arbitrary JSON keys exactly. */
+    jsonPath: string | readonly string[];
+    transform?: RuntimeContainerConfigValueTransform;
 }
 export interface RuntimeContainerMeta {
     configFileName: string;
@@ -80,7 +109,22 @@ export interface RuntimeAuthInstance {
     runtime: string;
 }
 export interface RuntimeAuthPreparationInput {
-    authProfile: ResolvedAuthProfile;
+    /**
+     * The Spawnfile-managed auth profile (`--auth-profile`), or `null` when the
+     * run/up invocation did not select one. Host-credential staging that does
+     * not depend on an imported auth profile (e.g. the Pi adapter's optional
+     * CLI-home mounts for grok/codex/antigravity) must still run when this is
+     * `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;
@@ -88,6 +132,10 @@ export interface RuntimeAuthPreparationInput {
 }
 export interface RuntimeAuthPreparationResult {
     coveredModelSecrets: string[];
+    launchIdentity?: {
+        kind: "daimon";
+        uid: number;
+    };
     mountArgs: string[];
 }
 export interface RuntimeProbeExecResult {

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;