@anhlp/alp-protocol 0.0.0-beta.2 → 0.0.1-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/dto.ts CHANGED
@@ -54,7 +54,7 @@ export type TaskRow = {
54
54
  ready: boolean;
55
55
  blockedBy?: string[];
56
56
  waits?: string[];
57
- approvals?: Array<{ gate: string; note: string }>;
57
+ approvals?: Array<{ gate: string; note: string; /** Answers to pick from; any approves. */ options?: string[]; /** The user's latest rejection; the gate stays open. */ rejected?: { at: string; reason?: string } }>;
58
58
  handoff?: { outcome: string; summary: string; agent?: string };
59
59
  closed?: { reason: string; summary?: string; at: string };
60
60
  description?: string;
package/src/events.ts CHANGED
@@ -6,7 +6,13 @@ import type { RuntimeKind, MailEvent, Pin } from './dto.js';
6
6
  export type AlpError = { message: string; code?: string };
7
7
 
8
8
  export type TimelineItem =
9
- | { kind: 'user_message'; id: string; text: string; clientMessageId?: string; /** How many images the message carried; their data is not replayed. */ images?: number }
9
+ | {
10
+ kind: 'user_message'; id: string; text: string; clientMessageId?: string; /** How many images the message carried; their data is not replayed. */ images?: number;
11
+ /** Files attached to the message (capability `attachments`, §12.6): ids, display names, types and sizes, never a host path. */
12
+ attachments?: Array<{ attachmentId: string; name: string; mimeType: string; size: number }>;
13
+ /** Who wrote it: the user, or ALP itself (mail, a brief, a resume); absent when the runtime cannot tell. Only the user's words name a root (ALPD §15). */
14
+ origin?: TurnOrigin;
15
+ }
10
16
  | { kind: 'assistant_message'; id: string; text: string }
11
17
  /** Something about ALP as a whole the user should see, such as a usage limit or a pause (ALPD §29). */
12
18
  | { kind: 'notice'; id: string; level: 'info' | 'warning' | 'error'; text: string }
@@ -99,6 +105,11 @@ export type SessionSnapshot = {
99
105
  instructionsSha?: string;
100
106
  /** The session's runtime takes images in session.prompt (capability `prompt.images`); absent means it does not. */
101
107
  promptImages?: boolean;
108
+ /**
109
+ * How the session's runtime can use files attached in session.prompt (§12.6): `file.path` (its tools
110
+ * read a staged read-only copy), `document.native`, `text.extract`. Absent: it takes no attachment parts.
111
+ */
112
+ promptAttachments?: Array<'file.path' | 'document.native' | 'text.extract'>;
102
113
  /** The latest usage the session's runtime reported (ALPD §57); absent before its first report. */
103
114
  usage?: SessionUsage;
104
115
  };
@@ -116,6 +127,13 @@ export type AssignmentSnapshot = {
116
127
  /** runtime: a turn the native runtime started by itself, such as Claude after a background task ended. */
117
128
  export type TurnOrigin = 'user' | 'wake' | 'assignment' | 'runtime';
118
129
 
130
+ /**
131
+ * A root's turn that ended while nobody looked (Paseo's attention): `finished` for a completed turn,
132
+ * `error` for a failed one. alpd keeps it for every client until one acknowledges it or the root
133
+ * starts another turn (docs/protocol/alp-json-rpc-v1.md §12.2).
134
+ */
135
+ export type TurnAttention = { reason: 'finished' | 'error'; at: string; turnId?: string; message?: string };
136
+
119
137
  /** A question an agent asked the user with alp_ask to: "user". */
120
138
  export type UserQuestion = {
121
139
  id: string;
@@ -125,6 +143,8 @@ export type UserQuestion = {
125
143
  body: string;
126
144
  options?: string[];
127
145
  askedAt: string;
146
+ /** A card that mirrors an open human gate of the project's tasks: choosing an option approves it, dismissing rejects it. It has no timeout. */
147
+ gate?: { projectRoot: string; taskId: string; gateId: string };
128
148
  };
129
149
 
130
150
  export type SessionState = 'running' | 'waiting' | 'waiting_parent' | 'waiting_user' | 'idle';
@@ -162,7 +182,15 @@ export type AlpEvent =
162
182
  | { type: 'question.resolved'; questionId: string; outcome: 'answered' | 'dismissed' | 'timeout' | 'canceled'; answer?: string }
163
183
  /** Emitted on the session that pinned it (plans/reference/ALPD.md §18). */
164
184
  | { type: 'pin'; pin: Pin }
165
- | { type: 'unpin'; pinId: string; reason: 'unpinned' | 'session_ended' };
185
+ | { type: 'unpin'; pinId: string; reason: 'unpinned' | 'session_ended' }
186
+ /** A root's attention set, or cleared when absent: sent only to `question.watch { attention: true }` connections, never kept. */
187
+ | { type: 'attention'; attention?: TurnAttention }
188
+ /**
189
+ * The root's conversation was rewound (capability `session.rewind`, §12.7): history pages and cursors of
190
+ * the earlier generation are stale. Sent to attached connections only, never kept: drop the cached
191
+ * history, fetch a new tail and attach again with this generation.
192
+ */
193
+ | { type: 'history.reset'; generation: string; reason: 'rewind'; branchId: string };
166
194
 
167
195
  export type Envelope = {
168
196
  sessionId: string;
package/src/index.ts CHANGED
@@ -3,4 +3,5 @@ export type * from './dto.js';
3
3
  export type * from './events.js';
4
4
  export type * from './connection.js';
5
5
  export type * from './session.js';
6
+ export type * from './schedule.js';
6
7
  export type * from './rpc.js';
package/src/rpc.ts CHANGED
@@ -1,27 +1,79 @@
1
1
  /** Portable JSON-RPC structures; implementations and provider SDKs stay outside protocol. */
2
2
  import type { RuntimeKind, Pin } from './dto.js';
3
- import type { AlpError, Envelope, SessionSnapshot, TreeStatus, UserQuestion } from './events.js';
4
- import type { PauseState, PromptContent, RecallAnswer, SessionPreview, SessionSpec, SessionSummary } from './session.js';
3
+ import type { AlpError, Envelope, SessionSnapshot, TreeStatus, TurnAttention, UserQuestion } from './events.js';
4
+ import type { ConfigureOutcome, ConfigurePreview, ConversationBranch, ForkProvenance, PauseState, PromptContent, RecallAnswer, ResumeCommand, SessionPreview, SessionSpec, SessionSummary } from './session.js';
5
5
  import type { EntryName, LanguageSetting, LibraryEntryRow, LibraryKind, LibraryScope, LibrarySource, TaskRow, TeamRow } from './dto.js';
6
+ import type { ScheduleJob, ScheduleStatus } from './schedule.js';
6
7
 
7
8
  export type RpcId = string | number | null;
8
9
  export type RpcErrorData = { code: number; message: string; data?: unknown };
9
10
  export type RpcRequest = { jsonrpc: '2.0'; id?: RpcId; method: string; params?: Record<string, unknown> };
10
11
  export type RpcResponse = { jsonrpc: '2.0'; id: RpcId } & ({ result: unknown; error?: never } | { error: RpcErrorData; result?: never });
11
12
  export type EventNotification = { jsonrpc: '2.0'; method: 'event'; params: Envelope };
13
+ /** Why a terminal ended (§12.10). */
14
+ export type TerminalEndReason = 'exited' | 'closed' | 'idle' | 'lifetime' | 'detached' | 'revoked' | 'disabled' | 'shutdown';
15
+ /** A terminal as clients see it (capability `terminal`, §12.10): never a process id, shell path or host path. */
16
+ export type TerminalInfo = {
17
+ terminalId: string; workspaceId: string; title: string; cols: number; rows: number; state: 'running' | 'exited';
18
+ attached: boolean; createdAt: string; lastActivityAt: string; expiresAt: string;
19
+ exitCode?: number | null; signal?: number | null; endReason?: TerminalEndReason;
20
+ /** Absent: full native protection. root-only: best-effort Linux. none: Windows ConPTY, best-effort cleanup. */
21
+ protection?: 'root-only' | 'none';
22
+ };
23
+ /** Effective terminal limits a daemon.hello advertises with capability `terminal`. */
24
+ export type TerminalLimits = {
25
+ maxPerPrincipal: number; maxPerDaemon: number; maxInputBytes: number; maxOutputFrameBytes: number;
26
+ replayBytes: number; idleMs: number; maxLifetimeMs: number; reconnectMs: number;
27
+ };
28
+ /** params of a terminal.event notification, sent only to the connection attached to the terminal. */
29
+ export type TerminalEvent =
30
+ | { terminalId: string; type: 'output'; seq: number; data: string }
31
+ | { terminalId: string; type: 'exit'; seq: number; exitCode: number | null; signal: number | null; reason: TerminalEndReason }
32
+ | { terminalId: string; type: 'detached'; reason: 'replaced' | 'slow_consumer' };
33
+ export type CatalogUpdatedNotification = { jsonrpc: '2.0'; method: 'catalog.updated'; params: { fetchedAt?: string } };
34
+ export type TerminalChangedNotification = { jsonrpc: '2.0'; method: 'terminal.changed'; params: { watchId: string; cursor: string } };
35
+ export type TerminalNotification = { jsonrpc: '2.0'; method: 'terminal.event'; params: TerminalEvent };
12
36
 
13
37
  /** Names a daemon may list in its daemon.hello result (schema/methods-v1.json `capabilities`). */
14
- export type Capability = 'attach.after' | 'prompt.receipts' | 'extension.methods' | 'team' | 'task' | 'library' | 'settings.language' | 'session.list.page' | 'question.watch' | 'question.watch.turns' | 'workspace.files' | 'workspace.files.read' | 'prompt.images';
38
+ export type HistoryItem = Envelope | { cursor: number; oversized: { bytes: number } };
39
+ export type HistoryPage = { generation: string; items: HistoryItem[]; olderCursor?: string; hasOlder: boolean; tipCursor: number };
40
+
41
+ /** One entry of session.commands: inserted as `/<name>` into the composer. */
42
+ export type SessionCommand = { name: string; description: string; argumentHint?: string; kind: 'command' | 'skill' };
43
+
44
+ export type Capability = 'session.interrupt.turn' | 'session.fork' | 'session.rewind' | 'session.reload' | 'session.resumeCommand' | 'session.commands' | 'session.configure.live' | 'terminal' | 'terminal.capture' | 'terminal.watch' | 'attachments' | 'workspace.git' | 'workspace.git.facts' | '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' | 'workspace.files.browse' | 'host.directories' | 'prompt.images' | 'schedule' | 'catalog.live';
15
45
 
16
46
  /** `data.reason` values alpd sets on errors (docs/protocol/alp-json-rpc-v1.md §5.3). */
17
47
  export type ErrorReason =
18
48
  | 'hello_required' | 'protocol_version' | 'invalid_params' | 'invalid_id' | 'batch_unsupported' | 'frame_too_large'
49
+ | 'invalid_cursor' | 'stale_cursor' | 'history_gap'
50
+ | 'stale_revision' | 'request_conflict' | 'cwd_mismatch' | 'workspace_mismatch' | 'corrupt_registry' | 'identity_changed'
19
51
  | 'response_too_large' | 'persistence_failed' | 'outcome_unknown' | 'key_conflict'
20
52
  // Project, task and library methods (docs/protocol/alp-json-rpc-v1.md §5.3).
21
53
  | 'invalid_path' | 'invalid_scope' | 'invalid_entry' | 'secret_marker' | 'not_alp_project' | 'unknown_task' | 'not_found'
22
- | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable'
54
+ | 'library_policy' | 'unsafe_path' | 'revision_conflict' | 'task_state' | 'in_use' | 'busy' | 'unreadable'
23
55
  // workspace.files.search (§12.3); workspace.files.list and read (§12.4).
24
- | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large';
56
+ | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large'
57
+ // workspace.files.find, workspace.files.preview and internal links (§12.11).
58
+ | 'outside' | 'changed'
59
+ // workspace.git.status and workspace.git.diff (§12.5).
60
+ | 'not_repository' | 'unknown_ref' | 'invalid_compare' | 'stale_snapshot' | 'git_unavailable' | 'git_failed'
61
+ // session.prompt: a Claude command ALP does not follow (t-e906).
62
+ | 'native_command_unsupported'
63
+ // Attachments (§12.6).
64
+ | 'invalid_name' | 'invalid_data' | 'attachment_too_large' | 'offset_mismatch' | 'chunk_conflict' | 'upload_incomplete'
65
+ | 'hash_mismatch' | 'upload_expired' | 'quota_exceeded' | 'attachment_referenced' | 'attachment_limit'
66
+ | 'attachment_unavailable' | 'attachment_unsupported'
67
+ // session.fork and session.rewind (§12.7).
68
+ | 'session_busy' | 'stale_generation' | 'turn_not_found' | 'turn_in_progress' | 'empty_prefix' | 'boundary_unmapped'
69
+ | 'runtime_unsupported' | 'native_refused' | 'branch_not_found' | 'attachment_forbidden'
70
+ // session.reload (§12.8).
71
+ | 'session_closed' | 'no_history'
72
+ // session.configure with model, thinking or team (§12.9).
73
+ | 'runtime_mismatch' | 'agent_mismatch' | 'permission_escalation' | 'team_not_found'
74
+ // Terminal (§12.10).
75
+ | 'terminal_capture_unavailable' | 'terminal_capture_too_large' | 'terminal_snapshot_too_large'
76
+ | 'terminal_disabled' | 'terminal_unsupported' | 'terminal_limit' | 'not_attached' | 'terminal_exited' | 'input_too_large';
25
77
 
26
78
  type Empty = Record<string, never>;
27
79
 
@@ -30,8 +82,86 @@ type Empty = Record<string, never>;
30
82
  * type-check the golden fixtures against this map, so the two cannot drift. Results may carry
31
83
  * properties this map does not name: clients ignore them.
32
84
  */
85
+ export type RegistryProject = { id: string; root: string; canonical?: string; customName?: string | null; addedAt: string; removedAt?: string | null; revision?: number };
86
+ 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 };
87
+ /** workspace.git.status and workspace.git.diff (capability `workspace.git`, §12.5): paths are relative to the workspace, never host paths. */
88
+ export type GitChange = 'modified' | 'added' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'untracked' | 'conflicted';
89
+ export type GitCompare = { mode: 'uncommitted' | 'staged' | 'unstaged' | 'base'; baseRef?: string; ignoreWhitespace?: boolean };
90
+ export type GitStatusFile = { path: string; oldPath?: string; change: GitChange; staged: boolean; unstaged: boolean };
91
+ export type GitStatus = {
92
+ state: 'repository' | 'not_repository' | 'unsupported'; reason?: string;
93
+ branch: string | null; detached: boolean; head: string | null;
94
+ upstream: { ref: string; ahead: number; behind: number } | null;
95
+ baseRef: string | null; aheadBehind: { ahead: number; behind: number } | null;
96
+ hasRemote: boolean; remoteUrl: string | null; dirty: boolean;
97
+ files: GitStatusFile[]; hiddenCount: number; truncated: boolean; snapshot: string;
98
+ };
99
+ export type GitDiffLine = { type: 'add' | 'remove' | 'context'; content: string; noNewline?: true };
100
+ export type GitDiffHunk = { oldStart: number; oldCount: number; newStart: number; newCount: number; context?: string; lines: GitDiffLine[] };
101
+ export type GitDiffFile = { path: string; oldPath?: string; change: GitChange; kind: 'text' | 'binary' | 'too_large' | 'withheld' | 'symlink' | 'submodule'; additions: number; deletions: number; hunks: GitDiffHunk[] };
102
+ export type GitDiffPage = { compare: { mode: GitCompare['mode']; baseRef?: string; ignoreWhitespace: boolean }; snapshot: string; files: GitDiffFile[]; hiddenCount: number; truncated: boolean; nextCursor?: string };
103
+ /**
104
+ * workspace.git.facts (capability `workspace.git.facts`, §12.5): an owner-only answer for a host
105
+ * directory, so `repoRoot` is a host path (the directory's real path, or the enclosing repository's
106
+ * top level for `not_repository_root`). Never forwarded by a gateway.
107
+ */
108
+ export type GitCheckoutFacts = { repoRoot: string; branch: string | null; detached: boolean; head: string | null; hasRemote: boolean; remoteUrl: string | null; dirty: boolean };
109
+ export type GitFacts =
110
+ | ({ kind: 'ok' | 'not_repository_root' } & GitCheckoutFacts)
111
+ | { kind: 'unknown' }
112
+ | { kind: 'unsupported'; reason: 'worktree_elsewhere' | 'inside_git_dir' };
113
+ /**
114
+ * Capability `attachments` (§12.6). Principal context is set only by a trusted gateway on its own
115
+ * connection; a local client leaves it out and acts as the owner.
116
+ */
117
+ export type PrincipalContext = { principalId?: string; principalEpoch?: string; authorizedRoots?: string[] };
118
+ /** A committed attachment as clients see it: ids and display metadata, never a host path or URL. */
119
+ export type AttachmentInfo = {
120
+ attachmentId: string; sessionId: string; name: string; mimeType: string; detectedMimeType: string;
121
+ size: number; sha256: string; createdAt: string; committedAt: string; referenced: boolean;
122
+ };
123
+ /** Effective attachment limits a daemon.hello advertises with capability `attachments`. */
124
+ export type AttachmentLimits = {
125
+ maxObjectBytes: number; maxPerPrompt: number; maxPromptBytes: number; maxChunkBytes: number; maxActiveUploads: number;
126
+ maxPrincipalBytes: number; maxDaemonBytes: number; uploadTimeoutMs: number; unreferencedRetentionMs: number; releasedGraceMs: number;
127
+ };
128
+ /** Where a fork cuts the source conversation (§12.7): after a completed turn, or before a turn. */
129
+ export type ForkBoundary = { throughTurnId: string } | { beforeTurnId: string };
130
+ export type RegistryMutation = { requestId: string; ifRevision: number };
131
+ export type RegistryPage = { revision: number; total: number; nextCursor: string | null };
33
132
  export type RpcMethodMap = {
34
- '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; capabilities?: string[] } };
133
+ 'terminal.create': { params: PrincipalContext & { workspaceId: string; cols: number; rows: number; requestId: string; protectionAcknowledgment?: 'linux-root-only-v1' /* deprecated, ignored */ }; result: { terminal: TerminalInfo } };
134
+ 'terminal.list': { params: PrincipalContext & { workspaceId?: string }; result: { terminals: TerminalInfo[] } };
135
+ 'terminal.watch': { params: PrincipalContext & { workspaceId?: string; after?: string }; result: { terminals: TerminalInfo[]; watchId: string; cursor: string; reset: boolean } };
136
+ 'terminal.unwatch': { params: Empty; result: { closed: true } };
137
+ 'terminal.capture': { params: PrincipalContext & { terminalId: string; start?: number; end?: number; stripAnsi?: boolean }; result: { lines: string[]; totalLines: number } };
138
+ 'terminal.attach': { params: PrincipalContext & { terminalId: string; after?: number; protectionAcknowledgment?: 'linux-root-only-v1' /* deprecated, ignored */ }; result: { terminal: TerminalInfo; nextSeq: number; gap?: { fromSeq: number; toSeq: number } } };
139
+ 'terminal.input': { params: PrincipalContext & { terminalId: string; data: string }; result: { bytes: number } };
140
+ 'terminal.resize': { params: PrincipalContext & { terminalId: string; cols: number; rows: number }; result: { cols: number; rows: number } };
141
+ 'terminal.close': { params: PrincipalContext & { terminalId: string }; result: { closed: true } };
142
+ 'terminal.revoke': { params: { principalId: string }; result: { closed: number } };
143
+ '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 } };
144
+ 'attachment.chunk': { params: PrincipalContext & { uploadId: string; offset: number; data: string }; result: { received: number; size: number } };
145
+ 'attachment.commit': { params: PrincipalContext & { uploadId: string; sha256: string }; result: { attachment: AttachmentInfo } };
146
+ 'attachment.abort': { params: PrincipalContext & { uploadId: string }; result: { aborted: true } };
147
+ 'attachment.get': { params: PrincipalContext & { attachmentId: string }; result: { attachment: AttachmentInfo } };
148
+ 'attachment.delete': { params: PrincipalContext & { attachmentId: string }; result: { deleted: true } };
149
+ 'workspace.git.status': { params: { workspaceId: string }; result: GitStatus };
150
+ 'workspace.git.diff': { params: { workspaceId: string; compare: GitCompare; path?: string; cursor?: string }; result: GitDiffPage };
151
+ 'workspace.git.facts': { params: { directory: string }; result: GitFacts };
152
+ 'workspace.worktree.options': { params: { workspaceId: string }; result: { mappingIds: string[] } };
153
+ 'workspace.worktree.create': { params: RegistryMutation & { workspaceId: string; mappingId: string }; result: { workspace: RegistryWorkspace; revision: number } };
154
+ 'workspace.worktree.remove': { params: RegistryMutation & { workspaceId: string }; result: { workspace: RegistryWorkspace; revision: number; filesRemoved: true; branchRetained: true } };
155
+ 'registry.worktree': { params: { principalId?: string; principalEpoch?: string; mappingIds?: string[]; authorizedRoots?: string[] }; result: { mappings: Array<{id:string;source:string}>; workspaces: unknown[] } };
156
+ 'project.list': { params: { cursor?: string; limit?: number; projectRoots?: string[] }; result: RegistryPage & { projects: RegistryProject[] } };
157
+ 'workspace.list': { params: { cursor?: string; limit?: number; projectRoots?: string[] }; result: RegistryPage & { workspaces: RegistryWorkspace[] } };
158
+ 'workspace.get': { params: { workspaceId: string }; result: { workspace: RegistryWorkspace; revision: number } };
159
+ 'project.register': { params: RegistryMutation & { directory: string }; result: { project: RegistryProject; revision: number } };
160
+ 'project.remove': { params: RegistryMutation & { projectId: string }; result: { project: RegistryProject; revision: number } };
161
+ 'workspace.update': { params: RegistryMutation & { workspaceId: string; title?: string | null; pinned?: boolean; archived?: boolean }; result: { workspace: RegistryWorkspace; revision: number } };
162
+ 'registry.owner': { params: { operation?: string; args?: Record<string, unknown>; requestId?: string; ifRevision?: number }; result: { registry: Record<string, unknown> } };
163
+
164
+ '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 }; attachmentLimits?: AttachmentLimits; terminalLimits?: TerminalLimits; capabilities?: string[] } };
35
165
  'daemon.status': {
36
166
  params: Empty;
37
167
  result: {
@@ -46,35 +176,105 @@ export type RpcMethodMap = {
46
176
  'daemon.resume': { params: { runtime?: RuntimeKind }; result: PauseState };
47
177
  'daemon.pauses': { params: Empty; result: PauseState };
48
178
  'daemon.usage': { params: { refresh?: boolean }; result: { providers: Array<Record<string, unknown>> } };
49
- 'catalog.get': { params: Empty; result: { models: Array<Record<string, unknown>>; modes: Array<Record<string, unknown>>; thinkingOptions?: unknown; defaultModel: string } };
179
+ 'catalog.get': { params: Empty; result: { models: Array<Record<string, unknown>>; modes: Array<Record<string, unknown>>; thinkingOptions?: unknown; defaultModel: string; fetchedAt?: string; providers?: Record<string, { status: string; fetchedAt?: string; error?: string }> } };
180
+ 'catalog.refresh': { params: Empty; result: { models: Array<Record<string, unknown>>; modes: Array<Record<string, unknown>>; thinkingOptions?: unknown; defaultModel: string; fetchedAt?: string; providers?: Record<string, { status: string; fetchedAt?: string; error?: string }> } };
50
181
  'assignment.recall': { params: { assignmentId?: string; taskId?: string; projectRoot?: string; question: string }; result: RecallAnswer };
51
182
  'board.list': { params: { projectRoot: string }; result: { pins: Pin[] } };
52
183
  'question.list': { params: { projectRoot?: string }; result: { questions: UserQuestion[] } };
53
- /** 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`. */
54
- 'question.watch': { params: { projectRoot?: string; turns?: boolean }; result: { questions: UserQuestion[] } };
184
+ /** 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. */
185
+ 'question.watch': { params: { projectRoot?: string; turns?: boolean; attention?: boolean }; result: { questions: UserQuestion[]; attention?: Array<{ sessionId: string; attention: TurnAttention }> } };
186
+ /** Capability `session.attention`: acknowledges a root's attention for every client; with `at`, only that one (a later turn's stays). */
187
+ 'session.attention.clear': { params: { sessionId: string; at?: string }; result: { cleared: boolean } };
55
188
  /** Capability `workspace.files`: files under `projectRoot` whose relative path matches `query`, best first; read-only, links not followed. */
56
189
  'workspace.files.search': { params: { projectRoot: string; query?: string; limit?: number }; result: { files: Array<{ path: string }>; truncated?: boolean } };
57
- /** 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. */
58
- '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 } };
190
+ /** 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. With `workspace.files.browse`: `cursor` pages past 1000 entries; `internalLinks` lists links inside the root as what they lead to (`target`). */
191
+ 'workspace.files.list': { params: { projectRoot: string; path?: string; includeIgnored?: boolean; cursor?: string; internalLinks?: boolean }; result: { entries: Array<{ name: string; path: string; kind: 'file' | 'directory'; size?: number; modifiedAt?: string; target?: string }>; truncated?: boolean; nextCursor?: string; target?: string } };
59
192
  /** Capability `workspace.files.read`: a UTF-8 text file under `projectRoot`, at most 1 MiB; read-only, links not followed. */
60
193
  'workspace.files.read': { params: { projectRoot: string; path: string; includeIgnored?: boolean }; result: { path: string; content: string; size: number; modifiedAt?: string } };
194
+ /** Capability `workspace.files.browse`: every name under `projectRoot` holding `query`'s letters in order (or ending with it), in path order, in pages of a snapshot; read-only, links not entered. */
195
+ 'workspace.files.find': { params: { projectRoot: string; query?: string; kinds?: Array<'file' | 'directory'>; matchMode?: 'subsequence' | 'suffix'; limit?: number; cursor?: string }; result: { entries: Array<{ path: string; kind: 'file' | 'directory' }>; nextCursor?: string; truncated?: boolean } };
196
+ /** Capability `workspace.files.browse`: a file under `projectRoot` as a preview, text, image or binary, at most 50 MiB, its bytes in chunks from `offset`. */
197
+ 'workspace.files.preview': { params: { projectRoot: string; path: string; includeIgnored?: boolean; internalLinks?: boolean; maxBytes?: number; offset?: number; revision?: string }; result: { path: string; target?: string; kind: 'text' | 'image' | 'binary'; mimeType: string; size: number; modifiedAt: string; revision: string; encoding: 'base64' | 'none'; content?: string; offset?: number; nextOffset?: number } };
198
+ /** Capability `host.directories`: directories of the daemon host whose path completes `query` (absolute or under ~), or whose name matches it under the home directory. */
199
+ 'host.directories.search': { params: { query: string; limit?: number }; result: { entries: Array<{ path: string }>; truncated?: boolean } };
61
200
  'question.answer': { params: { questionId: string; text?: string; dismiss?: boolean; reason?: string }; result: { questionId: string } };
62
201
  'session.create': {
63
- params: { sessionId?: string; spec: SessionSpec; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean };
202
+ params: { sessionId?: string; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean } & ({ workspaceId: string; spec: Omit<SessionSpec, 'cwd'> & { cwd?: string } } | { workspaceId?: undefined; spec: SessionSpec });
64
203
  result: { session: SessionSnapshot; attached: boolean; resumed?: true; durable?: boolean };
65
204
  };
66
205
  'session.preview': { params: { spec: SessionSpec }; result: { preview: SessionPreview } };
67
- 'session.attach': { params: { sessionId: string; replay?: boolean; after?: number }; result: { session: SessionSummary; cursor: number; reset?: true } };
206
+ 'session.history': { params: { sessionId: string; before?: string; limit?: number; maxBytes?: number }; result: HistoryPage };
207
+ 'session.attach': { params: { sessionId: string; replay?: boolean; after?: number; generation?: string }; result: { session: SessionSummary; cursor: number; reset?: true } };
68
208
  'session.release': { params: { sessionId: string }; result: { closed: boolean } };
69
209
  'session.prompt': {
70
- params: { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
210
+ params: PrincipalContext & { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
71
211
  /** `{}` from a daemon without prompt.receipts. */
72
212
  result: { outcome?: 'accepted' | 'failed'; error?: AlpError; duplicate?: boolean; durable?: boolean };
73
213
  };
74
- 'session.interrupt': { params: { sessionId: string }; result: Empty };
75
- 'session.configure': { params: { sessionId: string; mode?: string }; result: { session: SessionSnapshot } };
214
+ 'session.interrupt': { params: { sessionId: string; /** With session.interrupt.turn, cancel only this turn. */ turnId?: string }; result: { /** Conditional request only: false means the named turn is no longer active. */ interrupted?: boolean } };
215
+ /**
216
+ * Changes a session's permissions mode while idle; with capability `session.configure.live`, also a live
217
+ * root's model, effort or team (§12.9): those need requestId and ifGeneration, apply at the idle barrier
218
+ * through a restart of its native process on the same conversation, and answer `configured`. Answered
219
+ * once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
220
+ */
221
+ 'session.configure': {
222
+ params: { sessionId: string; mode?: string; model?: string; thinking?: string; team?: string; requestId?: string; ifGeneration?: string };
223
+ result: { session: SessionSnapshot | SessionSummary; configured?: ConfigureOutcome; duplicate?: true };
224
+ };
225
+ /** What session.configure would run a live root with, and whether it would take it now (capability `session.configure.live`, §12.9). */
226
+ 'session.configure.preview': {
227
+ params: { sessionId: string; mode?: string; model?: string; thinking?: string; team?: string };
228
+ result: { preview: ConfigurePreview };
229
+ };
76
230
  'session.close': { params: { sessionId: string }; result: Empty };
77
231
  'session.rename': { params: { sessionId: string; title: string }; result: { session: SessionSummary } };
232
+ /**
233
+ * A new root whose conversation is the source's up to a completed turn (capability `session.fork`, §12.7).
234
+ * Answered once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
235
+ */
236
+ 'session.fork': {
237
+ params: PrincipalContext & { sessionId: string; requestId: string; ifGeneration: string; boundary?: ForkBoundary; branchId?: string; workspaceId?: string; newSessionId?: string; title?: string };
238
+ result: { session: SessionSummary; forkedFrom: ForkProvenance; duplicate?: true };
239
+ };
240
+ /**
241
+ * The root's conversation from before a turn on, under the same session id; the later turns stay as a
242
+ * recoverable branch and no file is changed (capability `session.rewind`, §12.7).
243
+ */
244
+ 'session.rewind': {
245
+ params: { sessionId: string; requestId: string; ifGeneration: string; beforeTurnId: string };
246
+ result: { session: SessionSummary; generation: string; branch: ConversationBranch; duplicate?: true };
247
+ };
248
+ /**
249
+ * Restarts a live root's native process on its own conversation and configuration at the idle
250
+ * barrier, keeping its session id, history and receipts (capability `session.reload`, §12.8).
251
+ * Answered once per (sessionId, requestId): a repeat answers the first result with `duplicate: true`.
252
+ */
253
+ 'session.reload': {
254
+ params: { sessionId: string; requestId: string; ifGeneration: string };
255
+ result: { session: SessionSummary; duplicate?: true };
256
+ };
257
+ /**
258
+ * The ALP CLI command that continues a session in a terminal, built by alpd (capability
259
+ * `session.resumeCommand`, §12.8): argv and its POSIX and Windows command lines, for the clipboard only.
260
+ */
261
+ /**
262
+ * Compacts a live root's context (t-0e56): main writes a checkpoint by skill compact, then its runtime
263
+ * compacts, or ALP starts a fresh conversation seeded with it. Idle: now; otherwise at its next turn boundary.
264
+ */
265
+ 'session.compact': {
266
+ params: { sessionId: string };
267
+ result: { status: 'started' | 'deferred' | 'running' };
268
+ };
269
+ /** The slash commands and skills a live session's composer offers after "/" (capability `session.commands`, t-f628). */
270
+ 'session.commands': {
271
+ params: { sessionId: string };
272
+ result: { commands: SessionCommand[] };
273
+ };
274
+ 'session.resumeCommand': {
275
+ params: { sessionId: string };
276
+ result: ResumeCommand;
277
+ };
78
278
  'session.archive': { params: { sessionId: string; archived?: boolean }; result: { session: SessionSummary } };
79
279
  'session.get': { params: { sessionId: string }; result: { session: SessionSummary } };
80
280
  /** `limit`, `cursor`, `query` and `projectRoots` with capability `session.list.page`: a page, and `nextCursor` while more follow. */
@@ -88,7 +288,7 @@ export type RpcMethodMap = {
88
288
  'task.list': { params: { projectRoot: string }; result: { projectRoot: string; tasks: TaskRow[]; unreadable: Array<{ file: string; error: string }>; revision: string } };
89
289
  'task.create': { params: { projectRoot: string; title: string; priority?: number; requestId?: string }; result: { id: string; duplicate?: true } };
90
290
  'task.update': { params: { projectRoot: string; id: string; action: 'close' | 'reopen'; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number; landed?: string } };
91
- 'task.gate.resolve': { params: { projectRoot: string; id: string; gate: string; note?: string; ifRev?: number }; result: { id: string; status: string; rev: number } };
291
+ 'task.gate.resolve': { params: { projectRoot: string; id: string; gate: string; note?: string; ifRev?: number; /** One of a human gate's options; picking one approves it. */ choice?: string; /** Record the user's rejection instead (note is the reason); the gate stays open. */ reject?: boolean; /** Where the user decided, recorded on the gate. Default web. */ channel?: 'paseo' | 'web' }; result: { id: string; status: string; rev: number } };
92
292
  'library.list': { params: { kind: LibraryKind; projectRoot?: string }; result: { projectRoot: string | null; entries: LibraryEntryRow[] } };
93
293
  'library.get': {
94
294
  params: { kind: LibraryKind; name: EntryName; projectRoot?: string; scope?: LibraryScope };
@@ -96,16 +296,21 @@ export type RpcMethodMap = {
96
296
  result: { kind: LibraryKind; name: string; source: LibrarySource; overrides?: LibrarySource; content: Record<string, unknown>; revision: string | null; usedBy: string[]; librarySkills?: string[]; secrets?: string[] };
97
297
  };
98
298
  'library.save': {
99
- params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; content: Record<string, unknown>; revision?: string | null; sync?: 'none' | 'known-projects' };
299
+ params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data'; content: Record<string, unknown>; revision?: string | null; sync?: 'none' | 'known-projects' };
100
300
  result: { revision: string | null; syncedProjects?: number; syncErrors?: string[] };
101
301
  };
102
- 'library.delete': { params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; revision?: string }; result: { removed: true; now?: 'builtin' | 'library' } };
103
- 'library.duplicate': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string }; result: { revision: string | null } };
104
- 'library.rename': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string }; result: { revision: string | null } };
302
+ 'library.delete': { params: { kind: LibraryKind; name: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data'; revision?: string }; result: { removed: true; now?: 'builtin' | 'library' } };
303
+ 'library.duplicate': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data' }; result: { revision: string | null } };
304
+ 'library.rename': { params: { kind: LibraryKind; from: EntryName; to: EntryName; scope: LibraryScope; projectRoot?: string; policy?: 'project-data' }; result: { revision: string | null } };
105
305
  'library.skills.set': { params: { agent: EntryName; skills: EntryName[] }; result: { skills: string[] } };
106
306
  'library.models': { params: Empty; result: { models: Array<{ id: string; label: string; efforts: string[]; effort?: string }> } };
107
307
  'settings.language.get': { params: Empty; result: LanguageSetting };
108
308
  'settings.language.set': { params: { language: string | null }; result: LanguageSetting };
309
+ /** Capability `schedule`: a one-shot continuation of a root session, due at `dueAt` (UTC, ISO 8601). */
310
+ 'schedule.create': { params: { projectRoot: string; sessionId: string; dueAt: string; prompt: string; keepsSession?: boolean }; result: { job: ScheduleJob } };
311
+ 'schedule.list': { params: { projectRoot: string; status?: ScheduleStatus }; result: { jobs: ScheduleJob[] } };
312
+ 'schedule.get': { params: { id: string; projectRoot: string }; result: { job: ScheduleJob } };
313
+ 'schedule.cancel': { params: { id: string; projectRoot: string }; result: { job: ScheduleJob } };
109
314
  };
110
315
 
111
316
  export type RpcMethod = keyof RpcMethodMap;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * A scheduled continuation: a one-shot job that opens a new turn on a root session at a
3
+ * given time, without a user message. The protocol owns the shape so every
4
+ * client (the CLI, a viewer, an agent tool) reads the same state.
5
+ */
6
+
7
+ /** Where a job stands: waiting for its time, delivered, failed, or cancelled before it fired. */
8
+ export type ScheduleStatus = 'pending' | 'delivered' | 'failed' | 'cancelled';
9
+
10
+ /** Why a job failed or still waits; failed may mean execution is unknown. */
11
+ export type ScheduleError = { message: string; code?: string };
12
+
13
+ /** One job as `schedule.list` and `schedule.get` answer it. */
14
+ export type ScheduleJob = {
15
+ /** The job's own id, `sch_` and sixteen hex digits. */
16
+ id: string;
17
+ /** The project whose root session the job continues. */
18
+ projectRoot: string;
19
+ /** The root session the job opens a turn on. */
20
+ sessionId: string;
21
+ /** The continuation the job delivers. */
22
+ prompt: string;
23
+ /** When the job is due, in UTC (ISO 8601). */
24
+ dueAt: string;
25
+ status: ScheduleStatus;
26
+ /**
27
+ * How many times alpd tried to deliver the job. A job delivered once may have been
28
+ * tried twice: a retry after a crash reads the receipt of the first delivery.
29
+ */
30
+ attempts: number;
31
+ createdAt: string;
32
+ updatedAt: string;
33
+ /** When the job was delivered, failed or cancelled. */
34
+ deliveredAt?: string;
35
+ failedAt?: string;
36
+ cancelledAt?: string;
37
+ /** When the first delivery was tried. */
38
+ attemptedAt?: string;
39
+ /** How late the delivery was, in milliseconds; 0 when it was on time. */
40
+ lateByMs?: number;
41
+ /** The last error of the job: why it failed, or why it still waits. */
42
+ lastError?: ScheduleError;
43
+ /**
44
+ * false: the job does not keep its session open while it waits, so an idle session may
45
+ * still be closed and the job then fails as session_closed. Absent: it keeps it open.
46
+ */
47
+ keepsSession?: false;
48
+ };