@agent-api/sdk 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — @agent-api/sdk
 
+## 1.1.0
+
+### Added
+
+- Node-only `@agent-api/sdk/local` entrypoint for framework-neutral local app and CLI runtime support.
+- Cross-platform app directory resolution for data, config, cache, logs, and temp files.
+- Root-scoped local file stores with path traversal protection, atomic writes, JSON helpers, recursive listing, and local skill discovery.
+- Local workdir operations for entry search, file delivery, line-range reads and edits, literal grep, and directory summaries.
+- `LocalWorkspace` and `LocalWorkspaceManager` for project roots, default ignore rules, patch previews, snapshots, diffs, and file-watch handles.
+- Typed local errors, `.gitignore` loading, sensitivity classification for likely secret paths, and multi-file line-edit plans with conflict detection and rollback.
+- `createLocalContextPackage()` for bounded, secret-aware local workspace manifests that app integrations can hand to agent workflows.
+
+### Changed
+
+- Split the local SDK source behind a small `@agent-api/sdk/local` barrel so runtime and context APIs can grow without a monolithic entrypoint.
+
+## 1.0.8
+
+### Changed
+
+- Expanded `reasoning.effort` types to match the Responses-compatible enum: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
+
+## 1.0.7
+
+### Added
+
+- Skill artifact archive APIs: `client.skills.exportArchive()` and `client.skills.importArchive()`.
+- Local directory sync helpers for platform skills: `client.skills.pushDirectory()` and `client.skills.pullDirectory()`.
+- Skill branch diff API and file-level `acceptDev()` strategies (`patch` or `mirror`).
+
 ## 1.0.6
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 Production JavaScript/TypeScript SDK for the Managed Agent API.
 
-**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.0.6)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.0.8)
 
 ## Install
 
@@ -60,7 +60,7 @@ src/
 | `client.presets` | `list` |
 | `client.tools` | `list` |
 | `client.volumes` | `list`, `create`, `retrieve`, `update`, `delete`, `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `reconcileUsage`, `createDirectory`, `downloadArchive`, `summarize`, `readLines`, `patchLines`, `grep` |
-| `client.skills` | `list`, `create`, `discover`, `focus`, `createDev`, `updateFile`, `retrieve`, `update`, `archive`, `delete`, `acceptDev`, `discardDev`, `listFiles`, `readFile`, `writeFile`, `deleteFile` |
+| `client.skills` | `list`, `create`, `discover`, `focus`, `createDev`, `updateFile`, `retrieve`, `update`, `archive`, `delete`, `diff`, `acceptDev`, `discardDev`, `exportArchive`, `importArchive`, `pushDirectory`, `pullDirectory`, `listFiles`, `readFile`, `writeFile`, `deleteFile` |
 
 ## Durable Volumes
 
@@ -80,6 +80,8 @@ const response = await client.agent.create({
 
 ## Skills
 
+`localSkillFromDirectory()` reads `SKILL.md` into the descriptor for initial local-skill auto-focus; later focused reads still use the local skill tool bridge.
+
 ```typescript
 import { localSkillFromDirectory } from "@agent-api/sdk";
 
@@ -94,6 +96,93 @@ const response = await client.responses.create({
 });
 ```
 
+## Local Runtime
+
+Local app integrations can use the Node-only `@agent-api/sdk/local` entrypoint for core filesystem/runtime support. This layer is framework-neutral: it does not depend on Electron, Tauri, native UI kits, or browser APIs.
+
+```typescript
+import { createLocalRuntime } from "@agent-api/sdk/local";
+
+const local = createLocalRuntime({
+  appName: "agent-studio",
+});
+
+await local.ensure();
+
+await local.config.set("settings.json", "baseURL", "https://api.agentsway.dev");
+const baseURL = await local.config.get<string>("settings.json", "baseURL");
+
+await local.cache.writeJSON("models.json", [{ id: "openai/gpt-5.5" }]);
+const skills = await local.skills.discover();
+```
+
+The runtime provides:
+
+- Cross-platform app directories for data, config, cache, logs, and temp files.
+- Root-scoped file stores with path traversal protection.
+- Atomic text/JSON writes, byte reads/writes, recursive listing, copy, remove, and stat helpers.
+- Local workdir operations inspired by platform volumes: `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `createDirectory`, `readLines`, `patchLines`, `grep`, and `summarize`.
+- First-class local workspaces with default ignore rules, scoped workbench operations, patch previews, snapshots, diffs, file-watch handles, and budgeted context packaging.
+- Typed local errors, `.gitignore` loading, sensitivity classification, and multi-file edit plans with rollback on failure.
+- JSON config helpers for typed app settings.
+- Local skill discovery built on `localSkillFromDirectory()`.
+
+Keep UI and OS interaction policy in your host framework. Electron, Tauri, Qt, or native apps should call this layer from their trusted local process and expose only the capabilities their UI needs.
+
+```typescript
+const workspace = local.data.child("workspaces/demo");
+
+await workspace.writeText("src/index.ts", "console.log('hello');\n");
+
+const matches = await workspace.grep({ pattern: "hello", path: "src" });
+const lines = await workspace.readLines("src/index.ts", { startLine: 1, endLine: 20 });
+await workspace.patchLines("src/index.ts", {
+  startLine: 1,
+  replacement: "console.log('patched');",
+});
+
+const summary = await workspace.summarize();
+```
+
+For project/workspace roots, prefer `local.workspace()` so SDK defaults protect common generated directories such as `.git`, `node_modules`, `dist`, and build caches.
+
+```typescript
+const project = local.workspace("/path/to/project", {
+  name: "my-project",
+  trusted: true,
+  ignore: ["vendor", /^tmp\//],
+});
+await project.loadIgnoreFiles();
+
+const before = await project.snapshot();
+const plan = await project.previewEdits([
+  {
+    path: "src/index.ts",
+    startLine: 1,
+    endLine: 1,
+    replacement: "console.log('patched');",
+  },
+]);
+await project.applyEdits(plan.edits);
+const after = await project.snapshot();
+const diff = project.diff(before, after);
+
+const sensitivity = project.classifyPath(".env");
+```
+
+Use `createLocalContextPackage()` when a local app needs to prepare bounded workspace context for an agent request. The package includes a manifest, selected file previews, optional search matches, hashes, sensitivity labels, and secret-aware omission by default.
+
+```typescript
+import { createLocalContextPackage } from "@agent-api/sdk/local";
+
+const context = await createLocalContextPackage(project, {
+  query: "billing",
+  includeSearch: true,
+  maxFiles: 80,
+  maxBytes: 256 * 1024,
+});
+```
+
 ## Production features
 
 - **Retries:** automatic exponential backoff for network failures, 429, and 5xx (default 2 retries).

package/dist/local/context.d.ts

@@ -0,0 +1,49 @@
+import { type LocalFileDeliver, type LocalGrepResponse, type LocalPathSensitivity, type LocalPathSensitivityInfo, type LocalSummary, type LocalWorkspace, type LocalWorkspaceSnapshotFile } from "./core.js";
+export interface LocalContextPackageParams {
+    path?: string;
+    include?: string[];
+    exclude?: string[];
+    query?: string;
+    maxFiles?: number;
+    maxBytes?: number;
+    maxBytesPerFile?: number;
+    previewBytes?: number;
+    includeContent?: boolean;
+    includeHashes?: boolean;
+    includeSummary?: boolean;
+    includeSearch?: boolean;
+    includeSecrets?: boolean;
+}
+export interface LocalContextFile {
+    path: string;
+    size: number;
+    sha256?: string;
+    mime_type?: string;
+    sensitivity: LocalPathSensitivity;
+    sensitivity_reason?: string;
+    content?: string;
+    content_base64?: string;
+    encoding?: LocalFileDeliver["encoding"];
+    truncated?: boolean;
+    omitted_reason?: string;
+}
+export interface LocalContextManifest {
+    object: "local_context_manifest";
+    root: string;
+    workspace_name: string;
+    generated_at_unix: number;
+    base_path: string;
+    file_count: number;
+    total_bytes: number;
+    included_bytes: number;
+    truncated: boolean;
+    files: LocalContextFile[];
+    summary?: LocalSummary;
+    search?: LocalGrepResponse;
+}
+export declare function createLocalContextPackage(workspace: LocalWorkspace, params?: LocalContextPackageParams): Promise<LocalContextManifest>;
+export declare function summarizeLocalContextSensitivity(files: Array<Pick<LocalContextFile, "path" | "sensitivity" | "sensitivity_reason">>): {
+    highest: LocalPathSensitivity;
+    files: LocalPathSensitivityInfo[];
+};
+export type LocalContextSnapshotFile = LocalWorkspaceSnapshotFile;

package/dist/local/context.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { classifyLocalPathSensitivity, } from "./core.js";
+export async function createLocalContextPackage(workspace, params = {}) {
+    const basePath = params.path ?? ".";
+    const maxFiles = positiveInt(params.maxFiles, 80);
+    const maxBytes = positiveInt(params.maxBytes, 256 * 1024);
+    const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 32 * 1024);
+    const previewBytes = positiveInt(params.previewBytes, maxBytesPerFile);
+    const includeContent = params.includeContent ?? true;
+    const includeHashes = params.includeHashes ?? true;
+    const includeSummary = params.includeSummary ?? true;
+    const includeSearch = Boolean(params.includeSearch && params.query?.trim());
+    const includeSecrets = params.includeSecrets ?? false;
+    const stats = await workspace.list(basePath, { recursive: true });
+    const fileStats = stats
+        .filter((item) => item.type === "file")
+        .filter((item) => matchesPathFilters(item.path, params.include, params.exclude))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const files = [];
+    let includedBytes = 0;
+    let truncated = fileStats.length > maxFiles;
+    for (const item of fileStats.slice(0, maxFiles)) {
+        const sensitivity = classifyLocalPathSensitivity(item.path);
+        const baseFile = {
+            path: item.path,
+            size: item.size,
+            sensitivity: sensitivity.sensitivity,
+            sensitivity_reason: sensitivity.reason,
+        };
+        if (!includeSecrets && sensitivity.sensitivity === "secret") {
+            files.push({ ...baseFile, omitted_reason: "secret_path" });
+            continue;
+        }
+        if (item.size > maxBytesPerFile) {
+            files.push({ ...baseFile, omitted_reason: "file_too_large" });
+            truncated = true;
+            continue;
+        }
+        if (includedBytes >= maxBytes) {
+            files.push({ ...baseFile, omitted_reason: "package_budget_exceeded" });
+            truncated = true;
+            continue;
+        }
+        const remaining = maxBytes - includedBytes;
+        const readBudget = Math.min(previewBytes, maxBytesPerFile, remaining);
+        if (readBudget <= 0) {
+            files.push({ ...baseFile, omitted_reason: "package_budget_exceeded" });
+            truncated = true;
+            continue;
+        }
+        const delivered = await workspace.readFile(item.path, { maxBytes: readBudget });
+        includedBytes += delivered.encoding === "text"
+            ? Buffer.byteLength(delivered.content ?? "", "utf8")
+            : Buffer.byteLength(delivered.content_base64 ?? "", "base64");
+        const packaged = {
+            ...baseFile,
+            mime_type: delivered.mime_type,
+            encoding: delivered.encoding,
+            truncated: delivered.truncated || undefined,
+        };
+        if (includeContent) {
+            packaged.content = delivered.content;
+            packaged.content_base64 = delivered.content_base64;
+        }
+        if (includeHashes) {
+            packaged.sha256 = await sha256File(workspace, item.path);
+        }
+        if (delivered.truncated) {
+            truncated = true;
+        }
+        files.push(packaged);
+    }
+    const summary = includeSummary
+        ? await workspace.summarize({
+            path: basePath,
+            maxFiles,
+            previewBytes,
+            ignore: params.exclude,
+        })
+        : undefined;
+    const search = includeSearch
+        ? await workspace.grep({
+            pattern: params.query,
+            path: basePath,
+            limit: maxFiles,
+            maxBytesPerFile,
+            ignore: params.exclude,
+        })
+        : undefined;
+    return {
+        object: "local_context_manifest",
+        root: workspace.root,
+        workspace_name: workspace.name,
+        generated_at_unix: Math.floor(Date.now() / 1000),
+        base_path: basePath,
+        file_count: fileStats.length,
+        total_bytes: fileStats.reduce((sum, item) => sum + item.size, 0),
+        included_bytes: includedBytes,
+        truncated,
+        files,
+        summary,
+        search,
+    };
+}
+export function summarizeLocalContextSensitivity(files) {
+    const order = { normal: 0, sensitive: 1, secret: 2 };
+    let highest = "normal";
+    const sensitiveFiles = [];
+    for (const file of files) {
+        if (order[file.sensitivity] > order[highest]) {
+            highest = file.sensitivity;
+        }
+        if (file.sensitivity !== "normal") {
+            sensitiveFiles.push({
+                path: file.path,
+                sensitivity: file.sensitivity,
+                reason: file.sensitivity_reason,
+            });
+        }
+    }
+    return { highest, files: sensitiveFiles };
+}
+function matchesPathFilters(relativePath, include, exclude) {
+    if (include?.length && !include.some((pattern) => pathMatches(relativePath, pattern))) {
+        return false;
+    }
+    if (exclude?.some((pattern) => pathMatches(relativePath, pattern))) {
+        return false;
+    }
+    return true;
+}
+function pathMatches(relativePath, pattern) {
+    const clean = pattern.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!clean || clean === ".") {
+        return true;
+    }
+    if (!clean.includes("*")) {
+        return relativePath === clean || relativePath.startsWith(`${clean}/`);
+    }
+    const escaped = clean
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${escaped}$`).test(relativePath);
+}
+function positiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : fallback;
+}
+async function sha256File(workspace, relativePath) {
+    const fullPath = workspace.files.resolvePath(relativePath);
+    return createHash("sha256").update(await readFile(fullPath)).digest("hex");
+}