agentic-kit 1.0.3 → 1.2.0

package/README.md

@@ -12,7 +12,14 @@
    <a href="https://www.npmjs.com/package/agentic-kit"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/agentic-kit?filename=packages%2Fagentic-kit%2Fpackage.json"/></a>
 </p>
 
-A unified, streaming-capable interface for multiple LLM providers. Plug in any supported adapter and swap between them at runtime.
+A low-level provider portability layer for LLM applications. `agentic-kit`
+provides:
+
+- provider-independent `ModelDescriptor` and `Context` types
+- structured streaming events for text, reasoning, and tool calls
+- model and provider registries
+- cross-provider message normalization for replay and handoff
+- a one-release compatibility wrapper for the legacy `AgentKit.generate()` API
 
 ## Installation
 
@@ -23,58 +30,94 @@ npm install agentic-kit
 
 ## Quick Start
 
+### Structured API
+
 ```typescript
-import { createOllamaKit, createMultiProviderKit, OllamaAdapter, AgentKit } from 'agentic-kit';
+import { complete, getModel } from 'agentic-kit';
 
-// Ollama
-const kit = createOllamaKit('http://localhost:11434');
-const text = await kit.generate({ model: 'mistral', prompt: 'Hello' });
+const model = getModel('openai', 'gpt-4o-mini');
+const message = await complete(model!, {
+  messages: [{ role: 'user', content: 'Hello', timestamp: Date.now() }],
+});
 
-// Multi-provider with fallback
-const multi = createMultiProviderKit();
-multi.addProvider(new OllamaAdapter('http://localhost:11434'));
-const reply = await multi.generate({ model: 'mistral', prompt: 'Hello' });
+console.log(message.content);
 ```
 
-## Streaming
+### Streaming
 
 ```typescript
-await kit.generate(
-  { model: 'mistral', prompt: 'Hello', stream: true },
-  { onChunk: (chunk) => process.stdout.write(chunk) }
-);
+import { stream, getModel } from 'agentic-kit';
+
+const model = getModel('openai', 'gpt-4o-mini');
+const result = stream(model!, {
+  messages: [{ role: 'user', content: 'Explain tool calling briefly.', timestamp: Date.now() }],
+});
+
+for await (const event of result) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta);
+  }
+}
 ```
 
 ## API Reference
 
-### `AgentKit`
+### Core API
+
+- `stream(model: ModelDescriptor, context: Context, options?: StreamOptions)`
+- `complete(model: ModelDescriptor, context: Context, options?: StreamOptions)`
+- `completeText(model: ModelDescriptor, context: Context, options?: StreamOptions)`
+
+### Registry
+
+- `registerModel(model)`, `registerModels(models)`, `clearModels()`
+- `registerProvider(provider, sourceId?)`, `unregisterProviders(sourceId)`, `clearProviders()`
+- `getModel(provider, modelId)`, `getModels(provider?)`, `getModelProviders()`
+- `getProvider(api)`, `getRegisteredProviders()`
+
+The package pre-registers `OpenAIAdapter`, `AnthropicAdapter`, and
+`OllamaAdapter` (with empty credentials) plus the built-in model catalogs
+from each adapter package. Re-register an adapter with your own API key to
+activate it.
 
-- `.generate(input: GenerateInput, options?: StreamingOptions): Promise<string | void>`
-- `.addProvider(provider: AgentProvider): void`
-- `.setProvider(name: string): void`
-- `.listProviders(): string[]`
-- `.getCurrentProvider(): AgentProvider | undefined`
+### Message helpers
 
-### `GenerateInput`
+- `createUserMessage(content)`, `createAssistantMessage(model)`,
+  `createToolResultMessage(toolCallId, toolName, content, isError?)`
+- `createTextContent(text?)`, `createImageContent(data, mimeType)`,
+  `createToolCall(id, name)`
+- `getMessageText(assistant)` — concatenate text blocks.
+- `cloneMessage(message)` — deep clone.
+- `normalizeContext(context)` — apply per-message normalization.
+- `injectDeferralResults(messages, options?)` — synthesize stand-in
+  `toolResult` messages for every `toolCall` that lacks both a decision and
+  a paired result. Useful when the user types a new message instead of
+  responding to a paused tool — the next request needs a well-formed
+  transcript.
+- `transformMessages(messages, model)` — cross-provider normalization for
+  replay across different providers.
+
+### Adapter re-exports
+
+- `OpenAIAdapter`, `AnthropicAdapter`, `OllamaAdapter`
+- Types: `OpenAIOptions`, `AnthropicOptions`
+- `OllamaClient` for direct Ollama HTTP access.
+
+### Legacy Compatibility API
+
+`AgentKit` is still available for one transition release:
 
 ```ts
 interface GenerateInput {
   model: string;
-  prompt: string;
+  prompt?: string;
+  messages?: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>;
   stream?: boolean;
 }
 ```
 
-### `StreamingOptions`
-
-```ts
-interface StreamingOptions {
-  onChunk?: (chunk: string) => void;
-  onStateChange?: (state: string) => void;
-  onError?: (error: Error) => void;
-  onComplete?: () => void;
-}
-```
+Use `createOpenAIKit`, `createAnthropicKit`, `createOllamaKit`, or
+`createMultiProviderKit()` if you still need the old prompt-only entrypoint.
 
 ---
 

package/esm/event-stream.js

@@ -0,0 +1,77 @@
+export class EventStream {
+    isTerminal;
+    extractResult;
+    queue = [];
+    waiting = [];
+    done = false;
+    finalResultPromise;
+    resolveFinalResult;
+    constructor(isTerminal, extractResult) {
+        this.isTerminal = isTerminal;
+        this.extractResult = extractResult;
+        this.finalResultPromise = new Promise((resolve) => {
+            this.resolveFinalResult = resolve;
+        });
+    }
+    push(event) {
+        if (this.done) {
+            return;
+        }
+        if (this.isTerminal(event)) {
+            this.done = true;
+            this.resolveFinalResult(this.extractResult(event));
+        }
+        const waiter = this.waiting.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+            return;
+        }
+        this.queue.push(event);
+    }
+    end(result) {
+        this.done = true;
+        if (result !== undefined) {
+            this.resolveFinalResult(result);
+        }
+        while (this.waiting.length > 0) {
+            this.waiting.shift()({ value: undefined, done: true });
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.queue.length > 0) {
+                yield this.queue.shift();
+                continue;
+            }
+            if (this.done) {
+                return;
+            }
+            const next = await new Promise((resolve) => {
+                this.waiting.push(resolve);
+            });
+            if (next.done) {
+                return;
+            }
+            yield next.value;
+        }
+    }
+    result() {
+        return this.finalResultPromise;
+    }
+}
+export class DefaultAssistantMessageEventStream extends EventStream {
+    constructor() {
+        super((event) => event.type === 'done' || event.type === 'error', (event) => {
+            if (event.type === 'done') {
+                return event.message;
+            }
+            if (event.type === 'error') {
+                return event.error;
+            }
+            throw new Error('Unexpected terminal event');
+        });
+    }
+}
+export function createAssistantMessageEventStream() {
+    return new DefaultAssistantMessageEventStream();
+}

package/esm/index.js

@@ -1,74 +1,109 @@
-import OllamaClient from '@agentic-kit/ollama';
-import { AnthropicAdapter } from '@agentic-kit/anthropic';
-import { OpenAIAdapter } from '@agentic-kit/openai';
-export { OllamaClient };
-export { AnthropicAdapter };
-export { OpenAIAdapter };
-// ─── Ollama Adapter ───────────────────────────────────────────────────────────
-export class OllamaAdapter {
-    name = 'ollama';
-    client;
-    constructor(baseUrl) {
-        this.client = new OllamaClient(baseUrl);
-    }
-    async generate(input) {
-        return this.client.generate(input);
-    }
-    async generateStreaming(input, onChunk) {
-        return this.client.generate(input, onChunk);
-    }
-    async listModels() {
-        return this.client.listModels();
+import { ANTHROPIC_MODELS, AnthropicAdapter } from '@agentic-kit/anthropic';
+import { OLLAMA_MODELS, OllamaAdapter, OllamaClient } from '@agentic-kit/ollama';
+import { OPENAI_COMPATIBLE_MODELS, OpenAIAdapter, } from '@agentic-kit/openai';
+import { createAssistantMessageEventStream, EventStream } from './event-stream.js';
+import { getMessageText, normalizeContext } from './messages.js';
+import { clearModels, getModel, getModels, getProviders as getModelProviders, registerModel, registerModels, } from './model-registry.js';
+import { clearProviders, getProvider as getRegisteredProvider, getProviders as getRegisteredProviders, registerProvider, unregisterProviders, } from './provider-registry.js';
+import { transformMessages } from './transform-messages.js';
+export * from './event-stream.js';
+export * from './messages.js';
+export * from './transform-messages.js';
+export * from './types.js';
+export { createAssistantMessageEventStream, EventStream, OllamaClient };
+export { AnthropicAdapter, OllamaAdapter, OpenAIAdapter };
+registerModels([...OPENAI_COMPATIBLE_MODELS, ...ANTHROPIC_MODELS, ...OLLAMA_MODELS]);
+registerProvider(new OpenAIAdapter());
+registerProvider(new AnthropicAdapter({ apiKey: '' }));
+registerProvider(new OllamaAdapter());
+export function stream(model, context, options) {
+    const provider = getRegisteredProvider(model.api);
+    if (!provider) {
+        throw new Error(`No provider registered for api '${model.api}'`);
     }
+    return streamWithProvider(provider, model, context, options);
+}
+export async function complete(model, context, options) {
+    const response = stream(model, context, options);
+    return response.result();
+}
+export async function completeText(model, context, options) {
+    const message = await complete(model, context, options);
+    return getMessageText(message);
 }
-// ─── AgentKit ─────────────────────────────────────────────────────────────────
 export class AgentKit {
     providers = new Map();
     current;
     addProvider(provider) {
-        this.providers.set(provider.name, provider);
-        if (!this.current)
+        this.providers.set(getProviderName(provider), provider);
+        if (!this.current) {
             this.current = provider;
+        }
         return this;
     }
     setProvider(name) {
         const provider = this.providers.get(name);
-        if (!provider)
+        if (!provider) {
             throw new Error(`Provider '${name}' not found`);
+        }
         this.current = provider;
         return this;
     }
-    getCurrentProvider() { return this.current; }
-    listProviders() { return Array.from(this.providers.keys()); }
+    getCurrentProvider() {
+        return this.current;
+    }
+    listProviders() {
+        return Array.from(this.providers.keys());
+    }
     async generate(input, options) {
-        if (!this.current)
+        if (!this.current) {
             throw new Error('No provider set. Call addProvider() first.');
-        if (options?.onChunk) {
+        }
+        const provider = this.current;
+        const model = createLegacyModel(provider, input.model, input.maxTokens);
+        const context = legacyInputToContext(input);
+        const streamOptions = {
+            maxTokens: input.maxTokens,
+            temperature: input.temperature,
+        };
+        if (options?.onChunk || input.stream) {
+            options?.onStateChange?.('streaming');
             try {
-                await this.current.generateStreaming(input, options.onChunk);
-                options.onComplete?.();
+                const response = streamWithProvider(provider, model, context, streamOptions);
+                for await (const event of response) {
+                    if (event.type === 'text_delta') {
+                        options?.onChunk?.(event.delta);
+                    }
+                }
+                assertLegacyGenerateSucceeded(await response.result());
+                options?.onComplete?.();
             }
-            catch (err) {
-                options.onError?.(err);
-                throw err;
+            catch (error) {
+                options?.onError?.(error);
+                throw error;
             }
             return;
         }
         try {
-            const result = await this.current.generate(input);
+            const message = assertLegacyGenerateSucceeded(await completeWithProvider(provider, model, context, streamOptions));
+            options?.onStateChange?.('complete');
+            const text = getMessageText(message);
             options?.onComplete?.();
-            return result;
+            return text;
         }
-        catch (err) {
-            options?.onError?.(err);
-            throw err;
+        catch (error) {
+            options?.onError?.(error);
+            throw error;
         }
     }
     async listModels() {
-        return this.current?.listModels?.() ?? [];
+        if (!this.current?.listModels) {
+            return [];
+        }
+        const models = await this.current.listModels();
+        return models.map((model) => (typeof model === 'string' ? model : model.id));
     }
 }
-// ─── Factory helpers ──────────────────────────────────────────────────────────
 export function createOllamaKit(baseUrl) {
     return new AgentKit().addProvider(new OllamaAdapter(baseUrl));
 }
@@ -81,3 +116,78 @@ export function createOpenAIKit(options) {
 export function createMultiProviderKit() {
     return new AgentKit();
 }
+export { clearModels, clearProviders, getModel, getModelProviders, getModels, getRegisteredProvider as getProvider, getRegisteredProviders, registerModel, registerModels, registerProvider, unregisterProviders, };
+function legacyInputToContext(input) {
+    const messages = input.messages
+        ? input.messages
+            .filter((message) => message.role !== 'system')
+            .map((message) => message.role === 'assistant'
+            ? {
+                role: 'assistant',
+                api: 'legacy',
+                provider: 'legacy',
+                model: input.model,
+                content: [{ type: 'text', text: message.content }],
+                usage: {
+                    input: 0,
+                    output: 0,
+                    cacheRead: 0,
+                    cacheWrite: 0,
+                    totalTokens: 0,
+                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+                },
+                stopReason: 'stop',
+                timestamp: Date.now(),
+            }
+            : {
+                role: 'user',
+                content: message.content,
+                timestamp: Date.now(),
+            })
+        : [{ role: 'user', content: input.prompt ?? '', timestamp: Date.now() }];
+    const systemPrompt = input.system ?? input.messages?.find((message) => message.role === 'system')?.content;
+    return {
+        systemPrompt,
+        messages,
+    };
+}
+function createLegacyModel(provider, modelId, maxTokens) {
+    if (provider.createModel) {
+        return provider.createModel(modelId, {
+            maxOutputTokens: maxTokens,
+        });
+    }
+    return {
+        id: modelId,
+        name: modelId,
+        api: provider.api,
+        provider: getProviderName(provider),
+        baseUrl: '',
+        input: ['text'],
+        reasoning: false,
+        tools: true,
+        maxOutputTokens: maxTokens,
+    };
+}
+function streamWithProvider(provider, model, context, options) {
+    const normalized = normalizeContext(context);
+    const transformedContext = {
+        ...normalized,
+        messages: transformMessages(normalized.messages, model),
+    };
+    return provider.stream(model, transformedContext, options);
+}
+async function completeWithProvider(provider, model, context, options) {
+    const response = streamWithProvider(provider, model, context, options);
+    return response.result();
+}
+function getProviderName(provider) {
+    return provider.name ?? provider.provider;
+}
+function assertLegacyGenerateSucceeded(message) {
+    if (message.stopReason === 'error' || message.stopReason === 'aborted') {
+        throw new Error(message.errorMessage ??
+            (message.stopReason === 'aborted' ? 'Generation aborted.' : 'Generation failed.'), { cause: message });
+    }
+    return message;
+}

package/esm/messages.js

@@ -0,0 +1,130 @@
+export function createEmptyUsage() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: 0,
+        },
+    };
+}
+export function calculateUsageCost(model, usage) {
+    const schedule = model.cost;
+    usage.cost.input = ((schedule?.input ?? 0) / 1_000_000) * usage.input;
+    usage.cost.output = ((schedule?.output ?? 0) / 1_000_000) * usage.output;
+    usage.cost.cacheRead = ((schedule?.cacheRead ?? 0) / 1_000_000) * usage.cacheRead;
+    usage.cost.cacheWrite = ((schedule?.cacheWrite ?? 0) / 1_000_000) * usage.cacheWrite;
+    usage.cost.total =
+        usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+    return usage.cost;
+}
+export function createAssistantMessage(model) {
+    return {
+        role: 'assistant',
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        content: [],
+        usage: createEmptyUsage(),
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+}
+export function createTextContent(text = '') {
+    return { type: 'text', text };
+}
+export function createImageContent(data, mimeType) {
+    return { type: 'image', data, mimeType };
+}
+export function createToolCall(id, name) {
+    return { type: 'toolCall', id, name, arguments: {}, rawArguments: '' };
+}
+export function createUserMessage(content) {
+    return {
+        role: 'user',
+        content,
+        timestamp: Date.now(),
+    };
+}
+export function createToolResultMessage(toolCallId, toolName, content, isError = false) {
+    return {
+        role: 'toolResult',
+        toolCallId,
+        toolName,
+        content,
+        isError,
+        timestamp: Date.now(),
+    };
+}
+export function getMessageText(message) {
+    return message.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+}
+const DEFAULT_DEFERRAL_TEXT = 'User did not respond. Continue.';
+/**
+ * Synthesize toolResult messages for every toolCall that lacks both a decision
+ * and a paired toolResult. Returns input unchanged (referentially equal) when
+ * nothing needs synthesizing.
+ *
+ * Use case: user types a message instead of clicking approve/deny on a paused
+ * tool. The agent can't resume on text alone — every dangling toolCall needs
+ * a result before the next request. Compose with sendMessages to forward the
+ * conversation cleanly:
+ *
+ *   await sendMessages([...injectDeferralResults(messages), createUserMessage(text)]);
+ */
+export function injectDeferralResults(messages, optionsOrText = {}) {
+    const opts = typeof optionsOrText === 'string' ? { deferralText: optionsOrText } : optionsOrText;
+    const deferralText = opts.deferralText ?? DEFAULT_DEFERRAL_TEXT;
+    const completed = new Set();
+    for (const m of messages) {
+        if (m.role === 'toolResult')
+            completed.add(m.toolCallId);
+    }
+    const synthetic = [];
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        for (const block of m.content) {
+            if (block.type !== 'toolCall')
+                continue;
+            if (completed.has(block.id))
+                continue;
+            if ('decision' in block && block.decision !== undefined)
+                continue;
+            const result = createToolResultMessage(block.id, block.name, [
+                { type: 'text', text: deferralText },
+            ]);
+            if (opts.details !== undefined)
+                result.details = opts.details;
+            synthetic.push(result);
+        }
+    }
+    if (synthetic.length === 0)
+        return messages;
+    return [...messages, ...synthetic];
+}
+export function cloneMessage(message) {
+    return JSON.parse(JSON.stringify(message));
+}
+export function normalizeContext(context) {
+    return {
+        systemPrompt: context.systemPrompt,
+        tools: context.tools ?? [],
+        messages: context.messages.map((message) => ensureTimestamp(cloneMessage(message))),
+    };
+}
+function ensureTimestamp(message) {
+    if (typeof message.timestamp !== 'number') {
+        message.timestamp = Date.now();
+    }
+    return message;
+}

package/esm/model-registry.js

@@ -0,0 +1,26 @@
+const modelsByProvider = new Map();
+export function registerModel(model) {
+    const providerModels = modelsByProvider.get(model.provider) ?? new Map();
+    providerModels.set(model.id, model);
+    modelsByProvider.set(model.provider, providerModels);
+}
+export function registerModels(models) {
+    for (const model of models) {
+        registerModel(model);
+    }
+}
+export function getModel(provider, modelId) {
+    return modelsByProvider.get(provider)?.get(modelId);
+}
+export function getModels(provider) {
+    if (provider) {
+        return Array.from(modelsByProvider.get(provider)?.values() ?? []);
+    }
+    return Array.from(modelsByProvider.values()).flatMap((entries) => Array.from(entries.values()));
+}
+export function getProviders() {
+    return Array.from(modelsByProvider.keys());
+}
+export function clearModels() {
+    modelsByProvider.clear();
+}

package/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/esm/provider-registry.js

@@ -0,0 +1,20 @@
+const providersByApi = new Map();
+export function registerProvider(adapter, sourceId) {
+    providersByApi.set(adapter.api, { adapter, sourceId });
+}
+export function getProvider(api) {
+    return providersByApi.get(api)?.adapter;
+}
+export function getProviders() {
+    return Array.from(providersByApi.values(), (entry) => entry.adapter);
+}
+export function unregisterProviders(sourceId) {
+    for (const [api, entry] of providersByApi.entries()) {
+        if (entry.sourceId === sourceId) {
+            providersByApi.delete(api);
+        }
+    }
+}
+export function clearProviders() {
+    providersByApi.clear();
+}