@agents24/client 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,367 @@
+import type { RuntimeEvent, ThreadSummaryEvent } from "./generated/protocol.js";
+export type MaybePromise<T> = T | Promise<T>;
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+export interface HeadersLike {
+    get(name: string): string | null;
+}
+export interface ReadableBodyReaderLike {
+    read(): Promise<{
+        done: boolean;
+        value?: Uint8Array;
+    }>;
+    cancel(reason?: unknown): Promise<void>;
+    releaseLock?(): void;
+}
+export interface ReadableBodyLike {
+    getReader(): ReadableBodyReaderLike;
+}
+export interface FetchResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: HeadersLike;
+    readonly body: ReadableBodyLike | null;
+    readonly redirected?: boolean;
+    readonly url?: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface FetchRequestLike {
+    method?: string;
+    headers?: Readonly<Record<string, string>>;
+    body?: unknown;
+    signal?: AbortSignalLike | undefined;
+    redirect?: "error";
+    cache?: "no-store";
+    credentials?: "omit";
+}
+export type FetchLike = (url: string, init?: FetchRequestLike) => Promise<FetchResponseLike>;
+export interface TextDecoderLike {
+    decode(input?: Uint8Array, options?: {
+        stream?: boolean;
+    }): string;
+}
+export interface TextEncoderLike {
+    encode(input?: string): Uint8Array;
+}
+export interface Clock {
+    now(): number;
+}
+export interface IdProvider {
+    createId(): string;
+}
+export interface BlobLike {
+    readonly size: number;
+    readonly type?: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export type BinaryUploadData = Uint8Array | ArrayBuffer | BlobLike;
+export interface PortableUpload {
+    data: BinaryUploadData;
+    name: string;
+    mediaType: string;
+}
+export interface MultipartPart {
+    field: string;
+    value: string | PortableUpload;
+}
+export interface EncodedMultipart {
+    body: Uint8Array | unknown;
+    contentType: string;
+}
+export interface MultipartEncoder {
+    encode(parts: readonly MultipartPart[]): Promise<EncodedMultipart>;
+}
+export interface DpopProofInput {
+    method: string;
+    url: string;
+    accessToken?: string | undefined;
+    nonce?: string | undefined;
+}
+export interface PublicJwk {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    [key: string]: unknown;
+}
+export interface DpopKeyProvider {
+    getPublicJwk(): Promise<PublicJwk>;
+    getThumbprint(): Promise<string>;
+    signProof(input: DpopProofInput): Promise<string>;
+}
+export interface ClientSessionAccess {
+    accessToken: string;
+    tokenType: "Bearer" | "DPoP";
+    expiresAt: number;
+    sessionId?: string;
+    capabilities?: readonly string[];
+    dpopKeyProvider?: DpopKeyProvider;
+    dpopNonce?: string;
+}
+export interface SessionRequestContext {
+    reason: "request" | "expired" | "unauthorized" | "stream_detached";
+    signal?: AbortSignalLike | undefined;
+}
+export interface ClientSessionProvider {
+    getAccess(context: SessionRequestContext): Promise<ClientSessionAccess>;
+    refresh?(context: SessionRequestContext): Promise<ClientSessionAccess>;
+    revoke?(input?: {
+        signal?: AbortSignalLike | undefined;
+        idempotencyKey?: string;
+    }): Promise<void>;
+}
+export interface ClientSessionStorageRecord {
+    refreshGrant: string;
+    sessionId?: string;
+    absoluteExpiresAt?: string;
+}
+export interface ClientSessionStorage {
+    load(): Promise<ClientSessionStorageRecord | null>;
+    save(record: ClientSessionStorageRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface SessionRefreshFenceRecord {
+    active: boolean;
+    expiresAt: number;
+    fence: number;
+    operationId: string;
+    ownerId: string;
+}
+export interface SessionRefreshFenceStorage {
+    load(): Promise<SessionRefreshFenceRecord | null>;
+    compareAndSwap(expectedFence: number | null, next: SessionRefreshFenceRecord): Promise<boolean>;
+}
+export interface SessionRefreshLease {
+    readonly fence: number;
+    readonly operationId: string;
+    assertActive(): Promise<void>;
+}
+export interface SessionRefreshCoordinator {
+    runExclusive<T>(operation: (lease: SessionRefreshLease) => Promise<T>): Promise<T>;
+}
+export type WaitCapability = (milliseconds: number) => Promise<void>;
+export type TelemetryEvent = {
+    type: "request.started" | "request.completed";
+    operation: string;
+    method: string;
+    status?: number;
+    durationMs?: number;
+    retryCount: number;
+} | {
+    type: "stream.connected" | "stream.detached" | "stream.reconnecting" | "stream.completed";
+    operation: "chat.stream" | "runs.attach" | "threads.events";
+    runId?: string;
+    cursor?: number;
+    attempt: number;
+    reason?: "network" | "token_expired" | "revoked" | "policy_changed" | "server_detach";
+} | {
+    type: "session.refreshed" | "session.revoked";
+    operation: "session";
+};
+export interface TelemetrySink {
+    emit(event: TelemetryEvent): MaybePromise<void>;
+}
+export type TransportSelection = "auto" | "fetch";
+export interface Agents24ClientOptions {
+    baseUrl: string;
+    deploymentId: string;
+    sessionProvider: ClientSessionProvider;
+    fetch?: FetchLike;
+    decoder?: () => TextDecoderLike;
+    encoder?: TextEncoderLike;
+    ids?: IdProvider;
+    clock?: Clock;
+    multipart?: MultipartEncoder;
+    telemetry?: TelemetrySink;
+    transport?: TransportSelection;
+    maxReconnectAttempts?: number;
+}
+export interface ClientBootstrap {
+    version: string;
+    deployment: {
+        id: string;
+        name: string;
+        agent_version_id: string;
+        policy_epoch: number;
+    };
+    authentication: {
+        modes: readonly string[];
+        access_token_lifetime_seconds: number;
+        jwks_path: string;
+    };
+    capabilities: readonly string[];
+    features: Record<string, unknown>;
+    native_profiles: readonly Record<string, unknown>[];
+}
+export interface ClientHints {
+    sdk_name?: string;
+    sdk_version?: string;
+    platform?: string;
+    locale?: string;
+    timezone?: string;
+}
+export interface ChatStreamInput {
+    input: string;
+    headers?: Readonly<Record<string, string>>;
+    threadId?: string;
+    attachmentIds?: readonly string[];
+    requestedModelId?: string;
+    toolInputs?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    metadata?: Readonly<Record<string, unknown>>;
+    client?: ClientHints;
+    idempotencyKey: string;
+    signal?: AbortSignalLike | undefined;
+}
+export interface StreamResult {
+    runId: string | null;
+    threadId: string | null;
+    cursor: number | null;
+    detached: boolean;
+}
+export type RuntimeEventHandler = (event: RuntimeEvent) => MaybePromise<void>;
+export type ThreadSummaryEventHandler = (event: ThreadSummaryEvent) => MaybePromise<void>;
+export interface RunAttachInput {
+    runId: string;
+    cursor?: number;
+    headers?: Readonly<Record<string, string>>;
+    signal?: AbortSignalLike | undefined;
+}
+export interface ThreadListInput {
+    skip?: number;
+    limit?: number;
+    signal?: AbortSignalLike | undefined;
+}
+export interface ThreadSummary {
+    id: string;
+    title?: string | null;
+    status?: string | null;
+    updated_at?: string | null;
+    last_activity_at?: string | null;
+    last_run_id?: string | null;
+    last_run_status?: string | null;
+    [key: string]: unknown;
+}
+export interface ThreadListResult {
+    items: ThreadSummary[];
+    total?: number;
+}
+export interface ThreadDetail extends ThreadSummary {
+    turns?: readonly Record<string, unknown>[];
+    paging?: {
+        has_more?: boolean;
+        next_before_turn_index?: number | null;
+    };
+}
+export interface AttachmentResult {
+    id: string;
+    thread_id?: string | null;
+    filename: string;
+    mime_type: string;
+    byte_size: number;
+    status: string;
+    [key: string]: unknown;
+}
+export type HitlAction = "approve" | "reject" | "connect" | "skip";
+export interface HitlResumeResult {
+    run_id: string;
+    thread_id?: string | null;
+    interrupt_id: string;
+    run_status: string;
+    resolution_status: string;
+    idempotent: boolean;
+}
+export interface McpAuthorizationResult {
+    authorization_url: string;
+    callback_origin?: string;
+    state?: string;
+}
+export interface McpCallbackResult {
+    connection_id: string;
+    server_id?: string;
+}
+export interface AgentClient {
+    bootstrap(input?: {
+        signal?: AbortSignalLike;
+    }): Promise<ClientBootstrap>;
+    readonly chat: {
+        stream(input: ChatStreamInput, onEvent: RuntimeEventHandler): Promise<StreamResult>;
+    };
+    readonly runs: {
+        attach(input: RunAttachInput, onEvent: RuntimeEventHandler): Promise<StreamResult>;
+        cancel(input: {
+            runId: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<Record<string, unknown>>;
+    };
+    readonly threads: {
+        list(input?: ThreadListInput): Promise<ThreadListResult>;
+        get(input: {
+            threadId: string;
+            limit?: number;
+            beforeTurnIndex?: number;
+            includeRunEvents?: boolean;
+            signal?: AbortSignalLike;
+        }): Promise<ThreadDetail>;
+        events(input: {
+            cursor?: number;
+            signal?: AbortSignalLike;
+        }, onEvent: ThreadSummaryEventHandler): Promise<void>;
+        delete(input: {
+            threadId: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<Record<string, unknown>>;
+    };
+    readonly attachments: {
+        upload(input: {
+            upload: PortableUpload;
+            threadId?: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<AttachmentResult>;
+    };
+    readonly hitl: {
+        resume(input: {
+            runId: string;
+            interruptId: string;
+            action: HitlAction;
+            comment?: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<HitlResumeResult>;
+    };
+    readonly mcp: {
+        startAuthorization(input: {
+            runId: string;
+            serverId: string;
+            interruptId: string;
+            redirectUri: string;
+            popupNonce: string;
+            codeChallenge: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<McpAuthorizationResult>;
+        redeemCallback(input: {
+            code: string;
+            codeVerifier: string;
+            idempotencyKey: string;
+            signal?: AbortSignalLike;
+        }): Promise<McpCallbackResult>;
+    };
+    readonly sessions: {
+        revoke(input?: {
+            signal?: AbortSignalLike;
+            idempotencyKey?: string;
+        }): Promise<void>;
+    };
+}

package/dist/url.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeBaseUrl(input: string): string;
+export declare function absoluteUrl(baseUrl: string, path: string): string;
+export declare function canonicalHtu(input: string): string;
+export declare function encodePath(value: string): string;
+export declare function appendQuery(path: string, values: Readonly<Record<string, string | number | boolean | undefined>>): string;

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@agents24/client",
+  "version": "0.1.0",
+  "description": "Framework-neutral end-user runtime client for deployment-scoped Agents24 sessions.",
+  "keywords": [
+    "agents24",
+    "agent",
+    "client",
+    "sse",
+    "dpop"
+  ],
+  "author": "Talmudpedia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daniel5426/talmudpedia.git",
+    "directory": "packages/agents24-client"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./browser": {
+      "types": "./dist/adapters/browser.d.ts",
+      "default": "./dist/adapters/browser.js"
+    },
+    "./worker": {
+      "types": "./dist/adapters/worker.d.ts",
+      "default": "./dist/adapters/worker.js"
+    },
+    "./node": {
+      "types": "./dist/adapters/node.d.ts",
+      "default": "./dist/adapters/node.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/adapters/cloudflare.d.ts",
+      "default": "./dist/adapters/cloudflare.js"
+    },
+    "./compatibility.json": "./compatibility.json"
+  },
+  "files": [
+    "dist",
+    "compatibility.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "sync:contract": "node scripts/sync-contract.mjs",
+    "check:contract": "node scripts/sync-contract.mjs --check",
+    "clean": "rm -rf dist",
+    "build": "pnpm run sync:contract && tsup && tsc -p tsconfig.build.json && node scripts/sync-contract.mjs --dist",
+    "typecheck": "pnpm run sync:contract && tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test tests/unit/*.test.mjs tests/conformance/*.test.mjs",
+    "check:boundaries": "node scripts/check-boundaries.mjs",
+    "check:browser-matrix": "node scripts/check-browser-matrix.mjs",
+    "check:bun": "node scripts/check-portable-runtime.mjs --runtime=bun",
+    "check:cloudflare": "node scripts/check-cloudflare.mjs",
+    "check:deno": "node scripts/check-portable-runtime.mjs --runtime=deno",
+    "check:electron": "node scripts/check-electron.mjs",
+    "check:metro": "node scripts/check-metro.mjs",
+    "check:pack": "node scripts/check-pack.mjs",
+    "check:service-worker": "node scripts/check-service-worker.mjs",
+    "prepack": "pnpm run build && pnpm run check:boundaries"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "esbuild": "^0.28.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}