@agent-api/sdk 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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

package/README.md

@@ -96,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");
+}

package/dist/local/core.d.ts

@@ -0,0 +1,382 @@
+import type { LocalSkillDirectoryOptions } from "../local-skills.js";
+import type { LocalSkillDescriptor } from "../types/skills.js";
+export interface LocalAppDirs {
+    home: string;
+    data: string;
+    config: string;
+    cache: string;
+    logs: string;
+    temp: string;
+}
+export interface LocalRuntimeOptions {
+    appName: string;
+    appAuthor?: string;
+    baseDir?: string;
+    dirs?: Partial<Omit<LocalAppDirs, "home">>;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+}
+export interface LocalFileStoreOptions {
+    label?: string;
+}
+export declare class LocalError extends Error {
+    readonly code: string;
+    readonly path?: string;
+    constructor(code: string, message: string, options?: {
+        path?: string;
+        cause?: unknown;
+    });
+}
+export declare class LocalPathError extends LocalError {
+    constructor(message: string, path?: string);
+}
+export declare class LocalIgnoredPathError extends LocalError {
+    constructor(path: string);
+}
+export declare class LocalFileTooLargeError extends LocalError {
+    constructor(path: string);
+}
+export declare class LocalNotTextFileError extends LocalError {
+    constructor(path: string);
+}
+export declare class LocalConfigError extends LocalError {
+    constructor(message: string, path?: string);
+}
+export type LocalFileType = "file" | "directory" | "symlink" | "other";
+export interface LocalFileStat {
+    path: string;
+    fullPath: string;
+    type: LocalFileType;
+    size: number;
+    modifiedAt: Date;
+}
+export interface LocalListOptions {
+    recursive?: boolean;
+    includeDirectories?: boolean;
+    maxDepth?: number;
+    ignore?: Array<string | RegExp | ((relativePath: string) => boolean)>;
+}
+export type LocalIgnoreRule = NonNullable<LocalListOptions["ignore"]>[number];
+export interface LocalEntry {
+    path: string;
+    is_dir: boolean;
+    size: number;
+    modified_at_unix?: number;
+}
+export interface LocalEntryList {
+    object: "list";
+    entries: LocalEntry[];
+}
+export interface LocalSearchEntriesParams {
+    query: string;
+    path?: string;
+    limit?: number;
+}
+export interface LocalReadFileParams {
+    maxBytes?: number;
+    format?: "text";
+}
+export interface LocalReadFileRawParams {
+    maxBytes?: number;
+    format: "raw";
+}
+export interface LocalFileDeliver {
+    path: string;
+    encoding: "text" | "base64";
+    mime_type: string;
+    size: number;
+    truncated: boolean;
+    content?: string;
+    content_base64?: string;
+}
+export interface LocalFileRaw {
+    path: string;
+    size: number;
+    truncated: boolean;
+    content: Uint8Array;
+    content_type?: string;
+}
+export interface LocalFileWrite {
+    path: string;
+    size: number;
+}
+export interface LocalPathDelete {
+    path: string;
+    recursive: boolean;
+}
+export interface LocalReadLinesParams {
+    startLine: number;
+    endLine?: number;
+    maxBytes?: number;
+}
+export interface LocalFileLines {
+    path: string;
+    start_line: number;
+    end_line: number;
+    total_lines: number;
+    lines: string[];
+    file_truncated: boolean;
+    size: number;
+}
+export interface LocalPatchLinesParams {
+    startLine: number;
+    endLine?: number;
+    replacement?: string;
+    maxBytes?: number;
+}
+export interface LocalFileLinesPatch {
+    path: string;
+    start_line: number;
+    end_line: number;
+    total_lines: number;
+    size: number;
+}
+export interface LocalGrepParams {
+    pattern: string;
+    path?: string;
+    limit?: number;
+    maxFiles?: number;
+    maxBytesPerFile?: number;
+    maxLineLength?: number;
+    ignore?: LocalListOptions["ignore"];
+}
+export interface LocalGrepMatch {
+    path: string;
+    line_number: number;
+    line: string;
+}
+export interface LocalGrepResponse {
+    object: "list";
+    matches: LocalGrepMatch[];
+    files_scanned: number;
+    scan_truncated: boolean;
+}
+export interface LocalSummarizeParams {
+    path?: string;
+    maxFiles?: number;
+    maxPreviews?: number;
+    previewBytes?: number;
+    topPaths?: number;
+    ignore?: LocalListOptions["ignore"];
+}
+export interface LocalSummaryPreview {
+    path: string;
+    size: number;
+    preview: string;
+    preview_truncated?: boolean;
+}
+export interface LocalSummary {
+    summary_path: string;
+    file_count: number;
+    total_bytes: number;
+    top_paths_by_size: string[];
+    text_previews: LocalSummaryPreview[];
+    generated_at_unix: number;
+    scan_truncated: boolean;
+}
+export interface LocalWorkspaceOptions {
+    name?: string;
+    metadata?: Record<string, unknown>;
+    trusted?: boolean;
+    ignore?: LocalIgnoreRule[];
+    gitignore?: boolean;
+    maxFileBytes?: number;
+}
+export interface LocalWorkspaceSnapshotParams {
+    path?: string;
+    hash?: boolean;
+    maxBytesPerFile?: number;
+}
+export interface LocalWorkspaceSnapshotFile {
+    path: string;
+    size: number;
+    modified_at_unix?: number;
+    sha256?: string;
+}
+export interface LocalWorkspaceSnapshot {
+    root: string;
+    name: string;
+    generated_at_unix: number;
+    files: LocalWorkspaceSnapshotFile[];
+}
+export interface LocalWorkspaceDiff {
+    added: LocalWorkspaceSnapshotFile[];
+    modified: Array<{
+        before: LocalWorkspaceSnapshotFile;
+        after: LocalWorkspaceSnapshotFile;
+    }>;
+    deleted: LocalWorkspaceSnapshotFile[];
+    unchanged: LocalWorkspaceSnapshotFile[];
+}
+export interface LocalLinePatchPreview {
+    path: string;
+    start_line: number;
+    end_line: number;
+    total_lines: number;
+    before: string[];
+    after: string[];
+}
+export interface LocalWorkspaceLineEdit {
+    path: string;
+    startLine: number;
+    endLine?: number;
+    replacement?: string;
+    expectedSha256?: string;
+}
+export interface LocalWorkspaceEditPlan {
+    edits: LocalWorkspaceLineEdit[];
+    previews: LocalLinePatchPreview[];
+}
+export interface LocalWorkspaceEditResult {
+    applied: LocalFileLinesPatch[];
+    backups: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export type LocalPathSensitivity = "normal" | "sensitive" | "secret";
+export interface LocalPathSensitivityInfo {
+    path: string;
+    sensitivity: LocalPathSensitivity;
+    reason?: string;
+}
+export interface LocalWorkspaceWatchEvent {
+    type: "change" | "rename";
+    path: string;
+}
+export interface LocalWorkspaceWatcher {
+    close(): void;
+}
+export interface LocalSkillDiscoveryOptions extends LocalSkillDirectoryOptions {
+    roots?: string[];
+    recursive?: boolean;
+    maxDepth?: number;
+}
+export interface LocalRuntime {
+    appName: string;
+    dirs: LocalAppDirs;
+    files: LocalFileStore;
+    data: LocalFileStore;
+    cache: LocalFileStore;
+    logs: LocalFileStore;
+    temp: LocalFileStore;
+    config: LocalConfigStore;
+    skills: LocalSkillStore;
+    workspaces: LocalWorkspaceManager;
+    workspace(root: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+    ensure(): Promise<void>;
+}
+export declare function createLocalRuntime(options: LocalRuntimeOptions): LocalRuntime;
+export declare function localAppDirs(options: LocalRuntimeOptions): LocalAppDirs;
+export declare class LocalFileStore {
+    readonly root: string;
+    readonly label: string;
+    constructor(root: string, options?: LocalFileStoreOptions);
+    child(relativePath: string, options?: LocalFileStoreOptions): LocalFileStore;
+    ensure(): Promise<void>;
+    resolvePath(relativePath?: string): string;
+    relativePath(fullPath: string): string;
+    exists(relativePath?: string): Promise<boolean>;
+    stat(relativePath?: string): Promise<LocalFileStat>;
+    mkdir(relativePath?: string): Promise<string>;
+    list(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStat[]>;
+    listEntries(relativePath?: string, options?: LocalListOptions): Promise<LocalEntryList>;
+    searchEntries(params: LocalSearchEntriesParams): Promise<LocalEntryList>;
+    readText(relativePath: string): Promise<string>;
+    readJSON<T = unknown>(relativePath: string): Promise<T>;
+    readBytes(relativePath: string): Promise<Uint8Array>;
+    readFile(relativePath: string, params: LocalReadFileRawParams): Promise<LocalFileRaw>;
+    readFile(relativePath: string, params?: LocalReadFileParams): Promise<LocalFileDeliver>;
+    writeText(relativePath: string, content: string, options?: {
+        atomic?: boolean;
+    }): Promise<string>;
+    writeJSON(relativePath: string, value: unknown, options?: {
+        pretty?: boolean;
+        atomic?: boolean;
+    }): Promise<string>;
+    writeBytes(relativePath: string, content: Uint8Array, options?: {
+        atomic?: boolean;
+    }): Promise<string>;
+    writeFile(relativePath: string, content: string | Uint8Array, options?: {
+        atomic?: boolean;
+    }): Promise<LocalFileWrite>;
+    remove(relativePath: string): Promise<void>;
+    deletePath(relativePath: string): Promise<LocalPathDelete>;
+    createDirectory(relativePath?: string): Promise<{
+        path: string;
+    }>;
+    copy(fromRelativePath: string, toRelativePath: string): Promise<string>;
+    readLines(relativePath: string, params: LocalReadLinesParams): Promise<LocalFileLines>;
+    patchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalFileLinesPatch>;
+    grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
+    summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
+    private walk;
+}
+export declare class LocalConfigStore {
+    readonly files: LocalFileStore;
+    constructor(files: LocalFileStore);
+    read<T = Record<string, unknown>>(name?: string, fallback?: T): Promise<T>;
+    write(name: string, value: unknown): Promise<string>;
+    get<T = unknown>(name: string, key: string, fallback?: T): Promise<T>;
+    set(name: string, key: string, value: unknown): Promise<string>;
+    delete(name: string, key: string): Promise<string>;
+    private readRecord;
+}
+export declare class LocalWorkspaceManager {
+    open(root: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+}
+export declare class LocalWorkspace {
+    readonly root: string;
+    readonly name: string;
+    readonly metadata: Record<string, unknown>;
+    readonly trusted: boolean;
+    readonly files: LocalFileStore;
+    readonly ignore: LocalIgnoreRule[];
+    readonly gitignore: boolean;
+    readonly maxFileBytes: number;
+    constructor(root: string, options?: LocalWorkspaceOptions);
+    ensure(): Promise<void>;
+    loadIgnoreFiles(files?: string[]): Promise<LocalIgnoreRule[]>;
+    child(relativePath: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+    resolvePath(relativePath?: string): string;
+    list(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStat[]>;
+    listEntries(relativePath?: string, options?: LocalListOptions): Promise<LocalEntryList>;
+    searchEntries(params: LocalSearchEntriesParams): Promise<LocalEntryList>;
+    readFile(relativePath: string, params: LocalReadFileRawParams): Promise<LocalFileRaw>;
+    readFile(relativePath: string, params?: LocalReadFileParams): Promise<LocalFileDeliver>;
+    writeFile(relativePath: string, content: string | Uint8Array, options?: {
+        atomic?: boolean;
+    }): Promise<LocalFileWrite>;
+    readText(relativePath: string): Promise<string>;
+    writeText(relativePath: string, content: string, options?: {
+        atomic?: boolean;
+    }): Promise<string>;
+    deletePath(relativePath: string): Promise<LocalPathDelete>;
+    createDirectory(relativePath?: string): Promise<{
+        path: string;
+    }>;
+    readLines(relativePath: string, params: LocalReadLinesParams): Promise<LocalFileLines>;
+    previewPatchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalLinePatchPreview>;
+    patchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalFileLinesPatch>;
+    previewEdits(edits: LocalWorkspaceLineEdit[]): Promise<LocalWorkspaceEditPlan>;
+    applyEdits(edits: LocalWorkspaceLineEdit[]): Promise<LocalWorkspaceEditResult>;
+    classifyPath(relativePath: string): LocalPathSensitivityInfo;
+    grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
+    summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
+    snapshot(params?: LocalWorkspaceSnapshotParams): Promise<LocalWorkspaceSnapshot>;
+    diff(before: LocalWorkspaceSnapshot, after: LocalWorkspaceSnapshot): LocalWorkspaceDiff;
+    watch(onEvent: (event: LocalWorkspaceWatchEvent) => void, options?: {
+        recursive?: boolean;
+    }): LocalWorkspaceWatcher;
+    private scopedListOptions;
+    private mergeIgnore;
+    private assertAllowed;
+    private assertExpectedHash;
+}
+export declare class LocalSkillStore {
+    readonly files: LocalFileStore;
+    constructor(files: LocalFileStore);
+    fromDirectory(rootDir: string, options?: LocalSkillDirectoryOptions): Promise<LocalSkillDescriptor>;
+    discover(options?: LocalSkillDiscoveryOptions): Promise<LocalSkillDescriptor[]>;
+}
+export declare function classifyLocalPathSensitivity(relativePath: string): LocalPathSensitivityInfo;