feat(protocol): add zero-dep @agentic-kit/protocol kernel package

Extract the shared protocol kernel — types, EventStream, and the
usage/message/JSON/base-url helpers — into a standalone leaf package
with no runtime dependencies, so every provider adapter can depend on it
without pulling in the framework. Establishes a single source of truth
for the contract that was previously copy-pasted across packages.

Author: yyyyaaa

packages/protocol/README.md

@@ -0,0 +1,20 @@
+# @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.

packages/protocol/__tests__/protocol.test.ts

@@ -0,0 +1,94 @@
+import {
+  type AssistantMessage,
+  calculateUsageCost,
+  clone,
+  completePartialJson,
+  createAssistantMessageEventStream,
+  createEmptyUsage,
+  type ModelDescriptor,
+  normalizeBaseUrl,
+  parsePartialJson,
+} from '../src/index.js';
+
+const model: ModelDescriptor = {
+  id: 'test-model',
+  name: 'Test',
+  api: 'test-api',
+  provider: 'test',
+  baseUrl: 'https://example.com/v1',
+  input: ['text'],
+  reasoning: false,
+  cost: { input: 3, output: 15 },
+};
+
+describe('protocol kernel', () => {
+  it('createEmptyUsage produces a fully zeroed usage', () => {
+    expect(createEmptyUsage()).toEqual({
+      input: 0,
+      output: 0,
+      reasoning: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    });
+  });
+
+  it('calculateUsageCost applies the per-million schedule', () => {
+    const usage = createEmptyUsage();
+    usage.input = 1_000_000;
+    usage.output = 2_000_000;
+    calculateUsageCost(model, usage);
+    expect(usage.cost.input).toBeCloseTo(3);
+    expect(usage.cost.output).toBeCloseTo(30);
+    expect(usage.cost.total).toBeCloseTo(33);
+  });
+
+  it('parsePartialJson recovers truncated tool arguments', () => {
+    expect(parsePartialJson('{"city": "Paris')).toEqual({ city: 'Paris' });
+    expect(parsePartialJson('{"items": [1, 2')).toEqual({ items: [1, 2] });
+    expect(parsePartialJson('')).toEqual({});
+  });
+
+  it('completePartialJson closes open brackets and strings', () => {
+    expect(completePartialJson('{"a": [1, {"b": "x')).toBe('{"a": [1, {"b": "x"}]}');
+  });
+
+  it('normalizeBaseUrl appends /v1 only when no version segment is present', () => {
+    expect(normalizeBaseUrl('https://example.com')).toBe('https://example.com/v1');
+    expect(normalizeBaseUrl('https://example.com/v1')).toBe('https://example.com/v1');
+    expect(normalizeBaseUrl('https://example.com/v2/')).toBe('https://example.com/v2');
+  });
+
+  it('clone deep-copies without sharing references', () => {
+    const source = { a: { b: 1 }, list: [1, 2, 3] };
+    const copy = clone(source);
+    expect(copy).toEqual(source);
+    expect(copy.a).not.toBe(source.a);
+  });
+
+  it('EventStream yields events in order and resolves the terminal result', async () => {
+    const stream = createAssistantMessageEventStream();
+    const message: AssistantMessage = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'hi' }],
+      api: model.api,
+      provider: model.provider,
+      model: model.id,
+      usage: createEmptyUsage(),
+      stopReason: 'stop',
+      timestamp: Date.now(),
+    };
+
+    stream.push({ type: 'start', partial: message });
+    stream.push({ type: 'done', reason: 'stop', message });
+    stream.end(message);
+
+    const seen: string[] = [];
+    for await (const event of stream) {
+      seen.push(event.type);
+    }
+    expect(seen).toEqual(['start', 'done']);
+    await expect(stream.result()).resolves.toBe(message);
+  });
+});

packages/protocol/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "..",
+    "types": ["jest", "node"]
+  },
+  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "exclude": ["../dist", "../node_modules"]
+}

packages/protocol/jest.config.js

@@ -0,0 +1,21 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: '__tests__/tsconfig.json',
+      },
+    ],
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1'
+  }
+};

packages/protocol/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentic-kit/protocol",
+  "version": "1.0.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"
+  },
+  "dependencies": {},
+  "keywords": []
+}

packages/protocol/src/base-url.ts

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

packages/protocol/src/event-stream.ts

@@ -0,0 +1,105 @@
+import type {
+  AssistantMessage,
+  AssistantMessageEvent,
+  AssistantMessageEventStream,
+} from './types.js';
+
+export class EventStream<TEvent, TResult = TEvent> implements AsyncIterable<TEvent> {
+  private readonly queue: TEvent[] = [];
+  private readonly waiting: Array<(result: IteratorResult<TEvent>) => void> = [];
+  private done = false;
+  private readonly finalResultPromise: Promise<TResult>;
+  private resolveFinalResult!: (value: TResult) => void;
+
+  constructor(
+    private readonly isTerminal: (event: TEvent) => boolean,
+    private readonly extractResult: (event: TEvent) => TResult
+  ) {
+    this.finalResultPromise = new Promise<TResult>((resolve) => {
+      this.resolveFinalResult = resolve;
+    });
+  }
+
+  push(event: TEvent): void {
+    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?: TResult): void {
+    this.done = true;
+    if (result !== undefined) {
+      this.resolveFinalResult(result);
+    }
+
+    while (this.waiting.length > 0) {
+      this.waiting.shift()!({ value: undefined as never, done: true });
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<TEvent> {
+    while (true) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift()!;
+        continue;
+      }
+
+      if (this.done) {
+        return;
+      }
+
+      const next = await new Promise<IteratorResult<TEvent>>((resolve) => {
+        this.waiting.push(resolve);
+      });
+
+      if (next.done) {
+        return;
+      }
+
+      yield next.value;
+    }
+  }
+
+  result(): Promise<TResult> {
+    return this.finalResultPromise;
+  }
+}
+
+export class DefaultAssistantMessageEventStream
+  extends EventStream<AssistantMessageEvent, AssistantMessage>
+  implements AssistantMessageEventStream
+{
+  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(): DefaultAssistantMessageEventStream {
+  return new DefaultAssistantMessageEventStream();
+}

packages/protocol/src/index.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';

packages/protocol/src/json.ts

@@ -0,0 +1,82 @@
+import type { JsonValue } from './types.js';
+
+/** Deep structural clone via JSON round-trip. Used to snapshot streamed messages. */
+export function clone<TValue>(value: TValue): TValue {
+  return JSON.parse(JSON.stringify(value)) as 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 function parsePartialJson(raw: string): Record<string, JsonValue | undefined> {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(trimmed) as Record<string, JsonValue | undefined>;
+  } catch {
+    // continue
+  }
+
+  const completed = completePartialJson(trimmed);
+  if (!completed) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(completed) as Record<string, JsonValue | undefined>;
+  } catch {
+    return {};
+  }
+}
+
+/** Close any open strings, objects, and arrays so a truncated fragment parses. */
+export function completePartialJson(input: string): string | undefined {
+  let output = input;
+  let inString = false;
+  let escaping = false;
+  const stack: string[] = [];
+
+  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;
+}