@anhlp/alp-runtime 0.0.0-beta.1 → 0.0.0-beta.2

package/src/antigravity-transport.ts

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { createInterface, type Interface } from 'node:readline';
 import { openMcpTools } from './mcp-tools.js';
+import { antigravityToolDetail } from './tool-detail.js';
 
 /**
  * Antigravity provider definition for ALP.
@@ -72,6 +73,8 @@ export function encodePrompt(text: string): string {
  * Emits line-delimited JSON events and parses stdout line by line.
  */
 export class AntigravityTransport {
+  /** Antigravity's prompt is one line of text: no images. */
+  takesImages() { return false; }
   private child?: ChildProcessWithoutNullStreams;
   private lines?: Interface;
   private exit: Promise<void> = Promise.resolve();
@@ -383,6 +386,9 @@ export class AntigravityTransport {
       const toolName = step.tool_name || 'tool';
       const callId = `agy-tool-${this.activeTurn}-${step.step_index ?? ++this.messages}`;
 
+      // The command stays the tool's name, as the journal reads it; the typed detail rides along.
+      const detail = antigravityToolDetail(step.tool_info ?? { name: toolName });
+      const typed = { tool: typeof step.tool_info?.name === 'string' && step.tool_info.name ? step.tool_info.name : toolName, detail };
       if (step.state === 'ACTIVE') {
         this.emit('item/started', {
           threadId: this.conversationId,
@@ -393,6 +399,7 @@ export class AntigravityTransport {
             cwd: this.cwd,
             status: 'inProgress',
             aggregatedOutput: '',
+            ...typed,
           },
         });
       } else if (step.state === 'DONE' || step.state === 'ERROR') {
@@ -409,6 +416,8 @@ export class AntigravityTransport {
             status: step.state === 'DONE' ? 'completed' : 'failed',
             exitCode: step.state === 'DONE' ? 0 : 1,
             aggregatedOutput: output,
+            ...typed,
+            ...(step.state === 'ERROR' ? { error: step.tool_info?.error?.message } : {}),
           },
         });
       }

package/src/claude-transport.ts

@@ -6,6 +6,7 @@ import { optionalRead, claudeUsage } from './runtime-context.js';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { PIN_KINDS } from './board.js';
+import { claudeToolDetail, resultText } from './tool-detail.js';
 import { CLOSE_REASONS, GATE_KINDS, TASK_STATUSES, TASK_TYPES } from '@anhlp/alp-core/tasks';
 import { commandDecision } from '@anhlp/alp-core/permissions';
 
@@ -217,6 +218,13 @@ export function claudeSandboxAvailable() {
 
 const WRITERS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
 /** What ALP asks the user for a permission Claude would otherwise not have. */
+/** One turn-input part as Claude's: text, or a data-URL image as a base64 image block. */
+export function claudeContent(part: any) {
+  const image = part?.type === 'image' && typeof part.url === 'string' ? /^data:(image\/(?:png|jpeg|gif|webp));base64,([A-Za-z0-9+/]+={0,2})$/.exec(part.url) : null;
+  if (part?.type === 'image' && !image) throw new Error('Claude takes images as inline base64 PNG, JPEG, GIF or WebP only');
+  return image ? { type: 'image', source: { type: 'base64', media_type: image[1], data: image[2] } } : { type: 'text', text: part.text };
+}
+
 export type PermissionRequest = { tool: string; input: Record<string, unknown>; reason: 'rule' | 'mode'; rule?: string };
 export type PermissionAnswer = { allow: boolean; always?: boolean; message?: string };
 
@@ -337,7 +345,7 @@ export class ClaudeTransport {
   private activeTurn?: string;
   private closed = false;
   private assistantText = new Map<string, string>();
-  private toolCalls = new Map<string, { name: string; command: string }>();
+  private toolCalls = new Map<string, { name: string; command: string; input: unknown }>();
   /** The last rate limit Claude reported, and whether the running turn hit one. */
   private rateLimit?: { status: string; resetsAt?: number; overageStatus?: string; rateLimitType?: string; utilization?: number };
   private limitedTurn = false;
@@ -448,10 +456,7 @@ export class ClaudeTransport {
         type: 'user',
         message: {
           role: 'user',
-          content: params.input.map((part: any) => ({
-            type: 'text',
-            text: part.text,
-          })),
+          content: params.input.map(claudeContent),
         },
         parent_tool_use_id: null,
         uuid: randomUUID(),
@@ -658,6 +663,9 @@ export class ClaudeTransport {
       });
     }
     if (message.type === 'result') {
+      // The session's cost so far, as Claude counts it; a viewer shows it with the context meter.
+      const cost = (message as any).total_cost_usd;
+      if (typeof cost === 'number' && Number.isFinite(cost) && cost >= 0) this.emit('thread/tokenUsage/updated', { threadId: this.threadId, turnId: this.activeTurn, tokenUsage: { totalCostUsd: cost } });
       const windows = Object.values((message as any).modelUsage ?? {}).map((entry: any) => entry?.contextWindow).filter((value): value is number => typeof value === 'number' && value > 0);
       // Only when it was not measured: the measured window may be the setting's, smaller than the model's.
       if (windows.length && !this.compactAt) this.contextWindow = Math.max(...windows);
@@ -676,7 +684,9 @@ export class ClaudeTransport {
           const command = block.name === 'Bash'
             ? String(block.input?.command ?? '')
             : `${block.name} ${JSON.stringify(block.input ?? {})}`;
-          this.toolCalls.set(block.id, { name: block.name, command });
+          this.toolCalls.set(block.id, { name: block.name, command, input: block.input });
+          // The command stays what skill use, copy escapes and the journal read; the typed detail rides along.
+          const detail = claudeToolDetail(block.name, block.input);
           this.emit('item/started', {
             threadId: this.threadId,
             item: {
@@ -686,6 +696,7 @@ export class ClaudeTransport {
               cwd: this.cwd,
               status: 'inProgress',
               aggregatedOutput: '',
+              ...(detail ? { tool: block.name, detail } : {}),
             },
           });
         }
@@ -697,13 +708,17 @@ export class ClaudeTransport {
       const content = Array.isArray(message.message.content)
         ? message.message.content as any[]
         : [];
-      for (const block of content) {
-        if (block.type !== 'tool_result') continue;
+      // The SDK's structured output belongs to the message's one tool result.
+      const results = content.filter(block => block.type === 'tool_result');
+      const structured = results.length === 1 ? (message as any).tool_use_result : undefined;
+      for (const block of results) {
         const call = this.toolCalls.get(block.tool_use_id);
         if (!call) continue;
         const output = typeof block.content === 'string'
           ? block.content
           : JSON.stringify(block.content ?? '');
+        const text = resultText(block.content);
+        const detail = claudeToolDetail(call.name, call.input, { text, structured, error: Boolean(block.is_error) });
         this.emit('item/completed', {
           threadId: this.threadId,
           item: {
@@ -714,6 +729,7 @@ export class ClaudeTransport {
             status: block.is_error ? 'failed' : 'completed',
             exitCode: block.is_error ? 1 : 0,
             aggregatedOutput: output,
+            ...(detail ? { tool: call.name, detail, ...(block.is_error ? { error: text } : {}) } : {}),
           },
         });
         this.toolCalls.delete(block.tool_use_id);

package/src/contracts.ts

@@ -16,6 +16,8 @@ export type RuntimeTransport = {
   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 = {
@@ -156,8 +158,12 @@ export type AlpRuntime = {
 import type { SessionPreview } from '@anhlp/alp-protocol/session';
 export type { SessionPreview } from '@anhlp/alp-protocol/session';
 
-/** The team a viewer starts a root in when neither it nor the project's settings choose one, as Paseo does. */
-export const DEFAULT_TEAM = 'pho';
+/**
+ * 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';

package/src/index.ts

@@ -24,3 +24,5 @@ export type { Pin, PinKind } from './board.js';
 
 export { ProviderRegistry, createProviderRegistry } from './providers.js';
 export type { ProviderContext, ProviderFactory, ProviderFactories } from './providers.js';
+export { acpToolDetail, antigravityToolDetail, boundDetail, claudeToolDetail, clipText, codexToolCall, stripReadGutter, toolError, DETAIL_FILE_PATHS, DETAIL_TEXT_CHARS, DETAIL_WEB_RESULTS, ERROR_CHARS, TOOL_FAILED } from './tool-detail.js';
+export type { AcpCall, ClaudeResult, CodexToolCall, ToolCallDetail } from './tool-detail.js';

package/src/resolve.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { access, readFile, stat } from 'node:fs/promises';
-import { resolveWorkflow } from '@anhlp/alp-core/workflow';
+import { defaultTeam, resolveWorkflow } from '@anhlp/alp-core/workflow';
 import { initProject } from '@anhlp/alp-core/init';
 import { profileModel, agentProfiles, selectedProfile } from '@anhlp/alp-core/profiles';
 import { jsonObject, resolveAgent } from '@anhlp/alp-core/resolver';
@@ -95,13 +95,13 @@ export async function resolveSession(spec: SessionSpec, options: { templates?: R
     if (scaffoldMissing) await initProject(spec.cwd, { ...starter, library: options.library });
     else if (!spec.restore) {
       const settings = await jsonObject(settingsFile, 'INVALID_SETTINGS');
-      await initProject(spec.cwd, { ...starter, library: options.library, onlyManagedProfiles: true, teamIds: [teamOf(spec.workflow ?? settings.workflow?.mode ?? 'custom')] });
+      await initProject(spec.cwd, { ...starter, library: options.library, onlyManagedProfiles: true, teamIds: [spec.workflow === undefined ? defaultTeam(settings) : teamOf(spec.workflow)] });
     }
   }
   if (options.library) await ensureLibrary(options.library, options.templates ? { templates: options.templates } : {});
   const restored = spec.restore;
   if (restored && spec.agent !== undefined && spec.agent !== restored.agent) throw new Error('Cannot resume a thread as a different ALP agent');
-  const { team, ...workflow } = await resolveWorkflow(spec.cwd, spec.workflow, restored?.workflow, { library: options.library, templates: options.templates });
+  const { team, ...workflow } = await resolveWorkflow(spec.cwd, spec.workflow, restored?.workflow, { library: options.library, templates: options.templates, scaffold: options.initialize === false });
   const agent = await resolveAgent(spec.cwd, { agent: spec.agent ?? restored?.agent, library: options.library, templates: options.templates });
   const oracleModels = team?.oracleModels ?? ORACLE_MODELS;
   if (agent.name === 'oracle' && !restored && !oracleModels.includes(spec.model ?? '')) throw new Error(`Oracle runs on ${oracleModels.join(' or ')}; choose one`);

package/src/runtime.ts

@@ -2,9 +2,10 @@ import { constants as fsConstants } from 'node:fs';
 import type { Session, Assignment, Waiter } from './session-state.js';
 import { errorData, plainObject, toolResult } from './tool-results.js';
 import { createLogger } from '@anhlp/alp-core/log';
+import { PROMPT_IMAGES, base64Bytes } from '@anhlp/alp-protocol';
 import { createBoardDomain } from './board-domain.js';
 import { createWorktreeDomain } from './worktree-domain.js';
-import { DEFAULT_TEAM, type RuntimeTransport, type RuntimeOptions, type OpenOptions, type PromptContent, type PromptInput, type AlpRuntime, type SessionPreview, type RecoveryOutcome, type Pause, type PauseState, type RecallAnswer } from './contracts.js';
+import { type RuntimeTransport, type RuntimeOptions, type OpenOptions, type PromptContent, type PromptInput, type AlpRuntime, type SessionPreview, type RecoveryOutcome, type Pause, type PauseState, type RecallAnswer } from './contracts.js';
 export type { RuntimeTransport, RuntimeOptions, OpenOptions, PromptContent, PromptInput, AlpRuntime, SessionPreview, RecoveryOutcome, Pause, PauseState, RecallAnswer } from './contracts.js';
 export { DEFAULT_TEAM } from './contracts.js';
 import { verdictLine, parseHandoff, type Handoff } from './handoff.js';
@@ -40,9 +41,10 @@ import { OWN_START, sameProcessAlive } from './process-info.js';
 import { createRecallBook, recallPrompt, RECALL_KEEP_MS, RECALL_QUESTION_CHARS, RECALL_TIMEOUT_MS, type RecallEntry } from './recall.js';
 import { branchExists, checkoutFingerprint, checkoutKey, createCopy, createWorktree, reattachWorktree, removeCopy, removeWorktree } from './workspace.js';
 import { claudeSandboxAvailable, SKILL_PLUGIN } from './claude-transport.js';
+import { boundDetail, codexToolCall, toolError } from './tool-detail.js';
 import { ALP_REPO, gh, projectRepo } from './github.js';
 import { optionalRead, usageAllows, COMPACT_SHARE } from './runtime-context.js';
-import { providerUsage, type ProviderUsage } from './usage.js';
+import { providerUsage, sessionUsage, type ProviderUsage } from './usage.js';
 import { parse as toml } from 'smol-toml';
 import { findFormula, formulaDirs, listFormulas, pourFormula } from '@anhlp/alp-core/formulas';
 import { addAllowRule, capMode, commandDecision, profileFor, unwrapShell } from '@anhlp/alp-core/permissions';
@@ -183,6 +185,11 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     return run;
   }
 
+  /** Whether the session's runtime takes images in a prompt: the transport says, else Codex and Claude do. */
+  function takesImages(session: Session) {
+    return session.runtime.takesImages ? session.runtime.takesImages() : session.runtimeKind === 'codex' || session.runtimeKind === 'claude';
+  }
+
   function snapshot(sessionId: string, session: Session): SessionSnapshot {
     return {
       id: sessionId,
@@ -201,6 +208,8 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       ...(session.active ? { activeTurnId: session.active } : {}),
       ...(session.parked ? { parked: session.parked.reason } : {}),
       ...(session.instructionsSha ? { instructionsSha: session.instructionsSha } : {}),
+      ...(takesImages(session) ? { promptImages: true } : {}),
+      ...(session.usage ? { usage: session.usage } : {}),
       busy: !!(session.active || session.pending || session.children.size || session.assignments.size || hasActiveMail(session) || reviewing(session)),
     };
   }
@@ -273,6 +282,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     sessionId: string,
     session: Session,
     item: any,
+    done = false,
   ) {
     if (item.type === 'agentMessage') {
       // The first words main shows after the user wrote: how long the user waited.
@@ -290,7 +300,8 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
         .filter((c: any) => c.type === 'text')
         .map((c: any) => c.text)
         .join('\n');
-      emit(sessionId, { type: 'item', item: { kind: 'user_message', id: item.id, text } });
+      const images = (item.content ?? []).filter((c: any) => c.type === 'image' || c.type === 'localImage').length;
+      emit(sessionId, { type: 'item', item: { kind: 'user_message', id: item.id, text, ...(images ? { images } : {}) } });
       return;
     }
 
@@ -335,24 +346,37 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
         session.journal.push(stamp(`${session.mapping.agent.name} shell ${status}${item.exitCode != null ? ` (exit ${item.exitCode})` : ''}: ${clip(String(item.command ?? ''))}`));
       }
 
+      // A transport that knows the tool attaches its typed detail; the command stays as it was.
+      // The protocol's bounds hold here for every transport (boundDetail passes unknown as it is).
+      const typed = item.detail && typeof item.detail === 'object' && item.detail.type !== 'shell' ? boundDetail(item.detail) : undefined;
       emit(sessionId, {
         type: 'item',
         item: {
           kind: 'tool_call',
           id: item.id,
           callId: item.id,
-          name: 'shell',
+          name: typed ? String(item.tool || 'tool') : 'shell',
           status,
-          ...(status === 'failed' ? { error: 'Command failed' } : {}),
-          detail: {
+          ...(status === 'failed' ? { error: typed ? toolError(item.error) : 'Command failed' } : {}),
+          detail: typed ?? (item.detail?.type === 'shell' ? item.detail : {
             type: 'shell',
             command: item.command,
             cwd: item.cwd,
             output: item.aggregatedOutput ?? '',
             exitCode: item.exitCode,
-          },
+          }),
         },
       });
+      return;
+    }
+
+    // Codex's own file changes, web searches, MCP calls and sub-agents (ALPD §4.2).
+    const call = codexToolCall(item, done);
+    if (call) {
+      emit(sessionId, {
+        type: 'item',
+        item: { kind: 'tool_call', id: item.id, callId: item.id, name: call.name, status: call.status, ...(call.error ? { error: call.error } : {}), detail: call.detail },
+      });
     }
   }
 
@@ -390,19 +414,30 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     if (method === 'item/completed' || method === 'item/started') {
       if (method === 'item/completed') session.progressAt = Date.now();
       if (params.item?.type !== 'userMessage') {
-        nativeItem(sessionId, session, params.item);
+        nativeItem(sessionId, session, params.item, method === 'item/completed');
       }
       if (method === 'item/started' && params.item?.type === 'commandExecution') watchCopy(sessionId, session, params.item);
       if (method === 'item/started' && params.item) skillUse(sessionId, session, params.item);
       return;
     }
 
+    // A running tool call that learned more, such as an ACP call's path or diff.
+    if (method === 'item/updated') {
+      if (params.item?.type === 'commandExecution' && params.item.status === 'inProgress') nativeItem(sessionId, session, params.item);
+      return;
+    }
+
     if (method === 'account/rateLimits/updated') {
       usageReport(session, params);
       return;
     }
 
     if (method === 'thread/tokenUsage/updated') {
+      const usage = sessionUsage(session.usage, params?.tokenUsage);
+      if (usage) {
+        session.usage = usage;
+        emit(sessionId, { type: 'usage', usage });
+      }
       contextReport(sessionId, session, params?.tokenUsage);
       return;
     }
@@ -3165,15 +3200,21 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
       return;
     }
 
-    if (
-      prompt.content.some(
-        (content) =>
-          content.type !== 'text',
-      )
-    ) {
-      throw new Error(
-        'Only text prompts are supported',
-      );
+    if (prompt.content.some(content => content.type !== 'text' && content.type !== 'image')) {
+      throw new Error('Only text and image prompts are supported');
+    }
+    // Inline images only, never a path or URL: the native input gets a data URL ALP builds itself.
+    const images = prompt.content.filter(content => content.type === 'image') as Array<{ type: 'image'; mimeType: string; data: string }>;
+    if (images.length) {
+      if (!takesImages(session)) throw new Error(`${session.runtimeKind === 'acp' ? 'This ACP agent' : session.runtimeKind[0].toUpperCase() + session.runtimeKind.slice(1)} takes no images; send the message as text`);
+      if (images.length > PROMPT_IMAGES.maxCount) throw new Error(`A prompt takes at most ${PROMPT_IMAGES.maxCount} images`);
+      if (images.reduce((sum, image) => sum + (typeof image.data === 'string' ? base64Bytes(image.data) : 0), 0) > PROMPT_IMAGES.maxTotalBytes) throw new Error(`The images of a prompt are at most ${PROMPT_IMAGES.maxTotalBytes} bytes together`);
+      for (const image of images) {
+        const keys = Object.keys(image).filter(key => !['type', 'mimeType', 'data', 'name'].includes(key));
+        if (keys.length || !PROMPT_IMAGES.mimeTypes.includes(image.mimeType) || typeof image.data !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(image.data) || base64Bytes(image.data) > PROMPT_IMAGES.maxBytes) {
+          throw new Error(`An image must be inline base64 ${PROMPT_IMAGES.mimeTypes.join(', ')} of at most ${PROMPT_IMAGES.maxBytes} bytes`);
+        }
+      }
     }
 
     if (
@@ -3195,9 +3236,8 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
     }
 
     const text = prompt.content
-      .map(
-        (content) => content.text ?? '',
-      )
+      .filter(content => content.type === 'text')
+      .map(content => content.text ?? '')
       .join('\n');
 
     // Steering changes the brief; live assignments keep running and report by mail.
@@ -3251,6 +3291,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
           text: origin === 'user' ? text : promptSafe(text),
           text_elements: [],
         },
+        ...images.map(image => ({ type: 'image', url: `data:${image.mimeType};base64,${image.data}` })),
         ...(mail.length && !wake ? [{ type: 'text', text: promptSafe(renderMail(mail, session.parentAgent)), text_elements: [] }] : []),
       ];
 
@@ -3305,6 +3346,7 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
           id: `user:${prompt.clientMessageId}`,
           clientMessageId: prompt.clientMessageId,
           text,
+          ...(images.length ? { images: images.length } : {}),
         },
       });
       if (origin === 'user' && !session.parent) session.userWaiting ??= Date.now();
@@ -3477,12 +3519,10 @@ export function createAlpRuntime(options: RuntimeOptions = {}): AlpRuntime {
 
     async preview(spec) {
       const resolveOptions = { templates: options.templates, library: options.libraryDir, language: options.language };
-      // As Paseo: the team settings name, else Phở; a new project's settings name Phở.
-      const settings = JSON.parse(await readFile(path.join(spec.cwd, '.alp', 'settings.json'), 'utf8').catch(() => '{}'));
-      const named = typeof settings?.workflow?.mode === 'string' && settings.workflow.mode !== 'custom' ? settings.workflow.mode : undefined;
-      const workflow = spec.workflow ?? named ?? DEFAULT_TEAM;
+      // The team session.create would run (resolveWorkflow, ALPD §42): the one chosen, else settings'
+      // workflow.mode, else `custom`; a folder without settings gets init's, which name Phở.
       // A preview only reads: a folder the user has not run anything in stays as it is.
-      const mapping = await resolveSession({ ...spec, workflow }, { ...resolveOptions, initialize: false });
+      const mapping = await resolveSession(spec, { ...resolveOptions, initialize: false });
       const teams = (await listTeams(spec.cwd, { library: options.libraryDir, templates: options.templates }))
         .filter(team => !team.error)
         .map(team => ({ id: team.id, label: team.label ?? team.id, ...(team.description ? { description: team.description } : {}) }));

package/src/session-state.ts

@@ -4,6 +4,7 @@ import type { MailEvent } from './mailbox.js';
 import type { Worktree, WorktreeChange, Copy } from './workspace.js';
 import type { Verification } from '@anhlp/alp-core/verify';
 import type { Handoff } from './handoff.js';
+import type { SessionUsage } from './events.js';
 
 export type Session = {
   runtimeKind: RuntimeKind;
@@ -52,6 +53,8 @@ export type Session = {
   progressAt?: number;
   /** A digest of the instructions the session runs with. */
   instructionsSha?: string;
+  /** The latest usage its runtime reported, shown in viewers' context meters (ALPD §57). */
+  usage?: SessionUsage;
   /** The context advisory was given since the context last emptied (ALPD §57). */
   contextLevel?: number;
   /** An assignment's brief as its requester gave it, repeated after a compaction. */