byollm 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,913 @@
+import { z } from 'zod';
+import { BackendId, BackendClass, JobKind, OfferScope, Capability, PairStartResponse, PairPollResponse, ClaimResponse, HeartbeatResponse, JobOutcome, ResultResponse, ReleaseResponse, ClaimedJob, Audience } from '@byollm/protocol';
+
+/**
+ * One person, on one server, allowed to run work on this machine.
+ *
+ * Keyed by **(server origin, user id)** because owner ids are
+ * server-namespace-local: `alice` on one app is not `alice` on another, and a
+ * list keyed by id alone would silently merge strangers.
+ */
+declare const AllowEntry: z.ZodObject<{
+    origin: z.ZodString;
+    owner: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    addedAt: z.ZodNumber;
+}, z.core.$strict>;
+type AllowEntry = z.infer<typeof AllowEntry>;
+/**
+ * The daemon's local `named` allowlist.
+ *
+ * byollm_001 Rev 1 §B: a `named` job is admitted only when *this* list names
+ * its owner. A server's assertion that a runner is allowed is never enough —
+ * honouring it would mean obeying the server rather than enforcing against
+ * it. One file, every paired app, so the owner has one place to see everyone
+ * who can use their machine.
+ *
+ * The list is **empty by default**, which is what makes a fresh daemon
+ * effectively self-only until the owner deliberately widens it.
+ */
+declare class Allowlist {
+    #private;
+    constructor(path: string);
+    load(): Promise<void>;
+    /** Does this list admit `owner` on `origin`? */
+    admits(origin: string, owner: string): boolean;
+    /** A predicate bound to one origin, for {@link matchAudience}. */
+    predicateFor(origin: string): (owner: string) => boolean;
+    list(): readonly AllowEntry[];
+    add(entry: Omit<AllowEntry, "addedAt">, now: number): Promise<void>;
+    /** Remove an entry. Returns whether anything was removed. */
+    remove(origin: string, owner: string): Promise<boolean>;
+}
+/**
+ * Compare origins by scheme, host and port only.
+ *
+ * `https://app.test/` and `https://app.test` must be the same entry — a
+ * trailing slash is not a different server, and treating it as one would let
+ * an allowlist silently fail to match.
+ */
+declare function normalizeOrigin(input: string): string;
+
+/**
+ * Where the daemon keeps its state.
+ *
+ * One directory the owner can `ls`, `cat` and delete. The trust surface is
+ * the product (byollm_002), and a trust surface you cannot find is not one.
+ */
+interface DaemonPaths {
+    /** `~/.byollm` — everything below lives here. */
+    readonly root: string;
+    /** Job routing and backend configuration, owner-authored. */
+    readonly config: string;
+    /** Paired servers: origin, runner id, token, owner. */
+    readonly pairings: string;
+    /** The local `named` allowlist — one file, every app. */
+    readonly allowlist: string;
+    /** Append-only JSONL: every prompt that has run on this machine. */
+    readonly ingressLog: string;
+    /** Community-job counters, for rate limits and the daily cap. */
+    readonly budgets: string;
+    /** Set while the owner has the daemon paused. */
+    readonly pauseFlag: string;
+    /**
+     * Per-job scratch directories. A process-class backend runs with its `cwd`
+     * set to an empty one of these and nothing else (byollm_004 §2).
+     */
+    readonly scratch: string;
+}
+/** Resolve the daemon's paths, rooted at `~/.byollm` unless overridden. */
+declare function daemonPaths(root?: string): DaemonPaths;
+/**
+ * `BYOLLM_HOME` exists so the conformance kit and the adversarial suite can
+ * run real daemons without touching the developer's own `~/.byollm`.
+ */
+declare function defaultRoot(): string;
+
+/** Exit codes: 0 fine, 1 a real failure, 2 the user asked for something wrong. */
+type ExitCode = 0 | 1 | 2;
+/**
+ * Everything the CLI touches outside itself.
+ *
+ * byollm_002 calls the meter the product's soul, which means it has to be
+ * testable rather than merely observable by a human at a terminal. Injecting
+ * the streams, the state directory and the confirmation prompt lets the tests
+ * drive the real commands against a temporary `BYOLLM_HOME`.
+ */
+interface CliIo {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+    /** Answers the scarier-confirmation prompt when widening access. */
+    readonly confirm: (question: string) => Promise<boolean>;
+}
+/** Run one command. Exported so the tests drive the same code a user does. */
+declare function runCli(argv: readonly string[], options?: {
+    paths?: DaemonPaths;
+    io?: Partial<CliIo>;
+    /**
+     * Stops the polling loop. The executable wires this to SIGINT/SIGTERM;
+     * anything embedding the CLI (including its tests) can stop it the same
+     * way rather than by killing the process.
+     */
+    signal?: AbortSignal;
+}): Promise<ExitCode>;
+/** The `byollm` executable. */
+declare function main(argv: readonly string[]): Promise<ExitCode>;
+
+/**
+ * The text of one model call, already composed by the daemon.
+ *
+ * Note what a backend receives: a string and a model name. It gets no access
+ * to the job, the payload object, or anything that could carry routing. By
+ * the time execution reaches here, the payload has been reduced to the only
+ * thing byollm_004 §1 permits a job to cause — text sent to a model.
+ */
+interface BackendRequest {
+    /** The composed prompt text. */
+    readonly prompt: string;
+    /** The model, from owner config only ({@link MUSTS.NO_PAYLOAD_ROUTING}). */
+    readonly model: string;
+    /** Hard wall-clock ceiling. */
+    readonly timeoutMs: number;
+    /** Hard output ceiling; output past this truncates and fails the job. */
+    readonly maxOutputBytes: number;
+    /** Aborts the in-flight call — how cancel and revocation take effect. */
+    readonly signal: AbortSignal;
+}
+type BackendResult = {
+    readonly ok: true;
+    readonly text: string;
+    readonly durationMs: number;
+} | {
+    readonly ok: false;
+    readonly code: BackendErrorCode;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly durationMs: number;
+};
+/**
+ * Why a backend call failed.
+ *
+ * Distinct codes because byollm_002 requires that different truths never
+ * share a message: an owner whose model server is down needs a different
+ * sentence from one whose job hit its timeout.
+ */
+type BackendErrorCode = "backend-unreachable" | "backend-error" | "model-not-found" | "timeout" | "output-too-large" | "canceled" | "unauthorized";
+/** Whether a backend is usable right now, and with which models. */
+interface BackendHealth {
+    readonly healthy: boolean;
+    /** Models the backend reports; empty when it could not be reached. */
+    readonly models: readonly string[];
+    /** Why it is unhealthy — shown verbatim in `byollm status`. */
+    readonly detail?: string;
+}
+/**
+ * A way of reaching a model.
+ *
+ * Implementations are registered in {@link BACKENDS} and must ship
+ * adversarial-suite rows before they can be added — the coverage check in the
+ * adversarial suite enforces that, so a new backend cannot arrive without its
+ * hostile-payload corpus.
+ */
+interface Backend {
+    readonly id: BackendId;
+    readonly class: BackendClass;
+    /**
+     * Can this backend serve work right now, and with what?
+     *
+     * The capability matrix is config ∩ *this*
+     * ({@link MUSTS.CAPABILITY_IS_DETECTED}) — a configured but unreachable
+     * backend must never be advertised.
+     */
+    health(): Promise<BackendHealth>;
+    /** Run one model call. The only thing a job is permitted to cause. */
+    execute(request: BackendRequest): Promise<BackendResult>;
+}
+/** Everything a backend instance needs from the owner's config. */
+interface BackendInit {
+    /** HTTP-class only. Already validated by {@link checkBaseUrl}. */
+    readonly baseUrl?: string | undefined;
+    /** Name of the env var holding an API key, if the server needs one. */
+    readonly apiKeyEnv?: string | undefined;
+}
+
+/** Build the child's environment from the allowlist. */
+declare function childEnv(source?: NodeJS.ProcessEnv): Record<string, string>;
+/** The argv this backend would run for a given model. Exported for the suite. */
+declare function claudeArgv(model: string): readonly string[];
+/**
+ * The process-class backend: the user's own `claude` CLI, on their own
+ * subscription.
+ *
+ * Subscription-class, so its offer scope is locked to `self`
+ * ({@link MUSTS.SUBSCRIPTION_SELF_LOCK}) — one account runs one person's work.
+ *
+ * Every requirement of byollm_004 §2 applies here and is implemented here:
+ * fixed argv, prompt on stdin, stripped environment, empty scratch `cwd`, no
+ * inherited descriptors beyond the three std streams, hard timeout, hard
+ * output cap.
+ */
+declare class ClaudeCliBackend implements Backend {
+    #private;
+    readonly id: BackendId;
+    readonly class: BackendClass;
+    /**
+     * @param binary - which executable to run. Defaults to `claude` and is
+     * **not reachable from configuration**: {@link createBackend} constructs
+     * this with no arguments, and {@link BackendInit} has no field for it. It
+     * exists so the adversarial suite can substitute a probe that reports the
+     * argv, environment, cwd and stdin it actually received — which is the only
+     * way to *prove* byollm_004 §2 rather than assert it.
+     */
+    constructor(binary?: string);
+    health(): Promise<BackendHealth>;
+    execute(request: BackendRequest): Promise<BackendResult>;
+}
+
+/**
+ * The HTTP-class backend: any server speaking OpenAI-compatible
+ * `/v1/chat/completions`.
+ *
+ * One implementation covers Ollama, `mlx_lm.server`, llama.cpp server and
+ * vLLM (byollm_001 Rev 1 §A) — the collapse that puts MLX inference in v1.
+ *
+ * **Why this is the safest class.** It spawns nothing, so byollm_004 §2's
+ * argv, stdin, environment and sandbox requirements do not apply *by
+ * construction* rather than by discipline. The prompt travels as a JSON
+ * string in a request body; there is no command line for it to escape into
+ * because there is no command line.
+ *
+ * What remains is the destination, and that is nailed down: the base URL
+ * comes from owner config, is validated once at load and again here, and
+ * redirects are refused so a permitted URL cannot become a forbidden one in
+ * flight ({@link MUSTS.HTTP_BASE_URL_SAFE}).
+ */
+declare class OpenAiHttpBackend implements Backend {
+    #private;
+    readonly id: BackendId;
+    readonly class: BackendClass;
+    constructor(init: BackendInit);
+    health(): Promise<BackendHealth>;
+    execute(request: BackendRequest): Promise<BackendResult>;
+}
+
+/**
+ * Construct a backend instance.
+ *
+ * The switch is exhaustive over {@link BackendId}, so adding a backend to the
+ * protocol registry without implementing it here is a compile error rather
+ * than a runtime surprise — and adding one without adversarial rows fails the
+ * suite's coverage check.
+ */
+declare function createBackend(id: BackendId, init: BackendInit): Backend;
+/** Every backend the daemon can construct. */
+declare const IMPLEMENTED_BACKEND_IDS: readonly BackendId[];
+
+/**
+ * One configured backend instance.
+ *
+ * `openai-http` may be configured many times — one per model server the owner
+ * runs (Ollama here, `mlx_lm.server` there, a llama.cpp box on the LAN). That
+ * is byollm_001 Rev 1 §A's "one backend, N base URLs".
+ */
+declare const BackendConfig: z.ZodObject<{
+    backend: z.ZodEnum<{
+        "openai-http": "openai-http";
+        "claude-cli": "claude-cli";
+    }>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    offer: z.ZodDefault<z.ZodEnum<{
+        self: "self";
+        named: "named";
+        public: "public";
+    }>>;
+    apiKeyEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type BackendConfig = z.infer<typeof BackendConfig>;
+/** Which backend instance and model serves a job kind. */
+declare const RouteConfig: z.ZodObject<{
+    backend: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strict>;
+type RouteConfig = z.infer<typeof RouteConfig>;
+/**
+ * Budgets applied to jobs whose owner is not this machine's owner
+ * ({@link MUSTS.COMMUNITY_BUDGETS}).
+ */
+declare const CommunityBudget: z.ZodObject<{
+    maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
+    maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
+    maxWallClockMs: z.ZodDefault<z.ZodNumber>;
+    maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+    maxPayloadChars: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type CommunityBudget = z.infer<typeof CommunityBudget>;
+/** Ingress-log retention (byollm_004 Rev 1). */
+declare const IngressRetention: z.ZodObject<{
+    communityPromptDays: z.ZodDefault<z.ZodNumber>;
+    keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+type IngressRetention = z.infer<typeof IngressRetention>;
+/** Ceilings applied to every job, community or not. */
+declare const Limits: z.ZodObject<{
+    maxWallClockMs: z.ZodDefault<z.ZodNumber>;
+    maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type Limits = z.infer<typeof Limits>;
+declare const DaemonConfig: z.ZodObject<{
+    backends: z.ZodRecord<z.ZodString, z.ZodObject<{
+        backend: z.ZodEnum<{
+            "openai-http": "openai-http";
+            "claude-cli": "claude-cli";
+        }>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        offer: z.ZodDefault<z.ZodEnum<{
+            self: "self";
+            named: "named";
+            public: "public";
+        }>>;
+        apiKeyEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    routes: z.ZodRecord<z.ZodEnum<{
+        "llm.generate": "llm.generate";
+        "llm.chat": "llm.chat";
+    }> & z.core.$partial, z.ZodObject<{
+        backend: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    community: z.ZodPrefault<z.ZodObject<{
+        maxJobsPerHour: z.ZodDefault<z.ZodNumber>;
+        maxJobsPerDay: z.ZodDefault<z.ZodNumber>;
+        maxWallClockMs: z.ZodDefault<z.ZodNumber>;
+        maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+        maxPayloadChars: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    ingress: z.ZodPrefault<z.ZodObject<{
+        communityPromptDays: z.ZodDefault<z.ZodNumber>;
+        keepSelfPrompts: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    limits: z.ZodPrefault<z.ZodObject<{
+        maxWallClockMs: z.ZodDefault<z.ZodNumber>;
+        maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type DaemonConfig = z.infer<typeof DaemonConfig>;
+/** A route resolved against its backend, ready to execute. */
+interface ResolvedRoute {
+    readonly kind: z.infer<typeof JobKind>;
+    readonly backendKey: string;
+    readonly backendId: BackendId;
+    readonly backendClass: "http" | "process";
+    readonly model: string;
+    /** After the subscription lock is applied — never the raw configured value. */
+    readonly offerScope: z.infer<typeof OfferScope>;
+    readonly baseUrl: string | undefined;
+    readonly apiKeyEnv: string | undefined;
+}
+interface ConfigProblem {
+    readonly where: string;
+    readonly message: string;
+}
+interface LoadedConfig {
+    readonly config: DaemonConfig;
+    readonly routes: readonly ResolvedRoute[];
+    /** Non-fatal problems: a route that cannot be served is dropped, not fatal. */
+    readonly problems: readonly ConfigProblem[];
+}
+/** The config used when the owner has not written one. */
+declare const DEFAULT_CONFIG: DaemonConfig;
+/**
+ * Read and resolve `~/.byollm/config.json`.
+ *
+ * A missing file yields {@link DEFAULT_CONFIG}; a malformed one throws,
+ * because silently running with defaults when the owner *did* write a config
+ * would execute work under rules they did not choose.
+ */
+declare function loadConfig(path: string): Promise<LoadedConfig>;
+/**
+ * Turn a parsed config into executable routes, applying the subscription lock
+ * and rejecting unusable backends.
+ *
+ * A problem here is not fatal: a machine with three routes and one broken
+ * backend should serve the other two and say so, rather than refusing to
+ * start. What it must never do is *advertise* the broken one
+ * ({@link MUSTS.CAPABILITY_IS_DETECTED}).
+ */
+declare function resolveConfig(config: DaemonConfig): LoadedConfig;
+
+type BudgetRefusal = "hourly-cap" | "daily-cap" | "payload-too-large";
+type BudgetDecision = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly refusal: BudgetRefusal;
+    readonly detail: string;
+};
+/**
+ * The owner's ceiling on work done for other people
+ * ({@link MUSTS.COMMUNITY_BUDGETS}).
+ *
+ * byollm_004 §4 distinguishes two directions of abuse, and this is the one
+ * aimed *at* the volunteer: a stranger who can enqueue unlimited `public`
+ * jobs owns your GPU. Jobs for the machine's own owner are never counted —
+ * their machine, their call.
+ */
+declare class Budgets {
+    #private;
+    constructor(path: string, limits: CommunityBudget);
+    load(now: number): Promise<void>;
+    /**
+     * May this community job run?
+     *
+     * @param payloadChars - total payload text length, checked against the
+     * stricter community limit rather than the protocol's absolute ceiling.
+     */
+    check(now: number, payloadChars: number): BudgetDecision;
+    /** Count a community job as accepted. Call only after {@link check} passes. */
+    record(now: number): Promise<void>;
+    /** Current usage, for `byollm status`. */
+    usage(now: number): {
+        hour: number;
+        day: number;
+        limits: CommunityBudget;
+    };
+}
+
+/**
+ * Why a protocol call failed, from the daemon's seat.
+ *
+ * byollm_002 requires that "server unreachable", "revoked", "no matching
+ * work" and "backend down" never share a message. Three of those are
+ * distinguishable here; the fourth is a local condition the loop reports
+ * itself. "No matching work" is deliberately *not* an error — it is a `200`
+ * with an empty list.
+ */
+type ClientErrorKind = "unreachable" | "revoked" | "unauthorized" | "rejected" | "rate-limited" | "server-error" | "malformed-response";
+declare class ClientError extends Error {
+    readonly kind: ClientErrorKind;
+    /** Seconds the server asked us to wait, when it said. */
+    readonly retryAfter?: number | undefined;
+    readonly name = "ClientError";
+    constructor(kind: ClientErrorKind, message: string, 
+    /** Seconds the server asked us to wait, when it said. */
+    retryAfter?: number | undefined);
+    /** Is retrying this same call plausibly useful? */
+    get retryable(): boolean;
+}
+interface ClientOptions {
+    /** The app's origin, e.g. `https://app.example.com`. */
+    readonly origin: string;
+    /** Bearer token from pairing. Absent while pairing. */
+    readonly token?: string | undefined;
+    /** Per-request timeout. */
+    readonly timeoutMs?: number;
+    /** Injectable fetch, for tests. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * The daemon's outbound protocol client.
+ *
+ * Every call is outbound; nothing here ever listens. That is the whole
+ * network posture of the product, and it lives in this one class.
+ */
+declare class ProtocolClient {
+    #private;
+    constructor(options: ClientOptions);
+    /** A client for the same origin carrying a token. */
+    withToken(token: string): ProtocolClient;
+    get origin(): string;
+    pairStart(input: {
+        version: string;
+        label: string;
+        platform: "darwin" | "linux" | "win32";
+        capabilities: readonly Capability[];
+    }): Promise<PairStartResponse>;
+    pairPoll(deviceCode: string): Promise<PairPollResponse>;
+    claim(input: {
+        runnerId: string;
+        capabilities: readonly Capability[];
+        max: number;
+    }): Promise<ClaimResponse>;
+    heartbeat(input: {
+        runnerId: string;
+        daemonVersion: string;
+        capabilities: readonly Capability[];
+        activeJobIds: readonly string[];
+        paused: boolean;
+    }): Promise<HeartbeatResponse>;
+    result(input: {
+        runnerId: string;
+        jobId: string;
+        outcome: JobOutcome;
+        model: string;
+        backendClass: "http" | "process";
+        durationMs: number;
+    }): Promise<ResultResponse>;
+    release(input: {
+        runnerId: string;
+        jobIds: readonly string[];
+        reason: "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
+    }): Promise<ReleaseResponse>;
+}
+
+/**
+ * Reduce a job's payload to the single string a backend receives.
+ *
+ * This is the narrowest point in the daemon: everything upstream deals in a
+ * job, everything downstream deals in text and an owner-chosen model. By
+ * construction there is nothing left for a payload to influence.
+ *
+ * **On `system`.** byollm_004 §2 forbids payload text on a command line, and
+ * the `claude` CLI's only system-prompt input is the argv flag
+ * `--system-prompt` — so a payload's `system` can never be passed that way.
+ * It is folded into the stdin text instead, under a plain delimiter. That
+ * costs a little role fidelity on process-class backends and is documented
+ * rather than papered over; HTTP-class backends could carry the role natively
+ * but use the same composition so a job produces identical text on either
+ * class, which is what makes results comparable across runners.
+ */
+declare function composePrompt(job: ClaimedJob): string;
+
+/**
+ * One paired server.
+ *
+ * A daemon may pair with several apps; each pairing is a separate identity
+ * with its own token and its own owner. Nothing is shared between them —
+ * `owner` from one server means nothing on another
+ * ({@link MUSTS.PAIR_ONE_USER}).
+ */
+declare const Pairing: z.ZodObject<{
+    origin: z.ZodString;
+    runnerId: z.ZodString;
+    token: z.ZodString;
+    owner: z.ZodString;
+    ownerLabel: z.ZodOptional<z.ZodString>;
+    pairedAt: z.ZodNumber;
+}, z.core.$strict>;
+type Pairing = z.infer<typeof Pairing>;
+/** The daemon's paired servers, on disk. */
+declare class Pairings {
+    #private;
+    constructor(path: string);
+    load(): Promise<void>;
+    list(): readonly Pairing[];
+    get(origin: string): Pairing | undefined;
+    /** Add or replace the pairing for an origin. Re-pairing supersedes. */
+    put(pairing: Pairing): Promise<void>;
+    /** Forget a pairing. Returns whether one was removed. */
+    remove(origin: string): Promise<boolean>;
+}
+
+interface ConnectOptions {
+    readonly client: ProtocolClient;
+    readonly daemonVersion: string;
+    readonly label: string;
+    readonly capabilities: readonly Capability[];
+    /** Called once, with what to show the user. */
+    readonly onCode: (info: {
+        userCode: string;
+        verificationUrl: string;
+        expiresAt: number;
+    }) => void;
+    /** Called each poll, so a CLI can show it is still waiting. */
+    readonly onPoll?: () => void;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly signal?: AbortSignal;
+}
+type ConnectResult = {
+    readonly ok: true;
+    readonly pairing: Pairing;
+} | {
+    readonly ok: false;
+    readonly reason: "denied" | "expired" | "aborted";
+    readonly message: string;
+};
+/**
+ * The device-code pairing flow, from the daemon's side.
+ *
+ * The daemon asks for a code, shows it, and polls. The user approves inside
+ * the app's own authenticated session, which is how the server learns who
+ * they are — the daemon never asserts an identity and never accepts a pasted
+ * long-lived secret ({@link MUSTS.PAIR_INTERACTIVE}).
+ *
+ * Nothing listens on the user's machine for this. A loopback redirect would
+ * be fewer keystrokes and would contradict the product's whole posture, as
+ * well as breaking on the headless boxes most likely to be running a model.
+ */
+declare function connect(options: ConnectOptions): Promise<ConnectResult>;
+/** The platform, narrowed to what the protocol accepts. */
+declare function currentPlatform(): "darwin" | "linux" | "win32";
+
+/**
+ * A prompt about to be executed.
+ *
+ * Written *before* the backend is called
+ * ({@link MUSTS.INGRESS_LOGGED_BEFORE_EXECUTION}), so a job that wedges or
+ * crashes the machine still leaves a record of what it was.
+ */
+declare const PromptEntry: z.ZodObject<{
+    type: z.ZodLiteral<"prompt">;
+    at: z.ZodNumber;
+    origin: z.ZodString;
+    jobId: z.ZodString;
+    kind: z.ZodString;
+    audience: z.ZodString;
+    owner: z.ZodString;
+    backendId: z.ZodString;
+    backendClass: z.ZodString;
+    model: z.ZodString;
+    promptHash: z.ZodString;
+    promptChars: z.ZodNumber;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type PromptEntry = z.infer<typeof PromptEntry>;
+/** How a job ended. A separate line, so the prompt line is never rewritten. */
+declare const OutcomeEntry: z.ZodObject<{
+    type: z.ZodLiteral<"outcome">;
+    at: z.ZodNumber;
+    jobId: z.ZodString;
+    outcome: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        canceled: "canceled";
+        refused: "refused";
+    }>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    outputChars: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type OutcomeEntry = z.infer<typeof OutcomeEntry>;
+declare const IngressEntry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"prompt">;
+    at: z.ZodNumber;
+    origin: z.ZodString;
+    jobId: z.ZodString;
+    kind: z.ZodString;
+    audience: z.ZodString;
+    owner: z.ZodString;
+    backendId: z.ZodString;
+    backendClass: z.ZodString;
+    model: z.ZodString;
+    promptHash: z.ZodString;
+    promptChars: z.ZodNumber;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"outcome">;
+    at: z.ZodNumber;
+    jobId: z.ZodString;
+    outcome: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        canceled: "canceled";
+        refused: "refused";
+    }>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    outputChars: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+type IngressEntry = z.infer<typeof IngressEntry>;
+interface IngressOptions {
+    readonly path: string;
+    /** Days to keep a community prompt in full before reducing it to its hash. */
+    readonly communityPromptDays: number;
+    /** Whether to record the owner's own prompts in full. */
+    readonly keepSelfPrompts: boolean;
+}
+/**
+ * The append-only record of every prompt that has run on this machine.
+ *
+ * byollm_002 calls the meter the product's soul. This is it: one JSONL file
+ * the owner can read, grep and delete, written before execution rather than
+ * after.
+ */
+declare class IngressLog {
+    #private;
+    constructor(options: IngressOptions);
+    /** Record a prompt. Await this before starting the backend call. */
+    recordPrompt(input: {
+        at: number;
+        origin: string;
+        jobId: string;
+        kind: string;
+        audience: Audience;
+        owner: string;
+        backendId: string;
+        backendClass: string;
+        model: string;
+        prompt: string;
+    }): Promise<void>;
+    /** Record how a job ended. */
+    recordOutcome(input: {
+        at: number;
+        jobId: string;
+        outcome: OutcomeEntry["outcome"];
+        durationMs?: number;
+        outputChars?: number;
+        detail?: string;
+    }): Promise<void>;
+    /** Read the log, oldest first. Malformed lines are skipped, not fatal. */
+    read(): Promise<IngressEntry[]>;
+    /**
+     * Apply retention: drop the text of community prompts older than the
+     * window, keeping the hash, the metadata and the character count.
+     *
+     * byollm_004 Rev 1: a volunteer must not indefinitely retain strangers'
+     * content. The hash stays, so the owner can still prove what ran.
+     *
+     * @returns how many entries were reduced.
+     */
+    applyRetention(now: number): Promise<number>;
+}
+/** SHA-256 of a prompt, hex. */
+declare function hashText(text: string): string;
+/**
+ * Replace terminal control sequences before printing untrusted text.
+ *
+ * Model output and job payloads both reach the owner's terminal through
+ * `byollm log` and `byollm status`. Text that can move the cursor or set
+ * colours can forge output — the ANSI/log-injection row of byollm_004 §5's
+ * corpus. Stored bytes stay verbatim; only the *display* is sanitised, so the
+ * log remains an honest record of what actually arrived.
+ *
+ * Tab and newline are kept: they are legitimate content, not control.
+ */
+declare function stripControlChars(text: string): string;
+
+/** What the daemon is currently doing, for `byollm status`. */
+interface RunnerStatus {
+    readonly origin: string;
+    readonly owner: string;
+    readonly runnerId: string;
+    readonly paused: boolean;
+    readonly revoked: boolean;
+    readonly activeJobs: number;
+    readonly capabilities: readonly Capability[];
+    /** Set when the last server contact failed — one of the four truths. */
+    readonly lastError?: string;
+    readonly completed: number;
+    readonly refused: number;
+}
+interface RunnerOptions {
+    readonly client: ProtocolClient;
+    readonly runnerId: string;
+    readonly owner: string;
+    readonly daemonVersion: string;
+    readonly loaded: LoadedConfig;
+    readonly allowlist: Allowlist;
+    readonly budgets: Budgets;
+    readonly ingress: IngressLog;
+    /** Heartbeat cadence before jitter. */
+    readonly heartbeatMs?: number;
+    readonly now?: () => number;
+    /** Notified on every state change, so the CLI can render progress. */
+    readonly onEvent?: (event: RunnerEvent) => void;
+    /** Injectable backend factory, so tests need no real model server. */
+    readonly backendFactory?: (route: ResolvedRoute) => Backend;
+}
+type RunnerEvent = {
+    readonly type: "heartbeat";
+    readonly capabilities: number;
+} | {
+    readonly type: "claimed";
+    readonly jobId: string;
+    readonly kind: string;
+} | {
+    readonly type: "refused";
+    readonly jobId: string;
+    readonly reason: string;
+} | {
+    readonly type: "finished";
+    readonly jobId: string;
+    readonly outcome: string;
+    readonly durationMs: number;
+} | {
+    readonly type: "revoked";
+} | {
+    readonly type: "error";
+    readonly message: string;
+};
+/**
+ * The daemon's loop: heartbeat, claim, execute, report.
+ *
+ * Everything that makes the daemon a *trust anchor* rather than a worker
+ * happens in {@link Runner.admit} and {@link Runner.runJob} — the local
+ * audience check, the budget check, and the ingress write that precedes
+ * execution. The loop itself is deliberately dull.
+ */
+declare class Runner {
+    #private;
+    constructor(options: RunnerOptions);
+    status(): RunnerStatus;
+    pause(): void;
+    resume(): void;
+    /**
+     * Build the capability matrix: owner config intersected with what is
+     * actually reachable and healthy right now
+     * ({@link MUSTS.CAPABILITY_IS_DETECTED}).
+     *
+     * A configured route whose backend is down simply does not appear. The
+     * daemon then receives no work for it, which is the correct outcome and one
+     * the owner can see in `byollm status`.
+     */
+    detectCapabilities(): Promise<Capability[]>;
+    /**
+     * Decide whether this machine will run a claimed job.
+     *
+     * The server already applied its own version of the audience rules, and
+     * that is not what this checks. This is the daemon enforcing against the
+     * server: the local `named` allowlist
+     * ({@link MUSTS.NAMED_LOCAL_ALLOWLIST}), the subscription self-lock, and
+     * the owner's community budgets. A job that fails here is released with
+     * reason `refused`, which the server remembers so it is never offered back.
+     */
+    admit(job: ClaimedJob): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Execute one admitted job.
+     *
+     * Order is load-bearing: the ingress write is awaited *before* the backend
+     * is touched ({@link MUSTS.INGRESS_LOGGED_BEFORE_EXECUTION}), so a job that
+     * hangs the machine still leaves a record of what it was.
+     */
+    runJob(job: ClaimedJob): Promise<JobOutcome>;
+    /** Abort a job's in-flight backend call ({@link MUSTS.CANCEL_HONORED}). */
+    cancelJob(jobId: string): void;
+    /** Abort everything — revocation, or shutdown. */
+    cancelAll(): void;
+    /**
+     * Run until stopped.
+     *
+     * Resumable and idempotent by job id: a daemon that dies mid-job loses
+     * nothing, because the server reclaims the lease and offers the job again.
+     */
+    run(signal: AbortSignal): Promise<void>;
+    /** One heartbeat-and-claim cycle. Exposed so tests can step deterministically. */
+    tick(): Promise<void>;
+    /** Release everything on shutdown, so nothing waits for a lease to lapse. */
+    shutdown(reason: "shutdown" | "pause"): Promise<void>;
+}
+
+/**
+ * Why a base URL was refused.
+ */
+type BaseUrlRefusal = "not-a-url" | "bad-scheme" | "credentials-in-url" | "cloud-metadata" | "link-local" | "wildcard-address";
+type BaseUrlCheck = {
+    readonly ok: true;
+    readonly url: URL;
+} | {
+    readonly ok: false;
+    readonly refusal: BaseUrlRefusal;
+    readonly detail: string;
+};
+/**
+ * Validate an owner-configured backend base URL
+ * ({@link MUSTS.HTTP_BASE_URL_SAFE}).
+ *
+ * **What this is and is not.** byollm_004 Rev 1 calls the HTTP-class threat
+ * surface "SSRF-shaped", and the shape matters: the base URL comes from the
+ * machine owner's config and from nowhere else — no payload field can set it,
+ * redirect it, or append to it. There is therefore no attacker-controlled
+ * input channel into this value at all. What remains is an owner who
+ * misconfigures their own machine, and the one case where that is genuinely
+ * dangerous is a cloud metadata endpoint.
+ *
+ * So this deliberately **allows loopback and private LAN addresses**. Blocking
+ * them, as a generic SSRF filter would, would refuse
+ * `http://127.0.0.1:11434` — which is Ollama's default and the entire point of
+ * the product. A filter that breaks the primary path in exchange for no real
+ * protection is theatre, and byollm_004's honesty rule forbids claiming it as
+ * a guarantee.
+ *
+ * Redirects are a separate matter and are refused outright by the HTTP
+ * backend, so a permitted base URL cannot become a forbidden one in flight.
+ */
+declare function checkBaseUrl(raw: string): BaseUrlCheck;
+/** Human-readable explanations for the trust UI and startup errors. */
+declare const BASE_URL_REFUSAL_MESSAGES: Readonly<Record<BaseUrlRefusal, string>>;
+
+/**
+ * `byollm` — what end users run.
+ *
+ * The CLI (`byollm connect`, `status`, `log`, `pause`, `allow`) is the
+ * product surface; this module is the same machinery as a library, so the
+ * conformance kit can drive a real daemon in-process instead of shelling out.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * This daemon's version, reported on pairing and on every heartbeat.
+ *
+ * Kept in step with `package.json` by a test rather than by a build-time
+ * define: an app's runner list shows this string, so a stale one is a lie
+ * told to every user, and a literal that a test pins cannot drift quietly.
+ */
+declare const DAEMON_VERSION = "0.1.0-alpha.0";
+
+export { AllowEntry, Allowlist, BASE_URL_REFUSAL_MESSAGES, type Backend, BackendConfig, type BackendErrorCode, type BackendHealth, type BackendInit, type BackendRequest, type BackendResult, type BaseUrlCheck, type BaseUrlRefusal, type BudgetDecision, type BudgetRefusal, Budgets, ClaudeCliBackend, type CliIo, ClientError, type ClientErrorKind, type ClientOptions, CommunityBudget, type ConfigProblem, type ConnectOptions, type ConnectResult, DAEMON_VERSION, DEFAULT_CONFIG, DaemonConfig, type DaemonPaths, type ExitCode, IMPLEMENTED_BACKEND_IDS, IngressEntry, IngressLog, type IngressOptions, IngressRetention, Limits, type LoadedConfig, OpenAiHttpBackend, OutcomeEntry, Pairing, Pairings, PromptEntry, ProtocolClient, type ResolvedRoute, RouteConfig, Runner, type RunnerEvent, type RunnerOptions, type RunnerStatus, checkBaseUrl, childEnv, claudeArgv, composePrompt, connect, createBackend, currentPlatform, daemonPaths, defaultRoot, hashText, loadConfig, main, normalizeOrigin, resolveConfig, runCli, stripControlChars };