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

package/src/events.ts

@@ -6,7 +6,13 @@ import type { RuntimeKind, MailEvent, Pin } from './dto.js';
 export type AlpError = { message: string; code?: string };
 
 export type TimelineItem =
-  | { kind: 'user_message'; id: string; text: string; clientMessageId?: string; /** How many images the message carried; their data is not replayed. */ images?: number }
+  | {
+    kind: 'user_message'; id: string; text: string; clientMessageId?: string; /** How many images the message carried; their data is not replayed. */ images?: number;
+    /** Files attached to the message (capability `attachments`, §12.6): ids, display names, types and sizes, never a host path. */
+    attachments?: Array<{ attachmentId: string; name: string; mimeType: string; size: number }>;
+    /** 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). */
+    origin?: TurnOrigin;
+  }
   | { 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 }
@@ -99,6 +105,11 @@ export type SessionSnapshot = {
   instructionsSha?: string;
   /** The session's runtime takes images in session.prompt (capability `prompt.images`); absent means it does not. */
   promptImages?: boolean;
+  /**
+   * How the session's runtime can use files attached in session.prompt (§12.6): `file.path` (its tools
+   * read a staged read-only copy), `document.native`, `text.extract`. Absent: it takes no attachment parts.
+   */
+  promptAttachments?: Array<'file.path' | 'document.native' | 'text.extract'>;
   /** The latest usage the session's runtime reported (ALPD §57); absent before its first report. */
   usage?: SessionUsage;
 };
@@ -116,6 +127,13 @@ export type AssignmentSnapshot = {
 /** 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 root's turn that ended while nobody looked (Paseo's attention): `finished` for a completed turn,
+ * `error` for a failed one. alpd keeps it for every client until one acknowledges it or the root
+ * starts another turn (docs/protocol/alp-json-rpc-v1.md §12.2).
+ */
+export type TurnAttention = { reason: 'finished' | 'error'; at: string; turnId?: string; message?: string };
+
 /** A question an agent asked the user with alp_ask to: "user". */
 export type UserQuestion = {
   id: string;
@@ -162,7 +180,15 @@ export type AlpEvent =
   | { 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' };
+  | { type: 'unpin'; pinId: string; reason: 'unpinned' | 'session_ended' }
+  /** A root's attention set, or cleared when absent: sent only to `question.watch { attention: true }` connections, never kept. */
+  | { type: 'attention'; attention?: TurnAttention }
+  /**
+   * The root's conversation was rewound (capability `session.rewind`, §12.7): history pages and cursors of
+   * the earlier generation are stale. Sent to attached connections only, never kept: drop the cached
+   * history, fetch a new tail and attach again with this generation.
+   */
+  | { type: 'history.reset'; generation: string; reason: 'rewind'; branchId: string };
 
 export type Envelope = {
   sessionId: string;

package/src/index.ts

@@ -3,4 +3,5 @@ export type * from './dto.js';
 export type * from './events.js';
 export type * from './connection.js';
 export type * from './session.js';
+export type * from './schedule.js';
 export type * from './rpc.js';

package/src/rpc.ts

@@ -1,27 +1,67 @@
 /** 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; 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: 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'
+  | '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'
   // Project, task and library methods (docs/protocol/alp-json-rpc-v1.md §5.3).
   | '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'
   // workspace.files.search (§12.3); workspace.files.list and read (§12.4).
-  | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large';
+  | 'not_directory' | 'blocked_path' | 'ignored' | 'linked' | 'binary' | 'too_large'
+  // workspace.git.status and workspace.git.diff (§12.5).
+  | 'not_repository' | 'unknown_ref' | 'invalid_compare' | 'stale_snapshot' | 'git_unavailable' | 'git_failed'
+  // Attachments (§12.6).
+  | '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.fork and session.rewind (§12.7).
+  | 'session_busy' | 'stale_generation' | 'turn_not_found' | 'turn_in_progress' | 'empty_prefix' | 'boundary_unmapped'
+  | 'runtime_unsupported' | 'native_refused' | 'branch_not_found' | 'attachment_forbidden'
+  // session.reload (§12.8).
+  | 'session_closed' | 'no_history'
+  // session.configure with model, thinking or team (§12.9).
+  | 'runtime_mismatch' | 'agent_mismatch' | 'permission_escalation' | 'team_not_found'
+  // Terminal (§12.10).
+  | 'terminal_disabled' | 'terminal_unsupported' | 'terminal_limit' | 'not_attached' | 'terminal_exited' | 'input_too_large';
 
 type Empty = Record<string, never>;
 
@@ -30,8 +70,72 @@ type Empty = Record<string, never>;
  * 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 = {
-  '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 }; capabilities?: string[] } };
+  '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; 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[] } };
   'daemon.status': {
     params: Empty;
     result: {
@@ -50,8 +154,10 @@ export type RpcMethodMap = {
   'assignment.recall': { params: { assignmentId?: string; taskId?: string; projectRoot?: string; question: string }; result: RecallAnswer };
   'board.list': { params: { projectRoot: string }; result: { pins: Pin[] } };
   'question.list': { params: { projectRoot?: string }; result: { 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`. */
-  'question.watch': { params: { projectRoot?: string; turns?: boolean }; result: { 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`. `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. */
   'workspace.files.search': { params: { projectRoot: string; query?: string; limit?: number }; result: { files: Array<{ path: string }>; truncated?: boolean } };
   /** 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. */
@@ -60,21 +166,69 @@ export type RpcMethodMap = {
   'workspace.files.read': { params: { projectRoot: string; path: string; includeIgnored?: boolean }; result: { path: string; content: string; size: number; modifiedAt?: string } };
   'question.answer': { params: { questionId: string; text?: string; dismiss?: boolean; reason?: string }; result: { questionId: string } };
   'session.create': {
-    params: { sessionId?: string; spec: SessionSpec; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean };
+    params: { sessionId?: string; history?: 'skip' | 'replay'; delegation?: boolean; resume?: boolean } & ({ workspaceId: string; spec: Omit<SessionSpec, 'cwd'> & { cwd?: string } } | { workspaceId?: undefined; spec: SessionSpec });
     result: { session: SessionSnapshot; attached: boolean; resumed?: true; durable?: boolean };
   };
   'session.preview': { params: { spec: SessionSpec }; result: { preview: SessionPreview } };
-  'session.attach': { params: { sessionId: string; replay?: boolean; after?: number }; result: { session: SessionSummary; cursor: number; reset?: true } };
+  '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; cursor: number; reset?: true } };
   'session.release': { params: { sessionId: string }; result: { closed: boolean } };
   'session.prompt': {
-    params: { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
+    params: PrincipalContext & { sessionId: string; clientMessageId: string; delivery?: 'auto' | 'steer'; content: PromptContent };
     /** `{}` from a daemon without prompt.receipts. */
     result: { outcome?: 'accepted' | 'failed'; error?: AlpError; duplicate?: boolean; durable?: boolean };
   };
-  'session.interrupt': { params: { sessionId: string }; result: Empty };
-  'session.configure': { params: { sessionId: string; mode?: string }; result: { session: SessionSnapshot } };
+  '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 } };
+  /**
+   * 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 | 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': { params: { sessionId: string }; result: Empty };
   'session.rename': { params: { sessionId: string; title: string }; result: { 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; archived?: boolean }; result: { session: SessionSummary } };
   'session.get': { params: { sessionId: string }; result: { session: SessionSummary } };
   /** `limit`, `cursor`, `query` and `projectRoots` with capability `session.list.page`: a page, and `nextCursor` while more follow. */
@@ -106,6 +260,11 @@ export type RpcMethodMap = {
   'library.models': { params: Empty; result: { models: Array<{ id: string; label: string; efforts: string[]; effort?: string }> } };
   'settings.language.get': { params: Empty; result: LanguageSetting };
   'settings.language.set': { params: { language: string | null }; 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;

package/src/schedule.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/src/session.ts

@@ -1,5 +1,5 @@
 import type { RuntimeKind } from './dto.js';
-import type { SessionSnapshot } from './events.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> }
@@ -22,7 +22,11 @@ export type SessionSpec = {
   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 } };
+  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. */
@@ -41,8 +45,17 @@ export type OpenOptions = {
 
 /** 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 };
-/** Text parts carry `text`; image parts (`type: 'image'`) carry PromptImage's fields. */
-export type PromptContent = Array<{ type: string; text?: string; mimeType?: string; 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;
@@ -91,7 +104,110 @@ 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;
 };