sideagent 0.3.0 → 0.5.0

package/dist/keys.d.ts

@@ -0,0 +1,16 @@
+type KeyEnvironment = "test" | "live";
+interface PublishableKeyParts {
+    environment: KeyEnvironment;
+    /** host[:port], no scheme. */
+    host: string;
+    agentId: string;
+}
+/** Request header that carries the publishable key. Authorization stays free for the user's token. */
+declare const PUBLISHABLE_KEY_HEADER = "x-sideagent-key";
+declare function publishableKey(environment: KeyEnvironment, host: string, agentId: string): string;
+/** The key's parts, or null when it is not a well-formed publishable key. */
+declare function parsePublishableKey(key: string): PublishableKeyParts | null;
+/** The agent's data-plane URL. https, except http for localhost and 127.0.0.1 (local development). */
+declare function publishableEndpoint({ host, agentId }: PublishableKeyParts): string;
+
+export { type KeyEnvironment, PUBLISHABLE_KEY_HEADER, type PublishableKeyParts, parsePublishableKey, publishableEndpoint, publishableKey };

package/dist/keys.js

@@ -0,0 +1,12 @@
+import {
+  PUBLISHABLE_KEY_HEADER,
+  parsePublishableKey,
+  publishableEndpoint,
+  publishableKey
+} from "./chunk-73FXXOAR.js";
+export {
+  PUBLISHABLE_KEY_HEADER,
+  parsePublishableKey,
+  publishableEndpoint,
+  publishableKey
+};

package/dist/server/index.d.ts

@@ -1,8 +1,12 @@
 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';
+import { BaseStore, BaseCheckpointSaver } from '@langchain/langgraph';
+import { Document } from '@langchain/core/documents';
+import { EmbeddingsInterface } from '@langchain/core/embeddings';
+import { VectorStore, VectorStoreInterface } from '@langchain/core/vectorstores';
+export { VectorStoreInterface as VectorStore } from '@langchain/core/vectorstores';
 
 declare const configSchema: z.ZodObject<{
     spec: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
@@ -65,6 +69,46 @@ interface UrlGuardOptions {
 /** Throws unless `url` is safe to call under the pinned config. */
 declare function assertAllowedUrl(url: string, opts: UrlGuardOptions): URL;
 
+interface ChunkMeta {
+    sourceId: string;
+    title: string;
+    /** Only set for sources that came from a URL listed in config. */
+    url?: string;
+}
+interface Hit {
+    text: string;
+    score: number;
+    meta: ChunkMeta;
+}
+
+/** Default store: cosine similarity over everything in process memory. */
+declare class MemoryVectorStore extends VectorStore {
+    FilterType: object;
+    lc_namespace: string[];
+    private rows;
+    constructor(embeddings: EmbeddingsInterface);
+    _vectorstoreType(): string;
+    addVectors(vectors: number[][], documents: Document[], options?: {
+        ids?: string[];
+    }): Promise<string[]>;
+    addDocuments(documents: Document[], options?: {
+        ids?: string[];
+    }): Promise<string[]>;
+    delete(params?: {
+        ids?: string[];
+    }): Promise<void>;
+    similaritySearchVectorWithScore(query: number[], k: number): Promise<[Document, number][]>;
+}
+
+/** Splits markdown/plain text into chunks of at most about `size` chars, each prefixed with its nearest heading. */
+declare function chunkText(content: string, size: number): Promise<string[]>;
+
+/** HTML to text/markdown-ish conversion on a real parser. Plain text out; never HTML. */
+declare function htmlToText(html: string): {
+    title?: string;
+    text: string;
+};
+
 interface KnowledgeSourceInput {
     id: string;
     title: string;
@@ -83,39 +127,6 @@ interface KnowledgeOptions {
     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;
@@ -127,7 +138,7 @@ interface SourceStatus {
 interface KnowledgeDeps {
     embedDocuments(texts: string[]): Promise<number[][]>;
     embedQuery(text: string): Promise<number[]>;
-    store?: VectorStore;
+    store?: VectorStoreInterface;
     allowPrivateNetworks?: boolean;
     fetch?: typeof fetch;
     now?: () => number;
@@ -135,8 +146,10 @@ interface KnowledgeDeps {
 declare class KnowledgeBase {
     private opts;
     private deps;
-    readonly store: VectorStore;
+    readonly store: VectorStoreInterface;
     private statuses;
+    /** Chunk ids currently stored per source, so a refresh can drop the ones that disappeared. */
+    private chunkIds;
     private refreshing;
     private lastRefresh;
     private totalChunks;
@@ -147,12 +160,33 @@ declare class KnowledgeBase {
     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 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;
+    }[];
+}
+
 interface AuditEvent {
     at: number;
     userId: string;
@@ -184,6 +218,20 @@ declare class MemoryThreadStore implements ThreadStore {
     touch(userId: string, threadId: string, title: string): Promise<void>;
     delete(userId: string, threadId: string): Promise<void>;
 }
+/**
+ * Thread index on any LangGraph `BaseStore` (Postgres, Redis, …), so one store can serve the checkpointer
+ * ecosystem and the thread list. Keeps at most 200 threads per user, like `MemoryThreadStore`.
+ */
+declare class LangGraphThreadStore implements ThreadStore {
+    private store;
+    constructor(store: BaseStore);
+    private ns;
+    private all;
+    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. */
@@ -191,11 +239,13 @@ interface AuthResult {
     /** 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;
@@ -212,28 +262,7 @@ interface CreateAgentOptions extends AgentConfigInput {
     /** 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;
-    }[];
+    vectorStore?: VectorStoreInterface;
 }
 declare function createAgent(options: CreateAgentOptions): Promise<{
     handler: (request: Request) => Promise<Response>;
@@ -257,4 +286,4 @@ declare function honoHandler(agent: Agent): (c: {
 /** 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 };
+export { type Agent, type AgentConfig, type AgentConfigInput, type AuditEvent, type AuthResult, type CreateAgentOptions, type DoctorReport, type EmbeddingsLike, KnowledgeBase, type KnowledgeSourceInput, LangGraphThreadStore, MemoryThreadStore, MemoryVectorStore, type ThreadStore, assertAllowedUrl, chunkText, configSchema, createAgent, expressHandler, honoHandler, htmlToText, nextRoute, parseConfig };