@mandipadk7/kavi 0.1.0 → 0.1.2

package/README.md

@@ -7,13 +7,15 @@ Current capabilities:
 - `kavi init --home`: also scaffold the user-local config file used for binary overrides.
 - `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.
+- `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 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,7 +27,9 @@ 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, and worktree diff review with file and hunk navigation.
 
 Development:
 
@@ -38,14 +42,19 @@ 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 approvals
 node bin/kavi.js open
-node --experimental-strip-types --test src/**/*.test.ts
+npm test
 ```
 
 Notes:
-- The current managed task runners use the installed `codex` and `claude` CLIs directly.
-- The dashboard uses a file-backed control loop instead of local sockets so it can run in restricted shells and sandboxes.
+- 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 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, `y/n` resolve approvals, and `c` opens the inline task composer.
 
 Local install options:
 
@@ -63,17 +72,24 @@ npm link
 Publishing for testers:
 
 ```bash
+# interactive publish flow: prompts for version, defaults to the next patch,
+# runs release checks, then publishes the beta tag
+npm run publish
+
 # authenticate once
 npm login
 
 # verify the package before publish
 npm run release:check
 
-# publish a beta that friends can install immediately
+# prompt for version and publish beta explicitly
 npm run publish:beta
 
-# later, publish the stable tag
+# prompt for version and publish stable
 npm run publish:latest
+
+# test the publish flow without sending anything to npm
+npm run publish -- --dry-run
 ```
 
 Install commands for testers:
@@ -89,6 +105,8 @@ npx @mandipadk7/kavi@beta help
 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

@@ -1,7 +1,82 @@
 import fs from "node:fs/promises";
-import { buildEnvelopeInstruction, buildPeerMessages, buildSharedContext, extractJsonObject } from "./shared.js";
+import { buildAgentInstructions, buildPeerMessages, buildTaskPrompt, extractJsonObject } from "./shared.js";
 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) {
@@ -9,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",
@@ -88,33 +204,40 @@ 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 = [
-        buildSharedContext(session, task, "claude"),
+        buildAgentInstructions("claude", worktree.path, repoPrompt),
         "",
-        `User goal or prompt:\n${task.prompt}`,
-        "",
-        buildEnvelopeInstruction("claude", worktree.path)
+        buildTaskPrompt(session, task, "claude")
     ].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/codex.js

@@ -1,7 +1,82 @@
-import path from "node:path";
-import fs from "node:fs/promises";
-import { runCommand } from "../process.js";
-import { buildEnvelopeInstruction, buildPeerMessages, buildSharedContext, extractJsonObject } from "./shared.js";
+import { createApprovalRequest, describeCodexApprovalRequest, findApprovalRule, waitForApprovalDecision } from "../approvals.js";
+import { CodexAppServerClient } from "../codex-app-server.js";
+import { loadAgentPrompt } from "../prompts.js";
+import { recordEvent } from "../session.js";
+import { buildAgentInstructions, buildPeerMessages, buildTaskPrompt, extractJsonObject } from "./shared.js";
+const ENVELOPE_OUTPUT_SCHEMA = {
+    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) {
@@ -9,35 +84,165 @@ 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 supportsSessionApproval(params) {
+    return Array.isArray(params.availableDecisions) ? params.availableDecisions.some((value)=>value === "acceptForSession") : false;
+}
+function buildPermissionsGrant(params) {
+    const requested = asObject(params.permissions);
+    const granted = {};
+    if (requested.network !== null && requested.network !== undefined) {
+        granted.network = requested.network;
+    }
+    if (requested.fileSystem !== null && requested.fileSystem !== undefined) {
+        granted.fileSystem = requested.fileSystem;
+    }
+    return granted;
+}
+function buildApprovalResponse(method, params, approved, remember) {
+    switch(method){
+        case "item/commandExecution/requestApproval":
+            return {
+                decision: approved ? remember && supportsSessionApproval(params) ? "acceptForSession" : "accept" : "decline"
+            };
+        case "item/fileChange/requestApproval":
+            return {
+                decision: approved ? remember ? "acceptForSession" : "accept" : "decline"
+            };
+        case "item/permissions/requestApproval":
+            return {
+                permissions: approved ? buildPermissionsGrant(params) : {},
+                scope: remember ? "session" : "turn"
+            };
+        case "execCommandApproval":
+        case "applyPatchApproval":
+            return {
+                decision: approved ? remember ? "approved_for_session" : "approved" : "denied"
+            };
+        default:
+            throw new Error(`Unsupported Codex approval request: ${method}`);
+    }
+}
+function buildThreadParams(session, worktree, developerInstructions) {
+    const configuredModel = session.config.agents.codex.model.trim();
+    return {
+        cwd: worktree.path,
+        approvalPolicy: "on-request",
+        approvalsReviewer: "user",
+        sandbox: "workspace-write",
+        baseInstructions: "You are Codex inside Kavi. Operate inside the assigned worktree and keep work task-scoped.",
+        developerInstructions,
+        model: configuredModel || null,
+        ephemeral: false,
+        experimentalRawEvents: false,
+        persistExtendedHistory: true
+    };
+}
+async function ensureThread(client, session, paths, worktree, developerInstructions) {
+    const threadParams = buildThreadParams(session, worktree, developerInstructions);
+    const existingThreadId = session.agentStatus.codex.sessionId;
+    if (existingThreadId) {
+        try {
+            return await client.resumeThread({
+                threadId: existingThreadId,
+                ...threadParams
+            });
+        } catch (error) {
+            await recordEvent(paths, session.id, "codex.thread_resume_failed", {
+                threadId: existingThreadId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return await client.startThread(threadParams);
+}
+async function handleCodexApproval(session, paths, request) {
+    const descriptor = describeCodexApprovalRequest(request.method, request.params);
+    const rule = await findApprovalRule(paths, {
+        repoRoot: session.repoRoot,
+        agent: "codex",
+        toolName: descriptor.toolName,
+        matchKey: descriptor.matchKey
+    });
+    if (rule) {
+        await recordEvent(paths, session.id, "approval.auto_decided", {
+            agent: "codex",
+            requestId: request.id,
+            method: request.method,
+            toolName: descriptor.toolName,
+            summary: descriptor.summary,
+            decision: rule.decision
+        });
+        return buildApprovalResponse(request.method, request.params, rule.decision === "allow", true);
+    }
+    const approval = await createApprovalRequest(paths, {
+        sessionId: session.id,
+        repoRoot: session.repoRoot,
+        agent: "codex",
+        hookEvent: request.method,
+        payload: request.params,
+        toolName: descriptor.toolName,
+        summary: descriptor.summary,
+        matchKey: descriptor.matchKey
+    });
+    await recordEvent(paths, session.id, "approval.requested", {
+        requestId: approval.id,
+        agent: "codex",
+        method: request.method,
+        toolName: approval.toolName,
+        summary: approval.summary
+    });
+    const resolved = await waitForApprovalDecision(paths, approval.id);
+    const approved = resolved?.status === "approved";
+    const remember = resolved?.remember ?? false;
+    await recordEvent(paths, session.id, "approval.completed", {
+        requestId: approval.id,
+        agent: "codex",
+        method: request.method,
+        outcome: approved ? "approved" : resolved?.status === "denied" ? "denied" : "expired"
+    });
+    return buildApprovalResponse(request.method, request.params, approved, remember);
+}
 export async function runCodexTask(session, task, paths) {
     const worktree = findWorktree(session, "codex");
-    const outputFile = path.join(paths.runtimeDir, `codex-${task.id}.txt`);
-    const prompt = [
-        buildSharedContext(session, task, "codex"),
-        "",
-        `User goal or prompt:\n${task.prompt}`,
-        "",
-        buildEnvelopeInstruction("codex", worktree.path)
-    ].join("\n");
-    const result = await runCommand(session.runtime.codexExecutable, [
-        "exec",
-        "--skip-git-repo-check",
-        "--cd",
-        worktree.path,
-        "--sandbox",
-        "workspace-write",
-        "--output-last-message",
-        outputFile,
-        prompt
-    ], {
-        cwd: session.repoRoot
+    const repoPrompt = await loadAgentPrompt(paths, "codex");
+    const developerInstructions = buildAgentInstructions("codex", worktree.path, repoPrompt);
+    const client = new CodexAppServerClient(session.runtime, session.repoRoot, async (request)=>{
+        return await handleCodexApproval(session, paths, request);
     });
-    const rawOutput = result.code === 0 ? await fs.readFile(outputFile, "utf8") : `${result.stdout}\n${result.stderr}`;
-    const envelope = extractJsonObject(rawOutput);
-    return {
-        envelope,
-        raw: rawOutput
-    };
+    try {
+        await client.initialize();
+        const threadId = await ensureThread(client, session, paths, worktree, developerInstructions);
+        const result = await client.runTurn({
+            threadId,
+            cwd: worktree.path,
+            approvalPolicy: "on-request",
+            approvalsReviewer: "user",
+            model: session.config.agents.codex.model.trim() || null,
+            outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+            input: [
+                {
+                    type: "text",
+                    text: buildTaskPrompt(session, task, "codex"),
+                    text_elements: []
+                }
+            ]
+        });
+        const rawOutput = `${result.assistantMessage}${result.stderr ? `\n\n[stderr]\n${result.stderr}` : ""}`;
+        const envelope = extractJsonObject(result.assistantMessage);
+        return {
+            envelope,
+            raw: rawOutput,
+            threadId
+        };
+    } finally{
+        await client.close();
+    }
 }
 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,28 @@ 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 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",
+        "Compaction-safe replay:",
+        decisionReplay || "- empty",
+        "Active path claims:",
+        claims || "- empty",
         `Peer inbox for ${agent}:`,
         inbox || "- empty"
     ].join("\n");
 }
+export function buildTaskPrompt(session, task, agent) {
+    return [
+        buildSharedContext(session, task, agent),
+        "",
+        `User goal or prompt:\n${task.prompt}`
+    ].join("\n");
+}
 export function buildEnvelopeInstruction(agent, worktreePath) {
     const peer = agent === "codex" ? "claude" : "codex";
     const focus = agent === "codex" ? "Focus on planning, architecture, backend concerns, codebase structure, and implementation risks." : "Focus on intent, user experience, frontend structure, and interaction quality.";
@@ -64,6 +93,12 @@ export function buildEnvelopeInstruction(agent, worktreePath) {
         "Do not wrap the JSON in Markdown."
     ].join("\n");
 }
+export function buildAgentInstructions(agent, worktreePath, repoPrompt) {
+    return [
+        repoPrompt.trim(),
+        buildEnvelopeInstruction(agent, worktreePath)
+    ].filter(Boolean).join("\n\n");
+}
 
 
 //# sourceURL=adapters/shared.ts