@byollm/server 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,634 @@
+import {
+  ByollmHandlers,
+  SERVED_PROTOCOL_VERSION,
+  bearerFrom,
+  createFetchHandler,
+  generateDeviceCode,
+  generateJobId,
+  generateRunnerId,
+  generateRunnerToken,
+  generateUserCode,
+  hashSecret,
+  routeEndpoint,
+  secretsMatch
+} from "./chunk-HL6EYHQ7.js";
+import {
+  NoRunnerAvailableError,
+  PollingDelivery,
+  ResultTimeoutError
+} from "./chunk-7RKXFPBZ.js";
+
+// src/app.ts
+import {
+  backendDescriptor,
+  matchAudience
+} from "@byollm/protocol";
+var DEFAULT_LIVENESS_MS = 35e3;
+var ByollmApp = class {
+  #store;
+  #now;
+  #livenessMs;
+  #delivery;
+  constructor(options) {
+    this.#store = options.store;
+    this.#now = options.now ?? Date.now;
+    this.#livenessMs = options.livenessMs ?? DEFAULT_LIVENESS_MS;
+    const deps = {
+      ...options.noRunnerGraceMs === void 0 ? {} : { graceMs: options.noRunnerGraceMs },
+      read: (jobId) => this.result(jobId),
+      availability: async (jobId) => {
+        const job = await this.#store.get(jobId);
+        if (!job)
+          return { available: false, reason: "unknown-job", blocked: false };
+        if (job.claimableAt === null) {
+          return { available: true, blocked: true };
+        }
+        const availability = await this.runnerAvailability({
+          kind: job.kind,
+          owner: job.owner,
+          audience: job.audience,
+          ...job.audienceAllow === void 0 ? {} : { audienceAllow: job.audienceAllow }
+        });
+        return {
+          available: availability.available,
+          ...availability.reason === void 0 ? {} : { reason: availability.reason },
+          blocked: false
+        };
+      }
+    };
+    this.#delivery = options.delivery?.(deps) ?? new PollingDelivery(deps);
+  }
+  /**
+   * Enqueue a job.
+   *
+   * `audience` defaults to `self` — the safe direction. Widening it means the
+   * result comes back marked untrusted (see {@link ByollmApp.result}), and
+   * the app is obliged to disclose that to whoever reads it.
+   */
+  async enqueue(input) {
+    const record = await this.#store.create(input, this.#now());
+    return {
+      id: record.id,
+      record,
+      result: (options) => this.#delivery.waitFor(record.id, options),
+      cancel: async () => {
+        await this.cancel(record.id);
+      }
+    };
+  }
+  /** Read a job's current state. */
+  async job(jobId) {
+    await this.#store.expireDue(this.#now());
+    return this.#store.get(jobId);
+  }
+  /**
+   * A job's result with its provenance attached.
+   *
+   * 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}).
+   */
+  async result(jobId) {
+    const job = await this.job(jobId);
+    if (!job) return null;
+    return {
+      jobId: job.id,
+      state: job.state,
+      ...job.outcome === null ? {} : { outcome: job.outcome },
+      ...job.provenance === null ? {} : { provenance: job.provenance }
+    };
+  }
+  /** 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());
+  }
+  /**
+   * Is there a live runner that could take a job of this shape?
+   *
+   * Runs the identical {@link matchAudience} rule the claim path uses, so the
+   * signal cannot promise a runner the claim would then refuse.
+   */
+  async runnerAvailability(query) {
+    const now = this.#now();
+    const all = await this.#store.listRunners();
+    const live = all.filter(
+      (runner) => runner.revokedAt === null && !runner.paused && now - runner.lastHeartbeatAt <= this.#livenessMs
+    );
+    if (all.length === 0) {
+      return { available: false, reason: "no-runner-paired", candidates: 0 };
+    }
+    if (live.length === 0) {
+      return { available: false, reason: "no-runner-online", candidates: 0 };
+    }
+    let capable = 0;
+    let admitted = 0;
+    for (const runner of live) {
+      const capability = runner.capabilities.find((c) => c.kind === query.kind);
+      if (!capability) continue;
+      capable += 1;
+      const match = matchAudience(
+        {
+          owner: query.owner,
+          audience: query.audience ?? "self",
+          audienceAllow: query.audienceAllow
+        },
+        {
+          owner: runner.owner,
+          offerScope: capability.offerScope,
+          account: backendDescriptor(capability.backendId).account,
+          // Same conservative assumption the claim path makes: the server
+          // cannot see a remote daemon's local allowlist (protocol §4.2).
+          locallyAllows: () => true
+        }
+      );
+      if (match.ok) admitted += 1;
+    }
+    if (capable === 0) {
+      return {
+        available: false,
+        reason: "no-matching-capability",
+        candidates: 0
+      };
+    }
+    if (admitted === 0) {
+      return {
+        available: false,
+        reason: "audience-admits-nobody",
+        candidates: 0
+      };
+    }
+    return { available: true, candidates: admitted };
+  }
+  /**
+   * Approve a pairing on behalf of an authenticated user.
+   *
+   * `owner` MUST come from the approving user's own session. A daemon can
+   * never assert who it is — that is the whole reason pairing is interactive
+   * ({@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()
+    });
+  }
+  /** Deny a pairing the user did not initiate. */
+  async denyPairing(userCode) {
+    return this.#store.denyPairing(normalizeUserCode(userCode), this.#now());
+  }
+  /** What a pairing code refers to, for the approval page to show. */
+  async pendingPairing(userCode) {
+    const pairing = await this.#store.getPairingByUserCode(
+      normalizeUserCode(userCode)
+    );
+    if (pairing?.state !== "pending") return null;
+    if (pairing.expiresAt <= this.#now()) return null;
+    return {
+      label: pairing.label,
+      platform: pairing.platform,
+      daemonVersion: pairing.daemonVersion,
+      capabilities: pairing.capabilities.map((c) => ({
+        kind: c.kind,
+        model: c.model
+      })),
+      expiresAt: pairing.expiresAt
+    };
+  }
+  /** The user's paired runners, for a settings page. */
+  async runners(owner) {
+    return this.#store.listRunners(owner);
+  }
+  /** Revoke a runner. It stops at its next heartbeat, mid-queue. */
+  async revokeRunner(runnerId) {
+    return this.#store.revokeRunner(runnerId, this.#now());
+  }
+  /** Run the expiry sweep. Idempotent; safe to call on a timer or a request. */
+  async sweep() {
+    return this.#store.expireDue(this.#now());
+  }
+};
+function normalizeUserCode(input) {
+  const bare = input.toUpperCase().replace(/[^A-Z0-9]/g, "");
+  return bare.length === 8 ? `${bare.slice(0, 4)}-${bare.slice(4)}` : bare;
+}
+
+// src/memory.ts
+import {
+  backendDescriptor as backendDescriptor2,
+  matchAudience as matchAudience2
+} from "@byollm/protocol";
+var DEFAULT_TTL_MS = 15 * 6e4;
+var MemoryStore = class {
+  #jobs = /* @__PURE__ */ new Map();
+  #runners = /* @__PURE__ */ new Map();
+  #pairings = /* @__PURE__ */ new Map();
+  /** Job ids the app has asked to cancel, not yet acknowledged by a runner. */
+  #cancelRequests = /* @__PURE__ */ new Set();
+  #defaultTtlMs;
+  constructor(options = {}) {
+    this.#defaultTtlMs = options.defaultTtlMs ?? DEFAULT_TTL_MS;
+  }
+  // -- jobs ---------------------------------------------------------------
+  create(input, now) {
+    const id = input.id ?? generateJobId();
+    const existing = this.#jobs.get(id);
+    if (existing) return Promise.resolve(existing);
+    const dependsOn = [...input.dependsOn ?? []];
+    const blocked = dependsOn.some(
+      (depId) => this.#jobs.get(depId)?.state !== "ok"
+    );
+    const job = {
+      id,
+      kind: input.kind,
+      payload: input.payload,
+      audience: input.audience ?? "self",
+      owner: input.owner,
+      audienceAllow: input.audienceAllow ? [...input.audienceAllow] : void 0,
+      dependsOn,
+      state: "queued",
+      lease: null,
+      createdAt: now,
+      // The TTL clock starts here only if nothing blocks the job.
+      claimableAt: blocked ? null : now,
+      ttlMs: input.ttlMs ?? this.#defaultTtlMs,
+      deadlineAt: input.deadlineAt ?? null,
+      refusedBy: [],
+      attempts: 0,
+      outcome: null,
+      provenance: null,
+      updatedAt: now
+    };
+    this.#jobs.set(id, job);
+    return Promise.resolve(job);
+  }
+  get(jobId) {
+    return Promise.resolve(this.#jobs.get(jobId) ?? null);
+  }
+  claim(args) {
+    this.#expireDueSync(args.now);
+    const claimed = [];
+    const candidates = [...this.#jobs.values()].sort(
+      (a, b) => (a.claimableAt ?? Infinity) - (b.claimableAt ?? Infinity)
+    );
+    for (const job of candidates) {
+      if (claimed.length >= args.max) break;
+      if (!this.#isClaimable(job, args)) continue;
+      const updated = {
+        ...job,
+        state: "claimed",
+        lease: {
+          runnerId: args.runnerId,
+          expiresAt: args.now + args.leaseMs
+        },
+        attempts: job.attempts + 1,
+        updatedAt: args.now
+      };
+      this.#jobs.set(job.id, updated);
+      claimed.push(updated);
+    }
+    return Promise.resolve(claimed);
+  }
+  /**
+   * The claim predicate, shared by `claim` and the no-runner signal so the
+   * two can never disagree about what "a runner that could take this" means.
+   */
+  #isClaimable(job, args) {
+    if (job.state !== "queued") return false;
+    if (job.claimableAt === null || job.claimableAt > args.now) return false;
+    if (job.refusedBy.includes(args.runnerId)) return false;
+    const capability = capabilityFor(args.capabilities, job.kind);
+    if (!capability) return false;
+    const match = matchAudience2(
+      {
+        owner: job.owner,
+        audience: job.audience,
+        audienceAllow: job.audienceAllow
+      },
+      {
+        owner: args.runnerOwner,
+        offerScope: capability.offerScope,
+        // From the registry, not a local guess — the subscription self-lock
+        // must mean the same thing on both sides of the wire.
+        account: backendDescriptor2(capability.backendId).account,
+        // The server cannot see a remote daemon's local allowlist and must
+        // not pretend to (protocol §4.2). It admits the job here; the daemon
+        // is the enforcing side and releases with `refused` if its own list
+        // says no.
+        locallyAllows: () => true
+      }
+    );
+    return match.ok;
+  }
+  renewLeases(args) {
+    this.#expireDueSync(args.now);
+    const renewed = [];
+    const lost = [];
+    for (const jobId of args.jobIds) {
+      const job = this.#jobs.get(jobId);
+      if (!job || job.lease?.runnerId !== args.runnerId) {
+        lost.push(jobId);
+        continue;
+      }
+      if (job.state !== "claimed" && job.state !== "running") {
+        lost.push(jobId);
+        continue;
+      }
+      const expiresAt = args.now + args.leaseMs;
+      this.#jobs.set(jobId, {
+        ...job,
+        state: "running",
+        lease: { runnerId: args.runnerId, expiresAt },
+        updatedAt: args.now
+      });
+      renewed.push({ jobId, expiresAt });
+    }
+    return Promise.resolve({ renewed, lost });
+  }
+  complete(args) {
+    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") {
+      return Promise.resolve({ accepted: false, job });
+    }
+    if (job.state === "expired") {
+      return Promise.resolve({ accepted: false, job });
+    }
+    if (job.lease?.runnerId !== args.runnerId) {
+      return Promise.resolve({ accepted: false, job });
+    }
+    const state = args.outcome.outcome === "ok" ? "ok" : args.outcome.outcome === "canceled" ? "canceled" : "error";
+    const updated = {
+      ...job,
+      state,
+      lease: null,
+      outcome: args.outcome,
+      provenance: args.provenance,
+      updatedAt: args.now
+    };
+    this.#jobs.set(job.id, updated);
+    this.#cancelRequests.delete(job.id);
+    if (state === "ok") this.#unblockDependents(job.id, args.now);
+    return Promise.resolve({ accepted: true, job: updated });
+  }
+  /**
+   * Start the TTL clock on anything this job was blocking.
+   *
+   * Deliberately only on `ok`: a dependency that errored leaves its dependents
+   * blocked forever rather than releasing them into a run whose input never
+   * arrived. They expire at their absolute deadline if one was set, and the
+   * app sees a chain that stopped where it broke.
+   */
+  #unblockDependents(completedId, now) {
+    for (const job of this.#jobs.values()) {
+      if (job.claimableAt !== null) continue;
+      if (!job.dependsOn.includes(completedId)) continue;
+      const ready = job.dependsOn.every(
+        (depId) => this.#jobs.get(depId)?.state === "ok"
+      );
+      if (ready) {
+        this.#jobs.set(job.id, { ...job, claimableAt: now, updatedAt: now });
+      }
+    }
+  }
+  release(args) {
+    const released = [];
+    for (const jobId of args.jobIds) {
+      const job = this.#jobs.get(jobId);
+      if (!job || job.lease?.runnerId !== args.runnerId) continue;
+      this.#jobs.set(jobId, {
+        ...job,
+        state: "queued",
+        lease: 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
+        // release forever ({@link MUSTS.REFUSAL_NOT_REOFFERED}).
+        refusedBy: args.reason === "refused" ? [.../* @__PURE__ */ new Set([...job.refusedBy, args.runnerId])] : job.refusedBy,
+        updatedAt: args.now
+      });
+      released.push(jobId);
+    }
+    return Promise.resolve(released);
+  }
+  expireDue(now) {
+    return Promise.resolve(this.#expireDueSync(now));
+  }
+  /**
+   * Lease expiry and TTL expiry in one idempotent sweep.
+   *
+   * Order matters: a lease is reclaimed *before* the TTL is judged, so a job
+   * whose runner died is offered again rather than being expired for having
+   * sat in `claimed` too long.
+   */
+  #expireDueSync(now) {
+    const changed = [];
+    for (const job of this.#jobs.values()) {
+      if ((job.state === "claimed" || job.state === "running") && job.lease !== null && job.lease.expiresAt <= now) {
+        const requeued = {
+          ...job,
+          state: "queued",
+          lease: 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
+          // actively worked on — losing exactly the work `kill -9` recovery
+          // exists to save. Total lifetime is bounded by `deadlineAt`, which
+          // is absolute and unaffected by reclaim.
+          claimableAt: now,
+          updatedAt: now
+        };
+        this.#jobs.set(job.id, requeued);
+        changed.push(requeued);
+      }
+    }
+    for (const job of this.#jobs.values()) {
+      if (job.state !== "queued") continue;
+      const pastDeadline = job.deadlineAt !== null && job.deadlineAt <= now;
+      const pastTtl = job.claimableAt !== null && job.claimableAt + job.ttlMs <= now;
+      if (!pastDeadline && !pastTtl) continue;
+      const expired = {
+        ...job,
+        state: "expired",
+        lease: null,
+        updatedAt: now
+      };
+      this.#jobs.set(job.id, expired);
+      changed.push(expired);
+    }
+    return changed;
+  }
+  cancel(jobId, now) {
+    const job = this.#jobs.get(jobId);
+    if (!job) return Promise.resolve(null);
+    if (job.state === "queued") {
+      const canceled = {
+        ...job,
+        state: "canceled",
+        lease: null,
+        updatedAt: now
+      };
+      this.#jobs.set(jobId, canceled);
+      return Promise.resolve(canceled);
+    }
+    if (job.state === "claimed" || job.state === "running") {
+      this.#cancelRequests.add(jobId);
+      return Promise.resolve(job);
+    }
+    return Promise.resolve(job);
+  }
+  listClaimedBy(runnerId) {
+    return Promise.resolve(
+      [...this.#jobs.values()].filter(
+        (job) => job.lease?.runnerId === runnerId
+      )
+    );
+  }
+  listCancelRequests(runnerId) {
+    return Promise.resolve(
+      [...this.#cancelRequests].filter(
+        (jobId) => this.#jobs.get(jobId)?.lease?.runnerId === runnerId
+      )
+    );
+  }
+  // -- pairing and runners -------------------------------------------------
+  createPairing(record) {
+    this.#pairings.set(record.deviceCodeHash, record);
+    return Promise.resolve();
+  }
+  getPairingByDeviceCodeHash(hash) {
+    return Promise.resolve(this.#pairings.get(hash) ?? null);
+  }
+  getPairingByUserCode(userCode) {
+    for (const pairing of this.#pairings.values()) {
+      if (pairing.userCode === userCode) return Promise.resolve(pairing);
+    }
+    return Promise.resolve(null);
+  }
+  approvePairing(args) {
+    const pairing = [...this.#pairings.values()].find(
+      (p) => p.userCode === args.userCode
+    );
+    if (!pairing) throw new Error(`unknown pairing code: ${args.userCode}`);
+    if (pairing.expiresAt <= args.now) {
+      throw new Error("pairing code has expired");
+    }
+    if (pairing.state !== "pending") {
+      throw new Error(`pairing is already ${pairing.state}`);
+    }
+    const runner = {
+      id: args.runnerId,
+      owner: args.owner,
+      tokenHash: args.tokenHash,
+      label: pairing.label,
+      platform: pairing.platform,
+      daemonVersion: pairing.daemonVersion,
+      capabilities: pairing.capabilities,
+      paused: false,
+      revokedAt: null,
+      lastHeartbeatAt: args.now,
+      createdAt: args.now
+    };
+    this.#runners.set(runner.id, runner);
+    this.#pairings.set(pairing.deviceCodeHash, {
+      ...pairing,
+      state: "approved",
+      owner: args.owner,
+      runnerId: runner.id,
+      runnerTokenOnce: args.runnerToken
+    });
+    return Promise.resolve(runner);
+  }
+  denyPairing(userCode, _now) {
+    const pairing = [...this.#pairings.values()].find(
+      (p) => p.userCode === userCode
+    );
+    if (pairing) {
+      this.#pairings.set(pairing.deviceCodeHash, {
+        ...pairing,
+        state: "denied"
+      });
+    }
+    return Promise.resolve();
+  }
+  consumePairingToken(deviceCodeHash) {
+    const pairing = this.#pairings.get(deviceCodeHash);
+    if (pairing) {
+      this.#pairings.set(deviceCodeHash, {
+        ...pairing,
+        runnerTokenOnce: null
+      });
+    }
+    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);
+  }
+  touchRunner(args) {
+    const runner = this.#runners.get(args.runnerId);
+    if (!runner) return Promise.resolve(null);
+    const updated = {
+      ...runner,
+      capabilities: args.capabilities,
+      daemonVersion: args.daemonVersion,
+      paused: args.paused,
+      lastHeartbeatAt: args.now
+    };
+    this.#runners.set(runner.id, updated);
+    return Promise.resolve(updated);
+  }
+  revokeRunner(runnerId, now) {
+    const runner = this.#runners.get(runnerId);
+    if (runner?.revokedAt === null) {
+      this.#runners.set(runnerId, { ...runner, revokedAt: now });
+    }
+    return Promise.resolve();
+  }
+  listRunners(owner) {
+    const all = [...this.#runners.values()];
+    return Promise.resolve(
+      owner === void 0 ? all : all.filter((r) => r.owner === owner)
+    );
+  }
+  // -- test/demo helpers ---------------------------------------------------
+  /** All jobs, for demos and assertions. Not part of the store interface. */
+  allJobs() {
+    return [...this.#jobs.values()];
+  }
+};
+function capabilityFor(capabilities, kind) {
+  return capabilities.find((c) => c.kind === kind);
+}
+export {
+  ByollmApp,
+  ByollmHandlers,
+  MemoryStore,
+  NoRunnerAvailableError,
+  PollingDelivery,
+  ResultTimeoutError,
+  SERVED_PROTOCOL_VERSION,
+  bearerFrom,
+  capabilityFor,
+  createFetchHandler,
+  generateDeviceCode,
+  generateJobId,
+  generateRunnerId,
+  generateRunnerToken,
+  generateUserCode,
+  hashSecret,
+  normalizeUserCode,
+  routeEndpoint,
+  secretsMatch
+};
+//# sourceMappingURL=index.js.map