codekanban 0.26.0 → 0.27.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "codekanban",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "An auxiliary programming tool for the AI era, helping you speed up 10x.",
   "bin": {
     "codekanban": "npm-bin/codekanban.js"
   },
   "optionalDependencies": {
-    "@codekanban/win32-x64": "0.26.0",
-    "@codekanban/darwin-x64": "0.26.0",
-    "@codekanban/darwin-arm64": "0.26.0",
-    "@codekanban/linux-x64": "0.26.0",
-    "@codekanban/linux-arm64": "0.26.0"
+    "@codekanban/win32-x64": "0.27.0",
+    "@codekanban/darwin-x64": "0.27.0",
+    "@codekanban/darwin-arm64": "0.27.0",
+    "@codekanban/linux-x64": "0.27.0",
+    "@codekanban/linux-arm64": "0.27.0"
   },
   "keywords": [
     "ai",

package/packages/node-sdk/README.md

@@ -11,6 +11,12 @@ Node SDK and CLI for CodeKanban project workflows.
 - Support `standard`, `plan`, and `yolo` Codex profiles
 - Read terminal session lists and AI session summaries
 - Read AI conversations and continue existing terminal sessions
+- Control CodeKanban `web session` runs over HTTP and WebSocket
+- Read `web session` snapshots, history, runtime config, command groups, and archived sessions
+- Send `web session` messages, approvals, user-input answers, model/workflow/permission updates, and move operations
+- Receive normalized `web session` events through `on/off`, `waitFor`, or `for await`
+- Poll a `web session` for a derived actionable state instead of reconstructing history logic yourself
+- Execute the latest plan or answer the active structured prompt with one SDK call
 
 ## CLI
 
@@ -21,6 +27,19 @@ node packages/node-sdk/bin/codekanban-sdk.js session conversation --base-url htt
 node packages/node-sdk/bin/codekanban-sdk.js terminal continue --base-url http://127.0.0.1:3000 --session-id <terminal-session-id> --prompt "Continue from the previous plan"
 ```
 
+### Web Session CLI
+
+```bash
+node packages/node-sdk/bin/codekanban-sdk.js web-session create --base-url http://127.0.0.1:3000 --path D:\repo --agent codex --workflow-mode plan --permission-level elevated --title "Planning session"
+node packages/node-sdk/bin/codekanban-sdk.js web-session snapshot --base-url http://127.0.0.1:3000 --project-id <project-id> --session-id <session-id> --limit 80
+node packages/node-sdk/bin/codekanban-sdk.js web-session send --base-url http://127.0.0.1:3000 --session-id <session-id> --text "Continue from the last plan"
+node packages/node-sdk/bin/codekanban-sdk.js web-session approve --base-url http://127.0.0.1:3000 --session-id <session-id>
+node packages/node-sdk/bin/codekanban-sdk.js web-session user-input --base-url http://127.0.0.1:3000 --session-id <session-id> --item-id <item-id> --answers-json '{"scope":["full repo"]}'
+node packages/node-sdk/bin/codekanban-sdk.js web-session watch --base-url http://127.0.0.1:3000 --session-id <session-id> --max-events 20
+```
+
+`web-session watch` writes NDJSON. Add `--raw` to print raw short-key protocol frames.
+
 ## Library
 
 ```js
@@ -37,3 +56,117 @@ const result = await client.startWorkflow({
   },
 });
 ```
+
+### Web Session HTTP
+
+```js
+const client = new CodeKanbanClient({ baseURL: 'http://127.0.0.1:3000' });
+
+const session = await client.createWebSession({
+  path: 'D:/repo',
+  agent: 'codex',
+  workflowMode: 'plan',
+  permissionLevel: 'elevated',
+  title: 'Planning session',
+});
+
+const snapshot = await client.getWebSessionSnapshot({
+  projectId: session.projectId,
+  sessionId: session.id,
+});
+```
+
+### Polling-Friendly Web Session State
+
+```js
+const state = await client.getWebSessionState({
+  projectId: session.projectId,
+  sessionId: session.id,
+});
+
+if (state.phase === 'running') {
+  return;
+}
+
+if (state.nextAction?.type === 'answer_user_input') {
+  await client.answerPendingUserInput({
+    projectId: session.projectId,
+    sessionId: session.id,
+    answers: {
+      scope: ['full repo'],
+    },
+  });
+}
+
+if (state.nextAction?.type === 'execute_plan') {
+  await client.executeLatestPlan({
+    projectId: session.projectId,
+    sessionId: session.id,
+  });
+}
+```
+
+`getWebSessionState()` derives:
+
+- `phase`
+- `canSend`
+- `needsAction`
+- `nextAction`
+- `pendingApproval`
+- `pendingUserInput`
+- `latestPlan`
+- `lastAssistantMessage`
+- `snapshot`
+
+### Waiting With Polling
+
+```js
+const doneState = await client.waitForWebSessionState({
+  projectId: session.projectId,
+  sessionId: session.id,
+  until: 'done',
+  intervalMs: 5000,
+  timeoutMs: 120000,
+});
+
+console.log(doneState.lastAssistantMessage?.text);
+```
+
+### Web Session Command Channel
+
+```js
+const channel = client.openWebSessionCommandChannel();
+await channel.waitForOpen();
+
+await channel.sendMessage(session.id, {
+  text: 'Continue from the latest review.',
+});
+
+await channel.updateWorkflowMode(session.id, {
+  workflowMode: 'plan',
+});
+
+channel.close();
+```
+
+### Web Session Event Stream
+
+```js
+const events = client.openWebSessionEventStream({ sessionId: session.id });
+await events.waitForOpen();
+
+events.on('snapshot', event => {
+  console.log('snapshot', event.snapshot.session.title);
+});
+
+const nextApproval = events.waitFor(event => event.type === 'historyItem' && event.item.detail?.type === 'approval_request');
+
+for await (const event of events) {
+  if (event.type === 'historyItem') {
+    console.log(event.item.itemType, event.item.text);
+  }
+}
+
+await nextApproval;
+events.close();
+```

package/packages/node-sdk/src/cli.js

@@ -10,14 +10,39 @@ function readFlagValue(argv, index, flag) {
   return value;
 }
 
+function parseIntegerFlag(value, fieldName) {
+  if (value == null || value === '') {
+    return undefined;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${fieldName} must be a number`);
+  }
+  return Math.trunc(parsed);
+}
+
+function parseJsonFlag(value, fieldName) {
+  if (!value) {
+    throw new Error(`${fieldName} is required`);
+  }
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${fieldName} must be valid JSON`);
+  }
+}
+
 function parseCliArgs(argv) {
   const positionals = [];
   const flags = {
     addDirs: [],
+    attachmentIds: [],
     extraArgs: [],
     includeTerminal: true,
     includeAI: true,
     refresh: false,
+    clearExisting: false,
+    raw: false,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -44,10 +69,18 @@ function parseCliArgs(argv) {
         flags.prompt = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--text':
+        flags.text = readFlagValue(argv, index, token);
+        index += 1;
+        break;
       case '--agent':
         flags.agent = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--model':
+        flags.model = readFlagValue(argv, index, token);
+        index += 1;
+        break;
       case '--profile':
         flags.profile = readFlagValue(argv, index, token);
         index += 1;
@@ -64,6 +97,10 @@ function parseCliArgs(argv) {
         flags.addDirs.push(readFlagValue(argv, index, token));
         index += 1;
         break;
+      case '--attachment-id':
+        flags.attachmentIds.push(readFlagValue(argv, index, token));
+        index += 1;
+        break;
       case '--extra-arg':
         flags.extraArgs.push(readFlagValue(argv, index, token));
         index += 1;
@@ -96,9 +133,75 @@ function parseCliArgs(argv) {
         flags.toolUseId = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--reasoning-effort':
+        flags.reasoningEffort = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--workflow-mode':
+        flags.workflowMode = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--permission-level':
+        flags.permissionLevel = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--permission-mode':
+        flags.permissionMode = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--limit':
+        flags.limit = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--before-cursor':
+        flags.beforeCursor = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--mode':
+        flags.mode = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--group-id':
+        flags.groupId = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--file':
+        flags.file = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--item-id':
+        flags.itemId = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--answers-json':
+        flags.answersJson = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--prev-session-id':
+        flags.prevSessionId = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--next-session-id':
+        flags.nextSessionId = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--idle-timeout-ms':
+        flags.idleTimeoutMs = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--max-events':
+        flags.maxEvents = readFlagValue(argv, index, token);
+        index += 1;
+        break;
       case '--refresh':
         flags.refresh = true;
         break;
+      case '--clear-existing':
+        flags.clearExisting = true;
+        break;
+      case '--raw':
+        flags.raw = true;
+        break;
       case '--no-terminal':
         flags.includeTerminal = false;
         break;
@@ -136,6 +239,9 @@ function sanitizeConnection(value) {
   }
   const next = { ...value };
   delete next.connection;
+  delete next.commandChannel;
+  delete next.eventStream;
+  delete next.socket;
   return next;
 }
 
@@ -143,12 +249,88 @@ function printJson(stream, payload) {
   stream.write(createJsonOutput(payload));
 }
 
-export async function runCli(argv) {
+function writeJsonLine(stream, payload) {
+  stream.write(`${JSON.stringify(payload)}\n`);
+}
+
+async function withWebSessionCommandChannel(client, handler) {
+  const channel = client.openWebSessionCommandChannel();
+  try {
+    await channel.waitForOpen();
+    return await handler(channel);
+  } finally {
+    channel.close();
+  }
+}
+
+async function watchWebSession(client, flags, stdout) {
+  const eventStream = client.openWebSessionEventStream({
+    sessionId: flags.sessionId,
+  });
+  const maxEvents = parseIntegerFlag(flags.maxEvents, 'maxEvents');
+  const idleTimeoutMs = parseIntegerFlag(flags.idleTimeoutMs, 'idleTimeoutMs');
+  let eventCount = 0;
+  let idleTimer = null;
+  let closedByPolicy = false;
+
+  const armIdleTimer = () => {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs == null || idleTimeoutMs <= 0) {
+      return;
+    }
+    idleTimer = setTimeout(() => {
+      closedByPolicy = true;
+      eventStream.close();
+    }, idleTimeoutMs);
+  };
+
+  try {
+    await eventStream.waitForOpen();
+    armIdleTimer();
+
+    for await (const event of eventStream) {
+      if (event.type === 'open' || event.type === 'close') {
+        continue;
+      }
+
+      if (event.type === 'error' && event.errorType !== 'frame') {
+        throw event.error instanceof Error ? event.error : new Error(event.message || 'event stream failed');
+      }
+
+      const payload = flags.raw && event.raw ? event.raw : event;
+      writeJsonLine(stdout, payload);
+      eventCount += 1;
+      armIdleTimer();
+
+      if (maxEvents != null && maxEvents > 0 && eventCount >= maxEvents) {
+        closedByPolicy = true;
+        eventStream.close();
+      }
+    }
+
+    return 0;
+  } finally {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+    }
+    if (!closedByPolicy) {
+      eventStream.close();
+    }
+  }
+}
+
+export async function runCli(argv, options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
   try {
     const { positionals, flags } = parseCliArgs(argv);
     const [scope, action] = positionals;
     if (!scope || !action) {
-      throw new Error('usage: <workflow|session|terminal> <action> --base-url <url> [...]');
+      throw new Error('usage: <workflow|session|terminal|web-session> <action> --base-url <url> [...]');
     }
 
     if (scope === 'workflow' && action === 'command') {
@@ -159,7 +341,7 @@ export async function runCli(argv) {
         extraArgs: flags.extraArgs,
         prompt: flags.prompt || 'Inspect the project and respond.',
       });
-      printJson(process.stdout, sanitizeConnection(result));
+      printJson(stdout, sanitizeConnection(result));
       return 0;
     }
 
@@ -210,11 +392,155 @@ export async function runCli(argv) {
         sessionId: flags.sessionId,
         prompt: flags.prompt,
       });
+    } else if (scope === 'web-session' && action === 'list') {
+      result = await client.listWebSessions({
+        projectId: flags.projectId,
+        path: flags.path,
+      });
+    } else if (scope === 'web-session' && action === 'create') {
+      result = await client.createWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        worktreeId: flags.worktreeId,
+        agent: flags.agent,
+        model: flags.model,
+        reasoningEffort: flags.reasoningEffort,
+        workflowMode: flags.workflowMode,
+        permissionLevel: flags.permissionLevel,
+        permissionMode: flags.permissionMode,
+        title: flags.title,
+      });
+    } else if (scope === 'web-session' && action === 'connect') {
+      result = await withWebSessionCommandChannel(client, channel => channel.connect(flags.sessionId));
+    } else if (scope === 'web-session' && action === 'snapshot') {
+      result = await client.getWebSessionSnapshot({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        limit: parseIntegerFlag(flags.limit, 'limit'),
+      });
+    } else if (scope === 'web-session' && action === 'history') {
+      result = await client.getWebSessionHistory({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        beforeCursor: flags.beforeCursor,
+        limit: parseIntegerFlag(flags.limit, 'limit'),
+      });
+    } else if (scope === 'web-session' && action === 'sync') {
+      result = await client.syncWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        mode: flags.mode,
+        clearExisting: flags.clearExisting,
+      });
+    } else if (scope === 'web-session' && action === 'archive') {
+      result = await client.archiveWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+      });
+    } else if (scope === 'web-session' && action === 'unarchive') {
+      result = await client.unarchiveWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+      });
+    } else if (scope === 'web-session' && action === 'rename') {
+      result = await client.renameWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        title: flags.title,
+      });
+    } else if (scope === 'web-session' && action === 'close') {
+      result = await client.closeWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+      });
+    } else if (scope === 'web-session' && action === 'delete') {
+      result = await client.deleteWebSession({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+      });
+    } else if (scope === 'web-session' && action === 'runtime-config') {
+      result = await client.getWebSessionRuntimeConfig();
+    } else if (scope === 'web-session' && action === 'command-group') {
+      result = await client.getWebSessionCommandGroup({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        groupId: flags.groupId,
+      });
+    } else if (scope === 'web-session' && action === 'attach') {
+      result = await client.uploadWebSessionAttachment({
+        projectId: flags.projectId,
+        path: flags.path,
+        filePath: flags.file,
+      });
+    } else if (scope === 'web-session' && action === 'send') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.sendMessage(flags.sessionId, {
+          text: flags.text || flags.prompt,
+          attachmentIds: flags.attachmentIds,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'approve') {
+      result = await withWebSessionCommandChannel(client, channel => channel.approve(flags.sessionId));
+    } else if (scope === 'web-session' && action === 'reject') {
+      result = await withWebSessionCommandChannel(client, channel => channel.reject(flags.sessionId));
+    } else if (scope === 'web-session' && action === 'user-input') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.answerUserInput(flags.sessionId, {
+          itemId: flags.itemId,
+          answers: parseJsonFlag(flags.answersJson, 'answersJson'),
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'set-model') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.updateModel(flags.sessionId, { model: flags.model }),
+      );
+    } else if (scope === 'web-session' && action === 'set-reasoning') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.updateReasoningEffort(flags.sessionId, {
+          reasoningEffort: flags.reasoningEffort,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'set-workflow') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.updateWorkflowMode(flags.sessionId, {
+          workflowMode: flags.workflowMode,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'set-permission') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.updatePermissionLevel(flags.sessionId, {
+          permissionLevel: flags.permissionLevel,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'set-agent') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.updateAgent(flags.sessionId, {
+          agent: flags.agent,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'move') {
+      result = await withWebSessionCommandChannel(client, channel =>
+        channel.move(flags.sessionId, {
+          prevSessionId: flags.prevSessionId,
+          nextSessionId: flags.nextSessionId,
+        }),
+      );
+    } else if (scope === 'web-session' && action === 'watch') {
+      return await watchWebSession(client, flags, stdout);
     } else {
       throw new Error(`unsupported command: ${scope} ${action}`);
     }
 
-    printJson(process.stdout, sanitizeConnection(result));
+    printJson(stdout, sanitizeConnection(result));
     return 0;
   } catch (error) {
     const payload = {
@@ -223,7 +549,7 @@ export async function runCli(argv) {
         message: error instanceof Error ? error.message : String(error),
       },
     };
-    printJson(process.stderr, payload);
+    printJson(stderr, payload);
     return 1;
   }
 }