@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/src/runs/foreground/management-actions.ts

@@ -1,360 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { handleManagementAction } from "../../agents/agent-management.ts";
-import { buildDoctorReport } from "../../extension/doctor.ts";
-import {
-  resolveIntercomSessionTarget,
-  resolveOrchestratorIntercomTarget,
-} from "../../intercom/intercom-bridge.ts";
-import { queryLiveIntercomHealth, queryLiveIntercomStatus } from "../../intercom/live-intercom.ts";
-import { inspectSubagentStatus } from "../background/run-status.ts";
-import { resolveSubagentRunId, type ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
-import {
-  ownedRunList,
-  ownedRunStatusResult,
-  ownedRunView,
-  rememberOwnedRun,
-  resolveOwnedRun,
-} from "../shared/run-records.ts";
-import { ownedHistoryQuery } from "../shared/run-history-queries.ts";
-import { errorMessage } from "../../shared/unknown.ts";
-import { SUBAGENT_ACTIONS, type SubagentExecutionResult } from "../../shared/types.ts";
-import { controlSupervisorQuestion } from "./question-control.ts";
-import {
-  MUTATING_MANAGEMENT_ACTIONS,
-  extendAsyncTimeoutResult,
-  interruptAsyncRun,
-  interruptNestedRun,
-  nestedResolutionScopeForExecutor,
-  nudgeSubagentRun,
-  rememberedForegroundStatusResult,
-  resolveRememberedForegroundRun,
-  resumeAsyncRun,
-} from "./foreground-control.ts";
-import type { ExecutorDeps, SubagentParamsLike } from "./subagent-params.ts";
-
-export interface ManagementInvocation {
-  readonly params: SubagentParamsLike;
-  readonly requestCwd: string;
-  readonly ctx: ExtensionContext;
-  readonly signal?: AbortSignal;
-}
-function failure(error: unknown): SubagentExecutionResult {
-  return {
-    content: [{ type: "text", text: errorMessage(error) }],
-    isError: true,
-    details: { mode: "management", results: [] },
-  };
-}
-function present(value: string | undefined): boolean {
-  return value !== undefined && value.length > 0;
-}
-function reviewRequest(params: SubagentParamsLike): {
-  readonly id: string;
-  readonly decision: "accepted" | "needs_changes";
-} {
-  const id = params.id ?? params.runId;
-  if (
-    id === undefined ||
-    id.length === 0 ||
-    (params.decision !== "accepted" && params.decision !== "needs_changes")
-  ) {
-    throw new Error("action='review' requires id and decision ('accepted' or 'needs_changes').");
-  }
-  return { id, decision: params.decision };
-}
-/** Owns management actions against the current session's durable and tracked run state. */
-export class ManagementActions {
-  private readonly deps: ExecutorDeps;
-  constructor(
-    // Reviews and stop requests update this session's actual tracked state and persistence owner.
-    deps: ExecutorDeps,
-  ) {
-    this.deps = deps;
-  }
-  async execute(call: ManagementInvocation): Promise<SubagentExecutionResult> {
-    switch (call.params.action) {
-      case "review":
-        return this.review(call);
-      case "history":
-      case "search":
-        return this.history(call);
-      case "questions":
-      case "answer":
-        return controlSupervisorQuestion({ ...call, deps: this.deps });
-      case "doctor":
-        return this.doctor(call);
-      case "status":
-        return this.status(call);
-      case "nudge":
-        return nudgeSubagentRun({ params: call.params, deps: this.deps, ctx: call.ctx });
-      case "resume":
-        return resumeAsyncRun({ ...call, deps: this.deps });
-      case "extend":
-        return this.extend(call.params);
-      case "interrupt":
-        return this.interrupt(call.params);
-      case undefined:
-      default:
-        return this.manageAgent(call);
-    }
-  }
-  private review(call: ManagementInvocation): SubagentExecutionResult {
-    const { params } = call;
-    try {
-      const request = reviewRequest(params);
-      const run = resolveOwnedRun(this.deps.state, request.id);
-      if (!run) {
-        throw new Error("Run not found in this parent session.");
-      }
-      if (ownedRunView(run, this.deps.state).state === "live") {
-        throw new Error(
-          "The run is still live. Use nudge for guidance, or stop it before reviewing its result.",
-        );
-      }
-      const reviewed = {
-        ...run,
-        review: {
-          decision: request.decision,
-          ...(present(params.message) ? { message: params.message } : {}),
-          reviewedAt: Date.now(),
-        },
-      };
-      rememberOwnedRun(this.deps.state, reviewed);
-      const result = ownedRunStatusResult(reviewed, this.deps.state, undefined, {
-        childSafe: nestedResolutionScopeForExecutor(this.deps) !== undefined,
-      });
-      const tool =
-        this.deps.allowMutatingManagementActions === false &&
-        this.deps.config.compactChildTools === false
-          ? "subagent resume/nudge"
-          : "agent_runs continue/nudge";
-      return {
-        ...result,
-        content: [
-          {
-            type: "text",
-            text: `Saved parent review for ${run.runId}: ${request.decision}.\nThe review note is parent-only and was not sent to the child. Put actionable instructions in ${tool}. No work started.`,
-          },
-        ],
-      };
-    } catch (error) {
-      return failure(error);
-    }
-  }
-  private async history(call: ManagementInvocation): Promise<SubagentExecutionResult> {
-    try {
-      return await ownedHistoryQuery(this.deps.state, call.params, call.signal);
-    } catch (error) {
-      return failure(error);
-    }
-  }
-  private doctorSession(ctx: ExtensionContext) {
-    let currentSessionFile: string | null = null;
-    let currentSessionId = this.deps.state.currentSessionId;
-    let sessionError: string | undefined;
-    try {
-      currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
-      currentSessionId = ctx.sessionManager.getSessionId();
-    } catch (error) {
-      sessionError =
-        error instanceof Error ? `${error.name}: ${error.message}` : errorMessage(error);
-    }
-    return { currentSessionFile, currentSessionId, sessionError };
-  }
-  private async doctor(call: ManagementInvocation): Promise<SubagentExecutionResult> {
-    const session = this.doctorSession(call.ctx);
-    let orchestratorTarget: string | undefined;
-    try {
-      const fallback = resolveIntercomSessionTarget(
-        this.deps.pi.getSessionName(),
-        call.ctx.sessionManager.getSessionId(),
-      );
-      orchestratorTarget = resolveOrchestratorIntercomTarget(this.deps.pi.events, fallback);
-    } catch {
-      /* Identity lookup is optional; the doctor still reports the other observed session facts. */
-    }
-    const { connection } = await queryLiveIntercomStatus(this.deps.pi.events);
-    return {
-      content: [
-        {
-          type: "text",
-          text: buildDoctorReport({
-            cwd: call.requestCwd,
-            nativeSessionCwd: call.ctx.cwd,
-            config: this.deps.config,
-            state: this.deps.state,
-            requestedSessionDir: call.params.sessionDir,
-            ...session,
-            orchestratorTarget,
-            connection,
-            projectTrusted: call.ctx.isProjectTrusted(),
-            expandTilde: this.deps.expandTilde,
-          }),
-        },
-      ],
-      details: { mode: "management", results: [] },
-    };
-  }
-  private async status(call: ManagementInvocation): Promise<SubagentExecutionResult> {
-    const id = call.params.id ?? call.params.runId;
-    if (this.isParentListQuery(call.params) && this.deps.state.ownedRuns !== undefined) {
-      try {
-        return await ownedRunList(this.deps.state, { ...call.params, signal: call.signal });
-      } catch (error) {
-        return failure(error);
-      }
-    }
-    let includeRunHeader = true;
-    try {
-      includeRunHeader = this.includeRunHeader(call.params);
-    } catch (error) {
-      return failure(error);
-    }
-    const inspected = await this.inspectStatus(call.params, includeRunHeader);
-    const remembered = this.statusFallback(id, inspected);
-    if (remembered) {
-      return remembered;
-    }
-    return this.isParentListQuery(call.params)
-      ? this.appendForegroundStatuses(inspected)
-      : inspected;
-  }
-  private isParentListQuery(params: SubagentParamsLike): boolean {
-    return (
-      !present(params.id ?? params.runId) &&
-      !present(params.dir) &&
-      this.deps.allowMutatingManagementActions !== false
-    );
-  }
-  private includeRunHeader(params: SubagentParamsLike): boolean {
-    const id = params.id ?? params.runId;
-    if (id === undefined || id.length === 0) {
-      return true;
-    }
-    return present(params.dir) || !resolveOwnedRun(this.deps.state, id);
-  }
-  private async inspectStatus(
-    params: SubagentParamsLike,
-    includeRunHeader: boolean,
-  ): Promise<SubagentExecutionResult> {
-    const scope = {
-      state: this.deps.state,
-      nested: nestedResolutionScopeForExecutor(this.deps),
-      includeRunHeader,
-    };
-    let inspected = inspectSubagentStatus({ ...params, action: "status" }, scope);
-    const targets = inspected.details.intercomTargets ?? [];
-    if (inspected.isError !== true && targets.length > 0) {
-      const intercomHealth = await queryLiveIntercomHealth(this.deps.pi.events, targets);
-      if (intercomHealth.size > 0) {
-        inspected = inspectSubagentStatus(
-          { ...params, action: "status" },
-          { ...scope, intercomHealth },
-        );
-      }
-    }
-    return inspected;
-  }
-  private statusFallback(
-    id: string | undefined,
-    inspected: SubagentExecutionResult,
-  ): SubagentExecutionResult | undefined {
-    const first = inspected.content.at(0);
-    if (
-      !present(id) ||
-      inspected.isError !== true ||
-      first?.type !== "text" ||
-      !first.text.startsWith("Async run not found.")
-    ) {
-      return;
-    }
-    try {
-      const remembered = resolveRememberedForegroundRun(id, this.deps.state);
-      return remembered
-        ? rememberedForegroundStatusResult(
-            remembered,
-            nestedResolutionScopeForExecutor(this.deps) !== undefined,
-          )
-        : undefined;
-    } catch (error) {
-      return failure(error);
-    }
-  }
-  private appendForegroundStatuses(inspected: SubagentExecutionResult): SubagentExecutionResult {
-    const foreground = [...(this.deps.state.foregroundRuns?.values() ?? [])]
-      .sort((left, right) => right.updatedAt - left.updatedAt)
-      .map((run) => rememberedForegroundStatusResult(run));
-    if (foreground.length === 0) {
-      return inspected;
-    }
-    return {
-      ...inspected,
-      content: [...foreground.flatMap((result) => result.content), ...inspected.content],
-      details: {
-        ...inspected.details,
-        managementControls: [
-          ...foreground.flatMap((result) =>
-            result.details.managementControl ? [result.details.managementControl] : [],
-          ),
-          ...(inspected.details.managementControls ?? []),
-        ],
-      },
-    };
-  }
-  private resolveControlRun(params: SubagentParamsLike): ResolvedSubagentRunId | undefined {
-    const id = params.runId ?? params.id;
-    return id !== undefined && id.length > 0
-      ? resolveSubagentRunId(id, {
-          state: this.deps.state,
-          nested: nestedResolutionScopeForExecutor(this.deps),
-        })
-      : undefined;
-  }
-  private extend(params: SubagentParamsLike): SubagentExecutionResult {
-    try {
-      const resolved = this.resolveControlRun(params);
-      return extendAsyncTimeoutResult(
-        this.deps.state,
-        resolved?.id ?? params.runId ?? params.id,
-        params.extendMs ?? params.timeoutMs ?? params.maxRuntimeMs ?? 0,
-      );
-    } catch (error) {
-      return failure(error);
-    }
-  }
-  private interrupt(
-    params: SubagentParamsLike,
-  ): Promise<SubagentExecutionResult> | SubagentExecutionResult {
-    let resolved: ResolvedSubagentRunId | undefined;
-    try {
-      resolved = this.resolveControlRun(params);
-    } catch (error) {
-      return failure(error);
-    }
-    if (resolved?.kind === "nested") {
-      return interruptNestedRun(resolved, params.index);
-    }
-    return (
-      interruptAsyncRun(
-        this.deps.state,
-        resolved?.kind === "async" ? resolved.id : (params.runId ?? params.id),
-        params.index,
-      ) ?? failure("No interrupt-capable run found in this session.")
-    );
-  }
-  private manageAgent(
-    call: ManagementInvocation,
-  ): Promise<SubagentExecutionResult> | SubagentExecutionResult {
-    const action = call.params.action ?? "";
-    if (!SUBAGENT_ACTIONS.some((candidate) => candidate === action)) {
-      return failure(`Unknown action: ${action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}`);
-    }
-    if (
-      this.deps.allowMutatingManagementActions === false &&
-      MUTATING_MANAGEMENT_ACTIONS.has(action)
-    ) {
-      return failure(`Action '${action}' is not available from child-safe subagent fanout mode.`);
-    }
-    return handleManagementAction(action, call.params, { ...call.ctx, cwd: call.requestCwd });
-  }
-}

package/src/runs/foreground/nested-control.ts

@@ -1,248 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { writeAsyncInterruptRequest } from "../background/async-control.ts";
-import type { ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
-import {
-  readNestedControlResults,
-  resolveNestedAsyncDir,
-  writeNestedControlRequest,
-  type NestedControlResultRecord,
-} from "../shared/nested-events.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { buildManagementControl, formatRunAction } from "../../shared/status-format.ts";
-import { errorMessage } from "../../shared/unknown.ts";
-import { deliverSubagentIntercomMessageEvent } from "../../intercom/result-intercom.ts";
-import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
-import type {
-  ReadonlyInput,
-  ReadonlyAsyncStatus,
-  SubagentExecutionResult,
-} from "../../shared/types.ts";
-
-export type NestedTarget = Extract<
-  ReadonlyInput<ResolvedSubagentRunId>,
-  { readonly kind: "nested" }
->;
-export const LIVE_ACCEPTANCE_OVERRIDE_NOTICE =
-  "Acceptance override applies only to revive and was not applied to this live delivery.";
-function failure(text: string): SubagentExecutionResult {
-  return {
-    content: [{ type: "text", text }],
-    isError: true,
-    details: { mode: "management", results: [] },
-  };
-}
-async function waitForControl(
-  target: NestedTarget,
-  requestId: string,
-): Promise<NestedControlResultRecord | undefined> {
-  const deadline = Date.now() + 1_000;
-  while (Date.now() < deadline) {
-    const result = readNestedControlResults(target.match.route).find(
-      (candidate) =>
-        candidate.requestId === requestId && candidate.targetRunId === target.match.run.id,
-    );
-    if (result) {
-      return result;
-    }
-    // A response must be observed before the next poll; parallel polls cannot advance this deadline.
-    // oxlint-disable-next-line no-await-in-loop
-    await new Promise<void>((resolve) => {
-      setTimeout(resolve, 50);
-    });
-  }
-  return;
-}
-async function sendControl(
-  target: NestedTarget,
-  action: "interrupt" | "resume",
-  message?: string,
-  index?: number,
-): Promise<NestedControlResultRecord | undefined> {
-  const requestId = randomUUID();
-  const child = target.match.run.path.at(0)?.stepIndex ?? target.match.run.parentStepIndex;
-  writeNestedControlRequest(target.match.route, {
-    ts: Date.now(),
-    requestId,
-    targetRunId: target.match.run.id,
-    ...(child !== undefined ? { targetChildIndex: child } : {}),
-    action,
-    ...(index !== undefined ? { index } : {}),
-    ...(message !== undefined && message.length > 0 ? { message } : {}),
-  });
-  return waitForControl(target, requestId);
-}
-function observedAsyncOwner(
-  target: NestedTarget,
-): { readonly dir: string; readonly status: ReadonlyAsyncStatus } | undefined {
-  const dir = resolveNestedAsyncDir(target.match.rootRunId, target.match.run);
-  if (dir === undefined || dir.length === 0) {
-    return;
-  }
-  const status = readStatus(dir);
-  return status && status.runId === target.match.run.id && status.state === "running"
-    ? { dir, status }
-    : undefined;
-}
-function supportsSelectedStop(status: ReadonlyAsyncStatus, index: number | undefined): boolean {
-  return index === undefined || status.indexedControl === true || (status.steps?.length ?? 0) <= 1;
-}
-function directInterrupt(
-  target: NestedTarget,
-  index?: number,
-): SubagentExecutionResult | undefined {
-  const run = target.match.run;
-  const observed = observedAsyncOwner(target);
-  if (!observed || !supportsSelectedStop(observed.status, index)) {
-    return;
-  }
-  const { dir, status } = observed;
-  if (index !== undefined && status.steps?.[index]?.status !== "running") {
-    return failure(`No running nested child at index ${index}. No siblings were stopped.`);
-  }
-  try {
-    writeAsyncInterruptRequest(dir, run.id, index);
-    return {
-      content: [{ type: "text", text: `Interrupt requested for nested async run ${run.id}.` }],
-      details: {
-        mode: "management",
-        results: [],
-        managementControl: buildManagementControl({
-          state: "live",
-          runId: run.id,
-          intercomTarget: run.intercomTarget ?? run.leafIntercomTarget,
-          canInterrupt: true,
-        }),
-      },
-    };
-  } catch (error) {
-    return failure(`Failed to interrupt nested async run ${run.id}: ${errorMessage(error)}`);
-  }
-}
-function terminalInterrupt(target: NestedTarget): SubagentExecutionResult | undefined {
-  const run = target.match.run;
-  if (run.state === "complete") {
-    return failure(`Nested run ${run.id} is already complete and cannot be interrupted.`);
-  }
-  if (run.state === "failed") {
-    return failure(`Nested run ${run.id} has failed and cannot be interrupted.`);
-  }
-  if (run.state === "paused") {
-    return failure(`Nested run ${run.id} is already paused.`);
-  }
-  return;
-}
-function selectedStopUnavailable(
-  target: NestedTarget,
-  index: number | undefined,
-): SubagentExecutionResult | undefined {
-  if (index === undefined || target.match.run.indexedControl === true) {
-    return;
-  }
-  return (
-    directInterrupt(target, index) ??
-    failure(
-      "This nested owner does not advertise selected-child stop. No stop was sent; inspect the child or explicitly stop the whole run.",
-    )
-  );
-}
-export async function interruptNestedRun(
-  target: NestedTarget,
-  index?: number,
-): Promise<SubagentExecutionResult> {
-  const terminal = terminalInterrupt(target);
-  if (terminal) {
-    return terminal;
-  }
-  const run = target.match.run;
-  const unsupported = selectedStopUnavailable(target, index);
-  if (unsupported) {
-    return unsupported;
-  }
-  const result = await sendControl(target, "interrupt", undefined, index);
-  if (result?.ok === true) {
-    return {
-      content: [{ type: "text", text: result.message }],
-      details: {
-        mode: "management",
-        results: [],
-        managementControl: buildManagementControl({
-          state: "live",
-          runId: run.id,
-          intercomTarget: run.intercomTarget ?? run.leafIntercomTarget,
-          canResume: true,
-          canInterrupt: true,
-        }),
-      },
-    };
-  }
-  return (
-    directInterrupt(target, index) ??
-    failure(
-      result?.message ??
-        `Nested run ${run.id} owner is not reachable and no safe direct async interrupt fallback is available.`,
-    )
-  );
-}
-interface LiveResumeInput {
-  readonly target: NestedTarget;
-  readonly message: string;
-  readonly index?: number;
-  readonly acceptanceOverrideSupplied: boolean;
-  readonly pi: ReadonlyInput<Pick<ExtensionAPI, "events">>;
-  readonly childSafe: boolean;
-}
-function liveResult(message: string, override: boolean): SubagentExecutionResult {
-  return {
-    content: [
-      { type: "text", text: override ? `${message}\n${LIVE_ACCEPTANCE_OVERRIDE_NOTICE}` : message },
-    ],
-    details: { mode: "management", results: [] },
-  };
-}
-function directResumeTarget(input: LiveResumeInput): string | undefined {
-  const run = input.target.match.run;
-  if (input.index === undefined) {
-    return run.leafIntercomTarget ?? run.intercomTarget;
-  }
-  const dir = resolveNestedAsyncDir(input.target.match.rootRunId, run);
-  const selected =
-    dir !== undefined && dir.length > 0 ? readStatus(dir)?.steps?.[input.index] : undefined;
-  return selected?.status === "running"
-    ? resolveSubagentIntercomTarget(run.id, selected.agent, input.index)
-    : undefined;
-}
-export async function resumeLiveNestedRun(
-  input: LiveResumeInput,
-): Promise<SubagentExecutionResult> {
-  const run = input.target.match.run;
-  const result = await sendControl(input.target, "resume", input.message, input.index);
-  if (result?.ok === true) {
-    return liveResult(result.message, input.acceptanceOverrideSupplied);
-  }
-  const direct = directResumeTarget(input);
-  if (direct !== undefined && direct.length > 0) {
-    const delivered = await deliverSubagentIntercomMessageEvent(
-      input.pi.events,
-      direct,
-      `Follow-up for nested run ${run.id}:\n\n${input.message}`,
-      500,
-      {
-        source: "nested-resume-fallback",
-        runId: run.id,
-        agent: run.agent,
-        index: input.index ?? run.currentStep,
-      },
-    );
-    if (delivered) {
-      return liveResult(
-        `Delivered follow-up directly to live nested run ${run.id}.`,
-        input.acceptanceOverrideSupplied,
-      );
-    }
-  }
-  return failure(
-    result?.message ??
-      `Nested run ${run.id} appears live but its owner route is not reachable. Wait for completion, then retry ${formatRunAction("resume", run.id, { message: "..." }, input.childSafe)}.`,
-  );
-}