@agentic-kit/protocol 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @agentic-kit/protocol
+
+The shared protocol kernel for [agentic-kit](https://github.com/constructive-io/agentic-kit).
+
+This package holds the provider-agnostic contracts and helpers that every adapter
+and the top-level `agentic-kit` package build on:
+
+- **Types** — `Context`, `Message`, `AssistantMessage`, `ModelDescriptor`, `Usage`,
+  content blocks, and the provider/stream interfaces.
+- **Event stream** — `EventStream` / `createAssistantMessageEventStream` for
+  incremental assistant responses.
+- **Message helpers** — `createEmptyUsage`, `calculateUsageCost`, `getMessageText`,
+  `normalizeContext`, `createAssistantMessage`.
+- **JSON helpers** — `clone`, `parsePartialJson`, `completePartialJson` for snapshotting
+  and recovering streamed tool-call arguments.
+- **Base URL** — `normalizeBaseUrl`.
+
+It has no runtime dependencies, so a provider adapter (`@agentic-kit/openai`,
+`@agentic-kit/anthropic`, `@agentic-kit/ollama`) can depend on it standalone without
+pulling in the rest of the framework.
+
+---
+
+## Related Constructive Tooling
+
+### 🤖 AI & Agent Development
+
+* [agentic-kit](https://github.com/constructive-io/agentic-kit): **🧰 Provider-agnostic LLM adapter** with streaming and multi-turn support. Swap between Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint.
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/base-url.d.ts

@@ -0,0 +1 @@
+export declare function normalizeBaseUrl(baseUrl: string): string;

package/base-url.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBaseUrl = normalizeBaseUrl;
+function normalizeBaseUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    if (/\/v\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    return `${trimmed}/v1`;
+}

package/esm/base-url.js

@@ -0,0 +1,7 @@
+export function normalizeBaseUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    if (/\/v\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    return `${trimmed}/v1`;
+}

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

@@ -0,0 +1,5 @@
+export * from './base-url.js';
+export * from './event-stream.js';
+export * from './json.js';
+export * from './messages.js';
+export * from './types.js';

package/esm/json.js

@@ -0,0 +1,71 @@
+/** Deep structural clone via JSON round-trip. Used to snapshot streamed messages. */
+export function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Parse JSON that may be truncated mid-stream. Returns `{}` for empty/garbage
+ * input. Attempts a strict parse first, then closes any open strings/brackets
+ * and retries — so partial tool-call arguments deserialize as they arrive.
+ */
+export function parsePartialJson(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return {};
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // continue
+    }
+    const completed = completePartialJson(trimmed);
+    if (!completed) {
+        return {};
+    }
+    try {
+        return JSON.parse(completed);
+    }
+    catch {
+        return {};
+    }
+}
+/** Close any open strings, objects, and arrays so a truncated fragment parses. */
+export function completePartialJson(input) {
+    let output = input;
+    let inString = false;
+    let escaping = false;
+    const stack = [];
+    for (const char of input) {
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaping = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (char === '{') {
+            stack.push('}');
+        }
+        else if (char === '[') {
+            stack.push(']');
+        }
+        else if (char === '}' || char === ']') {
+            stack.pop();
+        }
+    }
+    if (inString) {
+        output += '"';
+    }
+    while (stack.length > 0) {
+        output += stack.pop();
+    }
+    return output;
+}

package/esm/messages.js

@@ -0,0 +1,147 @@
+export function createEmptyUsage() {
+    return {
+        input: 0,
+        output: 0,
+        reasoning: 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;
+}
+export function snapshotUsage(usage) {
+    return { ...usage, cost: { ...usage.cost } };
+}
+export function addUsage(target, delta) {
+    target.input += delta.input;
+    target.output += delta.output;
+    target.reasoning += delta.reasoning;
+    target.cacheRead += delta.cacheRead;
+    target.cacheWrite += delta.cacheWrite;
+    target.totalTokens += delta.totalTokens;
+    target.cost.input += delta.cost.input;
+    target.cost.output += delta.cost.output;
+    target.cost.cacheRead += delta.cost.cacheRead;
+    target.cost.cacheWrite += delta.cost.cacheWrite;
+    target.cost.total += delta.cost.total;
+    return target;
+}
+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/package.json

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

package/esm/types.js

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

package/event-stream.d.ts

@@ -0,0 +1,19 @@
+import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream } from './types.js';
+export declare class EventStream<TEvent, TResult = TEvent> implements AsyncIterable<TEvent> {
+    private readonly isTerminal;
+    private readonly extractResult;
+    private readonly queue;
+    private readonly waiting;
+    private done;
+    private readonly finalResultPromise;
+    private resolveFinalResult;
+    constructor(isTerminal: (event: TEvent) => boolean, extractResult: (event: TEvent) => TResult);
+    push(event: TEvent): void;
+    end(result?: TResult): void;
+    [Symbol.asyncIterator](): AsyncIterator<TEvent>;
+    result(): Promise<TResult>;
+}
+export declare class DefaultAssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> implements AssistantMessageEventStream {
+    constructor();
+}
+export declare function createAssistantMessageEventStream(): DefaultAssistantMessageEventStream;

package/event-stream.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultAssistantMessageEventStream = exports.EventStream = void 0;
+exports.createAssistantMessageEventStream = createAssistantMessageEventStream;
+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;
+    }
+}
+exports.EventStream = EventStream;
+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');
+        });
+    }
+}
+exports.DefaultAssistantMessageEventStream = DefaultAssistantMessageEventStream;
+function createAssistantMessageEventStream() {
+    return new DefaultAssistantMessageEventStream();
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from './base-url.js';
+export * from './event-stream.js';
+export * from './json.js';
+export * from './messages.js';
+export * from './types.js';

package/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base-url.js"), exports);
+__exportStar(require("./event-stream.js"), exports);
+__exportStar(require("./json.js"), exports);
+__exportStar(require("./messages.js"), exports);
+__exportStar(require("./types.js"), exports);

package/json.d.ts

@@ -0,0 +1,11 @@
+import type { JsonValue } from './types.js';
+/** Deep structural clone via JSON round-trip. Used to snapshot streamed messages. */
+export declare function clone<TValue>(value: TValue): TValue;
+/**
+ * Parse JSON that may be truncated mid-stream. Returns `{}` for empty/garbage
+ * input. Attempts a strict parse first, then closes any open strings/brackets
+ * and retries — so partial tool-call arguments deserialize as they arrive.
+ */
+export declare function parsePartialJson(raw: string): Record<string, JsonValue | undefined>;
+/** Close any open strings, objects, and arrays so a truncated fragment parses. */
+export declare function completePartialJson(input: string): string | undefined;

package/json.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clone = clone;
+exports.parsePartialJson = parsePartialJson;
+exports.completePartialJson = completePartialJson;
+/** Deep structural clone via JSON round-trip. Used to snapshot streamed messages. */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Parse JSON that may be truncated mid-stream. Returns `{}` for empty/garbage
+ * input. Attempts a strict parse first, then closes any open strings/brackets
+ * and retries — so partial tool-call arguments deserialize as they arrive.
+ */
+function parsePartialJson(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return {};
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // continue
+    }
+    const completed = completePartialJson(trimmed);
+    if (!completed) {
+        return {};
+    }
+    try {
+        return JSON.parse(completed);
+    }
+    catch {
+        return {};
+    }
+}
+/** Close any open strings, objects, and arrays so a truncated fragment parses. */
+function completePartialJson(input) {
+    let output = input;
+    let inString = false;
+    let escaping = false;
+    const stack = [];
+    for (const char of input) {
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaping = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (char === '{') {
+            stack.push('}');
+        }
+        else if (char === '[') {
+            stack.push(']');
+        }
+        else if (char === '}' || char === ']') {
+            stack.pop();
+        }
+    }
+    if (inString) {
+        output += '"';
+    }
+    while (stack.length > 0) {
+        output += stack.pop();
+    }
+    return output;
+}

package/messages.d.ts

@@ -0,0 +1,33 @@
+import type { AssistantMessage, Context, ImageContent, Message, ModelDescriptor, TextContent, ToolCallContent, ToolResultMessage, Usage, UserMessage } from './types.js';
+export declare function createEmptyUsage(): Usage;
+export declare function calculateUsageCost(model: ModelDescriptor, usage: Usage): void;
+export declare function snapshotUsage(usage: Usage): Usage;
+export declare function addUsage(target: Usage, delta: Usage): Usage;
+export declare function createAssistantMessage(model: ModelDescriptor): AssistantMessage;
+export declare function createTextContent(text?: string): TextContent;
+export declare function createImageContent(data: string, mimeType: string): ImageContent;
+export declare function createToolCall(id: string, name: string): ToolCallContent;
+export declare function createUserMessage(content: UserMessage['content']): UserMessage;
+export declare function createToolResultMessage(toolCallId: string, toolName: string, content: ToolResultMessage['content'], isError?: boolean): ToolResultMessage;
+export declare function getMessageText(message: AssistantMessage): string;
+export interface InjectDeferralResultsOptions {
+    /** Text body for synthesized results. Defaults to a generic continue prompt. */
+    deferralText?: string;
+    /** Stamped onto each synthesized result's `details` field — typically `{ deferred: true }` so renderers can hide a "Done" badge. */
+    details?: unknown;
+}
+/**
+ * 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 declare function injectDeferralResults(messages: Message[], optionsOrText?: InjectDeferralResultsOptions | string): Message[];
+export declare function cloneMessage<TMessage extends Message>(message: TMessage): TMessage;
+export declare function normalizeContext(context: Context): Context;

package/messages.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyUsage = createEmptyUsage;
+exports.calculateUsageCost = calculateUsageCost;
+exports.snapshotUsage = snapshotUsage;
+exports.addUsage = addUsage;
+exports.createAssistantMessage = createAssistantMessage;
+exports.createTextContent = createTextContent;
+exports.createImageContent = createImageContent;
+exports.createToolCall = createToolCall;
+exports.createUserMessage = createUserMessage;
+exports.createToolResultMessage = createToolResultMessage;
+exports.getMessageText = getMessageText;
+exports.injectDeferralResults = injectDeferralResults;
+exports.cloneMessage = cloneMessage;
+exports.normalizeContext = normalizeContext;
+function createEmptyUsage() {
+    return {
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: 0,
+        },
+    };
+}
+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;
+}
+function snapshotUsage(usage) {
+    return { ...usage, cost: { ...usage.cost } };
+}
+function addUsage(target, delta) {
+    target.input += delta.input;
+    target.output += delta.output;
+    target.reasoning += delta.reasoning;
+    target.cacheRead += delta.cacheRead;
+    target.cacheWrite += delta.cacheWrite;
+    target.totalTokens += delta.totalTokens;
+    target.cost.input += delta.cost.input;
+    target.cost.output += delta.cost.output;
+    target.cost.cacheRead += delta.cost.cacheRead;
+    target.cost.cacheWrite += delta.cost.cacheWrite;
+    target.cost.total += delta.cost.total;
+    return target;
+}
+function createAssistantMessage(model) {
+    return {
+        role: 'assistant',
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        content: [],
+        usage: createEmptyUsage(),
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+}
+function createTextContent(text = '') {
+    return { type: 'text', text };
+}
+function createImageContent(data, mimeType) {
+    return { type: 'image', data, mimeType };
+}
+function createToolCall(id, name) {
+    return { type: 'toolCall', id, name, arguments: {}, rawArguments: '' };
+}
+function createUserMessage(content) {
+    return {
+        role: 'user',
+        content,
+        timestamp: Date.now(),
+    };
+}
+function createToolResultMessage(toolCallId, toolName, content, isError = false) {
+    return {
+        role: 'toolResult',
+        toolCallId,
+        toolName,
+        content,
+        isError,
+        timestamp: Date.now(),
+    };
+}
+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)]);
+ */
+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];
+}
+function cloneMessage(message) {
+    return JSON.parse(JSON.stringify(message));
+}
+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/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentic-kit/protocol",
+  "version": "1.1.0",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "Shared protocol kernel (types, event stream, message + JSON helpers) for agentic-kit",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./esm/index.js",
+      "require": "./index.js"
+    }
+  },
+  "homepage": "https://github.com/constructive-io/agentic-kit",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/agentic-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/agentic-kit/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "postbuild": "node ../../scripts/write-esm-package-json.js",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [],
+  "gitHead": "fbf34d1146e8543664d904f75e5b3440f2b1d2a4"
+}

package/types.d.ts

@@ -0,0 +1,232 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+export interface JsonSchema {
+    $id?: string;
+    $ref?: string;
+    additionalProperties?: boolean | JsonSchema;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    const?: JsonValue;
+    default?: JsonValue;
+    description?: string;
+    enum?: JsonValue[];
+    format?: string;
+    items?: JsonSchema | JsonSchema[];
+    maxItems?: number;
+    maxLength?: number;
+    maximum?: number;
+    minItems?: number;
+    minLength?: number;
+    minimum?: number;
+    oneOf?: JsonSchema[];
+    pattern?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    title?: string;
+    type?: string | string[];
+}
+export type InputCapability = 'text' | 'image';
+export interface CostSchedule {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+export interface OpenAICompatibleCompat {
+    maxTokensField?: 'max_completion_tokens' | 'max_tokens';
+    reasoningFormat?: 'none' | 'openai';
+    supportsReasoningEffort?: boolean;
+    supportsStrictToolSchema?: boolean;
+    supportsUsageInStreaming?: boolean;
+    toolCallIdFormat?: 'passthrough' | 'safe64' | 'mistral9';
+    requiresToolResultName?: boolean;
+}
+export interface ModelDescriptor {
+    id: string;
+    name: string;
+    api: string;
+    provider: string;
+    baseUrl: string;
+    input: InputCapability[];
+    reasoning: boolean;
+    tools?: boolean;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    cost?: CostSchedule;
+    headers?: Record<string, string>;
+    compat?: OpenAICompatibleCompat;
+}
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+}
+export interface ToolCallContent {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments: Record<string, JsonValue | undefined>;
+    rawArguments?: string;
+    decision?: unknown;
+}
+export interface Usage {
+    input: number;
+    output: number;
+    reasoning: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = 'stop' | 'length' | 'toolUse' | 'error' | 'aborted';
+export interface UserMessage {
+    role: 'user';
+    content: string | Array<TextContent | ImageContent>;
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: 'assistant';
+    content: Array<TextContent | ThinkingContent | ToolCallContent>;
+    api: string;
+    provider: string;
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
+export interface ToolResultMessage<TDetails = unknown> {
+    role: 'toolResult';
+    toolCallId: string;
+    toolName: string;
+    content: Array<TextContent | ImageContent>;
+    isError: boolean;
+    details?: TDetails;
+    timestamp: number;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+export interface ToolDefinition<TSchema extends JsonSchema = JsonSchema> {
+    name: string;
+    description: string;
+    parameters: TSchema;
+}
+export interface Context {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: ToolDefinition[];
+}
+export type CacheRetention = 'none' | 'short' | 'long';
+export interface StreamOptions {
+    apiKey?: string;
+    cacheRetention?: CacheRetention;
+    headers?: Record<string, string>;
+    maxRetryDelayMs?: number;
+    maxTokens?: number;
+    metadata?: Record<string, JsonValue | undefined>;
+    onPayload?: (payload: unknown) => void;
+    reasoning?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    sessionId?: string;
+    signal?: AbortSignal;
+    temperature?: number;
+}
+export type AssistantMessageEvent = {
+    type: 'start';
+    partial: AssistantMessage;
+} | {
+    type: 'text_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'text_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'text_end';
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_end';
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_end';
+    contentIndex: number;
+    toolCall: ToolCallContent;
+    partial: AssistantMessage;
+} | {
+    type: 'done';
+    reason: Extract<StopReason, 'stop' | 'length' | 'toolUse'>;
+    message: AssistantMessage;
+} | {
+    type: 'error';
+    reason: Extract<StopReason, 'error' | 'aborted'>;
+    error: AssistantMessage;
+};
+export interface ProviderAdapter<TOptions extends StreamOptions = StreamOptions> {
+    api: string;
+    provider: string;
+    createModel?: (modelId: string, overrides?: Partial<ModelDescriptor>) => ModelDescriptor;
+    listModels?: (options?: Pick<StreamOptions, 'apiKey' | 'headers'>) => Promise<Array<ModelDescriptor | string>>;
+    stream: (model: ModelDescriptor, context: Context, options?: TOptions) => AssistantMessageEventStream;
+}
+export interface LegacyChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface LegacyGenerateInput {
+    model: string;
+    prompt?: string;
+    messages?: LegacyChatMessage[];
+    system?: string;
+    stream?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface LegacyStreamingOptions {
+    onChunk?: (chunk: string) => void;
+    onComplete?: () => void;
+    onError?: (error: Error) => void;
+    onStateChange?: (state: string) => void;
+}
+export interface AssistantMessageEventStream extends AsyncIterable<AssistantMessageEvent> {
+    result(): Promise<AssistantMessage>;
+}

package/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });