officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

command hq: POST /commanders/new, for a client that cannot open the websocket

Browse Source 
mobile's need, decided with the owner in COMMS/command-hq/mobile.md, now
built: { prompt (required), categoryId? } -> { sessionId, cwd }, sessionId
being claude's REAL transcript id, not a placeholder.

the owner confirmed prompt is required and described why: a commander
usually starts as an ordinary back-and-forth before a background job is ever
armed via the existing dialog, sometimes it's just "you know what to do" —
either way there's always a real first message, same as any conversation.
no empty-commander case to design around.

getting a real transcript id costs actually starting the turn, since claude
assigns one only once system.init has been reported. extracted the
turn-starting half of handleClaudeCodeChat into startClaudeTurn(ws: ... |
null, ..., onOutcome?) so both the websocket path and this endpoint drive
one spawn function instead of two that drift — handleClaudeCodeChat is now
a thin wrapper with an unchanged signature. onOutcome mirrors every
sendToClient(ws, {type:'error',...}) refusal point (member not signed in,
claude not installed, spawn failure) plus the session:claude success case,
so an http caller gets the real reason instead of a generic 30s timeout.

the category-write race: fileAsCommander (same hook the web path uses,
since context: 'command-hq' is set either way) always files with no
category. the endpoint's own createCommandHqSession is upsert-safe
regardless of which insert wins, and an unconditional setCommandHqSessionCategory
UPDATE runs after — always last, always wins, so the requested category is
what's left standing no matter the race.

said plainly in COMMS/command-hq/platform.md: this refactor of live spawn
machinery did not get the second-pair-of-eyes review i said i wanted before
touching it. bunx tsgo clean, suite at the same 7 pre-existing baseline
failures. not exercised against a running server on either side yet.

docs/command-hq.md updated throughout — API table, "how a commander is
created", "still open" now empty of blockers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
pastilhas
2026-08-18 07:29:57 +00:00
co-authored by Claude Opus 5
parent e9b1ce5e94
commit 7ad64445ee
4 changed files with 248 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/servers/api/chat/websocket.ts
+77 -24
View File
@@ -39,7 +39,7 @@ import { isSuperAdmin } from '@@/super-admin';
import { snapshotClaudeUsage } from './usage-store';
// Default model when no user preference is set
const DEFAULT_MODEL = 'claude-code';
export const DEFAULT_MODEL = 'claude-code';
// Harness selection: the `claude-code` provider runs through the Claude sidecar; every other provider
// (opencode/anthropic/openai/… — all `providerID/modelID` ids) runs through the OpenCode server.
@@ -79,7 +79,7 @@ export async function resolveTurnIdentity(userId: number): Promise<TurnIdentity>
return { kind: 'member', run: { osUser: row.osUser, home: resolved.home } };
}
async function getUserDefaultModel(userId: number): Promise<string | null> {
export async function getUserDefaultModel(userId: number): Promise<string | null> {
try {
const settings = await getUserSettings(userId);
const chat = settings?.chat as Record<string, unknown> | undefined;
@@ -688,10 +688,30 @@ async function handleChat(
return handleOpenCodeChat(ws, sessionId, model, msg, prompt);
}
async function handleClaudeCodeChat(
ws: ServerWebSocket<WSData>,
sessionId: string,
model: string,
export type ClaudeTurnOutcome = { ok: true; transcriptId: string } | { ok: false; error: string };
/**
* The core of starting or continuing a Claude Code turn — identity, cwd, session bookkeeping, spawn.
*
* Extracted from `handleClaudeCodeChat` so `POST /command-hq/commanders/new` (`command-hq/router.ts`) can
* drive the SAME path a websocket turn drives, rather than a second copy that drifts the way `turnParams`'
* own docstring below describes already happening once. `ws` is nullable for exactly that caller: an HTTP
* request has no live socket to attach, so every `ws`-specific step below is skipped when it is null rather
* than the whole function being duplicated.
*
* `onOutcome`, when given, fires exactly once — with the transcript id on the first `session:claude` the
* harness reports, or with the error text at whichever refusal/failure point this function would otherwise
* only have told a live socket about. That is what lets an HTTP caller await a real answer instead of a
* generic timeout: the reasons below (member not signed in, Claude not installed, spawn failure) are the
* same reasons a websocket caller already sees via `sendToClient`, just mirrored to a second listener.
*/
export async function startClaudeTurn(params: {
email: string;
username: string;
userId: number;
ws: ServerWebSocket<WSData> | null;
sessionId: string;
model: string;
msg: {
prompt: string;
displayText?: string;
@@ -703,16 +723,21 @@ async function handleClaudeCodeChat(
images?: PromptImage[];
resumeSessionId?: string;
planMode?: boolean;
},
effectivePrompt: string,
): Promise<void> {
const { email, username, userId } = ws.data;
};
effectivePrompt: string;
onOutcome?: (outcome: ClaudeTurnOutcome) => void;
}): Promise<void> {
const { email, username, userId, ws, sessionId, model, msg, effectivePrompt, onOutcome } = params;
const fail = (error: string) => {
sendToClient(ws, { type: 'error', message: error });
onOutcome?.({ ok: false, error });
};
// Identity first: it decides both whose home `~` expands against and whose account the turn runs as, and
// those must be the same answer. Resolving the cwd first would expand `~` before knowing whose it was.
const identity = await resolveTurnIdentity(userId);
if (identity.kind === 'refuse') {
sendToClient(ws, { type: 'error', message: identity.reason });
fail(identity.reason);
return;
}
@@ -724,18 +749,11 @@ async function handleClaudeCodeChat(
if (identity.kind === 'member') {
const state = await claudeLoginState({ email, osUser: identity.run.osUser });
if (!state.installed) {
sendToClient(ws, {
type: 'error',
message: 'Claude is not installed in your home yet — ask the server owner to reprovision your account.',
});
fail('Claude is not installed in your home yet — ask the server owner to reprovision your account.');
return;
}
if (!state.loggedIn) {
sendToClient(ws, {
type: 'error',
message:
'Open a terminal and run `claude` once to sign in with your own Anthropic account. It stays signed in.',
});
fail('Open a terminal and run `claude` once to sign in with your own Anthropic account. It stays signed in.');
return;
}
}
@@ -748,8 +766,12 @@ async function handleClaudeCodeChat(
const session = sessionManager.getOrCreate(sessionId, email, cwd, model, groupSlug, msg.context, msg.contextId);
session.userId = userId;
sessionManager.attachWs(sessionId, ws);
wsToSessionMap.set(ws as any, sessionId);
// No live socket to attach for an HTTP-originated turn — the caller attaches later, by transcript id,
// through the ordinary `/chat` websocket `attach` path, exactly as a reconnect already does.
if (ws) {
sessionManager.attachWs(sessionId, ws);
wsToSessionMap.set(ws as any, sessionId);
}
sendToClient(ws, {
type: 'session:init',
@@ -780,13 +802,22 @@ async function handleClaudeCodeChat(
// The resume id is passed so a tier switch on a RESUMED conversation is recorded when it happens rather
// than when the turn ends — see the seed in `createMessageHandler`. `commandHq` is `msg.context ===
// 'command-hq'`, the same signal `resolveChatCwd` above already reads to pick this session's directory.
const onMessage = createMessageHandler(
const baseOnMessage = createMessageHandler(
sessionId,
model,
msg.resumeSessionId,
msg.planMode,
msg.context === 'command-hq',
);
// Wrapped rather than passed straight to the spawn call, so `onOutcome` sees the transcript id at the
// exact moment `fileAsCommander` (inside `createMessageHandler`) does — both react to the same
// `session:claude` message, neither races the other for it.
const onMessage = (turnMsg: TurnMessage, seq?: number) => {
baseOnMessage(turnMsg, seq);
if (onOutcome && turnMsg.type === 'session:claude' && turnMsg.claudeSessionId) {
onOutcome({ ok: true, transcriptId: turnMsg.claudeSessionId });
}
};
/**
* One description of the turn, used by both paths below.
@@ -842,11 +873,33 @@ async function handleClaudeCodeChat(
}
} catch (err) {
logger.error('Failed to start Claude Code streaming', { sessionId, error: String(err) });
sendToClient(ws, { type: 'error', message: 'Failed to start Claude Code' });
session.isGenerating = false;
fail('Failed to start Claude Code');
}
}
async function handleClaudeCodeChat(
ws: ServerWebSocket<WSData>,
sessionId: string,
model: string,
msg: {
prompt: string;
displayText?: string;
groupSlug?: string;
context?: string;
contextId?: string;
cwd?: string;
cwdRoot?: string;
images?: PromptImage[];
resumeSessionId?: string;
planMode?: boolean;
},
effectivePrompt: string,
): Promise<void> {
const { email, username, userId } = ws.data;
return startClaudeTurn({ email, username, userId, ws, sessionId, model, msg, effectivePrompt });
}
async function handleOpenCodeChat(
ws: ServerWebSocket<WSData>,
sessionId: string,