@pat-lewczuk/cezar 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# cezar ⚡
+
+Local cockpit for running and tracking AI agent tasks in your repo. Single
+user, zero config, one command:
+
+```bash
+cd your-repo
+npx cezar
+```
+
+That's it. If you have the `claude` CLI logged in (Pro/Max subscription) and
+`gh` authenticated, there is nothing to configure — cez opens a browser
+cockpit at `http://localhost:4321` where you type a task, pick a workflow and
+watch the agent work live (steps, tool calls, tokens), with a repo view
+(status / diff / log) right next to it.
+
+No accounts, no database, no cloud. State lives in `.ai/cezar/` inside your repo.
+
+## What it does
+
+- **Runs** — every agent task is a run: queued → running → done/failed, with a
+  live event log (agent text, tool calls, tool results), token usage per step
+  and cancel/delete controls. Failed run? Take the session over interactively:
+  `claude --resume <session-id>` (shown in the run header).
+- **Workflows** — a YAML file: agent steps + shell checks, with bounded
+  retry loops (`onFail: retry`). The built-in `quick-task` workflow (one agent
+  step) works with zero setup.
+- **Skills** — Markdown files in `.ai/skills/` or `.ai/cezar/skills/`; a workflow
+  step references one via `skill: <name>` and its body becomes the agent's
+  extra system prompt.
+- **Repo view** — branch, working-tree status, diff vs HEAD, recent commits.
+
+## Commands
+
+```bash
+npx cezar              # start the cockpit for the current repo
+npx cezar run "task"   # headless run in the terminal (CI-friendly)
+npx cezar init         # scaffold .ai/cezar/ with an example workflow + skill
+```
+
+## Workflow format
+
+`.ai/cezar/workflows/fix-and-verify.yaml`:
+
+```yaml
+name: fix-and-verify
+description: Implement, then verify; retry with failing output on red.
+steps:
+  - id: implement
+    name: Implement
+    prompt: "{{task}}"
+    skill: project-conventions   # optional, from .ai/skills or .ai/cezar/skills
+    # model: opus                # optional per-step override
+    # allowedTools: [Read, Edit, Write, Grep, Glob, Bash]
+  - id: verify
+    name: Verify
+    command: "npm test"
+    onFail:
+      retry: implement           # loop back, at most:
+      max: 2
+```
+
+`{{task}}` is replaced with the task you typed. When a check fails and loops
+back, the failing output is appended to the retried agent's prompt.
+
+## How it runs agents
+
+cez shells out to your locally installed, logged-in `claude` CLI in headless
+stream-json mode — your subscription, no API key. Tool access is
+default-deny via `--allowedTools`; edits are auto-accepted
+(`--permission-mode acceptEdits`) inside the repo directory.
+
+Useful env vars:
+
+- `CEZ_DRY_RUN=1` — use the bundled mock instead of the real CLI (demo/dev).
+- `CEZ_CLAUDE_BIN=/path/to/claude` — override the binary.
+
+## Development
+
+```bash
+npm install
+npm run dev        # tsx src/index.ts
+npm run build      # tsc → dist/
+```
+
+---
+
+cez is the radically-simple, single-user sibling of
+[cezar](https://github.com/...) — same core ideas (agent runner, skills,
+declarative workflows, run cockpit), none of the SaaS.

package/dist/core/agent-runner.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * `claude` CLI invocation streaming normalized events.
+ */
+export type AgentBackend = 'claude-cli';
+export interface AgentRunSpec {
+    /** Appended to the CLI's default system prompt (`--append-system-prompt`). */
+    systemPrompt?: string;
+    userPrompt: string;
+    /** The directory the agent runs in — also the only writable root. */
+    cwd: string;
+    /** Tool allowlist; the CLI is default-deny for anything not listed. */
+    allowedTools?: string[];
+    /** When `Bash` is allowed, restrict it to commands starting with one of these. */
+    bashAllowlist?: string[];
+    /** Extra directories the agent may read/write besides `cwd`. */
+    additionalDirectories?: string[];
+    model?: string;
+    /** Wall-clock kill switch for the run (ms). */
+    timeoutMs?: number;
+    /**
+     * Stable session id (UUID) so the user can take over interactively later:
+     * `cd <repo> && claude --resume <sessionId>`.
+     */
+    sessionId?: string;
+    /**
+     * Spawn `claude --resume <sessionId>` instead of starting a fresh session —
+     * picks up the on-disk conversation (used by "Continue" after a run ends).
+     */
+    resume?: boolean;
+}
+/** One content block of a user message — mirrors the Anthropic wire format
+ *  so it can be written to the claude CLI's stdin verbatim. */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+/** Normalized event stream — the GUI renders these, the store persists them. */
+export type AgentEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-call';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    result: string;
+    isError: boolean;
+} | {
+    type: 'token-usage';
+    tokensUsed: number;
+} | {
+    type: 'cost';
+    usd: number;
+} | {
+    type: 'turn-end';
+} | {
+    type: 'note';
+    message: string;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    message: string;
+};
+export interface AgentToolCallRecord {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface AgentRunResult {
+    /** Concatenated assistant text across the run, trimmed. */
+    text: string;
+    toolCalls: AgentToolCallRecord[];
+    /** Cost-weighted token usage; 0 when the backend surfaced no telemetry. */
+    tokensUsed: number;
+    sessionId?: string;
+}
+export interface AgentRunner {
+    readonly backend: AgentBackend;
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    interrupt(): Promise<void>;
+}

package/dist/core/agent-runner.js

@@ -0,0 +1,8 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * `claude` CLI invocation streaming normalized events.
+ */
+export {};
+//# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/core/backend-detect.d.ts

@@ -0,0 +1,14 @@
+export interface BackendCheck {
+    name: 'claude' | 'gh' | 'git';
+    available: boolean;
+    version?: string;
+    hint?: string;
+}
+/**
+ * Probe the host for everything cez leans on: the `claude` CLI (the agent
+ * backend), `gh` (GitHub auth for PR creation) and `git`. Nothing is required
+ * except `claude` — the GUI degrades gracefully and shows the hints instead.
+ */
+export declare function detectEnvironment(): Promise<BackendCheck[]>;
+/** The host's GitHub token: logged-in `gh` first, `GITHUB_TOKEN` fallback. */
+export declare function readHostGithubToken(): Promise<string | null>;

package/dist/core/backend-detect.js

@@ -0,0 +1,78 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+/**
+ * Probe the host for everything cez leans on: the `claude` CLI (the agent
+ * backend), `gh` (GitHub auth for PR creation) and `git`. Nothing is required
+ * except `claude` — the GUI degrades gracefully and shows the hints instead.
+ */
+export async function detectEnvironment() {
+    return Promise.all([probeClaude(), probeGh(), probeGit()]);
+}
+async function probeClaude() {
+    if (process.env.CEZ_DRY_RUN === '1') {
+        return { name: 'claude', available: true, version: 'mock (CEZ_DRY_RUN=1)' };
+    }
+    try {
+        const { stdout } = await exec('claude', ['--version'], { timeout: 10_000 });
+        const version = stdout.trim();
+        // A generic `claude` binary (a shell wrapper, an unrelated tool) can shadow
+        // the real CLI on $PATH — reject anything that doesn't match the banner.
+        if (!/^\d+\.\d+|^claude(\s+code)?\s+version\s+\d+\.\d+/i.test(version)) {
+            return {
+                name: 'claude',
+                available: false,
+                hint: `\`claude\` is on PATH but doesn't look like Claude Code (got: ${version.slice(0, 80)})`,
+            };
+        }
+        return {
+            name: 'claude',
+            available: true,
+            version,
+            hint: 'if not authenticated, run `claude` once and log in',
+        };
+    }
+    catch {
+        return {
+            name: 'claude',
+            available: false,
+            hint: 'install Claude Code (npm i -g @anthropic-ai/claude-code) and log in',
+        };
+    }
+}
+async function probeGh() {
+    try {
+        const { stdout } = await exec('gh', ['auth', 'token'], { timeout: 10_000 });
+        return { name: 'gh', available: stdout.trim().length > 0, version: 'authenticated' };
+    }
+    catch {
+        return {
+            name: 'gh',
+            available: false,
+            hint: 'install the GitHub CLI and run `gh auth login` (only needed for PR creation)',
+        };
+    }
+}
+async function probeGit() {
+    try {
+        const { stdout } = await exec('git', ['--version'], { timeout: 10_000 });
+        return { name: 'git', available: true, version: stdout.trim() };
+    }
+    catch {
+        return { name: 'git', available: false, hint: 'install git' };
+    }
+}
+/** The host's GitHub token: logged-in `gh` first, `GITHUB_TOKEN` fallback. */
+export async function readHostGithubToken() {
+    try {
+        const { stdout } = await exec('gh', ['auth', 'token'], { timeout: 10_000 });
+        const token = stdout.trim();
+        if (token)
+            return token;
+    }
+    catch {
+        // fall through to the env var
+    }
+    return process.env.GITHUB_TOKEN?.trim() || null;
+}
+//# sourceMappingURL=backend-detect.js.map

package/dist/core/backend-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-detect.js","sourceRoot":"","sources":["../../src/core/backend-detect.ts"],"names":[],"mappings":"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"}

package/dist/core/claude-cli-runner.d.ts

@@ -0,0 +1,68 @@
+import type { AgentEvent, AgentRunResult, AgentRunSpec, AgentRunner, ContentBlock } from './agent-runner.js';
+/** Default wall-clock cap for a single run before SIGTERM → SIGKILL.
+ *  Interactive sessions pass `timeoutMs: 0` to disable it entirely. */
+export declare const DEFAULT_RUN_TIMEOUT_MS: number;
+/** Grace period between SIGTERM and SIGKILL when a timeout fires. */
+export declare const KILL_GRACE_MS = 10000;
+/** After `end()` closes stdin: claude in stream-json mode can ignore EOF and
+ *  hang (janitor-confirmed CLI bug) — escalate SIGTERM, then SIGKILL. */
+export declare const EOF_TERM_GRACE_MS = 8000;
+export declare const EOF_KILL_GRACE_MS = 4000;
+/** Reopen window after a turn ends before an auto-ended session closes stdin. */
+export declare const AUTO_END_DELAY_MS = 250;
+export interface ClaudeCliRunnerOptions {
+    /** Override the binary name/path; defaults to `claude` on PATH. */
+    bin?: string;
+    /** Wall-clock timeout for a run (ms); per-spec `timeoutMs` still wins. */
+    timeoutMs?: number;
+}
+export interface SessionOptions {
+    /** Close the session shortly after the first turn ends (single-turn
+     *  behavior, used for non-interactive workflow steps). Interactive
+     *  sessions omit this and control `end()` themselves. */
+    autoEndAfterFirstTurn?: boolean;
+}
+/**
+ * A live agent session over one spawned claude process. The process stays
+ * alive between turns (no `-p`) and reads further user messages from stdin —
+ * that's what makes mid-task follow-ups and pasted screenshots possible.
+ */
+export interface AgentSession {
+    /** Resolves when the claude process exits — the session is fully over. */
+    result: Promise<AgentRunResult>;
+    /** Write a user message into the live session. False when stdin is closed. */
+    sendMessage(content: ContentBlock[]): boolean;
+    /** Graceful close: EOF on stdin, then the SIGTERM→SIGKILL watchdog. */
+    end(): void;
+    /** Hard stop (used by cancel). */
+    interrupt(): void;
+    /** True while the session still accepts messages. */
+    readonly open: boolean;
+}
+/**
+ * `AgentRunner` over the Claude Code CLI in headless stream-json mode. Auth =
+ * the host's logged-in Pro/Max subscription (no API key needed). Sandboxing is
+ * `--allowedTools` (default-deny) + running inside the repo `cwd`; `Bash` is
+ * narrowed to `Bash(<prefix>:*)` patterns when `bashAllowlist` is set.
+ *
+ * Session mechanics (multi-turn stdin, EOF watchdog, reopen window) follow
+ * github-janitor's `claudeRunner.ts`; the original single-turn adaptation
+ * came from @cezar/core's `ClaudeCodeCliRunner`.
+ */
+export declare class ClaudeCliRunner implements AgentRunner {
+    readonly backend: "claude-cli";
+    private readonly bin;
+    private readonly timeoutMs;
+    private lastSession;
+    constructor(opts?: ClaudeCliRunnerOptions);
+    /** One-shot run: start a session and auto-end it after the first turn. */
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    interrupt(): Promise<void>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
+}
+/**
+ * Map `allowedTools` onto claude's `--allowedTools` syntax. `Bash` with a
+ * `bashAllowlist` becomes one `Bash(<prefix>:*)` entry per allowed prefix;
+ * `Bash` with no allowlist stays plain `Bash`.
+ */
+export declare function buildAllowedTools(allowedTools: string[], bashAllowlist?: string[]): string[];