@byollm/server 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/index.js

@@ -2,23 +2,23 @@ import {
   ByollmHandlers,
   SERVED_PROTOCOL_VERSION,
   createFetchHandler,
+  deadlineFor,
   generateDeviceCode,
   generateJobId,
   generateLeaseId,
   generateRunnerId,
-  generateRunnerToken,
   generateUserCode,
   hashSecret,
   resealForDevice,
   routeEndpoint,
   secretsMatch,
   signatureFrom
-} from "./chunk-4NIHWQAT.js";
+} from "./chunk-I4MSFVRA.js";
 import {
   NoRunnerAvailableError,
   PollingDelivery,
   ResultTimeoutError
-} from "./chunk-7RKXFPBZ.js";
+} from "./chunk-SAK63KNU.js";
 
 // src/app.ts
 import {
@@ -35,12 +35,25 @@ import {
 
 // src/cloud.ts
 import {
-  JobOutcome,
+  PROTOCOL_VERSION,
+  SealedOutcome,
   keyId,
   open,
   publicIdentityOf,
-  provenanceFor
+  provenanceFor,
+  signSiteRequest
 } from "@byollm/protocol";
+var RelayUnavailable = class extends Error {
+  retryable;
+  /** The protocol's own code, when the relay sent one. */
+  code;
+  constructor(message, retryable, code) {
+    super(message);
+    this.name = "RelayUnavailable";
+    this.retryable = retryable;
+    this.code = code;
+  }
+};
 var CloudLane = class {
   #options;
   #store;
@@ -66,20 +79,64 @@ var CloudLane = class {
       id: record.id,
       kind: record.kind,
       owner: record.owner,
+      // This site, by its identity key id — Amendment A §A.3. The relay
+      // already knows which site it is routing for, so this discloses nothing
+      // new to it; what it adds is that the *daemon* can check the stub
+      // against the envelope's `senderKeyId` without asking the relay.
+      site: keyId(publicIdentityOf(this.#siteKeys).identity),
       audience: record.audience,
-      ...record.audienceAllow === void 0 ? {} : { audienceAllow: [...record.audienceAllow] },
+      // `audienceAllow` is deliberately **not** published — cloud_008 §0.2.
+      //
+      // It is a list of the people who may run this job, and on the direct
+      // plane that is unremarkable: the site authored the list and the site is
+      // the upstream, so the party receiving it already has it. Through a
+      // relay it is a third party, and byollm_009 §6's enumerated metadata —
+      // "exhaustive and normative… what an upstream can see, stated as a
+      // commitment" — does not include it. It was reaching the relay on every
+      // named-audience job.
+      //
+      // Nothing is lost by withholding it, which is why this is a Tier 0 fix
+      // rather than a trade. `matchAudience` treats it as a *narrowing*:
+      // `job.audienceAllow !== undefined && !includes(daemon.owner)` refuses,
+      // and its absence simply falls through to the checks that actually
+      // enforce — the daemon's own allowlist (`NAMED_LOCAL_ALLOWLIST`) and the
+      // backend's offer scope. On this lane the relay narrows too, from the
+      // control plane's rosters. The enforcement was never here.
+      ...record.service === void 0 ? {} : { service: record.service },
       sizeClass: record.sizeClass,
       streaming: false,
       // The relay needs *a* deadline to bound routing. A job without one gets
       // the envelope's, which is the outer bound on how long the ciphertext
       // is worth carrying — never longer than the work could possibly matter.
-      deadlineAt: record.deadlineAt ?? record.createdAt + ENVELOPE_TTL_FALLBACK
+      // The same fallback the direct plane uses — cloud_008 Tier 4, finding
+      // 31. This said `createdAt + ENVELOPE_TTL_FALLBACK`, a local constant
+      // whose value happened to equal `ENVELOPE_MAX_AGE_MS`; the direct plane
+      // said `(claimableAt ?? now) + ttlMs`. One field, two meanings, and a
+      // job that was blocked on a dependency got a deadline measured from
+      // when it was *created* on one lane and from when it became *claimable*
+      // on the other.
+      deadlineAt: deadlineFor(record, this.#now())
     };
-    await this.#post("/relay/site/enqueue", {
+    await this.#post("enqueue", {
       siteId: this.#options.siteId,
       stub
     });
   }
+  /**
+   * Withdraw a job at the relay — cloud_008 §2.2.
+   *
+   * `app.cancel()` marks the site's own row terminal, which stops the *next*
+   * seal. It cannot stop a device that is already running the work, because
+   * on this lane the site is not the upstream: only the relay talks to the
+   * daemon, and it answered `cancel: []` unconditionally.
+   *
+   * So the cancellation has to travel. The relay marks the job, stops
+   * offering it, and names it to the holding device at its next heartbeat —
+   * the same path the direct plane has always had, arriving one hop later.
+   */
+  async cancel(jobId) {
+    await this.#post("cancel", { siteId: this.#options.siteId, jobId });
+  }
   /**
    * One cycle: seal for anything claimed, collect anything finished.
    *
@@ -92,7 +149,17 @@ var CloudLane = class {
     const sealed = [];
     const refused = [];
     const completed = [];
-    const pending = await this.#get("/relay/site/pending");
+    try {
+      return await this.#cycle(sealed, refused, completed);
+    } catch (error) {
+      if (error instanceof RelayUnavailable && error.retryable) {
+        return { sealed, completed, refused, deferred: error.message };
+      }
+      throw error;
+    }
+  }
+  async #cycle(sealed, refused, completed) {
+    const pending = await this.#get("pending");
     for (const claim of pending.jobs) {
       const record = await this.#store.get(claim.jobId);
       if (!record) continue;
@@ -109,20 +176,24 @@ var CloudLane = class {
         refused.push(claim.jobId);
         continue;
       }
-      await this.#store.adopt({
+      const adopted = await this.#store.adopt({
         jobId: claim.jobId,
         leaseId: claim.leaseId,
-        expiresAt: claim.awaitingUntil,
+        expiresAt: claim.leaseExpiresAt,
         now: this.#now()
       });
-      await this.#post("/relay/site/payload", {
+      if (!adopted) {
+        refused.push(claim.jobId);
+        continue;
+      }
+      await this.#post("payload", {
         siteId: this.#options.siteId,
         jobId: claim.jobId,
         envelope: resealed.envelope
       });
       sealed.push(claim.jobId);
     }
-    const finished = await this.#get("/relay/site/results");
+    const finished = await this.#get("results");
     for (const done of finished.jobs) {
       const record = await this.#store.get(done.jobId);
       if (!record || record.state === "ok" || record.state === "error") {
@@ -135,17 +206,30 @@ var CloudLane = class {
       }
       await this.#store.complete({
         jobId: done.jobId,
+        // The relay named the device; the signature above proved it — §3.6.
+        runnerId: done.runnerId,
         // The grant, not the machine: this site never paired with the device
         // that ran it, and the signature it verified above is the stronger
         // claim about who did.
         holder: { by: "lease", leaseId: done.leaseId },
-        outcome,
+        outcome: outcome.outcome,
         provenance: provenanceFor({
           audience: record.audience,
           runnerId: done.runnerId,
-          runnerOwner: keyId(done.device.identity),
-          backendClass: "http",
-          model: "unknown"
+          // The owner, from the relay's own record of who claimed it — not a
+          // key id. cloud_008 §2.5: this said `keyId(device.identity)`, which
+          // put a key id where the direct plane puts a user id, so an app
+          // comparing provenance across lanes compared two namespaces and got
+          // `false` for the same person. The device's key is still what the
+          // signature was verified against, above; that is a different
+          // question from whose machine it is.
+          runnerOwner: done.runnerOwner,
+          // From the envelope, not invented — cloud_008 §2.5. These were
+          // hardcoded `"http"` and `"unknown"` because the daemon's declared
+          // values stopped at the relay, which is right: a blind relay acts
+          // on neither. Sealing them carries them past it untouched.
+          backendClass: outcome.ran.backendClass,
+          model: outcome.ran.model
         }),
         now: this.#now()
       });
@@ -180,29 +264,107 @@ var CloudLane = class {
     } catch {
       return null;
     }
-    const outcome = JobOutcome.safeParse(parsed);
-    if (!outcome.success) return null;
-    if (outcome.data.outcome !== done.disposition) return null;
-    return outcome.data;
+    const sealed = SealedOutcome.safeParse(parsed);
+    if (!sealed.success) return null;
+    if (sealed.data.outcome.outcome !== done.disposition) return null;
+    return sealed.data;
   }
-  async #post(path, body) {
-    const response = await this.#fetch(`${this.#options.relayOrigin}${path}`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body)
+  /**
+   * Sign a site-plane call with this site's identity key.
+   *
+   * The same scheme the daemon uses against an upstream, because the site is
+   * in the same position: an outbound caller whose key the relay already holds
+   * for other reasons. Nothing else authenticates this plane — a relay that
+   * took the `siteId` in a body at face value would let anyone enqueue work in
+   * a site's name and read who claimed it.
+   */
+  #headers(endpoint, rawBody) {
+    const signature = signSiteRequest(this.#siteKeys, {
+      endpoint,
+      siteId: this.#options.siteId,
+      issuedAt: this.#now(),
+      body: rawBody
     });
-    return response.json();
+    return {
+      "x-byollm-site": this.#options.siteId,
+      "x-byollm-issued-at": String(signature.issuedAt),
+      "x-byollm-signature": signature.signature
+    };
   }
-  async #get(path) {
-    const url = `${this.#options.relayOrigin}${path}?siteId=${encodeURIComponent(this.#options.siteId)}`;
-    const response = await this.#fetch(url);
-    return response.json();
+  /**
+   * A relay answer, checked before it is believed — alpha.31.
+   *
+   * The bug this closes is one line long and its shape is general: a response
+   * body used without looking at the status. The daemon's client has always
+   * done this properly (`client.ts` maps every status to a typed refusal); the
+   * site's lane parsed JSON and hoped.
+   *
+   * Two classes, because they need opposite handling. **Retryable** — 503 from
+   * a draining pod, 429, 5xx, and the protocol's own `not-ready` — means the
+   * work is still there and this cycle should end quietly. **Refused** — a bad
+   * signature, an unknown site, a version this relay does not speak — will
+   * still be true in five seconds, and swallowing it would leave a site
+   * silently disconnected from its own users.
+   */
+  async #answer(response, endpoint) {
+    if (response.ok) return response.json();
+    let code = "";
+    let message;
+    try {
+      const body = await response.json();
+      code = body.error ?? "";
+      message = body.message ?? "";
+    } catch {
+      message = `HTTP ${String(response.status)}`;
+    }
+    const retryable = response.status >= 500 || response.status === 429 || code === "not-ready" || code === "server-error";
+    throw new RelayUnavailable(
+      `${endpoint}: ${code || "refused"} \u2014 ${message}`,
+      retryable,
+      code
+    );
+  }
+  async #post(endpoint, body) {
+    const rawBody = JSON.stringify({
+      protocolVersion: PROTOCOL_VERSION,
+      ...body
+    });
+    const response = await this.#fetch(
+      `${this.#options.relayOrigin}/relay/site/${endpoint}`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...this.#headers(endpoint, rawBody)
+        },
+        body: rawBody
+      }
+    );
+    return this.#answer(response, endpoint);
+  }
+  async #get(endpoint) {
+    const url = `${this.#options.relayOrigin}/relay/site/${endpoint}?siteId=${encodeURIComponent(this.#options.siteId)}&protocolVersion=${encodeURIComponent(PROTOCOL_VERSION)}`;
+    const response = await this.#fetch(url, {
+      headers: this.#headers(endpoint, "")
+    });
+    return this.#answer(response, endpoint);
   }
 };
-var ENVELOPE_TTL_FALLBACK = 24 * 60 * 6e4;
 
 // src/app.ts
 var DEFAULT_LIVENESS_MS = 35e3;
+var ENQUEUE_OPTIONS = Object.freeze({
+  kind: true,
+  payload: true,
+  owner: true,
+  audience: true,
+  service: true,
+  audienceAllow: true,
+  dependsOn: true,
+  ttlMs: true,
+  deadlineAt: true,
+  id: true
+});
 var ByollmApp = class {
   #store;
   #siteKeys;
@@ -255,6 +417,14 @@ var ByollmApp = class {
    * the app is obliged to disclose that to whoever reads it.
    */
   async enqueue(input) {
+    const unknown = Object.keys(input).filter(
+      (key) => !(key in ENQUEUE_OPTIONS)
+    );
+    if (unknown.length > 0) {
+      throw new Error(
+        `enqueue does not understand ${unknown.map((k) => `\`${k}\``).join(", ")}. An option this @byollm/server does not know is refused rather than ignored, because an ignored option is a job that runs differently than you asked with nothing to see \u2014 most often an SDK older than the code calling it. Upgrade @byollm/server, or remove the option.`
+      );
+    }
     const parsed = KindedPayload.safeParse({
       kind: input.kind,
       payload: input.payload
@@ -314,7 +484,7 @@ var ByollmApp = class {
    * Check `provenance.untrusted` before rendering. It is true for every
    * `named`/`public` job, because that text came from someone else's machine
    * and the app must not present it as its own AI's answer
-   * ({@link MUSTS.RESULT_PROVENANCE}).
+   * ({@link MUSTS.PROVENANCE_NAMES_DEVICE}).
    */
   async result(jobId) {
     const job = await this.job(jobId);
@@ -328,7 +498,11 @@ var ByollmApp = class {
   }
   /** Ask a runner to stop. Queued jobs cancel at once; held jobs at the next heartbeat. */
   async cancel(jobId) {
-    return this.#store.cancel(jobId, this.#now());
+    const cancelled = await this.#store.cancel(jobId, this.#now());
+    if (cancelled && this.cloud) {
+      await this.cloud.cancel(jobId).catch(() => void 0);
+    }
+    return cancelled;
   }
   /**
    * Is there a live runner that could take a job of this shape?
@@ -350,14 +524,20 @@ var ByollmApp = class {
     }
     let capable = 0;
     let admitted = 0;
+    let withheldSomewhere = 0;
+    let lastRefusal;
     for (const runner of live) {
-      const capability = runner.capabilities.find((c) => c.kind === query.kind);
+      const forKind = runner.capabilities.filter((c) => c.kind === query.kind);
+      const capability = query.service === void 0 ? forKind.find((c) => c.isDefault) : forKind.find((c) => c.service === query.service);
+      if (capability === void 0 && query.service === void 0 && forKind.length > 0) {
+        withheldSomewhere += 1;
+      }
       if (!capability) continue;
       capable += 1;
       const match = matchAudience(
         {
           owner: query.owner,
-          audience: query.audience ?? "self",
+          audience: query.audience ?? "private",
           audienceAllow: query.audienceAllow
         },
         {
@@ -381,18 +561,24 @@ var ByollmApp = class {
         }
       );
       if (match.ok) admitted += 1;
+      else lastRefusal = match.refusal;
     }
     if (capable === 0) {
-      return {
-        available: false,
-        reason: "no-matching-capability",
-        candidates: 0
-      };
+      const reason = query.service !== void 0 ? "selection-unavailable" : withheldSomewhere > 0 ? "awaiting-default" : "no-matching-capability";
+      return { available: false, reason, candidates: 0 };
     }
     if (admitted === 0) {
+      const ownersDoing = lastRefusal === "offer-scope-too-narrow" || lastRefusal === "subscription-self-lock" || lastRefusal === "metered-no-spend-consent" || lastRefusal === "metered-ceiling-reached";
+      if (query.service !== void 0) {
+        return {
+          available: false,
+          reason: "selection-unavailable",
+          candidates: 0
+        };
+      }
       return {
         available: false,
-        reason: "audience-admits-nobody",
+        reason: ownersDoing ? "default-unusable" : "audience-admits-nobody",
         candidates: 0
       };
     }
@@ -406,13 +592,10 @@ var ByollmApp = class {
    * ({@link MUSTS.PAIR_ONE_USER}, {@link MUSTS.PAIR_INTERACTIVE}).
    */
   async approvePairing(args) {
-    const token = generateRunnerToken();
     return this.#store.approvePairing({
       userCode: normalizeUserCode(args.userCode),
       owner: args.owner,
       runnerId: generateRunnerId(),
-      runnerToken: token,
-      tokenHash: hashSecret(token),
       now: this.#now()
     });
   }
@@ -485,13 +668,27 @@ function siteKeysFromEnv(variable = "BYOLLM_SITE_KEYS", env = process.env) {
 }
 function formatSiteKeys(keys) {
   const encoded = Buffer.from(JSON.stringify(keys)).toString("base64");
-  return `# Set this as BYOLLM_SITE_KEYS. It is a secret: it is this site's
-# identity, and anything holding it can be this site.
+  const pub = publicIdentityOf3(keys);
+  return `# \u2500\u2500 1. SECRET \u2014 set this on your server, and nowhere else \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# This is the site's identity. Anything holding it can *be* this site,
+# so it goes wherever your deployment keeps secrets \u2014 never in a repo,
+# never in a browser, never pasted into a dashboard.
 BYOLLM_SITE_KEYS=${encoded}
 
-# Fingerprint (not secret \u2014 show it to users so they can check what
-# their daemon pinned):
-# ${fingerprint(publicIdentityOf3(keys).identity)}
+# \u2500\u2500 2. PUBLIC \u2014 paste this line into the byollm dashboard \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# The public half. It proves signatures and seals nothing, so it is
+# safe to publish \u2014 which is the point: users pin it, and the relay
+# cannot forge work without the secret above.
+${JSON.stringify(pub)}
+
+# \u2500\u2500 3. Fingerprint \u2014 what a person compares by eye \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# A fingerprint is not secret. Show it on your site so somebody
+# connecting can check it against what their daemon printed.
+# The dashboard derives this itself, so there is nothing to paste.
+# ${fingerprint(pub.identity)}
 `;
 }
 
@@ -525,12 +722,14 @@ var MemoryStore = class {
       kind: input.kind,
       envelope: input.envelope,
       sizeClass: input.sizeClass,
-      audience: input.audience ?? "self",
+      audience: input.audience ?? "private",
+      service: input.service,
       owner: input.owner,
       audienceAllow: input.audienceAllow ? [...input.audienceAllow] : void 0,
       dependsOn,
       state: "queued",
       lease: null,
+      completedByLeaseId: null,
       createdAt: now,
       // The TTL clock starts here only if nothing blocks the job.
       claimableAt: blocked ? null : now,
@@ -620,11 +819,11 @@ var MemoryStore = class {
     for (const { jobId, leaseId } of args.leases) {
       const job = this.#jobs.get(jobId);
       if (!job || job.lease?.runnerId !== args.runnerId || job.lease.id !== leaseId) {
-        lost.push(jobId);
+        lost.push({ jobId, leaseId });
         continue;
       }
       if (job.state !== "claimed" && job.state !== "running") {
-        lost.push(jobId);
+        lost.push({ jobId, leaseId });
         continue;
       }
       const expiresAt = args.now + args.leaseMs;
@@ -666,6 +865,11 @@ var MemoryStore = class {
     const job = this.#jobs.get(args.jobId);
     if (!job) return Promise.resolve({ accepted: false, job: null });
     if (job.state === "ok" || job.state === "error" || job.state === "canceled") {
+      const sameDevice = job.provenance?.runnerId !== void 0 && job.provenance.runnerId === args.runnerId;
+      const sameGrant = args.holder.by === "lease" && job.completedByLeaseId !== null && job.completedByLeaseId === args.holder.leaseId;
+      if (sameDevice && sameGrant) {
+        return Promise.resolve({ accepted: false, duplicate: true, job });
+      }
       return Promise.resolve({ accepted: false, job });
     }
     if (job.state === "expired") {
@@ -680,6 +884,8 @@ var MemoryStore = class {
       ...job,
       state,
       lease: null,
+      // The grant that recorded it, kept after the lease is dropped — §3.6.
+      completedByLeaseId: args.holder.by === "lease" ? args.holder.leaseId : job.lease?.id ?? null,
       outcome: args.outcome,
       provenance: args.provenance,
       updatedAt: args.now
@@ -768,6 +974,7 @@ var MemoryStore = class {
         ...job,
         state: "queued",
         lease: null,
+        completedByLeaseId: null,
         // Newly available again, so the TTL clock restarts here too.
         claimableAt: args.now,
         // A refusal is remembered, or the pair spins between claim and
@@ -797,6 +1004,7 @@ var MemoryStore = class {
           ...job,
           state: "queued",
           lease: null,
+          completedByLeaseId: null,
           // The TTL clock restarts: it measures how long a job has waited
           // *unclaimed*, and this job has just become available again. Without
           // this, a job whose runner died would expire for time it spent being
@@ -819,6 +1027,7 @@ var MemoryStore = class {
         ...job,
         state: "expired",
         lease: null,
+        completedByLeaseId: null,
         updatedAt: now
       };
       this.#write(job.id, expired);
@@ -834,6 +1043,7 @@ var MemoryStore = class {
         ...job,
         state: "canceled",
         lease: null,
+        completedByLeaseId: null,
         updatedAt: now
       };
       this.#write(jobId, canceled);
@@ -854,9 +1064,7 @@ var MemoryStore = class {
   }
   listCancelRequests(runnerId) {
     return Promise.resolve(
-      [...this.#cancelRequests].filter(
-        (jobId) => this.#jobs.get(jobId)?.lease?.runnerId === runnerId
-      )
+      [...this.#cancelRequests].map((jobId) => ({ jobId, lease: this.#jobs.get(jobId)?.lease })).filter((row) => row.lease?.runnerId === runnerId).map((row) => ({ jobId: row.jobId, leaseId: row.lease?.id ?? "" }))
     );
   }
   // -- pairing and runners -------------------------------------------------
@@ -887,7 +1095,6 @@ var MemoryStore = class {
     const runner = {
       id: args.runnerId,
       owner: args.owner,
-      tokenHash: args.tokenHash,
       // Carried from the pairing, not re-supplied at approval: the user
       // approved a specific machine, and the runner must be that machine.
       device: pairing.device,
@@ -906,7 +1113,7 @@ var MemoryStore = class {
       state: "approved",
       owner: args.owner,
       runnerId: runner.id,
-      runnerTokenOnce: args.runnerToken
+      collected: false
     });
     return Promise.resolve(runner);
   }
@@ -927,17 +1134,11 @@ var MemoryStore = class {
     if (pairing) {
       this.#pairings.set(deviceCodeHash, {
         ...pairing,
-        runnerTokenOnce: null
+        collected: true
       });
     }
     return Promise.resolve();
   }
-  getRunnerByTokenHash(hash) {
-    for (const runner of this.#runners.values()) {
-      if (runner.tokenHash === hash) return Promise.resolve(runner);
-    }
-    return Promise.resolve(null);
-  }
   getRunner(runnerId) {
     return Promise.resolve(this.#runners.get(runnerId) ?? null);
   }
@@ -983,6 +1184,7 @@ export {
   MemoryStore,
   NoRunnerAvailableError,
   PollingDelivery,
+  RelayUnavailable,
   ResultTimeoutError,
   SERVED_PROTOCOL_VERSION,
   capabilityFor,
@@ -991,7 +1193,6 @@ export {
   generateDeviceCode,
   generateJobId,
   generateRunnerId,
-  generateRunnerToken,
   generateSiteKeys,
   generateUserCode,
   hashSecret,