@cspeach/cli 0.6.0

package/dist/sap/system-info.js

@@ -0,0 +1,515 @@
+/**
+ * SAP system release detection — auto-fills `<sap_system>` context for
+ * skills so they stop asking "are we on S/4HANA or ECC?" when the
+ * answer can be determined from a single CVERS query.
+ *
+ * Strategy (no redundant calls):
+ *   1. In-memory cache by alias — same session, same alias = no second query
+ *   2. Disk cache at ~/.cspeach/sap-cache/<alias>.json (30-day TTL) —
+ *      reconnecting next morning skips the query entirely
+ *   3. Lazy live query — only when both caches miss, runs ONE small SELECT
+ *      against CVERS (component versions). Round-trip is ~50 bytes / ~50ms.
+ *
+ * Failure mode: any error returns null. The caller injects nothing into
+ * the session context and the skill falls back to its old behavior of
+ * asking. Never blocks a turn.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { auditLog, xmlParser } from '@cspeach/sap-client';
+import { cspeachRoot } from '../config/paths.js';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const memCache = new Map();
+/**
+ * Top-level entry point. Returns cached info when available, queries
+ * CVERS once otherwise, persists the result, returns null on any error.
+ */
+export async function getSapSystemInfo(adt, alias) {
+    // Layer 1 — process memory
+    const cached = memCache.get(alias);
+    if (cached)
+        return cached;
+    // Layer 2 — disk
+    const fromDisk = readDiskCache(alias);
+    if (fromDisk) {
+        memCache.set(alias, fromDisk);
+        return fromDisk;
+    }
+    // Layer 3 — live query
+    const startedAt = Date.now();
+    try {
+        const info = await queryLive(adt, alias);
+        memCache.set(alias, info);
+        const count = Object.keys(info.components).length;
+        // Audit-log every probe outcome. Empty result is itself a signal —
+        // usually means the parser regex doesn't match the server's CVERS
+        // response shape on this release. Without this line every failure
+        // was silent (catch swallowed everything, empty case wrote nothing).
+        if (count > 0) {
+            writeDiskCache(alias, info);
+            await auditLog('sapProbe', 'ALIAS', alias, 'success', Date.now() - startedAt, `components=${count} platform=${info.platform} release=${info.release}`);
+        }
+        else {
+            // Do NOT persist — caching an empty result would freeze a parser
+            // bug into a 30-day "I don't know" answer.
+            await auditLog('sapProbe', 'ALIAS', alias, 'error', Date.now() - startedAt, 'components=0 (parser empty)');
+        }
+        return info;
+    }
+    catch (err) {
+        await auditLog('sapProbe', 'ALIAS', alias, 'error', Date.now() - startedAt, `threw: ${err.message}`);
+        return null;
+    }
+}
+/** Test-only: invalidate caches between tests. */
+export function _resetSystemInfoCache() {
+    memCache.clear();
+}
+async function queryLive(adt, alias) {
+    // S4FND covers some private-cloud variants where S4CORE isn't shipped
+    // — including both broadens detection without extra cost.
+    const sql = `SELECT COMPONENT, RELEASE FROM CVERS WHERE COMPONENT IN ('SAP_BASIS', 'S4CORE', 'S4FND', 'SAP_ABA')`;
+    // Dispatch order is INTENTIONALLY connection-first: AdtClient.sqlQuery
+    // internally uses parseDataPreview which silently returns empty rows on
+    // shapes it doesn't recognise — exactly the failure mode that surfaced
+    // as `components=0 (parser empty)` against live S/4HANA on 2026-05-06.
+    // By going through the raw POST whenever a real connection is available,
+    // we own the parser chain (parseCvers → parseCversTree) end-to-end and
+    // get the dump-on-total-failure diagnostic.
+    //
+    // The sqlQuery fallback exists only for test fakes that pass an adt
+    // shaped as `{ sqlQuery: vi.fn(...) }` with no connection. Production
+    // AdtClient always reaches the connection branch first.
+    let components;
+    const conn = adt.connection;
+    if (conn?.post) {
+        const url = '/sap/bc/adt/datapreview/freestyle?rowNumber=50';
+        const accept = 'application/vnd.sap.adt.datapreview.table.v1+xml';
+        const resp = await conn.post(url, sql, 'text/plain', accept);
+        if (resp.status !== 200)
+            throw new Error(`CVERS query HTTP ${resp.status}`);
+        components = await parseCversAny(resp.body);
+        // Diagnostic dump on total parser failure. Permanent feature — gives
+        // any customer site a self-contained way to send us the actual response
+        // shape when the parser chain can't decode it. Only writes when ALL
+        // parsers returned empty AND the HTTP was 200, so successful sessions
+        // never touch this file.
+        if (Object.keys(components).length === 0) {
+            try {
+                const dir = cacheDir();
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                const safeAlias = alias.replace(/[^A-Za-z0-9._-]/g, '_');
+                const dump = join(dir, `_last-empty-probe-${safeAlias}.xml`);
+                const header = `<!-- HTTP ${resp.status}, ${resp.body.length} bytes, queried ${new Date().toISOString()} -->\n`;
+                writeFileSync(dump, header + resp.body, 'utf8');
+            }
+            catch {
+                // best effort — never block the probe over a debug-write failure
+            }
+        }
+    }
+    else if (adt.sqlQuery) {
+        // Test-fake path — adt provides pre-extracted rows directly.
+        const result = await adt.sqlQuery(sql, 50);
+        components = {};
+        for (const row of result.rows) {
+            let name = '';
+            let rel = '';
+            for (const [k, v] of Object.entries(row)) {
+                const upper = k.toUpperCase();
+                if (upper === 'COMPONENT' || upper.endsWith('.COMPONENT'))
+                    name = String(v ?? '').trim();
+                else if (upper === 'RELEASE' || upper.endsWith('.RELEASE'))
+                    rel = String(v ?? '').trim();
+            }
+            if (name && rel)
+                components[name.toUpperCase()] = rel;
+        }
+    }
+    else {
+        throw new Error('adt has neither connection.post nor sqlQuery available');
+    }
+    return classify(alias, components);
+}
+/**
+ * Parse the SAP ADT data-preview response for our CVERS query.
+ *
+ * Response shape (verified 2026-05-06 against S/4HANA):
+ * ```xml
+ * <dataPreview:tableData>
+ *   <dataPreview:columns>
+ *     <dataPreview:metadata dataPreview:name="COMPONENT" .../>
+ *     <dataPreview:dataSet>
+ *       <dataPreview:data>SAP_BASIS</dataPreview:data>
+ *       <dataPreview:data>S4CORE</dataPreview:data>
+ *       ...
+ *     </dataPreview:dataSet>
+ *   </dataPreview:columns>
+ *   <dataPreview:columns>
+ *     <dataPreview:metadata dataPreview:name="RELEASE" .../>
+ *     <dataPreview:dataSet>
+ *       <dataPreview:data>757</dataPreview:data>
+ *       ...
+ *     </dataPreview:dataSet>
+ *   </dataPreview:columns>
+ * </dataPreview:tableData>
+ * ```
+ *
+ * Note: data is COLUMN-MAJOR (one block per column with all values for
+ * that column inside <dataSet>), not row-major. The shared
+ * parseDataPreview in sap-client/src/xml-parser.ts looks for
+ * <columnName> + <dataRow> + <dataCell> which is a different format —
+ * silently returns empty rows on this shape. Local parser sidesteps
+ * that bug for system-info; sap-client should be fixed properly later
+ * since other tools rely on the same endpoint.
+ */
+export function parseCvers(xml) {
+    const out = {};
+    // Word-boundary `\b` after the tag name is critical — `<data` is a
+    // prefix of `<dataSet>`, so without `\b` the data regex would match
+    // the dataset wrapper too. Same for `columns` defensively.
+    const colsRe = /<(?:[\w:]+:)?columns\b[^>]*>([\s\S]*?)<\/(?:[\w:]+:)?columns\s*>/g;
+    const cols = [];
+    let m;
+    while ((m = colsRe.exec(xml)) !== null) {
+        const block = m[1];
+        // The metadata's name attribute may have a namespace prefix on the
+        // attribute itself (dataPreview:name="...") — match either form.
+        const nameMatch = /<(?:[\w:]+:)?metadata\b[^>]*?\b(?:[\w:]+:)?name="([^"]+)"/i.exec(block);
+        if (!nameMatch)
+            continue;
+        const dataRe = /<(?:[\w:]+:)?data\b[^>]*>([\s\S]*?)<\/(?:[\w:]+:)?data\s*>/g;
+        const values = [];
+        let d;
+        while ((d = dataRe.exec(block)) !== null)
+            values.push(d[1].trim());
+        cols.push({ name: nameMatch[1], values });
+    }
+    const componentCol = cols.find((c) => c.name.toUpperCase() === 'COMPONENT');
+    const releaseCol = cols.find((c) => c.name.toUpperCase() === 'RELEASE');
+    if (!componentCol || !releaseCol)
+        return out;
+    const len = Math.min(componentCol.values.length, releaseCol.values.length);
+    for (let i = 0; i < len; i++) {
+        const c = componentCol.values[i];
+        const r = releaseCol.values[i];
+        if (c && r)
+            out[c.toUpperCase()] = r;
+    }
+    return out;
+}
+/**
+ * System-agnostic CVERS parser. Tries every known shape in turn and
+ * returns the first non-empty result.
+ *
+ * Why a chain instead of one parser: SAP ADT data-preview responses vary
+ * across SAP_BASIS releases, ServicePack levels, and ADT plugin versions.
+ * Live evidence on 2026-05-06: a regex written against documented shape
+ * returned zero components on a real S/4HANA system. Hand-tuning the
+ * regex to that customer's response would just shift the breakage to the
+ * next system. Instead: try cheap regex first, fall back to a tree walk
+ * that's namespace-agnostic and covers both column-major and row-major
+ * encodings, then surrender. Caller writes the raw body to a debug dump
+ * on total failure so unknown shapes can be characterised remotely.
+ *
+ * Shapes covered:
+ *   1. Column-major + namespaced + `metadata name="X"` + `dataSet/data` (regex path)
+ *   2. Same shape but with attribute-name variations or wildly different
+ *      namespace prefixes (tree-walker path A)
+ *   3. Row-major + `columnName` lists + `dataRow/dataCell` rows (tree-walker path B)
+ */
+export async function parseCversAny(xml) {
+    // Attempt 1 — cheap regex (the historical parser). Free, sync, no
+    // dependency on xml2js. Works on the documented shape, doesn't on much else.
+    const regexResult = parseCvers(xml);
+    if (Object.keys(regexResult).length > 0)
+        return regexResult;
+    // Attempt 2 — tree walker via xml2js with namespace stripping. Handles
+    // arbitrary namespace prefixes and both major encoding shapes.
+    try {
+        const treeResult = await parseCversTree(xml);
+        if (Object.keys(treeResult).length > 0)
+            return treeResult;
+    }
+    catch {
+        // tree parse failed — body might be malformed XML or not XML at all
+    }
+    return {};
+}
+/**
+ * xml2js-backed tree walker. Strips namespace prefixes (so `dataPreview:columns`
+ * becomes `columns`), then looks for either:
+ *   A) Column-major: nested `metadata` (with a `name`/`columnName`/`label`
+ *      attribute) plus a sibling `dataSet` containing `data`/`value`/`cell`
+ *      elements — this is the modern S/4HANA shape.
+ *   B) Row-major: a flat list of `columnName` element texts in order, plus
+ *      `dataRow` elements containing `dataCell` children — older NetWeaver shape.
+ *
+ * Either branch returns a flat `{ COMPONENT_NAME: RELEASE_VALUE }` map.
+ *
+ * Exported for direct unit testing of arbitrary fixtures — the production
+ * call site uses `parseCversAny`.
+ */
+export async function parseCversTree(xml) {
+    if (!xml || xml.trim().length === 0)
+        return {};
+    // xml2js throws on non-XML or seriously malformed input. The whole
+    // chain is meant to be tolerant — non-XML is a "this is not the
+    // shape we expected" signal, not an exception. Treat as empty and
+    // let the caller dump the raw body.
+    let tree;
+    try {
+        tree = await xmlParser.parseXml(xml);
+    }
+    catch {
+        return {};
+    }
+    const collected = [];
+    function walk(obj, tag) {
+        let node;
+        if (typeof obj === 'string') {
+            node = { tag, attrs: {}, children: [], text: obj };
+        }
+        else if (typeof obj !== 'object' || obj === null) {
+            node = { tag, attrs: {}, children: [], text: String(obj ?? '') };
+        }
+        else {
+            const o = obj;
+            const attrs = {};
+            if (o['$'] && typeof o['$'] === 'object') {
+                for (const [k, v] of Object.entries(o['$'])) {
+                    attrs[k] = String(v);
+                }
+            }
+            let text = '';
+            const children = [];
+            for (const [k, v] of Object.entries(o)) {
+                if (k === '$')
+                    continue;
+                if (k === '_') {
+                    text = String(v);
+                    continue;
+                }
+                const arr = Array.isArray(v) ? v : [v];
+                for (const item of arr)
+                    children.push(walk(item, k));
+            }
+            node = { tag, attrs, children, text };
+        }
+        collected.push(node);
+        return node;
+    }
+    walk(tree, 'root');
+    // Strategy A — column-major. A column block is any node whose direct
+    // children include a metadata-like element (with a name attribute) AND
+    // a dataSet-like element (with data children).
+    const columns = [];
+    for (const node of collected) {
+        let metaName;
+        let dataSetValues;
+        for (const c of node.children) {
+            if (c.tag === 'metadata' || c.tag === 'columnInfo' || c.tag === 'fieldMetadata') {
+                metaName = metaName ?? c.attrs['name'] ?? c.attrs['columnName'] ?? c.attrs['label'];
+            }
+            if (c.tag === 'dataSet') {
+                const vals = [];
+                for (const dc of c.children) {
+                    if ((dc.tag === 'data' || dc.tag === 'value' || dc.tag === 'cell') && dc.text) {
+                        vals.push(dc.text.trim());
+                    }
+                }
+                if (vals.length > 0)
+                    dataSetValues = vals;
+            }
+        }
+        if (metaName && dataSetValues) {
+            columns.push({ name: metaName.toUpperCase(), values: dataSetValues });
+        }
+    }
+    if (columns.length >= 2) {
+        const comp = columns.find((c) => c.name === 'COMPONENT');
+        const rel = columns.find((c) => c.name === 'RELEASE');
+        if (comp && rel) {
+            const out = {};
+            const n = Math.min(comp.values.length, rel.values.length);
+            for (let i = 0; i < n; i++) {
+                const cv = comp.values[i];
+                const rv = rel.values[i];
+                if (cv && rv)
+                    out[cv.toUpperCase()] = rv;
+            }
+            if (Object.keys(out).length > 0)
+                return out;
+        }
+    }
+    // Strategy B — row-major. columnName texts give us the column ordering;
+    // dataRow elements with dataCell children give us the values.
+    const colNames = [];
+    const rowEls = [];
+    for (const node of collected) {
+        if (node.tag === 'columnName' && node.text)
+            colNames.push(node.text.trim());
+        if (node.tag === 'dataRow' || node.tag === 'row')
+            rowEls.push(node);
+    }
+    if (colNames.length > 0 && rowEls.length > 0) {
+        const compIdx = colNames.findIndex((n) => n.toUpperCase() === 'COMPONENT');
+        const relIdx = colNames.findIndex((n) => n.toUpperCase() === 'RELEASE');
+        if (compIdx >= 0 && relIdx >= 0) {
+            const out = {};
+            for (const r of rowEls) {
+                const cells = r.children.filter((c) => c.tag === 'dataCell' || c.tag === 'cell' || c.tag === 'value');
+                const compVal = cells[compIdx]?.text?.trim();
+                const relVal = cells[relIdx]?.text?.trim();
+                if (compVal && relVal)
+                    out[compVal.toUpperCase()] = relVal;
+            }
+            if (Object.keys(out).length > 0)
+                return out;
+        }
+    }
+    return {};
+}
+/**
+ * Derive `{ platform, release, abapVersion }` from the raw CVERS rows.
+ * Pure function — exported for unit tests without going through
+ * caching or live query.
+ */
+export function classify(alias, components) {
+    const sapBasis = components['SAP_BASIS'];
+    const s4Core = components['S4CORE'] || components['S4FND'];
+    const platform = s4Core ? 'S/4HANA'
+        : sapBasis ? (parseInt(sapBasis, 10) >= 750 ? 'NetWeaver' : 'ECC')
+            : 'unknown';
+    const release = humanReadableRelease(platform, sapBasis, s4Core);
+    const abapVersion = abapVersionFor(sapBasis);
+    return {
+        alias,
+        platform,
+        release,
+        abapVersion,
+        // Public-cloud detection isn't reliable from CVERS alone; CSPeach
+        // running against a system over ADT typically rules out Public Cloud
+        // (which restricts ADT access). Mark conservatively.
+        deployment: 'on-prem-or-private-cloud',
+        components,
+        queriedAt: new Date().toISOString(),
+    };
+}
+/**
+ * S4CORE → S/4HANA edition mapping. Source: SAP release roadmap.
+ * SAP_BASIS alone is ambiguous (e.g. 757 covers both S/4 2021 and 2022),
+ * so we anchor on S4CORE when present and fall back to SAP_BASIS only
+ * for ECC/NW systems.
+ */
+function humanReadableRelease(platform, sapBasis, s4Core) {
+    if (platform === 'S/4HANA' && s4Core) {
+        const map = {
+            '100': 'S/4HANA 1503',
+            '101': 'S/4HANA 1511',
+            '102': 'S/4HANA 1610',
+            '103': 'S/4HANA 1709',
+            '104': 'S/4HANA 1809',
+            '105': 'S/4HANA 1909',
+            '106': 'S/4HANA 2020',
+            '107': 'S/4HANA 2022',
+            '108': 'S/4HANA 2023',
+            '109': 'S/4HANA 2023 FPS01',
+            '110': 'S/4HANA 2025',
+        };
+        return map[s4Core] ?? `S/4HANA (S4CORE ${s4Core})`;
+    }
+    if (platform === 'NetWeaver' && sapBasis) {
+        return `NetWeaver / ECC (SAP_BASIS ${sapBasis})`;
+    }
+    if (platform === 'ECC' && sapBasis) {
+        const map = {
+            '700': 'ECC 6.0',
+            '701': 'ECC 6.0 EHP1',
+            '702': 'ECC 6.0 EHP2',
+            '703': 'ECC 6.0 EHP3',
+            '704': 'ECC 6.0 EHP4',
+            '730': 'ECC 6.0 EHP5/6',
+            '731': 'ECC 6.0 EHP6',
+            '740': 'ECC 6.0 EHP7',
+        };
+        return map[sapBasis] ?? `ECC 6.0 (SAP_BASIS ${sapBasis})`;
+    }
+    return 'unknown';
+}
+/**
+ * SAP_BASIS to ABAP language version. Skills use this to know which
+ * ABAP syntax is available — `7.40` for inline data, `7.50` for FILTER,
+ * `7.55+` for full S/4 RAP, etc.
+ */
+function abapVersionFor(sapBasis) {
+    if (!sapBasis)
+        return 'unknown';
+    // SAP_BASIS release directly maps: 754 = 7.54, 757 = 7.57.
+    const n = parseInt(sapBasis, 10);
+    if (Number.isNaN(n))
+        return 'unknown';
+    // Modern releases — return as N.NN (e.g. 757 → 7.57).
+    if (n >= 740 && n < 800)
+        return `7.${n - 700}`;
+    return sapBasis;
+}
+// ── Disk cache ─────────────────────────────────────────────────────────────
+function cacheDir() {
+    return join(cspeachRoot(), 'sap-cache');
+}
+function cacheFile(alias) {
+    // Sanitise alias to a safe filename. Aliases are short identifiers
+    // ([A-Za-z0-9_-]) by convention but we strip anything else defensively.
+    const safe = alias.replace(/[^A-Za-z0-9._-]/g, '_');
+    return join(cacheDir(), `${safe}.json`);
+}
+function readDiskCache(alias) {
+    try {
+        const path = cacheFile(alias);
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (!raw.queriedAt)
+            return null;
+        const age = Date.now() - new Date(raw.queriedAt).getTime();
+        if (age > CACHE_TTL_MS)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function writeDiskCache(alias, info) {
+    try {
+        const dir = cacheDir();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(cacheFile(alias), JSON.stringify(info, null, 2), 'utf8');
+    }
+    catch {
+        // best-effort — we still return the in-memory result
+    }
+}
+/**
+ * Render the SAP system block for `<session_context>`. Returns an
+ * empty string when info is null so the caller can concatenate
+ * unconditionally without conditional logic at every call site.
+ */
+export function renderSapSystemBlock(info) {
+    if (!info)
+        return '';
+    const attrs = [
+        `alias="${escapeAttr(info.alias)}"`,
+        `platform="${escapeAttr(info.platform)}"`,
+        `release="${escapeAttr(info.release)}"`,
+        `abap_version="${escapeAttr(info.abapVersion)}"`,
+        `deployment="${escapeAttr(info.deployment)}"`,
+    ].join(' ');
+    return `<sap_system ${attrs} />`;
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/dist/session/awaiting-answer.js

@@ -0,0 +1,73 @@
+/**
+ * Detect whether the last assistant message in a session contains a
+ * "question marker" — signalling that the skill is waiting for the user's
+ * answer. When true, the next REPL turn should route to the same skill
+ * without re-classifying.
+ *
+ * Markers (any one triggers true):
+ *   - The literal phrase "Reply with your answer" — mandated outro of the
+ *     v0.3.1 question-widget pattern in skill prompts.
+ *   - The `<!-- widget-real -->` sentinel — raw widget fence emission, in
+ *     case the skill emitted the fence before our prose normaliser.
+ *
+ * Pure function — no I/O, no side effects. Takes an assistant-message
+ * content payload (string OR Anthropic-style array of content blocks) and
+ * returns boolean.
+ */
+// Markers we accept as a "skill is asking a question, expect an answer next"
+// signal. Kept deliberately broad because LLMs paraphrase the canonical
+// instruction ("Reply with your answer and I'll ask the next one") into
+// variants like "Reply with your choice" / "Reply with your pick".
+//   - PHRASE: "Reply with your <noun>" in any casing
+//   - PICK_HEADER: "Pick one:" or "Pick any" on a line (our question-widget
+//     normaliser emits these; and skill prompts tend to use them verbatim)
+//   - SENTINEL: the raw cspeach-widget:question sentinel, in case a fence
+//     did emit but the prose normaliser didn't fully consume it
+const MARKER_PHRASE = /Reply with your \w+/i;
+const MARKER_PICK_HEADER = /^\s*Pick (one|any)[\s:(]/im;
+const MARKER_SENTINEL = /<!-- widget-real -->/;
+// Fallback: if the prose normaliser failed and raw JSON leaked into the
+// rendered output, the `"kind":"choice|multi|text"` fragment is still a
+// strong signal that a question widget was intended. Catches the streaming
+// edge case where the normaliser couldn't complete the parse.
+const MARKER_JSON_KIND = /"kind"\s*:\s*"(choice|multi|text)"/;
+export function messageContainsQuestionMarker(content) {
+    const text = extractText(content);
+    if (!text)
+        return false;
+    return (MARKER_PHRASE.test(text) ||
+        MARKER_PICK_HEADER.test(text) ||
+        MARKER_SENTINEL.test(text) ||
+        MARKER_JSON_KIND.test(text));
+}
+/** Extract plain text from an assistant-message content payload. */
+function extractText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    // Anthropic content blocks: [{type:'text', text:'...'}, {type:'tool_use',...}, ...]
+    return content
+        .map((block) => {
+        if (block && typeof block === 'object' && 'type' in block) {
+            const b = block;
+            if (b.type === 'text' && typeof b.text === 'string')
+                return b.text;
+        }
+        return '';
+    })
+        .join('\n');
+}
+/**
+ * Scan the session's messages from the end backward and return whether the
+ * most recent assistant message (if any) contains a question marker.
+ * Returns false if no assistant message has been recorded yet.
+ */
+export function lastAssistantIsAwaitingAnswer(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role === 'assistant')
+            return messageContainsQuestionMarker(m.content);
+    }
+    return false;
+}

package/dist/session/gc.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { sessionsDir, pinnedSessionsDir, snapshotsDir } from '../config/paths.js';
+export async function runGcOnStartup() {
+    const now = Date.now();
+    const threshold = now - 30 * 24 * 60 * 60 * 1000; // 30 days
+    const sessionsRemoved = await gcDir(sessionsDir(), threshold, [pinnedSessionsDir()]);
+    const snapshotsRemoved = await gcDir(snapshotsDir(), threshold);
+    return { sessions: sessionsRemoved, snapshots: snapshotsRemoved };
+}
+async function gcDir(dir, thresholdMs, excludeDirs = []) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    let removed = 0;
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() && excludeDirs.includes(full))
+            continue;
+        try {
+            const stat = await fs.stat(full);
+            if (stat.mtimeMs < thresholdMs) {
+                await fs.rm(full, { recursive: entry.isDirectory(), force: true });
+                removed++;
+            }
+        }
+        catch { /* ignore — file may have been removed concurrently */ }
+    }
+    return removed;
+}

package/dist/session/pending.js

@@ -0,0 +1,37 @@
+import { saveSession } from './store.js';
+export async function appendPending(session, entry) {
+    session.toolCalls.push({ ...entry, completed: false });
+    await saveSession(session);
+}
+export async function finalizeToolCall(session, toolUseId, result, isError, durationMs) {
+    const idx = session.toolCalls.findIndex((c) => c.tool_use_id === toolUseId && !c.completed);
+    if (idx < 0) {
+        session.toolCalls.push({
+            tool_use_id: toolUseId,
+            tool: 'unknown',
+            args: null,
+            result,
+            is_error: isError,
+            duration_ms: durationMs,
+            completed_at: new Date().toISOString(),
+            completed: true,
+        });
+    }
+    else {
+        const pending = session.toolCalls[idx];
+        session.toolCalls[idx] = {
+            tool_use_id: pending.tool_use_id,
+            tool: pending.tool,
+            args: pending.args,
+            result,
+            is_error: isError,
+            duration_ms: durationMs,
+            completed_at: new Date().toISOString(),
+            completed: true,
+        };
+    }
+    await saveSession(session);
+}
+export function hasUnfinishedMutations(session) {
+    return session.toolCalls.some((c) => !c.completed);
+}