catelog 1.0.0 → 1.0.2

package/dist/adapters.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Framework Adapters
+ *
+ * Translates framework-specific streaming patterns into the Catelog
+ * task lifecycle contract. Each adapter is a thin transformer that:
+ *
+ * 1. Pipes framework chunks → stream.delta() / stream.progress()
+ * 2. Extracts telemetry (tokens, tool calls) when available
+ * 3. Returns the final result in Catelog's { output, telemetry } format
+ *
+ * All adapters are framework-optional — if the framework library
+ * isn't installed, the adapter gracefully skips enrichment.
+ */
+import type { AgentExecutionResult, AgentStream } from "./types.js";
+/**
+ * Pipes a Vercel AI SDK streamText/generateText result into Catelog events.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * async execute({ input, stream }) {
+ *   const result = streamText({
+ *     model: openai("gpt-4o"),
+ *     prompt: input.prompt,
+ *   });
+ *   return pipeAiSdkStream(result, stream);
+ * }
+ * ```
+ */
+export declare function pipeAiSdkStream(aiResult: any, stream: AgentStream): Promise<AgentExecutionResult>;
+/**
+ * Pipes an OpenAI SDK chat.completions.create({ stream: true }) result.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * const client = new OpenAI();
+ *
+ * async execute({ input, stream }) {
+ *   const openaiStream = await client.chat.completions.create({
+ *     model: "gpt-4o-mini",
+ *     messages: [{ role: "user", content: input.prompt }],
+ *     stream: true,
+ *   });
+ *   return pipeOpenAiStream(openaiStream, stream);
+ * }
+ * ```
+ */
+export declare function pipeOpenAiStream(openaiStream: any, stream: AgentStream): Promise<AgentExecutionResult>;
+/**
+ * Pipes a LangGraph compiled graph's stream into Catelog events.
+ * Translates graph node transitions to progress events and token
+ * deltas to stream chunks.
+ *
+ * @example
+ * ```ts
+ * async execute({ input, stream }) {
+ *   return pipeLangGraphStream(compiledGraph, { input }, stream);
+ * }
+ * ```
+ */
+export declare function pipeLangGraphStream(graph: any, graphInput: Record<string, unknown>, stream: AgentStream, options?: {
+    signal?: AbortSignal;
+}): Promise<AgentExecutionResult>;
+/**
+ * For any framework that produces an async iterable of text chunks
+ * (CrewAI, LlamaIndex, custom generators, etc.)
+ *
+ * @example
+ * ```ts
+ * async execute({ input, stream }) {
+ *   const chunks = myCustomAgentStream(input);
+ *   return pipeAsyncIterableStream(chunks, stream);
+ * }
+ * ```
+ */
+export declare function pipeAsyncIterableStream(iterable: AsyncIterable<string | {
+    text?: string;
+    content?: string;
+    delta?: string;
+}>, stream: AgentStream): Promise<AgentExecutionResult>;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,oBAAoB,CAAC,CAwD/B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,GAAG,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,oBAAoB,CAAC,CAkE/B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAwD/B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,aAAa,CAAC,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrF,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,oBAAoB,CAAC,CAgB/B"}

package/dist/adapters.js

@@ -0,0 +1,267 @@
+/**
+ * Framework Adapters
+ *
+ * Translates framework-specific streaming patterns into the Catelog
+ * task lifecycle contract. Each adapter is a thin transformer that:
+ *
+ * 1. Pipes framework chunks → stream.delta() / stream.progress()
+ * 2. Extracts telemetry (tokens, tool calls) when available
+ * 3. Returns the final result in Catelog's { output, telemetry } format
+ *
+ * All adapters are framework-optional — if the framework library
+ * isn't installed, the adapter gracefully skips enrichment.
+ */
+// ─────────────────────────────────────────────────
+//  Vercel AI SDK Adapter
+// ─────────────────────────────────────────────────
+/**
+ * Pipes a Vercel AI SDK streamText/generateText result into Catelog events.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * async execute({ input, stream }) {
+ *   const result = streamText({
+ *     model: openai("gpt-4o"),
+ *     prompt: input.prompt,
+ *   });
+ *   return pipeAiSdkStream(result, stream);
+ * }
+ * ```
+ */
+export async function pipeAiSdkStream(aiResult, stream) {
+    let fullText = "";
+    const telemetry = { framework: { adapter: "vercel-ai-sdk" } };
+    try {
+        // streamText returns a StreamTextResult with textStream
+        if (aiResult?.textStream && Symbol.asyncIterator in aiResult.textStream) {
+            for await (const chunk of aiResult.textStream) {
+                if (typeof chunk === "string" && chunk.length > 0) {
+                    stream.delta(chunk);
+                    fullText += chunk;
+                }
+            }
+        }
+        // generateText returns a GenerateTextResult with .text
+        else if (typeof aiResult?.text === "string") {
+            fullText = aiResult.text;
+            stream.delta(fullText);
+        }
+        // Fallback: try to iterate directly
+        else if (aiResult && Symbol.asyncIterator in aiResult) {
+            for await (const chunk of aiResult) {
+                const text = typeof chunk === "string" ? chunk : chunk?.textDelta || chunk?.delta || "";
+                if (text) {
+                    stream.delta(text);
+                    fullText += text;
+                }
+            }
+        }
+        // Extract token usage if available
+        if (aiResult?.usage) {
+            telemetry.llm_tokens = {
+                prompt: aiResult.usage.promptTokens ?? aiResult.usage.prompt_tokens,
+                completion: aiResult.usage.completionTokens ?? aiResult.usage.completion_tokens,
+                total: aiResult.usage.totalTokens ?? aiResult.usage.total_tokens,
+            };
+        }
+        // Extract tool calls if present
+        if (aiResult?.toolCalls && Array.isArray(aiResult.toolCalls)) {
+            telemetry.framework = {
+                ...telemetry.framework,
+                tool_calls: aiResult.toolCalls.length,
+                tools_used: aiResult.toolCalls.map((tc) => tc.toolName || tc.name),
+            };
+        }
+    }
+    catch (err) {
+        // Graceful fallback — adapter failures don't crash the agent
+        if (fullText) {
+            return { output: { text: fullText }, telemetry };
+        }
+        throw err;
+    }
+    return { output: { text: fullText }, telemetry };
+}
+// ─────────────────────────────────────────────────
+//  OpenAI SDK Stream Adapter
+// ─────────────────────────────────────────────────
+/**
+ * Pipes an OpenAI SDK chat.completions.create({ stream: true }) result.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * const client = new OpenAI();
+ *
+ * async execute({ input, stream }) {
+ *   const openaiStream = await client.chat.completions.create({
+ *     model: "gpt-4o-mini",
+ *     messages: [{ role: "user", content: input.prompt }],
+ *     stream: true,
+ *   });
+ *   return pipeOpenAiStream(openaiStream, stream);
+ * }
+ * ```
+ */
+export async function pipeOpenAiStream(openaiStream, stream) {
+    let fullText = "";
+    let model;
+    let promptTokens;
+    let completionTokens;
+    const telemetry = { framework: { adapter: "openai" } };
+    try {
+        if (openaiStream && Symbol.asyncIterator in openaiStream) {
+            for await (const chunk of openaiStream) {
+                // Standard OpenAI chat completion chunk
+                const delta = chunk?.choices?.[0]?.delta;
+                if (delta?.content) {
+                    stream.delta(delta.content);
+                    fullText += delta.content;
+                }
+                // Tool calls in streaming mode
+                if (delta?.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        stream.activity("tool_call", {
+                            name: tc.function?.name,
+                            arguments: tc.function?.arguments,
+                        });
+                    }
+                }
+                // Capture model name
+                if (chunk?.model && !model) {
+                    model = chunk.model;
+                }
+                // Usage in final chunk (OpenAI includes this with stream_options: { include_usage: true })
+                if (chunk?.usage) {
+                    promptTokens = chunk.usage.prompt_tokens;
+                    completionTokens = chunk.usage.completion_tokens;
+                }
+            }
+        }
+        // Non-streaming response
+        else if (openaiStream?.choices?.[0]?.message?.content) {
+            fullText = openaiStream.choices[0].message.content;
+            stream.delta(fullText);
+            model = openaiStream.model;
+            if (openaiStream.usage) {
+                promptTokens = openaiStream.usage.prompt_tokens;
+                completionTokens = openaiStream.usage.completion_tokens;
+            }
+        }
+        if (model)
+            telemetry.model_used = model;
+        if (promptTokens !== undefined || completionTokens !== undefined) {
+            telemetry.llm_tokens = {
+                prompt: promptTokens,
+                completion: completionTokens,
+                total: (promptTokens ?? 0) + (completionTokens ?? 0),
+            };
+        }
+    }
+    catch (err) {
+        if (fullText) {
+            return { output: { text: fullText }, telemetry };
+        }
+        throw err;
+    }
+    return { output: { text: fullText }, telemetry };
+}
+// ─────────────────────────────────────────────────
+//  LangGraph / LangChain Adapter
+// ─────────────────────────────────────────────────
+/**
+ * Pipes a LangGraph compiled graph's stream into Catelog events.
+ * Translates graph node transitions to progress events and token
+ * deltas to stream chunks.
+ *
+ * @example
+ * ```ts
+ * async execute({ input, stream }) {
+ *   return pipeLangGraphStream(compiledGraph, { input }, stream);
+ * }
+ * ```
+ */
+export async function pipeLangGraphStream(graph, graphInput, stream, options) {
+    let lastOutput = undefined;
+    let nodeCount = 0;
+    const nodesVisited = [];
+    const telemetry = { framework: { adapter: "langgraph" } };
+    try {
+        // LangGraph .stream() returns an async iterable of state snapshots
+        const streamMethod = graph.stream || graph.streamEvents;
+        if (!streamMethod) {
+            // Fallback: invoke synchronously
+            const result = await graph.invoke(graphInput, { signal: options?.signal });
+            return { output: result, telemetry };
+        }
+        const graphStream = await streamMethod.call(graph, graphInput, {
+            signal: options?.signal,
+            streamMode: "updates",
+        });
+        for await (const event of graphStream) {
+            // Each event is typically { nodeName: nodeOutput }
+            if (typeof event === "object" && event !== null) {
+                for (const [nodeName, nodeOutput] of Object.entries(event)) {
+                    nodeCount++;
+                    nodesVisited.push(nodeName);
+                    stream.activity("graph_node", { node: nodeName, step: nodeCount });
+                    // If node output has messages with content, stream them
+                    if (nodeOutput && typeof nodeOutput === "object") {
+                        const messages = nodeOutput.messages || [];
+                        for (const msg of messages) {
+                            if (msg?.content && typeof msg.content === "string") {
+                                stream.delta(msg.content);
+                            }
+                        }
+                    }
+                    lastOutput = nodeOutput;
+                }
+            }
+        }
+        telemetry.framework = {
+            ...telemetry.framework,
+            nodes_visited: nodesVisited,
+            node_count: nodeCount,
+        };
+    }
+    catch (err) {
+        if (lastOutput) {
+            return { output: lastOutput, telemetry };
+        }
+        throw err;
+    }
+    return { output: (lastOutput ?? {}), telemetry };
+}
+// ─────────────────────────────────────────────────
+//  Generic Async Iterable Adapter
+// ─────────────────────────────────────────────────
+/**
+ * For any framework that produces an async iterable of text chunks
+ * (CrewAI, LlamaIndex, custom generators, etc.)
+ *
+ * @example
+ * ```ts
+ * async execute({ input, stream }) {
+ *   const chunks = myCustomAgentStream(input);
+ *   return pipeAsyncIterableStream(chunks, stream);
+ * }
+ * ```
+ */
+export async function pipeAsyncIterableStream(iterable, stream) {
+    let fullText = "";
+    const telemetry = { framework: { adapter: "generic-iterable" } };
+    for await (const chunk of iterable) {
+        const text = typeof chunk === "string"
+            ? chunk
+            : (chunk?.text || chunk?.content || chunk?.delta || "");
+        if (text) {
+            stream.delta(text);
+            fullText += text;
+        }
+    }
+    return { output: { text: fullText }, telemetry };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}

package/dist/agent.d.ts

@@ -1,38 +1,98 @@
 import { SecurityManager } from "./security.js";
 import { type SchemaLike } from "./schema.js";
-import { type AgentCapabilities, type AgentExecutionContext, type AgentExecutionResult, type AgentManifest, type HealthCheckResponse } from "./types.js";
+import { type AgentCapabilities, type AgentExecutionContext, type AgentExecutionResult, type AgentManifest, type ExecutionMode, type HealthCheckResponse, type NeedInputResult } from "./types.js";
 import { type ServerOptions } from "./server.js";
 import type { IncomingMessage, ServerResponse, Server } from "node:http";
-export interface MarketplaceAgentConfig<TInput = Record<string, unknown>, TOutput = Record<string, unknown>> {
+export interface CatelogAgentConfig<TInput = any, TOutput = any> {
+    /** Unique slug ID (auto-generated from name if omitted) */
     id?: string;
+    /** Human-readable agent name */
     name: string;
+    /** Semantic version (default: "1.0.0") */
     version?: string;
+    /** Short description for marketplace listing */
     description?: string;
-    secret?: string;
+    /**
+     * Secret key for HMAC / Bearer auth.
+     * Auto-reads CATELOG_SECRET_KEY from env if omitted.
+     */
+    secretKey?: string;
+    /**
+     * Publishable key for public endpoints.
+     * Auto-reads CATELOG_PUBLIC_KEY from env if omitted.
+     */
+    publicKey?: string;
+    /**
+     * Execution mode:
+     * - "sync" (default): Direct HTTP/SSE stream, resolves in same connection.
+     * - "async": Returns 202 immediately, polled via GET /tasks/:id.
+     * - "conversational": Supports ctx.needInput() for HITL multi-turn.
+     */
+    mode?: ExecutionMode;
+    /** Partial capabilities overrides */
     capabilities?: Partial<AgentCapabilities>;
-    inputSchema: SchemaLike;
-    outputSchema: SchemaLike;
-    execute: (ctx: AgentExecutionContext<TInput>) => Promise<AgentExecutionResult<TOutput>>;
+    /**
+     * Input schema (Zod or JSON Schema). OPTIONAL — if omitted, accepts any JSON.
+     */
+    inputSchema?: SchemaLike;
+    /**
+     * Output schema (Zod or JSON Schema). OPTIONAL — if omitted, no output validation.
+     */
+    outputSchema?: SchemaLike;
+    /**
+     * The core execution function. This is the ONLY thing the developer MUST provide.
+     *
+     * - Return a value → task completes automatically
+     * - Throw an error → task fails automatically
+     * - Use ctx.needInput() → task suspends for human input
+     * - Use stream.delta() / stream.progress() → real-time events to marketplace
+     */
+    execute: (ctx: AgentExecutionContext<TInput>) => Promise<AgentExecutionResult<TOutput> | NeedInputResult | TOutput>;
+    /** Optional telemetry reporting config */
+    telemetry?: {
+        endpoint?: string;
+        disabled?: boolean;
+    };
 }
-export declare class MarketplaceAgent<TInput = Record<string, unknown>, TOutput = Record<string, unknown>> {
+export declare class CatelogAgent<TInput = any, TOutput = any> {
     readonly id: string;
     readonly name: string;
     readonly version: string;
     readonly description: string;
+    readonly mode: ExecutionMode;
     readonly capabilities: AgentCapabilities;
     readonly security: SecurityManager;
     private readonly config;
     private readonly startTime;
-    constructor(config: MarketplaceAgentConfig<TInput, TOutput>);
+    private readonly telemetryReporter;
+    constructor(config: CatelogAgentConfig<TInput, TOutput>);
     getHealth(): HealthCheckResponse;
     getManifest(): AgentManifest;
+    listen(portOrOptions?: number | ServerOptions): Server;
+    /** Alias for backward compat */
     serve(portOrOptions?: number | ServerOptions): Server;
     handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
     private handleExecute;
-    private writeJsonResponse;
+    private executeAsync;
+    private executeSyncOrConversational;
+    private executeWithSSE;
+    private executeWithJSON;
+    private handleTaskPoll;
+    /**
+     * Normalize the developer's return value into our standard result shape.
+     * Supports:
+     * - { output: T, telemetry?: ... } → standard result
+     * - Any other value → treated as the output directly
+     */
+    private normalizeExecuteResult;
+    private isNeedInputResult;
+    private reportTelemetry;
+    private writeJson;
 }
-/**
- * Convenience builder function for creating a compliant Marketplace Agent
- */
-export declare function createMarketplaceAgent<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(config: MarketplaceAgentConfig<TInput, TOutput>): MarketplaceAgent<TInput, TOutput>;
+/** Create a new CatelogAgent */
+export declare function createAgent<TInput = any, TOutput = any>(config: CatelogAgentConfig<TInput, TOutput>): CatelogAgent<TInput, TOutput>;
+/** Legacy alias */
+export declare function createMarketplaceAgent<TInput = any, TOutput = any>(config: CatelogAgentConfig<TInput, TOutput>): CatelogAgent<TInput, TOutput>;
+export { CatelogAgent as MarketplaceAgent };
+export type { CatelogAgentConfig as MarketplaceAgentConfig };
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAGlB,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEzE,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,OAAO,EAAE,CAAC,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;CACzF;AAED,qBAAa,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/F,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,YAAY,EAAE,iBAAiB,CAAC;IAChD,SAAgB,QAAQ,EAAE,eAAe,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC;IAgBpD,SAAS,IAAI,mBAAmB;IAShC,WAAW,IAAI,aAAa;IAa5B,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM;IAK/C,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;YAkDtE,aAAa;IAoK3B,OAAO,CAAC,iBAAiB;CAS1B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxG,MAAM,EAAE,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}