Skip to content

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

6.7 KB
Raw Blame
/**
 * Vocabulary both sides of the engine share.
 *
 * These are the types that resist the LLM/Environment split because both contracts genuinely
 * need them: the tool schema Environment produces and the LLM consumes, the thinking level a
 * Session sets and both a request and a spawned child carry, and the approval callback that
 * touches all three boundaries (Human answers it, the engine calls it, Environment forwards
 * it to derived sessions).
 *
 * Docs: packages/docs/content/interfaces.{zh,en}.md (site path /docs/interfaces).
 */
import type {
  ApprovalDecision,
  ErrorCode,
  OmniMessage,
  ToolCallPayload,
} from "../omnimessage/types.js";

// ToolDefinition is defined in omnimessage/types.ts (the tool_list_ready event carries the full tool schema); re-exported here to keep the original import path.
export type { ToolDefinition } from "../omnimessage/types.js";

/** Thinking level of one request. Shared: the LLM takes it per request and as a construction default, and a spawned child Session inherits or overrides it. */
export type ThinkingLevelName = "none" | "low" | "medium" | "high" | "xhigh" | "max";

/**
 * How a run was cut off early, returned as the **return value** of the run generators
 * (`ContextEngine.run` / `Session.run` / `SubagentHandle.run`): `null` means the run ran
 * to completion. The engine knows which exit it took, so consumers that must not treat a
 * cut-off run as finished (the goal hook deciding whether to re-fire a round, a subagent
 * round reporting completion) read this instead of re-deriving it from the stream —
 * failures emit no abort event, only their terminal request_end / compaction_end records.
 * `abort` is a user interruption; `llm_failure` a terminal LLM request failure;
 * `compaction_failure` a compaction given up mid-task (at a Task boundary the same
 * failure is advisory and the run returns null); `max_turns` the Task's turn cap — the
 * engine closes the Task with its own notice and holds the pending input as carry-over for
 * the next run. The error pair mirrors the terminal record's `error_code` / `error_message`
 * (none for `max_turns`).
 */
export interface RunCutoff {
  kind: "abort" | "llm_failure" | "compaction_failure" | "max_turns";
  errorCode?: ErrorCode;
  errorMessage?: string;
}

/**
 * Per-tool approval callback: the Human boundary gives allow/deny for each complete `tool_call`.
 * `context_engine` calls it once per tool call within a turn. Subagents forward the parent's
 * approval callback, so the child Agent **inherits the parent Agent's approval mode**.
 * The third decision, `"forbidden"`, is never a host's answer: `Session.run` wraps the
 * injected callback with the project sandbox command policy (see {@link CommandPolicyConfig}),
 * and a vetoed call answers `"forbidden"` without the wrapped callback being consulted.
 * Docs: /docs/interfaces § "ApproveFn".
 */
export type ApproveFn = (toolCall: OmniMessage<ToolCallPayload>) => Promise<ApprovalDecision>;

/**
 * What one pass over the pre-tool-use hooks produced, handed to `context_engine` by the
 * Session-wired {@link PreToolUseFn}: the `hook` events to record (every non-void answer,
 * in hook order), and the first decision — `"deny"` refuses the call without consulting the
 * approval callback, `"allow"` approves it the same way (the project command policy still
 * outranks an allow: the Session downgrades a policy-vetoed allow to `null` before the
 * engine sees it), `null` leaves the call to the normal approval boundary. `name` / `reason`
 * are the deciding hook's, for the denied output line the model reads.
 */
export interface PreToolUseOutcome {
  events: OmniMessage[];
  decision: "allow" | "deny" | null;
  name?: string;
  reason?: string;
}

/**
 * Pre-tool-use hook consult: called by `context_engine` once per complete `tool_call`,
 * BEFORE the approval callback. Wired by the Session from the Agent's installed hook
 * packages (`hooks.json` `pre_tool_use` commands); absent when none are installed, and the
 * engine then goes straight to approval.
 * Docs: /docs/agent-loop § "Hooks".
 */
export type PreToolUseFn = (
  toolCall: OmniMessage<ToolCallPayload>,
) => Promise<PreToolUseOutcome | null>;

/**
 * What one pass over the user-prompt hooks produced, handed to `context_engine` by the
 * Session-wired {@link UserPromptFn}: the records in hook order — one harness-stamped user
 * text per non-empty `context` a hook answered, one `hook` event per hook that failed. The
 * engine yields and writes them right behind the Prompt; the user texts join the Task's
 * first request input.
 */
export interface UserPromptOutcome {
  records: OmniMessage[];
}

/**
 * User-prompt hook consult: called by `context_engine` once at the start of a run, after
 * the Prompt is written and before the first request, with the run's new input. Wired by
 * the Session from the Agent's installed hook packages (`hooks.json` `user_prompt`
 * commands); answers null when the input carries no text of the user's own or no hook is
 * due, and the engine then sends the Prompt as it is.
 * Docs: /docs/agent-loop § "User-prompt hooks".
 */
export type UserPromptFn = (
  input: OmniMessage[],
  signal?: AbortSignal,
) => Promise<UserPromptOutcome | null>;

/**
 * One command-policy deny rule — plain project-editable data: a name (identifies the rule
 * in the settings UI), a regex source tested against the whitespace-normalized command, an
 * optional free-text description, and a per-rule switch.
 * Docs: /docs/configuration § "Command policy".
 */
export interface CommandPolicyRule {
  name: string;
  /** JavaScript regex source (no flags). */
  pattern: string;
  /** What the rule catches (free text, shown in the settings UI). */
  description?: string;
  /** Per-rule switch; absent = true. */
  enabled?: boolean;
}

/**
 * The project sandbox command policy (the `[command_policy]` block of
 * `.project_config.toml`, threaded into every Session the Agent creates). `Session.run`
 * wraps the injected approval callback with it, so a hit is denied without the human being
 * asked — under every approval mode. It is Project-owned security config, deliberately
 * outside Agent State so the Agent cannot rewrite it. The factory rule set is seeded into
 * new projects like model presets (copied at creation, never rewritten); an absent config
 * or an absent `rules` list means the factory set applies, and `enabled: false` switches
 * the whole policy off. An accident guardrail, not a security boundary — see
 * internal/command-policy.ts for what walks past it.
 * Docs: /docs/configuration § "Command policy".
 */
export interface CommandPolicyConfig {
  /** Master switch; absent = true. */
  enabled?: boolean;
  /** The deny-rule list, evaluated in order; absent = the factory set (a stored empty list means no rules). */
  rules?: CommandPolicyRule[];
}