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

package/dist/schedule.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A scheduled continuation: a one-shot job that opens a new turn on a root session at a
+ * given time, without a user message. The protocol owns the shape so every
+ * client (the CLI, a viewer, an agent tool) reads the same state.
+ */
+/** Where a job stands: waiting for its time, delivered, failed, or cancelled before it fired. */
+export type ScheduleStatus = 'pending' | 'delivered' | 'failed' | 'cancelled';
+/** Why a job failed or still waits; failed may mean execution is unknown. */
+export type ScheduleError = {
+    message: string;
+    code?: string;
+};
+/** One job as `schedule.list` and `schedule.get` answer it. */
+export type ScheduleJob = {
+    /** The job's own id, `sch_` and sixteen hex digits. */
+    id: string;
+    /** The project whose root session the job continues. */
+    projectRoot: string;
+    /** The root session the job opens a turn on. */
+    sessionId: string;
+    /** The continuation the job delivers. */
+    prompt: string;
+    /** When the job is due, in UTC (ISO 8601). */
+    dueAt: string;
+    status: ScheduleStatus;
+    /**
+     * How many times alpd tried to deliver the job. A job delivered once may have been
+     * tried twice: a retry after a crash reads the receipt of the first delivery.
+     */
+    attempts: number;
+    createdAt: string;
+    updatedAt: string;
+    /** When the job was delivered, failed or cancelled. */
+    deliveredAt?: string;
+    failedAt?: string;
+    cancelledAt?: string;
+    /** When the first delivery was tried. */
+    attemptedAt?: string;
+    /** How late the delivery was, in milliseconds; 0 when it was on time. */
+    lateByMs?: number;
+    /** The last error of the job: why it failed, or why it still waits. */
+    lastError?: ScheduleError;
+};

package/dist/session.d.ts

@@ -0,0 +1,285 @@
+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/dist/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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: any, value: unknown, root?: any): SchemaIssue[];
+export type SchemaIssue = {
+    path: string;
+    message: string;
+};

package/dist/validate.js

@@ -0,0 +1,151 @@
+// packages/protocol/src/validate.js
+var MAX_ISSUES = 8;
+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;
+}
+var typeMatches = (want, have) => want === have || want === "number" && have === "integer";
+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] !== void 0
+  ));
+  const right = Object.keys(
+    /** @type {object} */
+    b
+  ).filter((key) => (
+    /** @type {any} */
+    b[key] !== void 0
+  ));
+  return left.length === right.length && left.every((key) => equal(
+    /** @type {any} */
+    a[key],
+    /** @type {any} */
+    b[key]
+  ));
+}
+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 === void 0) throw new Error(`Unresolved schema reference ${ref}`);
+  return target;
+}
+function check(schema, value, at, root, issues) {
+  if (issues.length >= MAX_ISSUES || schema === true || schema === void 0) 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 !== void 0) {
+    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 !== void 0 && number < schema.minimum) issues.push({ path: at, message: `must be at least ${schema.minimum}` });
+    if (schema.maximum !== void 0 && 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 !== void 0 || schema.maxLength !== void 0) for (const _point of text) length++;
+    if (schema.minLength !== void 0 && length < schema.minLength) issues.push({ path: at, message: `must have at least ${schema.minLength} characters` });
+    if (schema.maxLength !== void 0 && length > schema.maxLength) issues.push({ path: at, message: `must have at most ${schema.maxLength} characters` });
+    if (schema.pattern !== void 0 && !new RegExp(schema.pattern, "u").test(text)) issues.push({ path: at, message: `must match ${schema.pattern}` });
+  }
+  if (kind === "array" && schema.minItems !== void 0 && /** @type {unknown[]} */
+  value.length < schema.minItems) issues.push({ path: at, message: `must have at least ${schema.minItems} items` });
+  if (kind === "array" && schema.maxItems !== void 0 && /** @type {unknown[]} */
+  value.length > schema.maxItems) issues.push({ path: at, message: `must have at most ${schema.maxItems} items` });
+  if (kind === "array" && schema.items !== void 0) {
+    const array = (
+      /** @type {unknown[]} */
+      value
+    );
+    for (let index = 0; index < array.length && issues.length < MAX_ISSUES; index++) check(schema.items, array[index] === void 0 ? 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] === void 0) issues.push({ path: `${at}/${name}`, message: "is required" });
+    for (const [name, child] of Object.entries(object)) {
+      if (child === void 0) continue;
+      if (Object.hasOwn(properties, name)) check(properties[name], child, `${at}/${name}`, root, issues);
+      else if (schema.additionalProperties !== void 0) check(schema.additionalProperties, child, `${at}/${name}`, root, issues);
+    }
+  }
+  if (schema.not !== void 0) {
+    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) => {
+        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" });
+  }
+}
+function validateSchema(schema, value, root = schema) {
+  const issues = [];
+  check(schema, value, "", root, issues);
+  return issues;
+}
+export {
+  validateSchema
+};