aligndev 0.0.0 → 0.18.0

package/dist/code/codex-agent.js

@@ -0,0 +1,168 @@
+import { readCodexContext } from "./codex-rollout.js";
+export function createCodexAdapter() {
+    return {
+        executable: "codex",
+        buildArgs: buildCodexArgs,
+        createState: createCodexState,
+        interpretLine: interpretCodexLine,
+        assess: assessCodexState,
+        isAuthenticationError: isCodexAuthenticationMessage,
+        authenticationMessage: codexAuthenticationMessage,
+        failureMessage: missingCodexOutcome,
+    };
+}
+export function buildCodexArgs(config) {
+    const args = ["exec", "--json"];
+    if (config.skipPermissions) {
+        args.push("--dangerously-bypass-approvals-and-sandbox");
+    }
+    else {
+        args.push("--sandbox", "workspace-write");
+    }
+    // An `exec` option, like `--sandbox`: `exec resume` does not accept it. The session does not
+    // store it, so a resume passes it again.
+    for (const dir of config.additionalDirectories)
+        args.push("--add-dir", dir);
+    if (config.executableModel !== undefined)
+        args.push("--model", config.executableModel);
+    if (config.resume !== undefined)
+        args.push("resume", config.resume);
+    args.push("-");
+    return args;
+}
+export function createCodexState() {
+    return {
+        protocolComplete: false,
+        protocolFailed: false,
+        authEvidence: false,
+    };
+}
+export function interpretCodexLine(line, state) {
+    const event = parseCodexLine(line);
+    if (!isRecord(event))
+        return;
+    switch (event.type) {
+        case "thread.started":
+            return captureThread(event, state);
+        case "item.completed":
+            return captureCompletedItem(event, state);
+        case "turn.completed":
+            state.protocolComplete = true;
+            captureStreamTotal(event, state);
+            return;
+        case "turn.failed":
+        case "error":
+            return captureFailure(event, state);
+        case "unparsed":
+            return `[unparsed] ${asString(event.raw) ?? ""}`;
+        default:
+            return;
+    }
+}
+export function assessCodexState(state) {
+    const succeeded = state.protocolComplete && !state.protocolFailed && state.result !== undefined;
+    const context = readCodexContext(state.sessionId, state.streamTotalTokens);
+    return {
+        succeeded,
+        sessionId: state.sessionId,
+        result: state.result,
+        error: succeeded ? undefined : state.failure,
+        authEvidence: state.authEvidence,
+        contextTokens: context.contextTokens ?? undefined,
+        contextCompacted: context.compacted,
+        contextTokensError: context.error,
+    };
+}
+// The `turn.completed` usage is the thread's cumulative total, not its context occupancy. It serves
+// only to pin the rollout file to this run; `codex-rollout.ts` reads the occupancy itself. Codex
+// counts cached input inside `input_tokens`, so adding `cached_input_tokens` would double it.
+function captureStreamTotal(event, state) {
+    const usage = event.usage;
+    if (!isRecord(usage))
+        return;
+    const total = asCount(usage.input_tokens) + asCount(usage.output_tokens);
+    if (total > 0)
+        state.streamTotalTokens = total;
+}
+function parseCodexLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { type: "unparsed", raw: line };
+    }
+}
+function captureThread(event, state) {
+    const id = asString(event.thread_id);
+    if (id !== undefined && id !== "")
+        state.sessionId = id;
+    return `[init] session ${id ?? "?"}`;
+}
+function captureCompletedItem(event, state) {
+    const item = event.item;
+    if (!isRecord(item))
+        return;
+    if (item.type === "agent_message") {
+        const text = asString(item.text);
+        if (text !== undefined && text !== "")
+            state.result = text;
+        return text;
+    }
+    if (item.type !== "error")
+        return;
+    const message = extractMessage(item);
+    if (message === undefined)
+        return;
+    recordFailure(message, state);
+    return `[error] ${message}`;
+}
+function captureFailure(event, state) {
+    const message = extractMessage(event);
+    state.protocolFailed = true;
+    if (message === undefined)
+        return;
+    recordFailure(message, state);
+    return `[error] ${message}`;
+}
+function recordFailure(message, state) {
+    state.protocolFailed = true;
+    state.failure = message;
+    if (isCodexAuthenticationMessage(message))
+        state.authEvidence = true;
+}
+function extractMessage(value) {
+    const direct = asString(value.message);
+    if (direct !== undefined)
+        return direct;
+    const error = value.error;
+    if (typeof error === "string")
+        return error;
+    if (!isRecord(error))
+        return;
+    return asString(error.message);
+}
+function isCodexAuthenticationMessage(message) {
+    const normalized = message.trim();
+    return (/^(?:error:\s*)?(?:you are |user is )?not logged in\b/i.test(normalized) ||
+        /^(?:error:\s*)?.*\brun [`']?codex login[`']?\b/i.test(normalized));
+}
+function missingCodexOutcome(state) {
+    if (!state.protocolComplete)
+        return "Codex stream ended before turn.completed.";
+    return "Codex turn completed without a final agent message.";
+}
+function codexAuthenticationMessage(detail) {
+    const base = "Coding agent not authenticated: an administrator must run `codex login` on the host before " +
+        "`aligndev code` can run again.";
+    const reason = detail?.trim();
+    return reason === undefined || reason === "" ? base : `${base}\n\n${reason}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}

package/dist/code/codex-rollout.d.ts

@@ -0,0 +1,18 @@
+export interface CodexContextReading {
+    contextTokens: number | null;
+    compacted: boolean;
+    error?: string;
+}
+/**
+ * Context-window occupancy of a finished Codex run, read from its rollout file.
+ *
+ * `codex exec --json` reports only cumulative totals: the `usage` of its `turn.completed` event
+ * sums every model request of the thread, so it passes the context window on any run with a few
+ * tool calls. The rollout holds the figure Codex itself uses for "% context left" —
+ * `last_token_usage`, the newest request's occupancy.
+ *
+ * `streamTotal` is the total taken from that `turn.completed` event. The rollout's own total must
+ * equal it, which pins the file to this run and turns any change in the Codex format into a
+ * reported error rather than a plausible wrong number.
+ */
+export declare function readCodexContext(threadId: string | undefined, streamTotal: number | undefined): CodexContextReading;

package/dist/code/codex-rollout.js

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+// Codex writes one rollout per thread under `$CODEX_HOME/sessions/<year>/<month>/<day>/`. The plain
+// file is `rollout-<timestamp>-<threadId>.jsonl`; a compacted thread appends `_<uuid>`.
+const SESSIONS_DIR = "sessions";
+const ROLLOUT_PREFIX = "rollout-";
+const ROLLOUT_SUFFIX = ".jsonl";
+/**
+ * Context-window occupancy of a finished Codex run, read from its rollout file.
+ *
+ * `codex exec --json` reports only cumulative totals: the `usage` of its `turn.completed` event
+ * sums every model request of the thread, so it passes the context window on any run with a few
+ * tool calls. The rollout holds the figure Codex itself uses for "% context left" —
+ * `last_token_usage`, the newest request's occupancy.
+ *
+ * `streamTotal` is the total taken from that `turn.completed` event. The rollout's own total must
+ * equal it, which pins the file to this run and turns any change in the Codex format into a
+ * reported error rather than a plausible wrong number.
+ */
+export function readCodexContext(threadId, streamTotal) {
+    if (threadId === undefined || threadId === "")
+        return failed("Codex reported no thread id.");
+    if (streamTotal === undefined)
+        return failed("Codex reported no turn.completed usage.");
+    const path = findRolloutPath(threadId);
+    if (path === undefined)
+        return failed(`No Codex rollout found for thread ${threadId}.`);
+    const records = readUsageRecords(path);
+    if (records.length === 0)
+        return failed(`No token_count record in ${basename(path)}.`);
+    const last = records[records.length - 1];
+    if (last.total !== streamTotal) {
+        return failed(`Codex rollout total ${last.total} does not match the stream total ${streamTotal}; ` +
+            "the rollout format may have changed.");
+    }
+    // Occupancy only ever falls when Codex compacts the thread, so an earlier reading above the
+    // final one is the compaction itself. Matching the rollout's compaction records instead would be
+    // brittle: they sit nested inside response items, not as their own event type.
+    const peak = Math.max(...records.map((record) => record.occupancy));
+    return { contextTokens: last.occupancy, compacted: peak > last.occupancy };
+}
+function failed(error) {
+    return { contextTokens: null, compacted: false, error };
+}
+function findRolloutPath(threadId) {
+    const root = join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), SESSIONS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(root, { recursive: true, encoding: "utf8" });
+    }
+    catch {
+        return;
+    }
+    const matches = entries.filter((entry) => matchesThread(basename(entry), threadId)).sort();
+    // Timestamps sort lexically, so the last match is the newest rollout of the thread.
+    const newest = matches[matches.length - 1];
+    return newest === undefined ? undefined : join(root, newest);
+}
+function matchesThread(name, threadId) {
+    return (name.startsWith(ROLLOUT_PREFIX) && name.endsWith(ROLLOUT_SUFFIX) && name.includes(threadId));
+}
+function readUsageRecords(path) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of content.split("\n")) {
+        if (!line.includes('"token_count"'))
+            continue;
+        const record = parseUsageRecord(line);
+        if (record !== undefined)
+            records.push(record);
+    }
+    return records;
+}
+function parseUsageRecord(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (!isRecord(parsed))
+        return;
+    const payload = parsed.payload;
+    if (!isRecord(payload) || payload.type !== "token_count")
+        return;
+    const info = payload.info;
+    if (!isRecord(info))
+        return;
+    const occupancy = sumUsage(info.last_token_usage);
+    const total = sumUsage(info.total_token_usage);
+    if (occupancy === undefined || total === undefined)
+        return;
+    return { occupancy, total };
+}
+// Codex counts cached input inside `input_tokens`, so adding `cached_input_tokens` would double it.
+function sumUsage(usage) {
+    if (!isRecord(usage))
+        return;
+    return asCount(usage.input_tokens) + asCount(usage.output_tokens);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}

package/dist/code/coding-agent.d.ts

@@ -0,0 +1,4 @@
+import type { AgentAdapter } from "./run-agent.js";
+export declare const CODING_AGENTS: readonly ["claude", "codex"];
+export type CodingAgent = (typeof CODING_AGENTS)[number];
+export declare function createAgentAdapter(agent: CodingAgent): AgentAdapter;

package/dist/code/coding-agent.js

@@ -0,0 +1,6 @@
+import { createClaudeAdapter } from "./claude-agent.js";
+import { createCodexAdapter } from "./codex-agent.js";
+export const CODING_AGENTS = ["claude", "codex"];
+export function createAgentAdapter(agent) {
+    return agent === "claude" ? createClaudeAdapter() : createCodexAdapter();
+}

package/dist/code/models.d.ts

@@ -0,0 +1,14 @@
+import type { CodingAgent } from "./coding-agent.js";
+export declare const CLAUDE_DEFAULT_MODELS: readonly ["fable", "opus", "sonnet", "haiku"];
+export declare const CODEX_DEFAULT_MODELS: readonly ["astra", "sol", "terra", "luna"];
+export declare function resolveModels(agent: CodingAgent, override: readonly string[] | undefined): readonly string[];
+export interface ModelDiscoveryContext {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type ModelCatalogRunner = (context: ModelDiscoveryContext) => Promise<string>;
+export type ExecutableModelResolver = (agent: CodingAgent, selectedModel: string | undefined, context: ModelDiscoveryContext) => Promise<string | undefined>;
+export declare function createExecutableModelResolver(runCatalog?: ModelCatalogRunner): ExecutableModelResolver;
+export declare const resolveExecutableModel: ExecutableModelResolver;
+export declare function parseBundledModelSlugs(output: string): readonly string[];
+export declare function selectNewestCodexModel(slugs: readonly string[], alias: string): string | undefined;

package/dist/code/models.js

@@ -0,0 +1,89 @@
+import { execFile } from "node:child_process";
+export const CLAUDE_DEFAULT_MODELS = ["fable", "opus", "sonnet", "haiku"];
+export const CODEX_DEFAULT_MODELS = ["astra", "sol", "terra", "luna"];
+const CODEX_ALIASES = new Set(CODEX_DEFAULT_MODELS);
+const CODEX_MODEL_PATTERN = new RegExp(`^gpt-([0-9]+)(?:\\.([0-9]+))?-(${CODEX_DEFAULT_MODELS.join("|")})$`);
+const CODEX_CATALOG_MAX_BUFFER = 8 * 1024 * 1024;
+const CODEX_CATALOG_TIMEOUT_MS = 30_000;
+export function resolveModels(agent, override) {
+    if (override !== undefined && override.length > 0)
+        return override;
+    return agent === "claude" ? CLAUDE_DEFAULT_MODELS : CODEX_DEFAULT_MODELS;
+}
+export function createExecutableModelResolver(runCatalog = runCodexModelCatalog) {
+    let cachedSlugs;
+    return async (agent, selectedModel, context) => {
+        if (selectedModel === undefined)
+            return;
+        if (agent === "claude" || !CODEX_ALIASES.has(selectedModel))
+            return selectedModel;
+        try {
+            cachedSlugs ??= parseBundledModelSlugs(await runCatalog(context));
+            const slug = selectNewestCodexModel(cachedSlugs, selectedModel);
+            if (slug !== undefined)
+                return slug;
+            throw new Error("the bundled catalog contains no matching model");
+        }
+        catch (error) {
+            throw new Error(codexAliasError(selectedModel, error));
+        }
+    };
+}
+export const resolveExecutableModel = createExecutableModelResolver();
+export function parseBundledModelSlugs(output) {
+    let value;
+    try {
+        value = JSON.parse(output);
+    }
+    catch {
+        throw new Error("Codex returned malformed JSON");
+    }
+    if (!isRecord(value) || !Array.isArray(value.models)) {
+        throw new Error("Codex returned an unexpected model catalog shape");
+    }
+    const slugs = [];
+    for (const model of value.models) {
+        if (!isRecord(model) || typeof model.slug !== "string") {
+            throw new Error("Codex returned an unexpected model catalog shape");
+        }
+        slugs.push(model.slug);
+    }
+    return slugs;
+}
+export function selectNewestCodexModel(slugs, alias) {
+    const matches = slugs
+        .map((slug) => ({ slug, match: slug.match(CODEX_MODEL_PATTERN) }))
+        .filter((candidate) => candidate.match?.[3] === alias)
+        .sort((a, b) => {
+        const major = Number(b.match?.[1]) - Number(a.match?.[1]);
+        return major !== 0 ? major : Number(b.match?.[2] ?? 0) - Number(a.match?.[2] ?? 0);
+    });
+    return matches[0]?.slug;
+}
+function runCodexModelCatalog(context) {
+    return new Promise((resolve, reject) => {
+        const child = execFile("codex", ["debug", "models", "--bundled"], {
+            cwd: context.cwd,
+            env: context.env,
+            encoding: "utf8",
+            maxBuffer: CODEX_CATALOG_MAX_BUFFER,
+            timeout: CODEX_CATALOG_TIMEOUT_MS,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+        child.stdin?.end();
+    });
+}
+function codexAliasError(alias, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return (`Unable to resolve Codex model alias ${JSON.stringify(alias)}: ${detail}. ` +
+        "Update the Codex CLI, or set `code.models` in the aligndev config to an explicit full model " +
+        "slug and select that value.");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/code/prompt.d.ts

@@ -0,0 +1,11 @@
+export declare const PROTOCOLS: readonly ["spec", "plan", "aad", "description", "review", "merge"];
+export type Protocol = (typeof PROTOCOLS)[number];
+export interface PromptInput {
+    protocol?: string;
+    ticket?: string;
+    message?: string;
+    catchupContent?: string;
+    contextContent?: string;
+    alignfirst: string;
+}
+export declare function buildPrompt(input: PromptInput): string;

package/dist/code/prompt.js

@@ -0,0 +1,26 @@
+export const PROTOCOLS = ["spec", "plan", "aad", "description", "review", "merge"];
+export function buildPrompt(input) {
+    const { protocol, ticket, message, catchupContent, contextContent, alignfirst } = input;
+    const instruction = protocol === undefined ? message : buildProtocolPrompt(alignfirst, protocol, ticket, message);
+    if (catchupContent === undefined && contextContent === undefined)
+        return instruction ?? "";
+    const sections = [];
+    if (contextContent !== undefined)
+        sections.push("## Project context", contextContent.trimEnd());
+    if (catchupContent !== undefined)
+        sections.push("## Ticket history", catchupContent);
+    sections.push("## Current instruction", currentInstruction(instruction, catchupContent));
+    return sections.join("\n\n");
+}
+function currentInstruction(instruction, catchupContent) {
+    const blank = instruction === undefined || instruction.trim() === "";
+    if (blank && catchupContent !== undefined) {
+        return "Summarize the ticket history briefly, including what remains unfinished.";
+    }
+    return instruction ?? "";
+}
+function buildProtocolPrompt(alignfirst, protocol, ticket, message) {
+    const ticketPart = ticket === undefined ? "" : ` Ticket ID = ${ticket}.`;
+    const messagePart = message === undefined ? "" : `\n\n${message}`;
+    return `Run \`${alignfirst} guide ${protocol}\` and follow the protocol.${ticketPart}${messagePart}`;
+}

package/dist/code/quota.d.ts

@@ -0,0 +1,25 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { CodingAgent } from "./coding-agent.js";
+export declare const readQuota: QuotaReader;
+export interface QuotaContext {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    unset: readonly string[];
+}
+export type QuotaReader = (agent: CodingAgent, context: QuotaContext) => Promise<string>;
+export interface QuotaProcessAdapter {
+    execute(file: string, args: string[], options: QuotaProcessOptions & {
+        timeout: number;
+    }): Promise<{
+        stdout: string;
+    }>;
+    spawn(file: string, args: string[], options: QuotaProcessOptions): ChildProcessWithoutNullStreams;
+}
+interface QuotaProcessOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export declare function createQuotaReader(adapter?: QuotaProcessAdapter, timeoutMs?: number): QuotaReader;
+export declare function parseClaudeQuota(stdout: string): string;
+export declare function formatCodexQuota(response: unknown, formatTime?: (timestampSeconds: number) => string): string;
+export {};