crewly 1.13.0 → 1.13.1

package/dist/cli/backend/src/services/memory/mission-context.service.js

@@ -0,0 +1,365 @@
+/**
+ * Mission Context Service — auto-injectable mission card for agent prompts.
+ *
+ * Builds a compact (≤2KB) markdown card that summarizes the active
+ * project OKR, the team's most-relevant active missions, and the team
+ * sub-OKR (if any) so every agent wakes with the answer to "what
+ * mission am I serving right now?".
+ *
+ * Per Memory Phase 1 / Fix M1: today, agents must call `recall` or
+ * `get_goals` explicitly to find the mission they're serving — and per
+ * the architecture audit, an agent can finish a sprint without ever
+ * reading it. This service closes that gap by feeding a tiny mission
+ * card into prompt assembly automatically.
+ *
+ * Out of scope for Phase 1 (deferred to later phases):
+ *   - Narrative summarization of mission state (no LLM round-trip here)
+ *   - Vector embedding / semantic recall
+ *   - Memory review queue / supersession
+ *
+ * @module services/memory/mission-context.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { LoggerService } from '../core/logger.service.js';
+import { GoalTrackingService } from './goal-tracking.service.js';
+import { sortMissionsByPriority, } from '../../types/v2/mission.types.js';
+import { MEMORY_CONSTANTS } from '../../constants.js';
+// ---------------------------------------------------------------------------
+// Tunables
+// ---------------------------------------------------------------------------
+/**
+ * Hard upper bound on the rendered mission card. The spec calls for
+ * 1-2KB; we cap at 2KB and truncate by section priority (most-recent
+ * status → oldest first) when over budget.
+ */
+export const MISSION_CONTEXT_HARD_CAP_BYTES = 2048;
+/** Maximum lines extracted from `goals.md` for the project-OKR slice. */
+const GOALS_MAX_LINES = 4;
+/** Maximum active missions to surface per call (sorted by priority + recency). */
+const MAX_MISSIONS = 2;
+/** Maximum status updates surfaced under "Recent Mission Status". */
+const MAX_STATUS_UPDATES = 3;
+/** Maximum lines extracted from the team sub-OKR file. */
+const TEAM_SUB_OKR_MAX_LINES = 4;
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Builds a small markdown card describing the agent's mission context.
+ *
+ * Singleton, side-effect-free reads. All file IO is fail-soft: any
+ * read or parse error skips the affected section but never throws into
+ * the prompt-assembly path.
+ *
+ * @example
+ * ```ts
+ * const svc = MissionContextService.getInstance();
+ * const card = await svc.getContextForAgent({
+ *   agentId: 'crewly-product-leo-21a5477e',
+ *   projectPath: '/Users/me/projects/crewly',
+ *   teamId: '28a4ac10-...',
+ *   teamSlug: 'product',
+ * });
+ * if (card) prompt += `\n${card}`;
+ * ```
+ */
+export class MissionContextService {
+    static instance = null;
+    logger;
+    goalService;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('MissionContextService');
+        this.goalService = GoalTrackingService.getInstance();
+    }
+    /** Get the shared singleton instance. */
+    static getInstance() {
+        if (!MissionContextService.instance) {
+            MissionContextService.instance = new MissionContextService();
+        }
+        return MissionContextService.instance;
+    }
+    /** Reset for tests. */
+    static clearInstance() {
+        MissionContextService.instance = null;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Build the mission-context card for an agent.
+     *
+     * Returns the empty string when no signals are available — callers
+     * should treat empty output as "skip the section entirely" rather
+     * than rendering an empty heading.
+     *
+     * @param req - Request inputs
+     * @returns A ≤2KB markdown card, or `''` when nothing is worth showing
+     */
+    async getContextForAgent(req) {
+        const goalsLines = await this.loadProjectGoalsSlice(req.projectPath);
+        // Filter accepts the agent's own team plus any ancestors (parent OKRs).
+        // De-duped at the call site; service treats the resulting set as the
+        // authoritative match list.
+        const teamScope = uniqueNonEmpty([req.teamId, ...(req.ancestorTeamIds ?? [])]);
+        const missions = await this.loadActiveTeamMissions(req.projectPath, teamScope);
+        const teamSubOkrLines = await this.loadTeamSubOkrSlice(req.projectPath, req.teamSlug);
+        const statusUpdates = collectRecentStatusUpdates(missions);
+        if (goalsLines.length === 0 &&
+            missions.length === 0 &&
+            teamSubOkrLines.length === 0 &&
+            statusUpdates.length === 0) {
+            this.logger.debug('No mission signals — emitting empty card', {
+                agentId: req.agentId,
+                teamId: req.teamId,
+            });
+            return '';
+        }
+        const card = renderMissionCard({
+            goalsLines,
+            missions: missions.slice(0, MAX_MISSIONS),
+            teamSubOkrLines,
+            statusUpdates: statusUpdates.slice(0, MAX_STATUS_UPDATES),
+        });
+        const capped = enforceHardCap(card, MISSION_CONTEXT_HARD_CAP_BYTES);
+        this.logger.debug('Mission card built', {
+            agentId: req.agentId,
+            teamId: req.teamId,
+            bytes: Buffer.byteLength(capped, 'utf-8'),
+            missionCount: missions.length,
+        });
+        return capped;
+    }
+    // -------------------------------------------------------------------------
+    // Internal readers (each one fail-soft — never throws)
+    // -------------------------------------------------------------------------
+    /**
+     * Read up to `GOALS_MAX_LINES` non-empty, non-comment lines from
+     * the project's `goals.md`. Returns `[]` when the file is missing.
+     */
+    async loadProjectGoalsSlice(projectPath) {
+        try {
+            const raw = await this.goalService.getGoals(projectPath);
+            if (!raw)
+                return [];
+            return extractMeaningfulLines(raw, GOALS_MAX_LINES);
+        }
+        catch (err) {
+            this.logger.warn('Failed to load project goals.md', {
+                projectPath,
+                error: errMsg(err),
+            });
+            return [];
+        }
+    }
+    /**
+     * Read all `*.json` files under `<projectPath>/.crewly/missions/`,
+     * filter to active missions whose `ownerTeamId` is in the supplied
+     * `teamScope` (own team + any ancestor teams the caller passed in),
+     * and sort by priority + recency. Returns `[]` on any error.
+     */
+    async loadActiveTeamMissions(projectPath, teamScope) {
+        if (teamScope.length === 0)
+            return [];
+        const dir = path.join(projectPath, '.crewly', 'missions');
+        let files;
+        try {
+            files = await fs.readdir(dir);
+        }
+        catch {
+            // Directory missing == no missions == empty section. Not an error.
+            return [];
+        }
+        const scope = new Set(teamScope);
+        const missions = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(dir, file), 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed.status === 'active' && scope.has(parsed.ownerTeamId)) {
+                    missions.push(parsed);
+                }
+            }
+            catch (err) {
+                this.logger.debug('Skipping unreadable mission file', {
+                    file,
+                    error: errMsg(err),
+                });
+            }
+        }
+        return sortMissionsByPriority(missions);
+    }
+    /**
+     * Read the team sub-OKR file at
+     * `<projectPath>/.crewly/goals/<teamSlug>-team-sub-okr.md`. Returns
+     * `[]` when no slug, no file, or any read error.
+     */
+    async loadTeamSubOkrSlice(projectPath, teamSlug) {
+        if (!teamSlug)
+            return [];
+        const filePath = path.join(projectPath, '.crewly', MEMORY_CONSTANTS.PATHS.GOALS_DIR, `${teamSlug}-team-sub-okr.md`);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            return extractMeaningfulLines(raw, TEAM_SUB_OKR_MAX_LINES);
+        }
+        catch {
+            // Missing file is the common case — skip silently.
+            return [];
+        }
+    }
+}
+/**
+ * Collect the most recent status updates across the supplied missions.
+ * A mission contributes at most one entry. Missions with no
+ * `lastReviewSummary` are skipped. Result is sorted by `lastReviewAt`
+ * descending; missions with no `lastReviewAt` sort last.
+ */
+export function collectRecentStatusUpdates(missions) {
+    const updates = [];
+    for (const m of missions) {
+        if (!m.lastReviewSummary)
+            continue;
+        updates.push({
+            missionId: m.id,
+            objective: m.objective,
+            summary: m.lastReviewSummary,
+            reviewedAt: m.lastReviewAt,
+        });
+    }
+    updates.sort((a, b) => {
+        const ta = a.reviewedAt ? Date.parse(a.reviewedAt) : 0;
+        const tb = b.reviewedAt ? Date.parse(b.reviewedAt) : 0;
+        return tb - ta;
+    });
+    return updates;
+}
+/**
+ * Extract up to `maxLines` "meaningful" lines from a markdown blob.
+ *
+ * Rules:
+ *   - skip empty lines
+ *   - skip standalone HTML/MD comments
+ *   - keep headings, prose, list items
+ *   - trim trailing whitespace
+ *   - de-duplicate consecutive identical lines
+ */
+export function extractMeaningfulLines(raw, maxLines) {
+    const out = [];
+    let lastPushed = '';
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (!line.trim())
+            continue;
+        if (/^\s*<!--.*-->\s*$/.test(line))
+            continue;
+        if (line === lastPushed)
+            continue;
+        out.push(line);
+        lastPushed = line;
+        if (out.length >= maxLines)
+            break;
+    }
+    return out;
+}
+/**
+ * Render the final mission card as markdown using the spec template.
+ * Sections with no data are omitted entirely (no empty headings).
+ */
+export function renderMissionCard(args) {
+    const { goalsLines, missions, teamSubOkrLines, statusUpdates } = args;
+    const sections = ['## Current Mission Context', ''];
+    if (goalsLines.length > 0) {
+        sections.push('Active Project OKR (90-day):');
+        for (const line of goalsLines)
+            sections.push(line);
+        sections.push('');
+    }
+    if (missions.length > 0) {
+        sections.push('Current Active Missions:');
+        for (const m of missions) {
+            sections.push(`- ${formatMissionLine(m)}`);
+        }
+        sections.push('');
+    }
+    if (teamSubOkrLines.length > 0) {
+        sections.push("Your Team's Sub-OKR:");
+        for (const line of teamSubOkrLines)
+            sections.push(line);
+        sections.push('');
+    }
+    if (statusUpdates.length > 0) {
+        sections.push('Recent Mission Status:');
+        for (const u of statusUpdates) {
+            sections.push(`- ${formatStatusLine(u)}`);
+        }
+        sections.push('');
+    }
+    // Trim trailing blank line for tidiness
+    while (sections.length > 0 && sections[sections.length - 1] === '') {
+        sections.pop();
+    }
+    return sections.join('\n');
+}
+/**
+ * Format one mission as a single line: priority + objective +
+ * top-of-success-criteria summary.
+ */
+function formatMissionLine(m) {
+    const priority = m.priority ?? 'medium';
+    const tail = m.successCriteria?.length > 0 ? ` — ${m.successCriteria[0]}` : '';
+    return `[${priority}] ${m.objective}${tail}`;
+}
+/** Format one status update as a single bullet. */
+function formatStatusLine(u) {
+    const date = u.reviewedAt ? u.reviewedAt.slice(0, 10) : '—';
+    return `${date}: ${u.objective} — ${u.summary}`;
+}
+/**
+ * Enforce the hard byte cap. If `card` already fits, returns it
+ * unchanged. Otherwise truncates line-by-line from the bottom until
+ * it fits, then appends a single ellipsis line so the card is
+ * obviously truncated.
+ */
+export function enforceHardCap(card, maxBytes) {
+    if (Buffer.byteLength(card, 'utf-8') <= maxBytes)
+        return card;
+    const lines = card.split('\n');
+    const ellipsis = '… (truncated to fit 2KB cap)';
+    while (lines.length > 0) {
+        lines.pop();
+        const candidate = `${lines.join('\n')}\n${ellipsis}`;
+        if (Buffer.byteLength(candidate, 'utf-8') <= maxBytes) {
+            return candidate;
+        }
+    }
+    // Even the heading didn't fit — return just the ellipsis.
+    return ellipsis;
+}
+/** Stringify an unknown error for log fields. */
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Return the input array de-duplicated and stripped of empty / falsy
+ * entries while preserving first-seen order.
+ */
+function uniqueNonEmpty(values) {
+    const out = [];
+    const seen = new Set();
+    for (const v of values) {
+        if (!v)
+            continue;
+        if (seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+/**
+ * Module-level convenience: get the singleton in one call.
+ */
+export const getMissionContextService = () => MissionContextService.getInstance();
+//# sourceMappingURL=mission-context.service.js.map

package/dist/cli/backend/src/services/memory/mission-context.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mission-context.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/mission-context.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAEL,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD,yEAAyE;AACzE,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,kFAAkF;AAClF,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,qEAAqE;AACrE,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,0DAA0D;AAC1D,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAuCjC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,qBAAqB;IACxB,MAAM,CAAC,QAAQ,GAAiC,IAAI,CAAC;IAC5C,MAAM,CAAkB;IACxB,WAAW,CAAsB;IAElD;QACE,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAC7D,uBAAuB,CACxB,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,mBAAmB,CAAC,WAAW,EAAE,CAAC;IACvD,CAAC;IAED,yCAAyC;IAClC,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,CAAC;YACpC,qBAAqB,CAAC,QAAQ,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC/D,CAAC;QACD,OAAO,qBAAqB,CAAC,QAAQ,CAAC;IACxC,CAAC;IAED,uBAAuB;IAChB,MAAM,CAAC,aAAa;QACzB,qBAAqB,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxC,CAAC;IAED,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;;OASG;IACI,KAAK,CAAC,kBAAkB,CAAC,GAA0B;QACxD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACrE,wEAAwE;QACxE,qEAAqE;QACrE,4BAA4B;QAC5B,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC/E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAChD,GAAG,CAAC,WAAW,EACf,SAAS,CACV,CAAC;QACF,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,mBAAmB,CACpD,GAAG,CAAC,WAAW,EACf,GAAG,CAAC,QAAQ,CACb,CAAC;QACF,MAAM,aAAa,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;QAE3D,IACE,UAAU,CAAC,MAAM,KAAK,CAAC;YACvB,QAAQ,CAAC,MAAM,KAAK,CAAC;YACrB,eAAe,CAAC,MAAM,KAAK,CAAC;YAC5B,aAAa,CAAC,MAAM,KAAK,CAAC,EAC1B,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAE;gBAC5D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,iBAAiB,CAAC;YAC7B,UAAU;YACV,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;YACzC,eAAe;YACf,aAAa,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC;SAC1D,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE;YACtC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC;YACzC,YAAY,EAAE,QAAQ,CAAC,MAAM;SAC9B,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,4EAA4E;IAC5E,uDAAuD;IACvD,4EAA4E;IAE5E;;;OAGG;IACK,KAAK,CAAC,qBAAqB,CAAC,WAAmB;QACrD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YACzD,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,CAAC;YACpB,OAAO,sBAAsB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE;gBAClD,WAAW;gBACX,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,sBAAsB,CAClC,WAAmB,EACnB,SAAmB;QAEnB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QAC1D,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;YACnE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,SAAS;YACtC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;gBAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;gBAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;oBAChE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE;oBACpD,IAAI;oBACJ,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;iBACnB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,mBAAmB,CAC/B,WAAmB,EACnB,QAA4B;QAE5B,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CACxB,WAAW,EACX,SAAS,EACT,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAChC,GAAG,QAAQ,kBAAkB,CAC9B,CAAC;QACF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACjD,OAAO,sBAAsB,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;YACnD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;;AAkBH;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAmB;IAEnB,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,iBAAiB;YAAE,SAAS;QACnC,OAAO,CAAC,IAAI,CAAC;YACX,SAAS,EAAE,CAAC,CAAC,EAAE;YACf,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,OAAO,EAAE,CAAC,CAAC,iBAAiB;YAC5B,UAAU,EAAE,CAAC,CAAC,YAAY;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAW,EACX,QAAgB;IAEhB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7C,IAAI,IAAI,KAAK,UAAU;YAAE,SAAS;QAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,UAAU,GAAG,IAAI,CAAC;QAClB,IAAI,GAAG,CAAC,MAAM,IAAI,QAAQ;YAAE,MAAM;IACpC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAKjC;IACC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACtE,MAAM,QAAQ,GAAa,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;IAE9D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,UAAU;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CAAC,KAAK,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,QAAQ,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,eAAe;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,wCAAwC;IACxC,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QACnE,QAAQ,CAAC,GAAG,EAAE,CAAC;IACjB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,CAAU;IACnC,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,IAAI,QAAQ,CAAC;IACxC,MAAM,IAAI,GACR,CAAC,CAAC,eAAe,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,OAAO,IAAI,QAAQ,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,mDAAmD;AACnD,SAAS,gBAAgB,CAAC,CAAsB;IAC9C,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC5D,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAAgB;IAC3D,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,8BAA8B,CAAC;IAChD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,GAAG,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACrD,IAAI,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;YACtD,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,0DAA0D;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iDAAiD;AACjD,SAAS,MAAM,CAAC,GAAY;IAC1B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,MAAgD;IACtE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAA0B,EAAE,CAClE,qBAAqB,CAAC,WAAW,EAAE,CAAC"}

package/dist/cli/backend/src/services/memory/session-memory.service.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Session Memory Service
+ *
+ * Manages session lifecycle for agents: startup briefings, session summaries,
+ * and the project-level agents index. Coordinates with AgentMemoryService and
+ * ProjectMemoryService to assemble the context an agent needs when it starts
+ * a new work session and to persist what it learned when the session ends.
+ *
+ * Storage locations:
+ * - Session summaries: ~/.crewly/agents/{agentId}/sessions/
+ * - Agents index: {projectPath}/.crewly/agents-index.json
+ *
+ * @module services/memory/session-memory.service
+ */
+import type { StartupBriefing } from '../../types/memory.types.js';
+/**
+ * Service for managing agent session lifecycle
+ *
+ * Follows singleton pattern for consistent state management.
+ * Coordinates AgentMemoryService and ProjectMemoryService to build
+ * startup briefings and persist session summaries.
+ *
+ * @example
+ * ```typescript
+ * const sessionMemory = SessionMemoryService.getInstance();
+ * await sessionMemory.onSessionStart('dev-001', 'developer', '/projects/app');
+ *
+ * // ... agent works ...
+ *
+ * await sessionMemory.onSessionEnd('dev-001', 'developer', '/projects/app', 'Implemented auth');
+ * ```
+ */
+export declare class SessionMemoryService {
+    private static instance;
+    private readonly logger;
+    /**
+     * Creates a new SessionMemoryService instance
+     *
+     * Private constructor -- use {@link getInstance} to obtain the singleton.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of SessionMemoryService
+     *
+     * @returns The singleton SessionMemoryService instance
+     */
+    static getInstance(): SessionMemoryService;
+    /**
+     * Clears the singleton instance (useful for testing)
+     */
+    static clearInstance(): void;
+    /**
+     * Returns the absolute path to the Crewly home directory (~/.crewly)
+     *
+     * @returns Absolute path to Crewly home
+     */
+    private getAgentmuxHome;
+    /**
+     * Returns the sessions archive directory for a given agent
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Absolute path to the agent's sessions directory
+     *
+     * @example
+     * ```typescript
+     * // Returns: ~/.crewly/agents/dev-001/sessions
+     * this.getSessionsDir('dev-001');
+     * ```
+     */
+    private getSessionsDir;
+    /**
+     * Safely reads a file and returns its contents as a string, or null if the
+     * file does not exist or cannot be read.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns File contents or null on any error
+     */
+    private safeReadFile;
+    /**
+     * Truncates a string to a maximum number of characters, appending an
+     * ellipsis marker when truncation occurs.
+     *
+     * @param text - The input string
+     * @param maxChars - Maximum number of characters to retain
+     * @returns Truncated string (or original if within limit)
+     */
+    private truncate;
+    /**
+     * Called when an agent session starts
+     *
+     * Initializes both agent-level and project-level memory stores (if not
+     * already initialized) and updates the project agents index so that the
+     * orchestrator knows which agents have worked on a project.
+     *
+     * @param agentId - Unique identifier for the agent
+     * @param role - Agent's role (e.g., 'developer', 'qa', 'pm')
+     * @param projectPath - Absolute path to the project the agent is working on
+     *
+     * @example
+     * ```typescript
+     * await sessionMemory.onSessionStart('backend-dev-001', 'developer', '/home/user/project');
+     * ```
+     */
+    onSessionStart(agentId: string, role: string, projectPath: string): Promise<void>;
+    /**
+     * Called when an agent session ends
+     *
+     * Persists a timestamped session summary markdown file under the agent's
+     * sessions directory and also writes a `latest-summary.md` symlink-equivalent
+     * so that the next startup briefing can quickly locate the most recent summary.
+     *
+     * @param agentId - Unique identifier for the agent
+     * @param role - Agent's role
+     * @param projectPath - Absolute path to the project
+     * @param summary - Optional human-readable summary of what the agent accomplished
+     *
+     * @example
+     * ```typescript
+     * await sessionMemory.onSessionEnd(
+     *   'backend-dev-001',
+     *   'developer',
+     *   '/home/user/project',
+     *   'Implemented user authentication with JWT tokens and added integration tests.',
+     * );
+     * ```
+     */
+    onSessionEnd(agentId: string, role: string, projectPath: string, summary?: string): Promise<void>;
+    /**
+     * Generates a startup briefing for an agent that is about to begin a session
+     *
+     * Aggregates context from multiple sources:
+     * - The agent's most recent session summary
+     * - Agent-level knowledge, preferences, and performance data
+     * - Project-level patterns, decisions, and gotchas
+     * - Today's daily log, active goals, and learning files
+     *
+     * All reads are best-effort: a missing file simply produces a null or empty
+     * field rather than an error.
+     *
+     * @param agentId - Unique identifier for the agent
+     * @param role - Agent's role
+     * @param projectPath - Absolute path to the project
+     * @returns A {@link StartupBriefing} containing all available context
+     *
+     * @example
+     * ```typescript
+     * const briefing = await sessionMemory.generateStartupBriefing(
+     *   'backend-dev-001',
+     *   'developer',
+     *   '/home/user/project',
+     * );
+     * const markdown = sessionMemory.formatBriefingAsMarkdown(briefing);
+     * ```
+     */
+    generateStartupBriefing(agentId: string, role: string, projectPath: string): Promise<StartupBriefing>;
+    /**
+     * Formats a {@link StartupBriefing} into a markdown string suitable for
+     * prompt injection
+     *
+     * Only includes sections that have non-null, non-empty content. Long
+     * sections are truncated to keep the prompt within reasonable limits.
+     *
+     * @param briefing - The startup briefing to format
+     * @returns A markdown string ready for injection into the agent's system prompt
+     *
+     * @example
+     * ```typescript
+     * const briefing = await sessionMemory.generateStartupBriefing(id, role, path);
+     * const md = sessionMemory.formatBriefingAsMarkdown(briefing);
+     * // md is a string like "## Your Previous Knowledge\n\n### Last Session\n..."
+     * ```
+     */
+    formatBriefingAsMarkdown(briefing: StartupBriefing): string;
+    /**
+     * Updates the project-level agents index with an agent's latest activity
+     *
+     * The agents index lives at `{projectPath}/.crewly/agents-index.json` and
+     * tracks every agent that has worked on the project, along with the timestamp
+     * of their most recent activity.
+     *
+     * If the agent already exists in the index, only the `lastActive` and `role`
+     * fields are updated. Otherwise a new entry is appended.
+     *
+     * @param projectPath - Absolute path to the project
+     * @param agentId - The agent's unique identifier
+     * @param role - Agent's role
+     *
+     * @throws Rethrows file I/O errors other than ENOENT
+     *
+     * @example
+     * ```typescript
+     * await sessionMemory.updateAgentsIndex('/home/user/project', 'dev-001', 'developer');
+     * ```
+     */
+    updateAgentsIndex(projectPath: string, agentId: string, role: string): Promise<void>;
+}
+//# sourceMappingURL=session-memory.service.d.ts.map

package/dist/cli/backend/src/services/memory/session-memory.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-memory.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/session-memory.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,KAAK,EAAkB,eAAe,EAAuC,MAAM,6BAA6B,CAAC;AAQxH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqC;IAE5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6E;IAEpG;;;;OAIG;IAEH,OAAO;IAEP;;;;OAIG;WACW,WAAW,IAAI,oBAAoB;IAOjD;;OAEG;WACW,aAAa,IAAI,IAAI;IAMnC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;OAMG;YACW,YAAY;IAQ1B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ;IAShB;;;;;;;;;;;;;;;OAeG;IACU,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9F;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,YAAY,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmChB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,uBAAuB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;IA4D3B;;;;;;;;;;;;;;;;OAgBG;IACI,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IA2ClE;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BlG"}