@anhlp/alp-protocol 0.0.0-stage → 0.0.1-beta.3

package/dist/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks `value` against `schema`, resolving `#/$defs/...` against `root`.
+ * @param {any} schema
+ * @param {unknown} value
+ * @param {any} [root]
+ * @returns {SchemaIssue[]} empty when the value conforms
+ */
+export function validateSchema(schema: any, value: unknown, root?: any): SchemaIssue[];
+export type SchemaIssue = {
+    path: string;
+    message: string;
+};

package/dist/validate.js

@@ -0,0 +1,151 @@
+// packages/protocol/src/validate.js
+var MAX_ISSUES = 8;
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return !Number.isFinite(value) ? "non-finite number" : Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+var typeMatches = (want, have) => want === have || want === "number" && have === "integer";
+function equal(a, b) {
+  if (a === b) return true;
+  if (typeOf(a) !== typeOf(b) || a === null || typeof a !== "object") return false;
+  if (Array.isArray(a)) return a.length === /** @type {unknown[]} */
+  b.length && a.every((item, index) => equal(
+    item,
+    /** @type {unknown[]} */
+    b[index]
+  ));
+  const left = Object.keys(a).filter((key) => (
+    /** @type {any} */
+    a[key] !== void 0
+  ));
+  const right = Object.keys(
+    /** @type {object} */
+    b
+  ).filter((key) => (
+    /** @type {any} */
+    b[key] !== void 0
+  ));
+  return left.length === right.length && left.every((key) => equal(
+    /** @type {any} */
+    a[key],
+    /** @type {any} */
+    b[key]
+  ));
+}
+function resolve(root, ref) {
+  if (!ref.startsWith("#/")) throw new Error(`Unsupported schema reference ${ref}`);
+  let target = root;
+  for (const part of ref.slice(2).split("/")) target = target?.[part.replaceAll("~1", "/").replaceAll("~0", "~")];
+  if (target === void 0) throw new Error(`Unresolved schema reference ${ref}`);
+  return target;
+}
+function check(schema, value, at, root, issues) {
+  if (issues.length >= MAX_ISSUES || schema === true || schema === void 0) return;
+  if (schema === false) {
+    issues.push({ path: at, message: "is not allowed" });
+    return;
+  }
+  if (schema.$ref) {
+    check(resolve(root, schema.$ref), value, at, root, issues);
+    if (Object.keys(schema).length === 1) return;
+  }
+  const kind = typeOf(value);
+  if (schema.type !== void 0) {
+    const wanted = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!wanted.some(
+      /** @param {string} want */
+      (want) => typeMatches(want, kind)
+    )) {
+      issues.push({ path: at, message: `must be ${wanted.join(" or ")}` });
+      return;
+    }
+  }
+  if ("const" in schema && !equal(schema.const, value)) {
+    issues.push({ path: at, message: `must be ${JSON.stringify(schema.const)}` });
+    return;
+  }
+  if (schema.enum && !schema.enum.some(
+    /** @param {unknown} option */
+    (option) => equal(option, value)
+  )) {
+    issues.push({ path: at, message: `must be one of ${schema.enum.map(
+      /** @param {unknown} option */
+      (option) => JSON.stringify(option)
+    ).join(", ")}` });
+    return;
+  }
+  if (kind === "integer" || kind === "number") {
+    const number = (
+      /** @type {number} */
+      value
+    );
+    if (schema.minimum !== void 0 && number < schema.minimum) issues.push({ path: at, message: `must be at least ${schema.minimum}` });
+    if (schema.maximum !== void 0 && number > schema.maximum) issues.push({ path: at, message: `must be at most ${schema.maximum}` });
+  }
+  if (kind === "string") {
+    const text = (
+      /** @type {string} */
+      value
+    );
+    let length = 0;
+    if (schema.minLength !== void 0 || schema.maxLength !== void 0) for (const _point of text) length++;
+    if (schema.minLength !== void 0 && length < schema.minLength) issues.push({ path: at, message: `must have at least ${schema.minLength} characters` });
+    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[]} */
+      value
+    );
+    for (let index = 0; index < array.length && issues.length < MAX_ISSUES; index++) check(schema.items, array[index] === void 0 ? null : array[index], `${at}/${index}`, root, issues);
+  }
+  if (kind === "object") {
+    const object = (
+      /** @type {Record<string, unknown>} */
+      value
+    );
+    const properties = schema.properties ?? {};
+    for (const name of schema.required ?? []) if (object[name] === void 0) issues.push({ path: `${at}/${name}`, message: "is required" });
+    for (const [name, child] of Object.entries(object)) {
+      if (child === void 0) continue;
+      if (Object.hasOwn(properties, name)) check(properties[name], child, `${at}/${name}`, root, issues);
+      else if (schema.additionalProperties !== void 0) check(schema.additionalProperties, child, `${at}/${name}`, root, issues);
+    }
+  }
+  if (schema.not !== void 0) {
+    const inner = [];
+    check(schema.not, value, at, root, inner);
+    if (!inner.length) issues.push({ path: at, message: "matches a schema it must not match" });
+  }
+  for (
+    const [keyword, exactlyOne] of
+    /** @type {const} */
+    [["anyOf", false], ["oneOf", true]]
+  ) {
+    if (!schema[keyword]) continue;
+    const passing = schema[keyword].filter(
+      /** @param {any} option */
+      (option) => {
+        const inner = [];
+        check(option, value, at, root, inner);
+        return !inner.length;
+      }
+    ).length;
+    if (exactlyOne ? passing !== 1 : passing === 0) issues.push({ path: at, message: exactlyOne && passing > 1 ? "matches more than one allowed shape" : "matches none of the allowed shapes" });
+  }
+}
+function validateSchema(schema, value, root = schema) {
+  const issues = [];
+  check(schema, value, "", root, issues);
+  return issues;
+}
+export {
+  validateSchema
+};

package/dist/wire.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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} */
+export function decodeFrame(line: string): unknown;
+/** Wire protocol of alpd (plans/reference/ALPD.md §3). Bump only for incompatible changes. */
+export const PROTOCOL_VERSION: 1;
+export const MAX_FRAME: number;
+export class AlpRpcError extends Error {
+    constructor(error: any);
+    code: any;
+    data: any;
+}
+export const ERROR: Readonly<{
+    failed: 1000;
+    notFound: 1001;
+    forbidden: 1003;
+    conflict: 1004;
+    unavailable: 1005;
+    protocol: 1006;
+}>;
+/** The JSON-RPC 2.0 codes alpd answers with (docs/protocol/alp-json-rpc-v1.md §5). */
+export const RPC_ERROR: Readonly<{
+    parseError: -32700;
+    invalidRequest: -32600;
+    methodNotFound: -32601;
+    invalidParams: -32602;
+}>;
+/**
+ * Features a daemon lists in its daemon.hello result. A client uses a feature only when listed;
+ * a daemon that lists none (one older than this list) has none of them. Unknown names are ignored.
+ */
+export const CAPABILITY: Readonly<{
+    attachAfter: "attach.after";
+    promptReceipts: "prompt.receipts";
+    extensionMethods: "extension.methods";
+    team: "team";
+    task: "task";
+    library: "library";
+    libraryProjectWrite: "library.project.write";
+    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

@@ -0,0 +1,62 @@
+// packages/protocol/src/wire.js
+var PROTOCOL_VERSION = 1;
+var MAX_FRAME = 16 * 1024 * 1024;
+var AlpRpcError = class extends Error {
+  constructor(error) {
+    super(error?.message ?? "ALP daemon request failed");
+    this.code = error?.code;
+    this.data = error?.data;
+  }
+};
+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", libraryProjectWrite: "library.project.write", 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)}
+`;
+}
+function decodeFrame(line) {
+  return JSON.parse(line);
+}
+export {
+  AlpRpcError,
+  CAPABILITY,
+  ERROR,
+  MAX_FRAME,
+  PROMPT_IMAGES,
+  PROTOCOL_VERSION,
+  RPC_ERROR,
+  RPC_METHODS,
+  WORKSPACE_FILES,
+  base64Bytes,
+  blockedFilePath,
+  decodeFrame,
+  encodeFrame
+};

package/fixtures/ipc-v1.jsonl

@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"method":"daemon.hello","params":{"protocolVersion":1,"client":{"name":"fixture","version":"0.9.5"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1}}
+{"jsonrpc":"2.0","method":"event","params":{"sessionId":"ses_fixture","epoch":"fixture-epoch","seq":1,"ts":"2026-10-14T00:00:00.000Z","event":{"type":"session.ready"}}}
+{"jsonrpc":"2.0","id":2,"error":{"code":1001,"message":"No session ses_fixture"}}