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

package/src/contracts.ts

@@ -7,6 +7,7 @@ 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>;
@@ -67,6 +68,12 @@ export type RuntimeOptions = {
   /** 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;
 
@@ -78,6 +85,8 @@ export type RuntimeOptions = {
 
   /** 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;
@@ -106,21 +115,44 @@ export type RuntimeOptions = {
   github?: GitHubRunner;
 };
 
-import type { OpenOptions, PromptContent, PromptInput } from '@anhlp/alp-protocol/session';
-export type { OpenOptions, PromptContent, PromptInput } from '@anhlp/alp-protocol/session';
+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>;
-  /** Changes permission mode while idle; undefined keeps the current mode. */
-  configure(sessionId: string, changes: { mode?: string }): Promise<SessionSnapshot>;
+  /** 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. */
@@ -153,8 +185,122 @@ export type AlpRuntime = {
   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';
 

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/index.ts

@@ -1,11 +1,15 @@
 // The ALP runtime: native harnesses, sessions, delegation and mail. Viewer-neutral; never imports a viewer SDK.
-export { createAlpRuntime, DEFAULT_TEAM } from './runtime.js';
-export type { AlpRuntime, RuntimeOptions, OpenOptions, RuntimeTransport, PromptInput, PromptContent, SessionPreview } from './runtime.js';
+export { createAlpRuntime, DEFAULT_TEAM, WorkspaceMutationError } from './runtime.js';
+export type { WorkspaceMutationReason, AlpRuntime, RuntimeOptions, OpenOptions, RuntimeTransport, PromptInput, PromptContent, SessionPreview } from './runtime.js';
+export { ConversationError } from './contracts.js';
+export type { BranchRequest, ConversationErrorReason, NativeBase, NativeBinding, ConfigureChanges, ConfigureResult, ConfigurePreview, EffectiveConfig } from './contracts.js';
 export type { AlpEvent, AlpError, Envelope, SessionSnapshot, TimelineItem, TurnOrigin, AssignmentSnapshot, UserQuestion, TreeStatus, SessionState } from './events.js';
 export { resolveSession, InstructionsAdapter, skillDescription } from './resolve.js';
 export type { SessionSpec, HostMcpServer, ResolvedSession, RuntimeKind } from './resolve.js';
 export { DEFAULT_MODEL, DEFAULT_CLAUDE_MODEL, models, modes, thinkingOptions, thinkingOptionsFor } from './catalog.js';
 export { CodexTransport } from './transport.js';
+export { ATTACHMENT_HEADER, ATTACHMENT_ROUTES, attachmentStageDir, createAttachmentStager, stagingExposure } from './attachments.js';
+export type { AttachmentReader, AttachmentRoute } from './attachments.js';
 export { usageAllows } from './runtime-context.js';
 export { AcpTransport, acpDecision, acpEnv, acpPermission } from './acp-transport.js';
 export type { AcpProvider } from './acp-transport.js';

package/src/mailbox.ts

@@ -27,8 +27,11 @@ export function takeBatch(mail: MailEvent[], accept: (event: MailEvent) => boole
   return batch;
 }
 
+/** How rendered mail begins, so a replayed prompt can tell ALP's mail from the user's words. */
+export const MAIL_HEADER = 'ALP mail from other agents.';
+
 export function renderMail(events: MailEvent[], requester?: string) {
-  const header = 'ALP mail from other agents. ' +
+  const header = `${MAIL_HEADER} ` +
     (events.some(event => event.from === USER)
       ? 'Mail sent by "user" is the user writing to you directly: follow it as a user instruction. ' +
         (requester ? `ALP has told ${requester} about it. You may now ask the user with alp_ask to: "user"; your handoff must say what the user asked and what you did. ` : '')