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

package/dist/configure.d.ts

@@ -0,0 +1,44 @@
+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 declare const CONFIGURABLE: ReadonlySet<RuntimeKind>;
+/**
+ * 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 declare function nativeModelOf(runtime: RuntimeKind, model: string): {
+    model: string;
+} | {
+    runtime: string;
+};
+/**
+ * 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 declare function offered(runtime: RuntimeKind, model: string, mapping: ResolvedSession): boolean;
+/** MCP servers of a resolved session by name and kind: a stdio one runs a command on the host. */
+export declare function mcpOf(mapping: ResolvedSession): EffectiveConfig['mcpServers'];
+/**
+ * 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 declare function executablesOf(mapping: ResolvedSession): Set<string>;
+/** The effective configuration of a resolved root, with its delegation targets, ALP tools and instructions digest. */
+export declare function effectiveOf(runtime: RuntimeKind, mapping: ResolvedSession, extra: {
+    delegates: string[];
+    tools: string[];
+    supervisor: boolean;
+    instructionsSha?: string;
+}): EffectiveConfig;
+/** Which of model, thinking, team and mode differ between two effective configurations. */
+export declare function changesOf(current: EffectiveConfig, proposed: EffectiveConfig): ConfigureChange[];

package/dist/configure.js

@@ -0,0 +1,64 @@
+// packages/runtime/src/configure.ts
+import { createHash } from "node:crypto";
+import { MODELS } from "@anhlp/alp-core/models";
+import { profileModel } from "@anhlp/alp-core/profiles";
+var CONFIGURABLE = /* @__PURE__ */ new Set(["codex", "claude"]);
+var PREFIXED = /^(codex|claude|antigravity|acp)[:/](.*)$/s;
+function nativeModelOf(runtime, model) {
+  const match = PREFIXED.exec(model);
+  if (!match) return { model };
+  return match[1] === runtime ? { model: match[2] } : { runtime: match[1] };
+}
+function offered(runtime, model, mapping) {
+  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}`);
+}
+function mcpOf(mapping) {
+  return Object.entries(mapping.mcp ?? {}).map(([name, server]) => ({ name, kind: server && typeof server === "object" && "command" in server ? "stdio" : "http" }));
+}
+var digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function executablesOf(mapping) {
+  const found = /* @__PURE__ */ new Set();
+  for (const [name, server] of Object.entries(mapping.mcp ?? {})) {
+    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 ?? []) found.add(`hook:${hook.name ?? ""}:${digest([hook.event, hook.command])}`);
+  return found;
+}
+function effectiveOf(runtime, mapping, extra) {
+  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 } : {}
+  };
+}
+function changesOf(current, proposed) {
+  const changes = [];
+  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;
+}
+export {
+  CONFIGURABLE,
+  changesOf,
+  effectiveOf,
+  executablesOf,
+  mcpOf,
+  nativeModelOf,
+  offered
+};

package/dist/contracts.d.ts

@@ -0,0 +1,327 @@
+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, 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' | '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 declare class ConversationError extends Error {
+    readonly data: {
+        reason: ConversationErrorReason;
+    };
+    readonly outcomeUnknown: boolean;
+    constructor(reason: ConversationErrorReason, message: string, { outcomeUnknown }?: {
+        outcomeUnknown?: boolean | undefined;
+    });
+}
+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/dist/contracts.js

@@ -0,0 +1,16 @@
+// packages/runtime/src/contracts.ts
+import { INIT_TEAM } from "@anhlp/alp-core/workflow";
+var ConversationError = class extends Error {
+  data;
+  outcomeUnknown;
+  constructor(reason, message, { outcomeUnknown = false } = {}) {
+    super(message);
+    this.name = "ConversationError";
+    this.data = { reason };
+    this.outcomeUnknown = outcomeUnknown;
+  }
+};
+export {
+  ConversationError,
+  INIT_TEAM as DEFAULT_TEAM
+};

package/dist/conversation.d.ts

@@ -0,0 +1,45 @@
+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;
+};
+/** The turn a Codex fork must end at, after ALP's own validation of the cut against its timeline. */
+export declare function codexForkEnd(request: Pick<BranchRequest, 'cutoff' | 'turns'>): {
+    last: string;
+    params: {
+        beforeTurnId?: undefined;
+        lastTurnId?: undefined;
+    };
+} | {
+    last: string;
+    params: {
+        beforeTurnId: string;
+        lastTurnId?: undefined;
+    };
+} | {
+    last: string;
+    params: {
+        lastTurnId: string;
+        beforeTurnId?: undefined;
+    };
+};
+/** What a refused thread/fork means; one written but unanswered may have forked. */
+export declare function codexForkRefusal(error: unknown): ConversationError;
+/**
+ * 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 declare function claudeCut(chain: ChainEntry[], request: Pick<BranchRequest, 'cutoff' | 'turns'>): string;
+/** The chain a binding stands for: a pending fork is its base cut at `at`, until its first prompt makes it. */
+export declare function pendingChain(base: {
+    at?: string;
+}, chain: ChainEntry[]): ChainEntry[];

package/dist/conversation.js

@@ -0,0 +1,62 @@
+// packages/runtime/src/conversation.ts
+import { ConversationError } from "./contracts.js";
+var refuse = (reason, message, outcomeUnknown = false) => new ConversationError(reason, message, { outcomeUnknown });
+function codexForkEnd(request) {
+  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 } };
+}
+function codexForkRefusal(error) {
+  if (error instanceof ConversationError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if (error?.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}`);
+}
+function claudeCut(chain, request) {
+  const { cutoff, turns } = request;
+  const position = new Map(chain.map((entry, index) => [entry.uuid, index]));
+  const prompt = (id2) => {
+    const index = position.get(id2);
+    return index !== void 0 && chain[index].type === "user" && !chain[index].toolResult ? index : void 0;
+  };
+  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 === void 0) throw refuse("boundary_unmapped", `Turn ${id} is not a turn of this conversation's transcript`);
+  const found = turns.map(prompt).filter((index) => index !== void 0);
+  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;
+  }
+  const next = turns.slice(turn + 1).map(prompt).find((index) => index !== void 0);
+  return chain[(next ?? chain.length) - 1].uuid;
+}
+function pendingChain(base, chain) {
+  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);
+}
+export {
+  claudeCut,
+  codexForkEnd,
+  codexForkRefusal,
+  pendingChain
+};

package/dist/events.d.ts

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

package/dist/github.d.ts

@@ -0,0 +1,10 @@
+/** Where agents send feedback about ALP itself: its process, tools and agent instructions. */
+export declare 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>;
+export declare const gh: GitHubRunner;
+/** The owner/name of the GitHub repository a project's origin remote points to. */
+export declare function projectRepo(projectRoot: string): Promise<string>;

package/dist/github.js

@@ -0,0 +1,39 @@
+// packages/runtime/src/github.ts
+import { spawn } from "node:child_process";
+import { gitEnvironment } from "./workspace.js";
+var ALP_REPO = "phucanh08/alp";
+function run(command, args, { cwd, input }) {
+  return new Promise((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.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 ?? "");
+  });
+}
+var gh = (args, options) => run(process.env.ALP_GH_BIN ?? "gh", args, options);
+async function projectRepo(projectRoot) {
+  let url;
+  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]}`;
+}
+export {
+  ALP_REPO,
+  gh,
+  projectRepo
+};

package/dist/handoff.d.ts

@@ -0,0 +1,36 @@
+export declare const HANDOFF_OUTCOMES: readonly ["complete", "partial", "blocked", "reconsider"];
+export declare const HANDOFF_LISTS: readonly ["candidate", "scope", "verification", "risks", "discovered"];
+/**
+ * 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 declare const VERDICT_RESULTS: readonly ["pass", "pass_with_findings", "fail", "blocked"];
+export declare const CRITERION_RESULTS: readonly ["pass", "fail", "not_checked"];
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low"];
+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 declare function parseVerdict(value: any): Verdict | string;
+/** A verdict in one line: its result and the criteria counts. */
+export declare function verdictLine(verdict: Verdict): string;
+export declare function parseHandoff(args: any): Handoff | string;