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

package/dist/{delivery-36nIe-b3.d.ts → delivery-C6VzgMgH.d.ts}

@@ -19,10 +19,22 @@ interface WaitOptions {
     readonly timeoutMs?: number;
     /**
      * Called instead of throwing when no runner can take the job. Return a
-     * substitute result (a hosted-model answer, say) and the wait resolves with
-     * it; return nothing and {@link NoRunnerAvailableError} is thrown.
+     * substitute and the wait resolves with it; return nothing and
+     * {@link NoRunnerAvailableError} is thrown.
+     *
+     * **A string is enough.** It is the app's own fallback answer — a hosted
+     * model's text, a cached reply — not wire data, and requiring a whole
+     * `DeliveredResult` for it was ceremony that invited invented shapes. The
+     * README's own example got it wrong, which is how this was found.
+     *
+     * **Whatever comes back is labelled `fallback: true` by the wait, not by
+     * the caller** — {@link MUSTS.FALLBACK_LABELED}. Work that did not come
+     * from the user's own compute must not be reportable as though it did, and
+     * that stays true whether an app returns a bare string or a full record it
+     * assembled itself. The stamp is applied after this function returns, so
+     * there is no shape an app can hand back that hides what it is.
      */
-    readonly onNoRunner?: (reason: string) => DeliveredResult | undefined | Promise<DeliveredResult | undefined>;
+    readonly onNoRunner?: (reason: string) => string | DeliveredResult | undefined | Promise<string | DeliveredResult | undefined>;
     /** Abort the wait. */
     readonly signal?: AbortSignal;
 }

package/dist/{handlers-DgW0QNTf.d.ts → handlers-D1ni1D8r.d.ts}

@@ -1,5 +1,5 @@
 import { StoredKeys, Endpoint } from '@byollm/protocol';
-import { B as ByollmStore } from './store-Cj5b6A9j.js';
+import { B as ByollmStore } from './store-DoUlJWaO.js';
 
 /** Everything a mount needs to serve the protocol. */
 /**

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { StoredKeys, JobKind, DeliveredResult, Endpoint, Capability } from '@byollm/protocol';
-import { P as PollingDeliveryDeps, R as ResultDelivery, W as WaitOptions } from './delivery-36nIe-b3.js';
-export { N as NoRunnerAvailableError, a as PollingDelivery, b as ResultTimeoutError } from './delivery-36nIe-b3.js';
-import { B as ByollmStore, J as JobRecord, E as EnqueueInput, R as RunnerRecord, S as StoredJobInput, C as ClaimArgs, a as RenewArgs, b as RenewResult, A as AdoptArgs, c as CompleteArgs, d as CompleteResult, e as ReleaseArgs, P as PairingRecord, f as ApproveArgs, T as TouchArgs } from './store-Cj5b6A9j.js';
-export { g as CompleteHolder, h as JobStore, i as RunnerStore } from './store-Cj5b6A9j.js';
-import { H as HandlerConfig } from './handlers-DgW0QNTf.js';
-export { B as ByollmHandlers, a as HandlerResult, S as SERVED_PROTOCOL_VERSION } from './handlers-DgW0QNTf.js';
+import { P as PollingDeliveryDeps, R as ResultDelivery, W as WaitOptions } from './delivery-C6VzgMgH.js';
+export { N as NoRunnerAvailableError, a as PollingDelivery, b as ResultTimeoutError } from './delivery-C6VzgMgH.js';
+import { B as ByollmStore, J as JobRecord, E as EnqueueInput, R as RunnerRecord, S as StoredJobInput, C as ClaimArgs, a as RenewArgs, b as RenewResult, A as AdoptArgs, c as CompleteArgs, d as CompleteResult, e as ReleaseArgs, P as PairingRecord, f as ApproveArgs, T as TouchArgs } from './store-DoUlJWaO.js';
+export { g as CompleteHolder, h as JobStore, i as RunnerStore } from './store-DoUlJWaO.js';
+import { H as HandlerConfig } from './handlers-D1ni1D8r.js';
+export { B as ByollmHandlers, a as HandlerResult, S as SERVED_PROTOCOL_VERSION } from './handlers-D1ni1D8r.js';
 
 /**
  * The cloud lane — cloud_004 §9.4.
@@ -49,6 +49,19 @@ interface CloudLaneOptions {
     readonly fetch?: typeof fetch;
 }
 /** What one pump cycle did, for logging and for tests. */
+/**
+ * A relay that could not answer this request — alpha.31.
+ *
+ * `retryable` is the whole point: a draining pod and a bad signature are both
+ * failures, and treating them alike is how a site either falls over on every
+ * deploy or stays silently disconnected for a week.
+ */
+declare class RelayUnavailable extends Error {
+    readonly retryable: boolean;
+    /** The protocol's own code, when the relay sent one. */
+    readonly code: string;
+    constructor(message: string, retryable: boolean, code: string);
+}
 interface PumpReport {
     /** Jobs sealed to a claiming device this cycle. */
     readonly sealed: string[];
@@ -62,6 +75,20 @@ interface PumpReport {
      * exactly the case `awaiting-payload` exists to bound.
      */
     readonly refused: string[];
+    /**
+     * Why this cycle stopped early, when it did — alpha.31.
+     *
+     * A relay can legitimately say "ask me later": a pod draining through its
+     * `preStop` window answers `503 not-ready` to every routed call, and that
+     * happens on **every deploy**. Before this existed the lane read the body
+     * of that answer, found no `jobs` in it, and threw `TypeError: finished.jobs
+     * is not iterable` — a site falling over because its relay was polite.
+     *
+     * Absent on an ordinary cycle. Present, with the reason, when the lane
+     * deferred: a site that quietly did nothing and a site that was told to wait
+     * must not look the same in a log.
+     */
+    readonly deferred?: string;
 }
 declare class CloudLane {
     #private;
@@ -79,6 +106,19 @@ declare class CloudLane {
      * field on `JobStub` to put one in.
      */
     publish(record: JobRecord): Promise<void>;
+    /**
+     * 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.
+     */
+    cancel(jobId: string): Promise<void>;
     /**
      * One cycle: seal for anything claimed, collect anything finished.
      *
@@ -91,7 +131,45 @@ declare class CloudLane {
 }
 
 /** Why a job cannot presently run. */
-type NoRunnerReason = "no-runner-paired" | "no-runner-online" | "no-matching-capability" | "audience-admits-nobody";
+type NoRunnerReason = "no-runner-paired" | "no-runner-online" | "no-matching-capability" | "audience-admits-nobody"
+/**
+ * A named service cannot serve this requester — byollm_016 Phase B.
+ *
+ * **One reason for two causes, and the collapse is the point.** The name may
+ * be one nobody advertises, or one advertised and not offered to this
+ * person. Those are different facts and a requester may learn neither,
+ * because telling them apart turns the advisory into an inventory oracle:
+ * try names, sort the answers, enumerate a device you were never offered.
+ *
+ * My first version split them, on the argument that this answers a site
+ * about its own users' devices. That argument does not survive a team job.
+ * The site holds capabilities for devices belonging to *other people* on the
+ * roster, and it is free to relay a reason to the requester who asked — so
+ * the split leaks through a side door rather than the front one, which is
+ * how the collapse in `RefusalReason` gets defeated by a helpful SDK.
+ *
+ * The finer cause stays owner-side, where `byollm services` reports it to
+ * the person who already knows what their machine runs.
+ */
+ | "selection-unavailable"
+/**
+ * A kind two services answer with no default chosen, so the daemon
+ * withholds it — byollm_016. Nothing is wrong with the device; its owner has
+ * a decision to make, and saying "no matching capability" would send them
+ * looking for a missing install instead.
+ */
+ | "awaiting-default"
+/**
+ * The owner's default for this kind can never serve *this* requester —
+ * byollm_016's defaults-meet-audiences corner.
+ *
+ * The specimen: a default of `claude-cli`, self-locked by
+ * `SUBSCRIPTION_SELF_LOCK`, and a team member's unselected job. It resolves
+ * to something that will never run it. Reported rather than left to time
+ * out, because a wait that can never end is indistinguishable from one that
+ * has not ended yet, and only one of them is worth waiting through.
+ */
+ | "default-unusable";
 /**
  * The no-runner signal (byollm_001 Rev 1 §D).
  *
@@ -110,7 +188,9 @@ interface RunnerAvailability {
 interface AvailabilityQuery {
     readonly kind: JobKind;
     readonly owner: string;
-    readonly audience?: "self" | "named" | "public";
+    /** The service the job named, if it named one — byollm_016 Phase B. */
+    readonly service?: string;
+    readonly audience?: "private" | "team" | "public";
     readonly audienceAllow?: readonly string[];
 }
 interface ByollmAppOptions {
@@ -163,14 +243,6 @@ interface JobHandle {
     /** Ask the runner to stop. */
     cancel(): Promise<void>;
 }
-/**
- * The app-facing half of `@byollm/server`.
- *
- * The daemon talks to {@link ByollmHandlers}; the app talks to this. Keeping
- * them separate is what makes "one door per state write" hold — an app
- * enqueues and cancels through these methods and never writes job rows by
- * hand.
- */
 declare class ByollmApp {
     #private;
     /** Present only in the cloud lane; the site's side of the relay. */
@@ -192,7 +264,7 @@ declare class ByollmApp {
      * 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}).
      */
     result(jobId: string): Promise<DeliveredResult | null>;
     /** Ask a runner to stop. Queued jobs cancel at once; held jobs at the next heartbeat. */
@@ -315,8 +387,6 @@ declare function formatSiteKeys(keys: StoredKeys): string;
 
 /** A device code: the secret the daemon polls with. Never shown to a user. */
 declare function generateDeviceCode(): string;
-/** A runner bearer token. */
-declare function generateRunnerToken(): string;
 /** A runner id. */
 declare function generateRunnerId(): string;
 /** A job id. */
@@ -366,14 +436,16 @@ declare class MemoryStore implements ByollmStore {
     expireDue(now: number): Promise<JobRecord[]>;
     cancel(jobId: string, now: number): Promise<JobRecord | null>;
     listClaimedBy(runnerId: string): Promise<JobRecord[]>;
-    listCancelRequests(runnerId: string): Promise<string[]>;
+    listCancelRequests(runnerId: string): Promise<{
+        jobId: string;
+        leaseId: string;
+    }[]>;
     createPairing(record: PairingRecord): Promise<void>;
     getPairingByDeviceCodeHash(hash: string): Promise<PairingRecord | null>;
     getPairingByUserCode(userCode: string): Promise<PairingRecord | null>;
     approvePairing(args: ApproveArgs): Promise<RunnerRecord>;
     denyPairing(userCode: string, _now: number): Promise<void>;
     consumePairingToken(deviceCodeHash: string): Promise<void>;
-    getRunnerByTokenHash(hash: string): Promise<RunnerRecord | null>;
     getRunner(runnerId: string): Promise<RunnerRecord | null>;
     touchRunner(args: TouchArgs): Promise<RunnerRecord | null>;
     revokeRunner(runnerId: string, now: number): Promise<void>;
@@ -384,4 +456,4 @@ declare class MemoryStore implements ByollmStore {
 /** The capability that would serve a kind, if any. */
 declare function capabilityFor(capabilities: readonly Capability[], kind: string): Capability | undefined;
 
-export { AdoptArgs, ApproveArgs, type AvailabilityQuery, ByollmApp, type ByollmAppOptions, ByollmStore, ClaimArgs, CloudLane, type CloudLaneOptions, CompleteArgs, CompleteResult, EnqueueInput, HandlerConfig, type JobHandle, JobRecord, MemoryStore, type MemoryStoreOptions, type NoRunnerReason, PairingRecord, PollingDeliveryDeps, type PumpReport, ReleaseArgs, RenewArgs, RenewResult, ResultDelivery, type RunnerAvailability, RunnerRecord, TouchArgs, WaitOptions, capabilityFor, createFetchHandler, formatSiteKeys, generateDeviceCode, generateJobId, generateRunnerId, generateRunnerToken, generateSiteKeys, generateUserCode, hashSecret, normalizeUserCode, routeEndpoint, secretsMatch, signatureFrom, siteKeysFromEnv };
+export { AdoptArgs, ApproveArgs, type AvailabilityQuery, ByollmApp, type ByollmAppOptions, ByollmStore, ClaimArgs, CloudLane, type CloudLaneOptions, CompleteArgs, CompleteResult, EnqueueInput, HandlerConfig, type JobHandle, JobRecord, MemoryStore, type MemoryStoreOptions, type NoRunnerReason, PairingRecord, PollingDeliveryDeps, type PumpReport, RelayUnavailable, ReleaseArgs, RenewArgs, RenewResult, ResultDelivery, type RunnerAvailability, RunnerRecord, TouchArgs, WaitOptions, capabilityFor, createFetchHandler, formatSiteKeys, generateDeviceCode, generateJobId, generateRunnerId, generateSiteKeys, generateUserCode, hashSecret, normalizeUserCode, routeEndpoint, secretsMatch, signatureFrom, siteKeysFromEnv };