@byollm/protocol 0.1.0-alpha.81 → 0.1.0-alpha.83

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.81`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.83`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/protocol@alpha`.
 >

package/dist/index.d.ts

@@ -1,5 +1,96 @@
 import { z } from 'zod';
 
+/**
+ * Who may be told about a new version — B053.
+ *
+ * `HeartbeatResponse.updateTo` is a new field on a `.strict()` schema, and
+ * strict means a daemon built before the field does not ignore it: it rejects
+ * the entire heartbeat. Send it to everybody and the message carrying the
+ * update is the message that takes offline the machines it was meant to
+ * update — the fleet-wide version of the failure this codebase keeps meeting
+ * one surface at a time.
+ *
+ * No handshake is needed to avoid that. `HeartbeatRequest.daemonVersion` is
+ * already on the wire, so the sender can simply decline to say anything a
+ * given listener cannot hear. The rule lives here, next to the field it
+ * governs, because a rule of this kind in a runbook is a rule that holds
+ * until the next person deploys.
+ *
+ * ## The other direction, deliberately not taken
+ *
+ * The tidier-looking design is a capability list on the request — the daemon
+ * says what it understands. It has a hole this one does not: that field is
+ * also new, the hub's schema is also strict, and an upgraded daemon sending
+ * it to a hub that has not deployed yet is refused outright. It makes the
+ * daemon's upgrade depend on the hub's, in a system where the daemon is the
+ * side we do not control the timing of.
+ *
+ * Reading a field that already exists has no such ordering problem: old
+ * daemons are never sent the new field, new daemons are, and neither needs
+ * the other to have moved first.
+ */
+/**
+ * The first daemon version whose schema has `updateTo` in it.
+ *
+ * Raising this is safe and lowering it is not, which is worth knowing before
+ * anybody tidies it: too high means some daemons miss an update they could
+ * have taken, and too low means their heartbeats are refused.
+ */
+declare const UPDATE_OFFER_SINCE = "0.1.0-alpha.83";
+/**
+ * Semver ordering, only as far as this needs it.
+ *
+ * Numeric prerelease parts compare as numbers, which is the whole reason not
+ * to compare these as strings: `alpha.9` sorts after `alpha.83`
+ * lexicographically, and that mistake here means every daemon between .10 and
+ * .82 is treated as too old to hear about an update — or worse, in the other
+ * direction, sent a field it cannot parse.
+ */
+declare function compareVersions(a: string, b: string): number | undefined;
+/**
+ * May this daemon be told about a new version?
+ *
+ * **A version this cannot parse is a no.** Unreadable is not permission: the
+ * consequence of guessing wrong in that direction is the daemon's heartbeat
+ * being refused, which is worse than it missing one update cycle. The same
+ * rule the rest of this protocol applies to unreadable answers, on the one
+ * field where getting it wrong is fleet-shaped.
+ */
+declare function mayOfferUpdate(daemonVersion: string): boolean;
+/**
+ * The oldest daemon a hub will serve — B052, the floor.
+ *
+ * The updater's backstop and its opposite number. The updater moves machines
+ * that opted in; the floor is what moves the ones that did not, and it is the
+ * only mechanism that works on a daemon which is not listening for offers.
+ *
+ * Raising it is a deliberate act with a spec note, never automatic — a floor
+ * that followed `latest` would refuse every machine that had not updated in
+ * the last hour, which is the outage version of hygiene.
+ */
+interface FloorRefusal {
+    readonly error: "daemon-below-floor";
+    readonly message: string;
+    readonly floor: string;
+}
+/**
+ * Is this daemon too old to serve?
+ *
+ * **An unreadable version is NOT refused**, and that is the deliberate
+ * asymmetry with {@link mayOfferUpdate}, which treats an unreadable version
+ * as "do not offer". The two point the same way once you ask what the
+ * mistake costs: there, guessing yes sends a field that breaks the
+ * heartbeat; here, guessing yes takes a working machine out of service over
+ * a string it could not parse. Both decline to act when they cannot tell,
+ * and declining to act means opposite booleans.
+ */
+declare function checkDaemonFloor(input: {
+    readonly daemonVersion: string;
+    readonly floor: string;
+    /** How somebody fixes it. The floor is useless without the remedy. */
+    readonly upgradeCommand: string;
+}): FloorRefusal | null;
+
 /** The full description — five sections, plus why it matters. */
 declare const ABOUT = "# About BYOLLM\n\n**What BYOLLM is**\n\nBYOLLM lets you use your own AI on websites. You install one small program on\nyour computer. Then, websites that support BYOLLM can use the AI you already\nhave \u2014 a free model running on your machine, or an AI service you already pay\nfor \u2014 instead of the website paying for AI and passing the cost to you.\n\n**Why it matters**\n\nFor you:\n\n- Your favorite model, everywhere you go.\n- New models the moment you get them \u2013 not when a site gets around to adding\n  them.\n- Encrypted end-to-end. Your prompts go to your own device; byollm.cloud can't\n  read them.\n- Sites never learn which model you use, and your subscriptions are never\n  shared.\n- Pay less. Sites that don't pay for AI can charge you less \u2013 or nothing.\n\nFor sites and developers:\n\n- Zero AI bills. Your users bring their own compute.\n- No floating money \u2013 you don't pay LLM bills up front and hope to collect\n  later, and you never ask people to prepay just to try you.\n- Free trials that cost you nothing to offer.\n- Ship the AI features you kept private for fear of the API bill.\n- One small integration. Your users choose the models.\n\n**Your device**\n\nThe `byollm` program runs on your computer. It knows which AI services you have\nset up: free open-source models on your machine, metered services you pay per\nuse, or your own subscriptions like Claude Pro/Max. When a website you have\nenabled sends work, your device runs it with the service you chose. Your\nprompts are encrypted end-to-end to your own device. byollm.cloud passes them\nalong and cannot read them.\n\n**Sites**\n\nA website that wants to use BYOLLM says what it needs \u2014 \"writing help,\" \"chat,\"\nand so on. When you connect the site, you pick which of your services answers\neach one. The site never learns which model you use. You can turn a site off at\nany time, and it stops getting your work.\n\n**Teams (optional)**\n\nA team lets you share what runs on your devices with people you name \u2014 the free\nopen-source models on your machine, or a metered service with a spending limit\nyou set. Your subscription accounts (like Claude Pro/Max) are never shared with\nanyone. That is a rule, not a setting.\n\n**byollm.cloud (or your own relay)**\n\nMany sites, many devices, many people. byollm.cloud keeps track of who has\nallowed what and sends each job to the right device. It never sees your\nprompts. If you would rather run this part yourself, the relay is open source \u2014\nyou can run your own instead of using byollm.cloud.";
 /**
@@ -594,8 +685,8 @@ declare function payloadTextLength(kinded: KindedPayload): number;
  * ```
  */
 declare const JobState: z.ZodEnum<{
-    ok: "ok";
     error: "error";
+    ok: "ok";
     expired: "expired";
     queued: "queued";
     claimed: "claimed";
@@ -846,8 +937,8 @@ type SealedOutcome = z.infer<typeof SealedOutcome>;
 declare const DeliveredResult: z.ZodObject<{
     jobId: z.ZodString;
     state: z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
         expired: "expired";
         queued: "queued";
         claimed: "claimed";
@@ -2535,6 +2626,7 @@ declare const HeartbeatResponse: z.ZodObject<{
     }, z.core.$strict>>;
     serverTime: z.ZodNumber;
     awaitingConsent: z.ZodArray<z.ZodString>;
+    updateTo: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type HeartbeatResponse = z.infer<typeof HeartbeatResponse>;
 /**
@@ -2550,8 +2642,8 @@ type HeartbeatResponse = z.infer<typeof HeartbeatResponse>;
  * and collapsing them would make the relay guess.
  */
 declare const ResultDisposition: z.ZodEnum<{
-    ok: "ok";
     error: "error";
+    ok: "ok";
     canceled: "canceled";
 }>;
 type ResultDisposition = z.infer<typeof ResultDisposition>;
@@ -2571,8 +2663,8 @@ declare const ResultRequest: z.ZodObject<{
         deadlineAt: z.ZodNumber;
     }, z.core.$strict>;
     disposition: z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
         canceled: "canceled";
     }>;
 }, z.core.$strict>;
@@ -2612,6 +2704,7 @@ type ReleaseResponse = z.infer<typeof ReleaseResponse>;
  * with no response at all.
  */
 declare const WireErrorCode: z.ZodEnum<{
+    "daemon-below-floor": "daemon-below-floor";
     "unsupported-protocol-version": "unsupported-protocol-version";
     revoked: "revoked";
     "bad-request": "bad-request";
@@ -2627,6 +2720,7 @@ declare const WireErrorCode: z.ZodEnum<{
 type WireErrorCode = z.infer<typeof WireErrorCode>;
 declare const WireError: z.ZodObject<{
     error: z.ZodEnum<{
+        "daemon-below-floor": "daemon-below-floor";
         "unsupported-protocol-version": "unsupported-protocol-version";
         revoked: "revoked";
         "bad-request": "bad-request";
@@ -2642,6 +2736,7 @@ declare const WireError: z.ZodObject<{
     message: z.ZodString;
     supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
     minimum: z.ZodOptional<z.ZodString>;
+    floor: z.ZodOptional<z.ZodString>;
     retryAfter: z.ZodOptional<z.ZodNumber>;
     serverTime: z.ZodOptional<z.ZodNumber>;
     maxSkewMs: z.ZodOptional<z.ZodNumber>;
@@ -2670,4 +2765,4 @@ declare const FetchResponse: z.ZodObject<{
 }, z.core.$strict>;
 type FetchResponse = z.infer<typeof FetchResponse>;
 
-export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkProtocolVersion, classifyCost, cryptoReady, declaredVersion, effectiveOfferScope, envelopeBytes, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };
+export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, type FloorRefusal, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, UPDATE_OFFER_SINCE, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkDaemonFloor, checkProtocolVersion, classifyCost, compareVersions, cryptoReady, declaredVersion, effectiveOfferScope, envelopeBytes, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mayOfferUpdate, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };

package/dist/index.js

@@ -1,3 +1,52 @@
+// src/update-offer.ts
+var UPDATE_OFFER_SINCE = "0.1.0-alpha.83";
+function parse(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (match === null) return void 0;
+  return {
+    release: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] === void 0 ? [] : match[4].split(".").map((part) => /^\d+$/.test(part) ? Number(part) : part)
+  };
+}
+function compareVersions(a, b) {
+  const left = parse(a);
+  const right = parse(b);
+  if (left === void 0 || right === void 0) return void 0;
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left.release[i] ?? 0) - (right.release[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  if (left.pre.length === 0 && right.pre.length > 0) return 1;
+  if (left.pre.length > 0 && right.pre.length === 0) return -1;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
+    const l = left.pre[i];
+    const r = right.pre[i];
+    if (l === void 0) return -1;
+    if (r === void 0) return 1;
+    if (l === r) continue;
+    if (typeof l === "number" && typeof r === "number") return l < r ? -1 : 1;
+    if (typeof l === "number") return -1;
+    if (typeof r === "number") return 1;
+    return l < r ? -1 : 1;
+  }
+  return 0;
+}
+function mayOfferUpdate(daemonVersion) {
+  const order = compareVersions(daemonVersion, UPDATE_OFFER_SINCE);
+  return order !== void 0 && order >= 0;
+}
+function checkDaemonFloor(input) {
+  const order = compareVersions(input.daemonVersion, input.floor);
+  if (order === void 0 || order >= 0) return null;
+  return {
+    error: "daemon-below-floor",
+    message: `byollm ${input.daemonVersion} is below the supported floor (${input.floor}). Run \`${input.upgradeCommand}\`, then \`byollm start\`.`,
+    floor: input.floor
+  };
+}
+
 // src/about.ts
 var ABOUT = `# About BYOLLM
 
@@ -2108,7 +2157,30 @@ var HeartbeatResponse = z11.object({
    * operator stopped it" — one word with two subjects on two halves of one
    * exchange is a confusion nobody untangles from a log.
    */
-  awaitingConsent: z11.array(z11.string().min(1))
+  awaitingConsent: z11.array(z11.string().min(1)),
+  /**
+   * A version this daemon should move itself to — B053.
+   *
+   * The channel the auto-updater reads, and it is the channel the daemon
+   * already polls rather than a new phone-home, which is what the ruling
+   * asked for (016 §Auto-update).
+   *
+   * **The hub may not send this to every daemon.** This schema is
+   * `.strict()`, so a daemon built before the field exists does not ignore
+   * it — it rejects the whole heartbeat and stops working. Which would mean
+   * the message carrying the update is the message that breaks the machines
+   * it was meant to update.
+   *
+   * That is decidable without any new handshake, because the request
+   * already carries `daemonVersion`. {@link mayOfferUpdate} is the rule,
+   * kept here as code rather than as a paragraph in a runbook, so both
+   * sides read the same one.
+   *
+   * Exact versions only, never a tag: the daemon refuses anything else, and
+   * a fleet resolving one tag at different minutes is a fleet on different
+   * builds reporting one number.
+   */
+  updateTo: z11.string().min(1).optional()
 }).strict();
 var ResultDisposition = z11.enum(["ok", "error", "canceled"]);
 var ResultRequest = z11.object({
@@ -2220,6 +2292,20 @@ var ReleaseResponse = z11.object({
 var WireErrorCode = z11.enum([
   "bad-request",
   "unsupported-protocol-version",
+  /**
+   * The daemon is older than this hub will serve — B052.
+   *
+   * Distinct from `unsupported-protocol-version`, which is about the
+   * contract; this is about the build. A daemon can speak protocol 1
+   * perfectly and still be old enough that we would rather move it than keep
+   * carrying it — and the two need different remedies in the message, since
+   * one is "your daemon and this server disagree" and the other is "yours
+   * works, and it is time".
+   *
+   * The floor is the backstop to the auto-updater (B053), and the only lever
+   * that reaches a machine which never opted into offers.
+   */
+  "daemon-below-floor",
   // "We do not know who you are." Exactly 401, and only that — cloud_008
   // §1.4d.
   "unauthorized",
@@ -2285,6 +2371,16 @@ var WireError = z11.object({
    */
   supported: z11.array(z11.string().min(1)).optional(),
   minimum: z11.string().min(1).optional(),
+  /**
+   * The oldest daemon this hub serves, on `daemon-below-floor` — B052.
+   *
+   * Carried for the same reason `supported` and `minimum` are: a refusal
+   * that cannot be branched on is a refusal a client can only print. The
+   * message already names the floor for a person; this names it for the
+   * code, so a surface can say "you are two versions under" without
+   * parsing English.
+   */
+  floor: z11.string().min(1).optional(),
   /** Seconds; mirrors Retry-After for `rate-limited` and `server-error`. */
   retryAfter: z11.number().int().nonnegative().optional(),
   /**
@@ -2313,6 +2409,19 @@ var WireError = z11.object({
       message: `${error.error} must not carry serverTime or maxSkewMs`
     });
   }
+  const floored = error.error === "daemon-below-floor";
+  if (floored && error.floor === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "daemon-below-floor must carry floor"
+    });
+  }
+  if (!floored && error.floor !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: `${error.error} must not carry floor`
+    });
+  }
   const version = error.error === "unsupported-protocol-version";
   const versionFields = error.supported !== void 0 || error.minimum !== void 0;
   if (version && !versionFields) {
@@ -2331,6 +2440,20 @@ var WireError = z11.object({
 var ERROR_STATUS = Object.freeze({
   "bad-request": 400,
   "unsupported-protocol-version": 400,
+  /**
+   * 426 Upgrade Required — B052, and it is the one status that says this.
+   *
+   * Not 403, which this daemon reads as a permission problem and which
+   * sits beside `revoked` in every log. Not 400, which reads as a
+   * malformed request; the request was perfect and the sender is old.
+   *
+   * It also fails safely on a daemon that predates the code: 426 is not in
+   * that switch, so it lands on the 4xx default — `rejected`, which is
+   * "never retried: the request is wrong, and repeating it stays wrong".
+   * Vaguer than the remedy, and the right behaviour, which is what a
+   * fallback has to be.
+   */
+  "daemon-below-floor": 426,
   unauthorized: 401,
   forbidden: 403,
   revoked: 403,
@@ -2472,6 +2595,7 @@ export {
   StoredKeys,
   Succession,
   TERMINAL_STATES,
+  UPDATE_OFFER_SINCE,
   WireError,
   WireErrorCode,
   WithheldKind,
@@ -2479,8 +2603,10 @@ export {
   backendName,
   canTransition,
   canonicalRequest,
+  checkDaemonFloor,
   checkProtocolVersion,
   classifyCost,
+  compareVersions,
   cryptoReady,
   declaredVersion,
   effectiveOfferScope,
@@ -2496,6 +2622,7 @@ export {
   keyId,
   kindsOf,
   matchAudience,
+  mayOfferUpdate,
   mustsVerifiedBy,
   open,
   payloadTextLength,