@anhlp/alp-protocol 0.0.1-beta.3 → 0.0.1-beta.4

package/dist/rpc.d.ts

@@ -1,8 +1,9 @@
 /** 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 { AlpError, Envelope, SessionSnapshot, TreeStatus, TurnAttention, UserQuestion } from './events.js';
+import type { ConfigureOutcome, ConfigurePreview, ConversationBranch, ForkProvenance, PauseState, PromptContent, RecallAnswer, ResumeCommand, SessionPreview, SessionSpec, SessionSummary } from './session.js';
 import type { EntryName, LanguageSetting, LibraryEntryRow, LibraryKind, LibraryScope, LibrarySource, TaskRow, TeamRow } from './dto.js';
+import type { ScheduleJob, ScheduleStatus } from './schedule.js';
 export type RpcId = string | number | null;
 export type RpcErrorData = {
     code: number;
@@ -30,17 +31,489 @@ export type EventNotification = {
     method: 'event';
     params: Envelope;
 };
+/** Why a terminal ended (§12.10). */
+export type TerminalEndReason = 'exited' | 'closed' | 'idle' | 'lifetime' | 'detached' | 'revoked' | 'disabled' | 'shutdown';
+/** A terminal as clients see it (capability `terminal`, §12.10): never a process id, shell path or host path. */
+export type TerminalInfo = {
+    terminalId: string;
+    workspaceId: string;
+    title: string;
+    cols: number;
+    rows: number;
+    state: 'running' | 'exited';
+    attached: boolean;
+    createdAt: string;
+    lastActivityAt: string;
+    expiresAt: string;
+    exitCode?: number | null;
+    signal?: number | null;
+    endReason?: TerminalEndReason;
+};
+/** Effective terminal limits a daemon.hello advertises with capability `terminal`. */
+export type TerminalLimits = {
+    maxPerPrincipal: number;
+    maxPerDaemon: number;
+    maxInputBytes: number;
+    maxOutputFrameBytes: number;
+    replayBytes: number;
+    idleMs: number;
+    maxLifetimeMs: number;
+    reconnectMs: number;
+};
+/** params of a terminal.event notification, sent only to the connection attached to the terminal. */
+export type TerminalEvent = {
+    terminalId: string;
+    type: 'output';
+    seq: number;
+    data: string;
+} | {
+    terminalId: string;
+    type: 'exit';
+    seq: number;
+    exitCode: number | null;
+    signal: number | null;
+    reason: TerminalEndReason;
+} | {
+    terminalId: string;
+    type: 'detached';
+    reason: 'replaced' | 'slow_consumer';
+};
+export type TerminalNotification = {
+    jsonrpc: '2.0';
+    method: 'terminal.event';
+    params: TerminalEvent;
+};
 /** 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';
+export type HistoryItem = Envelope | {
+    cursor: number;
+    oversized: {
+        bytes: number;
+    };
+};
+export type HistoryPage = {
+    generation: string;
+    items: HistoryItem[];
+    olderCursor?: string;
+    hasOlder: boolean;
+    tipCursor: number;
+};
+export type Capability = 'session.interrupt.turn' | 'session.fork' | 'session.rewind' | 'session.reload' | 'session.resumeCommand' | 'session.configure.live' | 'terminal' | 'attachments' | 'workspace.git' | 'workspace.worktree' | 'workspace.registry' | 'session.history' | 'attach.after' | 'prompt.receipts' | 'extension.methods' | 'team' | 'task' | 'library' | 'library.project.write' | 'settings.language' | 'session.list.page' | 'question.watch' | 'question.watch.turns' | 'session.attention' | 'workspace.files' | 'workspace.files.read' | 'prompt.images' | 'schedule';
 /** `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' | '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' | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large';
+export type ErrorReason = 'hello_required' | 'protocol_version' | 'invalid_params' | 'invalid_id' | 'batch_unsupported' | 'frame_too_large' | 'invalid_cursor' | 'stale_cursor' | 'history_gap' | 'stale_revision' | 'request_conflict' | 'cwd_mismatch' | 'workspace_mismatch' | 'corrupt_registry' | 'identity_changed' | 'response_too_large' | 'persistence_failed' | 'outcome_unknown' | 'key_conflict' | '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' | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large' | 'not_repository' | 'unknown_ref' | 'invalid_compare' | 'stale_snapshot' | 'git_unavailable' | 'git_failed' | 'invalid_name' | 'invalid_data' | 'attachment_too_large' | 'offset_mismatch' | 'chunk_conflict' | 'upload_incomplete' | 'hash_mismatch' | 'upload_expired' | 'quota_exceeded' | 'attachment_referenced' | 'attachment_limit' | 'attachment_unavailable' | 'attachment_unsupported' | 'session_busy' | 'stale_generation' | 'turn_not_found' | 'turn_in_progress' | 'empty_prefix' | 'boundary_unmapped' | 'runtime_unsupported' | 'native_refused' | 'branch_not_found' | 'attachment_forbidden' | 'session_closed' | 'no_history' | 'runtime_mismatch' | 'agent_mismatch' | 'permission_escalation' | 'team_not_found' | 'terminal_disabled' | 'terminal_unsupported' | 'terminal_limit' | 'not_attached' | 'terminal_exited' | 'input_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 RegistryProject = {
+    id: string;
+    root: string;
+    canonical?: string;
+    customName?: string | null;
+    addedAt: string;
+    removedAt?: string | null;
+    revision?: number;
+};
+export type RegistryWorkspace = {
+    branch?: string | null;
+    managedWorktree?: boolean;
+    id: string;
+    projectId: string;
+    directory: string;
+    canonical?: string;
+    title?: string | null;
+    pinnedAt?: string | null;
+    archivedAt?: string | null;
+    labels: string[];
+    createdAt: string;
+    revision?: number;
+    idempotencyKey?: string;
+};
+/** workspace.git.status and workspace.git.diff (capability `workspace.git`, §12.5): paths are relative to the workspace, never host paths. */
+export type GitChange = 'modified' | 'added' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'untracked' | 'conflicted';
+export type GitCompare = {
+    mode: 'uncommitted' | 'staged' | 'unstaged' | 'base';
+    baseRef?: string;
+    ignoreWhitespace?: boolean;
+};
+export type GitStatusFile = {
+    path: string;
+    oldPath?: string;
+    change: GitChange;
+    staged: boolean;
+    unstaged: boolean;
+};
+export type GitStatus = {
+    state: 'repository' | 'not_repository' | 'unsupported';
+    reason?: string;
+    branch: string | null;
+    detached: boolean;
+    head: string | null;
+    upstream: {
+        ref: string;
+        ahead: number;
+        behind: number;
+    } | null;
+    baseRef: string | null;
+    aheadBehind: {
+        ahead: number;
+        behind: number;
+    } | null;
+    hasRemote: boolean;
+    remoteUrl: string | null;
+    dirty: boolean;
+    files: GitStatusFile[];
+    hiddenCount: number;
+    truncated: boolean;
+    snapshot: string;
+};
+export type GitDiffLine = {
+    type: 'add' | 'remove' | 'context';
+    content: string;
+    noNewline?: true;
+};
+export type GitDiffHunk = {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    context?: string;
+    lines: GitDiffLine[];
+};
+export type GitDiffFile = {
+    path: string;
+    oldPath?: string;
+    change: GitChange;
+    kind: 'text' | 'binary' | 'too_large' | 'withheld' | 'symlink' | 'submodule';
+    additions: number;
+    deletions: number;
+    hunks: GitDiffHunk[];
+};
+export type GitDiffPage = {
+    compare: {
+        mode: GitCompare['mode'];
+        baseRef?: string;
+        ignoreWhitespace: boolean;
+    };
+    snapshot: string;
+    files: GitDiffFile[];
+    hiddenCount: number;
+    truncated: boolean;
+    nextCursor?: string;
+};
+/**
+ * Capability `attachments` (§12.6). Principal context is set only by a trusted gateway on its own
+ * connection; a local client leaves it out and acts as the owner.
+ */
+export type PrincipalContext = {
+    principalId?: string;
+    principalEpoch?: string;
+    authorizedRoots?: string[];
+};
+/** A committed attachment as clients see it: ids and display metadata, never a host path or URL. */
+export type AttachmentInfo = {
+    attachmentId: string;
+    sessionId: string;
+    name: string;
+    mimeType: string;
+    detectedMimeType: string;
+    size: number;
+    sha256: string;
+    createdAt: string;
+    committedAt: string;
+    referenced: boolean;
+};
+/** Effective attachment limits a daemon.hello advertises with capability `attachments`. */
+export type AttachmentLimits = {
+    maxObjectBytes: number;
+    maxPerPrompt: number;
+    maxPromptBytes: number;
+    maxChunkBytes: number;
+    maxActiveUploads: number;
+    maxPrincipalBytes: number;
+    maxDaemonBytes: number;
+    uploadTimeoutMs: number;
+    unreferencedRetentionMs: number;
+    releasedGraceMs: number;
+};
+/** Where a fork cuts the source conversation (§12.7): after a completed turn, or before a turn. */
+export type ForkBoundary = {
+    throughTurnId: string;
+} | {
+    beforeTurnId: string;
+};
+export type RegistryMutation = {
+    requestId: string;
+    ifRevision: number;
+};
+export type RegistryPage = {
+    revision: number;
+    total: number;
+    nextCursor: string | null;
+};
 export type RpcMethodMap = {
+    'terminal.create': {
+        params: PrincipalContext & {
+            workspaceId: string;
+            cols: number;
+            rows: number;
+            requestId: string;
+        };
+        result: {
+            terminal: TerminalInfo;
+        };
+    };
+    'terminal.list': {
+        params: PrincipalContext & {
+            workspaceId?: string;
+        };
+        result: {
+            terminals: TerminalInfo[];
+        };
+    };
+    'terminal.attach': {
+        params: PrincipalContext & {
+            terminalId: string;
+            after?: number;
+        };
+        result: {
+            terminal: TerminalInfo;
+            nextSeq: number;
+            gap?: {
+                fromSeq: number;
+                toSeq: number;
+            };
+        };
+    };
+    'terminal.input': {
+        params: PrincipalContext & {
+            terminalId: string;
+            data: string;
+        };
+        result: {
+            bytes: number;
+        };
+    };
+    'terminal.resize': {
+        params: PrincipalContext & {
+            terminalId: string;
+            cols: number;
+            rows: number;
+        };
+        result: {
+            cols: number;
+            rows: number;
+        };
+    };
+    'terminal.close': {
+        params: PrincipalContext & {
+            terminalId: string;
+        };
+        result: {
+            closed: true;
+        };
+    };
+    'terminal.revoke': {
+        params: {
+            principalId: string;
+        };
+        result: {
+            closed: number;
+        };
+    };
+    'attachment.begin': {
+        params: PrincipalContext & {
+            sessionId: string;
+            name: string;
+            size: number;
+            mimeType: string;
+            sha256?: string;
+            requestId: string;
+        };
+        result: {
+            uploadId: string;
+            state: 'uploading' | 'committed';
+            received: number;
+            size: number;
+            maxChunkBytes: number;
+            expiresAt?: string;
+            attachmentId?: string;
+        };
+    };
+    'attachment.chunk': {
+        params: PrincipalContext & {
+            uploadId: string;
+            offset: number;
+            data: string;
+        };
+        result: {
+            received: number;
+            size: number;
+        };
+    };
+    'attachment.commit': {
+        params: PrincipalContext & {
+            uploadId: string;
+            sha256: string;
+        };
+        result: {
+            attachment: AttachmentInfo;
+        };
+    };
+    'attachment.abort': {
+        params: PrincipalContext & {
+            uploadId: string;
+        };
+        result: {
+            aborted: true;
+        };
+    };
+    'attachment.get': {
+        params: PrincipalContext & {
+            attachmentId: string;
+        };
+        result: {
+            attachment: AttachmentInfo;
+        };
+    };
+    'attachment.delete': {
+        params: PrincipalContext & {
+            attachmentId: string;
+        };
+        result: {
+            deleted: true;
+        };
+    };
+    'workspace.git.status': {
+        params: {
+            workspaceId: string;
+        };
+        result: GitStatus;
+    };
+    'workspace.git.diff': {
+        params: {
+            workspaceId: string;
+            compare: GitCompare;
+            path?: string;
+            cursor?: string;
+        };
+        result: GitDiffPage;
+    };
+    'workspace.worktree.options': {
+        params: {
+            workspaceId: string;
+        };
+        result: {
+            mappingIds: string[];
+        };
+    };
+    'workspace.worktree.create': {
+        params: RegistryMutation & {
+            workspaceId: string;
+            mappingId: string;
+        };
+        result: {
+            workspace: RegistryWorkspace;
+            revision: number;
+        };
+    };
+    'workspace.worktree.remove': {
+        params: RegistryMutation & {
+            workspaceId: string;
+        };
+        result: {
+            workspace: RegistryWorkspace;
+            revision: number;
+            filesRemoved: true;
+            branchRetained: true;
+        };
+    };
+    'registry.worktree': {
+        params: {
+            principalId?: string;
+            principalEpoch?: string;
+            mappingIds?: string[];
+            authorizedRoots?: string[];
+        };
+        result: {
+            mappings: Array<{
+                id: string;
+                source: string;
+            }>;
+            workspaces: unknown[];
+        };
+    };
+    'project.list': {
+        params: {
+            cursor?: string;
+            limit?: number;
+            projectRoots?: string[];
+        };
+        result: RegistryPage & {
+            projects: RegistryProject[];
+        };
+    };
+    'workspace.list': {
+        params: {
+            cursor?: string;
+            limit?: number;
+            projectRoots?: string[];
+        };
+        result: RegistryPage & {
+            workspaces: RegistryWorkspace[];
+        };
+    };
+    'workspace.get': {
+        params: {
+            workspaceId: string;
+        };
+        result: {
+            workspace: RegistryWorkspace;
+            revision: number;
+        };
+    };
+    'project.register': {
+        params: RegistryMutation & {
+            directory: string;
+        };
+        result: {
+            project: RegistryProject;
+            revision: number;
+        };
+    };
+    'project.remove': {
+        params: RegistryMutation & {
+            projectId: string;
+        };
+        result: {
+            project: RegistryProject;
+            revision: number;
+        };
+    };
+    'workspace.update': {
+        params: RegistryMutation & {
+            workspaceId: string;
+            title?: string | null;
+            pinned?: boolean;
+            archived?: boolean;
+        };
+        result: {
+            workspace: RegistryWorkspace;
+            revision: number;
+        };
+    };
+    'registry.owner': {
+        params: {
+            operation?: string;
+            args?: Record<string, unknown>;
+            requestId?: string;
+            ifRevision?: number;
+        };
+        result: {
+            registry: Record<string, unknown>;
+        };
+    };
     'daemon.hello': {
         params: {
             protocolVersion: 1;
@@ -60,6 +533,8 @@ export type RpcMethodMap = {
                 maxBytes: number;
                 maxTotalBytes: number;
             };
+            attachmentLimits?: AttachmentLimits;
+            terminalLimits?: TerminalLimits;
             capabilities?: string[];
         };
     };
@@ -153,14 +628,29 @@ export type RpcMethodMap = {
             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`. */
+    /** 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`. `attention` (capability `session.attention`): also each root's attention, now and as it changes. */
     'question.watch': {
         params: {
             projectRoot?: string;
             turns?: boolean;
+            attention?: boolean;
         };
         result: {
             questions: UserQuestion[];
+            attention?: Array<{
+                sessionId: string;
+                attention: TurnAttention;
+            }>;
+        };
+    };
+    /** Capability `session.attention`: acknowledges a root's attention for every client; with `at`, only that one (a later turn's stays). */
+    'session.attention.clear': {
+        params: {
+            sessionId: string;
+            at?: string;
+        };
+        result: {
+            cleared: boolean;
         };
     };
     /** Capability `workspace.files`: files under `projectRoot` whose relative path matches `query`, best first; read-only, links not followed. */
@@ -223,11 +713,18 @@ export type RpcMethodMap = {
     'session.create': {
         params: {
             sessionId?: string;
-            spec: SessionSpec;
             history?: 'skip' | 'replay';
             delegation?: boolean;
             resume?: boolean;
-        };
+        } & ({
+            workspaceId: string;
+            spec: Omit<SessionSpec, 'cwd'> & {
+                cwd?: string;
+            };
+        } | {
+            workspaceId?: undefined;
+            spec: SessionSpec;
+        });
         result: {
             session: SessionSnapshot;
             attached: boolean;
@@ -243,11 +740,21 @@ export type RpcMethodMap = {
             preview: SessionPreview;
         };
     };
+    'session.history': {
+        params: {
+            sessionId: string;
+            before?: string;
+            limit?: number;
+            maxBytes?: number;
+        };
+        result: HistoryPage;
+    };
     'session.attach': {
         params: {
             sessionId: string;
             replay?: boolean;
             after?: number;
+            generation?: string;
         };
         result: {
             session: SessionSummary;
@@ -264,7 +771,7 @@ export type RpcMethodMap = {
         };
     };
     'session.prompt': {
-        params: {
+        params: PrincipalContext & {
             sessionId: string;
             clientMessageId: string;
             delivery?: 'auto' | 'steer';
@@ -280,17 +787,46 @@ export type RpcMethodMap = {
     };
     'session.interrupt': {
         params: {
-            sessionId: string;
+            sessionId: string; /** With session.interrupt.turn, cancel only this turn. */
+            turnId?: string;
+        };
+        result: {
+            interrupted?: boolean;
         };
-        result: Empty;
     };
+    /**
+     * Changes a session's permissions mode while idle; with capability `session.configure.live`, also a live
+     * root's model, effort or team (§12.9): those need requestId and ifGeneration, apply at the idle barrier
+     * through a restart of its native process on the same conversation, and answer `configured`. Answered
+     * once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
+     */
     'session.configure': {
         params: {
             sessionId: string;
             mode?: string;
+            model?: string;
+            thinking?: string;
+            team?: string;
+            requestId?: string;
+            ifGeneration?: string;
         };
         result: {
-            session: SessionSnapshot;
+            session: SessionSnapshot | SessionSummary;
+            configured?: ConfigureOutcome;
+            duplicate?: true;
+        };
+    };
+    /** What session.configure would run a live root with, and whether it would take it now (capability `session.configure.live`, §12.9). */
+    'session.configure.preview': {
+        params: {
+            sessionId: string;
+            mode?: string;
+            model?: string;
+            thinking?: string;
+            team?: string;
+        };
+        result: {
+            preview: ConfigurePreview;
         };
     };
     'session.close': {
@@ -308,6 +844,71 @@ export type RpcMethodMap = {
             session: SessionSummary;
         };
     };
+    /**
+     * A new root whose conversation is the source's up to a completed turn (capability `session.fork`, §12.7).
+     * Answered once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
+     */
+    'session.fork': {
+        params: PrincipalContext & {
+            sessionId: string;
+            requestId: string;
+            ifGeneration: string;
+            boundary?: ForkBoundary;
+            branchId?: string;
+            workspaceId?: string;
+            newSessionId?: string;
+            title?: string;
+        };
+        result: {
+            session: SessionSummary;
+            forkedFrom: ForkProvenance;
+            duplicate?: true;
+        };
+    };
+    /**
+     * The root's conversation from before a turn on, under the same session id; the later turns stay as a
+     * recoverable branch and no file is changed (capability `session.rewind`, §12.7).
+     */
+    'session.rewind': {
+        params: {
+            sessionId: string;
+            requestId: string;
+            ifGeneration: string;
+            beforeTurnId: string;
+        };
+        result: {
+            session: SessionSummary;
+            generation: string;
+            branch: ConversationBranch;
+            duplicate?: true;
+        };
+    };
+    /**
+     * Restarts a live root's native process on its own conversation and configuration at the idle
+     * barrier, keeping its session id, history and receipts (capability `session.reload`, §12.8).
+     * Answered once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
+     */
+    'session.reload': {
+        params: {
+            sessionId: string;
+            requestId: string;
+            ifGeneration: string;
+        };
+        result: {
+            session: SessionSummary;
+            duplicate?: true;
+        };
+    };
+    /**
+     * The ALP CLI command that continues a session in a terminal, built by alpd (capability
+     * `session.resumeCommand`, §12.8): argv and its POSIX and Windows command lines, for the clipboard only.
+     */
+    'session.resumeCommand': {
+        params: {
+            sessionId: string;
+        };
+        result: ResumeCommand;
+    };
     'session.archive': {
         params: {
             sessionId: string;
@@ -563,6 +1164,45 @@ export type RpcMethodMap = {
         };
         result: LanguageSetting;
     };
+    /** Capability `schedule`: a one-shot continuation of a root session, due at `dueAt` (UTC, ISO 8601). */
+    'schedule.create': {
+        params: {
+            projectRoot: string;
+            sessionId: string;
+            dueAt: string;
+            prompt: string;
+        };
+        result: {
+            job: ScheduleJob;
+        };
+    };
+    'schedule.list': {
+        params: {
+            projectRoot: string;
+            status?: ScheduleStatus;
+        };
+        result: {
+            jobs: ScheduleJob[];
+        };
+    };
+    'schedule.get': {
+        params: {
+            id: string;
+            projectRoot: string;
+        };
+        result: {
+            job: ScheduleJob;
+        };
+    };
+    'schedule.cancel': {
+        params: {
+            id: string;
+            projectRoot: string;
+        };
+        result: {
+            job: ScheduleJob;
+        };
+    };
 };
 export type RpcMethod = keyof RpcMethodMap;
 export type RpcParams<M extends RpcMethod> = RpcMethodMap[M]['params'];