jev-planner 0.0.1 → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,566 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+//#region ../core/dist/index.d.mts
+//#region src/doctor/doctor.types.d.ts
+interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+//#endregion
+//#region src/provider/provider.types.d.ts
+type Env = Readonly<Record<string, string | undefined>>;
+/** What the planner factory hands a provider when it builds an agent for a run. */
+interface AgentSetup {
+  /**
+   * The agent's name in the run, for a provider used more than once:
+   * `--agents codex:sol` or the config's `agents.sol`. The provider's `id` otherwise.
+   */
+  name?: string;
+  /** How prompts, stages and the judge refer to it. `agentLabel` otherwise. */
+  label?: string;
+  /** A model from `--model <name>=<model>` or the config's `agents.<name>.model`; the provider's default otherwise. */
+  model?: string;
+  /** A reasoning effort from `--effort <name>=<level>` or the config; only for a provider whose `effort` is true. */
+  effort?: string;
+  /** Every provider's secret variables, and the judge's: never passed to an agent subprocess. */
+  omitEnv: readonly string[];
+  env: Env;
+  /** Replaces the global `fetch`; for tests. */
+  fetch?: typeof fetch;
+}
+/**
+ * One AI the planner can plan with. Build one with `cliProvider` or
+ * `openAICompatibleProvider` and add it to `PROVIDERS` in `providers.ts`.
+ */
+interface Provider {
+  /**
+   * Lowercase, what `--agents` takes, and a key of the config's `agents`. An
+   * agent's name defaults to it; a second agent of the same provider is named
+   * (`--agents codex:sol,codex:terra`), and `--model` and `--finalizer` take
+   * the name.
+   */
+  readonly id: string;
+  readonly label: string;
+  /** `cli` agents read the repository themselves; `api` agents get a snapshot of it. */
+  readonly kind: 'cli' | 'api';
+  /** Variables holding this provider's credentials, stripped from every agent subprocess. */
+  readonly secretEnv: readonly string[];
+  /** Whether it takes a reasoning effort, from `--effort` or the config's `agents.<id>.effort`. */
+  readonly effort: boolean;
+  create(setup: AgentSetup): PlanningAgent;
+  /** Local checks only: `doctor` never makes a paid call. */
+  doctor(cwd: string, env: Env): Promise<CheckResult[]>;
+}
+interface CliProviderConfig {
+  id: string;
+  label: string;
+  command: string;
+  /**
+   * Arguments for one read-only, non-interactive run that reads the prompt on
+   * stdin and prints the answer on stdout. `model` and `effort` are the
+   * overrides for this run; each is set only when given, and wins over the
+   * CLI's own configuration.
+   */
+  args: (overrides: {
+    model?: string;
+    effort?: string;
+  }) => string[];
+  /** Whether `args` passes an effort on, so `--effort` is accepted for it. */
+  effort?: boolean;
+  /**
+   * For a CLI whose `args` make it print its work as one JSON event per stdout
+   * line: what one event means. `progress` is shown while the agent works, and
+   * the last `result` any event gives is the answer. A line that is not JSON is
+   * shown as it is. Without `events`, stdout is the answer; either way, each
+   * stderr line is progress.
+   */
+  events?: (event: unknown) => {
+    progress?: string;
+    result?: string;
+    session?: string;
+  };
+  /**
+   * For a CLI that can keep a conversation and continue it in a later call:
+   * the arguments for each. Used when the request carries an `AgentSession`;
+   * `args` otherwise. Both keep the run read-only, like `args`.
+   */
+  sessions?: {
+    /**
+     * The first call, keeping its conversation. `id` is a fresh UUID for a CLI
+     * that lets the caller name the session; a CLI that names its own reports
+     * the name as an event's `session`.
+     */
+    start: (overrides: {
+      model?: string;
+      effort?: string;
+    }, id: string) => string[];
+    /** A later call, continuing the conversation `id`, with the prompt on stdin. */
+    resume: (overrides: {
+      model?: string;
+      effort?: string;
+    }, id: string) => string[];
+  };
+  /**
+   * How `doctor` checks the login: arguments to `command` that exit 0 when
+   * logged in, or a check of its own.
+   */
+  auth?: readonly string[] | ((cwd: string) => Promise<CheckResult>);
+}
+interface OpenAICompatibleConfig {
+  id: string;
+  label: string;
+  /** Up to, not including, `/chat/completions`. */
+  baseUrl: string;
+  /** The variable holding the API key. */
+  apiKeyEnv: string;
+  /** The model used when neither `--model` nor the config sets one. */
+  model: string;
+}
+/** An agent's name in a run: its provider id (`codex`, `claude`, …) unless named (`sol`). */
+type AgentName = string;
+/**
+ * One agent's conversation, carried from one stage of a run to the next. The
+ * planner creates one per agent per run and passes it on every call to that
+ * agent; the provider fills it in on the first call and continues from it on
+ * the next ones. An agent that ignores it starts every call afresh.
+ */
+interface AgentSession {
+  /** The conversation to continue, once a call has started one: a CLI's session or thread id. */
+  id?: string;
+}
+interface AgentRequest {
+  /** The whole prompt, for an agent that starts afresh. */
+  prompt: string;
+  /**
+   * The same request for an agent continuing `session`, which already holds
+   * the task and its own earlier plans: `prompt` without them. `prompt` is used
+   * when this is absent or the conversation cannot be continued.
+   */
+  resumePrompt?: string;
+  /** Continue this conversation, when the agent can; see `AgentSession`. */
+  session?: AgentSession;
+  /**
+   * A reasoning effort for this call only, over the one the agent was created
+   * with. An agent that takes no effort ignores it.
+   */
+  effort?: string;
+  cwd: string;
+  timeoutMs: number;
+  /** Called with a line about the agent's work as it happens: a message, a command, a file read. */
+  onProgress?: (line: string) => void;
+  /** Aborted when the run no longer needs this answer, so the agent stops working and stops billing. */
+  signal?: AbortSignal;
+}
+interface PlanningAgent {
+  /**
+   * Unique in a run: what `--finalizer`, the judge's verdict, objection ids and the
+   * rounds files use. Its provider id, unless named (`--agents codex:sol`).
+   */
+  readonly name: AgentName;
+  /**
+   * How prompts, stages, the plan and the judge refer to it: `Codex`, `DeepSeek`, or
+   * `Codex (sol)` for a named one. Keep labels unique too: the judge tells plans
+   * apart by label.
+   */
+  readonly label: string;
+  /**
+   * Whether the agent opens files in the repository itself, as an agent CLI
+   * does. Only such agents check disputed claims in `debate` review; an agent
+   * that leaves this out is treated as one that does not.
+   */
+  readonly readsRepository?: boolean;
+  generate(request: AgentRequest): Promise<string>;
+}
+//#endregion
+//#region src/debate/debate.types.d.ts
+/** One objection a critic raised against another agent's plan, in `debate` review. */
+interface Objection {
+  /** `<critic>:<target>:C<n>`, unique in a run: what the author's reply answers. */
+  id: string;
+  critic: AgentName;
+  /** The agent whose plan the objection is about. */
+  target: AgentName;
+  claim: string;
+  /** The critic's reason, or `''` when it gave none. */
+  why: string;
+  /** Whether the claim is about a file, symbol or export in the repository, and so can be checked. */
+  repo: boolean;
+}
+/** An author's answer to one objection against its plan. */
+interface Reply {
+  /** The `Objection.id` it answers. */
+  id: string;
+  author: AgentName;
+  decision: 'accept' | 'reject';
+  reason: string;
+}
+/** What an agent that reads the repository found when it checked a disputed claim. */
+interface ClaimCheck {
+  checker: AgentName;
+  /** `unknown` also stands for an answer that could not be parsed, or a checker that was dropped. */
+  result: 'confirm' | 'refute' | 'unknown';
+  /** Where the checker looked, such as `src/jev.ts:agentOptions`; `''` when it said nothing. */
+  evidence: string;
+}
+/**
+ * An objection its author rejected, for the judge to rule on. The same claim from
+ * several critics against the same plan is one dispute.
+ */
+interface Dispute {
+  /** `D1`, `D2`, …, in the order the disputes are ranked. */
+  id: string;
+  /** The author, whose plan the claim is about. */
+  target: AgentName;
+  /** Every critic who raised it, in the order they raised it. */
+  critics: AgentName[];
+  /** The ids of the objections it merges. */
+  objections: string[];
+  claim: string;
+  /** The critics' reasons, those that gave one. */
+  reasons: string[];
+  /** The author's reasons for rejecting it. */
+  rejections: string[];
+  repo: boolean;
+  /** Present once a claim check ran on it. */
+  check?: ClaimCheck;
+}
+/** The judge's ruling on one dispute. */
+interface DisputeRuling {
+  /** The `Dispute.id` it rules on. */
+  id: string;
+  /** Whose position holds; `unclear` when the material does not settle it. */
+  choice: 'critic' | 'author' | 'unclear';
+  confidence: number;
+}
+/** The debate behind a round, in `debate` review; see `PlanRound.debate`. */
+interface RoundDebate {
+  /** Every objection the critics raised, as parsed. */
+  objections: Objection[];
+  /** Every reply the authors gave that answers an objection, first reply per objection. */
+  replies?: Reply[];
+  /** The ids of objections that got no parseable reply, including those to a dropped author. */
+  unanswered?: string[];
+  /** The rejected objections the judge rules on: at most eight, ranked. */
+  disputes?: Dispute[];
+  /** Rejected objections past the cap, which the judge did not rule on. */
+  overflow?: Dispute[];
+  /** Whether claim checks ran, when they were asked for. */
+  claimChecks?: 'ran' | 'skipped';
+}
+//#endregion
+//#region src/questions/questions.types.d.ts
+type JudgeStage = 'solo' | 'draft' | 'review';
+/** The judge's answer on one set of plans. Every confidence and probability is from 0 to 1, every score from 0 to 3. */
+interface Verdict {
+  /** An agent's name, or `'tie'`. */
+  strongerPlan: string;
+  strongerPlanConfidence: number;
+  finalizer: AgentName;
+  finalizerConfidence: number;
+  completeness: number;
+  completenessConfidence: number;
+  feasibility: number;
+  feasibilityConfidence: number;
+  riskCoverage: number;
+  riskCoverageConfidence: number;
+  needsAnotherPassProbability: number;
+  /**
+   * How likely the strongest plan is already a final plan on its own. In `balanced`
+   * mode a cross-reviewed run above the threshold is answered with that plan
+   * rather than a synthesis call.
+   */
+  standsAloneProbability: number;
+  /** The judge's ruling on each dispute it was given, in `debate` review; absent when it was given none. */
+  disputes?: DisputeRuling[];
+  model: string;
+}
+/** One plan, for the judge: the agent that wrote it and the text. */
+interface JudgedPlan {
+  agent: AgentName;
+  label: string;
+  plan: string;
+}
+/**
+ * What rates a run's plans and routes it: which plan is stronger, who merges,
+ * whether another pass would help, and the rulings on a debate's disputes.
+ * The planner never calls a model for this itself; `TypeSafeJevJudge` in
+ * `jev-planner` is one judge.
+ */
+interface PlanJudge {
+  /** How the run's stage messages refer to the judge: `Jev`. */
+  readonly name: string;
+  judge(input: {
+    task: string;
+    plans: readonly JudgedPlan[];
+    /**
+     * `draft` for the independent drafts, `review` for plans that have been
+     * cross-reviewed, and `solo` for one draft judged alone in `fast` mode.
+     * A `solo` verdict's `strongerPlan` and `finalizer` can only name that
+     * agent or `tie`, and the planner ignores both.
+     */
+    stage: 'solo' | 'draft' | 'review';
+    /** In `debate` review, the rejected objections to rule on alongside the plans. */
+    disputes?: readonly Dispute[];
+    /** `PlanOptions.judgeModel`, when the run set one. */
+    model?: string;
+  }): Promise<Verdict>;
+}
+//#endregion
+//#region src/orchestrator/orchestrator.types.d.ts
+/**
+ * How much work a run spends before it answers.
+ *
+ * - `fast` answers with the first draft the judge rates 0.5 or more to stand alone,
+ *   and stops the agents still drafting. That plan is one agent's, which no
+ *   other agent has seen, and the quickest agent's draft is judged first, so it
+ *   has the first chance. When the judge accepts no draft, the drafts are merged with
+ *   no cross-review. It never cross-reviews.
+ * - `balanced` lets the judge cut the run short: it judges the drafts first and orders a
+ *   cross-review only when one would help, adopts a cross-reviewed plan that
+ *   already stands alone instead of paying for a merge, and stops waiting on a
+ *   straggling agent once the round has enough plans.
+ * - `ultra` always runs the first cross-review, a second when the judge asks for it,
+ *   and then merges, unless `selectStronger` keeps the reviewed plan the judge rates
+ *   stronger: 2N + 1 agent calls in three sequential rounds, or 3N + 1 in four.
+ */
+type PlanMode = 'fast' | 'balanced' | 'ultra';
+/**
+ * How the agents review each other once the judge orders a cross-review.
+ *
+ * - `standard` has each agent read every other plan and return a revised one.
+ * - `debate` (experimental) turns the first cross-review into an argument: each
+ *   agent lists its objections to every other plan, each author accepts or
+ *   rejects the objections it received and revises its plan, and the judge rules on
+ *   every objection an author rejected. A second pass, when the judge asks for one,
+ *   is aimed at the disagreements the judge's rulings left open.
+ */
+type ReviewMode = 'standard' | 'debate';
+interface PlanOptions {
+  task: string;
+  cwd: string;
+  timeoutMs: number;
+  /**
+   * `balanced` (the default) lets the judge skip work a run does not need; `ultra`
+   * never skips; `fast` answers with the first draft the judge accepts. See `PlanMode`.
+   */
+  mode?: PlanMode;
+  /** Cross-review rounds a run may spend; `balanced` runs only the ones the judge asks for, `fast` none. */
+  maxReviewRounds?: 0 | 1 | 2;
+  /** `standard` (the default) or `debate`; see `ReviewMode`. */
+  reviewMode?: ReviewMode;
+  /**
+   * In `debate` review, have an agent that reads the repository check each
+   * disputed claim about it before the judge rules. Needs two or more such agents;
+   * with fewer, the checks are skipped and the run says so. `false` by default.
+   * Neither this nor `reviewMode: 'debate'` is allowed in `fast` mode, which has no review.
+   */
+  claimChecks?: boolean;
+  /**
+   * How long a round waits for the agents still working once enough of them
+   * have answered, in `balanced` and `fast` mode. `0` waits for every agent, as `ultra` always
+   * does. A dropped agent's call is aborted, and a round never falls below two
+   * plans, so nothing is dropped that the round still needs.
+   */
+  stragglerGraceMs?: number;
+  /** The model the judge should use, passed to it as `model`; what that names is up to the judge. */
+  judgeModel?: string;
+  /**
+   * Override the judge's choice; must be the name of one of the planner's agents.
+   * In `fast` mode it only chooses who merges when the judge accepts no draft.
+   */
+  finalizer?: AgentName;
+  /**
+   * Skip the placeholder check `plan` runs before any agent call. An empty
+   * task is still passed through unchecked, as before the check existed.
+   */
+  allowAnyTask?: boolean;
+  /**
+   * Skip the synthesis when the judge rates one cross-reviewed plan stronger, and
+   * return that plan as it is, whatever `standsAloneProbability` says. Saves
+   * the last agent call at some cost in quality. On a tie, or when no
+   * cross-review ran, the finalizer still merges the plans. `false` by default.
+   * Ignored in `fast` mode, which never cross-reviews.
+   */
+  selectStronger?: boolean;
+  /**
+   * A reasoning effort for the cross-review and synthesis calls, by agent name:
+   * lower effort where the job is editing a plan rather than exploring. An
+   * agent not listed uses the effort it was created with in every stage.
+   */
+  reviewEfforts?: Readonly<Record<AgentName, string>>;
+  /**
+   * Keep each agent's conversation from its draft to its later calls, so the
+   * cross-review and synthesis continue with what it already read. `true` by
+   * default; `false` starts every call afresh.
+   */
+  resume?: boolean;
+  onStage?: (message: string) => void;
+  /** Called with each agent's progress lines while it works, as `AgentRequest.onProgress` gets them. */
+  onAgentProgress?: (agent: AgentName, line: string) => void;
+  /**
+   * Called with every round's plans as soon as the round ends, and awaited:
+   * a rejection stops the run. Rounds are numbered from 1 — the drafts, then
+   * each cross-review — and the final plan comes last.
+   */
+  onRound?: (round: PlanRound) => void | Promise<void>;
+}
+/** One round of a run, as `PlanOptions.onRound` sees it. */
+interface PlanRound {
+  /** 1 for the drafts, 2 and up for the cross-reviews; one more for the final plan. */
+  round: number;
+  /**
+   * `draft`, `review` and `final` in every run. A `debate` review adds
+   * `critique`, whose `plans` are the drafts unchanged, and then `review`; with
+   * claim checks, `reply` (the revised plans, not yet judged) and `check` (the
+   * same plans, judged) take the place of that `review`.
+   */
+  stage: 'draft' | 'critique' | 'reply' | 'check' | 'review' | 'final';
+  /** Each agent's plan in this round, by agent name; for `final`, the plan the run answers with. */
+  plans: Record<AgentName, string>;
+  /** In a `debate` review, each agent's raw answer in this round: its critique, reply or check. */
+  artifacts?: Record<AgentName, string>;
+  /** In a `debate` review, what the round's answers said, parsed. */
+  debate?: RoundDebate;
+  /** The judge's verdict on this round's plans, and the one the final plan followed. */
+  verdict?: Verdict;
+  /** How long the round took. */
+  timings: RoundTimings;
+  /**
+   * On the `final` round: the plan is one agent's own, adopted whole rather
+   * than merged. A `fast` run that accepts a draft still reports `draft`, then
+   * `final`.
+   */
+  selected?: true;
+}
+/** How long one round of a run took, in milliseconds. */
+interface RoundTimings {
+  /** The whole round: its agent calls, then the judge when it judged the round. */
+  totalMs: number;
+  /** Each agent call in the round that answered, by agent name; a dropped straggler has none. */
+  agents: Record<AgentName, number>;
+  /** The judge's call on the round's plans; in `fast` mode, every solo judgement in the round, added up. */
+  judgeMs?: number;
+}
+/** How long a whole run took, in milliseconds. */
+interface RunTimings {
+  totalMs: number;
+  /** One entry per round, in the order `onRound` receives them. */
+  rounds: (RoundTimings & Pick<PlanRound, 'round' | 'stage'>)[];
+}
+interface PlanResult {
+  plan: string;
+  verdict: Verdict;
+  /** The agent that merged the plans, or whose plan was adopted whole. */
+  finalizer: AgentName;
+  /**
+   * The plan is `finalizer`'s own plan, adopted whole rather than merged: in
+   * `balanced` mode when the judge judged it final as it stands, in `fast` mode when
+   * the judge accepted it as it arrived, or by `selectStronger`.
+   */
+  selected?: true;
+  /** Each agent's last plan, by agent name; in `fast` mode, only the drafts that arrived. */
+  drafts: Record<AgentName, string>;
+  /** The debate, in `debate` review once one ran: its objections, replies, disputes and checks. */
+  debate?: RoundDebate;
+  timings: RunTimings;
+  /** What the run actually cost, for reporting and for tuning the next one. */
+  cost: PlanCost;
+}
+/** What a finished run spent, and where it stopped short. */
+interface PlanCost {
+  mode: PlanMode;
+  reviewMode: ReviewMode;
+  /** Cross-review rounds run: `0` when the judge found the drafts ready as they were. */
+  reviewRounds: number;
+  /** Whether a synthesis call merged the plans, or one plan was adopted whole. */
+  synthesized: boolean;
+  /** Agent calls made, the synthesis included. */
+  agentCalls: number;
+  /** The judge evaluations made: one per judged round, and in `fast` mode one per draft judged alone. */
+  judgeCalls: number;
+  /**
+   * Agents a round stopped waiting for, in the order they were dropped; in
+   * `fast` mode, also the agents stopped once a draft was accepted.
+   */
+  dropped: AgentName[];
+}
+/**
+ * Each provider's own checks, in order. No paid call. The CLI adds a check for
+ * each variable its judge reads (`PlannerProgram.judgeEnv`).
+ */
+export declare function runDoctor(cwd: string, providers: readonly Provider[], env?: Readonly<Record<string, string | undefined>>): Promise<CheckResult[]>;
+//#endregion
+//#region src/orchestrator/orchestrator.d.ts
+/** What a `balanced` round waits for a straggler once enough agents have answered. */
+export declare const DEFAULT_STRAGGLER_GRACE_MS = 90000;
+export declare class Planner {
+  private readonly judge;
+  private readonly agents;
+  /** Two or more agents with distinct names; each drafts, revises, and may finalize. */
+  constructor(agents: readonly PlanningAgent[], judge: PlanJudge);
+  plan(options: PlanOptions): Promise<PlanResult>;
+}
+//#endregion
+//#region src/process/process.types.d.ts
+interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+//#endregion
+//#region src/process/process.d.ts
+export declare class ProcessError extends Error {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  constructor(command: string, exitCode: number | null, stderr: string);
+}
+//#endregion
+//#region src/provider/provider.d.ts
+/** An agent CLI installed and logged in on this machine, run read-only in the repository. */
+export declare function cliProvider(config: CliProviderConfig): Provider;
+/**
+ * A chat API that speaks OpenAI's `/chat/completions`, as DeepSeek, Moonshot,
+ * Z.ai and most others do. It cannot read the repository, so each prompt is
+ * sent with a snapshot of it: the tracked file list and the top-level docs and
+ * manifests (see `repoSnapshot`). Given an `AgentSession`, it keeps the
+ * conversation and sends it back on the next call, so the snapshot is sent once
+ * and later prompts can leave out what the conversation already holds.
+ */
+export declare function openAICompatibleProvider(config: OpenAICompatibleConfig): Provider;
+//#endregion
+//#region src/providers/providers.d.ts
+/**
+ * Every AI the planner can plan with. To add one, add an entry here, and the
+ * agent to `config.schema.json` and its copy in `apps/docs/public/`, which a
+ * test keeps in step: the CLI, `doctor`, `--help`, the config, the prompts and
+ * the judge all read this list. An OpenAI-compatible chat API is one
+ * `openAICompatibleProvider` call; an agent CLI that can run read-only is one
+ * `cliProvider` call.
+ */
+export declare const PROVIDERS: readonly Provider[];
+/** The agents a run uses without `--agents`. */
+export declare const DEFAULT_AGENTS: string[];
+//#endregion
+//#region src/task/task.d.ts
+/** Thrown before any agent call when the task is empty or a placeholder. */
+export declare class TaskValidationError extends Error {
+  name: string;
+}
+//#endregion
+//#region src/jev/jev.d.ts
+/** TypeSafe Jev, asked the planner's questions in one `systemOne` call per judged round. */
+export declare class TypeSafeJevJudge implements PlanJudge {
+  private readonly client;
+  readonly name = "Jev";
+  constructor(client?: TypeSafeClient);
+  judge(input: {
+    task: string;
+    plans: readonly JudgedPlan[];
+    stage: JudgeStage;
+    disputes?: readonly Dispute[];
+    model?: string;
+  }): Promise<Verdict>;
+}
+//#endregion
+export type { AgentName, AgentRequest, AgentSession, AgentSetup, CheckResult, ClaimCheck, CliProviderConfig, Dispute, DisputeRuling, JudgedPlan, Objection, OpenAICompatibleConfig, PlanCost, PlanJudge, PlanMode, PlanOptions, PlanResult, PlanRound, PlanningAgent, ProcessResult, Provider, Reply, ReviewMode, RoundDebate, RoundTimings, RunTimings, Verdict };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as Planner, c as cliProvider, f as runDoctor, i as PROVIDERS, n as DEFAULT_AGENTS, o as ProcessError, r as DEFAULT_STRAGGLER_GRACE_MS, s as TaskValidationError, t as TypeSafeJevJudge, u as openAICompatibleProvider } from "./jev-CIzG0Rhl.mjs";
+export { DEFAULT_AGENTS, DEFAULT_STRAGGLER_GRACE_MS, PROVIDERS, Planner, ProcessError, TaskValidationError, TypeSafeJevJudge, cliProvider, openAICompatibleProvider, runDoctor };