@anhlp/alp-protocol 0.0.0-beta.1 → 0.0.0-beta.2

package/dist/rpc.d.ts

@@ -31,9 +31,9 @@ export type EventNotification = {
     params: Envelope;
 };
 /** Names a daemon may list in its daemon.hello result (schema/methods-v1.json `capabilities`). */
-export type Capability = 'attach.after' | 'prompt.receipts' | 'extension.methods' | 'team' | 'task' | 'library' | 'settings.language';
+export type Capability = 'attach.after' | 'prompt.receipts' | 'extension.methods' | 'team' | 'task' | 'library' | 'settings.language' | 'session.list.page' | 'question.watch' | 'question.watch.turns' | 'workspace.files' | 'workspace.files.read' | 'prompt.images';
 /** `data.reason` values alpd sets on errors (docs/protocol/alp-json-rpc-v1.md §5.3). */
-export type ErrorReason = 'hello_required' | 'protocol_version' | 'invalid_params' | 'invalid_id' | 'batch_unsupported' | 'frame_too_large' | 'response_too_large' | 'persistence_failed' | 'outcome_unknown' | 'key_conflict' | 'invalid_path' | 'invalid_scope' | 'invalid_entry' | 'secret_marker' | 'not_alp_project' | 'unknown_task' | 'not_found' | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable';
+export type ErrorReason = 'hello_required' | 'protocol_version' | 'invalid_params' | 'invalid_id' | 'batch_unsupported' | 'frame_too_large' | 'response_too_large' | 'persistence_failed' | 'outcome_unknown' | 'key_conflict' | 'invalid_path' | 'invalid_scope' | 'invalid_entry' | 'secret_marker' | 'not_alp_project' | 'unknown_task' | 'not_found' | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable' | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large';
 type Empty = Record<string, never>;
 /**
  * Params and result of every v1 method, as schema/methods-v1.json defines them; the protocol tests
@@ -53,7 +53,8 @@ export type RpcMethodMap = {
         result: {
             protocolVersion: 1;
             daemonVersion?: string;
-            pid?: number;
+            pid?: number; /** The daemon host's machine name (os.hostname()), a label for clients. */
+            hostname?: string;
             capabilities?: string[];
         };
     };
@@ -147,6 +148,62 @@ export type RpcMethodMap = {
             questions: UserQuestion[];
         };
     };
+    /** Capability `question.watch`: the waiting questions now; then this connection is told of every tree's `question` and `question.resolved` (of `projectRoot` when given). `turns` (capability `question.watch.turns`): also every root's `turn.ended`. */
+    'question.watch': {
+        params: {
+            projectRoot?: string;
+            turns?: boolean;
+        };
+        result: {
+            questions: UserQuestion[];
+        };
+    };
+    /** Capability `workspace.files`: files under `projectRoot` whose relative path matches `query`, best first; read-only, links not followed. */
+    'workspace.files.search': {
+        params: {
+            projectRoot: string;
+            query?: string;
+            limit?: number;
+        };
+        result: {
+            files: Array<{
+                path: string;
+            }>;
+            truncated?: boolean;
+        };
+    };
+    /** Capability `workspace.files.read`: the entries of a directory under `projectRoot` (its root when `path` is left out); links, blocked and (unless `includeIgnored`) .gitignore'd entries left out. */
+    'workspace.files.list': {
+        params: {
+            projectRoot: string;
+            path?: string;
+            includeIgnored?: boolean;
+        };
+        result: {
+            entries: Array<{
+                name: string;
+                path: string;
+                kind: 'file' | 'directory';
+                size?: number;
+                modifiedAt?: string;
+            }>;
+            truncated?: boolean;
+        };
+    };
+    /** Capability `workspace.files.read`: a UTF-8 text file under `projectRoot`, at most 1 MiB; read-only, links not followed. */
+    'workspace.files.read': {
+        params: {
+            projectRoot: string;
+            path: string;
+            includeIgnored?: boolean;
+        };
+        result: {
+            path: string;
+            content: string;
+            size: number;
+            modifiedAt?: string;
+        };
+    };
     'question.answer': {
         params: {
             questionId: string;
@@ -263,15 +320,21 @@ export type RpcMethodMap = {
             session: SessionSummary;
         };
     };
+    /** `limit`, `cursor`, `query` and `projectRoots` with capability `session.list.page`: a page, and `nextCursor` while more follow. */
     'session.list': {
         params: {
             projectRoot?: string;
+            projectRoots?: string[];
             rootsOnly?: boolean;
             includeClosed?: boolean;
             includeArchived?: boolean;
+            limit?: number;
+            cursor?: string;
+            query?: string;
         };
         result: {
             sessions: SessionSummary[];
+            nextCursor?: string;
         };
     };
     'session.status': {

package/dist/session.d.ts

@@ -53,9 +53,20 @@ export type OpenOptions = {
     /** False when the client cannot show child sessions; delegation is then refused in this tree. */
     delegation?: boolean;
 };
+/** An image inline in a prompt (capability `prompt.images`): base64 data, never a path or URL; limits in PROMPT_IMAGES. */
+export type PromptImage = {
+    type: 'image';
+    mimeType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    data: string;
+    name?: string;
+};
+/** Text parts carry `text`; image parts (`type: 'image'`) carry PromptImage's fields. */
 export type PromptContent = Array<{
     type: string;
     text?: string;
+    mimeType?: string;
+    data?: string;
+    name?: string;
 }>;
 export type PromptInput = {
     clientMessageId: string;

package/dist/validate.js

@@ -95,6 +95,10 @@ function check(schema, value, at, root, issues) {
     if (schema.maxLength !== void 0 && length > schema.maxLength) issues.push({ path: at, message: `must have at most ${schema.maxLength} characters` });
     if (schema.pattern !== void 0 && !new RegExp(schema.pattern, "u").test(text)) issues.push({ path: at, message: `must match ${schema.pattern}` });
   }
+  if (kind === "array" && schema.minItems !== void 0 && /** @type {unknown[]} */
+  value.length < schema.minItems) issues.push({ path: at, message: `must have at least ${schema.minItems} items` });
+  if (kind === "array" && schema.maxItems !== void 0 && /** @type {unknown[]} */
+  value.length > schema.maxItems) issues.push({ path: at, message: `must have at most ${schema.maxItems} items` });
   if (kind === "array" && schema.items !== void 0) {
     const array = (
       /** @type {unknown[]} */

package/dist/wire.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Whether a path relative to a workspace names something workspace.files.list and
+ * workspace.files.read never show, whatever the grant: a segment that is a blocked directory, or
+ * any segment (file or directory) named as a secret is (BLOCKED_* above). Compared without case,
+ * as macOS and Windows file systems name files. alpd and the gateway both check it; alpd also
+ * refuses a file whose content holds a private key, whatever its name.
+ * @param {string} relative a path relative to the workspace, '/'-separated
+ */
+export function blockedFilePath(relative: string): boolean;
 /** UTF-8 socket writers use one newline-terminated JSON value per frame. @param {unknown} value */
 export function encodeFrame(value: unknown): string;
 /** Parse one complete frame. Buffering and failure handling belong to the socket owner. @param {string} line @returns {unknown} */
@@ -37,5 +46,34 @@ export const CAPABILITY: Readonly<{
     task: "task";
     library: "library";
     settingsLanguage: "settings.language";
+    sessionListPage: "session.list.page";
+    questionWatch: "question.watch";
+    questionWatchTurns: "question.watch.turns";
+    workspaceFiles: "workspace.files";
+    workspaceFilesRead: "workspace.files.read";
+    promptImages: "prompt.images";
+}>;
+/**
+ * What alpd takes as images in one session.prompt (capability `prompt.images`): inline base64 of
+ * these types only, never a path or URL; at most `maxCount` of them, each at most `maxBytes`
+ * decoded, and `maxTotalBytes` together, so their base64 fits one MAX_FRAME. A gateway may allow
+ * less (docs/alp/remote-gateway.md).
+ */
+export const PROMPT_IMAGES: Readonly<{
+    mimeTypes: readonly string[];
+    maxCount: 8;
+    maxBytes: number;
+    maxTotalBytes: number;
 }>;
+export function base64Bytes(data: string): number;
 export const RPC_METHODS: readonly string[];
+/**
+ * Limits of workspace.files.list and workspace.files.read (capability `workspace.files.read`,
+ * docs/protocol/alp-json-rpc-v1.md §12.4): a file of at most `maxReadBytes`, a listing of at most
+ * `maxListEntries` entries, a relative path of at most `maxPathLength` characters.
+ */
+export const WORKSPACE_FILES: Readonly<{
+    maxReadBytes: number;
+    maxListEntries: 1000;
+    maxPathLength: 4096;
+}>;

package/dist/wire.js

@@ -10,8 +10,34 @@ var AlpRpcError = class extends Error {
 };
 var ERROR = Object.freeze({ failed: 1e3, notFound: 1001, forbidden: 1003, conflict: 1004, unavailable: 1005, protocol: 1006 });
 var RPC_ERROR = Object.freeze({ parseError: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602 });
-var CAPABILITY = Object.freeze({ attachAfter: "attach.after", promptReceipts: "prompt.receipts", extensionMethods: "extension.methods", team: "team", task: "task", library: "library", settingsLanguage: "settings.language" });
-var RPC_METHODS = Object.freeze(["assignment.recall", "board.list", "catalog.get", "daemon.hello", "daemon.pause", "daemon.pauses", "daemon.resume", "daemon.shutdown", "daemon.status", "daemon.usage", "extension.register", "extension.unregister", "library.delete", "library.duplicate", "library.get", "library.list", "library.models", "library.rename", "library.save", "library.skills.set", "question.answer", "question.list", "session.archive", "session.attach", "session.close", "session.configure", "session.create", "session.get", "session.interrupt", "session.list", "session.log", "session.message", "session.preview", "session.prompt", "session.release", "session.rename", "session.status", "settings.language.get", "settings.language.set", "task.create", "task.gate.resolve", "task.list", "task.update", "team.list"]);
+var CAPABILITY = Object.freeze({ attachAfter: "attach.after", promptReceipts: "prompt.receipts", extensionMethods: "extension.methods", team: "team", task: "task", library: "library", settingsLanguage: "settings.language", sessionListPage: "session.list.page", questionWatch: "question.watch", questionWatchTurns: "question.watch.turns", workspaceFiles: "workspace.files", workspaceFilesRead: "workspace.files.read", promptImages: "prompt.images" });
+var PROMPT_IMAGES = Object.freeze({ mimeTypes: Object.freeze(["image/png", "image/jpeg", "image/gif", "image/webp"]), maxCount: 8, maxBytes: 5 * 1024 * 1024, maxTotalBytes: 11 * 1024 * 1024 });
+var base64Bytes = (data) => Math.floor(data.length * 3 / 4) - (data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
+var RPC_METHODS = Object.freeze(["assignment.recall", "board.list", "catalog.get", "daemon.hello", "daemon.pause", "daemon.pauses", "daemon.resume", "daemon.shutdown", "daemon.status", "daemon.usage", "extension.register", "extension.unregister", "library.delete", "library.duplicate", "library.get", "library.list", "library.models", "library.rename", "library.save", "library.skills.set", "question.answer", "question.list", "question.watch", "session.archive", "session.attach", "session.close", "session.configure", "session.create", "session.get", "session.interrupt", "session.list", "session.log", "session.message", "session.preview", "session.prompt", "session.release", "session.rename", "session.status", "settings.language.get", "settings.language.set", "task.create", "task.gate.resolve", "task.list", "task.update", "team.list", "workspace.files.list", "workspace.files.read", "workspace.files.search"]);
+var WORKSPACE_FILES = Object.freeze({ maxReadBytes: 1024 * 1024, maxListEntries: 1e3, maxPathLength: 4096 });
+var BLOCKED_DIRECTORIES = /* @__PURE__ */ new Set([".git", ".alp", ".ssh", ".gnupg", ".aws", ".azure", ".kube", ".docker", "gcloud"]);
+var BLOCKED_NAMES = /* @__PURE__ */ new Set([".netrc", "_netrc", ".npmrc", ".yarnrc.yml", ".pypirc", ".pgpass", ".htpasswd", ".git-credentials", ".dockercfg", ".boto", ".s3cfg", ".mcp.json", "auth.json", "kubeconfig", "settings.local.json", ".vault-token", "application_default_credentials.json", "token.json"]);
+var BLOCKED_PAIRS = /* @__PURE__ */ new Set(["gh/hosts.yml"]);
+var BLOCKED_STEMS = /* @__PURE__ */ new Set(["credential", "credentials", "secret", "secrets"]);
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set(["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "py", "go", "rs", "java", "kt", "kts", "rb", "php", "cs", "swift", "c", "cc", "cpp", "h", "hpp", "m", "mm", "scala", "dart", "vue", "svelte"]);
+var BLOCKED_EXTENSIONS = /* @__PURE__ */ new Set(["pem", "key", "p12", "pfx", "p8", "jks", "keystore", "ppk", "der", "gpg", "pgp", "asc", "kdbx", "ovpn", "tfstate", "tfvars"]);
+var BLOCKED_PATTERN = /^(?:\.env|id_|service[-_]?account)|_history$|\.tfstate\.backup$/;
+function blockedFilePath(relative) {
+  let previous = "";
+  for (const segment of String(relative).toLowerCase().split(/[\\/]/)) {
+    if (!segment) continue;
+    if (BLOCKED_PAIRS.has(`${previous}/${segment}`)) return true;
+    previous = segment;
+    if (BLOCKED_DIRECTORIES.has(segment) || BLOCKED_NAMES.has(segment) || BLOCKED_PATTERN.test(segment)) return true;
+    const dot = segment.lastIndexOf(".");
+    const extension = dot >= 0 ? segment.slice(dot + 1) : "";
+    if (BLOCKED_EXTENSIONS.has(extension)) return true;
+    const parts = segment.replace(/^\.+/, "").split(".");
+    if (parts.length > 1) parts.pop();
+    if (parts.some((part) => BLOCKED_STEMS.has(part)) && !SOURCE_EXTENSIONS.has(extension)) return true;
+  }
+  return false;
+}
 function encodeFrame(value) {
   return `${JSON.stringify(value)}
 `;
@@ -24,9 +50,13 @@ export {
   CAPABILITY,
   ERROR,
   MAX_FRAME,
+  PROMPT_IMAGES,
   PROTOCOL_VERSION,
   RPC_ERROR,
   RPC_METHODS,
+  WORKSPACE_FILES,
+  base64Bytes,
+  blockedFilePath,
   decodeFrame,
   encodeFrame
 };