shraga 0.1.75 → 0.1.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/boot.ts

@@ -21,7 +21,7 @@ import express from 'express';
 import { WebSocketServer, WebSocket } from 'ws';
 import { requireAuth, verifyBearer, authenticateToken, AUTH_PROVIDER, localLogin, addLocalUser, localUserCount } from './auth.ts';
 import { getMcpConfig, getRawMcpConfig, getResolvedMcpConfig, getGlobalMcpConfig, saveMcpConfig, maskEnvValues, mergeWithOriginal, type McpConfig } from './mcp.ts';
-import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, getClaudeAuthSource, type AgentConfig, type PermissionHandler, type QuestionHandler, type QuestionAnswers, type AttachmentMeta, type WsEvent } from './claude.ts';
+import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, getClaudeAuthSource, type AgentConfig, type PermissionHandler, type QuestionHandler, type QuestionAnswers, type AttachmentMeta, type WsEvent, MAX_TURNS_NOTICE } from './claude.ts';
 import { mountFeatures, registerFeature, resumeFeatureSession, collectFeatureFlags, collectSidecarRoutes } from './features.ts';
 import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
@@ -576,7 +576,7 @@ app.get('/api/schedules/:id/runs', requireAuth, (req, res) => {
  */
 type RunChatTurnResult =
   | { status: 'busy' }
-  | { sessionId: string; text: string; blocks: ConvBlock[] }
+  | { sessionId: string; text: string; blocks: ConvBlock[]; stopReason?: string }
   | { sessionId: string; error: string };
 
 async function runChatTurn(
@@ -604,6 +604,14 @@ async function runChatTurn(
   appendMessage(sid, { id: crypto.randomUUID(), role: 'user', blocks: [{ type: 'text', text: prompt }], channel: 'api', senderName: userName });
   setRunStatus(sid, 'running', 'web');
 
+  let stopReason: string | undefined;
+  const onEvent = (ev: WsEvent) => {
+    // consumeStream() drops the `done` event's stopReason, so every non-WS transport lost the fact
+    // that the turn was TRUNCATED and returned the partial answer as if it were complete.
+    if (ev.type === 'done') stopReason = (ev as any).stopReason;
+    hooks?.onEvent?.(ev);
+  };
+
   try {
     const blocks = await consumeStream(streamChat({
       prompt,
@@ -615,7 +623,7 @@ async function runChatTurn(
       abortController,
       context: opts.context ?? { source: 'api', user: userEmail },
       onPermissionRequest: async () => ({ allow: true }),
-    }), hooks?.onEvent);
+    }), onEvent);
     if (blocks.length) {
       appendMessage(sid, { id: crypto.randomUUID(), role: 'assistant', blocks });
     }
@@ -623,7 +631,7 @@ async function runChatTurn(
     const meta = getSession(sid);
     notifyUnread(uid, sid, text.slice(0, 120) || '(completed)', 'response', meta?.title);
     broadcast({ type: 'session_messages_changed', sessionId: sid });
-    return { sessionId: sid, text, blocks };
+    return { sessionId: sid, text, blocks, stopReason };
   } catch (err: any) {
     console.error(`[chat-turn] error:`, err.message);
     return { sessionId: sid, error: err.message };
@@ -1460,7 +1468,7 @@ async function runStream(ws: WebSocket, session: WsSession, sid: string, promptT
       } else if (event.type === 'done') {
         stopReason = event.stopReason ?? 'end_turn';
         if (stopReason === 'max_turns_reached') {
-          assistantBlocks.push({ type: 'text', text: '\n\n---\n⚠️ Reached the maximum number of steps for this turn. Send "continue" to pick up where I left off.' });
+          assistantBlocks.push({ type: 'text', text: MAX_TURNS_NOTICE });
         }
         if (!assistantText && !thinkingText && assistantBlocks.length === 0 && !event.builtinHandled) {
           const fallback = '⚠️ No response was generated. Try rephrasing or sending again.';

package/src/server/claude-usage.ts

@@ -50,8 +50,12 @@ export class ClaudeUsageOptions {
   timeoutMs = 8_000;
   /** A 429 is not a transient blip here: retrying it on the ordinary TTL is what keeps a box wedged in
    *  the penalty box all day (25 straight 429s on prod). Each consecutive 429 climbs this ladder and a
-   *  success drops back to the first rung; a `Retry-After` header wins over the rung when it is longer. */
-  rateLimitBackoffMs = [60_000, 300_000, 900_000, 1_800_000];
+   *  success drops back to the first rung; a `Retry-After` header wins over the rung when it is longer.
+   *  Capped at 15m, not 30m: on a busy box (many CLI sessions sharing one account quota) upstream can
+   *  answer 429 for hours with a ~73s Retry-After, and every attempt is a chance at the first reading
+   *  that unhides the gauge. A failed attempt no longer costs the user anything — the last known-good
+   *  reading stays on screen — so a slightly shorter ceiling is the better trade. */
+  rateLimitBackoffMs = [60_000, 300_000, 600_000, 900_000];
   /** macOS stores Claude Code's OAuth credentials in the login Keychain and writes NO credentials
    *  file, so on darwin an absent file is not proof of an API-key deployment — we look there second.
    *  Linux keeps the file as the only source; we never shell out there. */

package/src/server/claude.ts

@@ -13,6 +13,7 @@ import {
   getSkill,
   getMcpCommandPrompt,
   parseSkillFrontmatter,
+  resolveSkillTurns,
 } from './skills.ts';
 
 import { buildWorkspaceContextBlock, expandWorkspaceMentions } from './workspace.ts';
@@ -306,6 +307,22 @@ export async function* streamChat(opts: {
   const newTriggerNames = discoveryEnabled ? matchTriggeredSkillNames(effectivePrompt, opts.context) : [];
   const triggeredNames = [...new Set([...stickyNames, ...newTriggerNames])];
   const triggeredSkills = skillInjectionBlocks(triggeredNames);
+
+  // Per-skill turn budget. Resolved HERE, once every invoked skill is known (the slash command and
+  // the triggered/sticky set), and GAP-FILLING only: an inline `[turns:N]` or a session-pinned
+  // value already sits in `directives` and is left alone. The global `config.maxTurns` is applied
+  // later still, by the engine (`directives.turns ?? config.maxTurns`), so a skill budget slots
+  // cleanly between the two without touching the global default.
+  // NOTE the deliberate asymmetry with `model` above, which OVERWRITES an inline directive: a
+  // long-running skill needs a floor, not the last word — the human who typed `[turns:5]` to probe
+  // it cheaply must still get 5.
+  if (!directives.turns) {
+    const skillTurns = resolveSkillTurns([slashCmd?.command, ...triggeredNames]);
+    if (skillTurns) {
+      directives.turns = skillTurns;
+      console.log(`[claude] Directives: ${JSON.stringify(directives)} (turns from skill frontmatter)`);
+    }
+  }
   const workspaceTree = buildWorkspaceContextBlock();
   const contact = opts.userEmail ? contacts.find({ email: opts.userEmail }) : null;
   const userBlock = contacts.formatUserBlock(contact);
@@ -366,6 +383,10 @@ export async function* streamChat(opts: {
   });
 }
 
+/** The notice appended to a turn that ran out of steps. Shared so every transport says the same
+ * thing — the MCP path said NOTHING at all, so a truncated turn arrived looking finished. */
+export const MAX_TURNS_NOTICE = '\n\n---\n⚠️ Reached the maximum number of steps for this turn. Send "continue" to pick up where I left off.';
+
 export async function consumeStream(stream: AsyncGenerator<WsEvent>, onEvent?: (ev: WsEvent) => void): Promise<ConvBlock[]> {
   let text = '';
   let thinking = '';

package/src/server/mcp-server.ts

@@ -10,7 +10,7 @@ import { listSkills, getSkill, saveSkill } from './skills.ts';
 import { getAllSessions, loadConversation, isSessionLocked } from './sessions.ts';
 import * as scheduler from './scheduler/index.ts';
 import { buildReport } from './downtime.ts';
-import { getAgentConfig } from './claude.ts';
+import { getAgentConfig, MAX_TURNS_NOTICE } from './claude.ts';
 import { validateApiKey } from './api-keys.ts';
 import { verifyMcpToken } from './auth.ts';
 import { makeProgressEmitter } from './mcp-progress.ts';
@@ -19,7 +19,7 @@ import type { WsEvent } from './claude.ts';
 
 export type RunChatTurnResult =
   | { status: 'busy' }
-  | { sessionId: string; text: string; blocks: unknown[] }
+  | { sessionId: string; text: string; blocks: unknown[]; stopReason?: string }
   | { sessionId: string; error: string };
 
 export type RunChatTurn = (
@@ -318,7 +318,16 @@ export function createShragaMcp(deps: McpServerDeps) {
       const result = await deps.runChatTurn(turn, { onEvent: makeProgressEmitter(captureMcpProgress()) });
       if ('status' in result) return json({ error: 'Session is already processing a request' }, { status: 409 });
       if ('error' in result) return json({ error: result.error, sessionId: result.sessionId }, { status: 500 });
-      return json({ sessionId: result.sessionId, text: result.text, blocks: result.blocks });
+      // A turn that hit the step ceiling is a PARTIAL answer. Without this the MCP caller got the
+      // partial text and no signal at all, which is what "the agent stalled" reports actually were.
+      const truncated = result.stopReason === 'max_turns_reached';
+      return json({
+        sessionId: result.sessionId,
+        text: truncated ? result.text + MAX_TURNS_NOTICE : result.text,
+        blocks: result.blocks,
+        ...(result.stopReason ? { stopReason: result.stopReason } : {}),
+        ...(truncated ? { truncated: true } : {}),
+      });
     } catch (e) { return json({ error: errMessage(e) }, { status: 500 }); }
   });
 

package/src/server/skills.ts

@@ -18,6 +18,9 @@ export interface SkillMeta {
   model?: string;
   allowedTools?: string[];
   argumentHint?: string;
+  /** Per-skill turn budget. Gap-fills `directives.turns` for the turn that invokes the skill —
+   * inline `[turns:N]` and a session-pinned value both still win. Capped at MAX_SKILL_TURNS. */
+  turns?: number;
   triggers?: string[];
   expires?: string;
   origin?: string;
@@ -26,6 +29,24 @@ export interface SkillMeta {
   managedBy?: string;
 }
 
+/** Ceiling on a skill's self-declared turn budget. A skill file is data — it is edited without a
+ * deploy and shipped by rsync — so an unbounded number there is an unattended spend hazard. 300 is
+ * one step above the 250 the video-ad pipeline needs in practice, so no real skill is clipped,
+ * while a typo'd `turns: 30000` costs a bounded worst case instead of an open-ended one. A human
+ * typing `[turns:N]` inline is NOT capped — that is a deliberate, attended choice. */
+export const MAX_SKILL_TURNS = 300;
+
+/** Largest turn budget declared by any of the named skills, clamped to MAX_SKILL_TURNS. */
+export function resolveSkillTurns(names: (string | undefined)[]): number | undefined {
+  let best = 0;
+  for (const name of names) {
+    if (!name) continue;
+    const t = getSkill(name)?.meta.turns;
+    if (t && t > best) best = t;
+  }
+  return best ? Math.min(best, MAX_SKILL_TURNS) : undefined;
+}
+
 export function isExpired(meta: SkillMeta): boolean {
   if (!meta.expires) return false;
   return new Date(meta.expires).getTime() < Date.now();
@@ -61,6 +82,7 @@ export function parseSkillFrontmatter(content: string): { meta: SkillMeta; body:
     if (key === 'model') meta.model = val;
     if (key === 'allowed-tools') meta.allowedTools = val.split(',').map(s => s.trim());
     if (key === 'argument-hint') meta.argumentHint = val;
+    if ((key === 'turns' || key === 'max-turns') && /^\d+$/.test(val)) meta.turns = parseInt(val, 10);
     if (key === 'triggers' && val) {
       try { meta.triggers = JSON.parse(val); } catch {
         meta.triggers = val.split(',').map(s => s.trim());