sublera-cli 0.0.0-stage → 1.3.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,37 @@
+# Third-Party Notices
+
+Sublet CLI is MIT-licensed. It depends on the following packages; none of their
+code is modified in this repository.
+
+## Runtime dependencies
+
+| Package | License | Use |
+| --- | --- | --- |
+| `adm-zip` | MIT | Extract official llama.cpp Windows ZIP releases |
+| `tar` | ISC | Extract official llama.cpp Linux/macOS tarballs |
+| `ws` | MIT | Outbound WebSocket tunnel and reconnect handling |
+| `undici` | MIT | HTTP(S) proxy support for downloads and API calls; loaded only when a proxy is set |
+
+## Development dependencies
+
+| Package | License |
+| --- | --- |
+| `typescript` | Apache-2.0 |
+| `tsx` | MIT |
+| `@types/node` | MIT |
+| `@types/ws` | MIT |
+| `@types/tar` | MIT |
+| `@types/adm-zip` | MIT |
+
+## Downloaded at runtime, not bundled
+
+- **llama.cpp / `llama-server`** — MIT. Downloaded from the official
+  `ggml-org/llama.cpp` GitHub releases and checked against the published digest
+  when available.
+- **GGUF model weights** — each HuggingFace model has its own license. The CLI
+  does not bundle weights and does not grant rights to any model. Hosts are
+  responsible for following the model's license and acceptable-use terms.
+- **Node.js** — MIT.
+
+The Sublet marketplace server, wallet, and payment integrations are a separate
+codebase and are not covered by this repository's license.

package/dist/agent.d.ts

@@ -0,0 +1,270 @@
+import { EventEmitter } from 'node:events';
+import type { AgentConfig } from './config.js';
+import type { Logger } from './logger.js';
+import { type GpuOverride } from './hardware/gpuMonitor.js';
+import { type InspectedModel } from './engine/gguf.js';
+import { type DashboardState } from './ui/terminalDashboard.js';
+import { type AgentHealth } from './health.js';
+export type AgentOptions = {
+    config: AgentConfig;
+    logger: Logger;
+    simulation: boolean;
+    model?: string | null;
+    modelInfo?: InspectedModel | null;
+    publicMode?: boolean;
+    price?: number | null;
+    priceInUsd?: number | null;
+    priceOutUsd?: number | null;
+    /** Public mode: price per hour for the full GPU (default 0.5; 0 = no hourly rentals). Other modes send 0. */
+    priceHourUsd?: number | null;
+    context?: number;
+    slots?: number;
+    gpuOverride?: GpuOverride | null;
+    /** `sublera start <code>`: serve this request from the website. */
+    requestId?: string | null;
+    tokPerSec?: number | null;
+    autoInstall?: boolean;
+    requireChecksum?: boolean;
+    drainTimeoutMs?: number;
+    json?: boolean;
+    once?: boolean;
+    dashboard?: boolean;
+    /** Unit tests only: run this program as the engine instead of an installed llama-server. */
+    engine?: {
+        binaryPath: string;
+        baseArgs?: string[];
+        env?: NodeJS.ProcessEnv;
+    };
+};
+/** One request the server booked on this host. Several run side by side on the loaded model. */
+type Booking = {
+    requestId: string;
+    model: string | null;
+    verified: boolean;
+    timerStartedAt: number | null;
+    timerEndsAt: number | null;
+    hours: number | null;
+    pricePerHourNanos: number | null;
+    minTokS: number | null;
+    guaranteedNanos: number | null;
+    /** A speed seat that shares the GPU with other renters and per-token buyers. */
+    shared: boolean;
+    /** The reserved speed of a seat; null means the full GPU. */
+    tokS: number | null;
+    /** llama-server slots and per-slot context the booking runs with; restored after a restart. */
+    slots: number;
+    context: number;
+    /** When a booking frame or a status poll last confirmed it. */
+    seenAt: number;
+    timer: NodeJS.Timeout | null;
+};
+export type BookingView = Readonly<Pick<Booking, 'requestId' | 'verified' | 'timerStartedAt' | 'timerEndsAt' | 'hours' | 'minTokS' | 'guaranteedNanos' | 'shared' | 'tokS'>>;
+export declare class Agent extends EventEmitter {
+    private readonly options;
+    private readonly logger;
+    private readonly gpuMonitor;
+    private readonly sleepGuard;
+    private readonly dashboard;
+    private tunnel;
+    private runner;
+    private install;
+    private runnerModelPath;
+    private runnerContext;
+    /** The --parallel count the running llama-server was started with. */
+    private runnerSlotCount;
+    private gpu;
+    private model;
+    private cachedModels;
+    private me;
+    private meTimer;
+    private gpuTimer;
+    private activeJobs;
+    private stopped;
+    private readonly startup;
+    /** Aborts the download of a request the server stopped (released, cancelled, or taken back). */
+    private loadAbort;
+    /** A model download or engine start that replaces the runner: new inference waits. */
+    private loadingModel;
+    /** Any load frame in progress, including one that reuses the running model. */
+    private loadInFlight;
+    /** llama-server slots the last load asked for: more than one only for a shared booking. */
+    private bookingSlots;
+    /** Every booked request, keyed by requestId. */
+    private readonly bookings;
+    /**
+     * Bookings that ended in this session (end timer, reject, or dropped by the status poll) and
+     * when. Their earned share is already settled, so they are never added again.
+     */
+    private readonly endedIds;
+    /** Server clock minus this machine's clock, from the last `/api/agent/me` answer. */
+    private serverOffset;
+    /** Requests the last status poll listed as live: claimed, loading, verifying or active. */
+    private liveRequestIds;
+    /** The id of `me.activeRequest` (the server's newest live request) in the last status answer. */
+    private serverNewestId;
+    private pending;
+    /** What the dashboard shows with no request: the public model, or the model loaded with --model. */
+    private startupJob;
+    private tokenEarnedNanos;
+    /** Earned share of bookings that ended or were stopped in this session. */
+    private settledEarnedNanos;
+    private settledGuaranteedNanos;
+    private meInitialWallet;
+    private lastSpeed;
+    private lastTtft;
+    private persisted;
+    /** True while the restore after a restart works on state.json. */
+    private restoring;
+    private stateWrite;
+    private online;
+    private onlineWaiters;
+    private keyHandler;
+    private heartbeatAt;
+    private bookingTimer;
+    private logLines;
+    /** The engine's answer to the self-check prompt right after the current model was loaded. */
+    private engineBaseline;
+    private selfCheckAbort;
+    private draining;
+    private runStarted;
+    private stopPromise;
+    private readonly messageTasks;
+    private healthTimer;
+    private healthWrite;
+    constructor(options: AgentOptions);
+    get dashboardState(): DashboardState;
+    /** Every booked request, soonest end first. */
+    get activeBookings(): BookingView[];
+    /** The booking for this request, or null when it is not (or no longer) booked here. */
+    booking(requestId: string): BookingView | null;
+    /**
+     * True while something other than `requestId` still needs this agent: public selling, another
+     * booking, another request being loaded, or another request the server lists as live. A seat on
+     * the loaded model never gets a load frame, so during its model check only the server's list shows it.
+     */
+    servingOthers(requestId: string): boolean;
+    /** This machine's estimate of the server clock. */
+    private serverTime;
+    /** Remembers the server clock from a status answer, so ends are judged by server time even when this clock is off. */
+    private noteServerClock;
+    /** The loaded request that waits for its model check, or a loaded benchmark. Restarting llama-server would break it. */
+    private checkingRequest;
+    /** Keeps the machine awake for a booking (the same call for a booking frame and a status poll). */
+    private holdWakeLock;
+    private bookingView;
+    /** Bookings, a pending request, or a real load keep the machine awake. */
+    private get bookingWake();
+    private priceOutUsd;
+    private priceHourUsd;
+    get health(): AgentHealth;
+    private publishHealth;
+    /** Reject new work, finish in-flight inference up to a bounded grace period,
+     * then cancel leftovers and preserve booking state for server reconciliation. */
+    drain(timeoutMs?: number): Promise<void>;
+    waitForOnline(timeoutMs?: number): Promise<void>;
+    private markOnline;
+    /** After a crash or restart, reload the booked model and resume every booking saved in state.json. */
+    private restorePersistedBooking;
+    private restoreOwned;
+    /** Writes every booking to state.json (newest first), or removes the file when none is left. */
+    private persistBookings;
+    private sortedBookings;
+    /** Adds or updates a booking. A pending request with the same id becomes this booking. */
+    private upsertBooking;
+    private scheduleBookingEnd;
+    /** The end timer of one booking fired: remove only that booking. */
+    private finishBooking;
+    /**
+     * Removes one booking and books its earned share into the session total. A settled booking has
+     * ended: its id is remembered so a status answer built before the end cannot add it (and its
+     * earnings) a second time. `settle = false` only drops it (a restore that failed), so it is not remembered.
+     */
+    private removeBooking;
+    private clearBookingTimers;
+    /** The part of a booking's guaranteed pay that the time so far has earned. */
+    private bookingShare;
+    private bookingJob;
+    private baseJob;
+    /**
+     * Rebuilds the dashboard's request view from the bookings. Earnings are the per-token
+     * earnings plus the time-proportional share of every booking, active or settled.
+     */
+    private syncDashboard;
+    /** Removes state.json if this agent wrote it; `force` also removes the file a restore in progress is working on. */
+    private clearPersistedBooking;
+    run(): Promise<void>;
+    private runOwned;
+    private endpointFor;
+    /** Tells the server about a newly downloaded model, so the board can show it as ready on this host. */
+    private refreshCachedModels;
+    private prepareStartupModel;
+    private loadModel;
+    /**
+     * True while llama-server serves someone other than `owner`: an inference job, another
+     * booking, public selling, or another request whose model is loaded and in its model check
+     * (or a benchmark). A restart would cut them off, so it is not allowed then.
+     */
+    private runnerBusy;
+    /** Decides whether loading `path` reuses, restarts, or must not touch the running llama-server. */
+    private runnerPlan;
+    /** Requests are served on the slots llama-server really runs with. */
+    private capacity;
+    private ensureRunner;
+    /**
+     * Asks the engine one short fixed question and compares the answer's token probabilities:
+     * twice in a row after a load, and against the load-time answer after a crash restart. It only
+     * warns; the server's model checks decide. It runs when the engine's prompt cache is empty and
+     * no buyer is waiting, and a buyer's job cancels it.
+     */
+    private selfCheckEngine;
+    private runnerSlots;
+    private helloPayload;
+    private heartbeatPayload;
+    private handleMessage;
+    /**
+     * The server started a booking's clock. It may be for the request just loaded, or for a
+     * request that never had a load frame (a speed seat or hourly rental on the loaded model).
+     * Each booking keeps its own end timer; a model load in progress stays busy.
+     */
+    private applyBooking;
+    private handleInfer;
+    /**
+     * Whether the dashboard counts a job that starts now as per-token income: only while no paid
+     * booking (speed seat or full GPU) is active. A renter's tokens are paid by the hour, and in
+     * public mode per-token buyers are served beside speed seats, but an `infer` frame does not say
+     * whose job it is. That is by design: the server must not reveal which jobs are hidden model
+     * checks. So while rentals run, per-token earnings are left out of the session total; the
+     * wallet on the website is exact.
+     */
+    private earnsPerToken;
+    private estimateEarned;
+    /** The loaded model, when a load frame names it: the same SHA-256, or the same HuggingFace link when no hash is given. */
+    private loadedModelFor;
+    /** The slots llama-server should run with after a load that asks for `loadSlots`. */
+    private slotsAfterLoad;
+    private handleLoad;
+    private refreshMe;
+    /**
+     * Makes the bookings match the server's list of live requests: adds booked ones this agent
+     * missed (never one that already ended here or whose end has passed on the server's clock),
+     * updates timers, and drops bookings the server no longer lists. Also keeps the ids of every
+     * live request for servingOthers(). Returns the dropped ids.
+     */
+    private reconcileBookings;
+    private setupKeyboard;
+    private handleKey;
+    /** The website page with this host's earnings, reliability, and current request. */
+    private hostPageUrl;
+    private openExternal;
+    private copyText;
+    private cleanupKeyboard;
+    private startGpuPolling;
+    private releaseWakeLockIfIdle;
+    private updateGpuDashboard;
+    private fail;
+    stop(preserveState?: boolean): Promise<void>;
+    private stopOwned;
+    /** Frees the wake lock, tunnel, llama-server and terminal. run() calls it again when startup finishes after stop(). */
+    private releaseResources;
+}
+export {};