@vincemakes/kiso-core 0.1.0

package/dist/protocol/messages.d.ts

@@ -0,0 +1,113 @@
+/**
+ * L1 — the message types.
+ *
+ * This is the conversation history the kernel hands to `adapter.stream()`.
+ * A `Message` is tagged by role; `ToolSpec` is the minimal projection an
+ * adapter advertises to the model.
+ *
+ * WHY the content of a user/tool message is `string | ContentBlock[]`:
+ * the string form is the common case and stays cheap, while the array form
+ * carries images. Forcing every caller into the array shape to serve the
+ * 5% that need vision is a tax paid on every line of product code.
+ *
+ * See ADR-0003 (sum type) and ADR-0008 (tool contract).
+ *
+ * This module is types-only: it compiles to nothing.
+ */
+export type Role = "user" | "assistant" | "tool";
+/** A text segment. Equivalent to plain `string` content, but interleavable. */
+export interface TextContentBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+/**
+ * An image input.
+ *
+ * - `sourceType: "url"`    — the PROVIDER fetches it. atto never downloads.
+ * - `sourceType: "base64"` — `data` holds raw base64 with no `data:` prefix;
+ *                            `mediaType` is then required.
+ *
+ * Exactly one of `url` / `data` must be set for the declared `sourceType`.
+ * Adapters do NOT re-validate this — a mismatch surfaces as a provider 400.
+ * That is deliberate: a second validation layer that disagrees with the
+ * provider's is worse than none.
+ */
+export interface ImageContentBlock {
+    readonly type: "image";
+    readonly sourceType: "url" | "base64";
+    readonly url?: string;
+    readonly data?: string;
+    readonly mediaType?: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+}
+export type ContentBlock = TextContentBlock | ImageContentBlock;
+/**
+ * Provenance — where a message actually came from.
+ *
+ * The model treats this as evidence about intent; a "user" line that the UI
+ * recycled from a suggestion chip is NOT user intent, and a model that cannot
+ * tell the difference drifts on its own recycled wording (Claude Code
+ * #60087). The kernel preserves the label; product code decides how to render
+ * it. Defaults (when absent): role `user` → "user", role `assistant` →
+ * "model", role `tool` → "tool_result".
+ */
+export type MessageSource = "user" | "suggestion" | "tool_result" | "subagent" | "system" | "model";
+export interface UserMessage {
+    readonly role: "user";
+    readonly content: string | readonly ContentBlock[];
+    readonly source?: MessageSource;
+}
+export interface AssistantTextBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface AssistantToolUseBlock {
+    readonly type: "tool_use";
+    readonly callId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export type AssistantBlock = AssistantTextBlock | AssistantToolUseBlock;
+export interface AssistantMessage {
+    readonly role: "assistant";
+    readonly blocks: readonly AssistantBlock[];
+    readonly source?: MessageSource;
+}
+/**
+ * Sent back to the model after a tool ran.
+ *
+ * `tags` are product-defined labels that the kernel honors but never defines.
+ * The canonical use is marking a result as do-not-compact (a safety notice, a
+ * billing receipt, a trace anchor). kiso prescribes no vocabulary: the kernel
+ * matches tags it was configured with and ignores the rest.
+ */
+export interface ToolResultMessage {
+    readonly role: "tool";
+    readonly callId: string;
+    readonly content: string | readonly ContentBlock[];
+    readonly isError: boolean;
+    readonly source?: MessageSource;
+    readonly tags?: readonly string[];
+    /**
+     * The seq of the `tool_result` EVENT this message was projected from —
+     * the stable identity compaction uses to name WHICH result it replaced
+     * (五: the callId may repeat across runs). DERIVED, never persisted: the
+     * projection attaches it as a non-enumerable field, so it is invisible
+     * to deep equality with seed messages and never survives a re-derive
+     * from anywhere but the log.
+     */
+    readonly eventSeq?: number;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+/**
+ * What the adapter advertises to the model.
+ *
+ * Deliberately minimal: the full tool (handler, repair, concurrency, dedup)
+ * is L3-internal and an adapter must never see it. An adapter that can reach
+ * the handler will eventually call it, and then the kernel is no longer the
+ * only thing that runs tools.
+ */
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}

package/dist/protocol/messages.js

@@ -0,0 +1,17 @@
+/**
+ * L1 — the message types.
+ *
+ * This is the conversation history the kernel hands to `adapter.stream()`.
+ * A `Message` is tagged by role; `ToolSpec` is the minimal projection an
+ * adapter advertises to the model.
+ *
+ * WHY the content of a user/tool message is `string | ContentBlock[]`:
+ * the string form is the common case and stays cheap, while the array form
+ * carries images. Forcing every caller into the array shape to serve the
+ * 5% that need vision is a tax paid on every line of product code.
+ *
+ * See ADR-0003 (sum type) and ADR-0008 (tool contract).
+ *
+ * This module is types-only: it compiles to nothing.
+ */
+export {};

package/dist/tools/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * L3 — the tool registry.
+ *
+ * One registry per agent. It is the ONLY place the kernel learns which tools
+ * exist: nothing is assembled from a list maintained elsewhere, because a
+ * second list is a second truth (the failure class behind Claude Code's five
+ * hand-maintained agent-tool sets and pi's six copies of the default tool
+ * list — see ADR-0001).
+ *
+ * `subset()` is the structural tool filter: a mode or a subagent gets a
+ * registry whose tool table PHYSICALLY lacks the tools it must not see. The
+ * model cannot call a tool that is not in its registry — no prompt can
+ * achieve that guarantee.
+ */
+import type { ToolSpec } from "../protocol/messages.js";
+import type { Tool } from "./tool.js";
+export declare class ToolRegistry {
+    #private;
+    register(tool: Tool<any>): void;
+    get(name: string): Tool<any> | undefined;
+    list(): readonly Tool[];
+    has(name: string): boolean;
+    /** A registry restricted to the named tools. Unknown names are dropped
+     *  loudly (the kernel never silently shrinks a tool set). */
+    subset(names: readonly string[]): ToolRegistry;
+    /** The minimal projection an adapter may see (never the handlers). */
+    toSpecs(): readonly ToolSpec[];
+}

package/dist/tools/registry.js

@@ -0,0 +1,53 @@
+/**
+ * L3 — the tool registry.
+ *
+ * One registry per agent. It is the ONLY place the kernel learns which tools
+ * exist: nothing is assembled from a list maintained elsewhere, because a
+ * second list is a second truth (the failure class behind Claude Code's five
+ * hand-maintained agent-tool sets and pi's six copies of the default tool
+ * list — see ADR-0001).
+ *
+ * `subset()` is the structural tool filter: a mode or a subagent gets a
+ * registry whose tool table PHYSICALLY lacks the tools it must not see. The
+ * model cannot call a tool that is not in its registry — no prompt can
+ * achieve that guarantee.
+ */
+export class ToolRegistry {
+    #tools = new Map();
+    register(tool) {
+        if (this.#tools.has(tool.name)) {
+            throw new Error(`Tool already registered: ${tool.name}`);
+        }
+        this.#tools.set(tool.name, tool);
+    }
+    get(name) {
+        return this.#tools.get(name);
+    }
+    list() {
+        return [...this.#tools.values()];
+    }
+    has(name) {
+        return this.#tools.has(name);
+    }
+    /** A registry restricted to the named tools. Unknown names are dropped
+     *  loudly (the kernel never silently shrinks a tool set). */
+    subset(names) {
+        const out = new ToolRegistry();
+        for (const name of names) {
+            const tool = this.#tools.get(name);
+            if (tool === undefined) {
+                throw new Error(`subset(): unknown tool '${name}'`);
+            }
+            out.register(tool);
+        }
+        return out;
+    }
+    /** The minimal projection an adapter may see (never the handlers). */
+    toSpecs() {
+        return [...this.#tools.values()].map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.parameters,
+        }));
+    }
+}

package/dist/tools/tool.d.ts

@@ -0,0 +1,72 @@
+/**
+ * L3 — the tool contract.
+ *
+ * A tool is a pure declaration + handler pair. The kernel never branches on
+ * a tool's internals: `parameters` is a JSON Schema the kernel validates and
+ * projects to the adapter as `ToolSpec` (adapter never sees the handler —
+ * see ADR-0001), `concurrencySafe` decides batch scheduling, `delivers`
+ * marks a tool as an artifact producer (consumed by harness-side delivery
+ * tracking; the kernel only carries the flag).
+ *
+ * WHY JSON Schema instead of a runtime library: the kernel has zero runtime
+ * dependencies (ADR-0001). Zod / TypeBox / valibot live at the harness layer;
+ * a harness author converts their schema to JSON Schema once, at defineTool
+ * time, and the kernel stays host- and library-agnostic.
+ *
+ * `ToolErrorKind` (protocol/events) rides on `ToolResult` so a refusal
+ * ("precondition") is distinguishable from a failure after work began.
+ */
+import type { AbortSignalLike } from "../protocol/adapter.js";
+import type { ToolErrorKind } from "../protocol/events.js";
+/** Everything a handler needs, and nothing else. */
+export interface ToolContext {
+    readonly signal: AbortSignalLike;
+    /** Opaque session anchor, when the harness has one. */
+    readonly sessionId?: string;
+    /** Free-form per-call metadata the kernel passes through untouched. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 第五轮(P1-9): a DISCRIMINATED union — `errorKind` is structurally
+ * impossible on a non-error result, matching the persisted-event schema
+ * (an isError:false result with an errorKind would be rejected by the
+ * store's validator and poison the next load).
+ */
+export type ToolResult = {
+    readonly content: string;
+    readonly isError: false;
+    readonly tags?: readonly string[];
+} | {
+    readonly content: string;
+    readonly isError: true;
+    /** Present only when the handler classified the failure. */
+    readonly errorKind?: ToolErrorKind;
+    readonly tags?: readonly string[];
+};
+export interface Tool<I = unknown> {
+    readonly name: string;
+    readonly description: string;
+    /** JSON Schema (draft-07 subset). Validated before execute. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /**
+     * Per-call concurrency predicate — the CC-invented shape that pi's static
+     * executionMode cannot express: the same tool may be parallel-safe for one
+     * input and must be serial for another (generate_image with
+     * `chain_to_previous`). Absent = safe when true-ish; see ADR-0015.
+     */
+    readonly concurrencySafe?: (input: I) => boolean;
+    /** Marks this tool as an artifact producer (harness-side delivery truth). */
+    readonly delivers?: {
+        readonly kind: string;
+    };
+    /**
+     * Exactly-once guard escape hatch (Phase D): a tool whose side effects
+     * are safe to repeat (reads, searches, pure computations) declares
+     * `idempotent: true`. Without it, the kernel refuses to run the same
+     * tool+input twice in a session — a confirmed success is replayed, an
+     * interrupted attempt blocks. The default is the safe side.
+     */
+    readonly idempotent?: boolean;
+    readonly execute: (input: I, ctx: ToolContext) => Promise<ToolResult>;
+}
+export declare function defineTool<I = unknown>(tool: Tool<I>): Tool<I>;

package/dist/tools/tool.js

@@ -0,0 +1,21 @@
+/**
+ * L3 — the tool contract.
+ *
+ * A tool is a pure declaration + handler pair. The kernel never branches on
+ * a tool's internals: `parameters` is a JSON Schema the kernel validates and
+ * projects to the adapter as `ToolSpec` (adapter never sees the handler —
+ * see ADR-0001), `concurrencySafe` decides batch scheduling, `delivers`
+ * marks a tool as an artifact producer (consumed by harness-side delivery
+ * tracking; the kernel only carries the flag).
+ *
+ * WHY JSON Schema instead of a runtime library: the kernel has zero runtime
+ * dependencies (ADR-0001). Zod / TypeBox / valibot live at the harness layer;
+ * a harness author converts their schema to JSON Schema once, at defineTool
+ * time, and the kernel stays host- and library-agnostic.
+ *
+ * `ToolErrorKind` (protocol/events) rides on `ToolResult` so a refusal
+ * ("precondition") is distinguishable from a failure after work began.
+ */
+export function defineTool(tool) {
+    return tool;
+}

package/dist/tools/validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * L3 — real JSON Schema validation of tool arguments (Phase B).
+ *
+ * `Tool.parameters` was always declared to be a JSON Schema the kernel
+ * validates; until Phase B it was only advertised, never enforced. ajv is
+ * the core's single runtime dependency (ADR-0023): the alternative —
+ * hand-rolling a draft-07 subset — is how schemas silently stop meaning
+ * what they say. Validators are compiled once per schema and cached.
+ */
+/** Returns a human-readable failure reason, or null when the input is valid. */
+export declare function validateArgs(schema: Readonly<Record<string, unknown>>, input: unknown): string | null;

package/dist/tools/validate.js

@@ -0,0 +1,28 @@
+/**
+ * L3 — real JSON Schema validation of tool arguments (Phase B).
+ *
+ * `Tool.parameters` was always declared to be a JSON Schema the kernel
+ * validates; until Phase B it was only advertised, never enforced. ajv is
+ * the core's single runtime dependency (ADR-0023): the alternative —
+ * hand-rolling a draft-07 subset — is how schemas silently stop meaning
+ * what they say. Validators are compiled once per schema and cached.
+ */
+import { Ajv } from "ajv";
+const ajv = new Ajv({ strict: false });
+const cache = new WeakMap();
+/** Returns a human-readable failure reason, or null when the input is valid. */
+export function validateArgs(schema, input) {
+    let validate = cache.get(schema);
+    if (!validate) {
+        validate = ajv.compile(schema);
+        cache.set(schema, validate);
+    }
+    if (validate(input))
+        return null;
+    const first = validate.errors?.[0];
+    if (first) {
+        const where = first.instancePath || "/";
+        return `${where} ${first.message ?? "is invalid"}`;
+    }
+    return "arguments failed schema validation";
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vincemakes/kiso-core",
+  "version": "0.1.0",
+  "description": "kiso(\u57fa\u790e) core \u2014 protocol, event log, loop, hooks, modes, permissions, compaction, delivery truth. The 2,000-line kernel at the bottom of the kiso framework.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "framework",
+    "kernel",
+    "anthropic",
+    "openai"
+  ],
+  "devDependencies": {
+    "@vincemakes/kiso-evals": "0.1.0",
+    "@types/node": "^26.1.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vincemakes/kiso.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/vincemakes/kiso/issues"
+  },
+  "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/core#readme"
+}