@anhlp/alp-protocol 0.0.0-stage → 0.10.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @anhlp/alp-protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stable JSON-RPC v1, portable session/event DTOs, JSON Schema and fixtures.
+
+Build: `npm run build --workspace=@anhlp/alp-protocol`. Test: `npm run test --workspace=@anhlp/alp-protocol`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).

package/dist/connection.d.ts

@@ -0,0 +1,9 @@
+import type { Envelope } from './events.js';
+export type DaemonConnection = {
+    request<T = any>(method: string, params?: unknown): Promise<T>;
+    onEvent(listener: (envelope: Envelope) => void): () => void;
+    onClose(listener: (error: Error) => void): () => void;
+    close(): void;
+    /** True once the connection is gone; socket clients report it, in-process ones may not. */
+    readonly closed?: boolean;
+};

package/dist/dto.d.ts

@@ -0,0 +1,36 @@
+export type RuntimeKind = 'codex' | 'claude' | 'acp' | 'antigravity';
+export type MailKind = 'question' | 'answer' | 'note' | 'steer' | 'result' | 'stalled' | 'board' | 'checkin';
+export type MailEvent = {
+    id: string;
+    kind: MailKind;
+    from: string;
+    assignment: string;
+    body?: string;
+    replyTo?: string;
+    result?: Record<string, unknown>;
+    redelivered?: boolean;
+    /** Informational; never steers or wakes a session by itself. */
+    passive?: boolean;
+    /** Delivered between turns, never steered into a running one or taken by alp_wait. */
+    defer?: boolean;
+    /** Turn that received the event; acknowledged when that turn completes. */
+    deliveredTurn?: string;
+};
+export type PinKind = 'claim' | 'decision' | 'finding';
+export type Pin = {
+    id: string;
+    /** The project root the board belongs to. */
+    project: string;
+    kind: PinKind;
+    body: string;
+    /** Project-relative files or directories, or absolute paths in an external write root; required for claims. */
+    paths?: string[];
+    agent: string;
+    sessionId: string;
+    rootId: string;
+    at: string;
+    /** When a claim ended, or any pin was taken down. */
+    released?: string;
+    /** The task the claiming assignment works on. */
+    task?: string;
+};

package/dist/events.d.ts

@@ -0,0 +1,217 @@
+import type { RuntimeKind, MailEvent, Pin } from './dto.js';
+/** Provider-neutral session events (plans/reference/ALPD.md §4). Viewers project them; the runtime never imports a viewer. */
+export type AlpError = {
+    message: string;
+};
+export type TimelineItem = {
+    kind: 'user_message';
+    id: string;
+    text: string;
+    clientMessageId?: string;
+} | {
+    kind: 'assistant_message';
+    id: string;
+    text: string;
+}
+/** Something about ALP as a whole the user should see, such as a usage limit or a pause (ALPD §29). */
+ | {
+    kind: 'notice';
+    id: string;
+    level: 'info' | 'warning' | 'error';
+    text: string;
+}
+/** The runtime compacting the session's context (ALPD §57). */
+ | {
+    kind: 'compaction';
+    id: string;
+    status: 'running' | 'completed' | 'failed';
+    trigger?: 'auto' | 'manual';
+    preTokens?: number;
+    postTokens?: number;
+}
+/** The tasks a root's tree created or worked on (plans/reference/ALPD.md §21). */
+ | {
+    kind: 'todo';
+    id: string;
+    items: Array<{
+        id: string;
+        text: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }>;
+} | {
+    kind: 'tool_call';
+    id: string;
+    callId: string;
+    name: string;
+    status: 'running' | 'completed' | 'failed';
+    error?: string;
+    detail: {
+        type: 'shell';
+        command: string;
+        cwd?: string;
+        output: string;
+        exitCode?: number | null;
+    } | {
+        type: 'unknown';
+        input: unknown;
+        output: unknown;
+    };
+};
+export type SessionSnapshot = {
+    id: string;
+    projectRoot: string;
+    agent: string;
+    runtime: RuntimeKind;
+    model: string;
+    mode: string;
+    thinking: string;
+    workflow: {
+        mode: string;
+        maxPeers: number;
+        supervisor: boolean;
+    };
+    /** The label of the session's team, such as Phở (ALPD §42); absent for a custom graph. */
+    teamLabel?: string;
+    threadId: string;
+    /** The native thread is kept and the session can be resumed. */
+    persistent: boolean;
+    parentId?: string;
+    /** The requester's tool call that started this assignment. */
+    toolCallId?: string;
+    activeTurnId?: string;
+    /** A turn, an assignment, a child, or undelivered mail keeps the session working. */
+    busy: boolean;
+    /** Why a usage limit or a pause parked this assignment (ALPD §29). */
+    parked?: string;
+    /** A digest of the instructions the session runs with (ALPD §34). */
+    instructionsSha?: string;
+};
+export type AssignmentSnapshot = {
+    id: string;
+    agent: string;
+    mode: string;
+    status: string;
+    startedAt: string;
+    /** An isolated assignment's branch and working directory. */
+    worktree?: {
+        branch: string;
+        path: string;
+    };
+};
+/** runtime: a turn the native runtime started by itself, such as Claude after a background task ended. */
+export type TurnOrigin = 'user' | 'wake' | 'assignment' | 'runtime';
+/** A question an agent asked the user with alp_ask to: "user". */
+export type UserQuestion = {
+    id: string;
+    sessionId: string;
+    rootId: string;
+    agent: string;
+    body: string;
+    options?: string[];
+    askedAt: string;
+};
+export type SessionState = 'running' | 'waiting' | 'waiting_parent' | 'waiting_user' | 'idle';
+/** A live tree at one moment, for dashboards (plans/reference/ALPD.md §17). */
+export type TreeStatus = {
+    rootId: string;
+    sessions: Array<SessionSnapshot & {
+        state: SessionState;
+        idleMs: number;
+        workdir: string;
+        unreadMail: number;
+    }>;
+    assignments: Array<AssignmentSnapshot & {
+        requester: string;
+        isolation: 'shared' | 'worktree';
+        idleMs: number;
+    }>;
+    questions: UserQuestion[];
+    /** Finished worktree assignments waiting for alp_merge or alp_discard. */
+    worktrees: Array<{
+        assignmentId: string;
+        requester: string;
+        agent: string;
+        branch: string;
+        files: string[];
+        stat: string;
+    }>;
+    leases: Array<{
+        checkout: string;
+        assignmentId: string;
+        agent: string;
+    }>;
+    /** Live claims on the project board held by this tree's sessions. */
+    claims: Pin[];
+};
+export type AlpEvent = {
+    type: 'session.opened';
+    session: SessionSnapshot;
+    cwd: string;
+    effective: {
+        model: string;
+        thinking: string;
+    };
+} | {
+    type: 'session.ready';
+} | {
+    type: 'session.updated';
+    session: SessionSnapshot;
+} | {
+    type: 'session.closed';
+} | {
+    type: 'session.failed';
+    error: AlpError;
+} | {
+    type: 'prompt.accepted';
+    clientMessageId: string;
+    result: 'turn' | 'steer';
+    turnId: string;
+} | {
+    type: 'prompt.failed';
+    clientMessageId: string;
+    error: AlpError;
+} | {
+    type: 'turn.started';
+    turnId: string;
+    origin: TurnOrigin;
+} | {
+    type: 'turn.ended';
+    turnId: string;
+    state: 'completed' | 'failed' | 'canceled';
+    error?: AlpError;
+} | {
+    type: 'item';
+    item: TimelineItem;
+} | {
+    type: 'mail';
+    mail: Omit<MailEvent, 'passive' | 'deliveredTurn'>;
+} | {
+    type: 'assignment';
+    assignment: AssignmentSnapshot;
+} | {
+    type: 'question';
+    question: UserQuestion;
+} | {
+    type: 'question.resolved';
+    questionId: string;
+    outcome: 'answered' | 'dismissed' | 'timeout' | 'canceled';
+    answer?: string;
+}
+/** Emitted on the session that pinned it (plans/reference/ALPD.md §18). */
+ | {
+    type: 'pin';
+    pin: Pin;
+} | {
+    type: 'unpin';
+    pinId: string;
+    reason: 'unpinned' | 'session_ended';
+};
+export type Envelope = {
+    sessionId: string;
+    /** Random per runtime instance; a cursor from another epoch is stale. */
+    epoch: string;
+    /** Strictly increasing per session. */
+    seq: number;
+    ts: string;
+    event: AlpEvent;
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './wire.js';
+export type * from './dto.js';
+export type * from './events.js';
+export type * from './connection.js';
+export type * from './session.js';
+export type * from './rpc.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// packages/protocol/src/index.ts
+export * from "./wire.js";

package/dist/public.d.ts

@@ -0,0 +1 @@
+export * from "./wire.js";

package/dist/public.js

@@ -0,0 +1,2 @@
+// packages/protocol/src/public.js
+export * from "./wire.js";

package/dist/rpc.d.ts

@@ -0,0 +1,28 @@
+/** Portable JSON-RPC structures; implementations and provider SDKs stay outside protocol. */
+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: import('./events.js').Envelope;
+};

package/dist/session.d.ts

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

@@ -0,0 +1,19 @@
+/** UTF-8 socket writers use one newline-terminated JSON value per frame. @param {unknown} value */
+export function encodeFrame(value: unknown): string;
+/** Parse one complete frame. Buffering and failure handling belong to the socket owner. @param {string} line @returns {unknown} */
+export function decodeFrame(line: string): unknown;
+/** Wire protocol of alpd (plans/reference/ALPD.md §3). Bump only for incompatible changes. */
+export const PROTOCOL_VERSION: 1;
+export const MAX_FRAME: number;
+export class AlpRpcError extends Error {
+    constructor(error: any);
+    code: any;
+    data: any;
+}
+export const ERROR: Readonly<{
+    failed: 1000;
+    notFound: 1001;
+    conflict: 1004;
+    protocol: 1006;
+}>;
+export const RPC_METHODS: readonly string[];

package/dist/wire.js

@@ -0,0 +1,28 @@
+// packages/protocol/src/wire.js
+var PROTOCOL_VERSION = 1;
+var MAX_FRAME = 16 * 1024 * 1024;
+var AlpRpcError = class extends Error {
+  constructor(error) {
+    super(error?.message ?? "ALP daemon request failed");
+    this.code = error?.code;
+    this.data = error?.data;
+  }
+};
+var ERROR = Object.freeze({ failed: 1e3, notFound: 1001, conflict: 1004, protocol: 1006 });
+var 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", "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"]);
+function encodeFrame(value) {
+  return `${JSON.stringify(value)}
+`;
+}
+function decodeFrame(line) {
+  return JSON.parse(line);
+}
+export {
+  AlpRpcError,
+  ERROR,
+  MAX_FRAME,
+  PROTOCOL_VERSION,
+  RPC_METHODS,
+  decodeFrame,
+  encodeFrame
+};

package/fixtures/ipc-v1.jsonl

@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"method":"daemon.hello","params":{"protocolVersion":1,"client":{"name":"fixture","version":"0.9.5"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1}}
+{"jsonrpc":"2.0","method":"event","params":{"sessionId":"ses_fixture","epoch":"fixture-epoch","seq":1,"ts":"2026-10-14T00:00:00.000Z","event":{"type":"session.ready"}}}
+{"jsonrpc":"2.0","id":2,"error":{"code":1001,"message":"No session ses_fixture"}}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@anhlp/alp-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "type": "module",
+  "description": "ALP protocol module",
+  "files": [
+    "src",
+    "dist",
+    "schema",
+    "fixtures"
+  ],
+  "exports": {
+    "./connection": {
+      "alp-source": {
+        "types": "./src/connection.ts",
+        "default": "./src/connection.ts"
+      },
+      "types": "./dist/connection.d.ts",
+      "default": "./dist/connection.js"
+    },
+    "./dto": {
+      "alp-source": {
+        "types": "./src/dto.ts",
+        "default": "./src/dto.ts"
+      },
+      "types": "./dist/dto.d.ts",
+      "default": "./dist/dto.js"
+    },
+    "./events": {
+      "alp-source": {
+        "types": "./src/events.ts",
+        "default": "./src/events.ts"
+      },
+      "types": "./dist/events.d.ts",
+      "default": "./dist/events.js"
+    },
+    "./index": {
+      "alp-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/public.js"
+    },
+    ".": {
+      "alp-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/public.js"
+    },
+    "./wire": {
+      "alp-source": {
+        "types": "./src/wire.js",
+        "default": "./src/wire.js"
+      },
+      "types": "./dist/wire.d.ts",
+      "default": "./src/wire.js"
+    },
+    "./schema": {
+      "default": "./schema/ipc-v1.json"
+    },
+    "./session": {
+      "alp-source": {
+        "types": "./src/session.ts",
+        "default": "./src/session.ts"
+      },
+      "types": "./dist/session.d.ts",
+      "default": "./dist/session.js"
+    },
+    "./rpc": {
+      "alp-source": {
+        "types": "./src/rpc.ts",
+        "default": "./src/rpc.ts"
+      },
+      "types": "./dist/rpc.d.ts",
+      "default": "./dist/rpc.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "scripts": {
+    "build": "node ../../scripts/build-workspace.mjs protocol",
+    "test": "node ../../scripts/test-package.mjs protocol",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucanh08/alp-paseo.git",
+    "directory": "packages/protocol"
+  },
+  "devDependencies": {
+    "ajv": "8.17.1"
+  }
+}