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

package/src/rpc.ts

@@ -0,0 +1,113 @@
+/** Portable JSON-RPC structures; implementations and provider SDKs stay outside protocol. */
+import type { RuntimeKind, Pin } from './dto.js';
+import type { AlpError, Envelope, SessionSnapshot, TreeStatus, UserQuestion } from './events.js';
+import type { PauseState, PromptContent, RecallAnswer, SessionPreview, SessionSpec, SessionSummary } from './session.js';
+import type { EntryName, LanguageSetting, LibraryEntryRow, LibraryKind, LibraryScope, LibrarySource, TaskRow, TeamRow } from './dto.js';
+
+export type RpcId = string | number | null;
+export type RpcErrorData = { code: number; message: string; data?: unknown };
+export type RpcRequest = { jsonrpc: '2.0'; id?: RpcId; method: string; params?: Record<string, unknown> };
+export type RpcResponse = { jsonrpc: '2.0'; id: RpcId } & ({ result: unknown; error?: never } | { error: RpcErrorData; result?: never });
+export type EventNotification = { jsonrpc: '2.0'; method: 'event'; 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' | 'library.project.write' | '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'
+  // Project, task and library methods (docs/protocol/alp-json-rpc-v1.md §5.3).
+  | 'invalid_path' | 'invalid_scope' | 'invalid_entry' | 'secret_marker' | 'not_alp_project' | 'unknown_task' | 'not_found'
+  | 'library_policy' | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable'
+  // workspace.files.search (§12.3); workspace.files.list and read (§12.4).
+  | '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
+ * type-check the golden fixtures against this map, so the two cannot drift. Results may carry
+ * properties this map does not name: clients ignore them.
+ */
+export type RpcMethodMap = {
+  'daemon.hello': { params: { protocolVersion: 1; client?: { name: string; version: string }; capabilities?: string[] }; result: { protocolVersion: 1; daemonVersion?: string; pid?: number; /** The daemon host's machine name (os.hostname()), a label for clients. */ hostname?: string; promptImageLimits?: { maxCount: number; maxBytes: number; maxTotalBytes: number }; capabilities?: string[] } };
+  'daemon.status': {
+    params: Empty;
+    result: {
+      pid: number; startedAt: string; version: string; protocolVersion: number; sessions: number; questions: number;
+      previousExit?: { kind: 'clean' | 'crash'; at?: string };
+      persistence?: Record<string, unknown>;
+      health: { live: boolean; ready: boolean; checks: Array<{ id: string; ok: boolean; code?: string; message?: string }> };
+    };
+  };
+  'daemon.shutdown': { params: Empty; result: Empty };
+  'daemon.pause': { params: { runtime?: RuntimeKind; now?: boolean; reason?: string }; result: PauseState };
+  'daemon.resume': { params: { runtime?: RuntimeKind }; result: PauseState };
+  'daemon.pauses': { params: Empty; result: PauseState };
+  'daemon.usage': { params: { refresh?: boolean }; result: { providers: Array<Record<string, unknown>> } };
+  'catalog.get': { params: Empty; result: { models: Array<Record<string, unknown>>; modes: Array<Record<string, unknown>>; thinkingOptions?: unknown; defaultModel: string } };
+  'assignment.recall': { params: { assignmentId?: string; taskId?: string; projectRoot?: string; question: string }; result: RecallAnswer };
+  'board.list': { params: { projectRoot: string }; result: { pins: Pin[] } };
+  'question.list': { params: { projectRoot?: string }; result: { 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; text?: string; dismiss?: boolean; reason?: string }; result: { questionId: string } };
+  'session.create': {
+    params: { sessionId?: string; spec: SessionSpec; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean };
+    result: { session: SessionSnapshot; attached: boolean; resumed?: true; durable?: boolean };
+  };
+  'session.preview': { params: { spec: SessionSpec }; result: { preview: SessionPreview } };
+  'session.attach': { params: { sessionId: string; replay?: boolean; after?: number }; result: { session: SessionSummary; cursor: number; reset?: true } };
+  'session.release': { params: { sessionId: string }; result: { closed: boolean } };
+  'session.prompt': {
+    params: { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
+    /** `{}` from a daemon without prompt.receipts. */
+    result: { outcome?: 'accepted' | 'failed'; error?: AlpError; duplicate?: boolean; durable?: boolean };
+  };
+  'session.interrupt': { params: { sessionId: string }; result: Empty };
+  'session.configure': { params: { sessionId: string; mode?: string }; result: { session: SessionSnapshot } };
+  'session.close': { params: { sessionId: string }; result: Empty };
+  'session.rename': { params: { sessionId: string; title: string }; result: { session: SessionSummary } };
+  'session.archive': { params: { sessionId: string; archived?: boolean }; result: { session: SessionSummary } };
+  'session.get': { params: { sessionId: string }; result: { 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': { params: { sessionId: string }; result: { status: TreeStatus } };
+  'session.message': { params: { sessionId: string; text: string }; result: Empty };
+  'session.log': { params: { sessionId: string }; result: { rootId: string; entries: Array<Record<string, unknown>> } };
+  'extension.register': { params: { method: string }; result: { registered: string } };
+  'extension.unregister': { params: { method: string }; result: { unregistered: string } };
+  'team.list': { params: { projectRoot?: string }; result: { projectRoot: string | null; teams: TeamRow[] } };
+  'task.list': { params: { projectRoot: string }; result: { projectRoot: string; tasks: TaskRow[]; unreadable: Array<{ file: string; error: string }>; revision: string } };
+  'task.create': { params: { projectRoot: string; title: string; priority?: number; requestId?: string }; result: { id: string; duplicate?: true } };
+  'task.update': { params: { projectRoot: string; id: string; action: 'close' | 'reopen'; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number; landed?: string } };
+  'task.gate.resolve': { params: { projectRoot: string; id: string; gate: string; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number } };
+  'library.list': { params: { kind: LibraryKind; projectRoot?: string }; result: { projectRoot: string | null; entries: LibraryEntryRow[] } };
+  'library.get': {
+    params: { kind: LibraryKind; name: EntryName; projectRoot?: string; scope?: LibraryScope };
+    /** `content` carries `{ $secret: 'keep' }` in place of each secret value; `secrets` lists their JSON Pointers. */
+    result: { kind: LibraryKind; name: string; source: LibrarySource; overrides?: LibrarySource; content: Record<string, unknown>; revision: string | null; usedBy: string[]; librarySkills?: string[]; secrets?: string[] };
+  };
+  'library.save': {
+    params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data'; content: Record<string, unknown>; revision?: string | null; sync?: 'none' | 'known-projects' };
+    result: { revision: string | null; syncedProjects?: number; syncErrors?: string[] };
+  };
+  'library.delete': { params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data'; revision?: string }; result: { removed: true; now?: 'builtin' | 'library' } };
+  'library.duplicate': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data' }; result: { revision: string | null } };
+  'library.rename': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data' }; result: { revision: string | null } };
+  'library.skills.set': { params: { agent: EntryName; skills: EntryName[] }; result: { skills: string[] } };
+  'library.models': { params: Empty; result: { models: Array<{ id: string; label: string; efforts: string[]; effort?: string }> } };
+  'settings.language.get': { params: Empty; result: LanguageSetting };
+  'settings.language.set': { params: { language: string | null }; result: LanguageSetting };
+};
+
+export type RpcMethod = keyof RpcMethodMap;
+export type RpcParams<M extends RpcMethod> = RpcMethodMap[M]['params'];
+export type RpcResult<M extends RpcMethod> = RpcMethodMap[M]['result'];

package/src/session.ts

@@ -0,0 +1,97 @@
+import type { RuntimeKind } from './dto.js';
+import type { SessionSnapshot } 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 } };
+  /** 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 };
+/** 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;
+  /** 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;
+  lastError?: SessionError;
+  createdAt?: string;
+  updatedAt?: string;
+};

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,87 @@
+/** 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({ 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 = 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"]);
+
+/**
+ * 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 });
+
+/** 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); }