@spredr/sdk 0.0.0-stage → 0.1.0

package/dist/owner.d.ts

@@ -0,0 +1,162 @@
+import { type Client, type ClientOptions } from './http.js';
+import { Tasks, type Tenant } from './tasks.js';
+import type { AgentInfo, Fact, Freedom, Json, Lesson, LessonVersion, Limits, MemoryUse, Pause, Redeploy, SessionFile, Summary, Task, TenantLimits, TenantUsage, Thread, Traces } from './types.js';
+export interface SpredrOptions extends ClientOptions {
+    /** A spredr token (spr_…), from Account › Tokens or `spredr login`; SPREDR_TOKEN when absent. */
+    token?: string;
+    /** Where ai is; SPREDR_AI_URL, or spredr's own. */
+    ai?: string;
+}
+export declare const DEFAULT_AI_URL = "https://api.spredr.cloud/ai";
+export declare class Spredr {
+    #private;
+    constructor(options?: SpredrOptions);
+    agents(): Promise<AgentInfo[]>;
+    /** Turns a spredr service into an agent: ai writes its keys into the service and deploys it again. A deploy spredr
+     *  refuses (redeploy.status «failed») leaves the agent made: deploy the service again once that is fixed. */
+    register(name: string, service: string, options?: {
+        redeploy?: boolean;
+    }): Promise<AgentInfo & {
+        redeploy: Redeploy;
+    }>;
+    /** Leaves a token for ai to wake and put to sleep your agents while nobody is looking. */
+    keepToken(token: string): Promise<void>;
+    /** What waits for a person across every agent: open questions, tasks that failed in the last `hours`, and agents whose
+     *  memory is 80 % full or more. */
+    inbox(hours?: number): Promise<{
+        questions: (Pause & {
+            agent: string;
+        })[];
+        errors: Task[];
+        memory: {
+            agent: string;
+            usedBytes: number;
+            maxBytes: number;
+            full: boolean;
+        }[];
+    }>;
+    agent(name: string): OwnedAgent;
+}
+export declare class OwnedAgent {
+    #private;
+    readonly tasks: Tasks;
+    constructor(client: Client, name: string);
+    /** The agent working for one tenant: its tasks, usage, caps, lessons and freedom, and forgetting it. */
+    for(tenant: string): Tenant;
+    /** The tenants it worked for in the last `days`, the latest active first, each with what it used. */
+    tenants(options?: {
+        days?: number;
+        limit?: number;
+    }): Promise<TenantUsage[]>;
+    /** The caps of every tenant without caps of its own. */
+    setTenantLimits(limits: TenantLimits): Promise<Required<TenantLimits>>;
+    info(): Promise<AgentInfo>;
+    /** Its last hours at a glance: tasks, failures, times, tokens, cost, tools, and how free it is. */
+    summary(hours?: number): Promise<Summary>;
+    /** Its conversations: tasks that share a thread. Read one with tasks.list({ thread }). */
+    threads(limit?: number): Promise<Thread[]>;
+    /** Every task since a moment with its steps (the export, read line by line). */
+    export(since?: Date | string): Promise<(Task & {
+        steps: Json[];
+    })[]>;
+    setLimits(limits: Limits): Promise<AgentInfo>;
+    /** Sends each finished task to your OpenTelemetry endpoint (OTLP/HTTP: Langfuse, Datadog, Honeycomb, your collector)
+     *  as a trace. headers carry its key (sealed by ai, never shown back); withContent sends the input and result too. */
+    setTraces(traces: {
+        endpoint: string;
+        headers?: Record<string, string>;
+        withContent?: boolean;
+    }): Promise<Traces>;
+    /** Where its traces go (the header names only), or null. */
+    traces(): Promise<Traces | null>;
+    stopTraces(): Promise<void>;
+    remove(): Promise<void>;
+    /** A new key pair: ai believes the new key at once, whatever the redeploy does (redeploy.status says). */
+    rotateKey(options?: {
+        redeploy?: boolean;
+    }): Promise<AgentInfo & {
+        redeploy: Redeploy;
+    }>;
+    /** A backend that may give this agent tasks. With `service`, ai writes its key there; with `publicKey`, the private
+     *  one never leaves you; with neither, the private key comes back this once. With `everything` and a `callbackUrl`, it
+     *  is an events webhook: it hears about every task of the agent (task.created, done, failed, paused, canceled). */
+    addCaller(name: string, options?: {
+        service?: string;
+        publicKey?: string;
+        callbackUrl?: string;
+        everything?: boolean;
+        redeploy?: boolean;
+    }): Promise<{
+        caller: {
+            id: string;
+            name: string;
+            publicKey: string;
+            callbackUrl: string;
+        };
+        privateKey?: string;
+    }>;
+    callers(): Promise<{
+        id: string;
+        name: string;
+        service: string;
+        callbackUrl: string;
+    }[]>;
+    removeCaller(id: string): Promise<void>;
+    schedule(name: string, kind: string, cron: string, options?: {
+        tz?: string;
+        input?: Json;
+    }): Promise<{
+        id: string;
+        nextAt: string;
+    }>;
+    /** A secret address that starts a task with whatever is POSTed to it; the address comes back this once. */
+    hook(name: string, kind: string): Promise<{
+        hook: {
+            id: string;
+            name: string;
+        };
+        url: string;
+    }>;
+    /** Every file its sessions keep, newest first (each with its tenant, conversation and place in the bucket), and how full
+     *  its room for them is. */
+    storedFiles(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        files: SessionFile[];
+        usedBytes: number;
+        maxBytes: number;
+        filesBytes: number;
+        memoryBytes: number;
+    }>;
+    /** One of them, as its bytes and type: any session's. */
+    downloadFile(id: string): Promise<{
+        data: Uint8Array;
+        type: string;
+    }>;
+    /** Removes one, any session's: its card and its bytes. */
+    deleteFile(id: string): Promise<void>;
+    /** How full its memory is (warn from 80 %, full from 95 %), and whether unchanged facts are forgotten. */
+    memoryUse(): Promise<MemoryUse>;
+    /** What it remembers; `tenant` narrows it to one tenant's. */
+    memory(options?: {
+        scope?: string;
+        q?: string;
+        limit?: number;
+        tenant?: string;
+    }): Promise<Fact[]>;
+    editFact(id: string, text: string, data?: Json): Promise<Fact>;
+    /** Erases everything the agent keeps under a scope (a customer who asks to be forgotten): the agent's own, or one
+     *  tenant's. */
+    forget(scope: string, tenant?: string): Promise<number>;
+    /** How free it is with each action in its own work (no tenant); a tenant's is `for(tenant).freedom()`. */
+    freedom(): Promise<Freedom[]>;
+    setFreedom(action: string, level: 'ask' | 'auto'): Promise<Freedom>;
+    lessons(): Promise<Lesson[]>;
+    writeLesson(text: string, why?: string): Promise<Lesson>;
+    decide(lessonId: string, decision: 'accept' | 'refuse' | 'retire'): Promise<Lesson>;
+    versions(): Promise<LessonVersion[]>;
+    /** Releases the accepted lessons as a new version, tried first on past tasks. */
+    release(): Promise<LessonVersion>;
+    version(version: number, action: 'publish' | 'rollback' | 'discard'): Promise<LessonVersion>;
+}

package/dist/schema.d.ts

@@ -0,0 +1,28 @@
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardProps<Input, Output>;
+}
+export interface StandardProps<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    readonly types?: {
+        readonly input: Input;
+        readonly output: Output;
+    } | undefined;
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+/** The value the schema makes of `input`, or an error that says every place it does not match. */
+export declare function validated<Output>(schema: StandardSchemaV1<unknown, Output>, input: unknown): Promise<Output>;

package/dist/sign.d.ts

@@ -0,0 +1,26 @@
+import { type KeyObject } from 'node:crypto';
+export declare const HEADERS: {
+    readonly from: "x-spredr-from";
+    readonly time: "x-spredr-time";
+    readonly nonce: "x-spredr-nonce";
+    readonly signature: "x-spredr-signature";
+};
+/** Who ai is when it signs a delivery or a callback. */
+export declare const AI_SIGNER = "ai";
+export declare const privateKeyOf: (base64: string) => KeyObject;
+export declare const publicKeyOf: (base64: string) => KeyObject;
+/** A new key pair for a backend that brings its own public key: keep `privateKey` secret, give spredr `publicKey`. */
+export declare function newKeys(): {
+    privateKey: string;
+    publicKey: string;
+};
+export declare function signedHeaders(from: string, key: KeyObject, method: string, path: string, body: string | Uint8Array): Record<string, string>;
+export interface Incoming {
+    method: string;
+    /** The path with its query, exactly as it arrived (Node's request.url). */
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: string | Uint8Array;
+}
+/** Checks that a request was signed by ai, recently, and never seen before. One instance per process. */
+export declare function aiVerifier(aiPublicKey: string): (request: Incoming) => boolean;

package/dist/tag.d.ts

@@ -0,0 +1,7 @@
+/** The id of the task the code is working on now, or null outside one: for a logger's own fields, e.g.
+ *  `pino({ mixin: () => ({ task: currentTask() }) })`. */
+export declare function currentTask(): string | null;
+/** Runs `work` as the given task: currentTask() says its id all the way down. */
+export declare function asTask<T>(taskId: string, work: () => T): T;
+/** From now on, console's lines printed while a task works start with its id. Done once per process. */
+export declare function tagConsole(): void;

package/dist/tasks.d.ts

@@ -0,0 +1,98 @@
+import { type Client } from './http.js';
+import type { Answer, AnyKinds, AskOptions, Feedback, Freedom, Json, Kinds, Lesson, Pause, SessionFile, Step, StreamEvent, Task, TaskEvent, TenantInfo, TenantLimits } from './types.js';
+export declare class Tasks<K extends Kinds = AnyKinds> {
+    #private;
+    constructor(client: Client, agent: string, tenant?: string);
+    /** The same agent, working for one tenant: `caller.for('user_42').result('reply', …)`. One agent serves any number
+     *  of tenants at once, each with its own memory, questions, freedom, lessons and caps. */
+    for(tenant: string): Tenant<K>;
+    /** Asks the agent for a task. With `wait`, answers once it is done (or when the wait runs out). With a `key`, asking
+     *  again is the same task, so it is safe to retry. */
+    ask<Name extends keyof K & string>(kind: Name, input: K[Name]['input'], options?: AskOptions): Promise<Task<K[Name]['output']>>;
+    /** Asks and waits until the task is done, failed, canceled or paused, however long (in rounds of up to a minute). */
+    run<Name extends keyof K & string>(kind: Name, input: K[Name]['input'], options?: Omit<AskOptions, 'wait'> & {
+        timeoutMs?: number;
+    }): Promise<Task<K[Name]['output']>>;
+    /** Asks, waits, and gives back the result itself; a task that fails, is canceled or waits for an answer throws a
+     *  TaskError carrying the task. */
+    result<Name extends keyof K & string>(kind: Name, input: K[Name]['input'], options?: Omit<AskOptions, 'wait'> & {
+        timeoutMs?: number;
+    }): Promise<K[Name]['output']>;
+    get<Result = Json>(id: string, wait?: number): Promise<Task<Result>>;
+    /** Waits for a task to leave the line: done, failed, canceled or paused. */
+    settle<Result = Json>(id: string, timeoutMs?: number): Promise<Task<Result>>;
+    list(options?: {
+        status?: Task['status'];
+        limit?: number;
+        before?: string;
+        thread?: string;
+        tenant?: string;
+    }): Promise<Task[]>;
+    /** What happened to a task after `after` (its events' seq); with `wait` seconds, waits for the first new one. */
+    events(id: string, after?: number, wait?: number): Promise<TaskEvent[]>;
+    /** What the agent did inside a task, step by step: its trace. */
+    steps(id: string): Promise<(Step & {
+        seq: number;
+        at: string;
+    })[]>;
+    cancel(id: string): Promise<Task>;
+    /** The questions waiting for an answer (a tenant's alone, in a tenant session). */
+    pauses(): Promise<Pause[]>;
+    answer(pauseId: string, answer: Answer): Promise<Pause>;
+    /** How a finished task went: what the agent learns from. A bad one also takes back what it did alone. */
+    feedback(id: string, verdict: 'good' | 'bad', details?: {
+        correction?: Json;
+        note?: string;
+    }): Promise<Feedback>;
+    /** A task as it happens: each piece of its live answer (the agent's ctx.stream), each of its other events, and last the
+     *  task itself once it is done, paused or failed. A stream that closes before the end is opened again after what
+     *  was seen, so nothing comes twice. */
+    stream(id: string): AsyncGenerator<StreamEvent>;
+    /** Asks for a task and gives its live answer as it is written: the pieces, then the task. */
+    live<Name extends keyof K & string>(kind: Name, input: K[Name]['input'], options?: AskOptions): AsyncGenerator<StreamEvent>;
+    /** Leaves a file in a session (a thread) for the agent's code to read: a price list, a catalogue, a document. Every
+     *  task of that thread lists it (ctx.files) and the agent downloads it (ctx.file) while it works on one. The same
+     *  name again replaces it. spredr keeps the bytes and never opens them; how the agent reads them is its code's. */
+    attach(thread: string, name: string, data: Uint8Array | string, options?: {
+        type?: string;
+        tenant?: string;
+    }): Promise<SessionFile>;
+    /** A session's files, without their bytes, newest first. */
+    files(thread: string, options?: {
+        tenant?: string;
+    }): Promise<SessionFile[]>;
+    /** Takes a file out of a session. */
+    detach(thread: string, name: string, options?: {
+        tenant?: string;
+    }): Promise<void>;
+    /** The client and agent a tenant session works with. */
+    protected get base(): {
+        client: Client;
+        agent: string;
+    };
+}
+/** One tenant of an agent: its tasks, and what is its own. Made with `caller.for(tenant)` or `spredr.agent(name).for(tenant)`. */
+export declare class Tenant<K extends Kinds = AnyKinds> extends Tasks<K> {
+    #private;
+    readonly name: string;
+    constructor(client: Client, agent: string, tenant: string);
+    /** What it used today and this month, its caps, the facts it holds and its open questions. */
+    usage(): Promise<TenantInfo>;
+    /** Caps this tenant on top of the agent's own; null lifts one. */
+    setLimits(limits: TenantLimits): Promise<Required<TenantLimits>>;
+    /** Forgets this tenant whole: its tasks, memory, questions, freedom, lessons and caps. The others stay. */
+    forget(): Promise<{
+        tasks: number;
+        facts: number;
+    }>;
+    /** How free the agent is with each action for this tenant. */
+    freedom(): Promise<Freedom[]>;
+    /** Lets an action run alone for this tenant (auto), or ask every time (ask): never for another tenant. */
+    setFreedom(action: string, level: 'ask' | 'auto'): Promise<Freedom>;
+    /** This tenant's lessons: its own rules, in every one of its tasks from the moment they are written. */
+    lessons(): Promise<Lesson[]>;
+    /** Teaches the agent a rule for this tenant alone («we never book on Sundays»). */
+    teach(text: string, why?: string): Promise<Lesson>;
+    /** Accepts or refuses a lesson the agent proposed for this tenant, or retires one. */
+    decide(lessonId: string, decision: 'accept' | 'refuse' | 'retire'): Promise<Lesson>;
+}

package/dist/types.d.ts

@@ -0,0 +1,293 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type TaskStatus = 'queued' | 'running' | 'paused' | 'done' | 'failed' | 'canceled';
+/** One kind of task: what goes in, what comes out. */
+export interface Kind {
+    input: unknown;
+    output: unknown;
+}
+/** An agent's kinds by name. Name none and any kind goes: JSON in, and a result as free as fetch's json(); take them
+ *  from the agent (KindsOf) and TypeScript checks each name, its input and its result. */
+export type Kinds = {
+    [name: string]: Kind;
+};
+export type AnyKinds = {
+    [name: string]: {
+        input: Json;
+        output: any;
+    };
+};
+export interface Task<Result = Json> {
+    id: string;
+    agent: string;
+    kind: string;
+    status: TaskStatus;
+    input: Json;
+    result: Result | null;
+    error: string;
+    attempt: number;
+    by: 'owner' | 'caller' | 'schedule' | 'hook' | 'agent' | 'trial' | 'judge';
+    key: string | null;
+    thread: string | null;
+    /** Whom the agent worked for in it ("" is no one in particular). */
+    tenant: string;
+    trial: boolean;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface TaskEvent {
+    seq: number;
+    type: string;
+    at: string;
+    data: Json;
+}
+export interface Pause {
+    id: string;
+    task: string;
+    /** Its task's tenant: whose question it is. */
+    tenant: string;
+    action: string;
+    question: string;
+    options: string[] | null;
+    data: Json;
+    status: 'open' | 'answered' | 'canceled';
+    answer: Answer | null;
+    answeredBy: string;
+    auto: boolean;
+    createdAt: string;
+    answeredAt: string | null;
+}
+export interface Answer {
+    yes: boolean;
+    /** What to do instead, when the person changed it. */
+    value?: Json;
+    note?: string;
+}
+export interface Fact {
+    id: string;
+    tenant: string;
+    scope: string;
+    key: string | null;
+    text: string;
+    data: Json;
+    updatedAt: string;
+}
+/** The service's redeploy after its keys changed: asked for, not asked for, or refused by spredr (and why). The agent
+ *  is made, or its new key taken, either way. */
+export type Redeploy = {
+    status: 'started' | 'skipped';
+} | {
+    status: 'failed';
+    error: string;
+};
+export interface AgentInfo {
+    id: string;
+    name: string;
+    service: string;
+    url: string;
+    state: 'new' | 'awake' | 'waking' | 'asleep';
+    description: string;
+    tasks: {
+        kind: string;
+        description: string;
+    }[];
+    actions: {
+        name: string;
+        neverAuto: boolean;
+    }[];
+    /** Quiet minutes before it sleeps, null never: the owner's choice when they made one, else what it declared. */
+    sleepAfterMinutes: number | null;
+    /** Whether that is the owner's choice (the panel's «Dormir») rather than its own. */
+    sleepChosen?: boolean;
+    lessonsVersion: number;
+    tools?: {
+        name: string;
+        description: string;
+        asks: boolean;
+    }[];
+    limits?: Limits;
+}
+export interface Freedom {
+    action: string;
+    tenant: string;
+    level: 'ask' | 'auto';
+    earned: boolean;
+    neverAuto: boolean;
+    streak: number;
+    approved: number;
+    edited: number;
+    rejected: number;
+    undone: number;
+}
+export interface Lesson {
+    id: string;
+    tenant: string;
+    text: string;
+    why: string;
+    sources: string[];
+    by: string;
+    status: 'proposed' | 'accepted' | 'refused' | 'retired';
+}
+export interface LessonVersion {
+    version: number;
+    lessons: string[];
+    status: 'trial' | 'live' | 'superseded' | 'failed' | 'discarded';
+    trial: {
+        total: number;
+        done: number;
+        passed: number;
+    };
+}
+export interface Feedback {
+    seq: number;
+    task: string;
+    verdict: 'good' | 'bad';
+    correction: Json;
+    note: string;
+    by: string;
+    at: string;
+}
+export interface AskOptions {
+    /** Your own key for this task: asking twice with the same key is the same task. */
+    key?: string;
+    /** Seconds to wait for the outcome (up to 60). */
+    wait?: number;
+    /** When to start (a Date or ISO time); absent: now. */
+    at?: Date | string;
+    /** The conversation it belongs to (a customer, a ticket): tasks with the same thread read as one. */
+    thread?: string;
+    /** Whom the agent works for in it (a user, an account, a team, a business): its memory, freedom, lessons and caps are that tenant's.
+     *  A tenant session (`caller.for(tenant)`) sets it for you. */
+    tenant?: string;
+}
+/** One step inside a task: a model call, a tool, a memory read. Its trace and its costs come from these. */
+export interface Step {
+    kind: 'model' | 'tool' | 'memory' | 'other';
+    name: string;
+    ms: number;
+    at?: number;
+    detail?: string;
+    model?: string;
+    tokensIn?: number;
+    tokensOut?: number;
+    costUsd?: number;
+    ok?: boolean;
+}
+export interface Summary {
+    hours: number;
+    tasks: number;
+    done: number;
+    failed: number;
+    failRate: number;
+    p50Ms: number | null;
+    p95Ms: number | null;
+    tokens: number;
+    costUsd: number;
+    perHour: number[];
+    failedPerHour: number[];
+    tools: {
+        name: string;
+        uses: number;
+    }[];
+    freedom: {
+        alone: number;
+        asked: number;
+        undone: number;
+    };
+}
+export interface Thread {
+    thread: string;
+    tasks: number;
+    lastAt: string;
+    lastTask: string;
+}
+export interface Limits {
+    /** Actions it may take alone in a day; past it, its free actions ask again. null: no limit. */
+    autoPerDay?: number | null;
+    /** What its model calls may cost in a day (from the steps it reports); past it, new tasks are refused until tomorrow. null: no limit. */
+    spendPerDayUsd?: number | null;
+    /** Quiet minutes before it sleeps, over what it declares: 0 never, 5 to 1440; null leaves it to the agent. */
+    sleepAfterMinutes?: number | null;
+    /** Days its finished tasks are kept: 7, 30, 60, 90, 365 or 1825, never past what the plan keeps; null: the plan's. */
+    keepDays?: 7 | 30 | 60 | 90 | 365 | 1825 | null;
+    /** Days a fact may go unchanged before it is forgotten: 30, 90, 180 or 365; null: never by itself. */
+    forgetAfterDays?: 30 | 90 | 180 | 365 | null;
+}
+/** How full an agent's memory is: what its facts hold of what its plan gives it, in bytes. warn from 80 %, full from
+ *  95 % (the next fact may not fit: not kept, the task goes on). */
+/** What a task's stream gives, in order: pieces of its live answer, its other events (steps, progress, a question), and
+ *  last the task as it finished, paused or failed. */
+export type StreamEvent = {
+    type: 'delta';
+    text: string;
+    seq: number;
+} | {
+    type: 'event';
+    event: TaskEvent;
+} | {
+    type: 'end';
+    task: Task;
+};
+/** A file in an agent's session (a thread, for one tenant): what a caller left for the agent's code to read. */
+export interface SessionFile {
+    id: string;
+    name: string;
+    type: string;
+    bytes: number;
+    thread?: string;
+    tenant?: string;
+    /** Where its bytes are in spredr's files' bucket: owners/<owner>/agents/<agent>/sessions/<tenant>/<thread>/<id>. */
+    path?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** An agent's space: its memory and its sessions' files share it (its plan's, plus packs bought in spredr). */
+export interface MemoryUse {
+    /** Memory and files together. */
+    usedBytes: number;
+    maxBytes: number;
+    memoryBytes: number;
+    filesBytes: number;
+    share: number;
+    warn: boolean;
+    full: boolean;
+    forgetAfterDays: number | null;
+}
+/** Where an agent's traces go: an OTLP/HTTP endpoint and the names of its headers (their values never come back). */
+export interface Traces {
+    endpoint: string;
+    headers: string[];
+    withContent: boolean;
+}
+/** What one tenant may use, on top of the agent's own caps; null is no cap. */
+export interface TenantLimits {
+    /** Actions it may take alone a day for this tenant; past it, they ask again until tomorrow. */
+    autoPerDay?: number | null;
+    /** Model spend a day for this tenant; past it, its new tasks are refused until tomorrow (the others go on). */
+    spendPerDayUsd?: number | null;
+    /** Facts it may hold of the agent's memory, which all its tenants share. */
+    facts?: number | null;
+}
+/** What one tenant used in a while: its tasks and what their model calls cost. */
+export interface TenantUsage {
+    tenant: string;
+    tasks: number;
+    done: number;
+    failed: number;
+    costUsd: number;
+    tokensIn: number;
+    tokensOut: number;
+    lastAt: string | null;
+}
+export interface TenantInfo {
+    tenant: string;
+    /** Its caps as they apply: its own, or every tenant's. */
+    caps: Required<TenantLimits>;
+    ownCaps: boolean;
+    today: TenantUsage;
+    month: TenantUsage;
+    facts: number;
+    openQuestions: number;
+}

package/dist/usage.d.ts

@@ -0,0 +1,3 @@
+import type { Step } from './types.js';
+/** The model and its tokens, as far as the answer tells them. */
+export declare function usageOf(answer: unknown): Pick<Step, 'model' | 'tokensIn' | 'tokensOut'>;

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@spredr/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Talk to agents on spredr: run an agent, give it tasks from your backend, and manage it with your token. No dependencies.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Candhrly, LLC (https://spredr.cloud)",
+  "keywords": [
+    "spredr",
+    "agents",
+    "ai-agents",
+    "tasks",
+    "sdk",
+    "ed25519"
+  ],
+  "homepage": "https://spredr.cloud",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "TRADEMARKS.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.ts",
+    "check": "tsc --noEmit -p . && node scripts/check-alone.ts",
+    "test": "node --test 'test/*.test.ts'",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=90 'test/*.test.ts'",
+    "package": "npm run build && publint --strict && node scripts/check-package.ts",
+    "prepublishOnly": "node scripts/check-readme.ts && npm run check && npm run coverage && npm run package"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "esbuild": "0.28.2",
+    "publint": "^0.3.14",
+    "typescript": "5.9.3"
+  }
+}