A local-first multi-agent app development platform, built on PenguinHarness
/**
* 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[];
}