@lite-agent/core 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @lite-agent/core
+
+Pluggable, event-driven agent core SDK — a lean kernel plus strategy interfaces (model provider, tool-call codec, tools, compaction, permission, approval, input, store), an onion middleware pipeline, and a typed event stream.
+
+> **Status: Phase 1 (foundation / walking skeleton).** Real local-model providers, permission + human approval, `ask_user`, context compaction, and sessions land in later phases.
+
+## Quick start
+
+```ts
+import {
+  createAgent,
+  nativeCodec,
+  fakeProvider,
+  textBlock,
+} from "@lite-agent/core";
+
+const agent = createAgent({
+  model: fakeProvider([
+    { text: "hi", message: { role: "assistant", content: [textBlock("hi")] } },
+  ]),
+  codec: nativeCodec(),
+});
+
+// Stream typed events
+for await (const ev of agent.run("hello")) {
+  if (ev.type === "text_delta") process.stdout.write(ev.text);
+}
+
+// Or await the final result
+const result = await agent.send("hello");
+console.log(result.text);
+```
+
+## Concepts
+
+- **Strategies** (swap a part): `ModelProvider`, `ToolCallCodec`, `Tool`, `Compactor`, `PermissionPolicy`, `ApprovalHandler`, `InputHandler`, `Store`.
+- **Middleware** (compose cross-cutting behavior): `wrapModelCall`, `wrapToolCall`, and lifecycle hooks (`beforeAgent`/`afterAgent`/`beforeModel`).
+- **Events** (observe / control): a typed `AgentEvent` stream from `run()`.

package/dist/index.d.ts

@@ -0,0 +1,287 @@
+import { ZodType } from 'zod';
+
+type Role = "system" | "user" | "assistant" | "tool";
+type TextBlock = {
+    type: "text";
+    text: string;
+};
+type ToolCallBlock = {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+};
+type ToolResultBlock = {
+    type: "tool_result";
+    id: string;
+    content: string;
+    isError?: boolean;
+};
+type ContentBlock = TextBlock | ToolCallBlock | ToolResultBlock;
+type Message = {
+    role: Role;
+    content: string | ContentBlock[];
+};
+type AssistantMessage = {
+    role: "assistant";
+    content: ContentBlock[];
+};
+type ToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+type ToolResult = {
+    id: string;
+    name: string;
+    content: string;
+    isError?: boolean;
+};
+type Usage = {
+    inputTokens: number;
+    outputTokens: number;
+};
+type StopReason = "stop" | "tool_use" | "max_tokens";
+type UserQuestion = {
+    question: string;
+    options?: string[];
+    multiSelect?: boolean;
+};
+type UserAnswer = {
+    text?: string;
+    selected?: string[];
+};
+type ToolSpec = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+type ModelRequest = {
+    model: string;
+    system?: string;
+    messages: Message[];
+    tools?: ToolSpec[];
+    maxTokens?: number;
+    stopSequences?: string[];
+};
+type ModelChunk = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "message_done";
+    message: AssistantMessage;
+    usage: Usage;
+};
+declare const textBlock: (text: string) => TextBlock;
+declare const toolResultBlock: (id: string, content: string, isError?: boolean) => ToolResultBlock;
+declare const isToolCallBlock: (b: ContentBlock) => b is ToolCallBlock;
+declare const isTextBlock: (b: ContentBlock) => b is TextBlock;
+
+type RunResult = {
+    messages: Message[];
+    text: string;
+    usage: Usage;
+    stopReason: "stop" | "aborted" | "max_turns";
+};
+declare class AgentError extends Error {
+}
+declare class ProviderError extends AgentError {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+declare class ToolError extends AgentError {
+    constructor(message: string);
+}
+declare class CodecError extends AgentError {
+    constructor(message: string);
+}
+declare class MaxTurnsError extends AgentError {
+    constructor(message: string);
+}
+declare class AbortError extends AgentError {
+    constructor(message?: string);
+}
+type AgentEvent = {
+    type: "turn_start";
+    turn: number;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "message";
+    message: AssistantMessage;
+} | {
+    type: "tool_use";
+    call: ToolCall;
+} | {
+    type: "approval_request";
+    call: ToolCall;
+    reason?: string;
+} | {
+    type: "approval_resolved";
+    id: string;
+    decision: "allow" | "deny";
+    by: string;
+} | {
+    type: "input_request";
+    call: ToolCall;
+    question: UserQuestion;
+} | {
+    type: "input_resolved";
+    id: string;
+    answer: UserAnswer;
+} | {
+    type: "tool_result";
+    result: ToolResult;
+} | {
+    type: "compaction";
+    kind: "micro" | "auto";
+    before: number;
+    after: number;
+} | {
+    type: "turn_end";
+    turn: number;
+    stopReason: StopReason;
+} | {
+    type: "error";
+    error: AgentError;
+    fatal: boolean;
+} | {
+    type: "done";
+    reason: "stop" | "aborted" | "max_turns";
+    result: RunResult;
+};
+
+interface ModelProvider {
+    readonly id: string;
+    stream(req: ModelRequest, signal?: AbortSignal): AsyncIterable<ModelChunk>;
+}
+interface ToolCallCodec {
+    encode(req: ModelRequest, tools: ToolSpec[]): ModelRequest;
+    decode(message: AssistantMessage): {
+        text: string;
+        calls: ToolCall[];
+    };
+}
+interface ToolContext {
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    emit(ev: AgentEvent): void;
+    readonly approval?: ApprovalHandler;
+    readonly input?: InputHandler;
+    readonly sandbox?: Sandbox;
+    readonly call?: ToolCall;
+}
+interface Tool<I = unknown> {
+    name: string;
+    description: string;
+    schema: ZodType<I>;
+    execute(input: I, ctx: ToolContext): Promise<string> | string;
+}
+type CompactResult = {
+    messages: Message[];
+    kind?: "micro" | "auto";
+    before?: number;
+    after?: number;
+};
+interface Compactor {
+    maybeCompact(messages: Message[], usage: Usage): Promise<CompactResult>;
+}
+type Decision = "allow" | "deny" | "ask";
+interface PolicyContext {
+    readonly sessionId: string;
+}
+interface PermissionPolicy {
+    check(call: ToolCall, ctx: PolicyContext): Decision | Promise<Decision>;
+}
+interface ApprovalHandler {
+    request(call: ToolCall): Promise<"allow" | "deny">;
+}
+interface InputHandler {
+    request(q: UserQuestion): Promise<UserAnswer>;
+}
+interface SandboxWrapOptions {
+    readonly cwd: string;
+}
+interface Sandbox {
+    readonly id: string;
+    wrap(command: string, opts: SandboxWrapOptions): Promise<string> | string;
+    dispose?(): Promise<void> | void;
+}
+interface Store {
+    load(id: string): Promise<Message[] | null>;
+    save(id: string, messages: Message[]): Promise<void>;
+}
+
+interface AgentContext {
+    readonly sessionId: string;
+    messages: Message[];
+    readonly turn: number;
+    readonly signal: AbortSignal;
+    emit(ev: AgentEvent): void;
+    state: Map<string, unknown>;
+}
+interface ToolCallContext extends AgentContext {
+    readonly call: ToolCall;
+}
+type ModelCall = () => AsyncIterable<ModelChunk>;
+type ToolExec = () => Promise<ToolResult>;
+type LifecycleHook = "beforeAgent" | "afterAgent" | "beforeModel";
+interface Middleware {
+    name: string;
+    beforeAgent?(ctx: AgentContext): void | Promise<void>;
+    afterAgent?(ctx: AgentContext): void | Promise<void>;
+    beforeModel?(ctx: AgentContext): void | Promise<void>;
+    wrapModelCall?(ctx: AgentContext, next: ModelCall): AsyncIterable<ModelChunk>;
+    wrapToolCall?(ctx: ToolCallContext, next: ToolExec): Promise<ToolResult>;
+}
+declare function composeModelCall(mws: Middleware[], ctx: AgentContext, base: ModelCall): ModelCall;
+declare function composeToolCall(mws: Middleware[], ctx: ToolCallContext, base: ToolExec): ToolExec;
+declare function runLifecycle(mws: Middleware[], hook: LifecycleHook, ctx: AgentContext): Promise<void>;
+
+interface CreateAgentConfig {
+    model: ModelProvider;
+    modelName?: string;
+    codec: ToolCallCodec;
+    tools?: Tool[];
+    use?: Middleware[];
+    system?: string;
+    maxTurns?: number;
+    maxTokens?: number;
+    sandbox?: Sandbox;
+    input?: InputHandler;
+}
+type RunOptions = {
+    signal?: AbortSignal;
+    sessionId?: string;
+};
+interface Agent {
+    run(input: string | Message[], opts?: RunOptions): AsyncGenerator<AgentEvent, RunResult>;
+    send(input: string | Message[], opts?: RunOptions): Promise<RunResult>;
+}
+declare function createAgent(cfg: CreateAgentConfig): Agent;
+
+declare function nativeCodec(): ToolCallCodec;
+
+declare function defineTool<I>(def: Tool<I>): Tool<I>;
+declare function toToolSpec(tool: Tool): ToolSpec;
+
+type FakeTurn = {
+    text?: string;
+    message: AssistantMessage;
+    usage?: Usage;
+};
+declare function fakeProvider(turns: FakeTurn[]): ModelProvider;
+
+declare function noopSandbox(): Sandbox;
+
+interface PolicyOptions {
+    allow?: string[];
+    ask?: string[];
+    deny?: string[];
+    default?: Decision;
+}
+declare function policy(opts?: PolicyOptions): PermissionPolicy;
+declare function permission(pol: PermissionPolicy, approval?: ApprovalHandler): Middleware;
+
+export { AbortError, type Agent, type AgentContext, AgentError, type AgentEvent, type ApprovalHandler, type AssistantMessage, CodecError, type CompactResult, type Compactor, type ContentBlock, type CreateAgentConfig, type Decision, type FakeTurn, type InputHandler, MaxTurnsError, type Message, type Middleware, type ModelCall, type ModelChunk, type ModelProvider, type ModelRequest, type PermissionPolicy, type PolicyContext, type PolicyOptions, ProviderError, type Role, type RunOptions, type RunResult, type Sandbox, type SandboxWrapOptions, type StopReason, type Store, type TextBlock, type Tool, type ToolCall, type ToolCallBlock, type ToolCallCodec, type ToolCallContext, type ToolContext, ToolError, type ToolExec, type ToolResult, type ToolResultBlock, type ToolSpec, type Usage, type UserAnswer, type UserQuestion, composeModelCall, composeToolCall, createAgent, defineTool, fakeProvider, isTextBlock, isToolCallBlock, nativeCodec, noopSandbox, permission, policy, runLifecycle, textBlock, toToolSpec, toolResultBlock };

package/dist/index.js

@@ -0,0 +1,295 @@
+// src/sandbox.ts
+function noopSandbox() {
+  return { id: "noop", wrap: (command) => command };
+}
+
+// src/types.ts
+var textBlock = (text) => ({ type: "text", text });
+var toolResultBlock = (id, content, isError = false) => isError ? { type: "tool_result", id, content, isError: true } : { type: "tool_result", id, content };
+var isToolCallBlock = (b) => b.type === "tool_call";
+var isTextBlock = (b) => b.type === "text";
+
+// src/events.ts
+var AgentError = class extends Error {
+};
+var ProviderError = class extends AgentError {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ProviderError";
+  }
+};
+var ToolError = class extends AgentError {
+  constructor(message) {
+    super(message);
+    this.name = "ToolError";
+  }
+};
+var CodecError = class extends AgentError {
+  constructor(message) {
+    super(message);
+    this.name = "CodecError";
+  }
+};
+var MaxTurnsError = class extends AgentError {
+  constructor(message) {
+    super(message);
+    this.name = "MaxTurnsError";
+  }
+};
+var AbortError = class extends AgentError {
+  constructor(message = "aborted") {
+    super(message);
+    this.name = "AbortError";
+  }
+};
+
+// src/middleware.ts
+function composeModelCall(mws, ctx, base) {
+  return mws.filter((m) => m.wrapModelCall).reduceRight((next, m) => () => m.wrapModelCall(ctx, next), base);
+}
+function composeToolCall(mws, ctx, base) {
+  return mws.filter((m) => m.wrapToolCall).reduceRight((next, m) => () => m.wrapToolCall(ctx, next), base);
+}
+async function runLifecycle(mws, hook, ctx) {
+  for (const m of mws) {
+    const fn = m[hook];
+    if (fn) await fn.call(m, ctx);
+  }
+}
+
+// src/tools/define.ts
+import { z } from "zod";
+function defineTool(def) {
+  return def;
+}
+function toToolSpec(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: z.toJSONSchema(tool.schema)
+  };
+}
+
+// src/kernel.ts
+async function* runKernel(cfg, input, signal, sessionId) {
+  let messages = typeof input === "string" ? [{ role: "user", content: input }] : [...input];
+  const queue = [];
+  const emit = (ev) => {
+    queue.push(ev);
+  };
+  const toolMap = new Map(cfg.tools.map((t) => [t.name, t]));
+  const toolSpecs = cfg.tools.map(toToolSpec);
+  const state = /* @__PURE__ */ new Map();
+  let usage = { inputTokens: 0, outputTokens: 0 };
+  function* drain() {
+    while (queue.length) yield queue.shift();
+  }
+  const mkCtx = (turn) => ({ sessionId, messages, turn, signal, emit, state });
+  await runLifecycle(cfg.middleware, "beforeAgent", mkCtx(0));
+  yield* drain();
+  let stopReason = "max_turns";
+  for (let turn = 1; turn <= cfg.maxTurns; turn++) {
+    if (signal.aborted) {
+      stopReason = "aborted";
+      break;
+    }
+    const ctx = mkCtx(turn);
+    yield { type: "turn_start", turn };
+    await runLifecycle(cfg.middleware, "beforeModel", ctx);
+    yield* drain();
+    messages = ctx.messages;
+    const req = cfg.codec.encode(
+      { model: cfg.model, system: cfg.system, messages: ctx.messages, maxTokens: cfg.maxTokens },
+      toolSpecs
+    );
+    const modelCall = composeModelCall(cfg.middleware, ctx, () => cfg.provider.stream(req, signal));
+    let assistant;
+    for await (const chunk of modelCall()) {
+      if (chunk.type === "text_delta") yield { type: "text_delta", text: chunk.text };
+      else {
+        assistant = chunk.message;
+        usage = {
+          inputTokens: usage.inputTokens + chunk.usage.inputTokens,
+          outputTokens: usage.outputTokens + chunk.usage.outputTokens
+        };
+      }
+    }
+    yield* drain();
+    if (!assistant) throw new ProviderError("provider produced no message_done chunk");
+    ctx.messages.push(assistant);
+    yield { type: "message", message: assistant };
+    const { calls } = cfg.codec.decode(assistant);
+    if (calls.length === 0) {
+      yield { type: "turn_end", turn, stopReason: "stop" };
+      stopReason = "stop";
+      break;
+    }
+    const resultBlocks = [];
+    for (const call of calls) {
+      yield { type: "tool_use", call };
+      const tctx = { ...ctx, call };
+      const tool = toolMap.get(call.name);
+      const baseExec = async () => {
+        if (!tool) return { id: call.id, name: call.name, content: `Error: unknown tool '${call.name}'`, isError: true };
+        try {
+          const parsed = tool.schema.parse(call.input);
+          const out = await tool.execute(parsed, { sessionId, signal, emit, sandbox: cfg.sandbox, input: cfg.input, call });
+          return { id: call.id, name: call.name, content: String(out) };
+        } catch (e) {
+          return { id: call.id, name: call.name, content: `Error: ${e.message}`, isError: true };
+        }
+      };
+      const result2 = await composeToolCall(cfg.middleware, tctx, baseExec)();
+      yield* drain();
+      resultBlocks.push(toolResultBlock(result2.id, result2.content, result2.isError));
+      yield { type: "tool_result", result: result2 };
+    }
+    ctx.messages.push({ role: "user", content: resultBlocks });
+    yield { type: "turn_end", turn, stopReason: "tool_use" };
+  }
+  await runLifecycle(cfg.middleware, "afterAgent", mkCtx(0));
+  yield* drain();
+  const result = { messages, text: lastAssistantText(messages), usage, stopReason };
+  yield { type: "done", reason: stopReason, result };
+  return result;
+}
+function lastAssistantText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m && m.role === "assistant" && Array.isArray(m.content)) {
+      return m.content.filter(isTextBlock).map((b) => b.text).join("");
+    }
+  }
+  return "";
+}
+
+// src/createAgent.ts
+var sessionCounter = 0;
+function createAgent(cfg) {
+  const kernelCfg = {
+    provider: cfg.model,
+    codec: cfg.codec,
+    tools: cfg.tools ?? [],
+    middleware: cfg.use ?? [],
+    model: cfg.modelName ?? cfg.model.id,
+    system: cfg.system,
+    maxTurns: cfg.maxTurns ?? 50,
+    maxTokens: cfg.maxTokens,
+    sandbox: cfg.sandbox ?? noopSandbox(),
+    input: cfg.input
+  };
+  const agent = {
+    run(input, opts) {
+      const signal = opts?.signal ?? new AbortController().signal;
+      const sessionId = opts?.sessionId ?? `s${++sessionCounter}`;
+      return runKernel(kernelCfg, input, signal, sessionId);
+    },
+    async send(input, opts) {
+      const gen = agent.run(input, opts);
+      let r = await gen.next();
+      while (!r.done) r = await gen.next();
+      return r.value;
+    }
+  };
+  return agent;
+}
+
+// src/codecs/native.ts
+function nativeCodec() {
+  return {
+    encode(req, tools) {
+      return tools.length ? { ...req, tools } : req;
+    },
+    decode(message) {
+      const calls = [];
+      let text = "";
+      for (const block of message.content) {
+        if (block.type === "text") text += block.text;
+        else if (isToolCallBlock(block)) calls.push({ id: block.id, name: block.name, input: block.input });
+      }
+      return { text, calls };
+    }
+  };
+}
+
+// src/testing/fakeProvider.ts
+function fakeProvider(turns) {
+  let i = 0;
+  return {
+    id: "fake",
+    async *stream() {
+      const turn = turns[Math.min(i, turns.length - 1)];
+      i++;
+      if (!turn) throw new Error("fakeProvider: no turns configured");
+      if (turn.text) for (const ch of turn.text) yield { type: "text_delta", text: ch };
+      yield {
+        type: "message_done",
+        message: turn.message,
+        usage: turn.usage ?? { inputTokens: 0, outputTokens: 0 }
+      };
+    }
+  };
+}
+
+// src/permission.ts
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function policy(opts = {}) {
+  const compile = (pats) => (pats ?? []).map(globToRegExp);
+  const deny = compile(opts.deny);
+  const ask = compile(opts.ask);
+  const allow = compile(opts.allow);
+  const fallback = opts.default ?? "allow";
+  const hit = (res, name) => res.some((re) => re.test(name));
+  return {
+    check(call) {
+      if (hit(deny, call.name)) return "deny";
+      if (hit(ask, call.name)) return "ask";
+      if (hit(allow, call.name)) return "allow";
+      return fallback;
+    }
+  };
+}
+function denied(ctx, reason) {
+  return { id: ctx.call.id, name: ctx.call.name, content: `Error: ${reason}`, isError: true };
+}
+function permission(pol, approval) {
+  return {
+    name: "permission",
+    async wrapToolCall(ctx, next) {
+      const decision = await pol.check(ctx.call, { sessionId: ctx.sessionId });
+      if (decision === "allow") return next();
+      if (decision === "deny") return denied(ctx, "blocked by policy");
+      ctx.emit({ type: "approval_request", call: ctx.call });
+      const resolved = approval ? await approval.request(ctx.call) : "deny";
+      ctx.emit({ type: "approval_resolved", id: ctx.call.id, decision: resolved, by: approval ? "user" : "auto" });
+      return resolved === "allow" ? next() : denied(ctx, "denied by user");
+    }
+  };
+}
+export {
+  AbortError,
+  AgentError,
+  CodecError,
+  MaxTurnsError,
+  ProviderError,
+  ToolError,
+  composeModelCall,
+  composeToolCall,
+  createAgent,
+  defineTool,
+  fakeProvider,
+  isTextBlock,
+  isToolCallBlock,
+  nativeCodec,
+  noopSandbox,
+  permission,
+  policy,
+  runLifecycle,
+  textBlock,
+  toToolSpec,
+  toolResultBlock
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lite-agent/core",
+  "version": "0.1.0",
+  "description": "Pluggable, event-driven agent core: kernel, strategy interfaces, middleware pipeline, and normalized types.",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "llm",
+    "agent-sdk",
+    "tool-use"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NelsonYong/lite-agent.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.3.0",
+    "typescript": "^6.0.2",
+    "vitest": "^2.1.0"
+  }
+}