@anhlp/alp-protocol 0.0.0-beta.1

package/src/session.ts

@@ -0,0 +1,94 @@
+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;
+};
+
+export type PromptContent = Array<{ type: string; text?: 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,113 @@
+/**
+ * A dependency-free checker for the JSON Schema subset the protocol schemas use (draft-07:
+ * type, const, enum, properties, required, additionalProperties, items, 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.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,26 @@
+/** 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', settingsLanguage: 'settings.language' });
+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", "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"]);
+
+/** 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); }