@lite-agent/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { ModelProvider, Tool, Middleware, Sandbox, PermissionPolicy, ApprovalHandler, InputHandler, Agent, Message, AgentEvent, RunResult, ToolContext } from '@lite-agent/core';
+export * from '@lite-agent/core';
+import { ZodType } from 'zod';
+
+interface CreateLiteAgentConfig {
+    model: ModelProvider;
+    modelName?: string;
+    workdir: string;
+    skillsDir?: string;
+    tools?: Tool[];
+    system?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxTurns?: number;
+    maxTokens?: number;
+    use?: Middleware[];
+    sandbox?: Sandbox;
+    permission?: PermissionPolicy;
+    onApproval?: ApprovalHandler;
+    onAskUser?: InputHandler;
+}
+declare function createLiteAgent(cfg: CreateLiteAgentConfig): Agent;
+
+interface QueryOptions {
+    prompt: string | Message[];
+    model: ModelProvider;
+    modelName?: string;
+    cwd?: string;
+    systemPrompt?: string;
+    skillsDir?: string;
+    tools?: Tool[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxTurns?: number;
+    maxTokens?: number;
+    use?: Middleware[];
+    signal?: AbortSignal;
+    sessionId?: string;
+    sandbox?: Sandbox;
+    permission?: PermissionPolicy;
+    onApproval?: ApprovalHandler;
+    onAskUser?: InputHandler;
+}
+declare function query(opts: QueryOptions): AsyncGenerator<AgentEvent, RunResult>;
+
+declare function tool<I>(name: string, description: string, schema: ZodType<I>, handler: (input: I, ctx: ToolContext) => Promise<string> | string): Tool<I>;
+
+interface SystemPromptOptions {
+    workdir: string;
+    modelName?: string;
+    skills: string;
+}
+declare function buildSystemPrompt(opts: SystemPromptOptions): string;
+
+declare function bashTool(workdir: string): Tool;
+
+declare function makeSafePath(workdir: string): (p: string) => string;
+declare function fileTools(workdir: string): Tool[];
+
+declare function todoTool(): Tool;
+
+declare function askUserTool(): Tool;
+
+declare function defaultTools(workdir: string): Tool[];
+
+declare class SkillLoader {
+    readonly skillsDir: string;
+    private skills;
+    constructor(skillsDir: string);
+    private loadAll;
+    private parse;
+    getDescriptions(): string;
+    getContent(name: string): string;
+}
+
+declare function loadSkillTool(loader: SkillLoader): Tool;
+
+export { type CreateLiteAgentConfig, type QueryOptions, SkillLoader, type SystemPromptOptions, askUserTool, bashTool, buildSystemPrompt, createLiteAgent, defaultTools, fileTools, loadSkillTool, makeSafePath, query, todoTool, tool };

package/dist/index.js

@@ -0,0 +1,354 @@
+// src/index.ts
+export * from "@lite-agent/core";
+
+// src/createLiteAgent.ts
+import { createAgent, nativeCodec, permission } from "@lite-agent/core";
+
+// src/tools/bash.ts
+import { execSync } from "child_process";
+import { z } from "zod";
+import { defineTool } from "@lite-agent/core";
+var DANGEROUS = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"];
+function bashTool(workdir) {
+  return defineTool({
+    name: "bash",
+    description: "Run a shell command.",
+    schema: z.object({ command: z.string() }),
+    execute: async ({ command }, ctx) => {
+      if (DANGEROUS.some((d) => command.includes(d)))
+        return "Error: Dangerous command blocked";
+      const toRun = ctx.sandbox ? await ctx.sandbox.wrap(command, { cwd: workdir }) : command;
+      try {
+        const out = execSync(toRun, {
+          cwd: workdir,
+          encoding: "utf8",
+          timeout: 12e4,
+          maxBuffer: 5e7
+        });
+        return out.trim() || "(no output)";
+      } catch (e) {
+        const err = e;
+        return `${err.stdout ?? ""}${err.stderr ?? ""}`.trim().slice(0, 5e4) || `Error: ${err.message}`;
+      }
+    }
+  });
+}
+
+// src/tools/file.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { z as z2 } from "zod";
+import { defineTool as defineTool2 } from "@lite-agent/core";
+var MAX_BYTES = 5e4;
+function makeSafePath(workdir) {
+  const root = resolve(workdir);
+  return (p) => {
+    const full = resolve(root, p);
+    if (full !== root && !full.startsWith(root + "/")) {
+      throw new Error(`Path escapes workspace: ${p}`);
+    }
+    return full;
+  };
+}
+function fileTools(workdir) {
+  const safePath = makeSafePath(workdir);
+  const readFile = defineTool2({
+    name: "read_file",
+    description: "Read file contents.",
+    schema: z2.object({ path: z2.string(), limit: z2.number().int().optional() }),
+    execute: ({ path, limit }) => {
+      const lines = readFileSync(safePath(path), "utf8").split("\n");
+      if (limit && limit < lines.length) {
+        return [
+          ...lines.slice(0, limit),
+          `... (${lines.length - limit} more lines)`
+        ].join("\n").slice(0, MAX_BYTES);
+      }
+      return lines.join("\n").slice(0, MAX_BYTES);
+    }
+  });
+  const writeFile = defineTool2({
+    name: "write_file",
+    description: "Write content to a file.",
+    schema: z2.object({ path: z2.string(), content: z2.string() }),
+    execute: ({ path, content }) => {
+      const fp = safePath(path);
+      mkdirSync(dirname(fp), { recursive: true });
+      writeFileSync(fp, content);
+      return `Wrote ${content.length} bytes to ${path}`;
+    }
+  });
+  const editFile = defineTool2({
+    name: "edit_file",
+    description: "Replace exact text in a file.",
+    schema: z2.object({
+      path: z2.string(),
+      old_text: z2.string(),
+      new_text: z2.string()
+    }),
+    execute: ({ path, old_text, new_text }) => {
+      const fp = safePath(path);
+      const content = readFileSync(fp, "utf8");
+      if (!content.includes(old_text))
+        return `Error: Text not found in ${path}`;
+      writeFileSync(fp, content.replace(old_text, new_text));
+      return `Edited ${path}`;
+    }
+  });
+  return [readFile, writeFile, editFile];
+}
+
+// src/tools/todo.ts
+import { z as z3 } from "zod";
+import { defineTool as defineTool3 } from "@lite-agent/core";
+var MARK = {
+  pending: "[ ]",
+  in_progress: "[>]",
+  completed: "[x]"
+};
+var itemSchema = z3.object({
+  id: z3.string(),
+  text: z3.string().min(1),
+  status: z3.enum(["pending", "in_progress", "completed"])
+});
+var TodoManager = class {
+  items = [];
+  update(items) {
+    if (items.length > 20) throw new Error("Max 20 todos allowed");
+    if (items.filter((t) => t.status === "in_progress").length > 1) {
+      throw new Error("Only one task can be in_progress at a time");
+    }
+    this.items = items;
+    return this.render();
+  }
+  render() {
+    if (!this.items.length) return "No todos.";
+    const lines = this.items.map(
+      (t) => `${MARK[t.status]} #${t.id}: ${t.text}`
+    );
+    const done = this.items.filter((t) => t.status === "completed").length;
+    lines.push(`
+(${done}/${this.items.length} completed)`);
+    return lines.join("\n");
+  }
+};
+function todoTool() {
+  const manager = new TodoManager();
+  return defineTool3({
+    name: "todo",
+    description: "Update the task list. Track progress on multi-step tasks.",
+    schema: z3.object({ items: z3.array(itemSchema) }),
+    execute: async ({ items }) => manager.update(items)
+  });
+}
+
+// src/tools/askUser.ts
+import { z as z4 } from "zod";
+import { defineTool as defineTool4 } from "@lite-agent/core";
+function renderAnswer(a) {
+  if (a.selected && a.selected.length) return a.selected.join(", ");
+  if (a.text && a.text.length) return a.text;
+  return "(no answer)";
+}
+function askUserTool() {
+  return defineTool4({
+    name: "ask_user",
+    description: "Ask the human a question and wait for their answer. Use for decisions, missing information, or confirmations. Provide `options` for a multiple-choice question (set `multiSelect` to allow several).",
+    schema: z4.object({
+      question: z4.string().min(1),
+      options: z4.array(z4.string()).optional(),
+      multiSelect: z4.boolean().optional()
+    }),
+    execute: async ({ question, options, multiSelect }, ctx) => {
+      if (!ctx.input)
+        return "Error: ask_user is unavailable (no input handler configured).";
+      const q = {
+        question,
+        ...options ? { options } : {},
+        ...multiSelect ? { multiSelect } : {}
+      };
+      if (ctx.call)
+        ctx.emit({ type: "input_request", call: ctx.call, question: q });
+      const answer = await ctx.input.request(q);
+      ctx.emit({
+        type: "input_resolved",
+        id: ctx.call?.id ?? "ask_user",
+        answer
+      });
+      return renderAnswer(answer);
+    }
+  });
+}
+
+// src/tools/index.ts
+function defaultTools(workdir) {
+  return [bashTool(workdir), ...fileTools(workdir), todoTool()];
+}
+
+// src/skills/loader.ts
+import { existsSync, readdirSync, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join } from "path";
+var SkillLoader = class {
+  skillsDir;
+  skills = {};
+  constructor(skillsDir) {
+    this.skillsDir = skillsDir;
+    this.loadAll();
+  }
+  loadAll() {
+    if (!existsSync(this.skillsDir)) return;
+    const walk = (dir) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory()) walk(p);
+        else if (entry.name === "SKILL.md") {
+          const { meta, body } = this.parse(readFileSync2(p, "utf8"));
+          const name = meta.name ?? dirname2(p).split("/").pop() ?? p;
+          this.skills[name] = { meta, body, path: p };
+        }
+      }
+    };
+    walk(this.skillsDir);
+  }
+  parse(text) {
+    const m = text.match(/^---\n(.*?)\n---\n(.*)/s);
+    if (!m) return { meta: {}, body: text };
+    const meta = {};
+    for (const line of m[1].trim().split("\n")) {
+      const i = line.indexOf(":");
+      if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    return { meta, body: m[2].trim() };
+  }
+  getDescriptions() {
+    const names = Object.keys(this.skills);
+    if (!names.length) return "(no skills available)";
+    return names.map((n) => {
+      const s = this.skills[n];
+      const tags = s.meta.tags ? ` [${s.meta.tags}]` : "";
+      return `  - ${n}: ${s.meta.description ?? "No description"}${tags}`;
+    }).join("\n");
+  }
+  getContent(name) {
+    const s = this.skills[name];
+    if (!s) return `Error: Unknown skill '${name}'. Available: ${Object.keys(this.skills).join(", ")}`;
+    return `<skill name="${name}">
+${s.body}
+</skill>`;
+  }
+};
+
+// src/skills/loadSkillTool.ts
+import { z as z5 } from "zod";
+import { defineTool as defineTool5 } from "@lite-agent/core";
+function loadSkillTool(loader) {
+  return defineTool5({
+    name: "load_skill",
+    description: "Load a skill's full instructions by name before tackling an unfamiliar task.",
+    schema: z5.object({ name: z5.string() }),
+    execute: ({ name }) => loader.getContent(name)
+  });
+}
+
+// src/system.ts
+function buildSystemPrompt(opts) {
+  const modelLine = opts.modelName ? `Your model is ${opts.modelName}.
+` : "";
+  return `You are lite-agent, a coding agent operating in ${opts.workdir}.
+${modelLine}
+## Core Principles
+- Prefer tools over prose.
+- Always work inside ${opts.workdir}; never access paths outside it.
+
+## Task Planning
+- For any task with 3+ steps, call the todo tool first to plan, then execute step by step.
+- Mark todos as in_progress before starting each step, and completed when done.
+
+## Skills
+Use load_skill to access specialized knowledge before tackling unfamiliar topics.
+Available skills:
+${opts.skills}`;
+}
+
+// src/createLiteAgent.ts
+function createLiteAgent(cfg) {
+  let tools = [...defaultTools(cfg.workdir)];
+  let skills = "(no skills available)";
+  if (cfg.skillsDir) {
+    const loader = new SkillLoader(cfg.skillsDir);
+    tools.push(loadSkillTool(loader));
+    skills = loader.getDescriptions();
+  }
+  if (cfg.tools) tools.push(...cfg.tools);
+  if (cfg.onAskUser) tools.push(askUserTool());
+  if (cfg.allowedTools)
+    tools = tools.filter((t) => cfg.allowedTools.includes(t.name));
+  if (cfg.disallowedTools)
+    tools = tools.filter((t) => !cfg.disallowedTools.includes(t.name));
+  const system = cfg.system ?? buildSystemPrompt({
+    workdir: cfg.workdir,
+    modelName: cfg.modelName,
+    skills
+  });
+  const use = [
+    ...cfg.permission ? [permission(cfg.permission, cfg.onApproval)] : [],
+    ...cfg.use ?? []
+  ];
+  return createAgent({
+    model: cfg.model,
+    modelName: cfg.modelName,
+    codec: nativeCodec(),
+    tools,
+    use,
+    system,
+    maxTurns: cfg.maxTurns,
+    maxTokens: cfg.maxTokens,
+    sandbox: cfg.sandbox,
+    input: cfg.onAskUser
+  });
+}
+
+// src/query.ts
+function query(opts) {
+  const agent = createLiteAgent({
+    model: opts.model,
+    modelName: opts.modelName,
+    workdir: opts.cwd ?? process.cwd(),
+    skillsDir: opts.skillsDir,
+    tools: opts.tools,
+    system: opts.systemPrompt,
+    allowedTools: opts.allowedTools,
+    disallowedTools: opts.disallowedTools,
+    maxTurns: opts.maxTurns,
+    maxTokens: opts.maxTokens,
+    use: opts.use,
+    sandbox: opts.sandbox,
+    permission: opts.permission,
+    onApproval: opts.onApproval,
+    onAskUser: opts.onAskUser
+  });
+  return agent.run(opts.prompt, {
+    signal: opts.signal,
+    sessionId: opts.sessionId
+  });
+}
+
+// src/tool.ts
+import { defineTool as defineTool6 } from "@lite-agent/core";
+function tool(name, description, schema, handler) {
+  return defineTool6({ name, description, schema, execute: handler });
+}
+export {
+  SkillLoader,
+  askUserTool,
+  bashTool,
+  buildSystemPrompt,
+  createLiteAgent,
+  defaultTools,
+  fileTools,
+  loadSkillTool,
+  makeSafePath,
+  query,
+  todoTool,
+  tool
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lite-agent/sdk",
+  "version": "0.1.0",
+  "description": "Batteries-included agent SDK over @lite-agent/core: tools, skills, system prompt, and query()/createLiteAgent().",
+  "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/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lite-agent/core": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.3.0",
+    "typescript": "^6.0.2",
+    "vitest": "^2.1.0"
+  }
+}