crewly 1.20.147 → 1.20.148

package/dist/backend/backend/src/services/agent/fresh-task-conversation.service.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Fresh Task Conversation Service
+ *
+ * Claude Code agents keep one conversation forever, so a small new task
+ * re-reads hundreds of thousands of tokens of unrelated history on every
+ * turn (81% of measured usage came from turns over 300k context). This
+ * service starts a fresh conversation when a team member is handed a task
+ * whose ROOT differs from the last one it was given:
+ *
+ *   1. The old conversation is saved server-side — a handover file under
+ *      `<CREWLY_HOME>/handover/` (same format the orchestrator uses at
+ *      restart) and a concise copy through the memory `remember` path, which
+ *      mirrors into the wiki. No agent turn is spent on it.
+ *   2. `/clear` is written to the PTY the same way context compaction writes
+ *      its command (Escape, 200 ms, command + CR), then a short pause for the
+ *      prompt to come back.
+ *   3. The dispatch goes on with a one-line note pointing at the handover.
+ *   4. In the background the new transcript Claude Code starts is found and
+ *      its id stored, so a restart resumes the NEW conversation; if it cannot
+ *      be found the stored id is cleared so a restart starts fresh instead of
+ *      resuming the huge pre-clear one.
+ *
+ * Retries, verifications and reviews of the same task share its root
+ * (`<id>:retry:N`, `<id>:verify:<id>`, `<id>:review:…`), so they keep their
+ * context. Never the orchestrator, only Claude Code, only when the agent is
+ * idle and nobody else just wrote to it; any failure falls back to plain
+ * delivery — nothing here throws into dispatch.
+ *
+ * @module services/agent/fresh-task-conversation.service
+ */
+import type { WorkItem } from '../../types/v2/work-item.types.js';
+/**
+ * The root task id of a work item: its id with any follow-up suffix
+ * (`:retry:N`, `:verify:…`, `:review:…`) removed, so every follow-up of one
+ * task maps to the same root.
+ *
+ * @param workItemId - WorkItem id
+ * @returns The root id
+ *
+ * @example
+ * ```typescript
+ * rootWorkItemId('abc:retry:2');        // 'abc'
+ * rootWorkItemId('abc:verify:abc');     // 'abc'
+ * rootWorkItemId('abc:retry:1:retry:2'); // 'abc'
+ * ```
+ */
+export declare function rootWorkItemId(workItemId: string): string;
+/**
+ * Whether the feature is switched on by the environment.
+ *
+ * @param env - Environment (tests)
+ * @returns False when CREWLY_FRESH_TASK_CONVERSATION is 0 / false / off / no
+ */
+export declare function freshTaskConversationEnvEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Everything the clear decision depends on. */
+export interface FreshTaskDecisionInput {
+    /** Agent session */
+    sessionName: string;
+    /** Its runtime (from session persistence) */
+    runtimeType?: string;
+    /** Root of the last task delivered to it, if any */
+    previousRoot: string | null;
+    /** Root of the task being delivered */
+    newRoot: string;
+    /** Env + settings kill-switch */
+    enabled: boolean;
+    /** Agent is mid-turn */
+    busy: boolean;
+    /** Someone else wrote to the session moments ago */
+    recentDelivery: boolean;
+    /** Roots of OTHER work the agent is actively running */
+    otherActiveRoots: string[];
+    /**
+     * The agent already started this very task a while ago (e.g. the lead
+     * handed it over directly and this is a re-delivery). Clearing now would
+     * wipe the live context of work in progress.
+     */
+    alreadyStarted?: boolean;
+}
+/** The clear decision and why. */
+export interface FreshTaskDecision {
+    /** Clear before delivering */
+    clear: boolean;
+    /** Short reason (logged) */
+    reason: string;
+}
+/**
+ * Decide whether to start a fresh conversation before delivering a task.
+ *
+ * @param input - Decision inputs
+ * @returns The decision
+ */
+export declare function decideFreshConversation(input: FreshTaskDecisionInput): FreshTaskDecision;
+/**
+ * The line put in front of the task text after a fresh start.
+ *
+ * @param handoverPath - Handover file written for the old conversation
+ * @returns One line
+ */
+export declare function freshConversationNote(handoverPath: string): string;
+/** What the service needs to know about a session. */
+export interface FreshTaskSessionInfo {
+    /** Runtime */
+    runtimeType?: string;
+    /** Working directory (Claude Code transcripts are keyed on it) */
+    cwd?: string;
+    /** Current Claude conversation id */
+    sessionId?: string;
+}
+/** Collaborators; the defaults talk to the running backend. */
+export interface FreshTaskDeps {
+    /** Session runtime / cwd / conversation id */
+    getSessionInfo: (sessionName: string) => FreshTaskSessionInfo | null;
+    /** Conversation ids of every OTHER registered session */
+    getClaimedSessionIds: (sessionName: string) => Set<string>;
+    /** Store the new conversation id */
+    updateSessionId: (sessionName: string, id: string) => void;
+    /** Forget the conversation id (restart starts fresh) */
+    clearSessionId: (sessionName: string) => void;
+    /** Agent is mid-turn */
+    isBusy: (sessionName: string) => Promise<boolean>;
+    /** Settings flag (general.freshConversationPerTask, default true) */
+    settingEnabled: () => Promise<boolean>;
+    /** Open work items targeting the session */
+    getActiveItems: (sessionName: string) => Promise<WorkItem[]>;
+    /** Raw PTY write; false when the session is gone */
+    writeToSession: (sessionName: string, data: string) => boolean;
+    /** Store the concise handover through memory (mirrors into the wiki) */
+    remember: (args: {
+        agentId: string;
+        projectPath?: string;
+        content: string;
+        title: string;
+    }) => Promise<unknown>;
+    /** Crewly home (handover + state files) */
+    crewlyHome: () => string;
+    /** Claude home override (tests) */
+    claudeHome?: string;
+    /** Clock */
+    now: () => number;
+    /** Sleep */
+    sleep: (ms: number) => Promise<void>;
+    /** Environment */
+    env: NodeJS.ProcessEnv;
+}
+/** Result of {@link FreshTaskConversationService.prepareForTask}. */
+export interface PrepareForTaskResult {
+    /** A fresh conversation was started */
+    cleared: boolean;
+    /** Handover file for the old conversation (when cleared) */
+    handoverPath?: string;
+}
+/**
+ * Singleton that starts a fresh Claude Code conversation per new task.
+ */
+export declare class FreshTaskConversationService {
+    private static instance;
+    private readonly logger;
+    private deps;
+    private state;
+    /** Per-session in-flight prepare (serialises prepares; waited on by terminal writes) */
+    private readonly inFlight;
+    /** Last time a message was written to a session (terminal write / deliver) */
+    private readonly lastDelivery;
+    private constructor();
+    /**
+     * @returns The singleton
+     */
+    static getInstance(): FreshTaskConversationService;
+    /**
+     * Replace the singleton with one using the given collaborators (tests).
+     *
+     * @param deps - Overrides for the default deps
+     * @returns The new singleton
+     */
+    static createForTesting(deps: Partial<FreshTaskDeps>): FreshTaskConversationService;
+    /** Drop the singleton (tests). */
+    static resetInstance(): void;
+    /**
+     * Record that a message is being written to a session. A clear right after
+     * would wipe it before the agent reads it, so {@link prepareForTask} skips
+     * clearing for a short window (this includes the dispatcher's own briefs,
+     * so two tasks dispatched back to back never clear each other).
+     *
+     * @param sessionName - Session written to
+     */
+    noteDelivery(sessionName: string): void;
+    /**
+     * Wait (bounded) while a prepare — possibly a `/clear` — is running for the
+     * session, so a message written now is not wiped by it.
+     *
+     * @param sessionName - Session about to be written to
+     * @param maxMs - Upper bound on the wait
+     */
+    waitIfClearing(sessionName: string, maxMs?: number): Promise<void>;
+    /**
+     * Root of the last task delivered to a session.
+     *
+     * @param sessionName - Session
+     * @returns Root id or null
+     */
+    getLastRoot(sessionName: string): string | null;
+    /**
+     * Called right before a task is written to an agent. Starts a fresh
+     * conversation when the task's root differs from the previous one and it
+     * is safe to; always records the new root. Never throws.
+     *
+     * @param sessionName - Target session
+     * @param workItem - Task being delivered
+     * @returns Whether it cleared, and the handover file when it did
+     */
+    prepareForTask(sessionName: string, workItem: Pick<WorkItem, 'id'>): Promise<PrepareForTaskResult>;
+    private doPrepare;
+    /**
+     * Write the handover file (same shape as the orchestrator's restart handover).
+     *
+     * @returns Its path
+     */
+    private writeHandover;
+    /**
+     * The capped text stored through memory: where the handover is plus the
+     * newest part of what was said.
+     */
+    private conciseHandover;
+    /**
+     * After `/clear`, find the transcript Claude Code starts for this agent and
+     * store its id; if none shows up in time, clear the stored id so a restart
+     * starts fresh rather than resuming the pre-clear conversation.
+     *
+     * A candidate is a `.jsonl` in the agent's transcript directory, modified
+     * since the clear, not the old id, not claimed by another session, and
+     * mentioning this session's name (the dispatch text written right after the
+     * clear carries it) — several agents can share one cwd.
+     */
+    private trackNewConversation;
+    /**
+     * One scan of the transcript directory.
+     *
+     * @returns The new conversation id, or null
+     */
+    private findNewTranscript;
+    /** Whether the start of a transcript mentions the session name. */
+    private fileMentions;
+    private statePath;
+    private loadState;
+    private recordRoot;
+}
+//# sourceMappingURL=fresh-task-conversation.service.d.ts.map

package/dist/backend/backend/src/services/agent/fresh-task-conversation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fresh-task-conversation.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/agent/fresh-task-conversation.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAiBH,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,mCAAmC,CAAC;AAMlF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAI7F;AAED,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,oBAAoB;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,wBAAwB;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,iBAAiB,CAWxF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAMD,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,cAAc;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,CAAC;IACrE,yDAAyD;IACzD,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3D,oCAAoC;IACpC,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,wDAAwD;IACxD,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,wBAAwB;IACxB,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,qEAAqE;IACrE,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,4CAA4C;IAC5C,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,oDAAoD;IACpD,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/D,wEAAwE;IACxE,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChH,2CAA2C;IAC3C,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY;IACZ,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,YAAY;IACZ,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AA2FD,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,4BAA4B;IACvC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6C;IAEpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAA+B;IAC5C,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoD;IAC7E,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D,OAAO;IAKP;;OAEG;WACW,WAAW,IAAI,4BAA4B;IAOzD;;;;;OAKG;WACW,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,4BAA4B;IAK1F,kCAAkC;WACpB,aAAa,IAAI,IAAI;IAInC;;;;;;;OAOG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIvC;;;;;;OAMG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAkE,GACxE,OAAO,CAAC,IAAI,CAAC;IAchB;;;;;OAKG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI/C;;;;;;;;OAQG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC;YA2B1F,SAAS;IAmGvB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IA8BrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;;;;;;OASG;YACW,oBAAoB;IA+BlC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA4BzB,mEAAmE;IACnE,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,UAAU;CAiBnB"}