crewly 1.20.34 → 1.20.35

package/dist/backend/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "82d2b99f83607a55b36a0982c9463e1d65c85f19",
-  "builtAt": "2026-09-19T23:52:29.078Z"
+  "commit": "8cc20b94b33b310ecb16ebc59b6aec4d86651d86",
+  "builtAt": "2026-09-19T23:54:35.448Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewly",
-  "version": "1.20.34",
+  "version": "1.20.35",
   "type": "module",
   "description": "Multi-agent orchestration platform for AI coding teams — coordinates Claude Code, Gemini CLI, and Codex agents with a real-time web dashboard",
   "workspaces": [

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

@@ -20,6 +20,7 @@ import {
   type CrewlyAgentConfig,
   type ConversationState,
   type AgentRunResult,
+  type IncompleteReason,
   type ToolCallRecord,
   type CompactionResult,
   type ContextBudgetStatus,
@@ -36,6 +37,109 @@ import {
   resolveMaxOutputTokens,
 } from './types.js';
 
+/**
+ * What a provider's finish reason means for the turn, and how to recover.
+ *
+ * `reason === null` is the only healthy outcome; everything else left work
+ * on the table. `recoverable` turns get `budget` more attempts, each
+ * prefixed with `nudge` so the model knows to carry on rather than restart.
+ */
+interface FinishOutcome {
+  reason: IncompleteReason | null;
+  detail: string;
+  recoverable: boolean;
+  budget: number;
+  nudge: string;
+}
+
+/** Nudge used when the model ran out of output tokens mid-answer. */
+const CONTINUE_NUDGE =
+  'Your previous message was cut off because it hit the output limit. Continue from exactly where you stopped. Do not repeat what you already wrote, and do not start over.';
+
+/** Nudge used after the provider ended a turn abnormally. */
+const RESUME_NUDGE =
+  'Your previous turn ended unexpectedly before the work was finished. Review what you had already done, then carry on and complete the task. Do not repeat completed steps.';
+
+/**
+ * Classify how a turn ended.
+ *
+ * @param finishReason - Raw provider finish reason
+ * @param steps - Steps the turn consumed
+ * @param maxSteps - The configured step ceiling
+ * @returns What it means and whether to retry
+ */
+export function classifyFinish(finishReason: string, steps: number, maxSteps: number): FinishOutcome {
+  const healthy: FinishOutcome = { reason: null, detail: '', recoverable: false, budget: 0, nudge: '' };
+
+  // Hitting the step ceiling is never a natural end, whatever the provider
+  // then reports — the loop was stopped from the outside mid-task.
+  if (steps >= maxSteps) {
+    return {
+      reason: 'steps-exhausted',
+      detail: `Stopped after the ${maxSteps}-step ceiling with work still outstanding.`,
+      recoverable: false,
+      budget: 0,
+      nudge: '',
+    };
+  }
+
+  switch (finishReason) {
+    case 'stop':
+    case 'tool-calls':
+      return healthy;
+    case 'length':
+      return {
+        reason: 'truncated',
+        detail: 'The model ran out of output tokens before finishing.',
+        recoverable: true,
+        budget: CREWLY_AGENT_DEFAULTS.MAX_CONTINUATIONS,
+        nudge: CONTINUE_NUDGE,
+      };
+    case 'content-filter':
+      return {
+        reason: 'content-filter',
+        detail: 'The provider refused to complete this turn on content grounds.',
+        recoverable: false,
+        budget: 0,
+        nudge: '',
+      };
+    default:
+      // 'other' | 'error' | 'unknown' | anything a provider invents.
+      return {
+        reason: 'abnormal-finish',
+        detail: `The provider ended the turn with "${finishReason}" before the work was finished.`,
+        recoverable: true,
+        budget: CREWLY_AGENT_DEFAULTS.MAX_ABNORMAL_RETRIES,
+        nudge: RESUME_NUDGE,
+      };
+  }
+}
+
+/**
+ * Fold a recovery attempt into the run it continues: text is appended (the
+ * model was told not to repeat itself), counters accumulate, and the newer
+ * finish reason wins.
+ *
+ * @param first - The run so far
+ * @param next - The continuation
+ * @returns The combined run
+ */
+export function mergeRuns(first: AgentRunResult, next: AgentRunResult): AgentRunResult {
+  const text = [first.text, next.text].map((t) => (t ?? '').trim()).filter(Boolean).join('\n\n');
+  return {
+    ...next,
+    text,
+    steps: first.steps + next.steps,
+    usage: {
+      input: first.usage.input + next.usage.input,
+      output: first.usage.output + next.usage.output,
+    },
+    toolCalls: [...first.toolCalls, ...next.toolCalls],
+    budgetWarning: next.budgetWarning ?? first.budgetWarning,
+    reasoning: next.reasoning ?? first.reasoning,
+  };
+}
+
 /**
  * No-op stubs for OSS-internal services. In OSS these resolve to concrete
  * implementations (tracing, memory flush, MCP client, Slack ID synth). The
@@ -1083,6 +1187,46 @@ export class AgentRunnerService {
   private async executeRunWithStreamText(
     tools: Record<string, unknown>,
     abortSignal: AbortSignal,
+  ): Promise<AgentRunResult> {
+    let result = await this.attemptWithErrorRetries(tools, abortSignal);
+    let outcome = classifyFinish(result.finishReason, result.steps, this.config.maxSteps);
+    let recoveryAttempts = 0;
+
+    // A turn only "finished" if the model chose to stop. Anything else left
+    // the job half-done, and until 0.1.2 that fragment was returned as if it
+    // were the answer — the agent would promise to do something, get cut off,
+    // and the user was told it was done (2026-09-19: the orchestrator ended
+    // 4 turns in a row on `other` and silently created nothing).
+    while (outcome.recoverable && recoveryAttempts < outcome.budget && !abortSignal.aborted) {
+      recoveryAttempts++;
+      this.streamingCallbacks.onTextChunk?.(`[recover] ${outcome.reason} — continuing (${recoveryAttempts}/${outcome.budget})\n`);
+      this.state.messages.push({ role: 'user', content: outcome.nudge });
+      const next = await this.attemptWithErrorRetries(tools, abortSignal);
+      result = mergeRuns(result, next);
+      outcome = classifyFinish(next.finishReason, next.steps, this.config.maxSteps);
+    }
+
+    if (outcome.reason === null) return result;
+
+    return {
+      ...result,
+      incomplete: {
+        reason: outcome.reason,
+        detail: outcome.detail,
+        finishReason: result.finishReason,
+        recoveryAttempts,
+      },
+    };
+  }
+
+  /**
+   * Run one turn, retrying only on *thrown* failures (rate limits, network,
+   * context length). A turn that returns with a bad `finishReason` is the
+   * caller's problem — see {@link executeRunWithStreamText}.
+   */
+  private async attemptWithErrorRetries(
+    tools: Record<string, unknown>,
+    abortSignal: AbortSignal,
   ): Promise<AgentRunResult> {
     const maxRetries = CREWLY_AGENT_DEFAULTS.MAX_RETRIES;
     const baseDelay = CREWLY_AGENT_DEFAULTS.RETRY_BASE_DELAY_MS;

package/packages/crewly-agent/src/runtime/finish-recovery.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for how a turn that did not end naturally is classified, continued
+ * and — when it cannot be rescued — reported as incomplete.
+ *
+ * The bug these lock down: a turn ending on `length` or `other` used to be
+ * returned as a finished answer, so the agent could promise work, get cut
+ * off, and report success (2026-09-19, the orchestrator ended four turns in
+ * a row on `other` and silently created nothing).
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AgentRunnerService, classifyFinish, mergeRuns } from './agent-runner.service.js';
+import { CREWLY_AGENT_DEFAULTS, type AgentRunResult, type CrewlyAgentConfig } from './types.js';
+
+const MAX_STEPS = 50;
+
+/** A run result with sensible defaults. */
+function runResult(over: Partial<AgentRunResult> = {}): AgentRunResult {
+  return {
+    text: 'text',
+    steps: 1,
+    usage: { input: 10, output: 5 },
+    toolCalls: [],
+    finishReason: 'stop',
+    ...over,
+  };
+}
+
+describe('classifyFinish', () => {
+  it('treats stop and tool-calls as the only healthy endings', () => {
+    for (const reason of ['stop', 'tool-calls']) {
+      expect(classifyFinish(reason, 3, MAX_STEPS)).toMatchObject({ reason: null, recoverable: false });
+    }
+  });
+
+  it('continues a turn cut off by the output limit, within the continuation budget', () => {
+    const out = classifyFinish('length', 3, MAX_STEPS);
+    expect(out).toMatchObject({ reason: 'truncated', recoverable: true, budget: CREWLY_AGENT_DEFAULTS.MAX_CONTINUATIONS });
+    expect(out.nudge).toMatch(/continue from exactly where you stopped/i);
+    expect(out.nudge).toMatch(/do not repeat/i);
+  });
+
+  it('retries an abnormal provider finish once, naming the reason', () => {
+    for (const reason of ['other', 'error', 'unknown', 'insufficient_system_resource']) {
+      const out = classifyFinish(reason, 3, MAX_STEPS);
+      expect(out).toMatchObject({ reason: 'abnormal-finish', recoverable: true, budget: CREWLY_AGENT_DEFAULTS.MAX_ABNORMAL_RETRIES });
+      expect(out.detail).toContain(reason);
+    }
+  });
+
+  it('never retries a content-filter refusal', () => {
+    expect(classifyFinish('content-filter', 3, MAX_STEPS)).toMatchObject({ reason: 'content-filter', recoverable: false, budget: 0 });
+  });
+
+  it('reports the step ceiling as incomplete whatever the provider says, and does not retry into it', () => {
+    // Even a 'stop' at the ceiling means the loop was cut from outside.
+    expect(classifyFinish('stop', MAX_STEPS, MAX_STEPS)).toMatchObject({ reason: 'steps-exhausted', recoverable: false });
+    expect(classifyFinish('length', MAX_STEPS + 2, MAX_STEPS)).toMatchObject({ reason: 'steps-exhausted' });
+    expect(classifyFinish('stop', MAX_STEPS - 1, MAX_STEPS)).toMatchObject({ reason: null });
+  });
+});
+
+describe('mergeRuns', () => {
+  it('appends text and accumulates steps, usage and tool calls', () => {
+    const merged = mergeRuns(
+      runResult({ text: 'part one', steps: 4, usage: { input: 10, output: 20 }, toolCalls: [{ toolName: 'a', args: {}, result: 1 }], finishReason: 'length' }),
+      runResult({ text: 'part two', steps: 2, usage: { input: 3, output: 7 }, toolCalls: [{ toolName: 'b', args: {}, result: 2 }], finishReason: 'stop' }),
+    );
+    expect(merged.text).toBe('part one\n\npart two');
+    expect(merged.steps).toBe(6);
+    expect(merged.usage).toEqual({ input: 13, output: 27 });
+    expect(merged.toolCalls.map((t) => t.toolName)).toEqual(['a', 'b']);
+    expect(merged.finishReason).toBe('stop');
+  });
+
+  it('drops empty halves rather than leaving blank gaps, and keeps the newer metadata', () => {
+    expect(mergeRuns(runResult({ text: '' }), runResult({ text: 'only' })).text).toBe('only');
+    expect(mergeRuns(runResult({ text: 'only' }), runResult({ text: '   ' })).text).toBe('only');
+    const merged = mergeRuns(runResult({ budgetWarning: 'old', reasoning: 'r1' }), runResult({ budgetWarning: undefined, reasoning: null }));
+    expect(merged.budgetWarning).toBe('old');
+    expect(merged.reasoning).toBe('r1');
+  });
+});
+
+describe('recovery loop', () => {
+  let runner: AgentRunnerService;
+  let attempts: AgentRunResult[];
+  let attemptSpy: ReturnType<typeof vi.fn>;
+
+  const config = {
+    sessionName: 'test-agent',
+    role: 'developer',
+    projectPath: '/tmp',
+    maxSteps: MAX_STEPS,
+    model: { provider: 'deepseek', modelId: 'deepseek-chat' },
+  } as unknown as CrewlyAgentConfig;
+
+  /** Drive the private recovery loop with a scripted sequence of attempts. */
+  async function runLoop(): Promise<AgentRunResult> {
+    return await (runner as unknown as {
+      executeRunWithStreamText(tools: Record<string, unknown>, signal: AbortSignal): Promise<AgentRunResult>;
+    }).executeRunWithStreamText({}, new AbortController().signal);
+  }
+
+  beforeEach(() => {
+    runner = new AgentRunnerService(config);
+    attempts = [];
+    attemptSpy = vi.fn(async () => attempts.shift() ?? runResult());
+    (runner as unknown as Record<string, unknown>).attemptWithErrorRetries = attemptSpy;
+  });
+
+  it('returns a healthy turn untouched, with no extra model call', async () => {
+    attempts = [runResult({ text: 'done', finishReason: 'stop' })];
+    const out = await runLoop();
+    expect(out.text).toBe('done');
+    expect(out.incomplete).toBeUndefined();
+    expect(attemptSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('continues a truncated turn until the model stops, and returns the joined answer', async () => {
+    attempts = [
+      runResult({ text: 'first half', finishReason: 'length' }),
+      runResult({ text: 'second half', finishReason: 'stop' }),
+    ];
+    const out = await runLoop();
+    expect(out.text).toBe('first half\n\nsecond half');
+    expect(out.incomplete).toBeUndefined();
+    expect(attemptSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('gives up after the continuation budget and reports what it kept', async () => {
+    attempts = Array.from({ length: 10 }, (_, i) => runResult({ text: `chunk ${i}`, finishReason: 'length' }));
+    const out = await runLoop();
+    expect(attemptSpy).toHaveBeenCalledTimes(CREWLY_AGENT_DEFAULTS.MAX_CONTINUATIONS + 1);
+    expect(out.incomplete).toMatchObject({ reason: 'truncated', recoveryAttempts: CREWLY_AGENT_DEFAULTS.MAX_CONTINUATIONS });
+    expect(out.text).toContain('chunk 0');
+  });
+
+  it('recovers the deepseek case: an abnormal finish retried once that then completes', async () => {
+    attempts = [
+      runResult({ text: "I'll create the team", finishReason: 'other' }),
+      runResult({ text: 'Team created.', finishReason: 'stop' }),
+    ];
+    const out = await runLoop();
+    expect(out.incomplete).toBeUndefined();
+    expect(out.text).toBe("I'll create the team\n\nTeam created.");
+  });
+
+  it('marks the turn incomplete when the provider keeps bailing', async () => {
+    attempts = [
+      runResult({ text: "I'll create the team", finishReason: 'other' }),
+      runResult({ text: '', finishReason: 'other' }),
+    ];
+    const out = await runLoop();
+    expect(attemptSpy).toHaveBeenCalledTimes(2);
+    expect(out.incomplete).toMatchObject({ reason: 'abnormal-finish', finishReason: 'other', recoveryAttempts: 1 });
+  });
+
+  it('does not retry a step-exhausted or content-filtered turn', async () => {
+    attempts = [runResult({ steps: MAX_STEPS, finishReason: 'tool-calls' })];
+    expect((await runLoop()).incomplete).toMatchObject({ reason: 'steps-exhausted', recoveryAttempts: 0 });
+    expect(attemptSpy).toHaveBeenCalledTimes(1);
+
+    attemptSpy.mockClear();
+    attempts = [runResult({ finishReason: 'content-filter' })];
+    expect((await runLoop()).incomplete).toMatchObject({ reason: 'content-filter' });
+    expect(attemptSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('pushes a continuation instruction into the conversation before retrying', async () => {
+    attempts = [runResult({ finishReason: 'length' }), runResult({ finishReason: 'stop' })];
+    await runLoop();
+    const messages = (runner as unknown as { state: { messages: Array<{ role: string; content: string }> } }).state.messages;
+    const nudge = messages.filter((m) => m.role === 'user').pop();
+    expect(nudge?.content).toMatch(/continue from exactly where you stopped/i);
+  });
+});

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

@@ -203,6 +203,34 @@ export interface AgentRunResult {
    * See P0-1 design-review gate for I2.5 reasoning-pipe routing.
    */
   reasoning?: string | null;
+  /**
+   * Set when the turn did NOT run to a natural end: the model was cut off,
+   * the provider bailed, or the step budget ran out. The text is then a
+   * fragment of an answer, not an answer.
+   */
+  incomplete?: IncompleteRun;
+}
+
+/** Why a turn ended early. */
+export type IncompleteReason =
+  /** Ran out of output tokens and continuation attempts. */
+  | 'truncated'
+  /** Provider returned an unmapped/error finish (`other`, `error`, `unknown`). */
+  | 'abnormal-finish'
+  /** Hit `maxSteps` with work still outstanding. */
+  | 'steps-exhausted'
+  /** Provider refused on content grounds. */
+  | 'content-filter';
+
+/** Describes a turn that ended early. */
+export interface IncompleteRun {
+  reason: IncompleteReason;
+  /** One line a human can act on. */
+  detail: string;
+  /** Raw provider finish reason of the final attempt. */
+  finishReason: string;
+  /** Recovery attempts made before giving up. */
+  recoveryAttempts: number;
 }
 
 /**
@@ -524,6 +552,10 @@ export interface SecurityGuardrailConfig {
 export const CREWLY_AGENT_DEFAULTS = {
   /** Default max reasoning steps per generateText call (high to mimic unlimited like Claude Code) */
   MAX_STEPS: 500,
+  /** Continuations allowed for a turn cut off by the output-token limit. */
+  MAX_CONTINUATIONS: 3,
+  /** Re-runs allowed after the provider ended a turn abnormally. */
+  MAX_ABNORMAL_RETRIES: 1,
   /** Maximum tool calls allowed per single response to prevent polling dead-loops */
   MAX_TOOL_CALLS_PER_RESPONSE: 15,
   /** Consecutive identical tool calls before aborting (loop detection) */