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

package/src/configure.ts

@@ -0,0 +1,93 @@
+/**
+ * Live configure of a root (docs/protocol/alp-json-rpc-v1.md §12.9, issue #121 branch D): the pure
+ * parts. What a model a client names means for a session's runtime, which models the host offers,
+ * the effective configuration a resolved session runs with, and what of it can run commands.
+ */
+import { createHash } from 'node:crypto';
+import { MODELS } from '@anhlp/alp-core/models';
+import { profileModel } from '@anhlp/alp-core/profiles';
+import type { ConfigureChange, EffectiveConfig } from '@anhlp/alp-protocol/session';
+import type { ResolvedSession, RuntimeKind } from './resolve.js';
+
+export type { ConfigureChange, EffectiveConfig } from '@anhlp/alp-protocol/session';
+
+/** What a client may change on a live root; each absent field keeps the session's own. */
+export type ConfigureChanges = { model?: string; thinking?: string; team?: string; mode?: string };
+
+/** Runtimes whose roots alpd reconfigures live (macOS and Linux; Codex and Claude, issue #121 closure scope). */
+export const CONFIGURABLE: ReadonlySet<RuntimeKind> = new Set(['codex', 'claude'] as RuntimeKind[]);
+
+const PREFIXED = /^(codex|claude|antigravity|acp)[:/](.*)$/s;
+
+/**
+ * The native model `model` names for a session of `runtime`: unprefixed, or prefixed with that runtime
+ * (`codex:`, `claude:`, or with a slash). A prefix of another runtime is a migration, never taken.
+ */
+export function nativeModelOf(runtime: RuntimeKind, model: string): { model: string } | { runtime: string } {
+  const match = PREFIXED.exec(model);
+  if (!match) return { model };
+  return match[1] === runtime ? { model: match[2] } : { runtime: match[1] };
+}
+
+/**
+ * Whether the host offers `model` on `runtime`: ALP's catalog (core MODELS, what library.models and
+ * catalog.get list), a model the project's settings give an agent of the team, or the model the session
+ * runs already. Never an arbitrary string.
+ */
+export function offered(runtime: RuntimeKind, model: string, mapping: ResolvedSession) {
+  if (model === mapping.model) return true;
+  if (MODELS.some(entry => entry.runtime === runtime && entry.id === model)) return true;
+  return Object.values(mapping.modelProfiles ?? {}).flat().some(profile => profileModel(profile) === `${runtime}:${model}`);
+}
+
+/** MCP servers of a resolved session by name and kind: a stdio one runs a command on the host. */
+export function mcpOf(mapping: ResolvedSession): EffectiveConfig['mcpServers'] {
+  return Object.entries(mapping.mcp ?? {}).map(([name, server]) => ({ name, kind: server && typeof server === 'object' && 'command' in (server as object) ? 'stdio' as const : 'http' as const }));
+}
+
+const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+
+/**
+ * What of a resolved session runs commands on the daemon host: its stdio MCP servers (command, args,
+ * env names) and its hooks (event and command), each as a digest. A change may keep or drop these,
+ * never add one (a team change that brings an executable resource is refused).
+ */
+export function executablesOf(mapping: ResolvedSession): Set<string> {
+  const found = new Set<string>();
+  for (const [name, server] of Object.entries(mapping.mcp ?? {}) as Array<[string, any]>) {
+    if (server && typeof server === 'object' && 'command' in server) found.add(`mcp:${name}:${digest([server.command, server.args ?? [], Object.keys(server.env ?? {}).sort()])}`);
+  }
+  for (const hook of (mapping.hooks ?? []) as Array<{ name?: string; event?: unknown; command?: unknown }>) found.add(`hook:${hook.name ?? ''}:${digest([hook.event, hook.command])}`);
+  return found;
+}
+
+/** The effective configuration of a resolved root, with its delegation targets, ALP tools and instructions digest. */
+export function effectiveOf(runtime: RuntimeKind, mapping: ResolvedSession, extra: { delegates: string[]; tools: string[]; supervisor: boolean; instructionsSha?: string }): EffectiveConfig {
+  return {
+    team: mapping.workflow.mode,
+    ...(mapping.team?.label ? { teamLabel: mapping.team.label } : {}),
+    agent: mapping.agent.name,
+    runtime,
+    model: mapping.model,
+    thinking: mapping.thinking,
+    mode: mapping.mode,
+    ...(mapping.permissions?.name ? { permissionProfile: mapping.permissions.name } : {}),
+    supervisor: extra.supervisor,
+    maxPeers: mapping.workflow.maxPeers,
+    delegates: [...extra.delegates],
+    tools: [...extra.tools],
+    mcpServers: mcpOf(mapping),
+    hooks: (mapping.hooks ?? []).length,
+    ...(extra.instructionsSha ? { instructionsSha: extra.instructionsSha } : {}),
+  };
+}
+
+/** Which of model, thinking, team and mode differ between two effective configurations. */
+export function changesOf(current: EffectiveConfig, proposed: EffectiveConfig): ConfigureChange[] {
+  const changes: ConfigureChange[] = [];
+  if (current.model !== proposed.model) changes.push('model');
+  if (current.thinking !== proposed.thinking) changes.push('thinking');
+  if (current.team !== proposed.team) changes.push('team');
+  if (current.mode !== proposed.mode) changes.push('mode');
+  return changes;
+}

package/src/contracts.ts

@@ -0,0 +1,318 @@
+import type { ProviderFactories, ProviderRegistry } from './providers.js';
+import type { RuntimeKind, SessionSpec } from './resolve.js';
+import type { Envelope, SessionSnapshot, TreeStatus, UserQuestion } from './events.js';
+import type { Pin } from './board.js';
+import type { LiveEntry } from './live.js';
+import type { ProviderUsage } from './usage.js';
+import type { AcpProvider } from './acp-transport.js';
+import type { AntigravityProvider } from './antigravity-transport.js';
+import type { GitHubRunner } from './github.js';
+import type { AttachmentReader } from './attachments.js';
+
+export type RuntimeTransport = {
+  request(method: string, params: any): Promise<any>;
+  initialize(): Promise<void>;
+  orchestrationContext?: () => Promise<unknown>;
+  onNotification(listener: (method: string, params: any) => void): void;
+  onFailure(listener: (error: unknown) => void): void;
+  close(): Promise<void>;
+  onRequest?: (listener: (method: string, params: any) => Promise<unknown>) => void;
+  /** Whether turn input may hold images (`{ type: 'image', url: 'data:…' }`); omitted, Codex and Claude do. */
+  takesImages?: () => boolean;
+};
+
+export type RuntimeOptions = {
+  /** Native adapter overrides, isolated to this runtime; the legacy transport hook takes precedence. */
+  providers?: ProviderFactories;
+  /** An explicit registry, including custom adapter factories registered by the host. */
+  providerRegistry?: ProviderRegistry;
+  codexCommand?: string;
+  claudeCommand?: string;
+  antigravityCommand?: string;
+  environment?: NodeJS.ProcessEnv;
+
+  /**
+   * Optional transport factory for tests/custom runtimes.
+   * When omitted, ALP creates CodexTransport, ClaudeTransport, or AntigravityTransport itself.
+   */
+  transport?: (
+    cwd: string,
+    env: NodeJS.ProcessEnv,
+    runtime?: RuntimeKind,
+    /** The ACP provider, when runtime is acp. */
+    acp?: AcpProvider,
+    /** The Antigravity provider, when runtime is antigravity. */
+    antigravity?: AntigravityProvider,
+  ) => RuntimeTransport;
+
+  /** An assignment with no activity this long is reported stalled; twice this long, it fails. */
+  silentForMs?: number;
+  /** How often main gets a check-in on its running assignments. Default 10 minutes; 0 turns it off. */
+  checkInMs?: number;
+  /** How often the watchdog looks at running assignments; derived from silentForMs and checkInMs when omitted. */
+  watchMs?: number;
+  /** How long alp_ask waits for the requester before returning unanswered. */
+  askTimeoutMs?: number;
+  /** How long alp_ask waits for the user before returning unanswered. Default 30 minutes. */
+  userAskTimeoutMs?: number;
+
+  /** Directory for per-root-session assignment logs (JSONL). Omitted disables logging. */
+  runLogDir?: string;
+
+  /** Starter files for projects without ALP; omitted reads the repository templates. */
+  templates?: Record<string, string>;
+
+  /** Where isolated assignments get their git worktrees. Default: a directory in the temp directory. */
+  worktreeDir?: string;
+
+  /** Where assignments whose profile has workdir copy get their disposable copies. Default: a directory in the temp directory. */
+  copyDir?: string;
+
+  /**
+   * Where the runtime stages read-only copies of attached files for its sessions' tools (§12.6):
+   * alpd's `<ALP_HOME>/state/staged`. Omitted, no session takes attachment parts.
+   */
+  attachmentStageDir?: string;
+
+  /** Where project boards are kept (JSONL per project). Omitted keeps them in memory only. */
+  boardDir?: string;
+
+  /** The user's skill library and lessons (ALP_HOME). Omitted: only skills inside the project, and project lessons. */
+  libraryDir?: string;
+
+  /** The language the user reads; omitted, their settings.json's language, else Vietnamese (ALPD §54). */
+  language?: string;
+
+  /** Where finished assignments' native threads are recorded for alp_recall. Omitted keeps the record in memory. */
+  recallFile?: string;
+  /** Permanent assignment ownership; unlike recall, results never expire. */
+  assignmentResultFile?: string;
+
+  /** Where pauses are kept across restarts. Omitted keeps them in memory. */
+  pauseFile?: string;
+
+  /**
+   * Resume a runtime a usage limit paused as soon as the runtime says the limit lifted
+   * (ALPD §58). Default true; false tells the user instead, who resumes it.
+   */
+  autoResume?: boolean;
+  /** How often alpd asks a runtime a usage limit paused whether the limit lifted. Default LIMIT_CHECK_MS. */
+  limitCheckMs?: number;
+
+  /** Where running assignments are kept, so the next alpd continues them (ALPD §31). Omitted keeps them in memory. */
+  liveFile?: string;
+
+  /** False parks assignments an earlier alpd left running until the user runs alp resume. Default true: they continue. */
+  recoveryResume?: boolean;
+
+  /** How the previous alpd ended, for what recovered sessions are told. */
+  previousExit?: { kind: 'clean' | 'crash'; at?: string };
+
+  /** False starts no supervisors, for hosts and tests that do not want them. Default true. */
+  supervisor?: boolean;
+
+  /** Runs the GitHub CLI for alp_issue. Default: `gh` (or ALP_GH_BIN) on PATH. */
+  github?: GitHubRunner;
+};
+
+import type { NativeBase, OpenOptions, PromptContent, PromptInput } from '@anhlp/alp-protocol/session';
+export type { NativeBase, OpenOptions, PromptContent, PromptInput } from '@anhlp/alp-protocol/session';
+
+export type ScheduleHandler = (action: 'create' | 'list' | 'get' | 'cancel', params: Record<string, unknown>) => Promise<unknown>;
+
+export type AlpRuntime = {
+  /** The daemon supplies its persistent schedule operations; standalone runtimes have none. */
+  bindSchedules?: (handler: ScheduleHandler | undefined) => void;
+  /** alpd hands over its attachment reader (§12.6) once, at start; with a staging directory, Codex and Claude sessions then take attachment parts. */
+  bindAttachments?: (reader: AttachmentReader | undefined) => void;
+  /** Whether this live session's runtime takes `{ type: 'attachment' }` parts (RuntimeAttachment) now. */
+  takesAttachments?: (sessionId: string) => boolean;
+  /** Removes the staged copy of an attachment alpd no longer keeps. */
+  dropAttachment?: (attachmentId: string) => Promise<void>;
+  onEvent(listener: (envelope: Envelope) => void): () => void;
+  /** Certifies a brand-new generated checkout; never use to adopt an existing workspace. */
+  registerWorkspace(directory: string): Promise<void>;
+  /** Reserves runtime admission while an external checkout mutation runs. */
+  withWorkspaceMutation<T>(directory: string, run: () => Promise<T>): Promise<T>;
+  /** Opens a root session under a client-chosen id. */
+  open(sessionId: string, spec: SessionSpec, options?: OpenOptions): Promise<SessionSnapshot>;
+  /** What a new root would run as, before it opens, and the teams it may choose (ALPD §60). */
+  preview(spec: SessionSpec): Promise<SessionPreview>;
+  /** Failures are reported as prompt.failed, once per clientMessageId. */
+  prompt(sessionId: string, input: PromptInput): Promise<void>;
+  /**
+   * Atomically admits an idle scheduled prompt in the runtime queue. Busy leaves all preparation
+   * untouched. The callback may persist its attempt/receipt, then use its single-use sender;
+   * the sender is valid only during the callback. Do not enqueue runtime operations in the callback.
+   */
+  withIdlePrompt?<T>(sessionId: string, run: (send: (input: PromptInput) => Promise<void>) => Promise<T>): Promise<{ busy: true } | { busy: false; value: T }>;
+  /** Cancels the running turn and closes the whole subtree. */
+  interrupt(sessionId: string): Promise<void>;
+  /** Atomically cancels only this active turn; false leaves the session and subtree untouched. */
+  interruptTurn?(sessionId: string, turnId: string): Promise<boolean>;
+  /** Changes permission mode while idle; undefined keeps the current mode.
+   * onApplied is awaited after apply and before session.updated; failure does not roll back permissions. */
+  configure(sessionId: string, changes: { mode?: string }, options?: { onApplied?: (session: SessionSnapshot) => Promise<void> }): Promise<SessionSnapshot>;
+  close(sessionId: string): Promise<void>;
+  snapshot(sessionId: string): SessionSnapshot | undefined;
+  /** Live sessions, roots before their children. */
+  list(): SessionSnapshot[];
+  /** The live tree containing a session: sessions, assignments, questions, worktrees and leases. */
+  status(sessionId: string): TreeStatus | undefined;
+  /** Questions agents asked the user that wait for an answer. */
+  questions(): UserQuestion[];
+  /** Answers or dismisses a question to the user. */
+  answer(questionId: string, reply: { text?: string; dismiss?: boolean; reason?: string }): void;
+  /** Mails a note from the user to any live session, such as an assignment the user wants to redirect. */
+  message(sessionId: string, text: string): void;
+  /** The project board: live claims, then decisions and findings, oldest first. */
+  board(projectRoot: string): Promise<Pin[]>;
+  /** Holds delegation and wakes on one runtime, or all; now also parks running assignments there. */
+  pause(input?: { runtime?: RuntimeKind; now?: boolean; reason?: string }): PauseState;
+  /** Lifts a pause and continues the assignments it parked. Without a runtime, lifts every pause. */
+  resume(input?: { runtime?: RuntimeKind }): PauseState;
+  /** Current pauses and parked assignments. */
+  pauses(): PauseState;
+  /** Read-only, cached account usage for the web and desktop viewers. */
+  usage(refresh?: boolean): Promise<{ providers: Array<ProviderUsage & { pause: Pause | null; parked: number }> }>;
+  /** The user asks a finished assignment, or the last one on a task of the project, about its work. */
+  recall(target: { assignmentId?: string; taskId?: string; projectRoot?: string }, question: string): Promise<RecallAnswer>;
+  /** Assignments an earlier alpd left running, which recover() can continue once their root is open again. */
+  recoverable(): LiveEntry[];
+  /** Continues work in a reopened tree. continueRoot resumes its running turn; parkedRoot restores its held continuation intent. */
+  recover(rootId: string, options?: { continueRoot?: boolean; parkedRoot?: string }): Promise<RecoveryOutcome[]>;
+  /** Gives up the assignments of a tree whose root cannot be opened again: their tasks go back to open. */
+  abandon(rootId: string, reason: string): Promise<RecoveryOutcome[]>;
+  /** Closes everything; assignments still running stay in the live file, so the next alpd continues them. */
+  shutdown(): Promise<void>;
+  /**
+   * Makes the native conversation a fork or rewind continues (docs/protocol/alp-json-rpc-v1.md §12.7): the
+   * source's conversation cut at a completed turn, persisted by the runtime and leaving the source
+   * unchanged. Touches no live session. Codex forks natively now (thread/fork); Claude validates the
+   * cut against the transcript and answers a binding the first prompt forks (NativeBinding.base).
+   * Refusals throw a ConversationError; one the runtime may or may not have acted on carries
+   * `outcomeUnknown: true`. Absent: the host cannot fork or rewind.
+   */
+  branch?(request: BranchRequest): Promise<NativeBinding>;
+  /**
+   * Moves an idle live root to another native conversation (a rewind), or reopens its own (a reload):
+   * its native process restarts and resumes `binding`, keeping the session id, its configuration and
+   * attached viewers. Refused (ConversationError session_busy) unless the whole tree is idle: no turn,
+   * pending prompt, child, assignment, question, mail or parked work. Emits session.updated.
+   * When the new binding cannot be opened, the old one is reopened and the error thrown; when neither
+   * opens, the session fails as a provider failure does.
+   */
+  rebind?(sessionId: string, binding: NativeBinding): Promise<SessionSnapshot>;
+  /**
+   * Restarts an idle live root's native process on the conversation it runs now (a reload, §12.8):
+   * the same binding, the session's own configuration, id and viewers. Refused as rebind is. The new
+   * process must resume that very conversation (a Claude one is refused unless its transcript, or its
+   * base, exists), never an empty one in its place; when it cannot, the session closes with its
+   * conversation kept (a later open resumes it) and a ConversationError native_refused is thrown.
+   * Emits session.updated.
+   */
+  reload?(sessionId: string): Promise<SessionSnapshot>;
+  /**
+   * Holds the turns the runtime would start by itself on this session (mail wakes) while a lifecycle
+   * operation changes its conversation (a rewind, later a reload or live configure): mail stays queued
+   * and is delivered when the last hold is released, to whatever conversation the session runs then.
+   * rebind does not refuse for mail a hold keeps. Client prompts are not held here; alpd holds them.
+   * Undefined when the session is not open.
+   */
+  hold?(sessionId: string): (() => void) | undefined;
+  /**
+   * Whether an open session may begin a turn it has no id for yet: its turn/start (a prompt or a mail
+   * wake) is reserved, queued or on its way to the native runtime, or its process is opening or restarting. Such a
+   * turn shows in `activeTurnId` only once the runtime answers, and a hold taken meanwhile does not
+   * stop it. False when the session is not open.
+   */
+  starting?(sessionId: string): boolean;
+  /**
+   * What a live root would run with after a change of model, thinking, team or mode (§12.9), and whether
+   * reconfigure would take it now; reads only. `teams` are the teams the host defines for its project.
+   */
+  previewConfigure?(sessionId: string, changes: ConfigureChanges): Promise<ConfigurePreview>;
+  /**
+   * Changes an idle live root's model, thinking, team or mode (§12.9): resolves the new configuration
+   * as session.create would (same runtime, agent and conversation; never more permissions or new
+   * executable resources), then restarts its native process with it on the same conversation (`fresh`:
+   * a root with no turn yet starts a new, empty one). The session takes the new configuration only
+   * once the runtime took it (Codex echoes the model it resumed with); otherwise the old one is
+   * restarted and a ConversationError thrown (`outcomeUnknown` when the runtime may have acted). A
+   * new team also replaces the root's supervisor. Refused as rebind is while the tree is not idle.
+   * `onApplied` lets a host persist the configuration the runtime took before session.updated is
+   * emitted. It is awaited only for an applied change; its failure leaves the runtime configured
+   * and reports outcomeUnknown (never a rollback or a known native refusal).
+   * Emits session.updated after that persistence succeeds.
+   */
+  reconfigure?(sessionId: string, changes: ConfigureChanges, options?: { fresh?: boolean; onApplied?: (result: ConfigureResult) => Promise<void> }): Promise<ConfigureResult>;
+};
+
+import type { ConfigureChanges, EffectiveConfig } from './configure.js';
+export type { ConfigureChanges, EffectiveConfig } from './configure.js';
+import type { ConfigurePreview } from '@anhlp/alp-protocol/session';
+export type { ConfigurePreview } from '@anhlp/alp-protocol/session';
+/** What reconfigure did: the session as it runs now, its effective configuration, and whether its process restarted. */
+export type ConfigureResult = {
+  session: SessionSnapshot;
+  effective: EffectiveConfig;
+  status: 'applied' | 'unchanged';
+  restarted: boolean;
+  /** What the native runtime answered it runs with (Codex: the resumed thread's model and effort). */
+  native?: { model?: string; reasoningEffort?: string };
+};
+
+/** The native conversation a session continues: its thread, or for Claude one its first prompt makes from `base`. */
+export type NativeBinding = { threadId: string; base?: NativeBase };
+
+export type BranchRequest = {
+  runtime: RuntimeKind;
+  /** The conversation to branch: the source session's binding. */
+  source: NativeBinding;
+  /** Where the source session runs (Claude keeps its transcripts by this directory). */
+  cwd: string;
+  /** Where the branch will run; the source's cwd when absent. */
+  targetCwd?: string;
+  /** The configuration the branch keeps: Codex otherwise forks with its default model and settings. */
+  model: string;
+  thinking: string;
+  mode: string;
+  /**
+   * The cut, by ALP turn id (a Codex turn id; a Claude prompt uuid): keep through a completed turn, or
+   * everything before a turn. Absent: the whole conversation.
+   */
+  cutoff?: { throughTurnId: string } | { beforeTurnId: string };
+  /** The source root's turns in order, as ALP's timeline has them, for the cut's validation. */
+  turns: string[];
+};
+
+export type ConversationErrorReason = 'runtime_unsupported' | 'boundary_unmapped' | 'empty_prefix' | 'native_refused' | 'session_busy'
+  // A live configure (§12.9).
+  | 'runtime_mismatch' | 'agent_mismatch' | 'permission_escalation' | 'team_not_found' | 'invalid_params' | 'not_root';
+/** A fork, rewind or rebind the runtime refused; `outcomeUnknown` when the native runtime may have acted. */
+export class ConversationError extends Error {
+  readonly data: { reason: ConversationErrorReason };
+  readonly outcomeUnknown: boolean;
+  constructor(reason: ConversationErrorReason, message: string, { outcomeUnknown = false } = {}) {
+    super(message);
+    this.name = 'ConversationError';
+    this.data = { reason };
+    this.outcomeUnknown = outcomeUnknown;
+  }
+}
+
+import type { SessionPreview } from '@anhlp/alp-protocol/session';
+export type { SessionPreview } from '@anhlp/alp-protocol/session';
+
+/**
+ * The team `alp init` names in a new project's settings (core INIT_TEAM). Kept for compatibility;
+ * it is not the default of a session: preview and create both resolve that through core
+ * `defaultTeam` (settings without workflow.mode run `custom`).
+ */
+export { INIT_TEAM as DEFAULT_TEAM } from '@anhlp/alp-core/workflow';
+
+import type { RecoveryOutcome, Pause, PauseState } from '@anhlp/alp-protocol/session';
+export type { RecoveryOutcome, Pause, PauseState } from '@anhlp/alp-protocol/session';
+
+import type { RecallAnswer } from '@anhlp/alp-protocol/session';
+export type { RecallAnswer } from '@anhlp/alp-protocol/session';

package/src/conversation.ts

@@ -0,0 +1,81 @@
+import { ConversationError, type BranchRequest } from './contracts.js';
+
+/**
+ * Conversation cuts for fork and rewind (docs/protocol/alp-json-rpc-v1.md §12.7). Pure helpers of
+ * runtime.ts's branch(): where a Claude transcript is cut, which Codex turn a fork must end at, and
+ * what a Codex refusal means.
+ */
+
+/** One entry of a Claude session's main chain, as the Agent SDK reads it from the transcript. */
+export type ChainEntry = { uuid: string; type: 'user' | 'assistant'; toolResult?: boolean };
+
+const refuse = (reason: ConstructorParameters<typeof ConversationError>[0], message: string, outcomeUnknown = false) =>
+  new ConversationError(reason, message, { outcomeUnknown });
+
+/** The turn a Codex fork must end at, after ALP's own validation of the cut against its timeline. */
+export function codexForkEnd(request: Pick<BranchRequest, 'cutoff' | 'turns'>) {
+  const { cutoff, turns } = request;
+  if (!cutoff) {
+    if (!turns.length) throw refuse('empty_prefix', 'The conversation has no turn to fork');
+    return { last: turns.at(-1)!, params: {} };
+  }
+  const id = 'beforeTurnId' in cutoff ? cutoff.beforeTurnId : cutoff.throughTurnId;
+  const index = turns.indexOf(id);
+  if (index < 0) throw refuse('boundary_unmapped', `Turn ${id} is not a turn of this conversation`);
+  if ('beforeTurnId' in cutoff) {
+    if (index === 0) throw refuse('empty_prefix', 'Nothing comes before the first turn');
+    return { last: turns[index - 1], params: { beforeTurnId: id } };
+  }
+  return { last: id, params: { lastTurnId: id } };
+}
+
+/** What a refused thread/fork means; one written but unanswered may have forked. */
+export function codexForkRefusal(error: unknown) {
+  if (error instanceof ConversationError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if ((error as { outcomeUnknown?: boolean })?.outcomeUnknown) return refuse('native_refused', `Codex did not answer the fork: ${message}`, true);
+  if (/^turn not found\b/i.test(message)) return refuse('boundary_unmapped', `Codex does not know that turn: ${message}`);
+  if (/identifies an in-progress turn/i.test(message)) return refuse('session_busy', `The turn is still running: ${message}`);
+  return refuse('native_refused', `Codex refused the fork: ${message}`);
+}
+
+/**
+ * The chain uuid a Claude fork resumes at (`resumeSessionAt`): the last entry kept. ALP turn ids are
+ * the prompt uuids it gave Claude, so a turn starts at its prompt entry and runs to the next ALP turn's
+ * prompt; entries of a turn Claude started itself belong to the turn before it. Always a pinned entry,
+ * never "everything", so turns the source adds later never reach a branch made before them.
+ */
+export function claudeCut(chain: ChainEntry[], request: Pick<BranchRequest, 'cutoff' | 'turns'>): string {
+  const { cutoff, turns } = request;
+  const position = new Map(chain.map((entry, index) => [entry.uuid, index]));
+  const prompt = (id: string) => {
+    const index = position.get(id);
+    return index !== undefined && chain[index].type === 'user' && !chain[index].toolResult ? index : undefined;
+  };
+  if (!cutoff) {
+    if (!chain.length) throw refuse('empty_prefix', 'The conversation has no turn to fork');
+    return chain.at(-1)!.uuid;
+  }
+  const id = 'beforeTurnId' in cutoff ? cutoff.beforeTurnId : cutoff.throughTurnId;
+  const turn = turns.indexOf(id);
+  const at = prompt(id);
+  if (turn < 0 || at === undefined) throw refuse('boundary_unmapped', `Turn ${id} is not a turn of this conversation's transcript`);
+  // ALP's turns found in the transcript must come in ALP's order, or the cut would not be what ALP shows.
+  const found = turns.map(prompt).filter((index): index is number => index !== undefined);
+  if (found.some((index, i) => i > 0 && index <= found[i - 1])) throw refuse('boundary_unmapped', 'The transcript orders turns differently from ALP');
+  if ('beforeTurnId' in cutoff) {
+    if (turn === 0 || at === 0) throw refuse('empty_prefix', 'Nothing comes before the first turn');
+    return chain[at - 1].uuid;
+  }
+  // Through a turn: up to the prompt of the next ALP turn the transcript has, else its end.
+  const next = turns.slice(turn + 1).map(prompt).find(index => index !== undefined);
+  return chain[(next ?? chain.length) - 1].uuid;
+}
+
+/** The chain a binding stands for: a pending fork is its base cut at `at`, until its first prompt makes it. */
+export function pendingChain(base: { at?: string }, chain: ChainEntry[]) {
+  if (!base.at) return chain;
+  const index = chain.findIndex(entry => entry.uuid === base.at);
+  if (index < 0) throw refuse('native_refused', `The conversation no longer has the entry ${base.at} it was cut at`);
+  return chain.slice(0, index + 1);
+}

package/src/events.ts

@@ -0,0 +1 @@
+export type * from '@anhlp/alp-protocol/events';

package/src/github.ts

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+import { gitEnvironment } from './workspace.js';
+
+/** Where agents send feedback about ALP itself: its process, tools and agent instructions. */
+export const ALP_REPO = 'phucanh08/alp';
+
+/** Runs the GitHub CLI with optional standard input and returns its standard output. Tests replace it. */
+export type GitHubRunner = (args: string[], options: { cwd: string; input?: string }) => Promise<string>;
+
+function run(command: string, args: string[], { cwd, input }: { cwd: string; input?: string }) {
+  return new Promise<string>((resolve, reject) => {
+    const child = spawn(command, args, { cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], env: gitEnvironment() });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.stdin.on('error', () => {});
+    child.on('error', error => reject((error as NodeJS.ErrnoException).code === 'ENOENT' ? new Error(`${command} is not installed or not on PATH`) : error));
+    child.on('close', code => code === 0 ? resolve(stdout) : reject(new Error((stderr || stdout).trim() || `${command} exited with ${code}`)));
+    child.stdin.end(input ?? '');
+  });
+}
+
+export const gh: GitHubRunner = (args, options) => run(process.env.ALP_GH_BIN ?? 'gh', args, options);
+
+/** The owner/name of the GitHub repository a project's origin remote points to. */
+export async function projectRepo(projectRoot: string) {
+  let url: string;
+  try {
+    url = (await run('git', ['remote', 'get-url', 'origin'], { cwd: projectRoot })).trim();
+  } catch {
+    throw new Error('This project has no git remote named origin; use target "alp" for feedback about ALP, or tell the user');
+  }
+  const match = /github\.com[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(url);
+  if (!match) throw new Error(`The origin remote is not on GitHub (${url}); issues are filed with the GitHub CLI only`);
+  return `${match[1]}/${match[2]}`;
+}

package/src/handoff.ts

@@ -0,0 +1,86 @@
+export const HANDOFF_OUTCOMES = ['complete', 'partial', 'blocked', 'reconsider'] as const;
+export const HANDOFF_LISTS = ['candidate', 'scope', 'verification', 'risks', 'discovered'] as const;
+
+/**
+ * A review's verdict (ALPD §38): each criterion judged with its evidence, findings
+ * by severity, and one result that follows from them, so requesters, tasks and
+ * later a review quorum read every review the same way.
+ */
+export const VERDICT_RESULTS = ['pass', 'pass_with_findings', 'fail', 'blocked'] as const;
+export const CRITERION_RESULTS = ['pass', 'fail', 'not_checked'] as const;
+export const SEVERITIES = ['critical', 'high', 'medium', 'low'] as const;
+export type Verdict = {
+  result: typeof VERDICT_RESULTS[number];
+  criteria: Array<{ criterion: string; result: typeof CRITERION_RESULTS[number]; evidence: string }>;
+  findings?: Array<{ severity: typeof SEVERITIES[number]; where: string; problem: string; fix?: string }>;
+};
+
+export type Handoff = {
+  outcome: typeof HANDOFF_OUTCOMES[number];
+  summary: string;
+  ownership?: string;
+  verdict?: Verdict;
+} & Partial<Record<typeof HANDOFF_LISTS[number], string[]>>;
+
+/** Returns the normalized handoff, or an error message for the child. */
+/** Returns the verdict, or what is wrong with it; its result must follow from its criteria and findings. */
+export function parseVerdict(value: any): Verdict | string {
+  const text = (item: unknown) => typeof item === 'string' && !!item.trim();
+  const only = (item: any, keys: string[]) => !!item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).every(key => keys.includes(key));
+  if (!only(value, ['result', 'criteria', 'findings'])) return 'verdict must be an object with result, criteria and findings';
+  if (!VERDICT_RESULTS.includes(value.result)) return `verdict.result must be one of ${VERDICT_RESULTS.join(', ')}`;
+  if (!Array.isArray(value.criteria) || !value.criteria.length || value.criteria.length > 50) return 'verdict.criteria must list 1 to 50 criteria';
+  for (const item of value.criteria) {
+    if (!only(item, ['criterion', 'result', 'evidence']) || !text(item.criterion) || !text(item.evidence) || !CRITERION_RESULTS.includes(item.result)) {
+      return `each verdict criterion needs criterion, result (${CRITERION_RESULTS.join(', ')}) and evidence`;
+    }
+  }
+  const findings = value.findings ?? [];
+  if (!Array.isArray(findings) || findings.length > 100) return 'verdict.findings must be a list of at most 100 findings';
+  for (const item of findings) {
+    if (!only(item, ['severity', 'where', 'problem', 'fix']) || !SEVERITIES.includes(item.severity) || !text(item.where) || !text(item.problem) || (item.fix !== undefined && !text(item.fix))) {
+      return `each verdict finding needs severity (${SEVERITIES.join(', ')}), where and problem, and optionally fix`;
+    }
+  }
+  const failed = value.criteria.filter((item: any) => item.result === 'fail').length;
+  const serious = findings.filter((item: any) => item.severity === 'critical' || item.severity === 'high').length;
+  if (value.result === 'fail' && !failed && !serious) return 'verdict fail needs a failed criterion or a critical or high finding';
+  if ((value.result === 'pass' || value.result === 'pass_with_findings') && (failed || serious)) {
+    return `verdict ${value.result} cannot have ${failed ? 'a failed criterion' : 'a critical or high finding'}; the result is fail`;
+  }
+  if (value.result === 'pass' && findings.length) return 'verdict pass cannot have findings; use pass_with_findings';
+  if (value.result === 'pass_with_findings' && !findings.length) return 'verdict pass_with_findings needs findings';
+  return { result: value.result, criteria: value.criteria, ...(findings.length ? { findings } : {}) };
+}
+
+/** A verdict in one line: its result and the criteria counts. */
+export function verdictLine(verdict: Verdict) {
+  const count = (result: string) => verdict.criteria.filter(item => item.result === result).length;
+  const parts = [`${count('pass')} passed`, count('fail') ? `${count('fail')} failed` : '', count('not_checked') ? `${count('not_checked')} not checked` : '', verdict.findings?.length ? `${verdict.findings.length} findings` : ''];
+  return `verdict ${verdict.result.toUpperCase()} (${parts.filter(Boolean).join(', ')})`;
+}
+
+export function parseHandoff(args: any): Handoff | string {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return 'Handoff must be an object';
+  const allowed = ['outcome', 'summary', 'ownership', 'verdict', ...HANDOFF_LISTS];
+  if (Object.keys(args).some(key => !allowed.includes(key))) return 'Unknown handoff field';
+  if (!HANDOFF_OUTCOMES.includes(args.outcome)) return `outcome must be one of ${HANDOFF_OUTCOMES.join(', ')}`;
+  if (typeof args.summary !== 'string' || !args.summary.trim()) return 'summary is required';
+  if (args.ownership !== undefined && typeof args.ownership !== 'string') return 'ownership must be a string';
+  const handoff: Handoff = { outcome: args.outcome, summary: args.summary };
+  for (const key of HANDOFF_LISTS) {
+    if (args[key] === undefined) continue;
+    if (!Array.isArray(args[key]) || args[key].length > 100 || !args[key].every((item: unknown) => typeof item === 'string' && item.trim())) {
+      return `${key} must be a list of at most 100 nonempty strings`;
+    }
+    handoff[key] = args[key];
+  }
+  if (args.ownership?.trim()) handoff.ownership = args.ownership;
+  if (args.verdict !== undefined) {
+    const verdict = parseVerdict(args.verdict);
+    if (typeof verdict === 'string') return verdict;
+    handoff.verdict = verdict;
+  }
+  if (JSON.stringify(handoff).length > 32_000) return 'Handoff exceeds 32000 characters; summarize and point to files instead';
+  return handoff;
+}