@lite-agent/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ModelProvider, Tool, Middleware, Sandbox, PermissionPolicy, ApprovalHandler, InputHandler, Agent, Message, AgentEvent, RunResult, ToolContext } from '@lite-agent/core';
+import { ModelProvider, Tool, Middleware, Sandbox, Store, Compactor, PermissionPolicy, ApprovalHandler, InputHandler, Agent, Message, AgentEvent, RunResult, ToolContext, SpillStore } from '@lite-agent/core';
 export * from '@lite-agent/core';
 import { ZodType } from 'zod';
 
@@ -15,6 +15,21 @@ interface CreateLiteAgentConfig {
     maxTokens?: number;
     use?: Middleware[];
     sandbox?: Sandbox;
+    store?: Store;
+    /** Override the global home (default `$LITE_AGENT_HOME` || `~/.lite-agent`). */
+    home?: string;
+    /** Persist transcripts under the project's sessions dir. Default true. Ignored when `store` is set. */
+    sessions?: boolean;
+    /** Spill oversized tool_results to disk + register `read_spilled`. Default true. */
+    spill?: boolean | {
+        budgetBytes?: number;
+    };
+    /** Proactive compactor. Default deterministic `defaultCompactor`; `false` disables compaction. */
+    compactor?: Compactor | false;
+    /** Sweep stale spill/session files once at startup. Default true (30 days). */
+    cleanup?: boolean | {
+        maxAgeDays?: number;
+    };
     permission?: PermissionPolicy;
     onApproval?: ApprovalHandler;
     onAskUser?: InputHandler;
@@ -37,6 +52,16 @@ interface QueryOptions {
     signal?: AbortSignal;
     sessionId?: string;
     sandbox?: Sandbox;
+    store?: Store;
+    compactor?: Compactor | false;
+    home?: string;
+    sessions?: boolean;
+    spill?: boolean | {
+        budgetBytes?: number;
+    };
+    cleanup?: boolean | {
+        maxAgeDays?: number;
+    };
     permission?: PermissionPolicy;
     onApproval?: ApprovalHandler;
     onAskUser?: InputHandler;
@@ -64,15 +89,58 @@ declare function askUserTool(): Tool;
 declare function defaultTools(workdir: string): Tool[];
 
 declare class SkillLoader {
-    readonly skillsDir: string;
+    readonly dirs: string[];
     private skills;
-    constructor(skillsDir: string);
+    constructor(dirs: string | string[]);
     private loadAll;
     private parse;
     getDescriptions(): string;
+    names(): 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 };
+interface JsonlStoreOptions {
+    /** Directory holding one `<sessionId>.jsonl` transcript per session. */
+    dir: string;
+}
+declare function jsonlStore(opts: JsonlStoreOptions): Store;
+
+/** Global home: `$LITE_AGENT_HOME` if set, else `~/.lite-agent`. */
+declare function liteAgentHome(): string;
+/** Stable per absolute project path: first 16 hex of sha1(resolve(workdir)). */
+declare function projectHash(workdir: string): string;
+interface ProjectPaths {
+    home: string;
+    hash: string;
+    spillDir: string;
+    sessionsDir: string;
+    globalSkillsDir: string;
+    projectSkillsDir: string;
+}
+/** Pure: derive every path from `workdir` (+ optional home). No fs side effects. */
+declare function resolveProjectPaths(opts: {
+    workdir: string;
+    home?: string;
+}): ProjectPaths;
+
+/**
+ * Delete stale runtime files under <home>/projects/HASH/spill and
+ * <home>/projects/HASH/sessions whose mtime is older than maxAgeDays
+ * (default 30). Global sweep, synchronous, fully guarded -- a failure
+ * here must never block agent startup.
+ */
+declare function sweepStale(opts?: {
+    home?: string;
+    maxAgeDays?: number;
+}): void;
+
+interface FileSpillStoreOptions {
+    /** Directory holding one `<ref>.txt` blob per spilled tool result. */
+    dir: string;
+}
+declare function fileSpillStore(opts: FileSpillStoreOptions): SpillStore;
+declare function readSpilledTool(store: SpillStore): Tool;
+
+export { type CreateLiteAgentConfig, type FileSpillStoreOptions, type JsonlStoreOptions, type ProjectPaths, type QueryOptions, SkillLoader, type SystemPromptOptions, askUserTool, bashTool, buildSystemPrompt, createLiteAgent, defaultTools, fileSpillStore, fileTools, jsonlStore, liteAgentHome, loadSkillTool, makeSafePath, projectHash, query, readSpilledTool, resolveProjectPaths, sweepStale, todoTool, tool };

package/dist/index.js

@@ -2,7 +2,14 @@
 export * from "@lite-agent/core";
 
 // src/createLiteAgent.ts
-import { createAgent, nativeCodec, permission } from "@lite-agent/core";
+import {
+  createAgent,
+  nativeCodec,
+  permission,
+  compaction,
+  reactiveCompaction,
+  defaultCompactor
+} from "@lite-agent/core";
 
 // src/tools/bash.ts
 import { execSync } from "child_process";
@@ -188,15 +195,15 @@ function defaultTools(workdir) {
 // src/skills/loader.ts
 import { existsSync, readdirSync, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, join } from "path";
+import matter from "gray-matter";
 var SkillLoader = class {
-  skillsDir;
+  dirs;
   skills = {};
-  constructor(skillsDir) {
-    this.skillsDir = skillsDir;
+  constructor(dirs) {
+    this.dirs = Array.isArray(dirs) ? dirs : [dirs];
     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);
@@ -208,27 +215,27 @@ var SkillLoader = class {
         }
       }
     };
-    walk(this.skillsDir);
+    for (const dir of this.dirs) {
+      if (existsSync(dir)) walk(dir);
+    }
   }
   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() };
+    const { data, content } = matter(text);
+    return { meta: data, body: content.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}]` : "";
+      const tagList = Array.isArray(s.meta.tags) ? s.meta.tags.join(", ") : s.meta.tags;
+      const tags = tagList ? ` [${tagList}]` : "";
       return `  - ${n}: ${s.meta.description ?? "No description"}${tags}`;
     }).join("\n");
   }
+  names() {
+    return Object.keys(this.skills);
+  }
   getContent(name) {
     const s = this.skills[name];
     if (!s) return `Error: Unknown skill '${name}'. Available: ${Object.keys(this.skills).join(", ")}`;
@@ -270,27 +277,144 @@ Available skills:
 ${opts.skills}`;
 }
 
+// src/paths.ts
+import { homedir } from "os";
+import { resolve as resolve2, join as join2 } from "path";
+import { createHash } from "crypto";
+function liteAgentHome() {
+  return process.env.LITE_AGENT_HOME || join2(homedir(), ".lite-agent");
+}
+function projectHash(workdir) {
+  return createHash("sha1").update(resolve2(workdir)).digest("hex").slice(0, 16);
+}
+function resolveProjectPaths(opts) {
+  const home = opts.home ?? liteAgentHome();
+  const hash = projectHash(opts.workdir);
+  const projectDir = join2(home, "projects", hash);
+  return {
+    home,
+    hash,
+    spillDir: join2(projectDir, "spill"),
+    sessionsDir: join2(projectDir, "sessions"),
+    globalSkillsDir: join2(home, "skills"),
+    projectSkillsDir: join2(resolve2(opts.workdir), ".lite-agent", "skills")
+  };
+}
+
+// src/store.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+function jsonlStore(opts) {
+  const fileFor = (id) => join3(opts.dir, `${id.replace(/[^a-zA-Z0-9_-]/g, "_")}.jsonl`);
+  return {
+    async load(id) {
+      const file = fileFor(id);
+      if (!existsSync2(file)) return null;
+      return readFileSync3(file, "utf8").split("\n").filter((line) => line.trim() !== "").map((line) => JSON.parse(line));
+    },
+    async save(id, messages) {
+      mkdirSync2(opts.dir, { recursive: true });
+      const body = messages.map((m) => JSON.stringify(m)).join("\n");
+      writeFileSync2(fileFor(id), messages.length ? body + "\n" : "");
+    }
+  };
+}
+
+// src/spill.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync4, existsSync as existsSync3 } from "fs";
+import { createHash as createHash2 } from "crypto";
+import { join as join4 } from "path";
+import { z as z6 } from "zod";
+import { defineTool as defineTool6 } from "@lite-agent/core";
+function fileSpillStore(opts) {
+  const fileFor = (ref) => join4(opts.dir, `${ref.replace(/[^a-f0-9]/gi, "")}.txt`);
+  return {
+    put(content) {
+      mkdirSync3(opts.dir, { recursive: true });
+      const ref = createHash2("sha1").update(content).digest("hex").slice(0, 16);
+      writeFileSync3(fileFor(ref), content);
+      return ref;
+    },
+    get(ref) {
+      const file = fileFor(ref);
+      return existsSync3(file) ? readFileSync4(file, "utf8") : null;
+    }
+  };
+}
+function readSpilledTool(store) {
+  return defineTool6({
+    name: "read_spilled",
+    description: "Retrieve the full content of a tool result that was moved off-context to save space. Pass the ref shown in its [spilled:<ref>] marker.",
+    schema: z6.object({ ref: z6.string() }),
+    execute: ({ ref }) => store.get(ref) ?? `No spilled content for ref '${ref}'`
+  });
+}
+
+// src/cleanup.ts
+import { existsSync as existsSync4, readdirSync as readdirSync2, statSync, rmSync } from "fs";
+import { join as join5 } from "path";
+var DAY_MS = 864e5;
+function sweepStale(opts = {}) {
+  const home = opts.home ?? liteAgentHome();
+  const cutoff = Date.now() - (opts.maxAgeDays ?? 30) * DAY_MS;
+  try {
+    const projectsDir = join5(home, "projects");
+    if (!existsSync4(projectsDir)) return;
+    for (const project of readdirSync2(projectsDir)) {
+      for (const sub of ["spill", "sessions"]) {
+        const dir = join5(projectsDir, project, sub);
+        if (!existsSync4(dir)) continue;
+        for (const name of readdirSync2(dir)) {
+          const fp = join5(dir, name);
+          try {
+            if (statSync(fp).mtimeMs < cutoff) rmSync(fp);
+          } catch {
+          }
+        }
+      }
+    }
+  } catch {
+  }
+}
+
 // src/createLiteAgent.ts
 function createLiteAgent(cfg) {
+  const paths = resolveProjectPaths({ workdir: cfg.workdir, home: cfg.home });
+  if (cfg.cleanup !== false) {
+    sweepStale({
+      home: paths.home,
+      maxAgeDays: typeof cfg.cleanup === "object" ? cfg.cleanup.maxAgeDays : void 0
+    });
+  }
   let tools = [...defaultTools(cfg.workdir)];
+  const loader = new SkillLoader([
+    paths.globalSkillsDir,
+    paths.projectSkillsDir,
+    ...cfg.skillsDir ? [cfg.skillsDir] : []
+  ]);
   let skills = "(no skills available)";
-  if (cfg.skillsDir) {
-    const loader = new SkillLoader(cfg.skillsDir);
+  if (loader.names().length > 0) {
     tools.push(loadSkillTool(loader));
     skills = loader.getDescriptions();
   }
+  const spillEnabled = cfg.spill !== false;
+  const spillStore = spillEnabled ? fileSpillStore({ dir: paths.spillDir }) : void 0;
+  if (spillStore) tools.push(readSpilledTool(spillStore));
   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 system = cfg.system ?? buildSystemPrompt({ workdir: cfg.workdir, modelName: cfg.modelName, skills });
+  const compactor = cfg.compactor === false ? void 0 : cfg.compactor ?? defaultCompactor({
+    spillStore,
+    budgetBytes: typeof cfg.spill === "object" ? cfg.spill.budgetBytes : void 0
   });
+  const store = cfg.store ?? (cfg.sessions === false ? void 0 : jsonlStore({ dir: paths.sessionsDir }));
   const use = [
+    // proactive compaction (beforeModel) + reactive overflow net (wrapModelCall)
+    ...compactor ? [compaction(compactor), reactiveCompaction()] : [],
     ...cfg.permission ? [permission(cfg.permission, cfg.onApproval)] : [],
     ...cfg.use ?? []
   ];
@@ -304,6 +428,7 @@ function createLiteAgent(cfg) {
     maxTurns: cfg.maxTurns,
     maxTokens: cfg.maxTokens,
     sandbox: cfg.sandbox,
+    store,
     input: cfg.onAskUser
   });
 }
@@ -323,6 +448,12 @@ function query(opts) {
     maxTokens: opts.maxTokens,
     use: opts.use,
     sandbox: opts.sandbox,
+    store: opts.store,
+    compactor: opts.compactor,
+    home: opts.home,
+    sessions: opts.sessions,
+    spill: opts.spill,
+    cleanup: opts.cleanup,
     permission: opts.permission,
     onApproval: opts.onApproval,
     onAskUser: opts.onAskUser
@@ -334,9 +465,9 @@ function query(opts) {
 }
 
 // src/tool.ts
-import { defineTool as defineTool6 } from "@lite-agent/core";
+import { defineTool as defineTool7 } from "@lite-agent/core";
 function tool(name, description, schema, handler) {
-  return defineTool6({ name, description, schema, execute: handler });
+  return defineTool7({ name, description, schema, execute: handler });
 }
 export {
   SkillLoader,
@@ -345,10 +476,17 @@ export {
   buildSystemPrompt,
   createLiteAgent,
   defaultTools,
+  fileSpillStore,
   fileTools,
+  jsonlStore,
+  liteAgentHome,
   loadSkillTool,
   makeSafePath,
+  projectHash,
   query,
+  readSpilledTool,
+  resolveProjectPaths,
+  sweepStale,
   todoTool,
   tool
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lite-agent/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Batteries-included agent SDK over @lite-agent/core: tools, skills, system prompt, and query()/createLiteAgent().",
   "license": "ISC",
   "type": "module",
@@ -34,19 +34,20 @@
   "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"
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.6",
+    "@lite-agent/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.3.0",
     "typescript": "^6.0.2",
     "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}