crewly 1.20.153 → 1.20.155

package/dist/backend/backend/src/services/memory/standing-answers.service.d.ts

@@ -0,0 +1,247 @@
+/**
+ * StandingAnswersService — question-anchored pages kept current from memory.
+ *
+ * Memory is a flat pile (in this repo: ~330 decisions, ~190 gotchas, ~120
+ * patterns) that agents must `recall`, and recall rarely hits at startup.
+ * A standing-answer page is the settled answer to one recurring question
+ * ("What decisions are in force?"), written by an agent from the entries
+ * behind it and read at boot as a plain file (#816). The idea is the
+ * "mental models" of vectorize-io/hindsight, copied as an idea only.
+ *
+ * Page file:
+ *
+ * ```
+ * ---
+ * question: "What decisions are in force?"
+ * last_refreshed: 2026-09-26T15:00:00.000Z
+ * watermark: 2026-09-26T14:58:12.000Z
+ * ---
+ *
+ * ## Prompt assembly
+ * New prompt content must be a prompt module ...
+ *
+ * Sources: dec:0f3c..., dec:9a1b...
+ * ```
+ *
+ * - `watermark` is the newest timestamp among the page's in-scope memory
+ *   entries when it was last written. A page is **stale** when an in-scope
+ *   entry is newer than its watermark.
+ * - Every section cites the entries it was built from. Writes go through
+ *   {@link StandingAnswersService.writeSection}, which checks each citation
+ *   against the page's sources and masks anything that looks like a secret.
+ * - No LLM runs here. The only writer is an agent working a refresh
+ *   WorkItem (see standing-refresh.service.ts), raised only when the
+ *   watermark moves.
+ *
+ * @module services/memory/standing-answers.service
+ */
+/** Whose knowledge a page summarises. */
+export type StandingScope = 'project' | 'agent';
+/** Which memory collection a page is built from. */
+export type StandingSource = 'decisions' | 'gotchas' | 'user_preferences' | 'agent_memory';
+/** A standing-answer page definition. */
+export interface StandingPageDef {
+    /** Stable page id; also the file name for project pages (`<id>.md`). */
+    id: string;
+    scope: StandingScope;
+    /** The recurring question the page answers. */
+    question: string;
+    source: StandingSource;
+}
+/** One memory entry a page may be built from, normalised across sources. */
+export interface StandingSourceEntry {
+    /** Citation token, `<kind>:<id>` (kinds: dec, got, pref, mem). */
+    cite: string;
+    title: string;
+    text: string;
+    /** Newest relevant timestamp of the entry (ISO); drives the watermark. */
+    at: string;
+    /** False for superseded decisions, resolved gotchas, superseded memories. */
+    inForce: boolean;
+}
+/** One `## heading` section of a page. */
+export interface StandingSection {
+    heading: string;
+    body: string;
+    cites: string[];
+}
+/** A parsed page file. */
+export interface StandingPage {
+    question?: string;
+    lastRefreshed?: string;
+    watermark?: string;
+    sections: StandingSection[];
+}
+/** Where to look: a project, an agent session, or both. */
+export interface StandingLocation {
+    projectPath?: string;
+    sessionName?: string;
+}
+/** A page definition resolved against the disk and its sources. */
+export interface StandingPageStatus {
+    def: StandingPageDef;
+    filePath: string;
+    /** Parsed page, or undefined when the file does not exist. */
+    page?: StandingPage;
+    /** Newest in-scope entry timestamp now, or null when there are no entries. */
+    currentWatermark: string | null;
+    /** In-scope entries examined. */
+    entriesInScope: number;
+    /** In-scope entries newer than the page's watermark (all of them when it has none). */
+    newerEntries: number;
+    /** True when the page is missing, has no watermark, or has newer entries. */
+    stale: boolean;
+}
+/** Input to {@link StandingAnswersService.writeSection}. */
+export interface WriteSectionInput extends StandingLocation {
+    pageId: string;
+    heading: string;
+    /** Section body; an empty body removes the section. */
+    body: string;
+    /** Citations (`dec:<id>` …); at least one unless removing. */
+    cites: string[];
+}
+/** Result of a section write. */
+export interface WriteSectionResult {
+    filePath: string;
+    watermark: string | null;
+    removed: boolean;
+    /** True when something that looked like a secret was masked out. */
+    masked: boolean;
+}
+/** Error codes for rejected writes. */
+export type StandingErrorCode = 'unknown_page' | 'invalid_input' | 'unknown_cite' | 'missing_cite';
+/** A write rejected for a reason the caller can fix. */
+export declare class StandingAnswersError extends Error {
+    readonly code: StandingErrorCode;
+    constructor(code: StandingErrorCode, message: string);
+}
+/** Project-scope pages, under `<project>/.crewly/wiki/llm-curated/standing/`. */
+export declare const PROJECT_STANDING_PAGES: readonly StandingPageDef[];
+/** The agent page, at `<CREWLY_HOME>/agents/<session>/standing.md`. */
+export declare const AGENT_STANDING_PAGE: StandingPageDef;
+/**
+ * Look up a page definition by id.
+ *
+ * @param pageId - Page id
+ * @returns The definition, or undefined
+ */
+export declare function findStandingPageDef(pageId: string): StandingPageDef | undefined;
+/**
+ * Parse a standing page file.
+ *
+ * Tolerant of hand edits: unknown frontmatter keys are ignored, text before
+ * the first `## ` heading is ignored, and a section's trailing
+ * `Sources: a, b` line becomes its citations.
+ *
+ * @param raw - File contents
+ * @returns The parsed page
+ */
+export declare function parseStandingPage(raw: string): StandingPage;
+/**
+ * Serialise a page back to its file form.
+ *
+ * @param page - Page to write
+ * @returns File contents
+ */
+export declare function serializeStandingPage(page: StandingPage): string;
+/**
+ * Replace, append or remove one section (matched by heading, case-insensitive).
+ *
+ * @param page - Page to edit (not mutated)
+ * @param section - New section; an empty body removes the heading
+ * @returns The edited page and whether a section was removed
+ */
+export declare function upsertSection(page: StandingPage, section: StandingSection): {
+    page: StandingPage;
+    removed: boolean;
+};
+/**
+ * The newest timestamp among entries, as ISO, or null for none.
+ *
+ * @param entries - Source entries
+ * @returns ISO watermark or null
+ */
+export declare function computeWatermark(entries: readonly StandingSourceEntry[]): string | null;
+/**
+ * Count entries strictly newer than a watermark (all, when there is none).
+ *
+ * @param entries - Source entries
+ * @param watermark - Page watermark (ISO) or undefined
+ * @returns Number of newer entries
+ */
+export declare function countNewer(entries: readonly StandingSourceEntry[], watermark: string | undefined): number;
+/**
+ * Reads, checks and writes standing-answer pages.
+ *
+ * Stateless apart from its paths; every call reads the files fresh, which
+ * keeps the boot-time read honest (no cache can hide a newer memory).
+ */
+export declare class StandingAnswersService {
+    private readonly crewlyHome;
+    /**
+     * @param options - `crewlyHome` overrides {@link getCrewlyHomePath} (tests)
+     */
+    constructor(options?: {
+        crewlyHome?: string;
+    });
+    /**
+     * File path of a page for a location.
+     *
+     * @param def - Page definition
+     * @param loc - Project path (project pages) or session name (agent page)
+     * @returns Absolute path, or null when the location lacks what the scope needs
+     */
+    pagePath(def: StandingPageDef, loc: StandingLocation): string | null;
+    /**
+     * Load the memory entries a page is built from. Missing or unreadable
+     * files yield an empty list (a fresh project has no memory yet).
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Normalised entries, newest first
+     */
+    loadSourceEntries(def: StandingPageDef, loc: StandingLocation): Promise<StandingSourceEntry[]>;
+    /**
+     * Resolve a page against the disk and its sources.
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Status, or null when the location cannot hold this page
+     */
+    getPageStatus(def: StandingPageDef, loc: StandingLocation): Promise<StandingPageStatus | null>;
+    /**
+     * Status of every page a location can hold: the project pages when a
+     * project path is given, the agent page when a session is given.
+     *
+     * @param loc - Location
+     * @returns Statuses, project pages first
+     */
+    listPageStatuses(loc: StandingLocation): Promise<StandingPageStatus[]>;
+    /**
+     * Write one section of a page (section-level edit).
+     *
+     * Validates the heading and body, requires every citation to name an
+     * entry in the page's sources, masks secrets, then stamps
+     * `last_refreshed` and moves `watermark` to the sources' current
+     * watermark. Creates the page (with its question) when missing.
+     *
+     * @param input - Page, location, section and citations
+     * @returns Where it was written and the new watermark
+     * @throws StandingAnswersError for an unknown page, bad input, or a
+     *   citation that is missing or does not resolve
+     */
+    writeSection(input: WriteSectionInput): Promise<WriteSectionResult>;
+    /**
+     * The brief for a refresh WorkItem: the question, the current sections,
+     * and the in-scope entries to use (newer than the watermark first), with
+     * secrets masked and each entry's citation token.
+     *
+     * @param status - The page's status
+     * @param loc - Location (for the skill command)
+     * @param agentSkillsPath - Absolute path of the agent skills directory
+     * @returns Markdown brief
+     */
+    buildRefreshBrief(status: StandingPageStatus, loc: StandingLocation, agentSkillsPath: string): Promise<string>;
+}
+//# sourceMappingURL=standing-answers.service.d.ts.map

package/dist/backend/backend/src/services/memory/standing-answers.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standing-answers.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/standing-answers.service.ts"],"names":[],"mappings":"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"}