Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

7.4 KB
Raw Blame
/**
 * Stop hooks — functions the Session runs after every Task of one `run` call, at the
 * **stop** hook point: the moment a Task ends (the model's final reply with no tool call,
 * or a cutoff — user abort, LLM failure, the max_turns cap).
 *
 * A hook is told only where to look — the Session id and the Trace file being written —
 * and derives everything else (token usage, turn counts, how the Task ended, its own state
 * files) from the Trace. It answers with a decision: `continue` keeps the run going — the
 * hook's `input` becomes the next Task's user message, inside the same `run` call — while
 * `stop` (or no answer at all) lets the run end. It may also ask for a background subagent
 * (`subagent`), which the Session spawns detached and records by session id. Every non-void
 * answer is recorded as one `hook` event message, streamed and written to the Trace; the
 * injected input is not in the event, it is the user message that follows it. The first
 * `continue` wins; the Session refuses to continue after a cutoff or once its signal is
 * aborted (the answer is still recorded). A hook that throws is recorded with the error as
 * its reason and treated as having no opinion, so a broken hook never takes the run down.
 *
 * Hooks installed into an Agent's `agent_state/hooks/` are scripts run through
 * script-hook.ts; the in-process interface here is what SDK embedders and tests register
 * directly. The loop that consults them is `Session.run`.
 * Docs: /docs/agent-loop § "Stop hooks".
 */
import { hookEvent } from "../omnimessage/index.js";
import type { OmniMessage } from "../omnimessage/index.js";
import type { ApproveFn } from "../interfaces/index.js";
import { errorMessage, failedAnswer } from "./answer.js";
import type { PreToolUseHook } from "./tool-hook.js";
import type { UserPromptHook } from "./prompt-hook.js";

/** What a stop hook is told: where the Session's record is. */
export interface StopHookInput {
  sessionId: string;
  /**
   * Absolute path of the Trace file the Session is writing right now — the current context
   * segment (compaction rotates to a new file). Absent for a Session without a Trace.
   */
  tracePath?: string;
  /** The run's abort signal. */
  signal?: AbortSignal;
}

/** A background subagent a hook asks for: spawned detached, its first user message being `prompt`. */
export interface HookSubagentRequest {
  prompt: string;
  /** The child Agent's id; omitted = the Session's own Agent. */
  agentId?: string;
}

/** A stop hook's answer; `undefined` (no answer) means "no opinion, nothing to record". */
export interface StopHookResult {
  /** `continue` keeps the run going with `input` as the next Task's user text; `stop` lets it end. Omitted: the hook only leaves a record. */
  decision?: "continue" | "stop";
  /** With `continue`: the next Task's user input text (a `continue` without one cannot continue and is recorded as-is). */
  input?: string;
  /** One line for people — the `hook` event carries it (hosts render it). */
  reason?: string;
  /** The hook's own structured record, scalars only — the `hook` event carries it for hosts and the Trace. */
  output?: Record<string, string | number | boolean>;
  /** Work to hand off: a detached background child Session; its session id joins `output` as `session_id`. */
  subagent?: HookSubagentRequest;
}

/** A named stop hook. The name identifies its `hook` events (e.g. `goal`, `continual-learning`). */
export interface StopHook {
  name: string;
  run(input: StopHookInput): Promise<StopHookResult | void>;
}

/**
 * What honoring a subagent request yields: the child's session id, and its origin-stamped
 * `session_meta` for the parent stream — the record a host registers a child session from
 * (the server gives it a session row and lists it with the other subagent sessions), so the
 * id on the event leads somewhere. Null when the runner's handle predates the upfront-meta
 * seam.
 */
export interface HookSubagentSpawned {
  sessionId: string;
  meta: OmniMessage | null;
}

/** Spawns the background child Session a hook asked for; `approve` is the run's approval callback, which the child inherits. */
export type HookSubagentSpawner = (
  request: HookSubagentRequest,
  approve?: ApproveFn,
) => Promise<HookSubagentSpawned>;

/** The hooks a Session is built with (`SessionConfig.hooks`): one list per hook point, plus the spawner hook answers may need. */
export interface SessionHooks {
  stop?: StopHook[];
  /** Consulted by the engine before each tool call's approval (see tool-hook.ts). */
  preToolUse?: PreToolUseHook[];
  /** Consulted every time the user submits a Prompt; the ones marked `trigger: "host"` run only through `Session.runUserPromptHook` (see prompt-hook.ts). */
  userPrompt?: UserPromptHook[];
  /** How a `subagent` answer is honored; without it the request is recorded as unhonored. */
  spawnSubagent?: HookSubagentSpawner;
}

/**
 * What one pass over the stop hooks produced: the messages to record and stream, in order,
 * and the first `continue`'s input (null = the run ends). Behind a hook's `hook` event comes
 * the origin-stamped session_meta of a child it spawned — stream material only (the Trace
 * writer drops origin-stamped messages, as it does for a tool-spawned child's). The parent
 * Trace keeps no pointer to the child: a hook's child is detached by design, out of the
 * parent's nested subagent view; the event's `output.session_id` is its record there.
 */
export interface StopHooksOutcome {
  events: OmniMessage[];
  next: string | null;
}

/**
 * Runs the stop hooks in registration order and turns every non-void answer into a `hook`
 * event. The first `continue` that carries an input decides the continuation; later ones are
 * recorded but not honored. A `subagent` request is handed to `spawn` and the child's session
 * id recorded on the event (`output.session_id`), with the child's session_meta following the
 * event; a failed spawn, or no spawner, is recorded in the reason. A throwing hook is
 * recorded with the error as its reason.
 */
export async function runStopHooks(
  hooks: readonly StopHook[],
  input: StopHookInput,
  spawn?: (request: HookSubagentRequest) => Promise<HookSubagentSpawned>,
): Promise<StopHooksOutcome> {
  const events: OmniMessage[] = [];
  let next: string | null = null;
  for (const hook of hooks) {
    let result: StopHookResult | void;
    try {
      result = await hook.run(input);
    } catch (err) {
      result = failedAnswer(err);
    }
    if (!result) continue;
    if (result.decision === "continue" && next === null && result.input) next = result.input;
    let output = result.output;
    let reason = result.reason;
    const childRecords: OmniMessage[] = [];
    if (result.subagent) {
      if (!spawn) {
        reason = `${reason ? `${reason} · ` : ""}subagent not spawned: no spawner`;
      } else {
        try {
          const child = await spawn(result.subagent);
          output = { ...output, session_id: child.sessionId };
          if (child.meta) childRecords.push(child.meta);
        } catch (err) {
          reason = `${reason ? `${reason} · ` : ""}subagent not spawned: ${errorMessage(err)}`;
        }
      }
    }
    events.push(
      hookEvent({
        hook: "stop",
        name: hook.name,
        ...(result.decision !== undefined ? { decision: result.decision } : {}),
        ...(reason !== undefined ? { reason } : {}),
        ...(output !== undefined ? { output } : {}),
      }),
      ...childRecords,
    );
  }
  return { events, next };
}