crewly 1.12.1 → 1.13.1

package/packages/crewly-agent/src/runtime/agent-runner.service.ts

@@ -158,7 +158,10 @@ export class ToolCallLoopDetector {
       }
       if (this.consecutiveErrors >= this.errorThreshold) {
         this.loopDetected = true;
-        this.loopReason = `Tool "${toolName}" returned errors ${this.consecutiveErrors} consecutive times. Last result: ${String(result).slice(0, 200)}`;
+        // Serialize objects properly — `String(obj)` yields "[object Object]"
+        // and loses the actual error. Mirror isErrorResult()'s serialization.
+        const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+        this.loopReason = `Tool "${toolName}" returned errors ${this.consecutiveErrors} consecutive times. Last result: ${resultStr.slice(0, 200)}`;
         return true;
       }
     } else {
@@ -198,6 +201,40 @@ export class ToolCallLoopDetector {
  * const result = await runner.run('Check all team statuses');
  * ```
  */
+/**
+ * Thrown when a single agent run exceeds its wall-clock budget.
+ *
+ * Distinct class (rather than a message-sniffed "timeout" string) because
+ * {@link AgentRunnerService.isRecoverableError} treats anything mentioning
+ * "timeout" as retryable. A hard-budget expiry is deliberately NOT retryable:
+ * the budget covers the whole run including retries, so re-entering the retry
+ * loop would multiply the very stall the budget exists to bound.
+ *
+ * @example
+ * ```typescript
+ * try { await runner.run(msg); }
+ * catch (e) { if (e instanceof AgentRunTimeoutError) recycleAgent(); }
+ * ```
+ */
+export class AgentRunTimeoutError extends Error {
+  /** Wall-clock budget that was exceeded, in milliseconds. */
+  readonly timeoutMs: number;
+
+  /**
+   * @param timeoutMs - The budget that was exceeded, in milliseconds
+   * @param modelId - Model the run was using, for operator diagnosis
+   */
+  constructor(timeoutMs: number, modelId: string) {
+    super(
+      `Agent run exceeded its ${timeoutMs}ms wall-clock budget (model: ${modelId}) `
+      + `and was hard-aborted. The model connection stalled without delivering a `
+      + `response — see CREWLY_AGENT_MESSAGE_TIMEOUT_MS to tune the budget.`,
+    );
+    this.name = 'AgentRunTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 /** Function type for generateText — used for dependency injection in tests */
 type GenerateTextFn = (opts: Record<string, unknown>) => Promise<Record<string, unknown>>;
 
@@ -269,6 +306,7 @@ export class AgentRunnerService {
         messages: [],
         systemPrompt: this.effectiveSystemPrompt,
         totalTokens: { input: 0, output: 0 },
+        lastContextTokens: 0,
         createdAt: new Date(),
         lastActivityAt: new Date(),
       };
@@ -662,11 +700,19 @@ export class AgentRunnerService {
    * @returns ContextBudgetStatus with usage stats and level
    */
   getContextBudget(): ContextBudgetStatus {
-    const totalTokensUsed = this.state.totalTokens.input + this.state.totalTokens.output;
+    const lifetimeTokensUsed = this.state.totalTokens.input + this.state.totalTokens.output;
+    // Occupancy, NOT lifetime spend. The prompt is re-sent in full on every
+    // request, so the lifetime sum counts the same history once per turn and
+    // sails past the window within a handful of messages — which used to pin
+    // `level` at 'critical' forever and run a compaction before every single
+    // message, doubling the model calls for the rest of the session.
+    const contextTokensUsed = this.state.lastContextTokens > 0
+      ? this.state.lastContextTokens
+      : this.estimateContextTokens();
     const contextWindowSize = MODEL_CONTEXT_WINDOWS[this.config.model.modelId]
       ?? MODEL_CONTEXT_WINDOWS.default;
     const usagePercent = contextWindowSize > 0
-      ? totalTokensUsed / contextWindowSize
+      ? contextTokensUsed / contextWindowSize
       : 0;
 
     const threshold = this.config.compactionThreshold;
@@ -682,7 +728,7 @@ export class AgentRunnerService {
       || usagePercent >= threshold;
 
     const pct = (usagePercent * 100).toFixed(1);
-    let summary = `${pct}% of context budget used (${totalTokensUsed.toLocaleString()}/${contextWindowSize.toLocaleString()} tokens, ${this.state.messages.length} messages)`;
+    let summary = `${pct}% of context budget used (${contextTokensUsed.toLocaleString()}/${contextWindowSize.toLocaleString()} tokens, ${this.state.messages.length} messages, ${lifetimeTokensUsed.toLocaleString()} billed this session)`;
     if (level === 'critical') {
       summary += ' — CRITICAL: compaction recommended immediately';
     } else if (level === 'warning') {
@@ -690,7 +736,8 @@ export class AgentRunnerService {
     }
 
     return {
-      totalTokensUsed,
+      contextTokensUsed,
+      lifetimeTokensUsed,
       contextWindowSize,
       usagePercent,
       level,
@@ -700,6 +747,91 @@ export class AgentRunnerService {
     };
   }
 
+  /**
+   * Provider-specific request options.
+   *
+   * Turns on Anthropic prompt caching. Every request re-sends the same
+   * prefix — the system prompt (tens of KB for an orchestrator) followed by
+   * the tool schemas — and that prefix is byte-stable for the life of the
+   * session, which is exactly the shape caching is for. Without this the
+   * whole prefix is billed at full rate on every single turn.
+   *
+   * The top-level `cacheControl` places the breakpoint at the last cacheable
+   * block, so tools + system + settled history are covered by one marker and
+   * only the newest turn is uncached.
+   *
+   * Anthropic-only by design: DeepSeek caches server-side with no opt-in, and
+   * the other providers ignore an option namespaced to a provider that is not
+   * theirs — but sending it only where it means something keeps the request
+   * honest.
+   *
+   * @returns Provider options for the current model, or undefined when the
+   *          provider needs none
+   */
+  private buildProviderOptions(): Record<string, Record<string, unknown>> | undefined {
+    if (this.config.model.provider !== 'anthropic') return undefined;
+    return { anthropic: { cacheControl: { type: 'ephemeral' } } };
+  }
+
+  /**
+   * Record how full the context is after a completed request.
+   *
+   * The prompt the provider just billed IS the context size — `input` covers
+   * the system prompt, the tool schemas and the retained history, and
+   * `cachedInput` covers the part of that same prompt served from cache
+   * (billed cheaper, but still occupying the window, so it must be added
+   * back). The reply is included because the next request carries it forward.
+   *
+   * Assigns rather than accumulates: this is a snapshot of the current turn,
+   * and compaction shrinks it back down on the next measurement.
+   *
+   * @param usage - Token counts reported by the provider for the request
+   */
+  private recordContextOccupancy(
+    usage: { input: number; output: number; cachedInput: number },
+  ): void {
+    this.state.lastContextTokens = usage.input + usage.cachedInput + usage.output;
+  }
+
+  /**
+   * Estimate context occupancy from the text we are about to send.
+   *
+   * Only used before the first response of a conversation, when no provider
+   * measurement exists yet. A rough number is fine there — one turn later it
+   * is replaced by the provider's own count — but it must not be wildly low,
+   * because a 40KB system prompt already fills a meaningful slice of a small
+   * window before any history exists.
+   *
+   * CJK and Latin text are counted separately: a single chars-per-token ratio
+   * misjudges a Chinese prompt by more than 2x in whichever direction it is
+   * tuned for. Tool schemas are not included — they are unavailable here and
+   * the estimate is superseded immediately.
+   *
+   * @returns Estimated tokens currently occupying the context window
+   */
+  private estimateContextTokens(): number {
+    let text = this.state.systemPrompt ?? '';
+    for (const m of this.state.messages) {
+      text += typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+    }
+    let cjk = 0;
+    for (const ch of text) {
+      const code = ch.codePointAt(0) ?? 0;
+      // CJK ideographs, kana, Hangul, and full-width forms.
+      if ((code >= 0x3040 && code <= 0x9fff)
+        || (code >= 0xac00 && code <= 0xd7af)
+        || (code >= 0xf900 && code <= 0xfaff)
+        || (code >= 0xff00 && code <= 0xffef)) {
+        cjk++;
+      }
+    }
+    const latin = [...text].length - cjk;
+    return Math.ceil(
+      latin / CREWLY_AGENT_DEFAULTS.CHARS_PER_TOKEN_LATIN
+      + cjk / CREWLY_AGENT_DEFAULTS.CHARS_PER_TOKEN_CJK,
+    );
+  }
+
   /**
    * Process queued messages serially.
    */
@@ -824,19 +956,73 @@ export class AgentRunnerService {
       externalAbortSignal.addEventListener('abort', () => runAbort.abort(), { once: true });
     }
 
+    // Wall-clock budget for the ENTIRE run (all retries included).
+    //
+    // Without this, a model connection that opens but then goes silent — no
+    // bytes, no FIN, no error — hangs `await streamResult` forever: undici
+    // applies no idle deadline to a streaming body. That stalled promise wedges
+    // processQueue permanently (`this.processing` stays true), so every later
+    // message queues behind it and the agent goes silently catatonic: the
+    // process is alive and heartbeating, but no run ever completes and no error
+    // is ever raised. Bounding the run converts that invisible hang into a
+    // normal rejection the caller can log, surface, and recover from.
+    const timeoutMs = this.resolveRunTimeoutMs();
+    let hardTimer: ReturnType<typeof setTimeout> | undefined;
+    let softTimer: ReturnType<typeof setTimeout> | undefined;
+
     try {
       // If a test override is set, use generateText path (backward compatible)
-      if (this._generateTextFn) {
-        return await this.executeRunWithGenerateText(tools, runAbort.signal);
-      }
+      const runPromise = this._generateTextFn
+        ? this.executeRunWithGenerateText(tools, runAbort.signal)
+        // Production path: streamText for real-time feedback
+        : this.executeRunWithStreamText(tools, runAbort.signal);
+
+      // The loser of the race stays pending. Attach a no-op catch so its
+      // eventual abort-rejection is never an unhandled rejection (which
+      // crashes the agent process under Node's default policy).
+      runPromise.catch(() => { /* settled by the race below */ });
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        softTimer = setTimeout(() => {
+          console.warn(
+            `[AgentRunner] Run exceeded soft warning threshold `
+            + `(${CREWLY_AGENT_DEFAULTS.MESSAGE_SOFT_WARNING_MS}ms) — still waiting on the model.`,
+          );
+        }, CREWLY_AGENT_DEFAULTS.MESSAGE_SOFT_WARNING_MS);
+
+        hardTimer = setTimeout(() => {
+          // Abort first so the in-flight HTTP request and any tool work are
+          // torn down, then reject — a well-behaved provider unwinds on the
+          // signal, and a wedged one no longer holds the queue hostage.
+          runAbort.abort();
+          reject(new AgentRunTimeoutError(timeoutMs, this.config.model.modelId));
+        }, timeoutMs);
+      });
 
-      // Production path: streamText for real-time feedback
-      return await this.executeRunWithStreamText(tools, runAbort.signal);
+      return await Promise.race([runPromise, timeoutPromise]);
     } finally {
+      if (hardTimer) clearTimeout(hardTimer);
+      if (softTimer) clearTimeout(softTimer);
       this.currentRunAbort = null;
     }
   }
 
+  /**
+   * Resolve the wall-clock budget for one run.
+   *
+   * Per-model overrides win over the global default: reasoning models emit
+   * chain-of-thought tokens far slower than plain content, so a budget tuned
+   * for a chat model would kill them mid-thought.
+   *
+   * @returns Budget in milliseconds for the currently configured model
+   */
+  private resolveRunTimeoutMs(): number {
+    return (
+      CREWLY_AGENT_DEFAULTS.MODEL_TIMEOUT_MS[this.config.model.modelId]
+      ?? CREWLY_AGENT_DEFAULTS.MESSAGE_TIMEOUT_MS
+    );
+  }
+
   /**
    * Check if an error is recoverable and eligible for automatic retry.
    *
@@ -850,6 +1036,9 @@ export class AgentRunnerService {
    */
   private isRecoverableError(error: unknown): boolean {
     if (!(error instanceof Error)) return false;
+    // Hard-budget expiry is terminal by construction: the budget spans the
+    // whole run, so retrying would just re-enter the stall it bounded.
+    if (error instanceof AgentRunTimeoutError) return false;
     const msg = error.message.toLowerCase();
     const statusMatch = msg.match(/\b(429|5\d{2})\b/);
     if (statusMatch) return true;
@@ -955,6 +1144,7 @@ export class AgentRunnerService {
       model: this.model!,
       system: this.state.systemPrompt,
       messages: this.state.messages,
+      providerOptions: this.buildProviderOptions(),
       tools: tools as any,
       stopWhen: stepCountIs(this.config.maxSteps),
       temperature: this.config.model.temperature,
@@ -1067,9 +1257,11 @@ export class AgentRunnerService {
       const usage = {
         input: resultUsage?.inputTokens ?? 0,
         output: resultUsage?.outputTokens ?? 0,
+        cachedInput: resultUsage?.cachedInputTokens ?? 0,
       };
       this.state.totalTokens.input += usage.input;
       this.state.totalTokens.output += usage.output;
+      this.recordContextOccupancy(usage);
 
       // Check budget after token update
       const postBudget = this.getContextBudget();
@@ -1183,6 +1375,7 @@ export class AgentRunnerService {
       model: this.model,
       system: this.state.systemPrompt,
       messages: this.state.messages,
+      providerOptions: this.buildProviderOptions(),
       tools,
       stopWhen: stepCountIs(this.config.maxSteps),
       temperature: this.config.model.temperature,
@@ -1251,9 +1444,11 @@ export class AgentRunnerService {
     const usage = {
       input: result.usage?.inputTokens ?? 0,
       output: result.usage?.outputTokens ?? 0,
+      cachedInput: result.usage?.cachedInputTokens ?? 0,
     };
     this.state.totalTokens.input += usage.input;
     this.state.totalTokens.output += usage.output;
+    this.recordContextOccupancy(usage);
 
     // Check budget after token update and attach warning if approaching limits
     const postBudget = this.getContextBudget();
@@ -1398,6 +1593,7 @@ export class AgentRunnerService {
         model: this.model,
         system: this.state.systemPrompt,
         messages: this.state.messages,
+        providerOptions: this.buildProviderOptions(),
         tools: tools as any,
         stopWhen: stepCountIs(20), // Limited steps for follow-up
         temperature: this.config.model.temperature,
@@ -1409,7 +1605,7 @@ export class AgentRunnerService {
       const followUpResult = followUp as unknown as Record<string, unknown>;
       const steps = (followUpResult.steps as Array<Record<string, unknown>>) ?? [];
       const text = (followUpResult.text as string) ?? '';
-      const followUpUsage = followUpResult.usage as { inputTokens?: number; outputTokens?: number } | undefined;
+      const followUpUsage = followUpResult.usage as { inputTokens?: number; outputTokens?: number; cachedInputTokens?: number } | undefined;
       const finishReason = (followUpResult.finishReason as string) ?? 'stop';
 
       const followUpToolCalls: ToolCallRecord[] = [];
@@ -1426,10 +1622,16 @@ export class AgentRunnerService {
         this.state.messages.push({ role: 'assistant', content: text });
       }
 
-      // Track follow-up token usage
+      // Track follow-up token usage. This is a later request in the same run,
+      // so its prompt is the most current picture of how full the context is.
       if (followUpUsage) {
         this.state.totalTokens.input += followUpUsage.inputTokens ?? 0;
         this.state.totalTokens.output += followUpUsage.outputTokens ?? 0;
+        this.recordContextOccupancy({
+          input: followUpUsage.inputTokens ?? 0,
+          output: followUpUsage.outputTokens ?? 0,
+          cachedInput: followUpUsage.cachedInputTokens ?? 0,
+        });
       }
 
       return {
@@ -1438,6 +1640,7 @@ export class AgentRunnerService {
         usage: {
           input: followUpUsage?.inputTokens ?? 0,
           output: followUpUsage?.outputTokens ?? 0,
+          cachedInput: followUpUsage?.cachedInputTokens ?? 0,
         },
         toolCalls: followUpToolCalls,
         finishReason,
@@ -1470,6 +1673,7 @@ export class AgentRunnerService {
         model: this.model,
         system: this.state.systemPrompt,
         messages: this.state.messages,
+        providerOptions: this.buildProviderOptions(),
         maxOutputTokens: resolveMaxOutputTokens(this.config.model),
         temperature: this.config.model.temperature,
       });
@@ -1484,6 +1688,11 @@ export class AgentRunnerService {
         if (fallbackUsage) {
           this.state.totalTokens.input += fallbackUsage.inputTokens ?? 0;
           this.state.totalTokens.output += fallbackUsage.outputTokens ?? 0;
+          this.recordContextOccupancy({
+            input: fallbackUsage.inputTokens ?? 0,
+            output: fallbackUsage.outputTokens ?? 0,
+            cachedInput: fallbackUsage.cachedInputTokens ?? 0,
+          });
         }
       }
 

package/packages/crewly-agent/src/runtime/tool-registry.test.ts

@@ -2186,6 +2186,25 @@ describe('Tool Registry', () => {
       expect(validateFn('rm -rf ./dist')).toBeNull();
       expect(validateFn('rm -rf node_modules')).toBeNull();
     });
+
+    it('should signal the block is permanent so the model stops retrying', () => {
+      // A blocked command is a policy decision, not a transient failure. When
+      // the message read like a retryable error the model retried variations
+      // until the loop detector aborted the whole run, so the wording carries
+      // real behavioural weight and is worth pinning.
+      const reason = validateFn('kill -9 $$');
+
+      expect(reason).not.toBeNull();
+      expect(reason).toMatch(/permanently blocked/i);
+      expect(reason).toMatch(/NOT a transient error/i);
+      expect(reason).toMatch(/do NOT retry/i);
+    });
+
+    it('should still identify which pattern caused the block', () => {
+      // The matched pattern stays in the message: without it the model cannot
+      // tell which part of a compound command was rejected.
+      expect(validateFn('shutdown -h now')).toMatch(/shutdown/);
+    });
   });
 
   describe('bash_exec tool', () => {

package/packages/crewly-agent/src/runtime/tool-registry.ts

@@ -79,7 +79,10 @@ export const APPROVAL_REQUIRED_BASH_PATTERNS: Array<{ pattern: RegExp; label: st
 export function validateBashCommand(command: string): string | null {
   for (const pattern of BLOCKED_COMMAND_PATTERNS) {
     if (pattern.test(command)) {
-      return `Command blocked by security policy: matches forbidden pattern ${pattern}`;
+      // Phrased to signal the model this is a PERMANENT policy block, not a
+      // transient failure — otherwise it retries variations until the loop
+      // detector aborts the whole run.
+      return `Command permanently blocked by security policy (matched ${pattern}). This is NOT a transient error — do NOT retry this or a variation. Achieve the goal a different way (use a Crewly API/tool, or skip this step).`;
     }
   }
   return null;

package/packages/crewly-agent/src/runtime/types.ts

@@ -105,6 +105,20 @@ export interface ConversationState {
   systemPrompt: string;
   /** Cumulative token usage across all generateText calls */
   totalTokens: { input: number; output: number };
+  /**
+   * Tokens occupying the model's context as of the most recent request:
+   * the prompt that was actually sent (system + tools + retained history,
+   * cache hits included) plus the reply it produced, which the next request
+   * carries forward.
+   *
+   * This is a MEASUREMENT, not a running total — it is assigned, never
+   * accumulated. `totalTokens` answers "what has this session cost?";
+   * this answers "how full is the context?". Using the former for the
+   * latter conflates lifetime spend with occupancy and climbs past 100%
+   * of the window after a few turns, pinning the runner in permanent
+   * compaction. 0 until the first response lands.
+   */
+  lastContextTokens: number;
   /** Conversation creation time */
   createdAt: Date;
   /** Last activity timestamp */
@@ -156,8 +170,13 @@ export interface AgentRunResult {
   text: string;
   /** Number of steps taken in this run */
   steps: number;
-  /** Token usage for this run */
-  usage: { input: number; output: number };
+  /**
+   * Token usage for this run. `cachedInput` is the portion of `input` the
+   * provider served from its prompt cache — the number to watch when
+   * verifying caching actually engaged. It is 0 on providers that do not
+   * report cache hits.
+   */
+  usage: { input: number; output: number; cachedInput: number };
   /** Tool calls made during this run */
   toolCalls: ToolCallRecord[];
   /** Reason the generation finished */
@@ -322,8 +341,19 @@ export const WRITE_TOOLS: readonly string[] = [
  * Tracks token usage against the model's context window limit.
  */
 export interface ContextBudgetStatus {
-  /** Total tokens used so far (input + output) */
-  totalTokensUsed: number;
+  /**
+   * Tokens occupying the context window right now — measured from the last
+   * request, or estimated from the system prompt + history before the first
+   * one. This is the numerator of `usagePercent`.
+   */
+  contextTokensUsed: number;
+  /**
+   * Lifetime tokens billed for this session (input + output across every
+   * request). Reported for cost visibility only — it must never be compared
+   * against the context window, since re-sent history is counted once per
+   * request and the sum exceeds the window long before the context is full.
+   */
+  lifetimeTokensUsed: number;
   /** Estimated context window size for the current model */
   contextWindowSize: number;
   /** Usage as a fraction (0.0 - 1.0) */
@@ -343,7 +373,20 @@ export interface ContextBudgetStatus {
  * Used for budget tracking when the model doesn't report its own limit.
  */
 export const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
-  // Anthropic
+  // Anthropic — current generation. These were missing, so every model the
+  // fleet actually runs fell through to `default: 128_000` while its real
+  // window is 1M. An 8x under-estimate makes `compactionThreshold` fire
+  // roughly 8x too early, which is expensive: each premature compaction is a
+  // whole extra model call.
+  'claude-fable-5': 1_000_000,
+  'claude-opus-5': 1_000_000,
+  'claude-opus-4-8': 1_000_000,
+  'claude-opus-4-7': 1_000_000,
+  'claude-opus-4-6': 1_000_000,
+  'claude-sonnet-5': 1_000_000,
+  'claude-sonnet-4-6': 1_000_000,
+  'claude-haiku-4-5': 200_000,
+  // Anthropic — older dated snapshots, kept so pinned configs still resolve.
   'claude-opus-4-20250514': 200_000,
   'claude-sonnet-4-20250514': 200_000,
   'claude-haiku-4-20250506': 200_000,
@@ -493,6 +536,14 @@ export const CREWLY_AGENT_DEFAULTS = {
   MAX_HISTORY_MESSAGES: 100,
   /** Default compaction threshold (80% of context window) */
   COMPACTION_THRESHOLD: 0.8,
+  /**
+   * Characters per token, used ONLY to size the context before the first
+   * response gives us a real measurement. Latin text runs about 4 chars per
+   * token; CJK about 1.5, so the two are counted separately — a single ratio
+   * would misjudge a Chinese system prompt by more than 2x.
+   */
+  CHARS_PER_TOKEN_LATIN: 4,
+  CHARS_PER_TOKEN_CJK: 1.5,
   /** Default model configuration */
   DEFAULT_MODEL: {
     provider: 'google' as ModelProvider,
@@ -540,6 +591,15 @@ export const CREWLY_AGENT_DEFAULTS = {
   /** Soft warning threshold in milliseconds — logs a warning but does not kill the request.
    *  Override via CREWLY_AGENT_MESSAGE_SOFT_WARNING_MS env var. */
   MESSAGE_SOFT_WARNING_MS: Number(process.env.CREWLY_AGENT_MESSAGE_SOFT_WARNING_MS) || 240_000,
+  /** Grace period added on top of the agent's own run budget before the PARENT
+   *  gives up waiting on the child's IPC reply.
+   *
+   *  The child enforces the run budget itself and reports a clean error, so in
+   *  normal operation the parent timer never fires. It exists for the case the
+   *  child can no longer report at all — blocked event loop, broken stdout pipe,
+   *  SIGSTOP. The grace keeps the parent from racing the child and mislabelling
+   *  a normal in-budget timeout as a wedged runtime. */
+  IPC_RUN_TIMEOUT_GRACE_MS: 30_000,
   /** Cooldown period in milliseconds after rate limit retries are exhausted */
   RATE_LIMIT_COOLDOWN_MS: 300_000,
   /** Maximum number of automatic retries for recoverable errors (429, 5xx, network) */