byollm 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { BackendId, BackendClass, StopReason, JobKind, BackendCost, OfferScope, PublicIdentity, Capability, PairStartResponse, PairPollResponse, FetchResponse, ClaimResponse, WithheldKind as WithheldKind$1, HeartbeatResponse, SealedEnvelope, ResultDisposition, ResultResponse, ReleaseResponse, ToolCallResponse, ToolResultsResponse, BlobUrlResponse, BlobSlotResponse, Audience, StoredKeys, GrantRefusal, ClaimedStub, ClaimedJob, JobOutcome, ImageJobOutcome, RunMetadata, ToolOutcomes, ToolDeclaration, ToolCall } from '@byollm/protocol';
1
+ import { BackendId, BackendClass, StopReason, JobKind, BackendCost, OfferScope, Audience, PublicIdentity, Capability, PairStartResponse, PairPollResponse, FetchResponse, ClaimResponse, WithheldKind as WithheldKind$1, HeartbeatResponse, SealedEnvelope, ResultDisposition, ResultResponse, ReleaseResponse, ToolCallResponse, ToolResultsResponse, BlobUrlResponse, BlobSlotResponse, StoredKeys, GrantRefusal, ClaimedStub, ClaimedJob, JobOutcome, ImageJobOutcome, RunMetadata, ToolOutcomes, ToolDeclaration, ToolCall } from '@byollm/protocol';
2
2
  import { z } from 'zod';
3
3
 
4
4
  /**
@@ -194,71 +194,6 @@ declare class UnusableOrigin extends Error {
194
194
  */
195
195
  declare function normalizeOrigin(input: string): string;
196
196
 
197
- /**
198
- * Signing a vendor CLI in, from inside `byollm setup`.
199
- *
200
- * Two machines sat in "we thought it wasn't working" because a logged-out CLI
201
- * only produced a *note*: setup found the binary, said it could not answer
202
- * yet, wrote the config anyway and moved on. The config was right — nothing
203
- * routes until it answers — and the person was not stopped at the one moment
204
- * they were sitting in front of a terminal ready to fix it.
205
- *
206
- * ## One terminal, because that is what a hosted console has
207
- *
208
- * The obvious shape is "open another terminal and log in there", and it is
209
- * wrong for the place this has to work: a hosted device's console is one
210
- * window, and so is an SSH session. The shell-job-control version — background
211
- * setup, run the CLI, `fg` — needs job control a child process does not own.
212
- *
213
- * So setup spawns the login itself with the TTY inherited. The vendor CLI
214
- * takes over the terminal, does whatever it does, exits, and setup re-probes.
215
- *
216
- * ## Verified against the shipped CLIs, not assumed
217
- *
218
- * The ruling allowed for "a direct login subcommand if one exists, else
219
- * interactive plus a `/exit` instruction". Both have one, which is better than
220
- * the fallback in every way — it exits by itself when the login finishes,
221
- * rather than depending on somebody typing the right thing to come back:
222
- *
223
- * claude claude auth login (also: claude auth status)
224
- * codex codex login --device-auth (also: codex login status)
225
- *
226
- * Checked by running them, per the FIXED_ARGV precedent. `claude login` is not
227
- * a command; `claude auth login` is. Guessing the first would have produced a
228
- * gate that always failed, on the path a new person meets first.
229
- *
230
- * **`--device-auth` since B148, and the table said `codex login` for one
231
- * commit after the code stopped.** That flow opens a localhost OAuth callback,
232
- * so on any machine without a browser and a loopback listener it does not fail
233
- * — it **hangs**. A summary whose authority is *"we ran these"*, listing a
234
- * command removed **because it hangs**, is worse than an unverified one; and
235
- * it is the first thing a reader of this file meets.
236
- *
237
- * The rule it breaks is instruction 20's corollary one scope down: a ruling is
238
- * not landed until the code matches it, and a file's own header is code's
239
- * nearest neighbour.
240
- *
241
- * ## Except on Windows, where the spawn cannot work — ruled 2026-09-04
242
- *
243
- * An npm-installed `claude` on Windows is `claude.cmd`, and Node will not
244
- * spawn a `.cmd` without a shell: since the CVE-2024-27980 fix (18.20/20.12)
245
- * it throws EINVAL, and before that ENOENT. {@link runLogin} is built to
246
- * swallow that — "cannot spawn" and "exited nonzero" are the same outcome to
247
- * the caller — so Kevin got three rounds of "Opening Claude's sign-in now"
248
- * followed by "Still cannot answer", with nothing opening and no error ever
249
- * printed. Two defensible designs composing into a silent loop.
250
- *
251
- * Todd ruled: on Windows do not spawn at all. Print the command, prominently,
252
- * and let the person run it. {@link loginPlan} is where that decision lives,
253
- * so it is made once and is testable without a platform to run on.
254
- */
255
- /** How a backend's CLI is signed in, when it has a way. */
256
- interface LoginCommand {
257
- readonly argv: readonly [string, ...string[]];
258
- /** What to tell somebody before the terminal stops being ours. */
259
- readonly says: string;
260
- }
261
-
262
197
  /**
263
198
  * The text of one model call, already composed by the daemon.
264
199
  *
@@ -621,767 +556,1145 @@ type ConverseResult = {
621
556
  });
622
557
 
623
558
  /**
624
- * Where the daemon keeps its state.
625
- *
626
- * One directory the owner can `ls`, `cat` and delete. The trust surface is
627
- * the product (byollm_002), and a trust surface you cannot find is not one.
628
- */
629
- interface DaemonPaths {
630
- /** `~/.byollm` — everything below lives here. */
631
- readonly root: string;
632
- /** Job routing and backend configuration, owner-authored. */
633
- readonly config: string;
634
- /** Paired servers: origin, runner id, token, owner. */
635
- readonly pairings: string;
636
- /** The local `team` allowlist — one file, every app. */
637
- readonly allowlist: string;
638
- /** Append-only JSONL: every prompt that has run on this machine. */
639
- readonly ingressLog: string;
640
- /** Community-job counters, for rate limits and the daily cap. */
641
- readonly budgets: string;
642
- /** Estimated money spent running other people's work on metered backends. */
643
- readonly spend: string;
644
- /**
645
- * Grant ids this device has already admitted — byollm-review 2026-08-27.
646
- *
647
- * On disk because a grant stays valid for two minutes and a supervised
648
- * restart takes about one, so an in-process set was empty exactly when it
649
- * was still needed. Holds only unexpired ids, so it stays small on its own.
650
- */
651
- readonly spentGrants: string;
652
- /**
653
- * This machine's device keypairs (byollm_009 §3). The most sensitive file
654
- * the daemon writes: it is the machine's identity, not a token a server can
655
- * revoke and reissue.
656
- */
657
- readonly keys: string;
658
- /**
659
- * What the last probe learned about each service — the owner's copy.
660
- *
661
- * Written by whoever ran the probe, read by `byollm status`, which is a
662
- * different process and must not spend a model call of its own to answer
663
- * "how are my services". A canary on a metered backend costs real money,
664
- * and `status` is a command people run often.
665
- *
666
- * Latest state only, never a history: this answers "where does this stand
667
- * now", and a log of every probe would be a log of when somebody's token
668
- * lapsed, which is nobody's business including ours.
669
- */
670
- readonly serviceStates: string;
671
- /**
672
- * The image probes' verdicts — byollm_021 §5. The image probe is a paid
673
- * call on a metered backend, so its answer is kept for 24 hours and shared
674
- * by every process that would otherwise ask again.
675
- */
676
- readonly imageProbes: string;
677
- /**
678
- * How the daemon's last conversation with an upstream went.
679
- *
680
- * Written by the running daemon, read by `byollm status`, which otherwise
681
- * cannot ask it anything: the two are separate processes and `state:
682
- * running` was derived from a local flag alone. That sentence was true
683
- * for hours while every heartbeat this device sent was refused — the
684
- * daemon was running and reporting nothing, and the only surface that knew
685
- * was a log line nobody tails.
686
- *
687
- * A file rather than a socket because the question is small and the answer
688
- * survives a restart of either side.
689
- */
690
- readonly health: string;
691
- /** Liveness, rewritten every beat — B202. */
692
- readonly heartbeat: string;
693
- /** Who keeps this device running when it is not a service — #8404. */
694
- readonly supervisor: string;
695
- /**
696
- * What this machine calls itself when it pairs.
697
- *
698
- * Its own file rather than a field in `config.json`, because that file is
699
- * routing and backends — the things somebody edits when work is going
700
- * wrong — and a name is neither. A one-line file is also a thing a person
701
- * can `cat` when they are wondering why an approval screen said
702
- * `todd@Todds-Mac-Studio`.
703
- */
704
- readonly label: string;
705
- /**
706
- * Per-job scratch directories. A process-class backend runs with its `cwd`
707
- * set to an empty one of these and nothing else (byollm_004 §2).
708
- */
709
- readonly scratch: string;
710
- }
711
- /** Resolve the daemon's paths, rooted at `~/.byollm` unless overridden. */
712
- declare function daemonPaths(root?: string): DaemonPaths;
713
- /**
714
- * `BYOLLM_HOME` is a TEST SEAM. Ruled 09-15 (B205): always or never, never
715
- * "sometimes" — and it stays, explicitly scoped and loud rather than silent.
716
- *
717
- * It exists so the conformance kit and the adversarial suite can run real
718
- * daemons without touching the developer's own `~/.byollm`; `edges.test.ts:48`
719
- * asserts exactly that. **On a person's own machine, a set `BYOLLM_HOME` is a
720
- * bug**, and {@link overriddenRootNotice} is what stops that being silent.
559
+ * One configured backend instance.
721
560
  *
722
- * One deliberate exception, and it is not a person's machine: the box
723
- * supervisor STATES this variable to the daemon it spawns (`boxDaemon`, B204's
724
- * rider) so that PID 1 and the daemon cannot disagree about where the heartbeat
725
- * file lives. It sets it to this same default, which is why the notice below
726
- * asks whether the root has actually MOVED rather than whether the variable
727
- * exists — see there.
561
+ * `openai-http` may be configured many times — one per model server the owner
562
+ * runs (Ollama here, `mlx_lm.server` there, a llama.cpp box on the LAN). That
563
+ * is byollm_001 Rev 1 §A's "one backend, N base URLs".
728
564
  */
729
- declare function defaultRoot(): string;
730
-
565
+ declare const ServiceConfig: z.ZodObject<{
566
+ type: z.ZodEnum<{
567
+ ollama: "ollama";
568
+ mlx: "mlx";
569
+ llamacpp: "llamacpp";
570
+ vllm: "vllm";
571
+ lmstudio: "lmstudio";
572
+ jan: "jan";
573
+ localai: "localai";
574
+ anthropic: "anthropic";
575
+ openai: "openai";
576
+ gemini: "gemini";
577
+ grok: "grok";
578
+ groq: "groq";
579
+ openrouter: "openrouter";
580
+ together: "together";
581
+ deepseek: "deepseek";
582
+ mistral: "mistral";
583
+ "openai-http": "openai-http";
584
+ "claude-cli": "claude-cli";
585
+ "codex-cli": "codex-cli";
586
+ }>;
587
+ baseUrl: z.ZodOptional<z.ZodString>;
588
+ model: z.ZodString;
589
+ kinds: z.ZodArray<z.ZodEnum<{
590
+ "llm.tools": "llm.tools";
591
+ "llm.generate": "llm.generate";
592
+ "llm.chat": "llm.chat";
593
+ "llm.vision": "llm.vision";
594
+ "llm.image": "llm.image";
595
+ }>>;
596
+ offer: z.ZodDefault<z.ZodEnum<{
597
+ private: "private";
598
+ team: "team";
599
+ }>>;
600
+ apiKeyEnv: z.ZodOptional<z.ZodString>;
601
+ spend: z.ZodOptional<z.ZodObject<{
602
+ acknowledged: z.ZodDefault<z.ZodBoolean>;
603
+ dailyCapCents: z.ZodOptional<z.ZodNumber>;
604
+ centsPerMillionTokens: z.ZodDefault<z.ZodNumber>;
605
+ }, z.core.$strict>>;
606
+ images: z.ZodOptional<z.ZodObject<{
607
+ sizes: z.ZodPrefault<z.ZodObject<{
608
+ square: z.ZodDefault<z.ZodString>;
609
+ portrait: z.ZodDefault<z.ZodString>;
610
+ landscape: z.ZodDefault<z.ZodString>;
611
+ }, z.core.$strict>>;
612
+ maxImagesPerJob: z.ZodDefault<z.ZodNumber>;
613
+ probeSize: z.ZodOptional<z.ZodString>;
614
+ }, z.core.$strict>>;
615
+ }, z.core.$strict>;
616
+ type ServiceConfig = z.infer<typeof ServiceConfig>;
731
617
  /**
732
- * One sentence about a service, for the three surfaces its owner reads.
733
- *
734
- * Your Devices, `byollm status`, and the daemon's own output all answer the
735
- * same question — can this thing do its job, and if not what do I run — so
736
- * they say it in one string rather than three that drift.
737
- *
738
- * The person this is for is the owner, and only the owner. A site gets a class
739
- * and a fixed sentence and never this; the CLI's own words quote paths,
740
- * usernames and account emails, and they name which backend answered, which
741
- * is what the disclosure fence exists to prevent.
618
+ * Budgets applied to jobs whose owner is not this machine's owner
619
+ * ({@link MUSTS.COMMUNITY_BUDGETS}).
742
620
  */
743
- /** What asking the backend produced. */
744
- type ServiceState =
745
- /** Ran a real call and answered. */
746
- {
747
- readonly kind: "answers";
748
- readonly model: string;
749
- }
750
- /** The binary is there; the credentials are not. */
751
- | {
752
- readonly kind: "signed-out";
753
- readonly detail?: string | undefined;
754
- }
755
- /** The config names a binary this machine does not have. */
756
- | {
757
- readonly kind: "missing";
758
- }
759
- /**
760
- * Installed here, not running, and startable — B056 / D4.
761
- *
762
- * Advertised, unlike `missing`, because it IS available: one spawn away,
763
- * and the daemon starts it when a job arrives (B050). Its own kind rather
764
- * than reusing `missing` or `unknown`, because this is the one state where
765
- * the machine ADVERTISES the service — and a service advertised while
766
- * `status` calls it "not found on this device" is a machine disagreeing
767
- * with itself on two screens.
768
- */
769
- /**
770
- * Stopped, and nothing here knows how to start it — B098.
771
- *
772
- * Distinct from `missing`, which means the program is not on this machine.
773
- * Conflating them told an owner to install software that was already
774
- * installed, which is an afternoon spent on a fix that was never the
775
- * problem.
776
- */
777
- | {
778
- readonly kind: "unstartable";
779
- readonly model: string;
621
+ declare const CommunityBudget: z.ZodObject<{
622
+ maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
623
+ maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
624
+ maxWallClockMs: z.ZodDefault<z.ZodNumber>;
625
+ maxOutputBytes: z.ZodDefault<z.ZodNumber>;
626
+ maxPayloadChars: z.ZodDefault<z.ZodNumber>;
627
+ countTeamJobs: z.ZodDefault<z.ZodBoolean>;
628
+ maxImageBytes: z.ZodDefault<z.ZodNumber>;
629
+ }, z.core.$strict>;
630
+ type CommunityBudget = z.infer<typeof CommunityBudget>;
631
+ /** Ingress-log retention (byollm_004 Rev 1). */
632
+ declare const IngressRetention: z.ZodObject<{
633
+ communityPromptDays: z.ZodDefault<z.ZodNumber>;
634
+ keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
635
+ }, z.core.$strict>;
636
+ type IngressRetention = z.infer<typeof IngressRetention>;
637
+ /** Ceilings applied to every job, community or not. */
638
+ declare const Limits: z.ZodObject<{
639
+ maxWallClockMs: z.ZodDefault<z.ZodNumber>;
640
+ maxOutputBytes: z.ZodDefault<z.ZodNumber>;
641
+ }, z.core.$strict>;
642
+ type Limits = z.infer<typeof Limits>;
643
+ declare const DaemonConfig: z.ZodObject<{
644
+ version: z.ZodDefault<z.ZodLiteral<1>>;
645
+ services: z.ZodRecord<z.ZodString, z.ZodObject<{
646
+ type: z.ZodEnum<{
647
+ ollama: "ollama";
648
+ mlx: "mlx";
649
+ llamacpp: "llamacpp";
650
+ vllm: "vllm";
651
+ lmstudio: "lmstudio";
652
+ jan: "jan";
653
+ localai: "localai";
654
+ anthropic: "anthropic";
655
+ openai: "openai";
656
+ gemini: "gemini";
657
+ grok: "grok";
658
+ groq: "groq";
659
+ openrouter: "openrouter";
660
+ together: "together";
661
+ deepseek: "deepseek";
662
+ mistral: "mistral";
663
+ "openai-http": "openai-http";
664
+ "claude-cli": "claude-cli";
665
+ "codex-cli": "codex-cli";
666
+ }>;
667
+ baseUrl: z.ZodOptional<z.ZodString>;
668
+ model: z.ZodString;
669
+ kinds: z.ZodArray<z.ZodEnum<{
670
+ "llm.tools": "llm.tools";
671
+ "llm.generate": "llm.generate";
672
+ "llm.chat": "llm.chat";
673
+ "llm.vision": "llm.vision";
674
+ "llm.image": "llm.image";
675
+ }>>;
676
+ offer: z.ZodDefault<z.ZodEnum<{
677
+ private: "private";
678
+ team: "team";
679
+ }>>;
680
+ apiKeyEnv: z.ZodOptional<z.ZodString>;
681
+ spend: z.ZodOptional<z.ZodObject<{
682
+ acknowledged: z.ZodDefault<z.ZodBoolean>;
683
+ dailyCapCents: z.ZodOptional<z.ZodNumber>;
684
+ centsPerMillionTokens: z.ZodDefault<z.ZodNumber>;
685
+ }, z.core.$strict>>;
686
+ images: z.ZodOptional<z.ZodObject<{
687
+ sizes: z.ZodPrefault<z.ZodObject<{
688
+ square: z.ZodDefault<z.ZodString>;
689
+ portrait: z.ZodDefault<z.ZodString>;
690
+ landscape: z.ZodDefault<z.ZodString>;
691
+ }, z.core.$strict>>;
692
+ maxImagesPerJob: z.ZodDefault<z.ZodNumber>;
693
+ probeSize: z.ZodOptional<z.ZodString>;
694
+ }, z.core.$strict>>;
695
+ }, z.core.$strict>>;
696
+ defaults: z.ZodPrefault<z.ZodRecord<z.ZodEnum<{
697
+ "llm.tools": "llm.tools";
698
+ "llm.generate": "llm.generate";
699
+ "llm.chat": "llm.chat";
700
+ "llm.vision": "llm.vision";
701
+ "llm.image": "llm.image";
702
+ }> & z.core.$partial, z.ZodString>>;
703
+ concurrency: z.ZodDefault<z.ZodNumber>;
704
+ autoUpdate: z.ZodDefault<z.ZodBoolean>;
705
+ updateAuthority: z.ZodOptional<z.ZodString>;
706
+ minAvailableMemoryBytes: z.ZodDefault<z.ZodNumber>;
707
+ community: z.ZodPrefault<z.ZodObject<{
708
+ maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
709
+ maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
710
+ maxWallClockMs: z.ZodDefault<z.ZodNumber>;
711
+ maxOutputBytes: z.ZodDefault<z.ZodNumber>;
712
+ maxPayloadChars: z.ZodDefault<z.ZodNumber>;
713
+ countTeamJobs: z.ZodDefault<z.ZodBoolean>;
714
+ maxImageBytes: z.ZodDefault<z.ZodNumber>;
715
+ }, z.core.$strict>>;
716
+ ingress: z.ZodPrefault<z.ZodObject<{
717
+ communityPromptDays: z.ZodDefault<z.ZodNumber>;
718
+ keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
719
+ }, z.core.$strict>>;
720
+ limits: z.ZodPrefault<z.ZodObject<{
721
+ maxWallClockMs: z.ZodDefault<z.ZodNumber>;
722
+ maxOutputBytes: z.ZodDefault<z.ZodNumber>;
723
+ }, z.core.$strict>>;
724
+ }, z.core.$strict>;
725
+ type DaemonConfig = z.infer<typeof DaemonConfig>;
726
+ /** One kind, served by one named service, ready to execute. */
727
+ interface ResolvedRoute {
728
+ readonly kind: z.infer<typeof JobKind>;
780
729
  /**
781
- * The type byollm WOULD start at this service's address — B098's offer,
782
- * carried to the screen people look at.
783
- *
784
- * Todd, 10-05, after a reboot: `glm-5.2` is `openai-http` at
785
- * `127.0.0.1:11434`, and this line told him only "start it yourself".
786
- * He read it as on-demand start having broken. It had not — only
787
- * `type: "ollama"` is ever started, ruled 09-10, offered not inferred —
788
- * and `byollm diagnose` already printed the one-field fix. `status`
789
- * did not, and `status` is what people read.
730
+ * The owner's name for the service serving this kind.
790
731
  *
791
- * Set by the daemon from `startableAt` (local-server.ts), the same function
792
- * diagnose asks, and only when that provider is installed here: an
793
- * offer to retype a service into one that would then read "not found"
794
- * is a remedy that moves the problem. Optional, and absent means no
795
- * offer — a file written before this field existed says what it always
796
- * said.
732
+ * Carried onto the wire in the capability matrix, so a device advertises
733
+ * *which* of its services answers a kind rather than only that something
734
+ * does. Phase B lets a job select by this name.
797
735
  */
798
- readonly startableAs?: BackendId | undefined;
799
- } | {
800
- readonly kind: "stopped";
801
- readonly model: string;
736
+ readonly service: string;
802
737
  /**
803
- * Whether anything on this device will actually start it — B087.
738
+ * Whether this is the service an *unselected* job for this kind reaches.
804
739
  *
805
- * The comment above says "the daemon starts it when a job arrives
806
- * (B050)", and until this field existed that was not true: the starter
807
- * is behind a `spawnServer` seam nothing passes, so a stopped server
808
- * was advertised and a job routed to it reached nothing listening —
809
- * the claimed-then-failed outcome B056's own ruling forbids.
740
+ * Phase B advertises the whole menu, so a kind may have several routes and
741
+ * exactly one of them is where a job that named nothing goes. Stated rather
742
+ * than inferred from position: the previous shape advertised only the
743
+ * winner, so "the route for this kind" and "the default for this kind" were
744
+ * the same object, and every consumer that took the first match was correct
745
+ * by accident.
810
746
  *
811
- * Optional, and absent means NO. `byollm status` is a different
812
- * process reading what the daemon wrote, so a file written before this
813
- * field existed is read by a daemon that has it — and the honest
814
- * default for "I cannot tell whether anything starts this" is not to
815
- * promise that something will.
747
+ * False for a kind that is withheld — nothing is the default there, which
748
+ * is the whole meaning of withheld.
816
749
  */
817
- readonly starts?: boolean | undefined;
750
+ readonly isDefault: boolean;
751
+ readonly backendId: BackendId;
752
+ readonly backendClass: "http" | "process";
753
+ readonly model: string;
754
+ /** Who pays for this route's tokens. From the registry, never from config. */
755
+ readonly cost: BackendCost;
756
+ /** After the cost rules are applied — never the raw configured value. */
757
+ readonly offerScope: z.infer<typeof OfferScope>;
758
+ /** The owner's spend consent, for a `metered` route. */
759
+ readonly spendAcknowledged: boolean;
760
+ readonly spendDailyCapCents: number | undefined;
761
+ readonly spendCentsPerMillionTokens: number;
762
+ readonly baseUrl: string | undefined;
763
+ readonly apiKeyEnv: string | undefined;
764
+ }
765
+ interface ConfigProblem {
766
+ readonly where: string;
767
+ readonly message: string;
818
768
  }
819
769
  /**
820
- * Signed in, healthy, and out of quota until further notice — 019 §3.2.
770
+ * A kind this device could serve and deliberately does not.
821
771
  *
822
- * Its own state because its remedy is the opposite of signed-out's: this
823
- * one needs **time and nothing else**, and there is nothing for the owner
824
- * to go and do. Rendering it as "needs sign-in" would send somebody to a
825
- * terminal to fix an account that is working perfectly.
772
+ * Withholding has to be *loud on the owner's side*, in every surface that
773
+ * could otherwise show absence. An owner who adds a second `llm.generate`
774
+ * service and finds their team's jobs quietly stop matching, with nothing
775
+ * anywhere saying why, has been failed by the correct behaviour — which is
776
+ * the quiet kind of correct this project keeps deleting.
826
777
  */
827
- | {
828
- readonly kind: "blocked";
829
- readonly detail?: string | undefined;
830
- /** Epoch ms the CLI expects to be back, when it said so. */
831
- readonly until?: number | undefined;
778
+ interface WithheldKind {
779
+ readonly kind: z.infer<typeof JobKind>;
780
+ /** The services that answer it, any of which the owner could name. */
781
+ readonly services: readonly string[];
782
+ }
783
+ interface LoadedConfig {
784
+ readonly config: DaemonConfig;
785
+ readonly routes: readonly ResolvedRoute[];
786
+ /** Kinds not advertised because the owner has not said which service wins. */
787
+ readonly withheld: readonly WithheldKind[];
788
+ /**
789
+ * What this build cannot yet do, in the owner's words.
790
+ *
791
+ * Separate from `problems` on purpose: a problem means the config says
792
+ * something wrong and something was dropped. A notice means the config is
793
+ * fine and *the build* is behind it. Folding the two would make every
794
+ * limitation read as an owner's mistake — and would make a genuine mistake
795
+ * easier to miss among them.
796
+ */
797
+ readonly notices: readonly string[];
798
+ /** Non-fatal problems: a route that cannot be served is dropped, not fatal. */
799
+ readonly problems: readonly ConfigProblem[];
832
800
  }
801
+ /** The config used when the owner has not written one. */
802
+ declare const DEFAULT_CONFIG: DaemonConfig;
833
803
  /**
834
- * Nobody asked, because there was nothing to ask with.
804
+ * Read and resolve `~/.byollm/config.json`.
835
805
  *
836
- * Not a failure and not a success. A backend with no canary — an HTTP model
837
- * server, say — has no credentials of its own to check, and rendering this
838
- * as "cannot answer" would tell every local-server owner their model was
839
- * broken. Not asked is not no, the same way an empty variable is not a
840
- * configured one.
806
+ * A missing file yields {@link DEFAULT_CONFIG}; a malformed one throws,
807
+ * because silently running with defaults when the owner *did* write a config
808
+ * would execute work under rules they did not choose.
841
809
  */
842
- | {
843
- readonly kind: "unknown";
844
- readonly model: string;
845
- };
810
+ declare function loadConfig(path: string): Promise<LoadedConfig>;
846
811
  /**
847
- * A service's state plus the remedy its backend supplies.
812
+ * Turn a parsed config into executable routes, applying the subscription lock
813
+ * and rejecting unusable backends.
848
814
  *
849
- * Kept together because they are learned together — at probe time, from the
850
- * backend instance that knows both — and needed together, by every surface
851
- * that renders a line. A caller looking the remedy up later would be looking
852
- * it up from somewhere that does not know which backend this service used.
815
+ * A problem here is not fatal: a machine with three routes and one broken
816
+ * backend should serve the other two and say so, rather than refusing to
817
+ * start. What it must never do is *advertise* the broken one
818
+ * ({@link MUSTS.CAPABILITY_IS_DETECTED}).
853
819
  */
854
- interface ServiceReport {
855
- readonly state: ServiceState;
856
- readonly signIn?: string | undefined;
857
- }
858
-
859
- /** Build the child's environment from the allowlist. */
860
- declare function childEnv(source?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Record<string, string>;
861
- /** The argv this backend would run for a given model. Exported for the suite. */
862
- declare function claudeArgv(model: string): readonly string[];
863
- /**
864
- * The process-class backend: the user's own `claude` CLI, on their own
865
- * subscription.
866
- *
867
- * Subscription-class, so its offer scope is locked to `private`
868
- * ({@link MUSTS.SUBSCRIPTION_SELF_LOCK}) — one account runs one person's work.
869
- *
870
- * Every requirement of byollm_004 §2 applies here and is implemented here:
871
- * fixed argv, prompt on stdin, stripped environment, empty scratch `cwd`, no
872
- * inherited descriptors beyond the three std streams, hard timeout, hard
873
- * output cap.
874
- */
875
- declare class ClaudeCliBackend implements Backend {
876
- #private;
877
- /**
878
- * Nothing to read — checked, not assumed (byollm_021).
879
- *
880
- * {@link FIXED_ARGV} runs `--output-format text`, and text is exactly what
881
- * comes back: an answer with no envelope around it, deliberately, because
882
- * an envelope is a thing to misparse. So there is no field carrying a stop
883
- * reason and no amount of parsing invents one.
884
- *
885
- * `--output-format json` would very likely carry it. Changing the frozen
886
- * argv is not a thing to do inside a mapping declaration: that argv is what
887
- * the adversarial suite asserts every hostile payload produces, and moving
888
- * it is its own decision with its own review.
889
- */
890
- readonly stopReasons: StopReasonMapping;
891
- readonly id: BackendId;
892
- readonly class: BackendClass;
893
- readonly signIn = "run `claude` in a terminal";
894
- /**
895
- * @param binary - which executable to run. Defaults to `claude` and is
896
- * **not reachable from configuration**: {@link createBackend} constructs
897
- * this with no arguments, and {@link BackendInit} has no field for it. It
898
- * exists so the adversarial suite can substitute a probe that reports the
899
- * argv, environment, cwd and stdin it actually received — which is the only
900
- * way to *prove* byollm_004 §2 rather than assert it.
901
- */
902
- constructor(binary?: string);
903
- /**
904
- * One real, tiny call — the only way to learn whether credentials work.
905
- *
906
- * `--version` answers "is the binary here", which was never the question.
907
- * This asks the question, and pays for it: a handful of tokens against the
908
- * owner's own subscription, at daemon start rather than on every heartbeat.
909
- *
910
- * A failure here is reported rather than thrown, and the runner treats an
911
- * `unauthorized` exactly as it treats one from a real job — the service is
912
- * withdrawn and the owner is told once.
913
- */
914
- canary(model: string): Promise<BackendHealth>;
915
- health(): Promise<BackendHealth>;
916
- execute(request: BackendRequest): Promise<BackendResult>;
917
- }
918
-
919
- declare class OpenAiHttpBackend implements Backend {
920
- #private;
921
- readonly stopReasons: StopReasonMapping;
922
- readonly id: BackendId;
923
- readonly class: BackendClass;
924
- constructor(init: BackendInit);
925
- health(): Promise<BackendHealth>;
926
- execute(request: BackendRequest): Promise<BackendResult>;
927
- /**
928
- * One turn of a function-calling conversation — byollm_012 §7.
929
- *
930
- * The declarations go to the model as OpenAI `tools`; the calls it asks for
931
- * come back as text. Nothing here runs one, opens anything or reaches
932
- * anywhere but this service's own configured `chat/completions` — the tool
933
- * loop seals each call to the site that declared it.
934
- */
935
- converse(request: ConverseRequest): Promise<ConverseResult>;
936
- /**
937
- * `llm.vision` — the same `/v1/chat/completions`, with image parts as
938
- * `image_url` data URLs (byollm_021 §6: Ollama, llama.cpp with a projector,
939
- * vLLM, LM Studio, OpenAI and the compatible endpoints all take this shape).
940
- *
941
- * A data URL, never a link: the bytes are the request, so the model server
942
- * has nothing to fetch and neither does this daemon.
943
- */
944
- readImages(request: VisionRequest): Promise<BackendResult>;
945
- /**
946
- * `llm.image` — `/v1/images/generations`, asking for `b64_json`.
947
- *
948
- * **Bytes, never URLs** ({@link MUSTS.IMAGE_BYTES_NOT_URLS}, C056). A
949
- * backend that answers with `url` instead is an error, and the URL is not
950
- * fetched: fetching it would be this device fetching an address a backend
951
- * chose, which byollm_012 §11.1 holds back from v1.
952
- */
953
- makeImages(request: ImageRequest): Promise<ImageResult>;
954
- }
820
+ declare function resolveConfig(config: DaemonConfig): LoadedConfig;
955
821
 
956
822
  /**
957
- * Construct a backend instance.
958
- *
959
- * Exhaustive over {@link BackendClass}, and now actually so — cloud_008 Tier
960
- * 3, finding 15. The docstring used to claim "the switch is exhaustive over
961
- * `BackendId`, so adding a backend to the protocol registry without
962
- * implementing it here is a compile error", and there was no switch: an `if`
963
- * on `class === "process"` with everything else falling through to the HTTP
964
- * transport. A backend class added to the registry would have got an
965
- * OpenAI-compatible client and failed at runtime, in the shape the comment
966
- * promised was impossible.
967
- *
968
- * The `never` assignment is what makes the claim true. It costs one line and
969
- * fails at compile time in the file that has to change.
970
- *
971
- * Providers are still registry entries rather than implementations
972
- * (byollm_007 §3): every HTTP-class id speaks the same
973
- * `/v1/chat/completions`, so they share one transport and one adversarial
974
- * corpus. Adding a *provider* is a line in the registry. Adding a *class* is
975
- * this function.
823
+ * The caps this class enforces. `countTeamJobs` is not one of them: whether a
824
+ * job is counted is the runner's question, asked per job, and answered here
825
+ * through `check`'s `counted`.
976
826
  */
977
- declare function createBackend(id: BackendId, init: BackendInit): Backend;
978
-
827
+ type Caps = Omit<CommunityBudget, "countTeamJobs" | "maxImageBytes">;
828
+ /** Which brake refused a community job — written to the ingress log. */
829
+ declare const BudgetRefusal: z.ZodEnum<{
830
+ "hourly-cap": "hourly-cap";
831
+ "daily-cap": "daily-cap";
832
+ "payload-too-large": "payload-too-large";
833
+ "ledger-untrusted": "ledger-untrusted";
834
+ "image-bytes": "image-bytes";
835
+ }>;
836
+ type BudgetRefusal = z.infer<typeof BudgetRefusal>;
837
+ type BudgetDecision = {
838
+ readonly ok: true;
839
+ } | {
840
+ readonly ok: false;
841
+ readonly refusal: BudgetRefusal;
842
+ readonly detail: string;
843
+ };
979
844
  /**
980
- * Grants this device has already admitted — byollm-review 2026-08-27.
981
- *
982
- * A grant admits one job, once. That was enforced by a `Map` that lived only
983
- * in the process, defended in a comment: "an entry can only matter for as
984
- * long as the grant naming it is still fresh, and a device that has restarted
985
- * since is past that window anyway."
986
- *
987
- * The second half is false, and it is the half the argument rests on.
988
- * {@link GRANT_MAX_AGE_MS} is two minutes; a supervised restart — systemd, a
989
- * crash loop, a deploy — completes in about a second. So the window is not
990
- * "past" at all: the set comes back empty while the grant is still perfectly
991
- * fresh, and a relay that re-delivers the same stub gets a second admission
992
- * and a second execution. Double-spend of somebody's metered backend, or
993
- * duplicated side effects, on work that was already done.
994
- *
995
- * ## What durable means here, exactly
996
- *
997
- * Written with a **synchronous** write, and that is the whole mechanism. The
998
- * threat is a process that dies and is restarted by a supervisor, which is
999
- * survived the moment the bytes reach the operating system — the page cache
1000
- * outlives the process. It is not `fsync`, so a machine losing power between
1001
- * the write and the flush can still forget. That is a worse failure with a
1002
- * far smaller window, and paying an `fsync` per admitted job to close it
1003
- * would put disk latency in front of every claim.
845
+ * The owner's ceiling on work done for other people
846
+ * ({@link MUSTS.COMMUNITY_BUDGETS}).
1004
847
  *
1005
- * Synchronous rather than awaited because {@link Runner.admit} answers
1006
- * synchronously, and the record has to be durable *before* the job runs —
1007
- * writing afterwards would leave exactly the gap this closes. The file holds
1008
- * only ids that are still fresh, so it is small by construction rather than
1009
- * by pruning policy.
848
+ * byollm_004 §4 distinguishes two directions of abuse, and this is the one
849
+ * aimed *at* the volunteer: a stranger who can enqueue unlimited `public`
850
+ * jobs owns your GPU. Jobs for the machine's own owner are never counted —
851
+ * their machine, their call.
1010
852
  */
1011
- declare class SpentGrants {
853
+ declare class Budgets {
1012
854
  #private;
855
+ constructor(path: string, limits: Caps);
1013
856
  /**
1014
- * Without a path this is memory-only, which is what tests want and what
1015
- * direct mode is: no control plane, no grants, nothing to replay.
1016
- */
1017
- constructor(path?: string);
1018
- /**
1019
- * Read what survived the last run, dropping whatever has expired.
1020
- *
1021
- * A file that will not parse is no longer read as "nothing spent". That
1022
- * reading was chosen deliberately here — the comment argued that refusing
1023
- * every grant turns a corrupt cache into a total outage — and the argument
1024
- * is sound against refusing *forever*. It is not an argument for this,
1025
- * because the exposure and the remedy have the same clock: an id only
1026
- * matters while the grant naming it is still fresh, so refusing for that
1027
- * long is all fail-closed ever needed. A torn write plus a supervised
1028
- * restart inside a grant's window lets the same valid grant execute twice,
1029
- * with nothing forged.
1030
- */
1031
- load(now: number): void;
1032
- /**
1033
- * Why every relayed grant is being refused, if it is.
857
+ * Read the record of what has already been accepted.
1034
858
  *
1035
- * This is the one ledger whose brake covers the owner's own jobs too. The
1036
- * other two count what the machine did for other people, and their brakes
1037
- * stop exactly that. This one guards the wire: it is what stands between a
1038
- * re-delivered stub and a second execution, and a duplicate of your own
1039
- * metered job is still your money.
859
+ * Every failure used to become an empty array, which reconstructs the
860
+ * counts as zero and passes both caps — the file that says "you have
861
+ * already run your hundred jobs today" and the file that will not parse
862
+ * were the same answer.
1040
863
  */
1041
- blockedReason(now: number): string | undefined;
1042
- /** Has this grant already admitted a job? */
1043
- has(grantId: string, now: number): boolean;
864
+ load(now: number): Promise<void>;
865
+ /** Why community work is braked, if it is — for `byollm status`. */
866
+ untrustedReason(): string | undefined;
1044
867
  /**
1045
- * Burn it, durably, and say whether that worked.
868
+ * May this community job run?
1046
869
  *
1047
- * Returns `false` when the burn is not on disk, and the caller must refuse
1048
- * the job. This used to swallow the write failure and let the job run on
1049
- * in-memory protection alone — which is precisely the protection that a
1050
- * restart erases, so the case where the note fails and the case where the
1051
- * note is needed are the same case.
870
+ * @param payloadChars - total payload text length, checked against the
871
+ * stricter community limit rather than the protocol's absolute ceiling.
872
+ * @param counted - whether this job counts toward the hourly and daily
873
+ * caps. `false` only for a teammate's job on a metered service the owner
874
+ * shared, which the spend ceiling already bounds — see
875
+ * {@link CommunityBudget}'s `countTeamJobs`. The payload limit applies
876
+ * either way.
1052
877
  */
1053
- spend(grantId: string, issuedAt: number, now: number): boolean;
878
+ check(now: number, payloadChars: number, counted?: boolean): BudgetDecision;
879
+ /** Count a community job as accepted. Call only after {@link check} passes. */
880
+ record(now: number): Promise<void>;
881
+ /** Current usage, for `byollm status`. */
882
+ usage(now: number): {
883
+ hour: number;
884
+ day: number;
885
+ limits: Caps;
886
+ };
1054
887
  }
1055
888
 
1056
889
  /**
1057
- * One configured backend instance.
890
+ * A prompt about to be executed.
1058
891
  *
1059
- * `openai-http` may be configured many times — one per model server the owner
1060
- * runs (Ollama here, `mlx_lm.server` there, a llama.cpp box on the LAN). That
1061
- * is byollm_001 Rev 1 §A's "one backend, N base URLs".
892
+ * Written *before* the backend is called
893
+ * ({@link MUSTS.INGRESS_LOGGED_BEFORE_EXECUTION}), so a job that wedges or
894
+ * crashes the machine still leaves a record of what it was.
1062
895
  */
1063
- declare const ServiceConfig: z.ZodObject<{
1064
- type: z.ZodEnum<{
1065
- ollama: "ollama";
1066
- mlx: "mlx";
1067
- llamacpp: "llamacpp";
1068
- vllm: "vllm";
1069
- lmstudio: "lmstudio";
1070
- jan: "jan";
1071
- localai: "localai";
1072
- anthropic: "anthropic";
1073
- openai: "openai";
1074
- gemini: "gemini";
1075
- grok: "grok";
1076
- groq: "groq";
1077
- openrouter: "openrouter";
1078
- together: "together";
1079
- deepseek: "deepseek";
1080
- mistral: "mistral";
1081
- "openai-http": "openai-http";
1082
- "claude-cli": "claude-cli";
1083
- "codex-cli": "codex-cli";
1084
- }>;
1085
- baseUrl: z.ZodOptional<z.ZodString>;
896
+ declare const PromptEntry: z.ZodObject<{
897
+ type: z.ZodLiteral<"prompt">;
898
+ at: z.ZodNumber;
899
+ origin: z.ZodString;
900
+ jobId: z.ZodString;
901
+ site: z.ZodOptional<z.ZodString>;
902
+ kind: z.ZodString;
903
+ audience: z.ZodString;
904
+ owner: z.ZodString;
905
+ backendId: z.ZodString;
906
+ backendClass: z.ZodString;
1086
907
  model: z.ZodString;
1087
- kinds: z.ZodArray<z.ZodEnum<{
1088
- "llm.tools": "llm.tools";
1089
- "llm.generate": "llm.generate";
1090
- "llm.chat": "llm.chat";
1091
- "llm.vision": "llm.vision";
1092
- "llm.image": "llm.image";
908
+ promptHash: z.ZodString;
909
+ promptChars: z.ZodNumber;
910
+ prompt: z.ZodOptional<z.ZodString>;
911
+ }, z.core.$strict>;
912
+ type PromptEntry = z.infer<typeof PromptEntry>;
913
+ /** How a job ended. A separate line, so the prompt line is never rewritten. */
914
+ declare const OutcomeEntry: z.ZodObject<{
915
+ type: z.ZodLiteral<"outcome">;
916
+ at: z.ZodNumber;
917
+ jobId: z.ZodString;
918
+ site: z.ZodOptional<z.ZodString>;
919
+ outcome: z.ZodEnum<{
920
+ error: "error";
921
+ canceled: "canceled";
922
+ ok: "ok";
923
+ refused: "refused";
924
+ }>;
925
+ durationMs: z.ZodOptional<z.ZodNumber>;
926
+ spawnMs: z.ZodOptional<z.ZodNumber>;
927
+ firstOutputMs: z.ZodOptional<z.ZodNumber>;
928
+ outputChars: z.ZodOptional<z.ZodNumber>;
929
+ detail: z.ZodOptional<z.ZodString>;
930
+ stop: z.ZodOptional<z.ZodEnum<{
931
+ length: "length";
932
+ unknown: "unknown";
933
+ end: "end";
934
+ "stop-sequence": "stop-sequence";
935
+ "tool-budget": "tool-budget";
1093
936
  }>>;
1094
- offer: z.ZodDefault<z.ZodEnum<{
1095
- private: "private";
1096
- team: "team";
937
+ stopKind: z.ZodOptional<z.ZodEnum<{
938
+ declared: "declared";
939
+ unavailable: "unavailable";
940
+ unverified: "unverified";
941
+ }>>;
942
+ brake: z.ZodOptional<z.ZodEnum<{
943
+ "hourly-cap": "hourly-cap";
944
+ "daily-cap": "daily-cap";
945
+ "payload-too-large": "payload-too-large";
946
+ "ledger-untrusted": "ledger-untrusted";
947
+ "image-bytes": "image-bytes";
1097
948
  }>>;
1098
- apiKeyEnv: z.ZodOptional<z.ZodString>;
1099
- spend: z.ZodOptional<z.ZodObject<{
1100
- acknowledged: z.ZodDefault<z.ZodBoolean>;
1101
- dailyCapCents: z.ZodOptional<z.ZodNumber>;
1102
- centsPerMillionTokens: z.ZodDefault<z.ZodNumber>;
1103
- }, z.core.$strict>>;
1104
- images: z.ZodOptional<z.ZodObject<{
1105
- sizes: z.ZodPrefault<z.ZodObject<{
1106
- square: z.ZodDefault<z.ZodString>;
1107
- portrait: z.ZodDefault<z.ZodString>;
1108
- landscape: z.ZodDefault<z.ZodString>;
1109
- }, z.core.$strict>>;
1110
- maxImagesPerJob: z.ZodDefault<z.ZodNumber>;
1111
- probeSize: z.ZodOptional<z.ZodString>;
1112
- }, z.core.$strict>>;
1113
949
  }, z.core.$strict>;
1114
- type ServiceConfig = z.infer<typeof ServiceConfig>;
950
+ type OutcomeEntry = z.infer<typeof OutcomeEntry>;
951
+ declare const IngressEntry: z.ZodDiscriminatedUnion<[z.ZodObject<{
952
+ type: z.ZodLiteral<"update">;
953
+ at: z.ZodNumber;
954
+ line: z.ZodString;
955
+ }, z.core.$strict>, z.ZodObject<{
956
+ type: z.ZodLiteral<"claim">;
957
+ at: z.ZodNumber;
958
+ jobId: z.ZodString;
959
+ site: z.ZodOptional<z.ZodString>;
960
+ kind: z.ZodString;
961
+ audience: z.ZodString;
962
+ }, z.core.$strict>, z.ZodObject<{
963
+ type: z.ZodLiteral<"prompt">;
964
+ at: z.ZodNumber;
965
+ origin: z.ZodString;
966
+ jobId: z.ZodString;
967
+ site: z.ZodOptional<z.ZodString>;
968
+ kind: z.ZodString;
969
+ audience: z.ZodString;
970
+ owner: z.ZodString;
971
+ backendId: z.ZodString;
972
+ backendClass: z.ZodString;
973
+ model: z.ZodString;
974
+ promptHash: z.ZodString;
975
+ promptChars: z.ZodNumber;
976
+ prompt: z.ZodOptional<z.ZodString>;
977
+ }, z.core.$strict>, z.ZodObject<{
978
+ type: z.ZodLiteral<"outcome">;
979
+ at: z.ZodNumber;
980
+ jobId: z.ZodString;
981
+ site: z.ZodOptional<z.ZodString>;
982
+ outcome: z.ZodEnum<{
983
+ error: "error";
984
+ canceled: "canceled";
985
+ ok: "ok";
986
+ refused: "refused";
987
+ }>;
988
+ durationMs: z.ZodOptional<z.ZodNumber>;
989
+ spawnMs: z.ZodOptional<z.ZodNumber>;
990
+ firstOutputMs: z.ZodOptional<z.ZodNumber>;
991
+ outputChars: z.ZodOptional<z.ZodNumber>;
992
+ detail: z.ZodOptional<z.ZodString>;
993
+ stop: z.ZodOptional<z.ZodEnum<{
994
+ length: "length";
995
+ unknown: "unknown";
996
+ end: "end";
997
+ "stop-sequence": "stop-sequence";
998
+ "tool-budget": "tool-budget";
999
+ }>>;
1000
+ stopKind: z.ZodOptional<z.ZodEnum<{
1001
+ declared: "declared";
1002
+ unavailable: "unavailable";
1003
+ unverified: "unverified";
1004
+ }>>;
1005
+ brake: z.ZodOptional<z.ZodEnum<{
1006
+ "hourly-cap": "hourly-cap";
1007
+ "daily-cap": "daily-cap";
1008
+ "payload-too-large": "payload-too-large";
1009
+ "ledger-untrusted": "ledger-untrusted";
1010
+ "image-bytes": "image-bytes";
1011
+ }>>;
1012
+ }, z.core.$strict>, z.ZodObject<{
1013
+ type: z.ZodLiteral<"memory">;
1014
+ at: z.ZodNumber;
1015
+ jobId: z.ZodOptional<z.ZodString>;
1016
+ backendId: z.ZodString;
1017
+ admit: z.ZodBoolean;
1018
+ why: z.ZodString;
1019
+ availableBytes: z.ZodOptional<z.ZodNumber>;
1020
+ totalBytes: z.ZodOptional<z.ZodNumber>;
1021
+ swapFreeBytes: z.ZodOptional<z.ZodNumber>;
1022
+ swapTotalBytes: z.ZodOptional<z.ZodNumber>;
1023
+ pressure: z.ZodEnum<{
1024
+ normal: "normal";
1025
+ warn: "warn";
1026
+ critical: "critical";
1027
+ unknown: "unknown";
1028
+ }>;
1029
+ }, z.core.$strict>, z.ZodObject<{
1030
+ type: z.ZodLiteral<"tool-call">;
1031
+ at: z.ZodNumber;
1032
+ jobId: z.ZodString;
1033
+ site: z.ZodOptional<z.ZodString>;
1034
+ audience: z.ZodString;
1035
+ callId: z.ZodString;
1036
+ seq: z.ZodNumber;
1037
+ name: z.ZodString;
1038
+ argumentsHash: z.ZodString;
1039
+ argumentsChars: z.ZodNumber;
1040
+ arguments: z.ZodOptional<z.ZodString>;
1041
+ }, z.core.$strict>, z.ZodObject<{
1042
+ type: z.ZodLiteral<"tool-outcome">;
1043
+ at: z.ZodNumber;
1044
+ jobId: z.ZodString;
1045
+ site: z.ZodOptional<z.ZodString>;
1046
+ callId: z.ZodString;
1047
+ seq: z.ZodNumber;
1048
+ outcome: z.ZodEnum<{
1049
+ refused: "refused";
1050
+ answered: "answered";
1051
+ errored: "errored";
1052
+ timedOut: "timedOut";
1053
+ }>;
1054
+ chars: z.ZodOptional<z.ZodNumber>;
1055
+ contentHash: z.ZodOptional<z.ZodString>;
1056
+ detail: z.ZodOptional<z.ZodString>;
1057
+ }, z.core.$strict>, z.ZodObject<{
1058
+ type: z.ZodLiteral<"tool-dropped">;
1059
+ at: z.ZodNumber;
1060
+ jobId: z.ZodString;
1061
+ site: z.ZodOptional<z.ZodString>;
1062
+ callId: z.ZodOptional<z.ZodString>;
1063
+ why: z.ZodString;
1064
+ }, z.core.$strict>], "type">;
1065
+ type IngressEntry = z.infer<typeof IngressEntry>;
1066
+ interface IngressOptions {
1067
+ readonly path: string;
1068
+ /** Days to keep a community prompt in full before reducing it to its hash. */
1069
+ readonly communityPromptDays: number;
1070
+ /** Whether to record the owner's own prompts in full. */
1071
+ readonly keepSelfPrompts: boolean;
1072
+ }
1115
1073
  /**
1116
- * Budgets applied to jobs whose owner is not this machine's owner
1117
- * ({@link MUSTS.COMMUNITY_BUDGETS}).
1074
+ * The append-only record of every prompt that has run on this machine.
1075
+ *
1076
+ * byollm_002 calls the meter the product's soul. This is it: one JSONL file
1077
+ * the owner can read, grep and delete, written before execution rather than
1078
+ * after.
1118
1079
  */
1119
- declare const CommunityBudget: z.ZodObject<{
1120
- maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
1121
- maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
1122
- maxWallClockMs: z.ZodDefault<z.ZodNumber>;
1123
- maxOutputBytes: z.ZodDefault<z.ZodNumber>;
1124
- maxPayloadChars: z.ZodDefault<z.ZodNumber>;
1125
- countTeamJobs: z.ZodDefault<z.ZodBoolean>;
1126
- maxImageBytes: z.ZodDefault<z.ZodNumber>;
1127
- }, z.core.$strict>;
1128
- type CommunityBudget = z.infer<typeof CommunityBudget>;
1129
- /** Ingress-log retention (byollm_004 Rev 1). */
1130
- declare const IngressRetention: z.ZodObject<{
1131
- communityPromptDays: z.ZodDefault<z.ZodNumber>;
1132
- keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
1133
- }, z.core.$strict>;
1134
- type IngressRetention = z.infer<typeof IngressRetention>;
1135
- /** Ceilings applied to every job, community or not. */
1136
- declare const Limits: z.ZodObject<{
1137
- maxWallClockMs: z.ZodDefault<z.ZodNumber>;
1138
- maxOutputBytes: z.ZodDefault<z.ZodNumber>;
1139
- }, z.core.$strict>;
1140
- type Limits = z.infer<typeof Limits>;
1141
- declare const DaemonConfig: z.ZodObject<{
1142
- version: z.ZodDefault<z.ZodLiteral<1>>;
1143
- services: z.ZodRecord<z.ZodString, z.ZodObject<{
1144
- type: z.ZodEnum<{
1145
- ollama: "ollama";
1146
- mlx: "mlx";
1147
- llamacpp: "llamacpp";
1148
- vllm: "vllm";
1149
- lmstudio: "lmstudio";
1150
- jan: "jan";
1151
- localai: "localai";
1152
- anthropic: "anthropic";
1153
- openai: "openai";
1154
- gemini: "gemini";
1155
- grok: "grok";
1156
- groq: "groq";
1157
- openrouter: "openrouter";
1158
- together: "together";
1159
- deepseek: "deepseek";
1160
- mistral: "mistral";
1161
- "openai-http": "openai-http";
1162
- "claude-cli": "claude-cli";
1163
- "codex-cli": "codex-cli";
1164
- }>;
1165
- baseUrl: z.ZodOptional<z.ZodString>;
1166
- model: z.ZodString;
1167
- kinds: z.ZodArray<z.ZodEnum<{
1168
- "llm.tools": "llm.tools";
1169
- "llm.generate": "llm.generate";
1170
- "llm.chat": "llm.chat";
1171
- "llm.vision": "llm.vision";
1172
- "llm.image": "llm.image";
1173
- }>>;
1174
- offer: z.ZodDefault<z.ZodEnum<{
1175
- private: "private";
1176
- team: "team";
1177
- }>>;
1178
- apiKeyEnv: z.ZodOptional<z.ZodString>;
1179
- spend: z.ZodOptional<z.ZodObject<{
1180
- acknowledged: z.ZodDefault<z.ZodBoolean>;
1181
- dailyCapCents: z.ZodOptional<z.ZodNumber>;
1182
- centsPerMillionTokens: z.ZodDefault<z.ZodNumber>;
1183
- }, z.core.$strict>>;
1184
- images: z.ZodOptional<z.ZodObject<{
1185
- sizes: z.ZodPrefault<z.ZodObject<{
1186
- square: z.ZodDefault<z.ZodString>;
1187
- portrait: z.ZodDefault<z.ZodString>;
1188
- landscape: z.ZodDefault<z.ZodString>;
1189
- }, z.core.$strict>>;
1190
- maxImagesPerJob: z.ZodDefault<z.ZodNumber>;
1191
- probeSize: z.ZodOptional<z.ZodString>;
1192
- }, z.core.$strict>>;
1193
- }, z.core.$strict>>;
1194
- defaults: z.ZodPrefault<z.ZodRecord<z.ZodEnum<{
1195
- "llm.tools": "llm.tools";
1196
- "llm.generate": "llm.generate";
1197
- "llm.chat": "llm.chat";
1198
- "llm.vision": "llm.vision";
1199
- "llm.image": "llm.image";
1200
- }> & z.core.$partial, z.ZodString>>;
1201
- concurrency: z.ZodDefault<z.ZodNumber>;
1202
- autoUpdate: z.ZodDefault<z.ZodBoolean>;
1203
- updateAuthority: z.ZodOptional<z.ZodString>;
1204
- minAvailableMemoryBytes: z.ZodDefault<z.ZodNumber>;
1205
- community: z.ZodPrefault<z.ZodObject<{
1206
- maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
1207
- maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
1208
- maxWallClockMs: z.ZodDefault<z.ZodNumber>;
1209
- maxOutputBytes: z.ZodDefault<z.ZodNumber>;
1210
- maxPayloadChars: z.ZodDefault<z.ZodNumber>;
1211
- countTeamJobs: z.ZodDefault<z.ZodBoolean>;
1212
- maxImageBytes: z.ZodDefault<z.ZodNumber>;
1213
- }, z.core.$strict>>;
1214
- ingress: z.ZodPrefault<z.ZodObject<{
1215
- communityPromptDays: z.ZodDefault<z.ZodNumber>;
1216
- keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
1217
- }, z.core.$strict>>;
1218
- limits: z.ZodPrefault<z.ZodObject<{
1219
- maxWallClockMs: z.ZodDefault<z.ZodNumber>;
1220
- maxOutputBytes: z.ZodDefault<z.ZodNumber>;
1221
- }, z.core.$strict>>;
1222
- }, z.core.$strict>;
1223
- type DaemonConfig = z.infer<typeof DaemonConfig>;
1224
- /** One kind, served by one named service, ready to execute. */
1225
- interface ResolvedRoute {
1226
- readonly kind: z.infer<typeof JobKind>;
1080
+ declare class IngressLog {
1081
+ #private;
1082
+ constructor(options: IngressOptions);
1083
+ /** Record a claim — see {@link ClaimEntry}. */
1084
+ recordClaim(input: {
1085
+ at: number;
1086
+ jobId: string;
1087
+ site?: string;
1088
+ kind: string;
1089
+ audience: Audience;
1090
+ }): Promise<void>;
1091
+ /** Record a prompt. Await this before starting the backend call. */
1092
+ recordPrompt(input: {
1093
+ at: number;
1094
+ origin: string;
1095
+ jobId: string;
1096
+ site?: string;
1097
+ kind: string;
1098
+ audience: Audience;
1099
+ owner: string;
1100
+ backendId: string;
1101
+ backendClass: string;
1102
+ model: string;
1103
+ prompt: string;
1104
+ }): Promise<void>;
1105
+ /** Record how a job ended. */
1106
+ recordOutcome(input: {
1107
+ at: number;
1108
+ jobId: string;
1109
+ site?: string;
1110
+ outcome: OutcomeEntry["outcome"];
1111
+ durationMs?: number;
1112
+ spawnMs?: number;
1113
+ firstOutputMs?: number;
1114
+ outputChars?: number;
1115
+ detail?: string;
1116
+ stop?: StopReason;
1117
+ stopKind?: StopReasonMapping["kind"];
1118
+ brake?: BudgetRefusal;
1119
+ }): Promise<void>;
1120
+ /** Record what the memory guard decided — B080. */
1121
+ /** A tool call, before it is sealed — see {@link ToolCallEntry}. */
1122
+ recordToolCall(input: {
1123
+ at: number;
1124
+ jobId: string;
1125
+ site?: string;
1126
+ audience: Audience;
1127
+ callId: string;
1128
+ seq: number;
1129
+ name: string;
1130
+ arguments: string;
1131
+ }): Promise<void>;
1132
+ /** How a tool call ended — see {@link ToolOutcomeEntry}. */
1133
+ recordToolOutcome(input: {
1134
+ at: number;
1135
+ jobId: string;
1136
+ site?: string;
1137
+ callId: string;
1138
+ seq: number;
1139
+ outcome: "answered" | "errored" | "timedOut" | "refused";
1140
+ /** The text the site returned, hashed and measured here, never stored. */
1141
+ content?: string;
1142
+ detail?: string;
1143
+ }): Promise<void>;
1144
+ /** A step of an update — see {@link UpdateEntry}. */
1145
+ recordUpdate(input: {
1146
+ at: number;
1147
+ line: string;
1148
+ }): Promise<void>;
1149
+ /** A result the model never saw — see {@link ToolDroppedEntry}. */
1150
+ recordToolDropped(input: {
1151
+ at: number;
1152
+ jobId: string;
1153
+ site?: string;
1154
+ callId?: string;
1155
+ why: string;
1156
+ }): Promise<void>;
1157
+ recordMemory(input: {
1158
+ at: number;
1159
+ jobId?: string;
1160
+ backendId: string;
1161
+ decision: {
1162
+ admit: boolean;
1163
+ why: string;
1164
+ };
1165
+ memory: MemoryReading;
1166
+ pressure: MemoryPressure;
1167
+ }): Promise<void>;
1168
+ /** Read the log, oldest first. Malformed lines are skipped, not fatal. */
1169
+ read(): Promise<IngressEntry[]>;
1170
+ /**
1171
+ * Apply retention: drop the text of community prompts older than the
1172
+ * window, keeping the hash, the metadata and the character count.
1173
+ *
1174
+ * byollm_004 Rev 1: a volunteer must not indefinitely retain strangers'
1175
+ * content. The hash stays, so the owner can still prove what ran.
1176
+ *
1177
+ * @returns how many entries were reduced.
1178
+ */
1179
+ applyRetention(now: number): Promise<number>;
1180
+ }
1181
+ /** SHA-256 of a prompt, hex. */
1182
+ declare function hashText(text: string): string;
1183
+ /**
1184
+ * Replace terminal control sequences before printing untrusted text.
1185
+ *
1186
+ * Model output and job payloads both reach the owner's terminal through
1187
+ * `byollm log` and `byollm status`. Text that can move the cursor or set
1188
+ * colours can forge output — the ANSI/log-injection row of byollm_004 §5's
1189
+ * corpus. Stored bytes stay verbatim; only the *display* is sanitised, so the
1190
+ * log remains an honest record of what actually arrived.
1191
+ *
1192
+ * Tab and newline are kept: they are legitimate content, not control.
1193
+ */
1194
+ declare function stripControlChars(text: string): string;
1195
+
1196
+ /**
1197
+ * Signing a vendor CLI in, from inside `byollm setup`.
1198
+ *
1199
+ * Two machines sat in "we thought it wasn't working" because a logged-out CLI
1200
+ * only produced a *note*: setup found the binary, said it could not answer
1201
+ * yet, wrote the config anyway and moved on. The config was right — nothing
1202
+ * routes until it answers — and the person was not stopped at the one moment
1203
+ * they were sitting in front of a terminal ready to fix it.
1204
+ *
1205
+ * ## One terminal, because that is what a hosted console has
1206
+ *
1207
+ * The obvious shape is "open another terminal and log in there", and it is
1208
+ * wrong for the place this has to work: a hosted device's console is one
1209
+ * window, and so is an SSH session. The shell-job-control version — background
1210
+ * setup, run the CLI, `fg` — needs job control a child process does not own.
1211
+ *
1212
+ * So setup spawns the login itself with the TTY inherited. The vendor CLI
1213
+ * takes over the terminal, does whatever it does, exits, and setup re-probes.
1214
+ *
1215
+ * ## Verified against the shipped CLIs, not assumed
1216
+ *
1217
+ * The ruling allowed for "a direct login subcommand if one exists, else
1218
+ * interactive plus a `/exit` instruction". Both have one, which is better than
1219
+ * the fallback in every way — it exits by itself when the login finishes,
1220
+ * rather than depending on somebody typing the right thing to come back:
1221
+ *
1222
+ * claude claude auth login (also: claude auth status)
1223
+ * codex codex login --device-auth (also: codex login status)
1224
+ *
1225
+ * Checked by running them, per the FIXED_ARGV precedent. `claude login` is not
1226
+ * a command; `claude auth login` is. Guessing the first would have produced a
1227
+ * gate that always failed, on the path a new person meets first.
1228
+ *
1229
+ * **`--device-auth` since B148, and the table said `codex login` for one
1230
+ * commit after the code stopped.** That flow opens a localhost OAuth callback,
1231
+ * so on any machine without a browser and a loopback listener it does not fail
1232
+ * — it **hangs**. A summary whose authority is *"we ran these"*, listing a
1233
+ * command removed **because it hangs**, is worse than an unverified one; and
1234
+ * it is the first thing a reader of this file meets.
1235
+ *
1236
+ * The rule it breaks is instruction 20's corollary one scope down: a ruling is
1237
+ * not landed until the code matches it, and a file's own header is code's
1238
+ * nearest neighbour.
1239
+ *
1240
+ * ## Except on Windows, where the spawn cannot work — ruled 2026-09-04
1241
+ *
1242
+ * An npm-installed `claude` on Windows is `claude.cmd`, and Node will not
1243
+ * spawn a `.cmd` without a shell: since the CVE-2024-27980 fix (18.20/20.12)
1244
+ * it throws EINVAL, and before that ENOENT. {@link runLogin} is built to
1245
+ * swallow that — "cannot spawn" and "exited nonzero" are the same outcome to
1246
+ * the caller — so Kevin got three rounds of "Opening Claude's sign-in now"
1247
+ * followed by "Still cannot answer", with nothing opening and no error ever
1248
+ * printed. Two defensible designs composing into a silent loop.
1249
+ *
1250
+ * Todd ruled: on Windows do not spawn at all. Print the command, prominently,
1251
+ * and let the person run it. {@link loginPlan} is where that decision lives,
1252
+ * so it is made once and is testable without a platform to run on.
1253
+ */
1254
+ /** How a backend's CLI is signed in, when it has a way. */
1255
+ interface LoginCommand {
1256
+ readonly argv: readonly [string, ...string[]];
1257
+ /** What to tell somebody before the terminal stops being ours. */
1258
+ readonly says: string;
1259
+ }
1260
+
1261
+ /**
1262
+ * Where the daemon keeps its state.
1263
+ *
1264
+ * One directory the owner can `ls`, `cat` and delete. The trust surface is
1265
+ * the product (byollm_002), and a trust surface you cannot find is not one.
1266
+ */
1267
+ interface DaemonPaths {
1268
+ /** `~/.byollm` — everything below lives here. */
1269
+ readonly root: string;
1270
+ /** Job routing and backend configuration, owner-authored. */
1271
+ readonly config: string;
1272
+ /** Paired servers: origin, runner id, token, owner. */
1273
+ readonly pairings: string;
1274
+ /** The local `team` allowlist — one file, every app. */
1275
+ readonly allowlist: string;
1276
+ /** Append-only JSONL: every prompt that has run on this machine. */
1277
+ readonly ingressLog: string;
1278
+ /** Community-job counters, for rate limits and the daily cap. */
1279
+ readonly budgets: string;
1280
+ /** Estimated money spent running other people's work on metered backends. */
1281
+ readonly spend: string;
1282
+ /**
1283
+ * Grant ids this device has already admitted — byollm-review 2026-08-27.
1284
+ *
1285
+ * On disk because a grant stays valid for two minutes and a supervised
1286
+ * restart takes about one, so an in-process set was empty exactly when it
1287
+ * was still needed. Holds only unexpired ids, so it stays small on its own.
1288
+ */
1289
+ readonly spentGrants: string;
1290
+ /**
1291
+ * This machine's device keypairs (byollm_009 §3). The most sensitive file
1292
+ * the daemon writes: it is the machine's identity, not a token a server can
1293
+ * revoke and reissue.
1294
+ */
1295
+ readonly keys: string;
1296
+ /**
1297
+ * What the last probe learned about each service — the owner's copy.
1298
+ *
1299
+ * Written by whoever ran the probe, read by `byollm status`, which is a
1300
+ * different process and must not spend a model call of its own to answer
1301
+ * "how are my services". A canary on a metered backend costs real money,
1302
+ * and `status` is a command people run often.
1303
+ *
1304
+ * Latest state only, never a history: this answers "where does this stand
1305
+ * now", and a log of every probe would be a log of when somebody's token
1306
+ * lapsed, which is nobody's business including ours.
1307
+ */
1308
+ readonly serviceStates: string;
1309
+ /**
1310
+ * The image probes' verdicts — byollm_021 §5. The image probe is a paid
1311
+ * call on a metered backend, so its answer is kept for 24 hours and shared
1312
+ * by every process that would otherwise ask again.
1313
+ */
1314
+ readonly imageProbes: string;
1315
+ /**
1316
+ * How the daemon's last conversation with an upstream went.
1317
+ *
1318
+ * Written by the running daemon, read by `byollm status`, which otherwise
1319
+ * cannot ask it anything: the two are separate processes and `state:
1320
+ * running` was derived from a local flag alone. That sentence was true
1321
+ * for hours while every heartbeat this device sent was refused — the
1322
+ * daemon was running and reporting nothing, and the only surface that knew
1323
+ * was a log line nobody tails.
1324
+ *
1325
+ * A file rather than a socket because the question is small and the answer
1326
+ * survives a restart of either side.
1327
+ */
1328
+ readonly health: string;
1329
+ /** Liveness, rewritten every beat — B202. */
1330
+ readonly heartbeat: string;
1331
+ /** Who keeps this device running when it is not a service — #8404. */
1332
+ readonly supervisor: string;
1333
+ /**
1334
+ * What this machine calls itself when it pairs.
1335
+ *
1336
+ * Its own file rather than a field in `config.json`, because that file is
1337
+ * routing and backends — the things somebody edits when work is going
1338
+ * wrong — and a name is neither. A one-line file is also a thing a person
1339
+ * can `cat` when they are wondering why an approval screen said
1340
+ * `todd@Todds-Mac-Studio`.
1341
+ */
1342
+ readonly label: string;
1343
+ /**
1344
+ * Per-job scratch directories. A process-class backend runs with its `cwd`
1345
+ * set to an empty one of these and nothing else (byollm_004 §2).
1346
+ */
1347
+ readonly scratch: string;
1348
+ /**
1349
+ * An update in flight between two daemons — #9594. Written by the one
1350
+ * that installed it, just before it exits; read and removed by the next
1351
+ * one to start, which is the only process that can say what it is.
1352
+ */
1353
+ readonly lastUpdate: string;
1354
+ }
1355
+ /** Resolve the daemon's paths, rooted at `~/.byollm` unless overridden. */
1356
+ declare function daemonPaths(root?: string): DaemonPaths;
1357
+ /**
1358
+ * `BYOLLM_HOME` is a TEST SEAM. Ruled 09-15 (B205): always or never, never
1359
+ * "sometimes" — and it stays, explicitly scoped and loud rather than silent.
1360
+ *
1361
+ * It exists so the conformance kit and the adversarial suite can run real
1362
+ * daemons without touching the developer's own `~/.byollm`; `edges.test.ts:48`
1363
+ * asserts exactly that. **On a person's own machine, a set `BYOLLM_HOME` is a
1364
+ * bug**, and {@link overriddenRootNotice} is what stops that being silent.
1365
+ *
1366
+ * One deliberate exception, and it is not a person's machine: the box
1367
+ * supervisor STATES this variable to the daemon it spawns (`boxDaemon`, B204's
1368
+ * rider) so that PID 1 and the daemon cannot disagree about where the heartbeat
1369
+ * file lives. It sets it to this same default, which is why the notice below
1370
+ * asks whether the root has actually MOVED rather than whether the variable
1371
+ * exists — see there.
1372
+ */
1373
+ declare function defaultRoot(): string;
1374
+
1375
+ /**
1376
+ * One sentence about a service, for the three surfaces its owner reads.
1377
+ *
1378
+ * Your Devices, `byollm status`, and the daemon's own output all answer the
1379
+ * same question — can this thing do its job, and if not what do I run — so
1380
+ * they say it in one string rather than three that drift.
1381
+ *
1382
+ * The person this is for is the owner, and only the owner. A site gets a class
1383
+ * and a fixed sentence and never this; the CLI's own words quote paths,
1384
+ * usernames and account emails, and they name which backend answered, which
1385
+ * is what the disclosure fence exists to prevent.
1386
+ */
1387
+ /** What asking the backend produced. */
1388
+ type ServiceState =
1389
+ /** Ran a real call and answered. */
1390
+ {
1391
+ readonly kind: "answers";
1392
+ readonly model: string;
1393
+ }
1394
+ /** The binary is there; the credentials are not. */
1395
+ | {
1396
+ readonly kind: "signed-out";
1397
+ readonly detail?: string | undefined;
1398
+ }
1399
+ /** The config names a binary this machine does not have. */
1400
+ | {
1401
+ readonly kind: "missing";
1402
+ }
1403
+ /**
1404
+ * Installed here, not running, and startable — B056 / D4.
1405
+ *
1406
+ * Advertised, unlike `missing`, because it IS available: one spawn away,
1407
+ * and the daemon starts it when a job arrives (B050). Its own kind rather
1408
+ * than reusing `missing` or `unknown`, because this is the one state where
1409
+ * the machine ADVERTISES the service — and a service advertised while
1410
+ * `status` calls it "not found on this device" is a machine disagreeing
1411
+ * with itself on two screens.
1412
+ */
1413
+ /**
1414
+ * Stopped, and nothing here knows how to start it — B098.
1415
+ *
1416
+ * Distinct from `missing`, which means the program is not on this machine.
1417
+ * Conflating them told an owner to install software that was already
1418
+ * installed, which is an afternoon spent on a fix that was never the
1419
+ * problem.
1420
+ */
1421
+ | {
1422
+ readonly kind: "unstartable";
1423
+ readonly model: string;
1424
+ /**
1425
+ * The type byollm WOULD start at this service's address — B098's offer,
1426
+ * carried to the screen people look at.
1427
+ *
1428
+ * Todd, 10-05, after a reboot: `glm-5.2` is `openai-http` at
1429
+ * `127.0.0.1:11434`, and this line told him only "start it yourself".
1430
+ * He read it as on-demand start having broken. It had not — only
1431
+ * `type: "ollama"` is ever started, ruled 09-10, offered not inferred —
1432
+ * and `byollm diagnose` already printed the one-field fix. `status`
1433
+ * did not, and `status` is what people read.
1434
+ *
1435
+ * Set by the daemon from `startableAt` (local-server.ts), the same function
1436
+ * diagnose asks, and only when that provider is installed here: an
1437
+ * offer to retype a service into one that would then read "not found"
1438
+ * is a remedy that moves the problem. Optional, and absent means no
1439
+ * offer — a file written before this field existed says what it always
1440
+ * said.
1441
+ */
1442
+ readonly startableAs?: BackendId | undefined;
1443
+ } | {
1444
+ readonly kind: "stopped";
1445
+ readonly model: string;
1446
+ /**
1447
+ * Whether anything on this device will actually start it — B087.
1448
+ *
1449
+ * The comment above says "the daemon starts it when a job arrives
1450
+ * (B050)", and until this field existed that was not true: the starter
1451
+ * is behind a `spawnServer` seam nothing passes, so a stopped server
1452
+ * was advertised and a job routed to it reached nothing listening —
1453
+ * the claimed-then-failed outcome B056's own ruling forbids.
1454
+ *
1455
+ * Optional, and absent means NO. `byollm status` is a different
1456
+ * process reading what the daemon wrote, so a file written before this
1457
+ * field existed is read by a daemon that has it — and the honest
1458
+ * default for "I cannot tell whether anything starts this" is not to
1459
+ * promise that something will.
1460
+ */
1461
+ readonly starts?: boolean | undefined;
1462
+ }
1463
+ /**
1464
+ * Signed in, healthy, and out of quota until further notice — 019 §3.2.
1465
+ *
1466
+ * Its own state because its remedy is the opposite of signed-out's: this
1467
+ * one needs **time and nothing else**, and there is nothing for the owner
1468
+ * to go and do. Rendering it as "needs sign-in" would send somebody to a
1469
+ * terminal to fix an account that is working perfectly.
1470
+ */
1471
+ | {
1472
+ readonly kind: "blocked";
1473
+ readonly detail?: string | undefined;
1474
+ /** Epoch ms the CLI expects to be back, when it said so. */
1475
+ readonly until?: number | undefined;
1476
+ }
1477
+ /**
1478
+ * Nobody asked, because there was nothing to ask with.
1479
+ *
1480
+ * Not a failure and not a success. A backend with no canary — an HTTP model
1481
+ * server, say — has no credentials of its own to check, and rendering this
1482
+ * as "cannot answer" would tell every local-server owner their model was
1483
+ * broken. Not asked is not no, the same way an empty variable is not a
1484
+ * configured one.
1485
+ */
1486
+ | {
1487
+ readonly kind: "unknown";
1488
+ readonly model: string;
1489
+ };
1490
+ /**
1491
+ * A service's state plus the remedy its backend supplies.
1492
+ *
1493
+ * Kept together because they are learned together — at probe time, from the
1494
+ * backend instance that knows both — and needed together, by every surface
1495
+ * that renders a line. A caller looking the remedy up later would be looking
1496
+ * it up from somewhere that does not know which backend this service used.
1497
+ */
1498
+ interface ServiceReport {
1499
+ readonly state: ServiceState;
1500
+ readonly signIn?: string | undefined;
1501
+ }
1502
+
1503
+ /** Build the child's environment from the allowlist. */
1504
+ declare function childEnv(source?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Record<string, string>;
1505
+ /** The argv this backend would run for a given model. Exported for the suite. */
1506
+ declare function claudeArgv(model: string): readonly string[];
1507
+ /**
1508
+ * The process-class backend: the user's own `claude` CLI, on their own
1509
+ * subscription.
1510
+ *
1511
+ * Subscription-class, so its offer scope is locked to `private`
1512
+ * ({@link MUSTS.SUBSCRIPTION_SELF_LOCK}) — one account runs one person's work.
1513
+ *
1514
+ * Every requirement of byollm_004 §2 applies here and is implemented here:
1515
+ * fixed argv, prompt on stdin, stripped environment, empty scratch `cwd`, no
1516
+ * inherited descriptors beyond the three std streams, hard timeout, hard
1517
+ * output cap.
1518
+ */
1519
+ declare class ClaudeCliBackend implements Backend {
1520
+ #private;
1227
1521
  /**
1228
- * The owner's name for the service serving this kind.
1522
+ * Nothing to read — checked, not assumed (byollm_021).
1229
1523
  *
1230
- * Carried onto the wire in the capability matrix, so a device advertises
1231
- * *which* of its services answers a kind rather than only that something
1232
- * does. Phase B lets a job select by this name.
1524
+ * {@link FIXED_ARGV} runs `--output-format text`, and text is exactly what
1525
+ * comes back: an answer with no envelope around it, deliberately, because
1526
+ * an envelope is a thing to misparse. So there is no field carrying a stop
1527
+ * reason and no amount of parsing invents one.
1528
+ *
1529
+ * `--output-format json` would very likely carry it. Changing the frozen
1530
+ * argv is not a thing to do inside a mapping declaration: that argv is what
1531
+ * the adversarial suite asserts every hostile payload produces, and moving
1532
+ * it is its own decision with its own review.
1233
1533
  */
1234
- readonly service: string;
1534
+ readonly stopReasons: StopReasonMapping;
1535
+ readonly id: BackendId;
1536
+ readonly class: BackendClass;
1537
+ readonly signIn = "run `claude` in a terminal";
1235
1538
  /**
1236
- * Whether this is the service an *unselected* job for this kind reaches.
1539
+ * @param binary - which executable to run. Defaults to `claude` and is
1540
+ * **not reachable from configuration**: {@link createBackend} constructs
1541
+ * this with no arguments, and {@link BackendInit} has no field for it. It
1542
+ * exists so the adversarial suite can substitute a probe that reports the
1543
+ * argv, environment, cwd and stdin it actually received — which is the only
1544
+ * way to *prove* byollm_004 §2 rather than assert it.
1545
+ */
1546
+ constructor(binary?: string);
1547
+ /**
1548
+ * One real, tiny call — the only way to learn whether credentials work.
1237
1549
  *
1238
- * Phase B advertises the whole menu, so a kind may have several routes and
1239
- * exactly one of them is where a job that named nothing goes. Stated rather
1240
- * than inferred from position: the previous shape advertised only the
1241
- * winner, so "the route for this kind" and "the default for this kind" were
1242
- * the same object, and every consumer that took the first match was correct
1243
- * by accident.
1550
+ * `--version` answers "is the binary here", which was never the question.
1551
+ * This asks the question, and pays for it: a handful of tokens against the
1552
+ * owner's own subscription, at daemon start rather than on every heartbeat.
1244
1553
  *
1245
- * False for a kind that is withheld — nothing is the default there, which
1246
- * is the whole meaning of withheld.
1554
+ * A failure here is reported rather than thrown, and the runner treats an
1555
+ * `unauthorized` exactly as it treats one from a real job — the service is
1556
+ * withdrawn and the owner is told once.
1247
1557
  */
1248
- readonly isDefault: boolean;
1249
- readonly backendId: BackendId;
1250
- readonly backendClass: "http" | "process";
1251
- readonly model: string;
1252
- /** Who pays for this route's tokens. From the registry, never from config. */
1253
- readonly cost: BackendCost;
1254
- /** After the cost rules are applied — never the raw configured value. */
1255
- readonly offerScope: z.infer<typeof OfferScope>;
1256
- /** The owner's spend consent, for a `metered` route. */
1257
- readonly spendAcknowledged: boolean;
1258
- readonly spendDailyCapCents: number | undefined;
1259
- readonly spendCentsPerMillionTokens: number;
1260
- readonly baseUrl: string | undefined;
1261
- readonly apiKeyEnv: string | undefined;
1262
- }
1263
- interface ConfigProblem {
1264
- readonly where: string;
1265
- readonly message: string;
1266
- }
1267
- /**
1268
- * A kind this device could serve and deliberately does not.
1269
- *
1270
- * Withholding has to be *loud on the owner's side*, in every surface that
1271
- * could otherwise show absence. An owner who adds a second `llm.generate`
1272
- * service and finds their team's jobs quietly stop matching, with nothing
1273
- * anywhere saying why, has been failed by the correct behaviour — which is
1274
- * the quiet kind of correct this project keeps deleting.
1275
- */
1276
- interface WithheldKind {
1277
- readonly kind: z.infer<typeof JobKind>;
1278
- /** The services that answer it, any of which the owner could name. */
1279
- readonly services: readonly string[];
1558
+ canary(model: string): Promise<BackendHealth>;
1559
+ health(): Promise<BackendHealth>;
1560
+ execute(request: BackendRequest): Promise<BackendResult>;
1280
1561
  }
1281
- interface LoadedConfig {
1282
- readonly config: DaemonConfig;
1283
- readonly routes: readonly ResolvedRoute[];
1284
- /** Kinds not advertised because the owner has not said which service wins. */
1285
- readonly withheld: readonly WithheldKind[];
1562
+
1563
+ declare class OpenAiHttpBackend implements Backend {
1564
+ #private;
1565
+ readonly stopReasons: StopReasonMapping;
1566
+ readonly id: BackendId;
1567
+ readonly class: BackendClass;
1568
+ constructor(init: BackendInit);
1569
+ health(): Promise<BackendHealth>;
1570
+ execute(request: BackendRequest): Promise<BackendResult>;
1286
1571
  /**
1287
- * What this build cannot yet do, in the owner's words.
1572
+ * One turn of a function-calling conversation — byollm_012 §7.
1288
1573
  *
1289
- * Separate from `problems` on purpose: a problem means the config says
1290
- * something wrong and something was dropped. A notice means the config is
1291
- * fine and *the build* is behind it. Folding the two would make every
1292
- * limitation read as an owner's mistake — and would make a genuine mistake
1293
- * easier to miss among them.
1574
+ * The declarations go to the model as OpenAI `tools`; the calls it asks for
1575
+ * come back as text. Nothing here runs one, opens anything or reaches
1576
+ * anywhere but this service's own configured `chat/completions` — the tool
1577
+ * loop seals each call to the site that declared it.
1294
1578
  */
1295
- readonly notices: readonly string[];
1296
- /** Non-fatal problems: a route that cannot be served is dropped, not fatal. */
1297
- readonly problems: readonly ConfigProblem[];
1579
+ converse(request: ConverseRequest): Promise<ConverseResult>;
1580
+ /**
1581
+ * `llm.vision` — the same `/v1/chat/completions`, with image parts as
1582
+ * `image_url` data URLs (byollm_021 §6: Ollama, llama.cpp with a projector,
1583
+ * vLLM, LM Studio, OpenAI and the compatible endpoints all take this shape).
1584
+ *
1585
+ * A data URL, never a link: the bytes are the request, so the model server
1586
+ * has nothing to fetch and neither does this daemon.
1587
+ */
1588
+ readImages(request: VisionRequest): Promise<BackendResult>;
1589
+ /**
1590
+ * `llm.image` — `/v1/images/generations`, asking for `b64_json`.
1591
+ *
1592
+ * **Bytes, never URLs** ({@link MUSTS.IMAGE_BYTES_NOT_URLS}, C056). A
1593
+ * backend that answers with `url` instead is an error, and the URL is not
1594
+ * fetched: fetching it would be this device fetching an address a backend
1595
+ * chose, which byollm_012 §11.1 holds back from v1.
1596
+ */
1597
+ makeImages(request: ImageRequest): Promise<ImageResult>;
1298
1598
  }
1299
- /** The config used when the owner has not written one. */
1300
- declare const DEFAULT_CONFIG: DaemonConfig;
1599
+
1301
1600
  /**
1302
- * Read and resolve `~/.byollm/config.json`.
1601
+ * Construct a backend instance.
1303
1602
  *
1304
- * A missing file yields {@link DEFAULT_CONFIG}; a malformed one throws,
1305
- * because silently running with defaults when the owner *did* write a config
1306
- * would execute work under rules they did not choose.
1307
- */
1308
- declare function loadConfig(path: string): Promise<LoadedConfig>;
1309
- /**
1310
- * Turn a parsed config into executable routes, applying the subscription lock
1311
- * and rejecting unusable backends.
1603
+ * Exhaustive over {@link BackendClass}, and now actually so — cloud_008 Tier
1604
+ * 3, finding 15. The docstring used to claim "the switch is exhaustive over
1605
+ * `BackendId`, so adding a backend to the protocol registry without
1606
+ * implementing it here is a compile error", and there was no switch: an `if`
1607
+ * on `class === "process"` with everything else falling through to the HTTP
1608
+ * transport. A backend class added to the registry would have got an
1609
+ * OpenAI-compatible client and failed at runtime, in the shape the comment
1610
+ * promised was impossible.
1312
1611
  *
1313
- * A problem here is not fatal: a machine with three routes and one broken
1314
- * backend should serve the other two and say so, rather than refusing to
1315
- * start. What it must never do is *advertise* the broken one
1316
- * ({@link MUSTS.CAPABILITY_IS_DETECTED}).
1612
+ * The `never` assignment is what makes the claim true. It costs one line and
1613
+ * fails at compile time in the file that has to change.
1614
+ *
1615
+ * Providers are still registry entries rather than implementations
1616
+ * (byollm_007 §3): every HTTP-class id speaks the same
1617
+ * `/v1/chat/completions`, so they share one transport and one adversarial
1618
+ * corpus. Adding a *provider* is a line in the registry. Adding a *class* is
1619
+ * this function.
1317
1620
  */
1318
- declare function resolveConfig(config: DaemonConfig): LoadedConfig;
1621
+ declare function createBackend(id: BackendId, init: BackendInit): Backend;
1319
1622
 
1320
1623
  /**
1321
- * The caps this class enforces. `countTeamJobs` is not one of them: whether a
1322
- * job is counted is the runner's question, asked per job, and answered here
1323
- * through `check`'s `counted`.
1324
- */
1325
- type Caps = Omit<CommunityBudget, "countTeamJobs" | "maxImageBytes">;
1326
- /** Which brake refused a community job — written to the ingress log. */
1327
- declare const BudgetRefusal: z.ZodEnum<{
1328
- "hourly-cap": "hourly-cap";
1329
- "daily-cap": "daily-cap";
1330
- "payload-too-large": "payload-too-large";
1331
- "ledger-untrusted": "ledger-untrusted";
1332
- "image-bytes": "image-bytes";
1333
- }>;
1334
- type BudgetRefusal = z.infer<typeof BudgetRefusal>;
1335
- type BudgetDecision = {
1336
- readonly ok: true;
1337
- } | {
1338
- readonly ok: false;
1339
- readonly refusal: BudgetRefusal;
1340
- readonly detail: string;
1341
- };
1342
- /**
1343
- * The owner's ceiling on work done for other people
1344
- * ({@link MUSTS.COMMUNITY_BUDGETS}).
1624
+ * Grants this device has already admitted — byollm-review 2026-08-27.
1345
1625
  *
1346
- * byollm_004 §4 distinguishes two directions of abuse, and this is the one
1347
- * aimed *at* the volunteer: a stranger who can enqueue unlimited `public`
1348
- * jobs owns your GPU. Jobs for the machine's own owner are never counted —
1349
- * their machine, their call.
1626
+ * A grant admits one job, once. That was enforced by a `Map` that lived only
1627
+ * in the process, defended in a comment: "an entry can only matter for as
1628
+ * long as the grant naming it is still fresh, and a device that has restarted
1629
+ * since is past that window anyway."
1630
+ *
1631
+ * The second half is false, and it is the half the argument rests on.
1632
+ * {@link GRANT_MAX_AGE_MS} is two minutes; a supervised restart — systemd, a
1633
+ * crash loop, a deploy — completes in about a second. So the window is not
1634
+ * "past" at all: the set comes back empty while the grant is still perfectly
1635
+ * fresh, and a relay that re-delivers the same stub gets a second admission
1636
+ * and a second execution. Double-spend of somebody's metered backend, or
1637
+ * duplicated side effects, on work that was already done.
1638
+ *
1639
+ * ## What durable means here, exactly
1640
+ *
1641
+ * Written with a **synchronous** write, and that is the whole mechanism. The
1642
+ * threat is a process that dies and is restarted by a supervisor, which is
1643
+ * survived the moment the bytes reach the operating system — the page cache
1644
+ * outlives the process. It is not `fsync`, so a machine losing power between
1645
+ * the write and the flush can still forget. That is a worse failure with a
1646
+ * far smaller window, and paying an `fsync` per admitted job to close it
1647
+ * would put disk latency in front of every claim.
1648
+ *
1649
+ * Synchronous rather than awaited because {@link Runner.admit} answers
1650
+ * synchronously, and the record has to be durable *before* the job runs —
1651
+ * writing afterwards would leave exactly the gap this closes. The file holds
1652
+ * only ids that are still fresh, so it is small by construction rather than
1653
+ * by pruning policy.
1350
1654
  */
1351
- declare class Budgets {
1655
+ declare class SpentGrants {
1352
1656
  #private;
1353
- constructor(path: string, limits: Caps);
1354
1657
  /**
1355
- * Read the record of what has already been accepted.
1658
+ * Without a path this is memory-only, which is what tests want and what
1659
+ * direct mode is: no control plane, no grants, nothing to replay.
1660
+ */
1661
+ constructor(path?: string);
1662
+ /**
1663
+ * Read what survived the last run, dropping whatever has expired.
1356
1664
  *
1357
- * Every failure used to become an empty array, which reconstructs the
1358
- * counts as zero and passes both caps — the file that says "you have
1359
- * already run your hundred jobs today" and the file that will not parse
1360
- * were the same answer.
1665
+ * A file that will not parse is no longer read as "nothing spent". That
1666
+ * reading was chosen deliberately here — the comment argued that refusing
1667
+ * every grant turns a corrupt cache into a total outage — and the argument
1668
+ * is sound against refusing *forever*. It is not an argument for this,
1669
+ * because the exposure and the remedy have the same clock: an id only
1670
+ * matters while the grant naming it is still fresh, so refusing for that
1671
+ * long is all fail-closed ever needed. A torn write plus a supervised
1672
+ * restart inside a grant's window lets the same valid grant execute twice,
1673
+ * with nothing forged.
1674
+ */
1675
+ load(now: number): void;
1676
+ /**
1677
+ * Why every relayed grant is being refused, if it is.
1678
+ *
1679
+ * This is the one ledger whose brake covers the owner's own jobs too. The
1680
+ * other two count what the machine did for other people, and their brakes
1681
+ * stop exactly that. This one guards the wire: it is what stands between a
1682
+ * re-delivered stub and a second execution, and a duplicate of your own
1683
+ * metered job is still your money.
1361
1684
  */
1362
- load(now: number): Promise<void>;
1363
- /** Why community work is braked, if it is — for `byollm status`. */
1364
- untrustedReason(): string | undefined;
1685
+ blockedReason(now: number): string | undefined;
1686
+ /** Has this grant already admitted a job? */
1687
+ has(grantId: string, now: number): boolean;
1365
1688
  /**
1366
- * May this community job run?
1689
+ * Burn it, durably, and say whether that worked.
1367
1690
  *
1368
- * @param payloadChars - total payload text length, checked against the
1369
- * stricter community limit rather than the protocol's absolute ceiling.
1370
- * @param counted - whether this job counts toward the hourly and daily
1371
- * caps. `false` only for a teammate's job on a metered service the owner
1372
- * shared, which the spend ceiling already bounds — see
1373
- * {@link CommunityBudget}'s `countTeamJobs`. The payload limit applies
1374
- * either way.
1691
+ * Returns `false` when the burn is not on disk, and the caller must refuse
1692
+ * the job. This used to swallow the write failure and let the job run on
1693
+ * in-memory protection alone — which is precisely the protection that a
1694
+ * restart erases, so the case where the note fails and the case where the
1695
+ * note is needed are the same case.
1375
1696
  */
1376
- check(now: number, payloadChars: number, counted?: boolean): BudgetDecision;
1377
- /** Count a community job as accepted. Call only after {@link check} passes. */
1378
- record(now: number): Promise<void>;
1379
- /** Current usage, for `byollm status`. */
1380
- usage(now: number): {
1381
- hour: number;
1382
- day: number;
1383
- limits: Caps;
1384
- };
1697
+ spend(grantId: string, issuedAt: number, now: number): boolean;
1385
1698
  }
1386
1699
 
1387
1700
  /**
@@ -1431,540 +1744,257 @@ type ClientErrorKind = "unreachable" | "revoked" | "unauthorized" | "rejected"
1431
1744
  * The upstream holds this job for us but has no payload to give yet.
1432
1745
  *
1433
1746
  * Only reachable off the direct plane. A direct site seals when asked,
1434
- * because it holds the keys; a relay must wait for the site to seal to the
1435
- * device that claimed — so "not yet" is a normal answer there, and treating
1436
- * it as a refusal drops work the daemon legitimately still holds.
1437
- */
1438
- | "not-ready"
1439
- /**
1440
- * The upstream knows exactly who this daemon is, and is refusing anyway.
1441
- *
1442
- * Distinct from `unauthorized` (it does not know us) and from `revoked`
1443
- * (this pairing is over). A device asking about a job it does not hold, or
1444
- * an upstream that does not route for the site named, is neither of those —
1445
- * and this client used to report all three as `revoked`, because it
1446
- * dispatched on the 403 rather than on the code beside it. A daemon told it
1447
- * was revoked stops for good; that is the wrong response to a refusal that
1448
- * is about one request.
1449
- */
1450
- | "forbidden"
1451
- /**
1452
- * The job has made every tool call it is allowed — byollm_012 §8.
1453
- *
1454
- * Arrives as `forbidden`, and is told apart by the sentence beside it
1455
- * (`TOOLS_SPENT_MESSAGE`, the protocol's). Its own kind because the remedy is not a
1456
- * permission problem: the tool loop tells the model the job's tools are
1457
- * spent and goes to the closing turn. The relay's count is the job's, so
1458
- * an honest second device meets this after a lapse (#7122, #7440).
1459
- */
1460
- | "tools-spent" | "rate-limited" | "server-error" | "malformed-response";
1461
- declare class ClientError extends Error {
1462
- readonly kind: ClientErrorKind;
1463
- /** Seconds the server asked us to wait, when it said. */
1464
- readonly retryAfter?: number | undefined;
1465
- /**
1466
- * The HTTP status the upstream answered with, when it answered at all.
1467
- *
1468
- * Guard (b) decides on this and on nothing in the body (byollm_021 §R2):
1469
- * a 0.1.4 upstream's refusal names no path, and a 0.1.5 one that does
1470
- * must not be depended on, so the status is the whole of what is read.
1471
- */
1472
- readonly status?: number | undefined;
1473
- readonly name = "ClientError";
1474
- constructor(kind: ClientErrorKind, message: string,
1475
- /** Seconds the server asked us to wait, when it said. */
1476
- retryAfter?: number | undefined,
1477
- /**
1478
- * The HTTP status the upstream answered with, when it answered at all.
1479
- *
1480
- * Guard (b) decides on this and on nothing in the body (byollm_021 §R2):
1481
- * a 0.1.4 upstream's refusal names no path, and a 0.1.5 one that does
1482
- * must not be depended on, so the status is the whole of what is read.
1483
- */
1484
- status?: number | undefined);
1485
- /** Is retrying this same call plausibly useful? */
1486
- get retryable(): boolean;
1487
- }
1488
- interface ClientOptions {
1489
- /** The app's origin, e.g. `https://app.example.com`. */
1490
- readonly origin: string;
1491
- /** Bearer token from pairing. Absent while pairing. */
1492
- /**
1493
- * How this daemon proves who it is (byollm_009 §4.2).
1494
- *
1495
- * A signer rather than a key, so the client never holds private material
1496
- * and the daemon decides where keys live. Absent while pairing, which is
1497
- * the one exchange that establishes an identity rather than using one.
1498
- */
1499
- readonly identity?: {
1500
- readonly runnerId: string;
1501
- sign(input: {
1502
- endpoint: string;
1503
- runnerId: string;
1504
- issuedAt: number;
1505
- body: string;
1506
- }): Promise<string> | string;
1507
- };
1508
- /** Per-request timeout. */
1509
- readonly timeoutMs?: number;
1510
- /** Injectable fetch, for tests. */
1511
- readonly fetch?: typeof fetch;
1512
- }
1513
- /**
1514
- * The daemon's outbound protocol client.
1515
- *
1516
- * Every call is outbound; nothing here ever listens. That is the whole
1517
- * network posture of the product, and it lives in this one class.
1518
- */
1519
- declare class ProtocolClient {
1520
- #private;
1521
- constructor(options: ClientOptions);
1522
- /** A client for the same origin that signs as a given runner. */
1523
- withIdentity(identity: NonNullable<ClientOptions["identity"]>): ProtocolClient;
1524
- get origin(): string;
1525
- pairStart(input: {
1526
- version: string;
1527
- label: string;
1528
- platform: "darwin" | "linux" | "win32";
1529
- /** This machine's public keys (byollm_009 §5). */
1530
- device: PublicIdentity;
1531
- capabilities: readonly Capability[];
1532
- }): Promise<PairStartResponse>;
1533
- pairPoll(deviceCode: string): Promise<PairPollResponse>;
1534
- /**
1535
- * Collect the payload for a lease this daemon holds (byollm_009 §6).
1536
- *
1537
- * The second half of claim-then-fetch: a claim answers with a stub, and the
1538
- * work is collected by the device that took it.
1539
- */
1540
- fetch(input: {
1541
- runnerId: string;
1542
- jobId: string;
1543
- leaseId: string;
1544
- }): Promise<FetchResponse>;
1545
- claim(input: {
1546
- runnerId: string;
1547
- capabilities: readonly Capability[];
1548
- max: number;
1549
- }): Promise<ClaimResponse>;
1550
- heartbeat(input: {
1551
- runnerId: string;
1552
- daemonVersion: string;
1553
- capabilities: readonly Capability[];
1554
- /** Kinds this device could serve and is withholding — byollm_016. */
1555
- withheld?: readonly WithheldKind$1[];
1556
- activeLeases: readonly {
1557
- jobId: string;
1558
- leaseId: string;
1559
- }[];
1560
- }): Promise<HeartbeatResponse>;
1561
- result(input: {
1562
- runnerId: string;
1563
- jobId: string;
1564
- /** The grant the work was done under — cloud_008 §1.4a. */
1565
- leaseId: string;
1566
- envelope: SealedEnvelope;
1567
- disposition: ResultDisposition;
1568
- }): Promise<ResultResponse>;
1569
- release(input: {
1570
- runnerId: string;
1571
- leases: readonly {
1572
- jobId: string;
1573
- leaseId: string;
1574
- }[];
1575
- reason: "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
1576
- }): Promise<ReleaseResponse>;
1577
- /**
1578
- * Send one tool call, sealed to the job's site — byollm_012 §5.2.
1579
- *
1580
- * Lease-scoped: only the device holding the job may call for it.
1581
- */
1582
- toolCall(input: {
1583
- runnerId: string;
1584
- jobId: string;
1585
- leaseId: string;
1586
- callId: string;
1587
- envelope: SealedEnvelope;
1588
- }): Promise<ToolCallResponse>;
1589
- /**
1590
- * What the site has answered, for the calls named — byollm_012 §5.2.
1591
- *
1592
- * Each call by job, lease and id, so the read is lease-scoped like every
1593
- * other holder call.
1594
- */
1595
- toolResults(input: {
1596
- runnerId: string;
1597
- calls: readonly {
1598
- jobId: string;
1599
- leaseId: string;
1600
- callId: string;
1601
- }[];
1602
- }): Promise<ToolResultsResponse>;
1603
- /**
1604
- * A download URL for one input blob of a job whose lease this daemon holds
1605
- * — byollm_021 §2. No lease, no URL.
1606
- */
1607
- blobUrl(input: {
1608
- runnerId: string;
1609
- jobId: string;
1610
- leaseId: string;
1611
- blob: string;
1612
- }): Promise<BlobUrlResponse>;
1613
- /**
1614
- * An upload slot for one output blob of an `llm.image` job whose lease this
1615
- * daemon holds, for an object of exactly `bytes` (`blobObjectBytes`).
1616
- */
1617
- blobSlot(input: {
1618
- runnerId: string;
1619
- jobId: string;
1620
- leaseId: string;
1621
- bytes: number;
1622
- }): Promise<BlobSlotResponse>;
1623
- /**
1624
- * GET one blob's ciphertext, **stopping at `size` bytes** — byollm_021 §3,
1625
- * {@link MUSTS.BLOB_BUDGET_BEFORE_DOWNLOAD} (C052).
1626
- *
1627
- * `size` is the object size the reference declares (`blobObjectBytes`). A
1628
- * `Content-Length` over it is refused before the body is read, and a body
1629
- * that runs past it is cancelled at the first chunk that crosses it, so a
1630
- * store holding 12 MiB under a 2 MiB reference costs this device at most
1631
- * 2 MiB and one chunk — never the 12. Fewer bytes than declared is refused
1632
- * too: `decryptBlob` opens nothing but the exact size.
1633
- *
1634
- * The URL is the upstream's answer to {@link blobUrl}, a capability on
1635
- * presigned object storage or on the direct-lane server — never a URL a
1636
- * backend or a payload chose. Redirects are refused, as on every call here.
1637
- */
1638
- getBlob(url: string, size: number, signal?: AbortSignal): Promise<{
1639
- readonly ok: true;
1640
- readonly bytes: Uint8Array;
1641
- } | {
1642
- readonly ok: false;
1643
- readonly message: string;
1644
- }>;
1645
- /** PUT one output blob's ciphertext to the slot the upstream issued. */
1646
- putBlob(url: string, object: Uint8Array, signal?: AbortSignal): Promise<{
1647
- readonly ok: true;
1648
- } | {
1649
- readonly ok: false;
1650
- readonly message: string;
1651
- }>;
1652
- }
1653
-
1654
- /**
1655
- * - `passes` — the probe proved the effect.
1656
- * - `cannot` — the service answered, and not like that. Held: asking the same
1657
- * model again will not change it.
1658
- * - `unanswered` — the service did not answer (down, timed out). Not held.
1747
+ * because it holds the keys; a relay must wait for the site to seal to the
1748
+ * device that claimed — so "not yet" is a normal answer there, and treating
1749
+ * it as a refusal drops work the daemon legitimately still holds.
1659
1750
  */
1660
- type ImageProbe = {
1661
- readonly kind: "passes";
1662
- readonly at: number;
1663
- } | {
1664
- readonly kind: "cannot";
1665
- readonly why: string;
1666
- readonly at: number;
1667
- } | {
1668
- readonly kind: "unanswered";
1669
- readonly why: string;
1670
- readonly at: number;
1671
- };
1751
+ | "not-ready"
1672
1752
  /**
1673
- * Where image-probe verdicts are kept, keyed by what was asked.
1753
+ * The upstream knows exactly who this daemon is, and is refusing anyway.
1674
1754
  *
1675
- * A file, because the image probe is a paid call on a metered backend and
1676
- * three processes ask: the daemon (one runner per pairing), `byollm start`
1677
- * and `byollm services`. Kept in memory alone, each would pay for its own.
1678
- * The key holds the kind, the service, its backend, its address and its
1679
- * model, so changing any of them is a new question and is asked again.
1755
+ * Distinct from `unauthorized` (it does not know us) and from `revoked`
1756
+ * (this pairing is over). A device asking about a job it does not hold, or
1757
+ * an upstream that does not route for the site named, is neither of those —
1758
+ * and this client used to report all three as `revoked`, because it
1759
+ * dispatched on the 403 rather than on the code beside it. A daemon told it
1760
+ * was revoked stops for good; that is the wrong response to a refusal that
1761
+ * is about one request.
1680
1762
  */
1681
- interface ImageProbeStore {
1682
- get(key: string): Promise<ImageProbe | undefined>;
1683
- set(key: string, verdict: ImageProbe): Promise<void>;
1684
- }
1685
-
1763
+ | "forbidden"
1686
1764
  /**
1687
- * A prompt about to be executed.
1765
+ * The job has made every tool call it is allowed — byollm_012 §8.
1688
1766
  *
1689
- * Written *before* the backend is called
1690
- * ({@link MUSTS.INGRESS_LOGGED_BEFORE_EXECUTION}), so a job that wedges or
1691
- * crashes the machine still leaves a record of what it was.
1767
+ * Arrives as `forbidden`, and is told apart by the sentence beside it
1768
+ * (`TOOLS_SPENT_MESSAGE`, the protocol's). Its own kind because the remedy is not a
1769
+ * permission problem: the tool loop tells the model the job's tools are
1770
+ * spent and goes to the closing turn. The relay's count is the job's, so
1771
+ * an honest second device meets this after a lapse (#7122, #7440).
1692
1772
  */
1693
- declare const PromptEntry: z.ZodObject<{
1694
- type: z.ZodLiteral<"prompt">;
1695
- at: z.ZodNumber;
1696
- origin: z.ZodString;
1697
- jobId: z.ZodString;
1698
- site: z.ZodOptional<z.ZodString>;
1699
- kind: z.ZodString;
1700
- audience: z.ZodString;
1701
- owner: z.ZodString;
1702
- backendId: z.ZodString;
1703
- backendClass: z.ZodString;
1704
- model: z.ZodString;
1705
- promptHash: z.ZodString;
1706
- promptChars: z.ZodNumber;
1707
- prompt: z.ZodOptional<z.ZodString>;
1708
- }, z.core.$strict>;
1709
- type PromptEntry = z.infer<typeof PromptEntry>;
1710
- /** How a job ended. A separate line, so the prompt line is never rewritten. */
1711
- declare const OutcomeEntry: z.ZodObject<{
1712
- type: z.ZodLiteral<"outcome">;
1713
- at: z.ZodNumber;
1714
- jobId: z.ZodString;
1715
- site: z.ZodOptional<z.ZodString>;
1716
- outcome: z.ZodEnum<{
1717
- error: "error";
1718
- canceled: "canceled";
1719
- ok: "ok";
1720
- refused: "refused";
1721
- }>;
1722
- durationMs: z.ZodOptional<z.ZodNumber>;
1723
- spawnMs: z.ZodOptional<z.ZodNumber>;
1724
- firstOutputMs: z.ZodOptional<z.ZodNumber>;
1725
- outputChars: z.ZodOptional<z.ZodNumber>;
1726
- detail: z.ZodOptional<z.ZodString>;
1727
- stop: z.ZodOptional<z.ZodEnum<{
1728
- length: "length";
1729
- unknown: "unknown";
1730
- end: "end";
1731
- "stop-sequence": "stop-sequence";
1732
- "tool-budget": "tool-budget";
1733
- }>>;
1734
- stopKind: z.ZodOptional<z.ZodEnum<{
1735
- declared: "declared";
1736
- unavailable: "unavailable";
1737
- unverified: "unverified";
1738
- }>>;
1739
- brake: z.ZodOptional<z.ZodEnum<{
1740
- "hourly-cap": "hourly-cap";
1741
- "daily-cap": "daily-cap";
1742
- "payload-too-large": "payload-too-large";
1743
- "ledger-untrusted": "ledger-untrusted";
1744
- "image-bytes": "image-bytes";
1745
- }>>;
1746
- }, z.core.$strict>;
1747
- type OutcomeEntry = z.infer<typeof OutcomeEntry>;
1748
- declare const IngressEntry: z.ZodDiscriminatedUnion<[z.ZodObject<{
1749
- type: z.ZodLiteral<"prompt">;
1750
- at: z.ZodNumber;
1751
- origin: z.ZodString;
1752
- jobId: z.ZodString;
1753
- site: z.ZodOptional<z.ZodString>;
1754
- kind: z.ZodString;
1755
- audience: z.ZodString;
1756
- owner: z.ZodString;
1757
- backendId: z.ZodString;
1758
- backendClass: z.ZodString;
1759
- model: z.ZodString;
1760
- promptHash: z.ZodString;
1761
- promptChars: z.ZodNumber;
1762
- prompt: z.ZodOptional<z.ZodString>;
1763
- }, z.core.$strict>, z.ZodObject<{
1764
- type: z.ZodLiteral<"outcome">;
1765
- at: z.ZodNumber;
1766
- jobId: z.ZodString;
1767
- site: z.ZodOptional<z.ZodString>;
1768
- outcome: z.ZodEnum<{
1769
- error: "error";
1770
- canceled: "canceled";
1771
- ok: "ok";
1772
- refused: "refused";
1773
- }>;
1774
- durationMs: z.ZodOptional<z.ZodNumber>;
1775
- spawnMs: z.ZodOptional<z.ZodNumber>;
1776
- firstOutputMs: z.ZodOptional<z.ZodNumber>;
1777
- outputChars: z.ZodOptional<z.ZodNumber>;
1778
- detail: z.ZodOptional<z.ZodString>;
1779
- stop: z.ZodOptional<z.ZodEnum<{
1780
- length: "length";
1781
- unknown: "unknown";
1782
- end: "end";
1783
- "stop-sequence": "stop-sequence";
1784
- "tool-budget": "tool-budget";
1785
- }>>;
1786
- stopKind: z.ZodOptional<z.ZodEnum<{
1787
- declared: "declared";
1788
- unavailable: "unavailable";
1789
- unverified: "unverified";
1790
- }>>;
1791
- brake: z.ZodOptional<z.ZodEnum<{
1792
- "hourly-cap": "hourly-cap";
1793
- "daily-cap": "daily-cap";
1794
- "payload-too-large": "payload-too-large";
1795
- "ledger-untrusted": "ledger-untrusted";
1796
- "image-bytes": "image-bytes";
1797
- }>>;
1798
- }, z.core.$strict>, z.ZodObject<{
1799
- type: z.ZodLiteral<"memory">;
1800
- at: z.ZodNumber;
1801
- jobId: z.ZodOptional<z.ZodString>;
1802
- backendId: z.ZodString;
1803
- admit: z.ZodBoolean;
1804
- why: z.ZodString;
1805
- availableBytes: z.ZodOptional<z.ZodNumber>;
1806
- totalBytes: z.ZodOptional<z.ZodNumber>;
1807
- swapFreeBytes: z.ZodOptional<z.ZodNumber>;
1808
- swapTotalBytes: z.ZodOptional<z.ZodNumber>;
1809
- pressure: z.ZodEnum<{
1810
- normal: "normal";
1811
- warn: "warn";
1812
- critical: "critical";
1813
- unknown: "unknown";
1814
- }>;
1815
- }, z.core.$strict>, z.ZodObject<{
1816
- type: z.ZodLiteral<"tool-call">;
1817
- at: z.ZodNumber;
1818
- jobId: z.ZodString;
1819
- site: z.ZodOptional<z.ZodString>;
1820
- audience: z.ZodString;
1821
- callId: z.ZodString;
1822
- seq: z.ZodNumber;
1823
- name: z.ZodString;
1824
- argumentsHash: z.ZodString;
1825
- argumentsChars: z.ZodNumber;
1826
- arguments: z.ZodOptional<z.ZodString>;
1827
- }, z.core.$strict>, z.ZodObject<{
1828
- type: z.ZodLiteral<"tool-outcome">;
1829
- at: z.ZodNumber;
1830
- jobId: z.ZodString;
1831
- site: z.ZodOptional<z.ZodString>;
1832
- callId: z.ZodString;
1833
- seq: z.ZodNumber;
1834
- outcome: z.ZodEnum<{
1835
- refused: "refused";
1836
- answered: "answered";
1837
- errored: "errored";
1838
- timedOut: "timedOut";
1839
- }>;
1840
- chars: z.ZodOptional<z.ZodNumber>;
1841
- contentHash: z.ZodOptional<z.ZodString>;
1842
- detail: z.ZodOptional<z.ZodString>;
1843
- }, z.core.$strict>, z.ZodObject<{
1844
- type: z.ZodLiteral<"tool-dropped">;
1845
- at: z.ZodNumber;
1846
- jobId: z.ZodString;
1847
- site: z.ZodOptional<z.ZodString>;
1848
- callId: z.ZodOptional<z.ZodString>;
1849
- why: z.ZodString;
1850
- }, z.core.$strict>], "type">;
1851
- type IngressEntry = z.infer<typeof IngressEntry>;
1852
- interface IngressOptions {
1853
- readonly path: string;
1854
- /** Days to keep a community prompt in full before reducing it to its hash. */
1855
- readonly communityPromptDays: number;
1856
- /** Whether to record the owner's own prompts in full. */
1857
- readonly keepSelfPrompts: boolean;
1773
+ | "tools-spent" | "rate-limited" | "server-error" | "malformed-response";
1774
+ declare class ClientError extends Error {
1775
+ readonly kind: ClientErrorKind;
1776
+ /** Seconds the server asked us to wait, when it said. */
1777
+ readonly retryAfter?: number | undefined;
1778
+ /**
1779
+ * The HTTP status the upstream answered with, when it answered at all.
1780
+ *
1781
+ * Guard (b) decides on this and on nothing in the body (byollm_021 §R2):
1782
+ * a 0.1.4 upstream's refusal names no path, and a 0.1.5 one that does
1783
+ * must not be depended on, so the status is the whole of what is read.
1784
+ */
1785
+ readonly status?: number | undefined;
1786
+ readonly name = "ClientError";
1787
+ constructor(kind: ClientErrorKind, message: string,
1788
+ /** Seconds the server asked us to wait, when it said. */
1789
+ retryAfter?: number | undefined,
1790
+ /**
1791
+ * The HTTP status the upstream answered with, when it answered at all.
1792
+ *
1793
+ * Guard (b) decides on this and on nothing in the body (byollm_021 §R2):
1794
+ * a 0.1.4 upstream's refusal names no path, and a 0.1.5 one that does
1795
+ * must not be depended on, so the status is the whole of what is read.
1796
+ */
1797
+ status?: number | undefined);
1798
+ /** Is retrying this same call plausibly useful? */
1799
+ get retryable(): boolean;
1800
+ }
1801
+ interface ClientOptions {
1802
+ /** The app's origin, e.g. `https://app.example.com`. */
1803
+ readonly origin: string;
1804
+ /** Bearer token from pairing. Absent while pairing. */
1805
+ /**
1806
+ * How this daemon proves who it is (byollm_009 §4.2).
1807
+ *
1808
+ * A signer rather than a key, so the client never holds private material
1809
+ * and the daemon decides where keys live. Absent while pairing, which is
1810
+ * the one exchange that establishes an identity rather than using one.
1811
+ */
1812
+ readonly identity?: {
1813
+ readonly runnerId: string;
1814
+ sign(input: {
1815
+ endpoint: string;
1816
+ runnerId: string;
1817
+ issuedAt: number;
1818
+ body: string;
1819
+ }): Promise<string> | string;
1820
+ };
1821
+ /** Per-request timeout. */
1822
+ readonly timeoutMs?: number;
1823
+ /** Injectable fetch, for tests. */
1824
+ readonly fetch?: typeof fetch;
1858
1825
  }
1859
1826
  /**
1860
- * The append-only record of every prompt that has run on this machine.
1827
+ * The daemon's outbound protocol client.
1861
1828
  *
1862
- * byollm_002 calls the meter the product's soul. This is it: one JSONL file
1863
- * the owner can read, grep and delete, written before execution rather than
1864
- * after.
1829
+ * Every call is outbound; nothing here ever listens. That is the whole
1830
+ * network posture of the product, and it lives in this one class.
1865
1831
  */
1866
- declare class IngressLog {
1832
+ declare class ProtocolClient {
1867
1833
  #private;
1868
- constructor(options: IngressOptions);
1869
- /** Record a prompt. Await this before starting the backend call. */
1870
- recordPrompt(input: {
1871
- at: number;
1872
- origin: string;
1834
+ constructor(options: ClientOptions);
1835
+ /** A client for the same origin that signs as a given runner. */
1836
+ withIdentity(identity: NonNullable<ClientOptions["identity"]>): ProtocolClient;
1837
+ get origin(): string;
1838
+ pairStart(input: {
1839
+ version: string;
1840
+ label: string;
1841
+ platform: "darwin" | "linux" | "win32";
1842
+ /** This machine's public keys (byollm_009 §5). */
1843
+ device: PublicIdentity;
1844
+ capabilities: readonly Capability[];
1845
+ }): Promise<PairStartResponse>;
1846
+ pairPoll(deviceCode: string): Promise<PairPollResponse>;
1847
+ /**
1848
+ * Collect the payload for a lease this daemon holds (byollm_009 §6).
1849
+ *
1850
+ * The second half of claim-then-fetch: a claim answers with a stub, and the
1851
+ * work is collected by the device that took it.
1852
+ */
1853
+ fetch(input: {
1854
+ runnerId: string;
1873
1855
  jobId: string;
1874
- site?: string;
1875
- kind: string;
1876
- audience: Audience;
1877
- owner: string;
1878
- backendId: string;
1879
- backendClass: string;
1880
- model: string;
1881
- prompt: string;
1882
- }): Promise<void>;
1883
- /** Record how a job ended. */
1884
- recordOutcome(input: {
1885
- at: number;
1856
+ leaseId: string;
1857
+ }): Promise<FetchResponse>;
1858
+ claim(input: {
1859
+ runnerId: string;
1860
+ capabilities: readonly Capability[];
1861
+ max: number;
1862
+ }): Promise<ClaimResponse>;
1863
+ heartbeat(input: {
1864
+ runnerId: string;
1865
+ daemonVersion: string;
1866
+ capabilities: readonly Capability[];
1867
+ /** Kinds this device could serve and is withholding — byollm_016. */
1868
+ withheld?: readonly WithheldKind$1[];
1869
+ activeLeases: readonly {
1870
+ jobId: string;
1871
+ leaseId: string;
1872
+ }[];
1873
+ }): Promise<HeartbeatResponse>;
1874
+ result(input: {
1875
+ runnerId: string;
1886
1876
  jobId: string;
1887
- site?: string;
1888
- outcome: OutcomeEntry["outcome"];
1889
- durationMs?: number;
1890
- spawnMs?: number;
1891
- firstOutputMs?: number;
1892
- outputChars?: number;
1893
- detail?: string;
1894
- stop?: StopReason;
1895
- stopKind?: StopReasonMapping["kind"];
1896
- brake?: BudgetRefusal;
1897
- }): Promise<void>;
1898
- /** Record what the memory guard decided — B080. */
1899
- /** A tool call, before it is sealed — see {@link ToolCallEntry}. */
1900
- recordToolCall(input: {
1901
- at: number;
1877
+ /** The grant the work was done under — cloud_008 §1.4a. */
1878
+ leaseId: string;
1879
+ envelope: SealedEnvelope;
1880
+ disposition: ResultDisposition;
1881
+ }): Promise<ResultResponse>;
1882
+ release(input: {
1883
+ runnerId: string;
1884
+ leases: readonly {
1885
+ jobId: string;
1886
+ leaseId: string;
1887
+ }[];
1888
+ reason: "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
1889
+ }): Promise<ReleaseResponse>;
1890
+ /**
1891
+ * Send one tool call, sealed to the job's site — byollm_012 §5.2.
1892
+ *
1893
+ * Lease-scoped: only the device holding the job may call for it.
1894
+ */
1895
+ toolCall(input: {
1896
+ runnerId: string;
1902
1897
  jobId: string;
1903
- site?: string;
1904
- audience: Audience;
1898
+ leaseId: string;
1905
1899
  callId: string;
1906
- seq: number;
1907
- name: string;
1908
- arguments: string;
1909
- }): Promise<void>;
1910
- /** How a tool call ended — see {@link ToolOutcomeEntry}. */
1911
- recordToolOutcome(input: {
1912
- at: number;
1900
+ envelope: SealedEnvelope;
1901
+ }): Promise<ToolCallResponse>;
1902
+ /**
1903
+ * What the site has answered, for the calls named — byollm_012 §5.2.
1904
+ *
1905
+ * Each call by job, lease and id, so the read is lease-scoped like every
1906
+ * other holder call.
1907
+ */
1908
+ toolResults(input: {
1909
+ runnerId: string;
1910
+ calls: readonly {
1911
+ jobId: string;
1912
+ leaseId: string;
1913
+ callId: string;
1914
+ }[];
1915
+ }): Promise<ToolResultsResponse>;
1916
+ /**
1917
+ * A download URL for one input blob of a job whose lease this daemon holds
1918
+ * — byollm_021 §2. No lease, no URL.
1919
+ */
1920
+ blobUrl(input: {
1921
+ runnerId: string;
1913
1922
  jobId: string;
1914
- site?: string;
1915
- callId: string;
1916
- seq: number;
1917
- outcome: "answered" | "errored" | "timedOut" | "refused";
1918
- /** The text the site returned, hashed and measured here, never stored. */
1919
- content?: string;
1920
- detail?: string;
1921
- }): Promise<void>;
1922
- /** A result the model never saw — see {@link ToolDroppedEntry}. */
1923
- recordToolDropped(input: {
1924
- at: number;
1923
+ leaseId: string;
1924
+ blob: string;
1925
+ }): Promise<BlobUrlResponse>;
1926
+ /**
1927
+ * An upload slot for one output blob of an `llm.image` job whose lease this
1928
+ * daemon holds, for an object of exactly `bytes` (`blobObjectBytes`).
1929
+ */
1930
+ blobSlot(input: {
1931
+ runnerId: string;
1925
1932
  jobId: string;
1926
- site?: string;
1927
- callId?: string;
1928
- why: string;
1929
- }): Promise<void>;
1930
- recordMemory(input: {
1931
- at: number;
1932
- jobId?: string;
1933
- backendId: string;
1934
- decision: {
1935
- admit: boolean;
1936
- why: string;
1937
- };
1938
- memory: MemoryReading;
1939
- pressure: MemoryPressure;
1940
- }): Promise<void>;
1941
- /** Read the log, oldest first. Malformed lines are skipped, not fatal. */
1942
- read(): Promise<IngressEntry[]>;
1933
+ leaseId: string;
1934
+ bytes: number;
1935
+ }): Promise<BlobSlotResponse>;
1943
1936
  /**
1944
- * Apply retention: drop the text of community prompts older than the
1945
- * window, keeping the hash, the metadata and the character count.
1937
+ * GET one blob's ciphertext, **stopping at `size` bytes** — byollm_021 §3,
1938
+ * {@link MUSTS.BLOB_BUDGET_BEFORE_DOWNLOAD} (C052).
1946
1939
  *
1947
- * byollm_004 Rev 1: a volunteer must not indefinitely retain strangers'
1948
- * content. The hash stays, so the owner can still prove what ran.
1940
+ * `size` is the object size the reference declares (`blobObjectBytes`). A
1941
+ * `Content-Length` over it is refused before the body is read, and a body
1942
+ * that runs past it is cancelled at the first chunk that crosses it, so a
1943
+ * store holding 12 MiB under a 2 MiB reference costs this device at most
1944
+ * 2 MiB and one chunk — never the 12. Fewer bytes than declared is refused
1945
+ * too: `decryptBlob` opens nothing but the exact size.
1949
1946
  *
1950
- * @returns how many entries were reduced.
1947
+ * The URL is the upstream's answer to {@link blobUrl}, a capability on
1948
+ * presigned object storage or on the direct-lane server — never a URL a
1949
+ * backend or a payload chose. Redirects are refused, as on every call here.
1951
1950
  */
1952
- applyRetention(now: number): Promise<number>;
1951
+ getBlob(url: string, size: number, signal?: AbortSignal): Promise<{
1952
+ readonly ok: true;
1953
+ readonly bytes: Uint8Array;
1954
+ } | {
1955
+ readonly ok: false;
1956
+ readonly message: string;
1957
+ }>;
1958
+ /** PUT one output blob's ciphertext to the slot the upstream issued. */
1959
+ putBlob(url: string, object: Uint8Array, signal?: AbortSignal): Promise<{
1960
+ readonly ok: true;
1961
+ } | {
1962
+ readonly ok: false;
1963
+ readonly message: string;
1964
+ }>;
1953
1965
  }
1954
- /** SHA-256 of a prompt, hex. */
1955
- declare function hashText(text: string): string;
1966
+
1956
1967
  /**
1957
- * Replace terminal control sequences before printing untrusted text.
1958
- *
1959
- * Model output and job payloads both reach the owner's terminal through
1960
- * `byollm log` and `byollm status`. Text that can move the cursor or set
1961
- * colours can forge output — the ANSI/log-injection row of byollm_004 §5's
1962
- * corpus. Stored bytes stay verbatim; only the *display* is sanitised, so the
1963
- * log remains an honest record of what actually arrived.
1968
+ * - `passes` — the probe proved the effect.
1969
+ * - `cannot` — the service answered, and not like that. Held: asking the same
1970
+ * model again will not change it.
1971
+ * - `unanswered` — the service did not answer (down, timed out). Not held.
1972
+ */
1973
+ type ImageProbe = {
1974
+ readonly kind: "passes";
1975
+ readonly at: number;
1976
+ } | {
1977
+ readonly kind: "cannot";
1978
+ readonly why: string;
1979
+ readonly at: number;
1980
+ } | {
1981
+ readonly kind: "unanswered";
1982
+ readonly why: string;
1983
+ readonly at: number;
1984
+ };
1985
+ /**
1986
+ * Where image-probe verdicts are kept, keyed by what was asked.
1964
1987
  *
1965
- * Tab and newline are kept: they are legitimate content, not control.
1988
+ * A file, because the image probe is a paid call on a metered backend and
1989
+ * three processes ask: the daemon (one runner per pairing), `byollm start`
1990
+ * and `byollm services`. Kept in memory alone, each would pay for its own.
1991
+ * The key holds the kind, the service, its backend, its address and its
1992
+ * model, so changing any of them is a new question and is asked again.
1966
1993
  */
1967
- declare function stripControlChars(text: string): string;
1994
+ interface ImageProbeStore {
1995
+ get(key: string): Promise<ImageProbe | undefined>;
1996
+ set(key: string, verdict: ImageProbe): Promise<void>;
1997
+ }
1968
1998
 
1969
1999
  /**
1970
2000
  * What the owner has spent running other people's work on a metered backend.
@@ -2649,8 +2679,14 @@ declare class Runner {
2649
2679
  * Resolves when nothing is held, or when `waitMs` has passed — because a
2650
2680
  * job that outlives its own lease must not hold a machine out of service
2651
2681
  * indefinitely, and the lease is the thing that bounds it either way.
2682
+ *
2683
+ * Says how many it waited for and how many it gave up on, for the
2684
+ * update's line in the service log (#9594).
2652
2685
  */
2653
- drain(waitMs: number, sleep?: (ms: number) => Promise<void>): Promise<void>;
2686
+ drain(waitMs: number, sleep?: (ms: number) => Promise<void>): Promise<{
2687
+ finished: number;
2688
+ stillRunning: number;
2689
+ }>;
2654
2690
  /** Undo a drain — the machine claims again. */
2655
2691
  resumeClaiming(): void;
2656
2692
  shutdown(reason: "shutdown" | "pause"): Promise<void>;
@@ -2836,6 +2872,18 @@ interface ServiceIo {
2836
2872
  * suite somebody starts skipping.
2837
2873
  */
2838
2874
  readonly wait?: (ms: number) => Promise<void>;
2875
+ /**
2876
+ * The three facts `start` needs to tell "a person ran me" from "the daemon
2877
+ * I am about to boot out ran me" — #9572. All absent in a test that does
2878
+ * not set them, which is the person case: nothing here reads the real
2879
+ * environment or the real parent unless {@link defaultServiceIo} put it in.
2880
+ */
2881
+ readonly env?: NodeJS.ProcessEnv;
2882
+ readonly parentPid?: number;
2883
+ /** Run a command in its own session, output to a file. See `spawnDetached`. */
2884
+ readonly detach?: (command: readonly string[], env: NodeJS.ProcessEnv, logPath: string) => Promise<boolean>;
2885
+ /** Has `pid` certainly exited? See `processIsGone`. */
2886
+ readonly isGone?: (pid: number) => boolean;
2839
2887
  }
2840
2888
  /** The `byollm` executable. */
2841
2889
  declare function main(argv: readonly string[]): Promise<ExitCode>;
@@ -3183,7 +3231,7 @@ declare const BASE_URL_REFUSAL_MESSAGES: Readonly<Record<BaseUrlRefusal, string>
3183
3231
  * define: an app's runner list shows this string, so a stale one is a lie
3184
3232
  * told to every user, and a literal that a test pins cannot drift quietly.
3185
3233
  */
3186
- declare const DAEMON_VERSION = "0.1.5";
3234
+ declare const DAEMON_VERSION = "0.1.6";
3187
3235
  /**
3188
3236
  * Everything needed to reason about one daemon — byollm_010 §5.
3189
3237
  *