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

package/dist/wire.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The decoded bytes one attachment.chunk may carry over frames of at most `maxFrame` bytes:
+ * `maxChunkBytes`, lowered so its base64 and ATTACHMENT_CHUNK_OVERHEAD fit. At least 1 byte.
+ * @param {number} [maxFrame] @param {number} [maxChunkBytes]
+ */
+export function attachmentChunkBytes(maxFrame?: number, maxChunkBytes?: number): number;
+/**
+ * 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;
+/** One argument for a POSIX shell: as it is when nothing in it is special, else in single quotes. @param {string} arg */
+export function quotePosix(arg: string): string;
+/**
+ * One argument for cmd.exe: as it is when nothing in it is special; else in double quotes for the C
+ * runtime's split (backslashes before the closing quote doubled), with every cmd.exe metacharacter,
+ * the quotes too, escaped with ^ for the interactive parse; the shim's second parse then sees one
+ * quoted argument, inside which `&|<>()^` are literal. `"`, `%` and `!` are refused (see above).
+ * @param {string} arg
+ */
+export function quoteWindows(arg: string): string;
+/** argv as one command line. @param {string[]} argv @param {'posix' | 'windows'} platform */
+export function commandLine(argv: string[], platform: "posix" | "windows"): string;
+/**
+ * session.resumeCommand's answer for a session: `alp attach <sessionId>`, which follows the session in
+ * a terminal (a closed one says how to send it a message). ALP keeps the orchestration, so it is never
+ * a native runtime's own resume command.
+ * @param {string} sessionId @param {'posix' | 'windows'} platform the daemon host's
+ */
+export function resumeCommandOf(sessionId: string, platform: "posix" | "windows"): {
+    argv: string[];
+    posix: string;
+    windows: string;
+    display: string;
+    platform: "posix" | "windows";
+};
+/** 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<{
+    sessionInterruptTurn: "session.interrupt.turn";
+    attachAfter: "attach.after";
+    sessionHistory: "session.history";
+    workspaceRegistry: "workspace.registry";
+    workspaceWorktree: "workspace.worktree";
+    workspaceGit: "workspace.git";
+    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";
+    sessionAttention: "session.attention";
+    workspaceFiles: "workspace.files";
+    workspaceFilesRead: "workspace.files.read";
+    promptImages: "prompt.images";
+    schedule: "schedule";
+    attachments: "attachments";
+    sessionFork: "session.fork";
+    sessionRewind: "session.rewind";
+    sessionReload: "session.reload";
+    sessionResumeCommand: "session.resumeCommand";
+    sessionConfigureLive: "session.configure.live";
+    terminal: "terminal";
+}>;
+/**
+ * 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;
+}>;
+/**
+ * Limits of workspace.git.status and workspace.git.diff (capability `workspace.git`,
+ * docs/protocol/alp-json-rpc-v1.md §12.5): one file's patch at most `maxFileBytes`, one page's
+ * patches at most `maxTotalBytes` (then `nextCursor`), at most `maxUntracked` untracked files with
+ * content, `maxStatusFiles` status rows, a base branch name of at most `maxRefLength` characters.
+ * A gateway may lower them; never raise them.
+ */
+export const WORKSPACE_GIT: Readonly<{
+    maxFileBytes: number;
+    maxTotalBytes: number;
+    maxUntracked: 200;
+    maxStatusFiles: 1000;
+    maxRefLength: 255;
+}>;
+/**
+ * Limits of non-image attachments (capability `attachments`, docs/protocol/alp-json-rpc-v1.md
+ * §12.6): an object of at most `maxObjectBytes`; a prompt of at most `maxPerPrompt` attachments and
+ * `maxPromptBytes` together; chunks of at most `maxChunkBytes` decoded (lowered further by
+ * attachmentChunkBytes to fit a frame); `maxActiveUploads` incomplete uploads and
+ * `maxPrincipalBytes` stored per principal, `maxDaemonBytes` per daemon, retained references
+ * included. An incomplete upload expires after `uploadTimeoutMs`; an unreferenced committed object
+ * is purged after `unreferencedRetentionMs`, one whose references were all released after
+ * `releasedGraceMs`. A display name is at most `maxNameBytes` UTF-8 bytes. An operator or a gateway
+ * may lower them, never raise them; daemon.hello advertises the effective ones (`attachmentLimits`).
+ */
+export const ATTACHMENTS: Readonly<{
+    maxObjectBytes: number;
+    maxPerPrompt: 8;
+    maxPromptBytes: number;
+    maxChunkBytes: number;
+    maxActiveUploads: 2;
+    maxPrincipalBytes: number;
+    maxDaemonBytes: number;
+    uploadTimeoutMs: number;
+    unreferencedRetentionMs: number;
+    releasedGraceMs: number;
+    maxNameBytes: 255;
+}>;
+/**
+ * Limits of terminals (capability `terminal`, docs/protocol/alp-json-rpc-v1.md §12.10): at most
+ * `maxPerPrincipal` running terminals per principal and `maxPerDaemon` per daemon; a
+ * terminal.input of at most `maxInputBytes` UTF-8 bytes; output events of at most
+ * `maxOutputFrameBytes` bytes of data; `replayBytes` of output kept per terminal for attach; a
+ * terminal ends after `idleMs` without input or output, after `maxLifetimeMs` in any case, and
+ * `reconnectMs` after its stream detached unless attached again. Sizes are `minCols`..`maxCols`
+ * columns and `minRows`..`maxRows` rows. An operator or a gateway may lower the first eight, never
+ * raise them; daemon.hello advertises the effective ones (`terminalLimits`).
+ */
+export const TERMINAL: Readonly<{
+    maxPerPrincipal: 4;
+    maxPerDaemon: 16;
+    maxInputBytes: number;
+    maxOutputFrameBytes: number;
+    replayBytes: number;
+    idleMs: number;
+    maxLifetimeMs: number;
+    reconnectMs: number;
+    minCols: 2;
+    maxCols: 500;
+    minRows: 1;
+    maxRows: 200;
+}>;
+/** The TERMINAL limits a daemon.hello `terminalLimits` carries (the size bounds are fixed). */
+export const TERMINAL_LIMIT_KEYS: readonly string[];
+export function isTerminalId(id: unknown): boolean;
+/** Room an attachment.chunk request needs besides its base64 data. */
+export const ATTACHMENT_CHUNK_OVERHEAD: number;

package/dist/wire.js

@@ -0,0 +1,137 @@
+// 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({ sessionInterruptTurn: "session.interrupt.turn", attachAfter: "attach.after", sessionHistory: "session.history", workspaceRegistry: "workspace.registry", workspaceWorktree: "workspace.worktree", workspaceGit: "workspace.git", 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", sessionAttention: "session.attention", workspaceFiles: "workspace.files", workspaceFilesRead: "workspace.files.read", promptImages: "prompt.images", schedule: "schedule", attachments: "attachments", sessionFork: "session.fork", sessionRewind: "session.rewind", sessionReload: "session.reload", sessionResumeCommand: "session.resumeCommand", sessionConfigureLive: "session.configure.live", terminal: "terminal" });
+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", "attachment.abort", "attachment.begin", "attachment.chunk", "attachment.commit", "attachment.delete", "attachment.get", "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", "project.list", "project.register", "project.remove", "question.answer", "question.list", "question.watch", "registry.owner", "registry.worktree", "schedule.cancel", "schedule.create", "schedule.get", "schedule.list", "session.archive", "session.attach", "session.attention.clear", "session.close", "session.configure", "session.configure.preview", "session.create", "session.fork", "session.get", "session.history", "session.interrupt", "session.list", "session.log", "session.message", "session.preview", "session.prompt", "session.release", "session.reload", "session.rename", "session.resumeCommand", "session.rewind", "session.status", "settings.language.get", "settings.language.set", "task.create", "task.gate.resolve", "task.list", "task.update", "team.list", "terminal.attach", "terminal.close", "terminal.create", "terminal.input", "terminal.list", "terminal.resize", "terminal.revoke", "workspace.files.list", "workspace.files.read", "workspace.files.search", "workspace.get", "workspace.git.diff", "workspace.git.status", "workspace.list", "workspace.update", "workspace.worktree.create", "workspace.worktree.options", "workspace.worktree.remove"]);
+var WORKSPACE_FILES = Object.freeze({ maxReadBytes: 1024 * 1024, maxListEntries: 1e3, maxPathLength: 4096 });
+var WORKSPACE_GIT = Object.freeze({ maxFileBytes: 1024 * 1024, maxTotalBytes: 2 * 1024 * 1024, maxUntracked: 200, maxStatusFiles: 1e3, maxRefLength: 255 });
+var ATTACHMENTS = Object.freeze({
+  maxObjectBytes: 20 * 1024 * 1024,
+  maxPerPrompt: 8,
+  maxPromptBytes: 40 * 1024 * 1024,
+  maxChunkBytes: 256 * 1024,
+  maxActiveUploads: 2,
+  maxPrincipalBytes: 200 * 1024 * 1024,
+  maxDaemonBytes: 1024 * 1024 * 1024,
+  uploadTimeoutMs: 60 * 60 * 1e3,
+  unreferencedRetentionMs: 24 * 60 * 60 * 1e3,
+  releasedGraceMs: 7 * 24 * 60 * 60 * 1e3,
+  maxNameBytes: 255
+});
+var TERMINAL = Object.freeze({
+  maxPerPrincipal: 4,
+  maxPerDaemon: 16,
+  maxInputBytes: 64 * 1024,
+  maxOutputFrameBytes: 64 * 1024,
+  replayBytes: 1024 * 1024,
+  idleMs: 30 * 60 * 1e3,
+  maxLifetimeMs: 8 * 60 * 60 * 1e3,
+  reconnectMs: 60 * 1e3,
+  minCols: 2,
+  maxCols: 500,
+  minRows: 1,
+  maxRows: 200
+});
+var TERMINAL_LIMIT_KEYS = Object.freeze(["maxPerPrincipal", "maxPerDaemon", "maxInputBytes", "maxOutputFrameBytes", "replayBytes", "idleMs", "maxLifetimeMs", "reconnectMs"]);
+var isTerminalId = (id) => typeof id === "string" && /^term_[0-9a-f]{32}$/.test(id);
+var ATTACHMENT_CHUNK_OVERHEAD = 64 * 1024;
+function attachmentChunkBytes(maxFrame = MAX_FRAME, maxChunkBytes = ATTACHMENTS.maxChunkBytes) {
+  const fits = Math.floor((maxFrame - ATTACHMENT_CHUNK_OVERHEAD) * 3 / 4);
+  return Math.max(1, Math.min(maxChunkBytes, fits));
+}
+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);
+}
+var POSIX_SAFE = /^[A-Za-z0-9_@+:,./-]+$/;
+var WINDOWS_SAFE = /^[A-Za-z0-9_@+:./\\-]+$/;
+var assertArgument = (arg) => {
+  if (typeof arg !== "string") throw new TypeError("A command argument is a string");
+  if (/[\u0000-\u001f\u007f]/.test(arg)) throw new TypeError("A command argument has no control characters");
+  return arg;
+};
+function quotePosix(arg) {
+  const text = assertArgument(arg);
+  return text && POSIX_SAFE.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
+}
+function quoteWindows(arg) {
+  const text = assertArgument(arg);
+  if (text && WINDOWS_SAFE.test(text)) return text;
+  if (/["%!]/.test(text)) throw new TypeError('A cmd.exe command argument has no ", % or !');
+  const quoted = `"${text.replace(/(\\*)$/, "$1$1")}"`;
+  return quoted.replace(/([()\][^"`<>&|;, *?])/g, "^$1");
+}
+var SESSION_ID = /^[\w.:-]{1,128}$/;
+function commandLine(argv, platform) {
+  return argv.map(platform === "windows" ? quoteWindows : quotePosix).join(" ");
+}
+function resumeCommandOf(sessionId, platform) {
+  if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId)) throw new TypeError("A session id is [A-Za-z0-9_.:-], at most 128 characters");
+  const argv = ["alp", "attach", sessionId];
+  const posix = commandLine(argv, "posix");
+  const windows = commandLine(argv, "windows");
+  return { argv, posix, windows, display: platform === "windows" ? windows : posix, platform };
+}
+export {
+  ATTACHMENTS,
+  ATTACHMENT_CHUNK_OVERHEAD,
+  AlpRpcError,
+  CAPABILITY,
+  ERROR,
+  MAX_FRAME,
+  PROMPT_IMAGES,
+  PROTOCOL_VERSION,
+  RPC_ERROR,
+  RPC_METHODS,
+  TERMINAL,
+  TERMINAL_LIMIT_KEYS,
+  WORKSPACE_FILES,
+  WORKSPACE_GIT,
+  attachmentChunkBytes,
+  base64Bytes,
+  blockedFilePath,
+  commandLine,
+  decodeFrame,
+  encodeFrame,
+  isTerminalId,
+  quotePosix,
+  quoteWindows,
+  resumeCommandOf
+};

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"}}