@spredr/sdk 0.0.0-stage → 0.1.0

package/dist/context.d.ts

@@ -0,0 +1,108 @@
+import type { Client } from './http.js';
+import type { Answer, Fact, Json, SessionFile, Step, Task } from './types.js';
+export interface Delivery {
+    /** Whom ai addressed it to, inside what it signs: an agent refuses one addressed to another. Absent from an older ai. */
+    to?: {
+        agent: string;
+    };
+    task: {
+        id: string;
+        kind: string;
+        input: Json;
+        attempt: number;
+        by: Task['by'];
+        trial: boolean;
+        judges: string | null;
+        createdAt: string;
+        tenant?: string;
+        thread?: string | null;
+    };
+    /** The last answer only: what an ai from before the journal sends. */
+    resume: (Answer & {
+        pause: string;
+        action: string;
+        question?: string;
+        data?: Json | null;
+    }) | null;
+    /** Every answer the task's questions got, in the order asked (free ones too). */
+    answers?: (Answer & {
+        pause: string;
+        action: string;
+        auto?: boolean;
+        question?: string;
+        data?: Json | null;
+    })[];
+    /** What each finished step gave back, in order: `key` is the step as the handler named it. */
+    memo?: {
+        key: string;
+        has: boolean;
+        value: Json;
+    }[];
+    lessons: {
+        version: number;
+        items: string[];
+    };
+    /** Its session's files, without their bytes: what an ai from before sessions' files does not send. */
+    files?: SessionFile[];
+}
+export interface Context {
+    task: Delivery['task'];
+    /** Whom it works for in this task (a user, an account, a team, a business): its memory, freedom, lessons and caps are that tenant's.
+     *  "" when the asker named no one. */
+    tenant: string;
+    /** The conversation it belongs to (a customer, a ticket), when the asker named one. */
+    thread: string | null;
+    /** The live lessons this task carries: put them in the prompt. */
+    lessons: string[];
+    /** A trial replays an old task with new lessons: do nothing real. */
+    trial: boolean;
+    /** Asks before an action and returns the answer; the first time the task stops here and comes back with it. Asked
+     *  again when the task runs again, it gives back the same answer without asking. */
+    ask(action: string, question: string, extra?: {
+        options?: string[];
+        data?: Json;
+    }): Promise<Answer>;
+    progress(data: Json): Promise<void>;
+    /** The next piece of its answer, for whoever watches the task live (the caller's stream()): sent in order, a few at a
+     *  time. A view, never the outcome: what the task returns is its result, and the pieces go once it is done. */
+    stream(text: string): void;
+    /** Sends what stream() still holds: done for you before the task's result. */
+    flush(): Promise<void>;
+    /** Reports one step it took (a model call, a tool): its trace and its costs come from these. */
+    step(step: Step): Promise<void>;
+    /** Runs `work`, times it, and reports it as a step (failed when it throws). Tokens and cost from what it returns, if
+     *  `usage` reads them. Done once per task: when the task runs again (after a question, a retry) it gives back what
+     *  `work` gave the first time, as JSON, without running it. Put side effects here so they never happen twice. */
+    track<T>(kind: Step['kind'], name: string, work: () => Promise<T>, usage?: (value: T) => Pick<Step, 'model' | 'tokensIn' | 'tokensOut' | 'costUsd' | 'detail'>): Promise<T>;
+    /** A model call, timed and reported with its model and tokens read from the answer (Claude, OpenAI, the AI SDK):
+     *  `await ctx.model(() => claude.messages.create({ … }))`. `name` defaults to the model. Done once per task, as track. */
+    model<T>(work: () => Promise<T>, name?: string): Promise<T>;
+    /** A task for later (a reminder, a follow-up), for the same tenant and thread. Done once per task, as track. */
+    later(kind: string, input: Json, at: Date | string, key?: string): Promise<void>;
+    /** Its session's files (the thread's, for its tenant): whatever its caller left for it to read, without their bytes. */
+    files: SessionFile[];
+    /** One of them, by id or by name, as its bytes and type: read inside this task, the way its code wants. */
+    file(idOrName: string): Promise<{
+        data: Uint8Array;
+        type: string;
+        name: string;
+    }>;
+    /** This tenant's memory (this task's): the agent's room is shared by all its tenants, each fact is one tenant's. */
+    memory: {
+        /** Done once per task, as track. The fact kept, or null when it was not (its room is full, or its tenant's share):
+         *  the task goes on either way, and why is printed in its logs. */
+        remember(scope: string, text: string, extra?: {
+            key?: string;
+            data?: Json;
+        }): Promise<Fact | null>;
+        recall(options: {
+            scope?: string;
+            q?: string;
+            limit?: number;
+        }): Promise<Fact[]>;
+        forget(id: string): Promise<void>;
+    };
+}
+/** Thrown inside ask() to stop a task that waits for an answer; the agent catches it. */
+export declare const PAUSED: unique symbol;
+export declare function contextFor(client: Client, delivery: Delivery): Context;

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+import type { Task } from './types.js';
+export declare class SpredrError extends Error {
+    /** The HTTP status ai answered with; 0 when no answer came. */
+    readonly status: number;
+    /** ai's trace id for this request, to quote when you write to spredr. */
+    readonly trace: string;
+    constructor(status: number, message: string, trace?: string);
+}
+/** 400: what was sent is not right; the message says what. */
+export declare class BadRequestError extends SpredrError {
+}
+/** 401: no token, a wrong one, or a signature ai does not believe. */
+export declare class AuthenticationError extends SpredrError {
+}
+/** 403: allowed to ask, not this (a plan's limit, another owner's agent). */
+export declare class PermissionDeniedError extends SpredrError {
+}
+/** 404: no such agent, task or question. */
+export declare class NotFoundError extends SpredrError {
+}
+/** 409: it changed meanwhile (a name taken, a question already answered, an attempt that is over). */
+export declare class ConflictError extends SpredrError {
+}
+/** 429: too many, or a cap reached (the month's tasks, the day's spend); `retryAfter` says when to come back. */
+export declare class RateLimitError extends SpredrError {
+    /** Seconds ai asked to wait, when it said. */
+    readonly retryAfter: number | null;
+    constructor(status: number, message: string, trace?: string, retryAfter?: number | null);
+}
+/** 5xx: ai failed; retried already, as far as it is safe. */
+export declare class InternalServerError extends SpredrError {
+}
+/** No answer: the network, a DNS name, ai unreachable. */
+export declare class ConnectionError extends SpredrError {
+}
+/** No answer in time (timeoutMs). */
+export declare class TimeoutError extends ConnectionError {
+}
+/** A task that ended without a result: failed, canceled, or paused for a question someone must answer. */
+export declare class TaskError extends Error {
+    readonly task: Task<unknown>;
+    constructor(task: Task<unknown>);
+}
+/** The error for ai's answer: its status picks the class. */
+export declare function errorFor(status: number, message: string, trace: string, retryAfter: number | null): SpredrError;

package/dist/http.d.ts

@@ -0,0 +1,48 @@
+import type { KeyObject } from 'node:crypto';
+export { SpredrError } from './errors.js';
+export type Auth = {
+    token: string;
+} | {
+    from: string;
+    key: KeyObject;
+};
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** How every side talks to ai. */
+export interface ClientOptions {
+    /** A fetch of your own (a proxy, a test). */
+    fetch?: typeof fetch;
+    /** How long one request may take, in ms: 75 s by default, since a wait for a task is up to 60 s. */
+    timeoutMs?: number;
+    /** How many more times a request is tried when that is safe: 2 by default; 0 never. */
+    maxRetries?: number;
+    /** The first wait before trying again, in ms, doubling each time (up to 8 s): 500 by default. */
+    retryDelayMs?: number;
+}
+export interface CallOptions {
+    /** Whether sending it twice does the same as once. By default GET, PUT and DELETE do; a POST that carries its own key
+     *  says true, a PUT that adds something each time says false. */
+    idempotent?: boolean;
+}
+export interface Client {
+    call<T = unknown>(method: Method, path: string, body?: unknown, options?: CallOptions): Promise<T>;
+    /** The answer as text (an export, one JSON per line). */
+    text(method: 'GET', path: string): Promise<string>;
+    /** Bytes sent as they are (a session's file): PUT, signed over those bytes, its own headers beside them. */
+    upload<T = unknown>(path: string, data: Uint8Array, headers: Record<string, string>): Promise<T>;
+    /** Bytes back as they are, with their type (a session's file). */
+    download(path: string): Promise<{
+        data: Uint8Array;
+        type: string;
+        headers: Headers;
+    }>;
+    /** Server-sent events from a GET that stays open, one after another, after the event `lastId` (Last-Event-ID). Ends
+     *  when the server closes it. */
+    events(path: string, lastId: number): AsyncGenerator<{
+        id: number;
+        event: string;
+        data: string;
+    }>;
+}
+export declare function client(base: string, auth: Auth, options?: ClientOptions): Client;
+/** A query string from the values that are set, encoded as it will be signed. */
+export declare function query(values: Record<string, string | number | undefined>): string;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Agent, type AgentAnswer, type AgentOptions, type Context, type Delivery, type Handler, type KindsOf, type Manifest } from './agent.js';
+export { Caller, type Callback, type CallerOptions } from './caller.js';
+export { AuthenticationError, BadRequestError, ConflictError, ConnectionError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, SpredrError, TaskError, TimeoutError, } from './errors.js';
+export type { CallOptions, ClientOptions } from './http.js';
+export { DEFAULT_AI_URL, OwnedAgent, Spredr, type SpredrOptions } from './owner.js';
+export type { InferInput, InferOutput, StandardSchemaV1 } from './schema.js';
+export { aiVerifier, newKeys, type Incoming } from './sign.js';
+export { currentTask } from './tag.js';
+export { Tasks, Tenant } from './tasks.js';
+export type * from './types.js';