novoagents 0.1.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0-alpha.2
+
+- Hardened the npm package surface for public beta distribution: the tarball
+  now ships compiled runtime and declaration files only, with TypeScript source
+  and source maps excluded.
+- Added a browser-runtime guard so the SDK fails fast before a customer can
+  accidentally expose `NOVO_AGENTS_API_KEY` client-side.
+
+## 0.1.0-alpha.1
+
+- Added the first publishable Novo Agents SDK surface.
+- Added `NovoAgents` with `agents` and `threads` namespaces.
+- Added server-side streaming via `RunStream`, including async iteration, `toResponse()`, `toReadableStream()`, `reconnect()`, `cancel()`, `finalResult`, and `usage`.
+- Added `NovoAPIError` for Stripe-shaped API errors.
+- Defaulted the API base to `https://api.novoagents.ai`.

package/README.md

@@ -0,0 +1,69 @@
+# Novo Agents TypeScript SDK
+
+Server-only TypeScript client for the hosted Novo Agents API.
+
+Customers install `novoagents`, keep `NOVO_AGENTS_API_KEY` on their server, and stream agent output through their own HTTP route. The SDK is a thin HTTP client; it does not include the private engine, Vercel Workflow, Vercel Sandbox, or provider SDKs.
+
+## Install
+
+```sh
+npm install novoagents@alpha
+```
+
+## Usage
+
+```ts
+import { NovoAgents } from 'novoagents';
+
+const novo = new NovoAgents({
+  apiKey: process.env.NOVO_AGENTS_API_KEY,
+});
+
+const agent = await novo.agents.create({
+  identity: 'You are an expert coding agent for our platform.',
+  intelligence: 3,
+});
+
+const thread = await novo.threads.create({ agentId: agent.id });
+
+const stream = await novo.threads.stream(thread.id, {
+  input: 'Fix the failing checkout tests',
+  budgetCents: 250,
+  maxSteps: 25,
+});
+
+for await (const event of stream) {
+  // event is NovoAgentEvent: AI SDK UIMessageChunk plus data-novo-* chunks.
+}
+
+const result = await stream.finalResult;
+```
+
+## Browser Streaming
+
+Do not expose Novo API keys to browsers. `novoagents` is server-only and throws
+if constructed in a browser-like runtime; proxy the stream through your server:
+
+```ts
+import { NovoAgents } from 'novoagents';
+
+const novo = new NovoAgents();
+
+export async function POST(req: Request) {
+  const { threadId, input } = await req.json();
+  const stream = await novo.threads.stream(threadId, { input });
+  return stream.toResponse();
+}
+```
+
+## API Shape
+
+- `novo.agents.*` manages reusable agent configuration: identity, intelligence, and metadata.
+- `novo.threads.*` manages conversation/task context and is the happy path for sending input.
+- `novo.threads.stream(threadId, ...)` starts a run and returns a `RunStream`.
+- `RunStream` is async iterable and also exposes `toResponse()`, `toReadableStream()`, `reconnect()`, `cancel()`, `finalResult`, and `usage`.
+- Runs are operational receipts. The SDK exposes `threads.getRun(runId)` for status reads, but customers do not create runs directly.
+
+Default API base: `https://api.novoagents.ai`.
+
+Default auth env var: `NOVO_AGENTS_API_KEY`.

package/dist/index.d.ts

@@ -0,0 +1,444 @@
+export type NovoAgentsOptions = {
+    apiKey?: string;
+    baseUrl?: string;
+    version?: string;
+    fetch?: typeof fetch;
+};
+export type Metadata = Record<string, string>;
+export type MetadataPatch = Record<string, string | null>;
+export type Page<T> = {
+    object: 'list';
+    data: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+};
+export type StandardUIMessageChunk = {
+    type: string;
+    [key: string]: unknown;
+};
+export type NovoRunMetaChunk = {
+    type: 'data-novo-run-meta';
+    data: {
+        runId: string;
+        threadId: string;
+        agentId: string;
+        createdAt: string;
+    };
+};
+export type NovoUsageChunk = {
+    type: 'data-novo-usage';
+    data: {
+        runId: string;
+        threadId: string;
+        agentId: string;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        runtimeMs: number;
+        toolCallCount: number;
+        finishReason: string;
+    };
+};
+export type NovoTerminalChunk = {
+    type: 'data-novo-terminal';
+    data: {
+        status: 'completed' | 'failed' | 'cancelled';
+        error?: RunError;
+        finishReason?: string;
+    };
+};
+export type NovoDataChunk = NovoRunMetaChunk | NovoUsageChunk | NovoTerminalChunk;
+export type NovoAgentEvent = StandardUIMessageChunk | NovoDataChunk;
+export type AgentCapabilities = {
+    filesystem?: {
+        environmentId: string;
+    };
+    shell?: {
+        environmentId: string;
+    };
+    web?: boolean;
+    planning?: boolean;
+    /**
+     * Enable the managed `generate_image` tool. Binary output routes through
+     * the universal `toolResultArtifacts` handler — the customer's handler
+     * does per-tool routing via the `toolName` field in the dispatch body.
+     * Requires `toolResultArtifacts` to be configured.
+     */
+    imageGeneration?: boolean;
+    toolResultArtifacts?: {
+        resultHandlerId: string;
+    };
+    rawMcp?: {
+        toolServerIds: string[];
+    };
+    /**
+     * Enable the managed `search_voices` tool — a metadata lookup against
+     * the public voice library. Inline response; requires the cloud
+     * worker to have an ElevenLabs API key configured.
+     */
+    voiceSearch?: boolean;
+    /**
+     * Enable the managed `generate_video` tool — Fal.ai Seedance 2.0 Fast
+     * Reference-to-Video. Output (an MP4 URL) routes through the universal
+     * `toolResultArtifacts` handler as a `content.kind: 'url'` artifact;
+     * the customer's handler is expected to copy the asset to its own
+     * storage before Fal's short-lived URL expires. Requires
+     * `toolResultArtifacts` to be configured.
+     */
+    videoGeneration?: boolean;
+    skills?: AgentSkill[];
+};
+export type AgentSkill = {
+    name: string;
+    description: string;
+    body: string;
+    frontmatter?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type AgentEventsInput = {
+    eventSinkId: string;
+} | {
+    type: 'remote';
+    url: string;
+    secret: string;
+};
+export type AgentPolicies = {
+    maxStepsDefault?: number;
+    maxDurationMsDefault?: number;
+    mediaFidelity?: 'standard' | 'spatial';
+};
+export type Agent = {
+    id: string;
+    object: 'agent';
+    status: 'active' | 'deleting';
+    identity: string;
+    intelligence: 1 | 2 | 3 | 4 | 5;
+    capabilities: AgentCapabilities;
+    events: {
+        eventSinkId: string;
+    } | null;
+    policies: AgentPolicies;
+    metadata: Metadata;
+    configVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type Thread = {
+    id: string;
+    object: 'thread';
+    agentId: string;
+    status: 'idle' | 'running' | 'deleting';
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+};
+export type UsageTotal = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    runtimeMs: number;
+    toolCallCount: number;
+};
+export type RunError = {
+    type: string;
+    code: string;
+    message: string;
+};
+export type Run = {
+    id: string;
+    object: 'run';
+    threadId: string;
+    agentId: string;
+    agentConfigSnapshot: {
+        identity: string;
+        intelligence: 1 | 2 | 3 | 4 | 5;
+        configVersion: number;
+    };
+    status: 'queued' | 'preparing' | 'running' | 'completed' | 'failed' | 'cancelled';
+    finishReason?: string;
+    usage?: UsageTotal;
+    error?: RunError;
+    metadata: Metadata;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+};
+export type Environment = {
+    id: string;
+    object: 'environment';
+    name: string;
+    type: 'http_workspace';
+    url: string;
+    metadata: Metadata;
+    configVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ResultHandler = {
+    id: string;
+    object: 'result_handler';
+    name: string;
+    /**
+     * Always `'artifact'` after the universal-handler collapse. One customer
+     * endpoint receives the binary output of every managed tool that emits
+     * one; per-tool routing happens inside the customer's handler via the
+     * `toolName` field in the dispatch body.
+     */
+    kind: 'artifact';
+    url: string;
+    metadata: Metadata;
+    configVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type EventSink = {
+    id: string;
+    object: 'event_sink';
+    name: string;
+    url: string;
+    enabled: boolean;
+    deliveryMode: 'required' | 'best_effort';
+    metadata: Metadata;
+    configVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ToolServer = {
+    id: string;
+    object: 'tool_server';
+    name: string;
+    transport: 'http' | 'sse';
+    url: string;
+    allowedTools?: string[];
+    resultCapBytes?: number;
+    protocolVersion: string;
+    trusted: boolean;
+    metadata: Metadata;
+    configVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type DeleteAgentResponse = {
+    id: string;
+    object: 'agent';
+    status: 'deleting';
+};
+export type DeleteThreadResponse = {
+    id: string;
+    object: 'thread';
+    status: 'deleting';
+};
+export type CancelThreadResponse = {
+    object: 'thread.cancel';
+    threadId: string;
+    runId: string | null;
+    status: 'cancelling' | 'idle';
+};
+export type RunFinalResult = {
+    runId: string;
+    threadId: string;
+    agentId: string;
+    text: string;
+    finishReason: string;
+    usage: UsageTotal;
+};
+export type RunStream = AsyncIterable<NovoAgentEvent> & {
+    runId: Promise<string>;
+    threadId: string;
+    agentId: Promise<string>;
+    finalResult: Promise<RunFinalResult>;
+    usage: Promise<UsageTotal>;
+    close(): void;
+    cancel(): Promise<void>;
+    reconnect(startIndex?: number): Promise<RunStream>;
+    toResponse(init?: ResponseInit): Response;
+    toReadableStream(): ReadableStream<Uint8Array>;
+};
+export type AgentsNamespace = {
+    list(input?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Agent>>;
+    create(input: {
+        identity: string;
+        intelligence?: 1 | 2 | 3 | 4 | 5;
+        capabilities?: AgentCapabilities;
+        events?: AgentEventsInput;
+        policies?: AgentPolicies;
+        metadata?: Metadata;
+    }): Promise<Agent>;
+    get(agentId: string): Promise<Agent>;
+    update(agentId: string, input: {
+        identity?: string;
+        intelligence?: 1 | 2 | 3 | 4 | 5;
+        capabilities?: AgentCapabilities;
+        events?: AgentEventsInput | null;
+        policies?: {
+            maxStepsDefault?: number | null;
+            maxDurationMsDefault?: number | null;
+            mediaFidelity?: 'standard' | 'spatial' | null;
+        };
+        metadata?: MetadataPatch;
+    }): Promise<Agent>;
+    delete(agentId: string): Promise<DeleteAgentResponse>;
+};
+export type EnvironmentsNamespace = {
+    register(input: {
+        type: 'http_workspace';
+        name: string;
+        url: string;
+        secret: string;
+        metadata?: Metadata;
+    }): Promise<Environment>;
+    list(): Promise<Page<Environment>>;
+    get(environmentId: string): Promise<Environment>;
+    delete(environmentId: string): Promise<{
+        id: string;
+        object: 'environment';
+        deleted: true;
+    }>;
+    rotateSecret(environmentId: string, input: {
+        secret: string;
+    }): Promise<Environment>;
+};
+export type ResultHandlersNamespace = {
+    register(input: {
+        kind: 'artifact';
+        name: string;
+        url: string;
+        secret: string;
+        metadata?: Metadata;
+    }): Promise<ResultHandler>;
+    list(): Promise<Page<ResultHandler>>;
+    get(resultHandlerId: string): Promise<ResultHandler>;
+    delete(resultHandlerId: string): Promise<{
+        id: string;
+        object: 'result_handler';
+        deleted: true;
+    }>;
+    rotateSecret(resultHandlerId: string, input: {
+        secret: string;
+    }): Promise<ResultHandler>;
+};
+export type EventSinksNamespace = {
+    register(input: {
+        name: string;
+        url: string;
+        secret: string;
+        deliveryMode?: 'required' | 'best_effort';
+        metadata?: Metadata;
+    }): Promise<EventSink>;
+    list(): Promise<Page<EventSink>>;
+    get(eventSinkId: string): Promise<EventSink>;
+    delete(eventSinkId: string): Promise<{
+        id: string;
+        object: 'event_sink';
+        deleted: true;
+    }>;
+    rotateSecret(eventSinkId: string, input: {
+        secret: string;
+    }): Promise<EventSink>;
+    test(eventSinkId: string): Promise<{
+        delivered: true;
+        latencyMs: number;
+    }>;
+};
+export type ToolServersNamespace = {
+    register(input: {
+        name: string;
+        transport: 'http' | 'sse';
+        url: string;
+        secret: string;
+        allowedTools?: string[];
+        resultCapBytes?: number;
+        protocolVersion?: '2025-11-25';
+        trusted?: boolean;
+        metadata?: Metadata;
+    }): Promise<ToolServer>;
+    list(): Promise<Page<ToolServer>>;
+    get(toolServerId: string): Promise<ToolServer>;
+    delete(toolServerId: string): Promise<{
+        id: string;
+        object: 'tool_server';
+        deleted: true;
+    }>;
+    rotateSecret(toolServerId: string, input: {
+        secret: string;
+    }): Promise<ToolServer>;
+};
+export type ThreadsNamespace = {
+    list(input: {
+        agentId: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Thread>>;
+    create(input: {
+        agentId: string;
+        metadata?: Metadata;
+    }): Promise<Thread>;
+    get(threadId: string): Promise<Thread>;
+    update(threadId: string, input: {
+        metadata?: MetadataPatch;
+    }): Promise<Thread>;
+    delete(threadId: string): Promise<DeleteThreadResponse>;
+    stream(threadId: string, input: {
+        input: string;
+        budgetCents?: number;
+        maxSteps?: number;
+        maxDurationMs?: number;
+        metadata?: Metadata;
+        idempotencyKey?: string;
+    }): Promise<RunStream>;
+    send(threadId: string, input: {
+        input: string;
+        budgetCents?: number;
+        maxSteps?: number;
+        maxDurationMs?: number;
+        metadata?: Metadata;
+        idempotencyKey?: string;
+    }): Promise<Run>;
+    cancel(threadId: string): Promise<CancelThreadResponse>;
+    getRun(runId: string): Promise<Run>;
+};
+export declare class NovoAPIError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly requestId: string;
+    readonly status: number;
+    constructor(input: {
+        type: string;
+        code: string;
+        message: string;
+        requestId: string;
+        status: number;
+    });
+}
+export declare class NovoAgents {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly version: string;
+    readonly fetch: typeof fetch;
+    readonly agents: AgentsNamespace;
+    readonly threads: ThreadsNamespace;
+    readonly environments: EnvironmentsNamespace;
+    readonly resultHandlers: ResultHandlersNamespace;
+    readonly eventSinks: EventSinksNamespace;
+    readonly toolServers: ToolServersNamespace;
+    private readonly client;
+    constructor(options?: NovoAgentsOptions);
+}
+export declare function verifyNovoSignature(input: {
+    rawBody: string;
+    signatureHeader: string;
+    secret: string;
+    toleranceSeconds?: number;
+}): {
+    valid: true;
+    timestamp: number;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare const verifyEventSinkSignature: typeof verifyNovoSignature;

package/dist/index.js

@@ -0,0 +1,752 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const DEFAULT_BASE_URL = 'https://api.novoagents.ai';
+const DEFAULT_VERSION = '2026-05-17';
+const TERMINAL_RUN_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const EMPTY_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    runtimeMs: 0,
+    toolCallCount: 0,
+};
+export class NovoAPIError extends Error {
+    type;
+    code;
+    requestId;
+    status;
+    constructor(input) {
+        super(input.message);
+        this.name = 'NovoAPIError';
+        this.type = input.type;
+        this.code = input.code;
+        this.requestId = input.requestId;
+        this.status = input.status;
+    }
+}
+export class NovoAgents {
+    apiKey;
+    baseUrl;
+    version;
+    fetch;
+    agents;
+    threads;
+    environments;
+    resultHandlers;
+    eventSinks;
+    toolServers;
+    client;
+    constructor(options = {}) {
+        if (typeof window !== 'undefined') {
+            throw new Error('novoagents is server-only; proxy streams through your server route.');
+        }
+        const apiKey = options.apiKey ?? process.env.NOVO_AGENTS_API_KEY;
+        if (!apiKey) {
+            throw new Error('NovoAgents requires apiKey or NOVO_AGENTS_API_KEY.');
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.version = options.version ?? DEFAULT_VERSION;
+        this.fetch = options.fetch ?? fetch;
+        this.client = new NovoHttpClient({
+            apiKey: this.apiKey,
+            baseUrl: this.baseUrl,
+            version: this.version,
+            fetch: this.fetch,
+        });
+        this.agents = createAgentsNamespace(this.client);
+        this.threads = createThreadsNamespace(this.client);
+        this.environments = createEnvironmentsNamespace(this.client);
+        this.resultHandlers = createResultHandlersNamespace(this.client);
+        this.eventSinks = createEventSinksNamespace(this.client);
+        this.toolServers = createToolServersNamespace(this.client);
+    }
+}
+class NovoHttpClient {
+    baseUrl;
+    apiKey;
+    version;
+    fetchImpl;
+    constructor(input) {
+        this.apiKey = input.apiKey;
+        this.baseUrl = input.baseUrl;
+        this.version = input.version;
+        this.fetchImpl = input.fetch;
+    }
+    async json(options) {
+        const response = await this.raw({
+            ...options,
+            headers: {
+                Accept: 'application/json',
+                ...options.headers,
+            },
+        });
+        await assertOk(response);
+        return (await response.json());
+    }
+    async stream(options) {
+        const response = await this.raw({
+            ...options,
+            headers: {
+                Accept: 'text/event-stream',
+                ...options.headers,
+            },
+        });
+        await assertOk(response);
+        if (!response.body) {
+            throw new NovoAPIError({
+                type: 'api_error',
+                code: 'internal_error',
+                message: 'Stream response did not include a body.',
+                requestId: response.headers.get('X-Request-Id') ?? '',
+                status: response.status,
+            });
+        }
+        return response;
+    }
+    async raw(options) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Novo-Version': this.version,
+        };
+        for (const [key, value] of Object.entries(options.headers ?? {})) {
+            if (value !== undefined)
+                headers[key] = value;
+        }
+        let body;
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(options.body);
+        }
+        return this.fetchImpl(this.url(options.path, options.query), {
+            method: options.method ?? 'GET',
+            headers,
+            body,
+            signal: options.signal,
+        });
+    }
+    url(path, query) {
+        const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+}
+function createAgentsNamespace(client) {
+    return {
+        list(input = {}) {
+            return client.json({
+                path: '/v1/agents',
+                query: input,
+            });
+        },
+        create(input) {
+            return client.json({
+                method: 'POST',
+                path: '/v1/agents',
+                body: input,
+            });
+        },
+        get(agentId) {
+            return client.json({ path: `/v1/agents/${encodeURIComponent(agentId)}` });
+        },
+        update(agentId, input) {
+            return client.json({
+                method: 'PATCH',
+                path: `/v1/agents/${encodeURIComponent(agentId)}`,
+                body: input,
+            });
+        },
+        delete(agentId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/agents/${encodeURIComponent(agentId)}`,
+            });
+        },
+    };
+}
+function createThreadsNamespace(client) {
+    return {
+        list(input) {
+            return client.json({
+                path: '/v1/threads',
+                query: input,
+            });
+        },
+        create(input) {
+            return client.json({
+                method: 'POST',
+                path: '/v1/threads',
+                body: input,
+            });
+        },
+        get(threadId) {
+            return client.json({ path: `/v1/threads/${encodeURIComponent(threadId)}` });
+        },
+        update(threadId, input) {
+            return client.json({
+                method: 'PATCH',
+                path: `/v1/threads/${encodeURIComponent(threadId)}`,
+                body: input,
+            });
+        },
+        delete(threadId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/threads/${encodeURIComponent(threadId)}`,
+            });
+        },
+        async stream(threadId, input) {
+            const controller = new AbortController();
+            const response = await client.stream({
+                method: 'POST',
+                path: `/v1/threads/${encodeURIComponent(threadId)}/messages`,
+                body: stripIdempotencyKey(input),
+                signal: controller.signal,
+                headers: {
+                    ...(input.idempotencyKey ? { 'Idempotency-Key': input.idempotencyKey } : {}),
+                },
+            });
+            return new NovoRunStream({
+                client,
+                threadId,
+                body: response.body,
+                abortController: controller,
+            });
+        },
+        async send(threadId, input) {
+            const receipt = await client.json({
+                method: 'POST',
+                path: `/v1/threads/${encodeURIComponent(threadId)}/messages`,
+                body: stripIdempotencyKey(input),
+                headers: {
+                    ...(input.idempotencyKey ? { 'Idempotency-Key': input.idempotencyKey } : {}),
+                },
+            });
+            return client.json({ path: `/v1/runs/${encodeURIComponent(receipt.id)}` });
+        },
+        cancel(threadId) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/threads/${encodeURIComponent(threadId)}/cancel`,
+            });
+        },
+        getRun(runId) {
+            return client.json({ path: `/v1/runs/${encodeURIComponent(runId)}` });
+        },
+    };
+}
+function createEnvironmentsNamespace(client) {
+    return {
+        register(input) {
+            return client.json({ method: 'POST', path: '/v1/environments', body: input });
+        },
+        list() {
+            return client.json({ path: '/v1/environments' });
+        },
+        get(environmentId) {
+            return client.json({ path: `/v1/environments/${encodeURIComponent(environmentId)}` });
+        },
+        delete(environmentId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/environments/${encodeURIComponent(environmentId)}`,
+            });
+        },
+        rotateSecret(environmentId, input) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/environments/${encodeURIComponent(environmentId)}/rotate-secret`,
+                body: input,
+            });
+        },
+    };
+}
+function createResultHandlersNamespace(client) {
+    return {
+        register(input) {
+            return client.json({ method: 'POST', path: '/v1/result-handlers', body: input });
+        },
+        list() {
+            return client.json({ path: '/v1/result-handlers' });
+        },
+        get(resultHandlerId) {
+            return client.json({ path: `/v1/result-handlers/${encodeURIComponent(resultHandlerId)}` });
+        },
+        delete(resultHandlerId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/result-handlers/${encodeURIComponent(resultHandlerId)}`,
+            });
+        },
+        rotateSecret(resultHandlerId, input) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/result-handlers/${encodeURIComponent(resultHandlerId)}/rotate-secret`,
+                body: input,
+            });
+        },
+    };
+}
+function createEventSinksNamespace(client) {
+    return {
+        register(input) {
+            return client.json({ method: 'POST', path: '/v1/event-sinks', body: input });
+        },
+        list() {
+            return client.json({ path: '/v1/event-sinks' });
+        },
+        get(eventSinkId) {
+            return client.json({ path: `/v1/event-sinks/${encodeURIComponent(eventSinkId)}` });
+        },
+        delete(eventSinkId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/event-sinks/${encodeURIComponent(eventSinkId)}`,
+            });
+        },
+        rotateSecret(eventSinkId, input) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/event-sinks/${encodeURIComponent(eventSinkId)}/rotate-secret`,
+                body: input,
+            });
+        },
+        test(eventSinkId) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/event-sinks/${encodeURIComponent(eventSinkId)}/test`,
+            });
+        },
+    };
+}
+function createToolServersNamespace(client) {
+    return {
+        register(input) {
+            return client.json({ method: 'POST', path: '/v1/tool-servers', body: input });
+        },
+        list() {
+            return client.json({ path: '/v1/tool-servers' });
+        },
+        get(toolServerId) {
+            return client.json({ path: `/v1/tool-servers/${encodeURIComponent(toolServerId)}` });
+        },
+        delete(toolServerId) {
+            return client.json({
+                method: 'DELETE',
+                path: `/v1/tool-servers/${encodeURIComponent(toolServerId)}`,
+            });
+        },
+        rotateSecret(toolServerId, input) {
+            return client.json({
+                method: 'POST',
+                path: `/v1/tool-servers/${encodeURIComponent(toolServerId)}/rotate-secret`,
+                body: input,
+            });
+        },
+    };
+}
+class NovoRunStream {
+    threadId;
+    runId;
+    agentId;
+    client;
+    abortController;
+    body;
+    consumed = false;
+    decoder = new TextDecoder();
+    sse = new SSEDecoder();
+    textParts = [];
+    observedFinishReason;
+    observedUsage;
+    finalResultPromise;
+    activeReader;
+    activeIterator;
+    complete;
+    fail;
+    completion;
+    runIdDeferred = deferred();
+    agentIdDeferred = deferred();
+    constructor(input) {
+        this.client = input.client;
+        this.threadId = input.threadId;
+        this.body = input.body;
+        this.abortController = input.abortController;
+        this.runId = this.runIdDeferred.promise;
+        this.agentId = this.agentIdDeferred.promise;
+        this.completion = new Promise((resolve, reject) => {
+            this.complete = resolve;
+            this.fail = reject;
+        });
+    }
+    get finalResult() {
+        this.finalResultPromise ??= this.buildFinalResult();
+        return this.finalResultPromise;
+    }
+    get usage() {
+        return this.finalResult.then((result) => result.usage);
+    }
+    [Symbol.asyncIterator]() {
+        const body = this.takeBody();
+        const reader = body.getReader();
+        this.activeReader = reader;
+        const iterator = this.iterateBody(reader);
+        this.activeIterator = iterator;
+        return iterator;
+    }
+    async *iterateBody(reader) {
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                const chunks = this.decodeChunk(next.value);
+                for (const chunk of chunks) {
+                    this.observe(chunk);
+                    yield chunk;
+                }
+                if (this.sse.done)
+                    break;
+            }
+            const chunks = this.flushDecoder();
+            for (const chunk of chunks) {
+                this.observe(chunk);
+                yield chunk;
+            }
+            this.complete();
+        }
+        catch (error) {
+            this.fail(error);
+            throw error;
+        }
+        finally {
+            if (this.activeReader === reader) {
+                this.activeReader = undefined;
+            }
+            if (this.activeIterator) {
+                this.activeIterator = undefined;
+            }
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // The stream may already be closed by the server.
+            }
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                // `close()` may have force-released the lock for a paused iterator.
+            }
+        }
+    }
+    close() {
+        this.abortController.abort();
+        void this.activeIterator?.return?.(undefined).catch(() => undefined);
+        if (!this.activeIterator && this.activeReader) {
+            const reader = this.activeReader;
+            void reader.cancel().catch(() => undefined);
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                // The reader may already be released by a concurrently finishing consumer.
+            }
+            this.activeReader = undefined;
+        }
+        this.complete();
+    }
+    async cancel() {
+        await this.client.json({
+            method: 'POST',
+            path: `/v1/threads/${encodeURIComponent(this.threadId)}/cancel`,
+        });
+    }
+    async reconnect(startIndex = 0) {
+        const runId = await this.runId;
+        const controller = new AbortController();
+        const response = await this.client.stream({
+            path: `/v1/threads/${encodeURIComponent(this.threadId)}/events`,
+            query: { runId, startIndex },
+            signal: controller.signal,
+        });
+        return new NovoRunStream({
+            client: this.client,
+            threadId: this.threadId,
+            body: response.body,
+            abortController: controller,
+        });
+    }
+    toReadableStream() {
+        const body = this.takeBody();
+        const reader = body.getReader();
+        this.activeReader = reader;
+        return new ReadableStream({
+            start: async (controller) => {
+                try {
+                    while (true) {
+                        const next = await reader.read();
+                        if (next.done)
+                            break;
+                        for (const chunk of this.decodeChunk(next.value)) {
+                            this.observe(chunk);
+                        }
+                        controller.enqueue(next.value);
+                        if (this.sse.done)
+                            break;
+                    }
+                    for (const chunk of this.flushDecoder()) {
+                        this.observe(chunk);
+                    }
+                    controller.close();
+                    this.complete();
+                }
+                catch (error) {
+                    controller.error(error);
+                    this.fail(error);
+                }
+                finally {
+                    if (this.activeReader === reader) {
+                        this.activeReader = undefined;
+                    }
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch {
+                        // `close()` may have force-released the lock for a paused proxy reader.
+                    }
+                }
+            },
+            cancel: async (reason) => {
+                await reader.cancel(reason);
+                this.close();
+            },
+        });
+    }
+    toResponse(init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set('Content-Type', headers.get('Content-Type') ?? 'text/event-stream; charset=utf-8');
+        headers.set('Cache-Control', headers.get('Cache-Control') ?? 'no-cache, no-transform');
+        headers.set('Connection', headers.get('Connection') ?? 'keep-alive');
+        headers.set('x-vercel-ai-ui-message-stream', headers.get('x-vercel-ai-ui-message-stream') ?? 'v1');
+        return new Response(this.toReadableStream(), {
+            ...init,
+            headers,
+        });
+    }
+    takeBody() {
+        if (this.consumed || !this.body) {
+            throw new Error('RunStream is single-consumer; create a reconnect stream for another reader.');
+        }
+        this.consumed = true;
+        const body = this.body;
+        this.body = null;
+        return body;
+    }
+    decodeChunk(bytes) {
+        const text = this.decoder.decode(bytes, { stream: true });
+        return this.sse.push(text);
+    }
+    flushDecoder() {
+        return this.sse.push(this.decoder.decode());
+    }
+    observe(event) {
+        if (isNovoRunMetaChunk(event)) {
+            this.runIdDeferred.resolve(event.data.runId);
+            this.agentIdDeferred.resolve(event.data.agentId);
+            return;
+        }
+        if (isNovoUsageChunk(event)) {
+            this.observedUsage = {
+                inputTokens: event.data.inputTokens,
+                outputTokens: event.data.outputTokens,
+                cacheReadTokens: event.data.cacheReadTokens,
+                cacheWriteTokens: event.data.cacheWriteTokens,
+                runtimeMs: event.data.runtimeMs,
+                toolCallCount: event.data.toolCallCount,
+            };
+            this.observedFinishReason = event.data.finishReason;
+            return;
+        }
+        if (event.type === 'text-delta' && typeof event.delta === 'string') {
+            this.textParts.push(event.delta);
+            return;
+        }
+        if (event.type === 'finish' && typeof event.finishReason === 'string') {
+            this.observedFinishReason = event.finishReason;
+        }
+    }
+    async buildFinalResult() {
+        await this.completion;
+        const runId = await this.runId;
+        const agentId = await this.agentId;
+        const run = await this.pollTerminalRun(runId);
+        const usage = run.usage ?? this.observedUsage ?? EMPTY_USAGE;
+        return {
+            runId,
+            threadId: this.threadId,
+            agentId,
+            text: this.textParts.join(''),
+            finishReason: run.finishReason ?? this.observedFinishReason ?? run.status,
+            usage,
+        };
+    }
+    async pollTerminalRun(runId) {
+        let latest;
+        for (let attempt = 0; attempt < 10; attempt += 1) {
+            latest = await this.client.json({ path: `/v1/runs/${encodeURIComponent(runId)}` });
+            if (TERMINAL_RUN_STATUSES.has(latest.status) && latest.usage) {
+                return latest;
+            }
+            await sleep(250);
+        }
+        if (latest)
+            return latest;
+        return this.client.json({ path: `/v1/runs/${encodeURIComponent(runId)}` });
+    }
+}
+class SSEDecoder {
+    done = false;
+    buffer = '';
+    push(input) {
+        if (this.done)
+            return [];
+        this.buffer += input.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const events = [];
+        while (true) {
+            const separator = this.buffer.indexOf('\n\n');
+            if (separator === -1)
+                break;
+            const frame = this.buffer.slice(0, separator);
+            this.buffer = this.buffer.slice(separator + 2);
+            const event = this.parseFrame(frame);
+            if (event === '[DONE]') {
+                this.done = true;
+                break;
+            }
+            if (event)
+                events.push(event);
+        }
+        return events;
+    }
+    parseFrame(frame) {
+        const dataLines = [];
+        for (const line of frame.split('\n')) {
+            if (!line || line.startsWith(':'))
+                continue;
+            if (!line.startsWith('data:'))
+                continue;
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+        }
+        if (dataLines.length === 0)
+            return undefined;
+        const data = dataLines.join('\n');
+        if (data === '[DONE]')
+            return '[DONE]';
+        return JSON.parse(data);
+    }
+}
+async function assertOk(response) {
+    if (response.ok)
+        return;
+    const requestId = response.headers.get('X-Request-Id') ?? '';
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch {
+        parsed = undefined;
+    }
+    const error = parsed?.error;
+    throw new NovoAPIError({
+        type: error?.type ?? 'api_error',
+        code: error?.code ?? 'internal_error',
+        message: error?.message ?? `Novo API request failed with status ${response.status}.`,
+        requestId: error?.request_id ?? requestId,
+        status: response.status,
+    });
+}
+function stripIdempotencyKey(input) {
+    const { idempotencyKey: _idempotencyKey, ...body } = input;
+    return body;
+}
+function isNovoRunMetaChunk(event) {
+    return (event.type === 'data-novo-run-meta' &&
+        hasObjectData(event) &&
+        typeof event.data.runId === 'string' &&
+        typeof event.data.threadId === 'string' &&
+        typeof event.data.agentId === 'string' &&
+        typeof event.data.createdAt === 'string');
+}
+function isNovoUsageChunk(event) {
+    return (event.type === 'data-novo-usage' &&
+        hasObjectData(event) &&
+        typeof event.data.runId === 'string' &&
+        typeof event.data.threadId === 'string' &&
+        typeof event.data.agentId === 'string' &&
+        typeof event.data.inputTokens === 'number' &&
+        typeof event.data.outputTokens === 'number' &&
+        typeof event.data.cacheReadTokens === 'number' &&
+        typeof event.data.cacheWriteTokens === 'number' &&
+        typeof event.data.runtimeMs === 'number' &&
+        typeof event.data.toolCallCount === 'number' &&
+        typeof event.data.finishReason === 'string');
+}
+function hasObjectData(event) {
+    return ('data' in event &&
+        typeof event.data === 'object' &&
+        event.data !== null &&
+        !Array.isArray(event.data));
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, '');
+}
+export function verifyNovoSignature(input) {
+    const parsed = parseNovoSignatureHeader(input.signatureHeader);
+    if (!parsed)
+        return { valid: false, reason: 'signature_header_invalid' };
+    const toleranceSeconds = input.toleranceSeconds ?? 300;
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - parsed.timestamp) > toleranceSeconds) {
+        return { valid: false, reason: 'timestamp_outside_tolerance' };
+    }
+    const expected = createHmac('sha256', input.secret)
+        .update(`${parsed.timestamp}.${input.rawBody}`)
+        .digest('hex');
+    const actual = Buffer.from(parsed.signature, 'hex');
+    const expectedBuffer = Buffer.from(expected, 'hex');
+    if (actual.length !== expectedBuffer.length) {
+        return { valid: false, reason: 'signature_mismatch' };
+    }
+    if (!timingSafeEqual(actual, expectedBuffer)) {
+        return { valid: false, reason: 'signature_mismatch' };
+    }
+    return { valid: true, timestamp: parsed.timestamp };
+}
+export const verifyEventSinkSignature = verifyNovoSignature;
+function parseNovoSignatureHeader(value) {
+    const parts = Object.fromEntries(value.split(',').map((part) => {
+        const [key, ...rest] = part.trim().split('=');
+        return [key, rest.join('=')];
+    }));
+    const timestamp = Number(parts.t);
+    const signature = parts.v1;
+    if (!Number.isInteger(timestamp) || !signature || !/^[a-f0-9]+$/i.test(signature)) {
+        return undefined;
+    }
+    return { timestamp, signature };
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "novoagents",
+  "version": "0.1.0-alpha.2",
+  "description": "Thin TypeScript SDK for the Novo Agents hosted API.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "browser": {
+    "./dist/index.js": false
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "pnpm run clean && pnpm run build"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  }
+}