@nkmc/agent-fs 0.1.0

package/dist/rpc-D1IHpjF_.d.cts

@@ -0,0 +1,330 @@
+/** The 5 filesystem operations */
+type FsOp = "ls" | "cat" | "write" | "rm" | "grep";
+/** A parsed command from the LLM */
+interface FsCommand {
+    op: FsOp;
+    path: string;
+    data?: unknown;
+    pattern?: string;
+}
+/** Result of a filesystem operation */
+type FsResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: FsError;
+};
+/** Error types */
+type FsError = {
+    code: "PARSE_ERROR";
+    message: string;
+} | {
+    code: "INVALID_PATH";
+    message: string;
+} | {
+    code: "NOT_FOUND";
+    message: string;
+} | {
+    code: "PERMISSION_DENIED";
+    message: string;
+} | {
+    code: "NO_MOUNT";
+    message: string;
+} | {
+    code: "BACKEND_ERROR";
+    message: string;
+};
+/** Agent identity context passed through the call chain */
+interface AgentContext {
+    id: string;
+    roles: string[];
+}
+/** Access role for permissions */
+type AccessRole = "public" | "agent" | "premium" | "admin" | string;
+/** Mount point configuration — maps a virtual path to a backend */
+interface Mount {
+    path: string;
+    backend: FsBackend;
+    permissions?: {
+        read?: AccessRole[];
+        write?: AccessRole[];
+    };
+}
+/** The interface every backend must implement */
+interface FsBackend {
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+}
+
+/** Auth configuration for HTTP requests */
+type HttpAuth = {
+    type: "bearer";
+    token: string;
+    prefix?: string;
+} | {
+    type: "api-key";
+    header: string;
+    key: string;
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "oauth2";
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+};
+/** A resource (collection-like, from skill.md Schema section) */
+interface HttpResource {
+    /** Name used in filesystem path: /mount/{name}/ */
+    name: string;
+    /** API base path for this resource. Defaults to /{name} */
+    apiPath?: string;
+    /** Field name for record ID in API responses. Defaults to "id" */
+    idField?: string;
+    /** Key to extract array from list response. e.g. "result" for Cloudflare, "data" for others */
+    listKey?: string;
+    /** Schema fields (for _schema support) */
+    fields?: {
+        name: string;
+        type: string;
+        description?: string;
+    }[];
+    /** Child resources (for nested paths like /zones/{id}/dns_records) */
+    children?: HttpResource[];
+    /** "tree" mode: all remaining path segments form the ID (for file-tree APIs) */
+    pathMode?: "tree";
+    /** Override HTTP method for updates. Default "PUT" */
+    updateMethod?: "PUT" | "PATCH";
+    /** Data transformation hooks */
+    transform?: {
+        /** Transform item after GET response */
+        read?: (data: unknown) => unknown;
+        /** Transform data before POST/PUT body */
+        write?: (data: unknown) => unknown;
+        /** Build DELETE body from read result */
+        remove?: (readResult: unknown | null) => unknown;
+        /** Format each list item to display string. Default: item[idField] + ".json" */
+        list?: (item: unknown) => string;
+    };
+    /** Auto-read before write/delete to obtain fields like SHA, ETag */
+    readBeforeWrite?: {
+        inject: (readResult: unknown, writeData: unknown) => unknown;
+    };
+}
+/** An API endpoint (invocation-like, from skill.md API section) */
+interface HttpEndpoint {
+    /** Name used in filesystem path: /mount/_api/{name} */
+    name: string;
+    /** HTTP method */
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** API path */
+    apiPath: string;
+    /** Description */
+    description?: string;
+}
+/** Configuration for HttpBackend */
+interface HttpBackendConfig {
+    /** Base URL of the API (e.g. "https://api.cloudflare.com/client/v4") */
+    baseUrl: string;
+    /** Authentication */
+    auth?: HttpAuth;
+    /** Resource definitions (from skill.md Schema section) */
+    resources?: HttpResource[];
+    /** API endpoint definitions (from skill.md API section) */
+    endpoints?: HttpEndpoint[];
+    /** Static parameters for template resolution (e.g. { accountId: "abc123" }) */
+    params?: Record<string, string>;
+    /** Body encoding: "json" (default) or "form" (application/x-www-form-urlencoded) */
+    bodyEncoding?: "json" | "form";
+    /** Custom fetch function (for testing) */
+    fetch?: typeof globalThis.fetch;
+    /** Auto-pagination for list operations */
+    pagination?: PaginationConfig;
+    /** Retry configuration for transient errors (429, 5xx) */
+    retry?: {
+        /** Max retry attempts (default 3) */
+        maxRetries?: number;
+        /** Base delay in ms for exponential backoff (default 1000) */
+        baseDelayMs?: number;
+    };
+}
+/** Pagination configuration — supports multiple strategies */
+type PaginationConfig = {
+    type: "link-header";
+    maxPages?: number;
+} | {
+    type: "cursor";
+    cursorParam: string;
+    cursorPath: string;
+    maxPages?: number;
+} | {
+    type: "offset";
+    offsetParam?: string;
+    limitParam?: string;
+    pageSize?: number;
+    maxPages?: number;
+} | {
+    type: "page";
+    pageParam?: string;
+    maxPages?: number;
+};
+/**
+ * HTTP-based FsBackend driven by skill.md descriptions.
+ *
+ * Filesystem mapping (flat):
+ *   ls /                        → list resources + endpoints
+ *   ls /{resource}/             → GET baseUrl/{apiPath}  (list records)
+ *   cat /{resource}/{id}.json   → GET baseUrl/{apiPath}/{id}  (read record)
+ *   write /{resource}/ data     → POST baseUrl/{apiPath}  (create)
+ *   write /{resource}/{id} data → PUT baseUrl/{apiPath}/{id}  (update)
+ *   rm /{resource}/{id}.json    → DELETE baseUrl/{apiPath}/{id}
+ *   grep pattern /{resource}/   → GET baseUrl/{apiPath}?q={pattern}  (search)
+ *
+ * Nested resources:
+ *   ls /{parent}/{pid}/                   → list child resource directories
+ *   ls /{parent}/{pid}/{child}/           → GET resolved nested path (list)
+ *   cat /{parent}/{pid}/{child}/{id}.json → GET resolved nested path/{id}
+ *
+ * Endpoints:
+ *   ls /_api/                   → list available endpoints
+ *   cat /_api/{name}            → GET endpoint (for GET endpoints)
+ *   write /_api/{name} data     → POST/PUT/etc endpoint (for non-GET endpoints)
+ */
+declare class HttpBackend implements FsBackend {
+    private baseUrl;
+    private auth?;
+    private resourceList;
+    private endpoints;
+    private params;
+    private _fetch;
+    private bodyEncoding;
+    private pagination?;
+    private retryConfig;
+    /** Cached OAuth2 access token */
+    private _oauth2Token?;
+    constructor(config: HttpBackendConfig);
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+    private request;
+    /** Obtain (or refresh) OAuth2 access token via client_credentials grant */
+    private getOAuth2Token;
+    /** Parse Link header to extract rel="next" URL */
+    private getNextPageUrl;
+    /** Fetch all items with optional pagination */
+    private fetchAllItems;
+    /** Format list items using transform.list or default idField + ".json" */
+    private formatListItems;
+    private getEndpoint;
+    /** Replace :param and {param} placeholders in API paths with values from config.params */
+    private resolveTemplate;
+    /** Recursively resolve a filesystem path against the resource tree */
+    private resolveResourcePath;
+    private parsePath;
+}
+
+/** Transport interface for RPC calls */
+interface RpcTransport {
+    call(method: string, params: unknown[]): Promise<unknown>;
+    batch?(calls: Array<{
+        method: string;
+        params: unknown[];
+    }>): Promise<unknown[]>;
+}
+/** Configuration for JSON-RPC 2.0 transport */
+interface JsonRpcTransportConfig {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    /** Retry configuration for transient errors (429, 5xx, -32603, -32000~-32099) */
+    retry?: {
+        /** Max retry attempts (default 3) */
+        maxRetries?: number;
+        /** Base delay in ms for exponential backoff (default 1000) */
+        baseDelayMs?: number;
+    };
+}
+/** JSON-RPC error with code and optional data */
+declare class RpcError extends Error {
+    code: number;
+    data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Context passed to RpcMethod.params callback */
+interface RpcCallContext {
+    id?: string;
+    data?: unknown;
+    pattern?: string;
+}
+/** Maps a filesystem operation to an RPC call */
+interface RpcMethod {
+    method: string;
+    params: (ctx: RpcCallContext) => unknown[];
+}
+/** A resource exposed as a directory in the filesystem */
+interface RpcResource {
+    name: string;
+    idField?: string;
+    methods: {
+        list?: RpcMethod;
+        read?: RpcMethod;
+        write?: RpcMethod;
+        create?: RpcMethod;
+        remove?: RpcMethod;
+        search?: RpcMethod;
+    };
+    transform?: {
+        read?: (data: unknown) => unknown;
+        write?: (data: unknown) => unknown;
+        remove?: (id: string) => unknown;
+        list?: (item: unknown) => string | string[];
+    };
+}
+/** Configuration for RpcBackend */
+interface RpcBackendConfig {
+    transport: RpcTransport;
+    resources: RpcResource[];
+}
+declare class JsonRpcTransport implements RpcTransport {
+    private url;
+    private headers;
+    private _fetch;
+    private nextId;
+    private retryConfig;
+    constructor(config: JsonRpcTransportConfig);
+    call(method: string, params: unknown[]): Promise<unknown>;
+    batch(calls: Array<{
+        method: string;
+        params: unknown[];
+    }>): Promise<unknown[]>;
+    /** Exponential backoff with jitter + Retry-After header support */
+    private backoff;
+}
+declare class RpcBackend implements FsBackend {
+    private transport;
+    private resources;
+    constructor(config: RpcBackendConfig);
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+    private parsePath;
+}
+
+export { type AgentContext as A, type FsResult as F, type HttpAuth as H, JsonRpcTransport as J, type Mount as M, type PaginationConfig as P, RpcBackend as R, type FsError as a, type FsBackend as b, type FsCommand as c, type AccessRole as d, type FsOp as e, HttpBackend as f, type HttpBackendConfig as g, type HttpEndpoint as h, type HttpResource as i, type JsonRpcTransportConfig as j, type RpcBackendConfig as k, type RpcCallContext as l, RpcError as m, type RpcMethod as n, type RpcResource as o, type RpcTransport as p };

package/dist/rpc-D1IHpjF_.d.ts

@@ -0,0 +1,330 @@
+/** The 5 filesystem operations */
+type FsOp = "ls" | "cat" | "write" | "rm" | "grep";
+/** A parsed command from the LLM */
+interface FsCommand {
+    op: FsOp;
+    path: string;
+    data?: unknown;
+    pattern?: string;
+}
+/** Result of a filesystem operation */
+type FsResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: FsError;
+};
+/** Error types */
+type FsError = {
+    code: "PARSE_ERROR";
+    message: string;
+} | {
+    code: "INVALID_PATH";
+    message: string;
+} | {
+    code: "NOT_FOUND";
+    message: string;
+} | {
+    code: "PERMISSION_DENIED";
+    message: string;
+} | {
+    code: "NO_MOUNT";
+    message: string;
+} | {
+    code: "BACKEND_ERROR";
+    message: string;
+};
+/** Agent identity context passed through the call chain */
+interface AgentContext {
+    id: string;
+    roles: string[];
+}
+/** Access role for permissions */
+type AccessRole = "public" | "agent" | "premium" | "admin" | string;
+/** Mount point configuration — maps a virtual path to a backend */
+interface Mount {
+    path: string;
+    backend: FsBackend;
+    permissions?: {
+        read?: AccessRole[];
+        write?: AccessRole[];
+    };
+}
+/** The interface every backend must implement */
+interface FsBackend {
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+}
+
+/** Auth configuration for HTTP requests */
+type HttpAuth = {
+    type: "bearer";
+    token: string;
+    prefix?: string;
+} | {
+    type: "api-key";
+    header: string;
+    key: string;
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "oauth2";
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+};
+/** A resource (collection-like, from skill.md Schema section) */
+interface HttpResource {
+    /** Name used in filesystem path: /mount/{name}/ */
+    name: string;
+    /** API base path for this resource. Defaults to /{name} */
+    apiPath?: string;
+    /** Field name for record ID in API responses. Defaults to "id" */
+    idField?: string;
+    /** Key to extract array from list response. e.g. "result" for Cloudflare, "data" for others */
+    listKey?: string;
+    /** Schema fields (for _schema support) */
+    fields?: {
+        name: string;
+        type: string;
+        description?: string;
+    }[];
+    /** Child resources (for nested paths like /zones/{id}/dns_records) */
+    children?: HttpResource[];
+    /** "tree" mode: all remaining path segments form the ID (for file-tree APIs) */
+    pathMode?: "tree";
+    /** Override HTTP method for updates. Default "PUT" */
+    updateMethod?: "PUT" | "PATCH";
+    /** Data transformation hooks */
+    transform?: {
+        /** Transform item after GET response */
+        read?: (data: unknown) => unknown;
+        /** Transform data before POST/PUT body */
+        write?: (data: unknown) => unknown;
+        /** Build DELETE body from read result */
+        remove?: (readResult: unknown | null) => unknown;
+        /** Format each list item to display string. Default: item[idField] + ".json" */
+        list?: (item: unknown) => string;
+    };
+    /** Auto-read before write/delete to obtain fields like SHA, ETag */
+    readBeforeWrite?: {
+        inject: (readResult: unknown, writeData: unknown) => unknown;
+    };
+}
+/** An API endpoint (invocation-like, from skill.md API section) */
+interface HttpEndpoint {
+    /** Name used in filesystem path: /mount/_api/{name} */
+    name: string;
+    /** HTTP method */
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** API path */
+    apiPath: string;
+    /** Description */
+    description?: string;
+}
+/** Configuration for HttpBackend */
+interface HttpBackendConfig {
+    /** Base URL of the API (e.g. "https://api.cloudflare.com/client/v4") */
+    baseUrl: string;
+    /** Authentication */
+    auth?: HttpAuth;
+    /** Resource definitions (from skill.md Schema section) */
+    resources?: HttpResource[];
+    /** API endpoint definitions (from skill.md API section) */
+    endpoints?: HttpEndpoint[];
+    /** Static parameters for template resolution (e.g. { accountId: "abc123" }) */
+    params?: Record<string, string>;
+    /** Body encoding: "json" (default) or "form" (application/x-www-form-urlencoded) */
+    bodyEncoding?: "json" | "form";
+    /** Custom fetch function (for testing) */
+    fetch?: typeof globalThis.fetch;
+    /** Auto-pagination for list operations */
+    pagination?: PaginationConfig;
+    /** Retry configuration for transient errors (429, 5xx) */
+    retry?: {
+        /** Max retry attempts (default 3) */
+        maxRetries?: number;
+        /** Base delay in ms for exponential backoff (default 1000) */
+        baseDelayMs?: number;
+    };
+}
+/** Pagination configuration — supports multiple strategies */
+type PaginationConfig = {
+    type: "link-header";
+    maxPages?: number;
+} | {
+    type: "cursor";
+    cursorParam: string;
+    cursorPath: string;
+    maxPages?: number;
+} | {
+    type: "offset";
+    offsetParam?: string;
+    limitParam?: string;
+    pageSize?: number;
+    maxPages?: number;
+} | {
+    type: "page";
+    pageParam?: string;
+    maxPages?: number;
+};
+/**
+ * HTTP-based FsBackend driven by skill.md descriptions.
+ *
+ * Filesystem mapping (flat):
+ *   ls /                        → list resources + endpoints
+ *   ls /{resource}/             → GET baseUrl/{apiPath}  (list records)
+ *   cat /{resource}/{id}.json   → GET baseUrl/{apiPath}/{id}  (read record)
+ *   write /{resource}/ data     → POST baseUrl/{apiPath}  (create)
+ *   write /{resource}/{id} data → PUT baseUrl/{apiPath}/{id}  (update)
+ *   rm /{resource}/{id}.json    → DELETE baseUrl/{apiPath}/{id}
+ *   grep pattern /{resource}/   → GET baseUrl/{apiPath}?q={pattern}  (search)
+ *
+ * Nested resources:
+ *   ls /{parent}/{pid}/                   → list child resource directories
+ *   ls /{parent}/{pid}/{child}/           → GET resolved nested path (list)
+ *   cat /{parent}/{pid}/{child}/{id}.json → GET resolved nested path/{id}
+ *
+ * Endpoints:
+ *   ls /_api/                   → list available endpoints
+ *   cat /_api/{name}            → GET endpoint (for GET endpoints)
+ *   write /_api/{name} data     → POST/PUT/etc endpoint (for non-GET endpoints)
+ */
+declare class HttpBackend implements FsBackend {
+    private baseUrl;
+    private auth?;
+    private resourceList;
+    private endpoints;
+    private params;
+    private _fetch;
+    private bodyEncoding;
+    private pagination?;
+    private retryConfig;
+    /** Cached OAuth2 access token */
+    private _oauth2Token?;
+    constructor(config: HttpBackendConfig);
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+    private request;
+    /** Obtain (or refresh) OAuth2 access token via client_credentials grant */
+    private getOAuth2Token;
+    /** Parse Link header to extract rel="next" URL */
+    private getNextPageUrl;
+    /** Fetch all items with optional pagination */
+    private fetchAllItems;
+    /** Format list items using transform.list or default idField + ".json" */
+    private formatListItems;
+    private getEndpoint;
+    /** Replace :param and {param} placeholders in API paths with values from config.params */
+    private resolveTemplate;
+    /** Recursively resolve a filesystem path against the resource tree */
+    private resolveResourcePath;
+    private parsePath;
+}
+
+/** Transport interface for RPC calls */
+interface RpcTransport {
+    call(method: string, params: unknown[]): Promise<unknown>;
+    batch?(calls: Array<{
+        method: string;
+        params: unknown[];
+    }>): Promise<unknown[]>;
+}
+/** Configuration for JSON-RPC 2.0 transport */
+interface JsonRpcTransportConfig {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    /** Retry configuration for transient errors (429, 5xx, -32603, -32000~-32099) */
+    retry?: {
+        /** Max retry attempts (default 3) */
+        maxRetries?: number;
+        /** Base delay in ms for exponential backoff (default 1000) */
+        baseDelayMs?: number;
+    };
+}
+/** JSON-RPC error with code and optional data */
+declare class RpcError extends Error {
+    code: number;
+    data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Context passed to RpcMethod.params callback */
+interface RpcCallContext {
+    id?: string;
+    data?: unknown;
+    pattern?: string;
+}
+/** Maps a filesystem operation to an RPC call */
+interface RpcMethod {
+    method: string;
+    params: (ctx: RpcCallContext) => unknown[];
+}
+/** A resource exposed as a directory in the filesystem */
+interface RpcResource {
+    name: string;
+    idField?: string;
+    methods: {
+        list?: RpcMethod;
+        read?: RpcMethod;
+        write?: RpcMethod;
+        create?: RpcMethod;
+        remove?: RpcMethod;
+        search?: RpcMethod;
+    };
+    transform?: {
+        read?: (data: unknown) => unknown;
+        write?: (data: unknown) => unknown;
+        remove?: (id: string) => unknown;
+        list?: (item: unknown) => string | string[];
+    };
+}
+/** Configuration for RpcBackend */
+interface RpcBackendConfig {
+    transport: RpcTransport;
+    resources: RpcResource[];
+}
+declare class JsonRpcTransport implements RpcTransport {
+    private url;
+    private headers;
+    private _fetch;
+    private nextId;
+    private retryConfig;
+    constructor(config: JsonRpcTransportConfig);
+    call(method: string, params: unknown[]): Promise<unknown>;
+    batch(calls: Array<{
+        method: string;
+        params: unknown[];
+    }>): Promise<unknown[]>;
+    /** Exponential backoff with jitter + Retry-After header support */
+    private backoff;
+}
+declare class RpcBackend implements FsBackend {
+    private transport;
+    private resources;
+    constructor(config: RpcBackendConfig);
+    list(path: string): Promise<string[]>;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<{
+        id: string;
+    }>;
+    remove(path: string): Promise<void>;
+    search(path: string, pattern: string): Promise<unknown[]>;
+    private parsePath;
+}
+
+export { type AgentContext as A, type FsResult as F, type HttpAuth as H, JsonRpcTransport as J, type Mount as M, type PaginationConfig as P, RpcBackend as R, type FsError as a, type FsBackend as b, type FsCommand as c, type AccessRole as d, type FsOp as e, HttpBackend as f, type HttpBackendConfig as g, type HttpEndpoint as h, type HttpResource as i, type JsonRpcTransportConfig as j, type RpcBackendConfig as k, type RpcCallContext as l, RpcError as m, type RpcMethod as n, type RpcResource as o, type RpcTransport as p };