export interface McpServerRef {
    name: string;
    url?: string;
    command?: string;
    args?: string[];
}
/** Reasoning effort for the agent's model (Opus 4.x / Fable). Higher = more thinking. */
export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
/**
 * Capability tier for an agent — how much it can reach beyond a bare prompt.
 *
 * - `constrained` (default): pure brain. No tools, no MCP, no skills. It decides/drafts; a
 *   deterministic `task.http` node does any write. Use for tightly-controlled steps (routing).
 * - `surface`: may use its MCP servers (e.g. Atlassian) to read AND write — but no filesystem/
 *   bash tools and no skills. Use for agents that create/update Jira/Confluence directly.
 * - `full`: a Claude Code session — project + user skills/plugins (gstack, superpowers), all
 *   built-in tools, and MCP. Use for skill-driven planning and coding agents (e.g. refine).
 *
 * For `surface`/`full`, dry-run is still enforced: a permission callback blocks + logs every
 * write tool/MCP call (allowing reads), so capable agents stay testable.
 */
export type AgentProfile = "constrained" | "surface" | "full";
export type SettingSource = "user" | "project" | "local";
/**
 * Declared capabilities for a capable (`full`) agent — what plugins/skills/commands it can reach.
 *
 * This is **config**, not an assumption about the operator's `~/.claude`: plugin paths are
 * resolved against the project dir (so capabilities can be vendored into the repo) and the engine
 * sets the SDK options explicitly. A plugin bundles its commands + skills + agents + hooks.
 */
export interface Capabilities {
    /** Local plugins to load. `path` is resolved relative to the project dir if not absolute. */
    plugins?: Array<{
        path: string;
    }>;
    /** Which skills to enable: `'all'` or a curated list (matches the SDK `skills` filter). */
    skills?: "all" | string[];
    /** Which settings tiers to load (`.claude/…`). Omitted → user+project; `[]` → isolated. */
    settingSources?: SettingSource[];
}
export interface AgentRunInput {
    prompt: string;
    model?: string;
    /** Reasoning effort for this run. Falls back to the project default, then the model's own default. */
    effort?: EffortLevel;
    mcpServers?: McpServerRef[];
    context: Record<string, unknown>;
    /**
     * When set, the agent must return a JSON object matching this JSON Schema —
     * a structured *decision* (e.g. which allowlisted action to take). The parsed
     * object is returned as `AgentResult.data`. This is how an agent recommends an
     * action without executing one: a deterministic node dispatches on the result.
     */
    decisionSchema?: Record<string, unknown>;
    /** Capability tier (default `constrained`). */
    profile?: AgentProfile;
    /** When true, the permission callback blocks + logs write tools/MCP calls (capable agents). */
    dryRun?: boolean;
    /** Working dir for a `full` agent (project skill/`.claude` resolution). Defaults to process.cwd().
     *  Also the base for resolving relative capability plugin paths. */
    cwd?: string;
    /** Declared plugins/skills/settingSources for a `full` agent (config, not env-assumed). */
    capabilities?: Capabilities;
    /** Optional sink for permission/dry-run log lines (e.g. the engine logger). */
    log?: (message: string) => void;
    /** Optional live feed of what the agent is doing — its reasoning, tool/MCP calls, and results. */
    onActivity?: (activity: AgentActivity) => void;
}
/** One step of an agent's work, streamed live so the dashboard can show what it's actually doing. */
export interface AgentActivity {
    /** text = a chunk of the agent's reply; thinking = its reasoning; tool_use = a tool/MCP call it made;
     *  tool_result = what that call returned. */
    kind: "text" | "thinking" | "tool_use" | "tool_result";
    /** The text for text/thinking, or a short preview for a tool_result. */
    text?: string;
    /** Tool/MCP name for a tool_use (e.g. "mcp__atlassian__editJiraIssue"). */
    tool?: string;
    /** Tool input for a tool_use (capped). */
    input?: unknown;
}
/** Token usage + cost for one agent run (summed across the SDK result messages it produced). */
export interface RunUsage {
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
    cacheCreationTokens: number;
    /** input + output + cache (read+creation) — the headline number. */
    totalTokens: number;
    /** Anthropic's own cost estimate for the run, in USD. */
    costUsd: number;
}
/** One claude.ai plan rate-limit window: how much of it is used + when it resets. */
export interface PlanWindow {
    /** Percentage of the window used, 0–100 (null when unknown). */
    utilization: number | null;
    /** ISO 8601 timestamp when the window resets (null when unknown). */
    resetsAt: string | null;
}
/** Claude.ai plan usage: session cost + the rolling rate-limit windows, for the spend/balance box. */
export interface PlanUsage {
    /** False for API-key / Bedrock / Vertex sessions (rate limits don't apply) — windows are null. */
    available: boolean;
    /** 'pro' | 'max' | 'team' | 'enterprise' | null (null for non-subscription sessions). */
    subscriptionType?: string | null;
    /** Accumulated cost of the probe session (USD). */
    sessionCostUsd?: number;
    /** 5-hour ("session") window. */
    fiveHour?: PlanWindow | null;
    /** 7-day ("weekly") window. */
    sevenDay?: PlanWindow | null;
    /** When this snapshot was taken (ms epoch). */
    fetchedAt: number;
}
export interface AgentResult {
    text: string;
    data?: unknown;
    /** Skills the agent actually invoked this run (observed from `Skill` tool_use) — for provenance. */
    skillsUsed?: string[];
    /** All tools/MCP the agent invoked this run (observed) — e.g. `mcp__atlassian__editJiraIssue`. */
    toolsUsed?: string[];
    /** Token usage + cost for this run (from the SDK result message). */
    usage?: RunUsage;
}
export interface AgentRunner {
    run(input: AgentRunInput): Promise<AgentResult>;
    /** Best-effort claude.ai plan usage (session + weekly windows). Returns null when unavailable
     *  (API-key session, the experimental SDK call fails, or no runner support). */
    getPlanUsage?(): Promise<PlanUsage | null>;
}