sideagent 0.0.0-stage → 0.2.0

package/dist/protocol.d.ts

@@ -0,0 +1,87 @@
+/** Events streamed from server to client over SSE. Shared with the client as types only. */
+type AgentEvent = {
+    type: "turn.start";
+    threadId: string;
+} | {
+    type: "text.delta";
+    text: string;
+} | {
+    type: "tool.start";
+    callId: string;
+    operationId: string;
+} | {
+    type: "approval.request";
+    callId: string;
+    operationId: string;
+    method: string;
+    path: string;
+    args: unknown;
+    token: string;
+    expiresAt: number;
+} | {
+    type: "tool.complete";
+    callId: string;
+    operationId: string;
+    status: number;
+    args: unknown;
+    result: unknown;
+    invalidates: string[];
+} | {
+    type: "tool.rejected";
+    callId: string;
+    operationId: string;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+} | {
+    type: "turn.end";
+};
+type ChatRequest = {
+    threadId?: string;
+    message: string;
+    context?: unknown;
+} | {
+    threadId: string;
+    approval: {
+        token: string;
+        decision: "approve" | "reject";
+    };
+} | {
+    action: "threads.list";
+} | {
+    action: "threads.get";
+    threadId: string;
+} | {
+    action: "threads.delete";
+    threadId: string;
+};
+interface ThreadMeta {
+    id: string;
+    /** First user message, truncated. Never model output. */
+    title: string;
+    updatedAt: number;
+}
+type HistoryPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool";
+    callId: string;
+    operationId: string;
+    args: unknown;
+    result?: unknown;
+};
+interface HistoryMessage {
+    role: "user" | "assistant";
+    parts: HistoryPart[];
+}
+interface ThreadResponse {
+    messages: HistoryMessage[];
+    /** Set when the thread is waiting for an approval decision. */
+    pending?: Extract<AgentEvent, {
+        type: "approval.request";
+    }>;
+}
+
+export type { AgentEvent, ChatRequest, HistoryMessage, HistoryPart, ThreadMeta, ThreadResponse };

package/dist/server/browser.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/server/browser.js

@@ -0,0 +1,4 @@
+// src/server/browser.ts
+throw new Error(
+  "sideagent/server is server-only and was imported into a browser bundle. It holds your LLM key and tool credentials. Import 'sideagent' in the browser instead."
+);

package/dist/server/index.d.ts

@@ -0,0 +1,260 @@
+import { ThreadMeta } from '../protocol.js';
+export { AgentEvent, ChatRequest } from '../protocol.js';
+import { z } from 'zod';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+
+declare const configSchema: z.ZodObject<{
+    spec: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    baseUrl: z.ZodString;
+    llm: z.ZodOptional<z.ZodObject<{
+        baseUrl: z.ZodString;
+        apiKey: z.ZodString;
+        model: z.ZodString;
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    allow: z.ZodArray<z.ZodString>;
+    allowedOrigins: z.ZodArray<z.ZodString>;
+    anonymous: z.ZodOptional<z.ZodBoolean>;
+    allowPrivateNetworks: z.ZodOptional<z.ZodBoolean>;
+    approvalSecret: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>>>;
+        urls: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        embeddings: z.ZodOptional<z.ZodObject<{
+            model: z.ZodString;
+            baseUrl: z.ZodOptional<z.ZodString>;
+            apiKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        topK: z.ZodDefault<z.ZodNumber>;
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+        maxSourceBytes: z.ZodDefault<z.ZodNumber>;
+        maxChunks: z.ZodDefault<z.ZodNumber>;
+        chunkSize: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    limits: z.ZodDefault<z.ZodObject<{
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        callTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxResultBytes: z.ZodDefault<z.ZodNumber>;
+        turnTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentTurnsPerUser: z.ZodDefault<z.ZodNumber>;
+        maxTools: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+type AgentConfigInput = z.input<typeof configSchema>;
+type AgentConfig = z.output<typeof configSchema>;
+/** Validates config; also requires getAuth or anonymous:true (checked by caller with the function in hand). */
+declare function parseConfig(input: unknown, hasGetAuth: boolean, injected?: {
+    model?: boolean;
+    embeddings?: boolean;
+}): AgentConfig;
+
+interface UrlGuardOptions {
+    /** Pinned origin from config. Requests may only go here. */
+    baseUrl: string;
+    allowPrivateNetworks?: boolean;
+}
+/** Throws unless `url` is safe to call under the pinned config. */
+declare function assertAllowedUrl(url: string, opts: UrlGuardOptions): URL;
+
+interface KnowledgeSourceInput {
+    id: string;
+    title: string;
+    content: string;
+}
+interface KnowledgeUrlInput {
+    url: string;
+    title?: string;
+}
+interface KnowledgeOptions {
+    sources: KnowledgeSourceInput[];
+    urls: (string | KnowledgeUrlInput)[];
+    topK: number;
+    ttlMs: number;
+    maxSourceBytes: number;
+    maxChunks: number;
+    chunkSize: number;
+}
+interface ChunkMeta {
+    sourceId: string;
+    title: string;
+    /** Only set for sources that came from a URL listed in config. */
+    url?: string;
+}
+interface StoredChunk {
+    text: string;
+    vector: number[];
+    meta: ChunkMeta;
+}
+interface Hit {
+    text: string;
+    score: number;
+    meta: ChunkMeta;
+}
+/** Plug in your own (pgvector, Vectorize, …). The default is an in-memory cosine store. */
+interface VectorStore {
+    replace(sourceId: string, chunks: StoredChunk[]): Promise<void>;
+    search(vector: number[], k: number): Promise<Hit[]>;
+}
+declare class MemoryVectorStore implements VectorStore {
+    private bySource;
+    replace(sourceId: string, chunks: StoredChunk[]): Promise<void>;
+    search(vector: number[], k: number): Promise<Hit[]>;
+}
+/** Splits markdown/plain text into chunks of roughly `size` chars, keeping the nearest heading as context. */
+declare function chunkText(content: string, size: number): string[];
+/** Dependency-free HTML to text/markdown-ish conversion. Plain text out; never HTML. */
+declare function htmlToText(html: string): {
+    title?: string;
+    text: string;
+};
+interface SourceStatus {
+    id: string;
+    title: string;
+    url?: string;
+    chunks: number;
+    loadedAt?: number;
+    error?: string;
+}
+interface KnowledgeDeps {
+    embedDocuments(texts: string[]): Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+    store?: VectorStore;
+    allowPrivateNetworks?: boolean;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+declare class KnowledgeBase {
+    private opts;
+    private deps;
+    readonly store: VectorStore;
+    private statuses;
+    private refreshing;
+    private lastRefresh;
+    private totalChunks;
+    constructor(opts: KnowledgeOptions, deps: KnowledgeDeps);
+    private now;
+    status(): SourceStatus[];
+    /** Loads every source. Failures are recorded per source and never throw. */
+    load(): Promise<void>;
+    private loadUrls;
+    private ingest;
+    private fetchPage;
+    /** Re-fetches URL sources. Keeps the old data for any source that fails. Concurrent calls share one run. */
+    refresh(): Promise<void>;
+    search(query: string): Promise<Hit[]>;
+}
+
+interface AuditEvent {
+    at: number;
+    userId: string;
+    threadId: string;
+    operationId: string;
+    callId: string;
+    args: unknown;
+    status: "executed" | "rejected" | "denied" | "error";
+    httpStatus?: number;
+    approval: "auto" | "approved" | "rejected";
+    durationMs?: number;
+    error?: string;
+}
+
+/** Index of a user's conversations. The messages themselves live in the LangGraph checkpointer. */
+interface ThreadStore {
+    list(userId: string): Promise<ThreadMeta[]>;
+    has(userId: string, threadId: string): Promise<boolean>;
+    /** Creates the thread with `title` if new, otherwise only bumps `updatedAt`. */
+    touch(userId: string, threadId: string, title: string): Promise<void>;
+    delete(userId: string, threadId: string): Promise<void>;
+}
+/** Per-process store. Use a persistent implementation (SQL, KV, Redis) in production. */
+declare class MemoryThreadStore implements ThreadStore {
+    private users;
+    private of;
+    list(userId: string): Promise<ThreadMeta[]>;
+    has(userId: string, threadId: string): Promise<boolean>;
+    touch(userId: string, threadId: string, title: string): Promise<void>;
+    delete(userId: string, threadId: string): Promise<void>;
+}
+
+interface AuthResult {
+    /** Stable identity of the signed-in user. Threads are bound to it. */
+    userId: string;
+    /** Headers forwarded to your API (e.g. Authorization, Cookie). Never shown to the LLM. */
+    headers?: Record<string, string>;
+}
+/** Same shape as LangChain's Embeddings, minimal so any adapter fits. */
+interface EmbeddingsLike {
+    embedDocuments(texts: string[]): Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+}
+interface CreateAgentOptions extends AgentConfigInput {
+    /** Your own chat model (e.g. workersAiChatModel from sideagent/workers-ai). Use instead of `llm`, never with it. It must support bindTools(). */
+    model?: BaseChatModel;
+    /** Your own embeddings, used instead of knowledge.embeddings. */
+    embeddings?: EmbeddingsLike;
+    getAuth?: (request: Request) => AuthResult | Promise<AuthResult>;
+    /** Throw to reject a turn (rate limiting, quota). */
+    beforeTurn?: (ctx: {
+        request: Request;
+        userId: string;
+    }) => void | Promise<void>;
+    onAudit?: (event: AuditEvent) => void | Promise<void>;
+    checkpointer?: BaseCheckpointSaver;
+    /** Index of each user's conversations (history list). Defaults to in-memory. */
+    threadStore?: ThreadStore;
+    /** Where knowledge embeddings live. Defaults to in-memory (re-embedded on every start). */
+    vectorStore?: VectorStore;
+}
+interface DoctorReport {
+    ok: boolean;
+    checks: {
+        name: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    tools: {
+        operationId: string;
+        method: string;
+        path: string;
+        approval: "required" | "auto";
+    }[];
+    knowledge?: {
+        id: string;
+        title: string;
+        url?: string;
+        chunks: number;
+        error?: string;
+    }[];
+}
+declare function createAgent(options: CreateAgentOptions): Promise<{
+    handler: (request: Request) => Promise<Response>;
+    doctor: () => Promise<DoctorReport>;
+    tools: string[];
+    knowledge: KnowledgeBase | undefined;
+}>;
+type Agent = Awaited<ReturnType<typeof createAgent>>;
+
+/** Next.js App Router: `export const { POST } = nextRoute(agent)` */
+declare function nextRoute(agent: Agent): {
+    POST: (req: Request) => Promise<Response>;
+    OPTIONS: (req: Request) => Promise<Response>;
+};
+/** Hono: `app.on(["POST", "OPTIONS"], "/agent", honoHandler(agent))` */
+declare function honoHandler(agent: Agent): (c: {
+    req: {
+        raw: Request;
+    };
+}) => Promise<Response>;
+/** Express (use express.json() before it): `app.post("/agent", expressHandler(agent))` and `app.options("/agent", expressHandler(agent))` */
+declare function expressHandler(agent: Agent): (req: any, res: any) => Promise<any>;
+
+export { type Agent, type AgentConfig, type AgentConfigInput, type AuditEvent, type AuthResult, type CreateAgentOptions, type DoctorReport, type EmbeddingsLike, KnowledgeBase, type KnowledgeSourceInput, MemoryThreadStore, MemoryVectorStore, type ThreadStore, type VectorStore, assertAllowedUrl, chunkText, configSchema, createAgent, expressHandler, honoHandler, htmlToText, nextRoute, parseConfig };