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

package/src/session.ts

@@ -0,0 +1,213 @@
+import type { RuntimeKind } from './dto.js';
+import type { SessionSnapshot, TurnAttention } from './events.js';
+/** MCP servers a client adds to the agent's own; the agent's names win no collisions. */
+export type HostMcpServer =
+  | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | { type: 'http' | 'sse'; url: string; headers?: Record<string, string> };
+
+/** What a client asks for; resolveSession turns it into a launchable session. */
+export type SessionSpec = {
+  cwd: string;
+  agent?: string;
+  /** Workflow selected for a new session; omitted uses settings or the restored snapshot. */
+  workflow?: string;
+  /** Native model, or runtime-prefixed (`codex:`/`claude:`, or `acp:<provider>[/<model>]`) to also choose the runtime. */
+  model?: string;
+  mode?: string;
+  thinking?: string;
+  systemPrompt?: string;
+  env?: Record<string, string>;
+  mcpServers?: Record<string, HostMcpServer>;
+  /** Keep the native thread so the session can be resumed. */
+  persist?: boolean;
+  /** Keep the native thread on disk though the session cannot be resumed: an assignment, which alp_recall may question later. */
+  keepThread?: boolean;
+  restore?: {
+    agent: string; threadId: string; runtime?: string; model?: string; workflow?: { mode: string; maxPeers: number; supervisor?: boolean };
+    /** Claude: `threadId` does not exist yet and is made from this conversation on its first prompt (a fork or rewind, §12.7). */
+    base?: NativeBase;
+  };
+  /** Where the native harness works, when not the project root: an assignment's git worktree. ALP files are still read from cwd. */
+  workdir?: string;
+  /** Explicit shared-assignment write scope; workdir points here while ALP uses cwd for its project. */
+  writeRoot?: string;
+  /** The workdir is a disposable copy the session may write, though its mode is read-only for the requester's tree. */
+  copy?: boolean;
+  /** The requester's directory the copy mirrors. */
+  copyOf?: string;
+};
+
+export type OpenOptions = {
+  history?: 'replay' | 'skip';
+  /** 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 };
+/** A stored attachment in a prompt (capability `attachments`, §12.6): its opaque id only, never a path or URL. */
+export type PromptAttachment = { type: 'attachment'; attachmentId: string };
+/**
+ * What alpd hands a runtime for an attachment part once it validated and pinned it (§12.6, the
+ * runtime seam of issue #121 branch J): ids, display metadata and digest, never a host path. The
+ * runtime reads the bytes through the AttachmentReader alpd binds, and only for a session whose
+ * runtime declared it takes attachments.
+ */
+export type RuntimeAttachment = { type: 'attachment'; attachmentId: string; name: string; mimeType: string; detectedMimeType: string; size: number; sha256: string };
+/** Text parts carry `text`; image parts (`type: 'image'`) carry PromptImage's fields; attachment parts (`type: 'attachment'`) `attachmentId`. */
+export type PromptContent = Array<{ type: string; text?: string; mimeType?: string; data?: string; name?: string; attachmentId?: string }>;
+
+export type PromptInput = {
+  clientMessageId: string;
+  /** auto starts a turn; steer adds to the running one. */
+  delivery: 'auto' | 'steer';
+  content: PromptContent;
+};
+
+/** A root before it opens: the team and main it would run with, for viewers that let the user choose first (ALPD §60). */
+export type SessionPreview = {
+  teams: Array<{ id: string; label: string; description?: string }>;
+  /** The team the spec selects, else settings' workflow.mode, else Phở. */
+  team: string;
+  teamLabel?: string;
+  agent: string;
+  runtime: RuntimeKind;
+  model: string;
+  mode: string;
+  thinking: string;
+};
+
+/** What became of one assignment an earlier alpd left running. */
+export type RecoveryOutcome = { assignmentId: string; agent: string; outcome: 'resumed' | 'parked' | 'failed'; error?: string };
+
+export type Pause = { since: string; by: string; reason: string; resetsAt?: string; /** When alpd last asked the runtime about the limit (ALPD §58). */ checkedAt?: string };
+export type PauseState = {
+  all?: Pause;
+  runtimes: Partial<Record<RuntimeKind, Pause>>;
+  parked: Array<{ assignmentId: string; agent: string; runtime: RuntimeKind; rootId: string; reason: string; since: string }>;
+};
+
+export type RecallAnswer = { assignmentId: string; agent: string; taskId?: string; finishedAt: string; answer: string };
+
+/** A session's lifecycle as alpd records it; neutral, so viewers and integrations share one union. */
+export type SessionStatus = 'initializing' | 'idle' | 'running' | 'error' | 'closed';
+
+/** The last failure recorded for a session (daemon store `SessionRecord.lastError`). */
+export type SessionError = { code?: string; message: string };
+
+/**
+ * A session as clients list it: its last snapshot plus lifecycle (ALPD §18). This is the portable
+ * shape served by `session.list`; the daemon and every viewer agree on it, so it is the same type
+ * the daemon's store and server use rather than a lossy summary.
+ */
+export type SessionSummary = SessionSnapshot & {
+  status: SessionStatus;
+  title?: string;
+  archived?: boolean;
+  /** A root's turn that ended unseen, until a client acknowledges it (capability `session.attention`). */
+  attention?: TurnAttention;
+  lastError?: SessionError;
+  createdAt?: string;
+  updatedAt?: string;
+  /**
+   * Whether alpd can fork or rewind this session's conversation now, and why not (capabilities
+   * `session.fork` and `session.rewind`, §12.7). A single turn may still be refused: one in
+   * progress, the first one, or one alpd cannot map to the runtime's own history.
+   */
+  conversation?: {
+    fork: boolean; rewind: boolean;
+    /** Whether session.reload can restart this root's native process (capability `session.reload`, §12.8); the root must also be open and idle. */
+    reload?: boolean;
+    /** Whether session.configure can change this root's model, effort or team (capability `session.configure.live`, §12.9); the root must also be open and idle. */
+    configure?: boolean;
+    reason?: 'runtime_unsupported' | 'not_persistent' | 'not_root';
+  };
+  /** The session this root was forked from (§12.7). */
+  forkedFrom?: ForkProvenance;
+  /** Conversation branches rewinds set aside, oldest first; each stays recoverable with session.fork { branchId } (§12.7). */
+  branches?: ConversationBranch[];
+};
+
+/**
+ * A Claude conversation ALP has bound a session to but the runtime has not written yet (§12.7): the
+ * first prompt resumes `threadId` as a new session, keeping its history through the entry `at` (all of
+ * it when absent). Internal to alpd and its runtime; never accepted from a remote client.
+ */
+export type NativeBase = { threadId: string; at?: string };
+
+/** Where a fork came from (§12.7): the source root, and the turn its conversation was cut at. */
+export type ForkProvenance = {
+  sessionId: string;
+  /** The cut: through this turn, or before it; absent when the whole conversation was taken. */
+  turnId?: string;
+  boundary: 'through' | 'before' | 'whole';
+  /** Set when the fork restored a branch a rewind set aside. */
+  branchId?: string;
+  at: string;
+};
+
+/** The later turns of a conversation a rewind set aside (§12.7): kept, never deleted, recoverable as a new session. */
+export type ConversationBranch = {
+  branchId: string;
+  /** The turn the rewind went back to before; it and every later turn are in the branch. */
+  beforeTurnId: string;
+  /** How many turns the branch holds past the kept conversation. */
+  turns: number;
+  at: string;
+};
+
+/**
+ * The ALP CLI command that continues a session in a terminal (session.resumeCommand, §12.8): `argv`
+ * and the same command quoted for a POSIX shell and for Windows (cmd.exe). `display` is the one for
+ * the daemon host's own platform. Never a native runtime's command, credential, env or path.
+ */
+export type ResumeCommand = { argv: string[]; posix: string; windows: string; display: string; platform: 'posix' | 'windows' };
+
+/**
+ * The configuration a root runs with, or would after a change, as alpd resolved it (§12.9): its team,
+ * agent, runtime, model, effort and mode, and what they bring (delegation targets, ALP tools, MCP
+ * servers by name and kind, hook count, an instructions digest). Never a path, command or credential.
+ */
+export type EffectiveConfig = {
+  team: string;
+  teamLabel?: string;
+  agent: string;
+  runtime: RuntimeKind;
+  model: string;
+  thinking: string;
+  mode: string;
+  /** The permission profile capping the agent's mode, when one does. */
+  permissionProfile?: string;
+  supervisor: boolean;
+  maxPeers?: number;
+  delegates: string[];
+  tools: string[];
+  mcpServers: Array<{ name: string; kind: 'stdio' | 'http' }>;
+  hooks: number;
+  instructionsSha?: string;
+};
+
+export type ConfigureChange = 'model' | 'thinking' | 'team' | 'mode';
+export type ConfigureRefusal = 'session_busy' | 'session_closed' | 'not_root' | 'runtime_unsupported' | 'runtime_mismatch' | 'agent_mismatch' | 'permission_escalation' | 'team_not_found' | 'invalid_params' | 'not_persistent';
+
+/** session.configure.preview (§12.9): the current and proposed configuration, and whether alpd would apply it now. */
+export type ConfigurePreview = {
+  current: EffectiveConfig;
+  proposed: EffectiveConfig;
+  changes: ConfigureChange[];
+  /** Applying it restarts the root's native process on its own conversation. */
+  restart: boolean;
+  /** session.configure would take it now; a tree that gets busy meanwhile still refuses it. */
+  allowed: boolean;
+  reason?: ConfigureRefusal;
+  message?: string;
+  teams: Array<{ id: string; label: string; description?: string }>;
+};
+
+/** What a session.configure with model, thinking or team did (§12.9): what was asked, and what the root runs with now. */
+export type ConfigureOutcome = {
+  status: 'applied' | 'unchanged';
+  requested: { model?: string; thinking?: string; team?: string; mode?: string };
+  effective: EffectiveConfig;
+  restarted: boolean;
+};

package/src/validate.js

@@ -0,0 +1,115 @@
+/**
+ * A dependency-free checker for the JSON Schema subset the protocol schemas use (draft-07:
+ * type, const, enum, properties, required, additionalProperties, items, minItems, maxItems, minimum, maximum,
+ * minLength, maxLength, pattern, oneOf, anyOf, not and local `#/$defs/...` references).
+ * Lengths count Unicode code points, as JSON Schema does. A property whose value is
+ * `undefined` counts as absent, so in-process callers behave as their JSON would.
+ */
+
+/** @typedef {{ path: string, message: string }} SchemaIssue */
+
+const MAX_ISSUES = 8;
+
+/** @param {unknown} value */
+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;
+}
+
+/** @param {string} want @param {string} have */
+const typeMatches = (want, have) => want === have || (want === 'number' && have === 'integer');
+
+/** @param {unknown} a @param {unknown} b @returns {boolean} */
+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] !== undefined);
+  const right = Object.keys(/** @type {object} */ (b)).filter(key => /** @type {any} */ (b)[key] !== undefined);
+  return left.length === right.length && left.every(key => equal(/** @type {any} */ (a)[key], /** @type {any} */ (b)[key]));
+}
+
+/** @param {any} root @param {string} ref */
+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 === undefined) throw new Error(`Unresolved schema reference ${ref}`);
+  return target;
+}
+
+/**
+ * @param {any} schema
+ * @param {unknown} value
+ * @param {string} at
+ * @param {any} root
+ * @param {SchemaIssue[]} issues
+ */
+function check(schema, value, at, root, issues) {
+  if (issues.length >= MAX_ISSUES || schema === true || schema === undefined) 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 !== undefined) {
+    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 !== undefined && number < schema.minimum) issues.push({ path: at, message: `must be at least ${schema.minimum}` });
+    if (schema.maximum !== undefined && 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 !== undefined || schema.maxLength !== undefined) for (const _point of text) length++;
+    if (schema.minLength !== undefined && length < schema.minLength) issues.push({ path: at, message: `must have at least ${schema.minLength} characters` });
+    if (schema.maxLength !== undefined && length > schema.maxLength) issues.push({ path: at, message: `must have at most ${schema.maxLength} characters` });
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern, 'u').test(text)) issues.push({ path: at, message: `must match ${schema.pattern}` });
+  }
+  if (kind === 'array' && schema.minItems !== undefined && /** @type {unknown[]} */ (value).length < schema.minItems) issues.push({ path: at, message: `must have at least ${schema.minItems} items` });
+  if (kind === 'array' && schema.maxItems !== undefined && /** @type {unknown[]} */ (value).length > schema.maxItems) issues.push({ path: at, message: `must have at most ${schema.maxItems} items` });
+  if (kind === 'array' && schema.items !== undefined) {
+    const array = /** @type {unknown[]} */ (value);
+    for (let index = 0; index < array.length && issues.length < MAX_ISSUES; index++) check(schema.items, array[index] === undefined ? 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] === undefined) issues.push({ path: `${at}/${name}`, message: 'is required' });
+    for (const [name, child] of Object.entries(object)) {
+      if (child === undefined) continue;
+      if (Object.hasOwn(properties, name)) check(properties[name], child, `${at}/${name}`, root, issues);
+      else if (schema.additionalProperties !== undefined) check(schema.additionalProperties, child, `${at}/${name}`, root, issues);
+    }
+  }
+  if (schema.not !== undefined) {
+    /** @type {SchemaIssue[]} */
+    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 => { /** @type {SchemaIssue[]} */ 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' });
+  }
+}
+
+/**
+ * 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, value, root = schema) {
+  /** @type {SchemaIssue[]} */
+  const issues = [];
+  check(schema, value, '', root, issues);
+  return issues;
+}

package/src/wire.js

@@ -0,0 +1,213 @@
+/** Wire protocol of alpd (plans/reference/ALPD.md §3). Bump only for incompatible changes. */
+export const PROTOCOL_VERSION = 1;
+export const MAX_FRAME = 16 * 1024 * 1024;
+
+export class AlpRpcError extends Error {
+  constructor(error) {
+    super(error?.message ?? 'ALP daemon request failed');
+    this.code = error?.code;
+    this.data = error?.data;
+  }
+}
+
+export const ERROR = Object.freeze({ 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 = Object.freeze({ 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 = 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`
+ * 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 = 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", "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`,
+ * 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 = 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. */
+const BLOCKED_NAMES = 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']);
+/** Credential files known by their directory too: GitHub CLI's token file. */
+const BLOCKED_PAIRS = new Set(['gh/hosts.yml']);
+/** Names of credential files before their first dot (a leading dot aside): credentials.json, .credentials.json, secrets.yaml, a secrets/ directory. */
+const BLOCKED_STEMS = new Set(['credential', 'credentials', 'secret', 'secrets']);
+/**
+ * Source code is not a credential store: src/credentials.ts, lib/secrets.py stay readable (the stem
+ * rule only; never a data or config format such as json, yaml, toml, ini, xml, txt). alpd's
+ * private-key check still applies to them.
+ */
+const SOURCE_EXTENSIONS = 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']);
+/** Key, certificate-store, keyring and Terraform-state extensions. */
+const BLOCKED_EXTENSIONS = new Set(['pem', 'key', 'p12', 'pfx', 'p8', 'jks', 'keystore', 'ppk', 'der', 'gpg', 'pgp', 'asc', 'kdbx', 'ovpn', 'tfstate', 'tfvars']);
+/** .env and every name starting with it (.env.local, .envrc); id_* (SSH keys: id_rsa, id_ed25519.pub, id_work); service-account keys; shell and REPL histories; Terraform state backups. */
+const BLOCKED_PATTERN = /^(?:\.env|id_|service[-_]?account)|_history$|\.tfstate\.backup$/;
+
+/**
+ * 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) {
+  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;
+    // Any dotted part of the name but its extension: secrets.yaml, prod.secrets.yaml, .credentials.json.
+    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;
+}
+
+/** UTF-8 socket writers use one newline-terminated JSON value per frame. @param {unknown} value */
+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 };
+}