@anhlp/alp-protocol 0.0.1-beta.3 → 0.0.1-beta.4

package/src/wire.js

@@ -17,7 +17,7 @@ export const RPC_ERROR = Object.freeze({ parseError: -32700, invalidRequest: -32
  * 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 = 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' });
+export const 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' });
 /**
  * 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`
@@ -27,7 +27,7 @@ export const CAPABILITY = Object.freeze({ attachAfter: 'attach.after', promptRec
 export const 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 });
 /** Decoded bytes of base64 `data` (padding aware), without decoding it. @param {string} data */
 export const base64Bytes = data => Math.floor(data.length * 3 / 4) - (data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0);
-export const 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"]);
+export const 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"]);
 
 /**
  * Limits of workspace.files.list and workspace.files.read (capability `workspace.files.read`,
@@ -36,6 +36,79 @@ export const RPC_METHODS = Object.freeze(["assignment.recall", "board.list", "ca
  */
 export const WORKSPACE_FILES = Object.freeze({ maxReadBytes: 1024 * 1024, 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 = Object.freeze({ maxFileBytes: 1024 * 1024, maxTotalBytes: 2 * 1024 * 1024, 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 = 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 * 1000,
+  unreferencedRetentionMs: 24 * 60 * 60 * 1000,
+  releasedGraceMs: 7 * 24 * 60 * 60 * 1000,
+  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 = Object.freeze({
+  maxPerPrincipal: 4,
+  maxPerDaemon: 16,
+  maxInputBytes: 64 * 1024,
+  maxOutputFrameBytes: 64 * 1024,
+  replayBytes: 1024 * 1024,
+  idleMs: 30 * 60 * 1000,
+  maxLifetimeMs: 8 * 60 * 60 * 1000,
+  reconnectMs: 60 * 1000,
+  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 = Object.freeze(['maxPerPrincipal', 'maxPerDaemon', 'maxInputBytes', 'maxOutputFrameBytes', 'replayBytes', 'idleMs', 'maxLifetimeMs', 'reconnectMs']);
+/** An opaque terminal id (§12.10). @param {unknown} id */
+export const isTerminalId = id => typeof id === 'string' && /^term_[0-9a-f]{32}$/.test(id);
+/** Room an attachment.chunk request needs besides its base64 data. */
+export const ATTACHMENT_CHUNK_OVERHEAD = 64 * 1024;
+/**
+ * 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 = MAX_FRAME, maxChunkBytes = ATTACHMENTS.maxChunkBytes) {
+  const fits = Math.floor((maxFrame - ATTACHMENT_CHUNK_OVERHEAD) * 3 / 4);
+  return Math.max(1, Math.min(maxChunkBytes, fits));
+}
+
 /** Directories whose whole content is refused: Git's, ALP's own configuration (its library overrides hold env values), and key and cloud-credential stores. */
 const BLOCKED_DIRECTORIES = new Set(['.git', '.alp', '.ssh', '.gnupg', '.aws', '.azure', '.kube', '.docker', 'gcloud']);
 /** Files that hold credentials by convention. */
@@ -85,3 +158,56 @@ export function blockedFilePath(relative) {
 export function encodeFrame(value) { return `${JSON.stringify(value)}\n`; }
 /** Parse one complete frame. Buffering and failure handling belong to the socket owner. @param {string} line @returns {unknown} */
 export function decodeFrame(line) { return JSON.parse(line); }
+
+/**
+ * The command lines of session.resumeCommand (docs/protocol/alp-json-rpc-v1.md §12.8), built from argv
+ * so that every argument reaches the program as it is: for a POSIX shell (sh, bash, zsh) and for
+ * Windows cmd.exe, typed at its prompt and then read again by npm's `alp.cmd` shim (`%*`). An argument
+ * with a control character (a line break would run a pasted command early) is refused, and for cmd.exe
+ * one with `"`, `%` or `!` too: a quote inside an argument ends the shim's quoting and lets the rest
+ * run, and `%`/`!` expand variables in either parse, so no escaping keeps them (session ids have none).
+ */
+const POSIX_SAFE = /^[A-Za-z0-9_@+:,./-]+$/;
+const WINDOWS_SAFE = /^[A-Za-z0-9_@+:./\\-]+$/;
+const assertArgument = (/** @type {unknown} */ 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;
+};
+/** 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) {
+  const text = assertArgument(arg);
+  return text && POSIX_SAFE.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * 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) {
+  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');
+}
+const SESSION_ID = /^[\w.:-]{1,128}$/;
+/** argv as one command line. @param {string[]} argv @param {'posix' | 'windows'} platform */
+export function commandLine(argv, platform) {
+  return argv.map(platform === 'windows' ? quoteWindows : quotePosix).join(' ');
+}
+/**
+ * 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, 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 };
+}