agent-lyceum 0.4.9

package/dist/schema.d.ts

@@ -0,0 +1,303 @@
+import { z } from "zod";
+export declare const RUNTIMES: readonly ["claude-code", "codex"];
+export type Runtime = (typeof RUNTIMES)[number];
+/** Union of both runtimes' levels; `validate` rejects the ones a given runtime does not accept. */
+export declare const EFFORTS: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
+export type Effort = (typeof EFFORTS)[number];
+/** Levels each runtime's CLI accepts (`claude --effort`, codex `model_reasoning_effort`). */
+export declare const RUNTIME_EFFORTS: Record<Runtime, readonly Effort[]>;
+/** Guess the runtime from a model name: Claude aliases/IDs -> claude-code, GPT/o-series/codex names -> codex. */
+export declare function inferRuntime(model: string | undefined): Runtime | undefined;
+export declare const AgentPartial: z.ZodObject<{
+    runtime: z.ZodOptional<z.ZodEnum<["claude-code", "codex"]>>;
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<["minimal", "low", "medium", "high", "xhigh", "max"]>>;
+    agent_md: z.ZodOptional<z.ZodString>;
+    memory: z.ZodOptional<z.ZodObject<{
+        global: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        global?: string | undefined;
+        project?: string | undefined;
+    }, {
+        global?: string | undefined;
+        project?: string | undefined;
+    }>>;
+    resume: z.ZodOptional<z.ZodBoolean>;
+    can_message: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodArray<z.ZodString, "many">]>>;
+    can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+    owns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    runtime?: "claude-code" | "codex" | undefined;
+    model?: string | undefined;
+    effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    agent_md?: string | undefined;
+    memory?: {
+        global?: string | undefined;
+        project?: string | undefined;
+    } | undefined;
+    resume?: boolean | undefined;
+    can_message?: string[] | "all" | undefined;
+    can_edit_agent_md?: boolean | undefined;
+    owns?: string[] | undefined;
+}, {
+    runtime?: "claude-code" | "codex" | undefined;
+    model?: string | undefined;
+    effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    agent_md?: string | undefined;
+    memory?: {
+        global?: string | undefined;
+        project?: string | undefined;
+    } | undefined;
+    resume?: boolean | undefined;
+    can_message?: string[] | "all" | undefined;
+    can_edit_agent_md?: boolean | undefined;
+    owns?: string[] | undefined;
+}>;
+export type AgentPartialT = z.infer<typeof AgentPartial>;
+export declare const DispatcherPartial: z.ZodObject<{
+    max_rounds: z.ZodOptional<z.ZodNumber>;
+    max_parallel: z.ZodOptional<z.ZodNumber>;
+    wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
+    retry: z.ZodOptional<z.ZodNumber>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    workspace_mode: z.ZodOptional<z.ZodEnum<["auto", "shared", "worktree"]>>;
+}, "strict", z.ZodTypeAny, {
+    strict?: boolean | undefined;
+    max_rounds?: number | undefined;
+    max_parallel?: number | undefined;
+    wake_timeout_sec?: number | undefined;
+    retry?: number | undefined;
+    workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+}, {
+    strict?: boolean | undefined;
+    max_rounds?: number | undefined;
+    max_parallel?: number | undefined;
+    wake_timeout_sec?: number | undefined;
+    retry?: number | undefined;
+    workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+}>;
+export declare const GlobalConfig: z.ZodObject<{
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<["claude-code", "codex"]>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<["minimal", "low", "medium", "high", "xhigh", "max"]>>;
+        agent_md: z.ZodOptional<z.ZodString>;
+        memory: z.ZodOptional<z.ZodObject<{
+            global: z.ZodOptional<z.ZodString>;
+            project: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            global?: string | undefined;
+            project?: string | undefined;
+        }, {
+            global?: string | undefined;
+            project?: string | undefined;
+        }>>;
+        resume: z.ZodOptional<z.ZodBoolean>;
+        can_message: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodArray<z.ZodString, "many">]>>;
+        can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+        owns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    agents: Record<string, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }>;
+}, {
+    agents?: Record<string, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }> | undefined;
+}>;
+export declare const ProjectConfig: z.ZodObject<{
+    dir: z.ZodString;
+    team: z.ZodObject<{
+        lead: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        lead: string;
+    }, {
+        lead: string;
+    }>;
+    dispatcher: z.ZodDefault<z.ZodObject<{
+        max_rounds: z.ZodOptional<z.ZodNumber>;
+        max_parallel: z.ZodOptional<z.ZodNumber>;
+        wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
+        retry: z.ZodOptional<z.ZodNumber>;
+        strict: z.ZodOptional<z.ZodBoolean>;
+        workspace_mode: z.ZodOptional<z.ZodEnum<["auto", "shared", "worktree"]>>;
+    }, "strict", z.ZodTypeAny, {
+        strict?: boolean | undefined;
+        max_rounds?: number | undefined;
+        max_parallel?: number | undefined;
+        wake_timeout_sec?: number | undefined;
+        retry?: number | undefined;
+        workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+    }, {
+        strict?: boolean | undefined;
+        max_rounds?: number | undefined;
+        max_parallel?: number | undefined;
+        wake_timeout_sec?: number | undefined;
+        retry?: number | undefined;
+        workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+    }>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<["claude-code", "codex"]>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<["minimal", "low", "medium", "high", "xhigh", "max"]>>;
+        agent_md: z.ZodOptional<z.ZodString>;
+        memory: z.ZodOptional<z.ZodObject<{
+            global: z.ZodOptional<z.ZodString>;
+            project: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            global?: string | undefined;
+            project?: string | undefined;
+        }, {
+            global?: string | undefined;
+            project?: string | undefined;
+        }>>;
+        resume: z.ZodOptional<z.ZodBoolean>;
+        can_message: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodArray<z.ZodString, "many">]>>;
+        can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+        owns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    agents: Record<string, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }>;
+    dir: string;
+    team: {
+        lead: string;
+    };
+    dispatcher: {
+        strict?: boolean | undefined;
+        max_rounds?: number | undefined;
+        max_parallel?: number | undefined;
+        wake_timeout_sec?: number | undefined;
+        retry?: number | undefined;
+        workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+    };
+}, {
+    dir: string;
+    team: {
+        lead: string;
+    };
+    agents?: Record<string, {
+        runtime?: "claude-code" | "codex" | undefined;
+        model?: string | undefined;
+        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        agent_md?: string | undefined;
+        memory?: {
+            global?: string | undefined;
+            project?: string | undefined;
+        } | undefined;
+        resume?: boolean | undefined;
+        can_message?: string[] | "all" | undefined;
+        can_edit_agent_md?: boolean | undefined;
+        owns?: string[] | undefined;
+    }> | undefined;
+    dispatcher?: {
+        strict?: boolean | undefined;
+        max_rounds?: number | undefined;
+        max_parallel?: number | undefined;
+        wake_timeout_sec?: number | undefined;
+        retry?: number | undefined;
+        workspace_mode?: "shared" | "auto" | "worktree" | undefined;
+    } | undefined;
+}>;
+export interface DispatcherSettings {
+    max_rounds: number;
+    max_parallel: number;
+    wake_timeout_sec: number;
+    retry: number;
+    strict: boolean;
+    /** "auto": a git worktree per non-lead agent when agents can run in parallel, otherwise one shared checkout. */
+    workspace_mode: "auto" | "shared" | "worktree";
+}
+export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
+/** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
+export declare const RUN_OUTCOMES: readonly ["completed", "partial", "blocked", "failed", "cancelled"];
+export type RunOutcome = (typeof RUN_OUTCOMES)[number];
+export declare function exitCodeForOutcome(outcome: RunOutcome): 0 | 1 | 2 | 130;

package/dist/schema.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+export const RUNTIMES = ["claude-code", "codex"];
+/** Union of both runtimes' levels; `validate` rejects the ones a given runtime does not accept. */
+export const EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+/** Levels each runtime's CLI accepts (`claude --effort`, codex `model_reasoning_effort`). */
+export const RUNTIME_EFFORTS = {
+    "claude-code": ["low", "medium", "high", "xhigh", "max"],
+    codex: ["minimal", "low", "medium", "high", "xhigh"],
+};
+/** Guess the runtime from a model name: Claude aliases/IDs -> claude-code, GPT/o-series/codex names -> codex. */
+export function inferRuntime(model) {
+    if (!model)
+        return undefined;
+    const m = model.trim().toLowerCase();
+    if (/^(claude|anthropic|opus|sonnet|haiku|fable|best|default|opusplan)\b/.test(m) || m.includes("claude"))
+        return "claude-code";
+    if (/^(gpt|codex|o\d)/.test(m) || m.includes("codex"))
+        return "codex";
+    return undefined;
+}
+const Memory = z
+    .object({
+    global: z.string().optional(),
+    project: z.string().optional(),
+})
+    .strict();
+export const AgentPartial = z
+    .object({
+    runtime: z.enum(RUNTIMES).optional(),
+    model: z.string().optional(),
+    effort: z.enum(EFFORTS).optional(),
+    agent_md: z.string().optional(),
+    memory: Memory.optional(),
+    resume: z.boolean().optional(),
+    can_message: z.union([z.literal("all"), z.array(z.string())]).optional(),
+    can_edit_agent_md: z.boolean().optional(),
+    owns: z.array(z.string()).optional(),
+})
+    .strict();
+export const DispatcherPartial = z
+    .object({
+    max_rounds: z.number().int().positive().optional(),
+    max_parallel: z.number().int().positive().optional(),
+    wake_timeout_sec: z.number().int().positive().optional(),
+    retry: z.number().int().min(0).optional(),
+    strict: z.boolean().optional(),
+    workspace_mode: z.enum(["auto", "shared", "worktree"]).optional(),
+})
+    .strict();
+export const GlobalConfig = z
+    .object({
+    agents: z.record(AgentPartial).default({}),
+})
+    .strict();
+export const ProjectConfig = z
+    .object({
+    dir: z.string(),
+    team: z.object({ lead: z.string() }).strict(),
+    dispatcher: DispatcherPartial.default({}),
+    agents: z.record(AgentPartial).default({}),
+})
+    .strict();
+export const DISPATCHER_DEFAULTS = {
+    max_rounds: 30,
+    max_parallel: 1,
+    wake_timeout_sec: 600,
+    retry: 1,
+    strict: false,
+    workspace_mode: "auto",
+};
+/** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
+export const RUN_OUTCOMES = ["completed", "partial", "blocked", "failed", "cancelled"];
+export function exitCodeForOutcome(outcome) {
+    switch (outcome) {
+        case "completed":
+            return 0;
+        case "failed":
+            return 1;
+        case "cancelled":
+            return 130;
+        default:
+            return 2;
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,142 @@
+import { type ActiveWake, type EndReason, type RunState, type WakeRecord } from "./run-store.js";
+import type { RunOutcome } from "./schema.js";
+import type { ResolvedProject } from "./config.js";
+import type { Step } from "./format.js";
+export declare function latestRun(project: ResolvedProject): {
+    dir: string;
+    state: RunState;
+} | undefined;
+/** Newest run that can still be resumed: not done and not currently running. */
+export declare function latestUnfinishedRun(project: ResolvedProject): {
+    dir: string;
+    state: RunState;
+} | undefined;
+export declare function listRuns(project: ResolvedProject, limit: number): {
+    dir: string;
+    state: RunState;
+}[];
+/**
+ * Is this run's dispatcher running now? Runs with a project lock (schema 2) are judged by the lock holder;
+ * the recorded pid is only the fallback for older runs and runs started without a lock.
+ */
+export declare function runIsAlive(s: RunState, project?: ResolvedProject): boolean;
+export declare function runStateLabel(s: Pick<RunState, "outcome" | "end_reason"> & {
+    pid?: number;
+}, live?: boolean): string;
+/** ANSI styling; `paint(false)` returns identity functions so output stays plain for pipes and tests. */
+export interface Paint {
+    bold: (t: string) => string;
+    dim: (t: string) => string;
+    red: (t: string) => string;
+    green: (t: string) => string;
+    yellow: (t: string) => string;
+    cyan: (t: string) => string;
+}
+export declare function paint(on: boolean): Paint;
+export declare function progressBar(done: number, total: number, width?: number, c?: Paint): string;
+export interface QueueItem {
+    agent: string;
+    from: string;
+    type: string;
+    subject: string;
+}
+export interface RunReport {
+    run_id: string;
+    dir: string;
+    /** running: its dispatcher is alive; interrupted: it died mid-run; ended: it stopped (see end_reason). */
+    state: "running" | "interrupted" | "ended";
+    live: boolean;
+    end_reason?: EndReason;
+    outcome?: RunOutcome;
+    /** False for runs that ended before outcomes were recorded: `outcome` is then only a cautious reading. */
+    outcome_verified: boolean;
+    outcome_note?: string;
+    verification?: string;
+    started_at: string;
+    ended_at?: string;
+    rounds: number;
+    max_rounds: number;
+    output_tokens: number;
+    task_source: "text" | "file";
+    task_path?: string;
+    task_summary: string;
+    steps?: Step[];
+    current_step: string | null;
+    active: Record<string, ActiveWake>;
+    /** Who is woken next, in order (empty once the run ended). */
+    queue: QueueItem[];
+    wakes: WakeRecord[];
+    notes: string[];
+    blocked_integrations: {
+        agent: string;
+        branch: string;
+        reason: string;
+        report: string;
+    }[];
+    result_path?: string;
+    /** First lines of the result, for the summary page. */
+    result_head: string[];
+    mail_layout: "run" | "legacy";
+    workspace_mode?: "shared" | "worktree";
+    last_wake: Record<string, {
+        at: string;
+        ok: boolean;
+        error?: string;
+    }>;
+}
+export interface AgentReport {
+    name: string;
+    runtime?: string;
+    lead: boolean;
+    unread: number;
+    last_wake?: {
+        at: string;
+        ok: boolean;
+        error?: string;
+    };
+}
+export interface StatusReport {
+    schema_version: 1;
+    project: {
+        name: string;
+        dir: string;
+        lead: string;
+    };
+    agents: AgentReport[];
+    run?: RunReport;
+}
+export interface TaskListReport {
+    schema_version: 1;
+    project: {
+        name: string;
+        dir: string;
+        lead: string;
+    };
+    runs: RunReport[];
+}
+/** One run as `status` sees it. Without `project`, liveness falls back to the recorded pid and there is no queue. */
+export declare function buildRunReport(run: {
+    dir: string;
+    state: RunState;
+}, project?: ResolvedProject, opts?: {
+    detail?: boolean;
+}): RunReport;
+/** The status of a project: its agents and one run (the newest, or the one named by `runId`). */
+export declare function buildStatusReport(base: ResolvedProject, runId?: string): StatusReport;
+/** Every run of the project, newest first. */
+export declare function buildTaskListReport(project: ResolvedProject): TaskListReport;
+/** Live view: summary and agent table, plus the latest run and any run still going, wake by wake. */
+export declare function formatMonitor(project: ResolvedProject, now?: number, color?: boolean): string;
+/** Plain `status`: the status page followed by the full wake-by-wake record of the latest run. */
+export declare function formatStatusWithLog(project: ResolvedProject, now?: number, color?: boolean): string;
+/** One run in full: header, every wake, the final result, and where its logs live. */
+export declare function formatRunDetail(run: {
+    dir: string;
+    state: RunState;
+}, now?: number, color?: boolean, project?: ResolvedProject): string;
+export declare function formatRunReport(r: RunReport, now?: number, color?: boolean): string;
+/** Every run of the project, newest first: id, state, rounds, progress and task. */
+export declare function formatTaskList(project: ResolvedProject, color?: boolean): string;
+export declare function formatTaskListReport(report: TaskListReport, color?: boolean): string;
+export declare function formatStatus(base: ResolvedProject, now?: number, color?: boolean): string;
+export declare function formatStatusReport(report: StatusReport, now?: number, color?: boolean): string;