@mandipadk7/kavi 0.1.1 → 0.1.3

package/README.md

@@ -3,17 +3,21 @@
 Kavi is a local terminal control plane for managed Codex and Claude collaboration.
 
 Current capabilities:
-- `kavi init`: create repo-local `.kavi` config, prompt files, and ignore rules.
+- `kavi init`: create repo-local `.kavi` config, prompt files, ignore rules, and bootstrap git if the folder is not already a repository.
 - `kavi init --home`: also scaffold the user-local config file used for binary overrides.
+- `kavi init --no-commit`: skip the bootstrap commit and let `kavi open` or `kavi start` create the first base commit later.
 - `kavi doctor`: verify Node, Codex, Claude, git worktree support, and local readiness.
 - `kavi start`: start a managed session without attaching the TUI.
-- `kavi open`: create a managed session with separate Codex and Claude worktrees and open the terminal dashboard.
-- `kavi resume`: reopen the dashboard for the current repo session.
+- `kavi open`: create a managed session with separate Codex and Claude worktrees and open the full-screen operator console, even from an empty folder or a repo with no `HEAD` yet.
+- `kavi resume`: reopen the operator console for the current repo session.
 - `kavi status`: inspect session health and task counts from any terminal.
 - `kavi paths`: inspect resolved repo-local, user-local, worktree, and runtime paths.
 - `kavi task`: enqueue a task for `codex`, `claude`, or `auto` routing.
 - `kavi tasks`: inspect the session task list with summaries and artifact availability.
 - `kavi task-output`: inspect the normalized envelope and raw output for a completed task.
+- `kavi decisions`: inspect the persisted routing, approval, task, and integration decisions.
+- `kavi claims`: inspect active or historical path claims.
+- `kavi reviews`: inspect persisted operator review threads and linked follow-up tasks.
 - `kavi approvals`: inspect the approval inbox.
 - `kavi approve` and `kavi deny`: resolve a pending approval request, optionally with `--remember`.
 - `kavi events`: inspect recent daemon and task events.
@@ -25,11 +29,15 @@ Runtime model:
 - Machine-local state defaults to `~/.config/kavi` and `~/.local/state/kavi`.
 - In restricted environments you can override those with `KAVI_HOME_CONFIG_DIR` and `KAVI_HOME_STATE_DIR`.
 - User-local runtime overrides live in `~/.config/kavi/config.toml` and can point Kavi at custom `node`, `codex`, and `claude` binaries.
+- The operator surface talks to the daemon over a local control socket under the machine-local state root.
 - SQLite event mirroring is opt-in with `KAVI_ENABLE_SQLITE_HISTORY=1`; the default event log is JSONL under `.kavi/state/events.jsonl`.
+- The operator console exposes a task board, dual agent lanes, a live inspector pane, approval actions, inline task composition, worktree diff review with file and hunk navigation, and persisted operator review threads on files or hunks.
 
 Development:
 
 ```bash
+# works in an empty folder; Kavi will initialize git and create the
+# bootstrap commit it needs for managed worktrees
 node bin/kavi.js init --home
 node bin/kavi.js doctor --json
 node bin/kavi.js paths
@@ -38,15 +46,22 @@ node bin/kavi.js status
 node bin/kavi.js task --agent auto "Design the dashboard shell"
 node bin/kavi.js tasks
 node bin/kavi.js task-output latest
+node bin/kavi.js decisions
+node bin/kavi.js claims
+node bin/kavi.js reviews
 node bin/kavi.js approvals
 node bin/kavi.js open
-node --experimental-strip-types --test src/**/*.test.ts
+npm test
 ```
 
 Notes:
+- `kavi init` and `kavi open` now support the "empty folder to first managed session" path. If no git repo exists, Kavi initializes one; if git exists but no `HEAD` exists yet, Kavi creates the bootstrap commit it needs for worktrees.
 - Codex runs through `codex app-server` in managed mode, so Codex-side approvals now land in the same Kavi inbox as Claude hook approvals.
 - Claude still runs through the installed `claude` CLI with Kavi-managed hooks and approval decisions.
-- The dashboard uses a file-backed control loop instead of local sockets so it can run in restricted shells and sandboxes.
+- The dashboard and operator commands now use the daemon's local RPC socket instead of editing session files directly, and the TUI stays updated from pushed daemon snapshots rather than polling.
+- The socket is machine-local rather than repo-local to avoid Unix socket path-length issues in deep repos and temp directories.
+- The console is keyboard-driven: `1-7` switch views, `j/k` move selection, `[` and `]` cycle task detail sections, `,` and `.` cycle changed files, `{` and `}` cycle patch hunks, `A/C/Q/M` add review notes, `o/O` cycle existing threads, `T` reply, `E` edit, `R` resolve or reopen, `F` queue a fix task, `H` queue a handoff task, `y/n` resolve approvals, and `c` opens the inline task composer.
+- Successful follow-up tasks now auto-resolve linked open review threads, landed follow-up work marks those resolved threads as landed, and replying to a resolved thread reopens it.
 
 Local install options:
 
@@ -98,6 +113,7 @@ Notes on publish:
 - The package name is scoped as `@mandipadk7/kavi` to match the npm user `mandipadk7`.
 - The publish flow now builds a compiled `dist/` directory first, and the installed CLI prefers `dist/main.js`. Source mode remains available for local development.
 - Hook commands now invoke the compiled entrypoint directly when `dist/` is present, and only use `--experimental-strip-types` in source mode.
+- The interactive publish script strips `repository`, `homepage`, and `bugs` from the packaged `package.json`, so the npm page uses the bundled `README.md` instead of private GitHub links.
 - `prepublishOnly` runs the release checks automatically during publish.
 
 User-local config example:

package/dist/adapters/claude.js

@@ -3,6 +3,80 @@ import { buildAgentInstructions, buildPeerMessages, buildTaskPrompt, extractJson
 import { runCommand } from "../process.js";
 import { loadAgentPrompt } from "../prompts.js";
 import { buildKaviShellCommand } from "../runtime.js";
+const CLAUDE_ENVELOPE_SCHEMA = JSON.stringify({
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "summary",
+        "status",
+        "blockers",
+        "nextRecommendation",
+        "peerMessages"
+    ],
+    properties: {
+        summary: {
+            type: "string"
+        },
+        status: {
+            type: "string",
+            enum: [
+                "completed",
+                "blocked",
+                "needs_review"
+            ]
+        },
+        blockers: {
+            type: "array",
+            items: {
+                type: "string"
+            }
+        },
+        nextRecommendation: {
+            type: [
+                "string",
+                "null"
+            ]
+        },
+        peerMessages: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "to",
+                    "intent",
+                    "subject",
+                    "body"
+                ],
+                properties: {
+                    to: {
+                        type: "string",
+                        enum: [
+                            "codex",
+                            "claude"
+                        ]
+                    },
+                    intent: {
+                        type: "string",
+                        enum: [
+                            "question",
+                            "handoff",
+                            "review_request",
+                            "blocked",
+                            "context_share"
+                        ]
+                    },
+                    subject: {
+                        type: "string"
+                    },
+                    body: {
+                        type: "string"
+                    }
+                }
+            }
+        }
+    }
+});
 function findWorktree(session, agent) {
     const worktree = session.worktrees.find((item)=>item.agent === agent);
     if (!worktree) {
@@ -10,6 +84,47 @@ function findWorktree(session, agent) {
     }
     return worktree;
 }
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function normalizeEnvelope(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const parsed = value;
+        return {
+            summary: typeof parsed.summary === "string" ? parsed.summary : "",
+            status: parsed.status === "blocked" || parsed.status === "needs_review" ? parsed.status : "completed",
+            blockers: Array.isArray(parsed.blockers) ? parsed.blockers.map((item)=>String(item)) : [],
+            nextRecommendation: parsed.nextRecommendation === null || typeof parsed.nextRecommendation === "string" ? parsed.nextRecommendation : null,
+            peerMessages: Array.isArray(parsed.peerMessages) ? parsed.peerMessages.map((message)=>{
+                const payload = asObject(message);
+                return {
+                    to: payload.to === "codex" ? "codex" : "claude",
+                    intent: payload.intent === "handoff" || payload.intent === "review_request" || payload.intent === "blocked" || payload.intent === "context_share" ? payload.intent : "question",
+                    subject: String(payload.subject ?? ""),
+                    body: String(payload.body ?? "")
+                };
+            }) : []
+        };
+    }
+    return extractJsonObject(String(value ?? ""));
+}
+export function parseClaudeStructuredOutput(rawOutput, fallbackSessionId) {
+    const parsed = JSON.parse(rawOutput);
+    const wrapper = Array.isArray(parsed) ? asObject(parsed[parsed.length - 1]) : asObject(parsed);
+    const sessionId = asString(wrapper.session_id) ?? asString(wrapper.sessionId) ?? fallbackSessionId;
+    const resultPayload = "result" in wrapper ? wrapper.result : "content" in wrapper ? wrapper.content : parsed;
+    if (wrapper.is_error === true) {
+        throw new Error(asString(wrapper.result) ?? "Claude returned an error response.");
+    }
+    return {
+        envelope: normalizeEnvelope(resultPayload),
+        sessionId,
+        raw: rawOutput
+    };
+}
 export async function writeClaudeSettings(paths, session) {
     const buildHookCommand = (event)=>buildKaviShellCommand(session.runtime, [
             "__hook",
@@ -89,7 +204,7 @@ export async function writeClaudeSettings(paths, session) {
 }
 export async function runClaudeTask(session, task, paths) {
     const worktree = findWorktree(session, "claude");
-    const claudeSessionId = `${session.id}-claude`;
+    const claudeSessionId = session.agentStatus.claude.sessionId ?? `${session.id}-claude`;
     await writeClaudeSettings(paths, session);
     const repoPrompt = await loadAgentPrompt(paths, "claude");
     const prompt = [
@@ -99,22 +214,30 @@ export async function runClaudeTask(session, task, paths) {
     ].join("\n");
     const result = await runCommand(session.runtime.claudeExecutable, [
         "-p",
-        "--session-id",
-        claudeSessionId,
+        "--output-format",
+        "json",
+        "--json-schema",
+        CLAUDE_ENVELOPE_SCHEMA,
         "--settings",
         paths.claudeSettingsFile,
         "--permission-mode",
         "plan",
+        ...session.agentStatus.claude.sessionId ? [
+            "--resume",
+            claudeSessionId
+        ] : [
+            "--session-id",
+            claudeSessionId
+        ],
         prompt
     ], {
         cwd: worktree.path
     });
     const rawOutput = result.code === 0 ? result.stdout : `${result.stdout}\n${result.stderr}`;
-    const envelope = extractJsonObject(rawOutput);
-    return {
-        envelope,
-        raw: rawOutput
-    };
+    if (result.code !== 0) {
+        throw new Error(rawOutput.trim() || "Claude task failed.");
+    }
+    return parseClaudeStructuredOutput(rawOutput, claudeSessionId);
 }
 export { buildPeerMessages };
 

package/dist/adapters/shared.js

@@ -1,5 +1,21 @@
 import { randomUUID } from "node:crypto";
 import { nowIso } from "../paths.js";
+function formatDecisionLine(summary, detail) {
+    return detail.trim() ? `- ${summary}: ${detail}` : `- ${summary}`;
+}
+export function buildDecisionReplay(session, task, agent) {
+    const taskDecisions = session.decisions.filter((decision)=>decision.taskId === task.id).slice(-6).map((decision)=>formatDecisionLine(`[${decision.kind}] ${decision.summary}`, decision.detail));
+    const sharedDecisions = session.decisions.filter((decision)=>decision.taskId !== task.id && (decision.agent === agent || decision.agent === null)).slice(-4).map((decision)=>formatDecisionLine(`[${decision.kind}] ${decision.summary}`, decision.detail));
+    const relevantClaims = session.pathClaims.filter((claim)=>claim.status === "active" && (claim.taskId === task.id || claim.agent !== agent)).slice(-6).map((claim)=>`- ${claim.agent} ${claim.source} claim on ${claim.paths.join(", ")}${claim.note ? `: ${claim.note}` : ""}`);
+    const replay = [
+        `- Current route reason: ${task.routeReason ?? "not recorded"}`,
+        `- Current claimed paths: ${task.claimedPaths.join(", ") || "none"}`,
+        ...taskDecisions,
+        ...sharedDecisions,
+        ...relevantClaims
+    ];
+    return replay.slice(0, 16);
+}
 export function extractJsonObject(rawOutput) {
     const trimmed = rawOutput.trim();
     const fencedMatch = trimmed.match(/```json\s*([\s\S]*?)```/i);
@@ -36,15 +52,15 @@ export function buildPeerMessages(envelope, from, taskId) {
 export function buildSharedContext(session, task, agent) {
     const inbox = session.peerMessages.filter((message)=>message.to === agent).slice(-session.config.messageLimit).map((message)=>`- [${message.intent}] ${message.subject}: ${message.body}`).join("\n");
     const tasks = session.tasks.map((item)=>`- ${item.id} | ${item.owner} | ${item.status} | ${item.title}`).join("\n");
-    const decisions = session.decisions.slice(-6).map((decision)=>`- [${decision.kind}] ${decision.summary}`).join("\n");
+    const decisionReplay = buildDecisionReplay(session, task, agent).join("\n");
     const claims = session.pathClaims.filter((claim)=>claim.status === "active").slice(-6).map((claim)=>`- ${claim.agent} | ${claim.paths.join(", ")}`).join("\n");
     return [
         `Session goal: ${session.goal ?? "No goal recorded."}`,
         `Current task: ${task.title}`,
         "Task board:",
         tasks || "- none",
-        "Decision ledger:",
-        decisions || "- empty",
+        "Compaction-safe replay:",
+        decisionReplay || "- empty",
         "Active path claims:",
         claims || "- empty",
         `Peer inbox for ${agent}:`,