@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.7

package/src/task/runner.ts

@@ -0,0 +1,365 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+
+import type { ImageContent, Usage } from '@earendil-works/pi-ai';
+import { detectSupportedImageMimeTypeFromFile } from '@earendil-works/pi-coding-agent';
+import { PACKAGE_ROOT } from '../paths.ts';
+import type { ModelSpec } from './models.ts';
+
+// TodoWrite only changes the child's own todo list, so a readonly reviewer can still keep one. The child replaces
+// bash with a sandboxed read-only shell (readonly-shell.ts).
+const READONLY_TOOLS = 'read,grep,find,ls,bash,TodoWrite';
+const AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,126}[A-Za-z0-9]$/;
+export const KILL_GRACE_MS = 3_000;
+// Dialogs block a run until answered. A subagent has nobody to ask, so its owner dismisses them.
+const DIALOG_METHODS = new Set(['select', 'confirm', 'input', 'editor']);
+
+export interface ChildArgsOptions {
+  sessionDir: string;
+  agentId: string;
+  model?: ModelSpec;
+  readonly?: boolean;
+  /** Tools to add back to the loadout Pi restores from the transcript (records.ts `readonlyLaunchRestores`). */
+  restoreTools?: readonly string[];
+  /** The parent's project trust, so the child loads the same project resources (`ctx.isProjectTrusted()`). */
+  trusted?: boolean;
+}
+
+/** Argv for one `pi --mode rpc` subagent process. Its prompts travel as RPC commands on stdin, never in argv. */
+export function childArgs(options: ChildArgsOptions): string[] {
+  const model = options.model === undefined ? [] : ['--model', `${options.model.provider}/${options.model.id}`, ...(options.model.thinking === undefined ? [] : ['--thinking', options.model.thinking])];
+  return [
+    '--mode',
+    'rpc',
+    '--session-dir',
+    options.sessionDir,
+    '--session-id',
+    options.agentId,
+    '-e',
+    PACKAGE_ROOT,
+    ...(options.trusted === undefined ? [] : [options.trusted ? '--approve' : '--no-approve']),
+    ...model,
+    ...(options.readonly === true ? ['--tools', READONLY_TOOLS, '--no-mcp'] : []),
+    ...(options.readonly !== true && (options.restoreTools ?? []).length > 0 ? ['--tools', (options.restoreTools ?? []).map((name) => `+${name}`).join(',')] : []),
+  ];
+}
+
+export function validateAgentId(id: string): string {
+  if (!AGENT_ID.test(id)) throw new Error(`"${id.slice(0, 80)}" is not a valid agent ID.`);
+  return id;
+}
+
+/** Absolute paths of files to attach: `~` expands as in Pi's read paths, and each must be an existing file. */
+export function resolveAttachments(paths: readonly string[], cwd: string, home: string = homedir()): string[] {
+  return paths.map((path) => {
+    const expanded = path === '~' || path.startsWith('~/') ? join(home, path.slice(1)) : path;
+    const absolute = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+    if (!existsSync(absolute)) throw new Error(`file_attachments: ${absolute} does not exist`);
+    if (!statSync(absolute).isFile()) throw new Error(`file_attachments: ${absolute} is not a file`);
+    return absolute;
+  });
+}
+
+export interface ChildInput {
+  text: string;
+  images: ImageContent[];
+}
+
+/**
+ * The first message Pi builds from piped input and `@file` arguments, which RPC mode does not accept: the trimmed
+ * prompt, then each non-empty text file in a <file> block, and each image as an attachment with an empty <file> block.
+ */
+export async function withAttachments(prompt: string, attachments: readonly string[]): Promise<ChildInput> {
+  let text = prompt.trim();
+  const images: ImageContent[] = [];
+  for (const path of attachments) {
+    const bytes = readFileSync(path);
+    if (bytes.length === 0) continue;
+    const mimeType = await detectSupportedImageMimeTypeFromFile(path);
+    if (mimeType === null) {
+      text += `<file name="${path}">\n${bytes.toString('utf8').replace(/^\uFEFF/, '')}\n</file>\n`;
+      continue;
+    }
+    images.push({ type: 'image', mimeType, data: bytes.toString('base64') });
+    text += `<file name="${path}"></file>\n`;
+  }
+  return { text, images };
+}
+
+export interface ChildOptions {
+  command: readonly string[];
+  args: readonly string[];
+  prompt: string;
+  images?: readonly ImageContent[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  onEvent?: (event: { type: string } & Record<string, unknown>) => void;
+}
+
+export interface ChildOutcome {
+  finalText: string;
+  usage: Usage;
+  failure?: string;
+  stderr: string;
+}
+
+export interface ChildHandle {
+  done: Promise<ChildOutcome>;
+  /** Ends the child and its process group now: session shutdown or an aborted foreground call. */
+  kill: () => void;
+  /** stop_agent: aborts the run over RPC so the transcript records it, then kills the group if it outlives the grace period. */
+  stop: () => void;
+  /** Queues a message into the running turn (a new turn if the run just ended); rejects once the child is closing. */
+  steer: (text: string, images: readonly ImageContent[]) => Promise<void>;
+  pid: number | undefined;
+}
+
+export const zeroUsage = (): Usage => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, totalFromProvider: true } });
+
+export function addUsage(left: Usage, right: Usage): Usage {
+  return {
+    input: left.input + right.input,
+    output: left.output + right.output,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    totalTokens: left.totalTokens + right.totalTokens,
+    cost: {
+      input: left.cost.input + right.cost.input,
+      output: left.cost.output + right.cost.output,
+      cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+      total: left.cost.total + right.cost.total,
+      totalFromProvider: left.cost.totalFromProvider === true && right.cost.totalFromProvider === true,
+    },
+  };
+}
+
+interface AssistantRecord {
+  text: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Usage a JSON-mode event adds to the child's session totals, counted the way Pi's own session stats count it:
+ * assistant replies, tool results that carry nested usage (such as a grandchild subagent), and compactions.
+ */
+function usageOf(event: Record<string, unknown>): Usage | undefined {
+  if (event['type'] === 'compaction_end') return (event['result'] as { usage?: Usage } | undefined)?.usage;
+  const message = event['message'] as { role?: string; usage?: Usage } | undefined;
+  if (event['type'] !== 'message_end' || (message?.role !== 'assistant' && message?.role !== 'toolResult')) return undefined;
+  return message.usage;
+}
+
+function readAssistant(event: Record<string, unknown>): AssistantRecord | undefined {
+  const message = event['message'] as { role?: string; content?: { type: string; text?: string }[]; stopReason?: string; errorMessage?: string } | undefined;
+  if (event['type'] !== 'message_end' || message?.role !== 'assistant') return undefined;
+  const text = (message.content ?? [])
+    .filter((part) => part.type === 'text')
+    .map((part) => part.text ?? '')
+    .join('');
+  return {
+    text,
+    ...(message.stopReason === undefined ? {} : { stopReason: message.stopReason }),
+    ...(message.errorMessage === undefined ? {} : { errorMessage: message.errorMessage }),
+  };
+}
+
+function lineReader(onLine: (line: string) => void): (chunk: Buffer) => void {
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  return (chunk) => {
+    buffer += decoder.write(chunk);
+    for (let index = buffer.indexOf('\n'); index !== -1; index = buffer.indexOf('\n')) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (line !== '') onLine(line);
+    }
+  };
+}
+
+/** RPC mode reserves stdout for protocol records, but a child extension can still print there; such a line must not crash the parent. */
+function parseEvent(line: string): ({ type: string } & Record<string, unknown>) | undefined {
+  try {
+    const value: unknown = JSON.parse(line);
+    return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string' ? (value as { type: string } & Record<string, unknown>) : undefined;
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+}
+
+/** Signals the child's whole process group. A group that is already gone (ESRCH) or not ours (EPERM) is left alone. */
+export function signalGroup(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ESRCH' && code !== 'EPERM') throw error;
+  }
+}
+
+function killGroup(pid: number | undefined): void {
+  if (pid === undefined) return;
+  signalGroup(pid, 'SIGTERM');
+  setTimeout(() => signalGroup(pid, 'SIGKILL'), KILL_GRACE_MS).unref();
+}
+
+interface ChildState {
+  usage: Usage;
+  stderr: string;
+  aborted: boolean;
+  stopped: boolean;
+  /** Why Pi refused the first prompt. */
+  refused?: string;
+}
+
+function outcomeOf(last: AssistantRecord | undefined, state: ChildState, code: number | null): ChildOutcome {
+  const base = { finalText: last?.text ?? '', usage: state.usage, stderr: state.stderr };
+  if (state.aborted) return { ...base, failure: 'Subagent was aborted' };
+  if (state.stopped) return { ...base, failure: 'Subagent was stopped with stop_agent' };
+  if (state.refused !== undefined) return { ...base, failure: state.refused };
+  if (last?.stopReason === 'error' || last?.stopReason === 'aborted') return { ...base, failure: last.errorMessage ?? `subagent stopped: ${last.stopReason}` };
+  if (code !== 0) return { ...base, failure: `pi exited with code ${code}: ${state.stderr.trim().split('\n').at(-1) ?? ''}`.trim() };
+  return base;
+}
+
+interface RpcResponse {
+  id?: string;
+  success: boolean;
+  error?: string;
+  data?: { disposition?: string; steering?: string[]; followUp?: string[] };
+}
+
+/**
+ * Runs one `pi --mode rpc` child in its own process group, so abort and shutdown can stop it and everything it started.
+ * The child stays open while its run is active or a command awaits its response, so a steer always lands in a run;
+ * once the run settles with nothing outstanding, closing stdin makes Pi save the session and exit.
+ * Pi's `RpcClient` cannot start or end this child (no detached spawn, stdin close, `extension_ui_response`, or exit
+ * code); docs/native-gaps.md records each missing mechanism.
+ */
+export function startChild(options: ChildOptions): ChildHandle {
+  const [command, ...prefix] = options.command;
+  if (command === undefined) throw new Error('startChild needs a command');
+  const child = spawn(command, [...prefix, ...options.args], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+  const state: ChildState = { usage: zeroUsage(), stderr: '', aborted: false, stopped: false };
+  let last: AssistantRecord | undefined;
+  let open = true;
+  let idle = true;
+  let steered = false;
+  let nextId = 0;
+  let grace: ReturnType<typeof setTimeout> | undefined;
+  const waiting = new Map<string, (response: RpcResponse) => void>();
+
+  const write = (record: Record<string, unknown>) => {
+    if (open) child.stdin.write(`${JSON.stringify(record)}\n`);
+  };
+  const close = () => {
+    if (!open) return;
+    open = false;
+    child.stdin.end();
+  };
+  const request = (record: Record<string, unknown>, onResponse: (response: RpcResponse) => void) => {
+    const id = `pstack-${nextId++}`;
+    waiting.set(id, onResponse);
+    write({ ...record, id });
+  };
+  const prompt = (text: string, images: readonly ImageContent[], onResponse: (response: RpcResponse) => void, streamingBehavior?: 'steer') =>
+    request({ type: 'prompt', message: text, ...(images.length === 0 ? {} : { images }), ...(streamingBehavior === undefined ? {} : { streamingBehavior }) }, (response) => {
+      if (response.data?.disposition === 'started') idle = false;
+      onResponse(response);
+    });
+  // A steer can reach Pi just as its run ends and stay queued with no run to take it, so it goes out as a new prompt.
+  const closeWhenSettled = () => {
+    if (!open || !idle || waiting.size > 0) return;
+    if (!steered || state.stopped) return close();
+    steered = false;
+    request({ type: 'clear_queue' }, (response) => {
+      const left = [...(response.data?.steering ?? []), ...(response.data?.followUp ?? [])];
+      if (left.length > 0) prompt(left.join('\n\n'), [], () => undefined);
+    });
+  };
+
+  const kill = () => {
+    state.aborted = true;
+    killGroup(child.pid);
+  };
+  const stop = () => {
+    if (state.stopped || state.aborted) return;
+    state.stopped = true;
+    request({ type: 'clear_queue' }, () => undefined);
+    request({ type: 'abort' }, () => undefined);
+    grace = setTimeout(() => killGroup(child.pid), KILL_GRACE_MS);
+    grace.unref();
+  };
+  const steer = (text: string, images: readonly ImageContent[]) =>
+    new Promise<void>((resolve, reject) => {
+      if (!open || state.stopped || state.aborted) return reject(new Error('The subagent has finished its run.'));
+      steered = true;
+      prompt(text, images, (response) => (response.success ? resolve() : reject(new Error(response.error ?? 'Pi refused the message.'))), 'steer');
+    });
+
+  const onRecord = (record: { type: string } & Record<string, unknown>) => {
+    if (record.type === 'response') {
+      const response = record as unknown as RpcResponse;
+      const onResponse = response.id === undefined ? undefined : waiting.get(response.id);
+      if (onResponse === undefined) return;
+      waiting.delete(response.id as string);
+      onResponse(response);
+      return closeWhenSettled();
+    }
+    if (record.type === 'extension_ui_request') {
+      if (DIALOG_METHODS.has(String(record['method']))) write({ type: 'extension_ui_response', id: record['id'], cancelled: true });
+      return;
+    }
+    options.onEvent?.(record);
+    if (record.type === 'agent_start') idle = false;
+    const usage = usageOf(record);
+    if (usage !== undefined) state.usage = addUsage(state.usage, usage);
+    last = readAssistant(record) ?? last;
+    if (record.type === 'agent_settled') {
+      idle = true;
+      closeWhenSettled();
+    }
+  };
+
+  child.stdout.on(
+    'data',
+    lineReader((line) => {
+      const record = parseEvent(line);
+      if (record === undefined) state.stderr = `${state.stderr}${line}\n`.slice(-8_192);
+      else onRecord(record);
+    }),
+  );
+  child.stderr.on('data', (chunk: Buffer) => {
+    state.stderr = `${state.stderr}${chunk.toString('utf8')}`.slice(-8_192);
+  });
+  // A child that exits or is killed before it reads a large prompt closes the pipe. Unhandled, that EPIPE would be an
+  // uncaught exception in the parent, and interactive Pi exits on one; the child's exit already reports the failure.
+  child.stdin.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code !== 'EPIPE' && error.code !== 'ECONNRESET') state.stderr = `${state.stderr}stdin: ${error.message}\n`.slice(-8_192);
+  });
+  if (options.signal?.aborted) kill();
+  else options.signal?.addEventListener('abort', kill, { once: true });
+  if (state.aborted || (options.prompt.trim() === '' && (options.images ?? []).length === 0)) close();
+  else
+    prompt(options.prompt, options.images ?? [], (response) => {
+      if (!response.success) state.refused = response.error ?? 'Pi refused the prompt.';
+    });
+  const done = new Promise<ChildOutcome>((resolveDone) => {
+    child.on('error', (error) => resolveDone({ finalText: '', usage: state.usage, stderr: state.stderr, failure: `could not start pi: ${error.message}` }));
+    child.on('close', (code) => {
+      open = false;
+      clearTimeout(grace);
+      options.signal?.removeEventListener('abort', kill);
+      resolveDone(outcomeOf(last, state, code));
+      for (const onResponse of waiting.values()) onResponse({ success: false, error: 'The subagent exited.' });
+      waiting.clear();
+    });
+  });
+  return { done, kill, stop, steer, pid: child.pid };
+}

package/src/task/status.ts

@@ -0,0 +1,170 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { subagentDir } from '../paths.ts';
+import type { ModelSpec } from './models.ts';
+import { readRecord, recordIds, runningPid, transcriptFor } from './records.ts';
+import { validateAgentId } from './runner.ts';
+
+const LIST_LIMIT = 20;
+const TEXT_LIMIT = 500;
+const FIRST_READ_BYTES = 64 * 1024;
+// A transcript can grow to hundreds of megabytes; status reads only its tail.
+const TAIL_LIMIT_BYTES = 4 * 1024 * 1024;
+
+export interface AgentStatus {
+  agentId: string;
+  state: 'running' | 'idle' | 'missing';
+  pid?: number;
+  type?: string;
+  model?: string;
+  readonly?: boolean;
+  directory?: string;
+  branch?: string;
+  forkedFrom?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  transcript?: string;
+  lastText?: string;
+}
+
+const modelName = (model: ModelSpec | undefined) => (model === undefined ? "Pi's default model" : `${model.provider}/${model.id}${model.thinking === undefined ? '' : `:${model.thinking}`}`);
+
+function truncate(text: string): string {
+  const flat = text.trim();
+  return flat.length > TEXT_LIMIT ? `${flat.slice(0, TEXT_LIMIT)}…` : flat;
+}
+
+function readTail(path: string, size: number, bytes: number): string {
+  const length = Math.min(size, bytes);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, 'r');
+  try {
+    readSync(fd, buffer, 0, length, size - length);
+  } finally {
+    closeSync(fd);
+  }
+  return buffer.toString('utf8');
+}
+
+function assistantTextOf(line: string): string | undefined {
+  let entry: { type?: unknown; message?: { role?: unknown; content?: unknown } };
+  try {
+    entry = JSON.parse(line) as typeof entry;
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (entry.type !== 'message' || entry.message?.role !== 'assistant' || !Array.isArray(entry.message.content)) return undefined;
+  const text = (entry.message.content as { type?: unknown; text?: unknown }[])
+    .filter((part) => part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text as string)
+    .join('');
+  return text.trim() === '' ? undefined : truncate(text);
+}
+
+/** The text of the last assistant message in a Pi session file, scanning back from the end through at most its last 4 MiB. */
+export function lastAssistantText(transcript: string): string | undefined {
+  const { size } = statSync(transcript);
+  for (let bytes = FIRST_READ_BYTES; ; bytes *= 4) {
+    const lines = readTail(transcript, size, bytes).split('\n');
+    // The first line of a partial read is cut off.
+    if (bytes < size) lines.shift();
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const text = assistantTextOf(lines[index]?.trim() ?? '');
+      if (text !== undefined) return text;
+    }
+    if (bytes >= size || bytes >= TAIL_LIMIT_BYTES) return undefined;
+  }
+}
+
+/** One agent's state from its record, run lock, and transcript. Reads files only; never starts anything. */
+export function agentStatus(dir: string, agentId: string): AgentStatus {
+  const record = readRecord(dir, agentId);
+  const transcript = transcriptFor(dir, agentId);
+  if (record === undefined && transcript === undefined) return { agentId, state: 'missing' };
+  const pid = runningPid(dir, agentId);
+  const updated = transcript ?? join(dir, `${agentId}.json`);
+  const lastText = transcript === undefined ? undefined : lastAssistantText(transcript);
+  return {
+    agentId,
+    state: pid === undefined ? 'idle' : 'running',
+    ...(pid === undefined ? {} : { pid }),
+    ...(record === undefined
+      ? {}
+      : {
+          type: record.type,
+          model: modelName(record.model),
+          readonly: record.readonly,
+          directory: record.worktree?.cwd ?? record.cwd,
+          createdAt: record.createdAt,
+          ...(record.worktree === undefined ? {} : { branch: record.worktree.branch }),
+          ...(record.forkedFrom === undefined ? {} : { forkedFrom: record.forkedFrom }),
+        }),
+    ...(existsSync(updated) ? { updatedAt: statSync(updated).mtime.toISOString() } : {}),
+    ...(transcript === undefined ? {} : { transcript }),
+    ...(lastText === undefined ? {} : { lastText }),
+  };
+}
+
+/** Agents with a record in `dir`, newest first, at most `limit`, and how many there are in all. */
+export function listAgentStatuses(dir: string, limit: number = LIST_LIMIT): { agents: AgentStatus[]; total: number } {
+  const records = recordIds(dir).flatMap((agentId) => {
+    try {
+      const record = readRecord(dir, agentId);
+      return record === undefined ? [] : [record];
+    } catch {
+      return [];
+    }
+  });
+  const newest = records.toSorted((left, right) => right.createdAt.localeCompare(left.createdAt)).slice(0, limit);
+  return { agents: newest.map((record) => agentStatus(dir, record.agentId)), total: records.length };
+}
+
+export function statusText(status: AgentStatus): string {
+  if (status.state === 'missing') return `Agent ${status.agentId}: missing (no record or transcript in this workspace)`;
+  const fields: [string, string | undefined][] = [
+    ['state', status.state === 'running' ? `running (pid ${status.pid})` : 'idle'],
+    ['type', status.type === undefined ? undefined : `${status.type}${status.readonly === true ? ' (readonly)' : ''}`],
+    ['model', status.model],
+    ['directory', status.directory],
+    ['branch', status.branch],
+    ['forked from', status.forkedFrom],
+    ['created', status.createdAt],
+    ['updated', status.updatedAt],
+    ['transcript', status.transcript],
+  ];
+  const lines = fields.flatMap(([name, value]) => (value === undefined ? [] : [`  ${name}: ${value}`]));
+  const last = status.lastText === undefined ? [] : ['  last response:', ...status.lastText.split('\n').map((line) => `    ${line}`)];
+  return [`Agent ${status.agentId}`, ...lines, ...last].join('\n');
+}
+
+export const AgentStatusParams = Type.Object({
+  agent_id: Type.Optional(Type.String({ description: 'Agent ID from an earlier Task call in this workspace. Omit it to list the most recent agents, newest first.' })),
+});
+
+const DESCRIPTION =
+  'Read-only status of subagents in this workspace: running or idle, type, model, directory, worktree branch, created and updated times, and the last response. This is the way to check on a worker; it never starts, messages, or resumes anything. Task resume would message a running agent or restart an idle one instead.';
+
+export function registerAgentStatus(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'agent_status',
+    label: 'Agent status',
+    description: DESCRIPTION,
+    promptSnippet: 'Check subagents read-only (running or idle, last response) without restarting them',
+    parameters: AgentStatusParams,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const dir = subagentDir(ctx.cwd);
+      if (params.agent_id !== undefined) {
+        const status = agentStatus(dir, validateAgentId(params.agent_id));
+        return { content: [{ type: 'text', text: statusText(status) }], details: { agents: [status], total: status.state === 'missing' ? 0 : 1 } };
+      }
+      const { agents, total } = listAgentStatuses(dir);
+      const header = total === 0 ? 'No subagents in this workspace yet.' : `${total} subagent${total === 1 ? '' : 's'} in this workspace${total > agents.length ? `; the ${agents.length} newest` : ''}:`;
+      return { content: [{ type: 'text', text: [header, ...agents.map(statusText)].join('\n\n') }], details: { agents, total } };
+    },
+  });
+}

package/src/task/stop.ts

@@ -0,0 +1,100 @@
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { subagentDir } from '../paths.ts';
+import { type ChildHandle, KILL_GRACE_MS, signalGroup, validateAgentId } from './runner.ts';
+import { agentStatus } from './status.ts';
+
+// A subagent starts a moment before its owner writes its pid into the run lock.
+const LOCK_AFTER_START_MS = 3_000;
+const POLL_MS = 100;
+
+function processStart(pid: number): number | undefined {
+  try {
+    const started = Date.parse(execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim());
+    return Number.isNaN(started) ? undefined : started;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether the run lock's pid is the subagent process: one this user may signal that started just before the lock named
+ * it. That refuses a lock naming its owner while the owner prepares the launch, and a pid reused after a crash.
+ */
+function isLockedChild(lockPath: string, pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  const started = processStart(pid);
+  const named = statSync(lockPath).mtimeMs;
+  return started !== undefined && started <= named && started >= named - LOCK_AFTER_START_MS;
+}
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function exited(pid: number, withinMs: number): Promise<boolean> {
+  const deadline = Date.now() + withinMs;
+  while (alive(pid) && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  return !alive(pid);
+}
+
+/** Stops the subagent another Pi process runs: SIGTERM to its process group, then SIGKILL after the grace period. */
+async function stopElsewhere(agentId: string, lockPath: string, pid: number): Promise<string> {
+  if (!isLockedChild(lockPath, pid))
+    return `Agent ${agentId}'s run lock names pid ${pid}, which is not a subagent process this user can stop (its owner may still be starting it, or the lock is stale). Nothing was signalled; check again with agent_status.`;
+  signalGroup(pid, 'SIGTERM');
+  if (await exited(pid, KILL_GRACE_MS)) return `Stopped agent ${agentId}: another Pi process ran it (pid ${pid}), so it got SIGTERM and has exited. That process reports the stop as the agent's result.`;
+  signalGroup(pid, 'SIGKILL');
+  const gone = await exited(pid, KILL_GRACE_MS);
+  return `Agent ${agentId} (pid ${pid}, run by another Pi process) ignored SIGTERM, so it got SIGKILL${gone ? ' and has exited' : ' and has not exited yet'}.`;
+}
+
+export interface StopAgentOptions {
+  /** A child this process runs, if any. */
+  running: (agentId: string) => { handle: ChildHandle } | undefined;
+  depth: number;
+}
+
+const DESCRIPTION =
+  'Stop a running subagent: abort its run and end its process. Its result (the completion notification of a background agent, or the waiting Task result of a foreground one) reports the stop. An agent that is not running is left alone. Resume a stopped agent with Task resume.';
+
+export function registerStopAgent(pi: ExtensionAPI, options: StopAgentOptions): void {
+  pi.registerTool({
+    name: 'stop_agent',
+    label: 'Stop agent',
+    description: DESCRIPTION,
+    promptSnippet: 'Stop a running subagent by agent ID',
+    parameters: Type.Object({ agent_id: Type.String({ description: 'Agent ID from an earlier Task call in this workspace.' }) }),
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    // Nesting stops at the subagent of a subagent, which has no subagents to stop.
+    defaultActive: options.depth < 2,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const agentId = validateAgentId(params.agent_id);
+      const owned = options.running(agentId);
+      if (owned !== undefined) {
+        owned.handle.stop();
+        await owned.handle.done;
+        return { content: [{ type: 'text', text: `Stopped agent ${agentId}: its run was aborted and its process has exited. Its result reports the stop; resume it with Task resume.` }], details: { agentId, stopped: true } };
+      }
+      const dir = subagentDir(ctx.cwd);
+      const status = agentStatus(dir, agentId);
+      if (status.state === 'missing') throw new Error(`Unknown agent ID ${agentId}. stop_agent needs an agent ID returned by an earlier Task call in this workspace.`);
+      if (status.state === 'idle' || status.pid === undefined) return { content: [{ type: 'text', text: `Agent ${agentId} is not running, so there is nothing to stop.` }], details: { agentId, stopped: false } };
+      const text = await stopElsewhere(agentId, join(dir, `${agentId}.lock`), status.pid);
+      return { content: [{ type: 'text', text }], details: { agentId, stopped: !alive(status.pid), pid: status.pid } };
+    },
+  });
+}