knoxis-helper 1.7.1 → 1.7.2

package/lib/knoxis-interactive-pair.js

@@ -36,6 +36,7 @@ const os = require('os');
 const { SessionRecorder } = require('./session-recorder');
 const { scaffoldStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
+const kitTemplates = require('./templates');
 
 // === CONFIG ===
 const CONFIG_PATH = path.join(os.homedir(), '.knoxis', 'config.json');
@@ -354,10 +355,89 @@ async function finalizeSession(recorder) {
   }
 }
 
+// === KIT MODE (kickoff / resume) ===
+// When the local agent routes a kit mode here, it sets KNOXIS_KIT_MODE so we
+// load the matching kit template (the same module pair-program.js uses) and
+// run it as a single Claude turn via runClaudeTurn — i.e. through `claude -p
+// --session-id`, which has the file-writing tool access the kit prompts need.
+// The 4-phase Groq flow is bypassed entirely; kit prompts are self-contained
+// frameworks with their own state machine.
+async function runKitMode(kitMode, task, identity, scaffoldResult) {
+  const archetype = process.env.KNOXIS_KIT_ARCHETYPE || null;
+  const pattern = process.env.KNOXIS_KIT_PATTERN || null;
+  let tpl;
+  try {
+    tpl = kitTemplates.getTemplate(kitMode, {
+      taskDescription: task || null,
+      archetype,
+      pattern,
+      productSlug: identity.productSlug,
+      projectSlug: identity.projectSlug,
+      workspace: identity.workspace
+    });
+  } catch (e) {
+    console.error('Kit template error: ' + e.message);
+    process.exit(1);
+  }
+
+  const recorder = new SessionRecorder(task || `[${kitMode} session]`, identity.workspace, 'Claude Code (kit)', {
+    mode: kitMode,
+    archetype,
+    productSlug: identity.productSlug,
+    projectSlug: identity.projectSlug,
+    engineerId: identity.engineerId,
+    userId: identity.userId,
+    workspaceId: identity.workspaceId,
+    taskIds: identity.taskIds
+  });
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        KNOXIS KIT MODE: ' + kitMode.toUpperCase().padEnd(36) + '║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log('  Mode:      ' + kitMode + (archetype ? ' (archetype: ' + archetype + ')' : ''));
+  console.log('  Workspace: ' + identity.workspace);
+  console.log('  Session:   ' + SESSION_ID);
+  console.log('  Recorded:  ' + recorder.sessionId);
+  if (task) console.log('  Hint:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
+  if (scaffoldResult && (scaffoldResult.dirs.length || scaffoldResult.files.length)) {
+    console.log('  Scaffolded: ' + (scaffoldResult.dirs.length + scaffoldResult.files.length) + ' new entries (CODING_RULES + docs/state/)');
+  }
+  console.log('');
+
+  appendLog('# Knoxis Kit Mode: ' + kitMode);
+  appendLog('Session: ' + SESSION_ID);
+  if (task) appendLog('Hint: ' + task);
+  appendLog('Date: ' + new Date().toISOString());
+  appendLog('');
+
+  const stepKey = 'kit-' + kitMode;
+  const stepIdx = recorder.startStep(stepKey, 'Claude Code', tpl.body);
+  recorder.setStepPrompt(stepIdx, tpl.body);
+  const result = await runClaudeTurn(tpl.body, false);
+  appendLog(result.stdout.substring(0, 10000) + '\n');
+  recorder.completeStep(stepIdx, result.stdout, result.code !== 0 ? 'exit ' + result.code + (result.stderr ? ': ' + result.stderr.slice(0, 200) : '') : null);
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        KIT SESSION COMPLETE                                 ║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  const logFile = saveSessionLog();
+  if (logFile) console.log('  Log: ' + logFile);
+  console.log('  Resume: claude --resume ' + SESSION_ID);
+  console.log('');
+
+  await finalizeSession(recorder);
+  process.exit(result.code || 0);
+}
+
 // === MAIN ===
 async function main() {
+  const kitMode = process.env.KNOXIS_KIT_MODE || null;
   const task = loadTask();
-  if (!task) {
+  if (!task && !kitMode) {
     console.error('No task found. Set KNOXIS_TASK_FILE, pass as CLI argument, or include in CLAUDE.md.');
     process.exit(1);
   }
@@ -376,6 +456,17 @@ async function main() {
     console.warn('  Scaffold failed: ' + e.message);
   }
 
+  // Kit modes (kickoff/resume) take a different path: run the kit template as
+  // a single Claude turn. Skips the 4-phase Groq plan/implement/verify flow —
+  // the kit prompt is the framework.
+  if (kitMode) {
+    if (!kitTemplates.isKitMode(kitMode)) {
+      console.error('Unknown KNOXIS_KIT_MODE "' + kitMode + '". Supported: ' + kitTemplates.listModes().join(', '));
+      process.exit(1);
+    }
+    return runKitMode(kitMode, task, identity, scaffoldResult);
+  }
+
   const recorder = new SessionRecorder(task, identity.workspace, 'Claude Code + Knoxis (Groq)', {
     mode: null,             // interactive flow isn't a kit mode
     archetype: null,

package/lib/knoxis-local-agent.js

@@ -595,6 +595,13 @@ function resolvePairProgramScript() {
 }
 
 const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
+// kickoff and resume rely on Claude actually writing files to disk
+// (docs/state/OPEN_QUESTIONS.md and the rest of the context pack). The
+// interactive runner invokes `claude -p --session-id`, which gives Claude
+// proper tool access; pair-program.js pipes to `claude` without -p and
+// silently skips the file writes. Route those two kits through the
+// interactive runner so their kit prompts actually do their work.
+const KIT_MODES_VIA_INTERACTIVE = new Set(['kickoff', 'resume']);
 
 function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
   const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;
@@ -965,11 +972,28 @@ async function handleRequest(req, res) {
       // 4-step pipeline. Interactive (Groq) mode and the legacy claude-pipe
       // fallback remain available when the runner isn't present.
       const ppScript = resolvePairProgramScript();
-      if (kitMode && !ppScript) {
+      const kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
+      if (kitMode && !kitViaInteractive && !ppScript) {
         return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
       }
-
-      if (kitMode || (ppScript && !interactive && promptText)) {
+      if (kitViaInteractive) {
+        const scriptPath = resolveInteractiveScript();
+        if (!scriptPath) {
+          return sendJSON(res, 500, { success: false, error: 'knoxis-interactive-pair.js not found — reinstall knoxis-helper.' }, requestOrigin);
+        }
+        const kitEnv = { KNOXIS_WORKSPACE_PATH: workspaceDir, KNOXIS_KIT_MODE: kitMode };
+        if (promptText) kitEnv.KNOXIS_TASK_FILE = promptFile;
+        if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
+        if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
+        if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+        if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+        if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
+        if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+        if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+        command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
+        mode = `kit:${kitMode}${archetype ? `/${archetype}` : ''}`;
+        console.log(`🧰 Kit (interactive runner): ${mode} — ${scriptPath}`);
+      } else if (kitMode || (ppScript && !interactive && promptText)) {
         command = buildPairProgramCommand({
           scriptPath: ppScript,
           workspace: workspaceDir,
@@ -1447,9 +1471,35 @@ function connectRelayWebSocket() {
           ? msg.taskIds.filter(t => typeof t === 'string' && t)
           : (typeof msg.taskId === 'string' ? [msg.taskId] : []);
         const ppScript = resolvePairProgramScript();
-        const routeViaPairProgram = (kitMode || (ppScript && !interactive && taskPrompt));
-
-        if (routeViaPairProgram && ppScript) {
+        const kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
+        const routeViaPairProgram = !kitViaInteractive && (kitMode || (ppScript && !interactive && taskPrompt));
+
+        if (kitViaInteractive) {
+          const scriptPath = resolveInteractiveScript();
+          if (scriptPath) {
+            // kickoff/resume need Claude's tool path (claude -p --session-id),
+            // which the interactive runner provides. Pass the kit mode + identity
+            // via env so the runner picks the kit branch instead of the 4-phase
+            // Groq flow.
+            if (taskPrompt) {
+              promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
+              fs.writeFileSync(promptFile, taskPrompt, 'utf8');
+            }
+            const kitEnv = { KNOXIS_WORKSPACE_PATH: wsDir, KNOXIS_KIT_MODE: kitMode };
+            if (promptFile) kitEnv.KNOXIS_TASK_FILE = promptFile;
+            if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
+            if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
+            if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+            if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+            if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
+            if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+            if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+            command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
+            console.log(`   🧰 Kit (interactive runner): ${kitMode}${archetype ? `/${archetype}` : ''} — ${scriptPath}`);
+          } else {
+            console.warn(`   ⚠️ knoxis-interactive-pair.js not found — cannot run kit mode ${kitMode}`);
+          }
+        } else if (routeViaPairProgram && ppScript) {
           command = buildPairProgramCommand({
             scriptPath: ppScript,
             workspace: wsDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"