hammadev 0.1.0-alpha.0

package/dist/adapters/codex/paths.js

@@ -0,0 +1,21 @@
+import os from "node:os";
+import path from "node:path";
+export function defaultCodexHome() {
+    return path.join(os.homedir(), ".codex");
+}
+export function codexSessionsGlob(codexHome = defaultCodexHome()) {
+    return path.join(codexHome, "sessions", "*", "*", "*", "rollout-*.jsonl");
+}
+const ROLLOUT_RE = /^rollout-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2})-(.+)\.jsonl$/;
+export function parseRolloutFilename(filePath) {
+    const base = path.basename(filePath);
+    const match = base.match(ROLLOUT_RE);
+    if (!match)
+        return null;
+    const [, timestampRaw, conversationId] = match;
+    return {
+        timestampRaw,
+        conversationId,
+        startedAt: timestampRaw.replace(/T(\d{2})-(\d{2})-(\d{2})$/, "T$1:$2:$3")
+    };
+}

package/dist/adapters/codex/resolve.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { discoverCodexSessions } from "./discover.js";
+const CODEX_PREFIX = "codex:";
+export async function resolveCodexTarget(target, options = {}) {
+    if (target.startsWith(CODEX_PREFIX)) {
+        const rest = target.slice(CODEX_PREFIX.length);
+        if (!rest) {
+            throw new Error(`Invalid Codex target '${target}'. Expected 'codex:last', 'codex:<conversationId>', or a rollout file path.`);
+        }
+        const sessions = await discoverCodexSessions(options.codexHome);
+        if (rest === "last") {
+            const latest = sessions[0];
+            if (!latest)
+                throw new Error("No Codex sessions found.");
+            return latest.path;
+        }
+        return resolveByConversationId(rest, sessions);
+    }
+    return resolveByFilePath(target);
+}
+function resolveByConversationId(id, sessions) {
+    const exact = sessions.find((s) => s.conversationId === id);
+    if (exact)
+        return exact.path;
+    const prefixMatches = sessions.filter((s) => s.conversationId.startsWith(id));
+    if (prefixMatches.length === 1)
+        return prefixMatches[0].path;
+    if (prefixMatches.length > 1) {
+        const list = prefixMatches
+            .map((s) => `  - ${s.conversationId} (${s.path})`)
+            .join("\n");
+        throw new Error(`Ambiguous Codex conversationId prefix '${id}'. Matches ${prefixMatches.length} sessions:\n${list}`);
+    }
+    throw new Error(`No Codex session found with conversationId matching '${id}'.`);
+}
+async function resolveByFilePath(target) {
+    const abs = path.resolve(target);
+    const base = path.basename(abs);
+    if (!abs.endsWith(".jsonl")) {
+        throw new Error(`Rollout file must have a .jsonl extension: ${abs}`);
+    }
+    if (!base.startsWith("rollout-")) {
+        throw new Error(`Rollout file basename must start with 'rollout-': ${base}`);
+    }
+    try {
+        const stat = await fs.stat(abs);
+        if (!stat.isFile()) {
+            throw new Error(`Rollout path is not a regular file: ${abs}`);
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Rollout file does not exist: ${abs}`);
+        }
+        throw err;
+    }
+    return abs;
+}

package/dist/adapters/codex/rollout.js

@@ -0,0 +1,214 @@
+import fs from "node:fs";
+import readline from "node:readline";
+import { redactText } from "../../core/redact.js";
+import { parseRolloutFilename } from "./paths.js";
+function stringifySafe(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractContentText(content) {
+    if (!content)
+        return undefined;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const parts = content
+            .map((item) => {
+            if (typeof item === "string")
+                return item;
+            if (typeof item?.text === "string")
+                return item.text;
+            if (typeof item?.content === "string")
+                return item.content;
+            return "";
+        })
+            .filter(Boolean);
+        return parts.length > 0 ? parts.join("\n") : undefined;
+    }
+    if (typeof content === "object") {
+        const obj = content;
+        if (typeof obj.text === "string")
+            return obj.text;
+        if (typeof obj.content === "string")
+            return obj.content;
+        if (typeof obj.message === "string")
+            return obj.message;
+    }
+    return undefined;
+}
+function extractPayloadText(payload) {
+    if (!payload)
+        return undefined;
+    if (typeof payload.message === "string")
+        return payload.message;
+    if (typeof payload.text === "string")
+        return payload.text;
+    if (typeof payload.content === "string")
+        return payload.content;
+    const fromContent = extractContentText(payload.content);
+    if (fromContent)
+        return fromContent;
+    return undefined;
+}
+function redactIntoSession(session, text) {
+    const redacted = redactText(text);
+    session.security.redactionCount += redacted.count;
+    if (redacted.count > 0)
+        session.security.redacted = true;
+    return redacted.text;
+}
+export async function parseCodexRollout(rolloutPath) {
+    try {
+        await fs.promises.access(rolloutPath, fs.constants.R_OK);
+    }
+    catch (err) {
+        throw new Error(`Rollout file is missing or not readable: ${rolloutPath}`);
+    }
+    const parsedFile = parseRolloutFilename(rolloutPath);
+    const session = {
+        meta: {
+            sourceCli: "codex",
+            sourceSessionId: parsedFile?.conversationId ?? "",
+            startedAt: parsedFile?.startedAt,
+            sourcePath: rolloutPath
+        },
+        messages: [],
+        shellCommands: [],
+        parserWarnings: [],
+        security: {
+            redacted: false,
+            redactionCount: 0,
+            warnings: []
+        }
+    };
+    const fileStream = fs.createReadStream(rolloutPath);
+    const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+    const toolCalls = new Map();
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let item;
+        try {
+            item = JSON.parse(line);
+        }
+        catch {
+            session.parserWarnings.push("Skipped malformed JSONL line.");
+            continue;
+        }
+        const topType = String(item.type ?? "");
+        const payload = item.payload ?? {};
+        const payloadType = String(payload.type ?? "");
+        const timestamp = item.timestamp ? String(item.timestamp) : undefined;
+        // session_meta line
+        if (topType === "session_meta") {
+            const id = payload.session_id ?? payload.id;
+            const cwd = payload.cwd;
+            if (id && !session.meta.sourceSessionId)
+                session.meta.sourceSessionId = String(id);
+            if (cwd)
+                session.meta.projectPath = String(cwd);
+            if (payload.timestamp && !session.meta.startedAt) {
+                session.meta.startedAt = String(payload.timestamp);
+            }
+            continue;
+        }
+        // turn_context contains cwd/model/git-ish context
+        if (topType === "turn_context") {
+            if (payload.cwd)
+                session.meta.projectPath = String(payload.cwd);
+            continue;
+        }
+        // event_msg: user visible events
+        if (topType === "event_msg") {
+            if (payloadType === "user_message") {
+                const raw = extractPayloadText(payload);
+                if (raw) {
+                    session.messages.push({
+                        role: "user",
+                        content: redactIntoSession(session, raw),
+                        timestamp
+                    });
+                }
+                continue;
+            }
+            if (payloadType === "agent_message") {
+                const raw = extractPayloadText(payload);
+                if (raw) {
+                    session.messages.push({
+                        role: "assistant",
+                        content: redactIntoSession(session, raw),
+                        timestamp
+                    });
+                }
+                continue;
+            }
+            // Some command/tool completions may appear here.
+            if (payloadType === "mcp_tool_call_end") {
+                const invocation = payload.invocation;
+                const result = payload.result;
+                const command = invocation?.arguments?.cmd ??
+                    invocation?.arguments?.command ??
+                    invocation?.input?.cmd ??
+                    invocation?.input?.command;
+                if (command) {
+                    session.shellCommands.push({
+                        command: redactIntoSession(session, stringifySafe(command)),
+                        output: result ? redactIntoSession(session, stringifySafe(result)) : undefined,
+                        endedAt: timestamp
+                    });
+                }
+                continue;
+            }
+            continue;
+        }
+        // response_item: model/tool transcript items
+        if (topType === "response_item") {
+            if (payloadType === "function_call" || payloadType === "custom_tool_call") {
+                const callId = payload.call_id;
+                const name = payload.name ?? "tool_call";
+                if (callId) {
+                    toolCalls.set(String(callId), {
+                        name: String(name),
+                        input: payload.arguments ?? payload.input
+                    });
+                }
+                // Shell commands are often represented as custom tool calls.
+                const input = payload.arguments ?? payload.input;
+                const possibleCommand = input?.cmd ??
+                    input?.command ??
+                    input?.argv?.join?.(" ") ??
+                    (name === "shell" || name === "exec" || name === "bash" ? input : undefined);
+                if (possibleCommand) {
+                    session.shellCommands.push({
+                        command: redactIntoSession(session, stringifySafe(possibleCommand)),
+                        startedAt: timestamp
+                    });
+                }
+                continue;
+            }
+            if (payloadType === "function_call_output" || payloadType === "custom_tool_call_output") {
+                const rawOutput = payload.output;
+                if (rawOutput !== undefined) {
+                    const output = redactIntoSession(session, stringifySafe(rawOutput));
+                    // Attach to latest shell command if possible.
+                    const last = session.shellCommands[session.shellCommands.length - 1];
+                    if (last && !last.output) {
+                        last.output = output;
+                        last.endedAt = timestamp;
+                    }
+                }
+                continue;
+            }
+            // Ignore reasoning/token_count for v0.1.
+            continue;
+        }
+    }
+    session.meta.lastUpdatedAt = new Date().toISOString();
+    return session;
+}

package/dist/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import { CodexAdapter } from "./adapters/codex/index.js";
+import { ClaudeAdapter } from "./adapters/claude/index.js";
+import { createHandoff } from "./core/handoff.js";
+import { formatHandoffLog, listHandoffs, readHandoff } from "./core/history.js";
+import { formatProjectStatus, getProjectStatus } from "./core/project-status.js";
+import { runDoctor } from "./core/doctor.js";
+import { loadSession, resolveSessionTarget } from "./session-loader.js";
+function truncate(s, max) {
+    if (!s)
+        return s;
+    return s.length > max ? s.slice(0, max) + "..." : s;
+}
+function renderSession(session, summary) {
+    if (!summary)
+        return JSON.stringify(session, null, 2);
+    const view = {
+        meta: session.meta,
+        messageCount: session.messages.length,
+        shellCommandCount: session.shellCommands.length,
+        parserWarningsCount: session.parserWarnings.length,
+        redactionCount: session.security.redactionCount,
+        firstMessages: session.messages.slice(0, 5).map((m) => ({
+            ...m,
+            content: truncate(m.content, 300)
+        })),
+        lastMessages: session.messages.slice(-5).map((m) => ({
+            ...m,
+            content: truncate(m.content, 300)
+        })),
+        lastShellCommands: session.shellCommands.slice(-10).map((c) => ({
+            ...c,
+            command: truncate(c.command, 200),
+            output: c.output !== undefined ? "<omitted>" : undefined
+        }))
+    };
+    return JSON.stringify(view, null, 2);
+}
+function printCountMap(label, counts) {
+    const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+    if (entries.length === 0) {
+        console.log(`${label}: (none)`);
+        return;
+    }
+    console.log(`${label}:`);
+    for (const [k, v] of entries)
+        console.log(`  ${k}: ${v}`);
+}
+function printClaudeShapeReport(report) {
+    console.log(pc.bold("Claude session shape inspection"));
+    console.log(pc.yellow("(read-only — no message content, tool inputs, or outputs are printed)"));
+    console.log("");
+    console.log(`File: ${report.path}`);
+    console.log(`Size: ${report.sizeBytes} bytes`);
+    console.log(`Total non-empty lines: ${report.totalLines}`);
+    console.log(`Parsed JSON lines: ${report.parsedLines}`);
+    console.log(`Malformed lines: ${report.malformedLines}`);
+    console.log("");
+    printCountMap("Top-level key frequency", report.topLevelKeyFrequency);
+    console.log("");
+    printCountMap("Type field values", report.typeCounts);
+    console.log("");
+    printCountMap("Role values", report.roleCounts);
+    console.log("");
+    const typeShapes = Object.entries(report.shapeByType).sort((a, b) => a[0].localeCompare(b[0]));
+    if (typeShapes.length === 0) {
+        console.log("Shape by type: (none)");
+    }
+    else {
+        console.log("Shape by type:");
+        for (const [t, shape] of typeShapes) {
+            console.log(`  ${t}:`);
+            const keys = Object.keys(shape).sort();
+            for (const k of keys)
+                console.log(`    ${k}: ${shape[k]}`);
+        }
+    }
+    console.log("");
+    if (report.cwdValues.length === 0) {
+        console.log("Detected cwd values: (none)");
+    }
+    else {
+        console.log("Detected cwd values:");
+        for (const v of report.cwdValues)
+            console.log(`  ${v}`);
+    }
+    if (report.projectPathValues.length === 0) {
+        console.log("Detected projectPath values: (none)");
+    }
+    else {
+        console.log("Detected projectPath values:");
+        for (const v of report.projectPathValues)
+            console.log(`  ${v}`);
+    }
+}
+const program = new Command();
+program
+    .name("hamma")
+    .description("Shared memory and handoff layer for agentic coding CLIs")
+    .version("0.1.0-alpha.0");
+program
+    .command("list")
+    .argument("<source>", "source CLI: codex | claude")
+    .description("List sessions from a source CLI")
+    .action(async (source) => {
+    if (source === "codex") {
+        const sessions = await CodexAdapter.list();
+        if (sessions.length === 0) {
+            console.log(pc.yellow("No Codex sessions found."));
+            return;
+        }
+        console.log(pc.bold(`Codex sessions found: ${sessions.length}\n`));
+        sessions.slice(0, 20).forEach((s, i) => {
+            console.log(`${i + 1}. ${pc.cyan(s.startedAt ?? "unknown-time")} ${s.conversationId}`);
+            console.log(`   ${s.path}`);
+            console.log(`   updated: ${s.lastUpdatedAt ?? "unknown"} size: ${s.sizeBytes ?? 0} bytes`);
+        });
+        return;
+    }
+    if (source === "claude") {
+        const sessions = await ClaudeAdapter.list();
+        console.log(pc.yellow("Claude Code discovery is read-only and experimental — no files are modified."));
+        if (sessions.length === 0) {
+            console.log(pc.yellow("\nNo Claude Code session files found."));
+            console.log("Looked under ~/.claude, ~/.config/claude, and ~/.local/share/claude for projects/**/*.jsonl, sessions/**/*.jsonl, and history/**/*.jsonl.");
+            console.log("If Claude Code is installed elsewhere on this machine, this is expected.");
+            return;
+        }
+        console.log(pc.bold(`\nCandidate Claude session files: ${sessions.length}\n`));
+        sessions.slice(0, 20).forEach((s, i) => {
+            const idLabel = s.sessionId ?? "unknown-session-id";
+            console.log(`${i + 1}. ${pc.cyan(s.lastUpdatedAt)} ${idLabel}`);
+            console.log(`   ${s.path}`);
+            console.log(`   size: ${s.sizeBytes} bytes  home: ${s.claudeHome}${s.projectPathHint ? `  cwd hint: ${s.projectPathHint}` : ""}`);
+        });
+        if (sessions.length > 20) {
+            console.log(pc.dim(`\n… ${sessions.length - 20} more not shown.`));
+        }
+        return;
+    }
+    console.error(pc.red(`Error: Unsupported source '${source}'. Supported: 'codex', 'claude'.`));
+    process.exit(1);
+});
+program
+    .command("inspect")
+    .argument("<target>", "codex:last | codex:<conversationId> | claude:last | claude:<sessionId> | session JSONL path")
+    .option("--summary", "Print a summarized view (meta, counts, head/tail messages)")
+    .option("--shape", "Read-only shape report for Claude targets — no message content is printed")
+    .description("Inspect one session")
+    .action(async (target, options) => {
+    if (options.shape) {
+        try {
+            const resolved = await resolveSessionTarget(target);
+            if (resolved.sourceCli !== "claude") {
+                throw new Error("--shape is only supported for Claude sessions.");
+            }
+            const report = await ClaudeAdapter.inspectShape(resolved.sessionPath);
+            printClaudeShapeReport(report);
+            return;
+        }
+        catch (err) {
+            console.error(pc.red(`Error inspecting Claude session shape: ${err.message}`));
+            process.exit(1);
+        }
+    }
+    try {
+        const session = await loadSession(target);
+        console.log(renderSession(session, Boolean(options.summary)));
+    }
+    catch (err) {
+        console.error(pc.red(`Error inspecting session: ${err.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("handoff")
+    .argument("<target>", "codex:last | codex:<conversationId> | claude:last | claude:<sessionId> | session JSONL path")
+    .requiredOption("--to <agent>", "Target CLI (e.g. claude or codex)")
+    .option("--no-gitignore", "Do not modify .gitignore")
+    .description("Create a handoff package for another agent")
+    .action(async (target, options) => {
+    try {
+        const session = await loadSession(target);
+        await createHandoff(session, options.to, options.gitignore);
+    }
+    catch (err) {
+        console.error(pc.red(`Error processing handoff: ${err.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("status")
+    .option("--project <path>", "Project directory to inspect")
+    .description("Show a read-only project and local session overview")
+    .action(async (options) => {
+    const projectPath = path.resolve(options.project ?? process.cwd());
+    try {
+        console.log(formatProjectStatus(await getProjectStatus(projectPath)));
+    }
+    catch (err) {
+        console.error(pc.red(`Error reading project status: ${err.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("log")
+    .option("--project <path>", "Project whose local handoff history should be listed")
+    .description("List local handoffs for a project, newest first")
+    .action(async (options) => {
+    const projectPath = path.resolve(options.project ?? process.cwd());
+    try {
+        const handoffs = await listHandoffs(projectPath);
+        if (handoffs.length === 0) {
+            console.log(pc.yellow(`No handoffs found in ${path.join(projectPath, ".hamma", "tasks")}.`));
+            return;
+        }
+        console.log(formatHandoffLog(handoffs));
+    }
+    catch (err) {
+        console.error(pc.red(`Error reading handoff history: ${err.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("show")
+    .argument("<task-id>", "Handoff task id or 'latest'")
+    .description("Print a local handoff brief")
+    .action(async (taskId) => {
+    try {
+        const markdown = await readHandoff(process.cwd(), taskId);
+        process.stdout.write(markdown.endsWith("\n") ? markdown : markdown + "\n");
+    }
+    catch (err) {
+        console.error(pc.red(`Error reading handoff: ${err.message}`));
+        process.exit(1);
+    }
+});
+program
+    .command("doctor")
+    .description("Validate environment, Codex availability, and .gitignore safety")
+    .action(async () => {
+    const code = await runDoctor();
+    process.exit(code);
+});
+program.parseAsync();