@agenticmail/core 0.9.37 → 0.9.38

package/dist/{chunk-J6JINNJ3.js → chunk-FYULLCZX.js}

@@ -575,8 +575,8 @@ function validateSkill(s) {
   if (typeof sk.contributed_by !== "string") errs.push({ path: "contributed_by", message: "must be a string" });
   return errs;
 }
-function summarize(s) {
-  return {
+function summarize(s, score) {
+  const out = {
     id: s.id,
     name: s.name,
     category: s.category,
@@ -584,8 +584,12 @@ function summarize(s) {
     description: s.description,
     version: s.version,
     disclaimer_required: !!s.disclaimer,
-    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes
+    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes,
+    when_to_use: s.context.when_to_use,
+    first_principle: s.principles && s.principles.length > 0 ? s.principles[0] : ""
   };
+  if (score !== void 0) out.score = score;
+  return out;
 }
 function listSkills(opts = {}) {
   const all = Array.from(ensureLoaded().byId.values());
@@ -606,17 +610,17 @@ function searchSkills(query, limit = 20) {
     const fallback = [];
     for (const s of byId.values()) {
       if (s.id.toLowerCase().includes(qLow) || s.name.toLowerCase().includes(qLow) || s.tags.some((t) => t.toLowerCase().includes(qLow))) {
-        fallback.push(summarize(s));
+        fallback.push(summarize(s, 0.1));
         if (fallback.length >= limit) break;
       }
     }
     return fallback;
   }
   const out = [];
-  for (const { id } of ranked) {
+  for (const { id, score } of ranked) {
     const skill = byId.get(id);
     if (!skill) continue;
-    out.push(summarize(skill));
+    out.push(summarize(skill, score));
     if (out.length >= limit) break;
   }
   return out;

package/dist/index.cjs

@@ -1280,8 +1280,8 @@ function validateSkill(s) {
   if (typeof sk.contributed_by !== "string") errs.push({ path: "contributed_by", message: "must be a string" });
   return errs;
 }
-function summarize(s) {
-  return {
+function summarize(s, score) {
+  const out = {
     id: s.id,
     name: s.name,
     category: s.category,
@@ -1289,8 +1289,12 @@ function summarize(s) {
     description: s.description,
     version: s.version,
     disclaimer_required: !!s.disclaimer,
-    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes
+    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes,
+    when_to_use: s.context.when_to_use,
+    first_principle: s.principles && s.principles.length > 0 ? s.principles[0] : ""
   };
+  if (score !== void 0) out.score = score;
+  return out;
 }
 function listSkills(opts = {}) {
   const all = Array.from(ensureLoaded().byId.values());
@@ -1311,17 +1315,17 @@ function searchSkills(query, limit = 20) {
     const fallback = [];
     for (const s of byId.values()) {
       if (s.id.toLowerCase().includes(qLow) || s.name.toLowerCase().includes(qLow) || s.tags.some((t) => t.toLowerCase().includes(qLow))) {
-        fallback.push(summarize(s));
+        fallback.push(summarize(s, 0.1));
         if (fallback.length >= limit) break;
       }
     }
     return fallback;
   }
   const out = [];
-  for (const { id } of ranked) {
+  for (const { id, score } of ranked) {
     const skill = byId.get(id);
     if (!skill) continue;
-    out.push(summarize(skill));
+    out.push(summarize(skill, score));
     if (out.length >= limit) break;
   }
   return out;
@@ -8678,6 +8682,73 @@ var PhoneManager = class {
     }]);
     return { mission: updated, query: answered, alreadyAnswered: false };
   }
+  /**
+   * v0.9.92 — auto-close stale operator queries.
+   *
+   * An operator query is "stale" when:
+   *   - it's unanswered, AND
+   *   - either (a) the mission is no longer live (status in
+   *     {completed, failed, cancelled}), OR (b) the query is older
+   *     than `maxAgeSeconds`.
+   *
+   * The sweeper marks each stale query as answered with a synthetic
+   * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+   * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+   * the bridge's "you have N open questions" hint to the operator,
+   * and (c) leaves a permanent audit trail of WHY the query was
+   * closed.
+   *
+   * Returns the count of queries closed + a per-mission breakdown
+   * for logging.
+   */
+  sweepStaleOperatorQueries(opts = {}) {
+    const maxAgeMs = (opts.maxAgeSeconds ?? 3600) * 1e3;
+    const nowMs = opts.nowMs ?? Date.now();
+    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    const rows = this.db.prepare(
+      `SELECT * FROM phone_missions WHERE metadata_json LIKE '%"operatorQueries"%'`
+    ).all();
+    const breakdown = [];
+    let totalClosed = 0;
+    let missionsTouched = 0;
+    for (const row of rows) {
+      const mission = rowToMission(row);
+      const queries = readOperatorQueries(mission);
+      const open = queries.filter((q) => !q.answer);
+      if (open.length === 0) continue;
+      const reason = TERMINAL.has(mission.status) ? "mission-terminal" : null;
+      const closedAt = new Date(nowMs).toISOString();
+      const nextQueries = queries.map((q) => {
+        if (q.answer) return q;
+        const askedAtMs = Date.parse(q.askedAt);
+        const tooOld = Number.isFinite(askedAtMs) && nowMs - askedAtMs >= maxAgeMs;
+        const queryReason = reason ?? (tooOld ? "age" : null);
+        if (!queryReason) return q;
+        return {
+          ...q,
+          answer: queryReason === "mission-terminal" ? `[auto-closed: mission ended (${mission.status}) before this question was answered]` : `[auto-closed: question went unanswered for over ${Math.round(maxAgeMs / 6e4)} minutes]`,
+          answeredAt: closedAt,
+          answeredVia: "auto-sweeper"
+        };
+      });
+      const closedHere = nextQueries.filter(
+        (q, i) => q.answer && !queries[i].answer && q.answeredVia === "auto-sweeper"
+      ).length;
+      if (closedHere === 0) continue;
+      this.updateMissionStatus(mission.id, mission.status, {
+        operatorQueries: nextQueries
+      }, [{
+        at: closedAt,
+        source: "system",
+        text: `Auto-closed ${closedHere} stale operator query(ies): ${reason ?? "aged out"}.`,
+        metadata: { closedCount: closedHere, reason: reason ?? "age" }
+      }]);
+      totalClosed += closedHere;
+      missionsTouched += 1;
+      breakdown.push({ missionId: mission.id, closed: closedHere, reason: reason ?? "age" });
+    }
+    return { closed: totalClosed, missionsTouched, breakdown };
+  }
   // ─── Callback on disconnect (plan §7) ─────────────────
   /**
    * Flag a mission for callback-on-disconnect: the call dropped while
@@ -10690,7 +10761,7 @@ var SEARCH_EMAIL_TOOL = {
 var SEARCH_SKILLS_TOOL = {
   type: "function",
   name: "search_skills",
-  description: "Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns ranked summaries \u2014 pick the best match and pass its id to load_skill. Fast.",
+  description: 'Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns up to 5 ranked matches, each with: id, name, BM25 score, when_to_use (the specific situation the skill is for), first_principle (the playbook\'s strategic frame), and a `recommendation` field. If `recommendation` says LOAD IT NOW or the top score > 0.3, immediately call load_skill with the top id \u2014 do not deliberate. If scores are weak (< 0.15), re-search with a different phrasing instead of loading a poor match. The model that judges "is this the right skill" is YOU \u2014 but the recommendation field will tell you what the right move usually is.',
   parameters: {
     type: "object",
     properties: {

package/dist/index.d.cts

@@ -4109,6 +4109,37 @@ declare class PhoneManager {
         query: PhoneOperatorQuery;
         alreadyAnswered: boolean;
     } | null;
+    /**
+     * v0.9.92 — auto-close stale operator queries.
+     *
+     * An operator query is "stale" when:
+     *   - it's unanswered, AND
+     *   - either (a) the mission is no longer live (status in
+     *     {completed, failed, cancelled}), OR (b) the query is older
+     *     than `maxAgeSeconds`.
+     *
+     * The sweeper marks each stale query as answered with a synthetic
+     * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+     * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+     * the bridge's "you have N open questions" hint to the operator,
+     * and (c) leaves a permanent audit trail of WHY the query was
+     * closed.
+     *
+     * Returns the count of queries closed + a per-mission breakdown
+     * for logging.
+     */
+    sweepStaleOperatorQueries(opts?: {
+        maxAgeSeconds?: number;
+        nowMs?: number;
+    }): {
+        closed: number;
+        missionsTouched: number;
+        breakdown: Array<{
+            missionId: string;
+            closed: number;
+            reason: 'mission-terminal' | 'age';
+        }>;
+    };
     /**
      * Flag a mission for callback-on-disconnect: the call dropped while
      * an operator query was still unanswered, so once the operator
@@ -6010,6 +6041,32 @@ interface SkillSummary {
     version: string;
     disclaimer_required: boolean;
     estimated_call_duration_minutes: number;
+    /**
+     * v0.9.92 — surfaced from `context.when_to_use`. This is the field
+     * that actually tells the model "should I load this for the
+     * current situation?" — far more diagnostic than the generic
+     * `description` (which is just a one-liner for browsing). The
+     * realtime `search_skills` tool result includes it so the model
+     * can decide WITHOUT a second `load_skill` round-trip on a wrong
+     * guess.
+     */
+    when_to_use: string;
+    /**
+     * v0.9.92 — the skill's first principle, surfaced for the same
+     * "is this the right playbook" decision. Principles are the
+     * strategic frame ("be calm and friendly — the rep didn't choose
+     * your bill"); seeing one principle tells the model whether the
+     * skill's POSTURE matches the situation, not just its topic.
+     */
+    first_principle: string;
+    /**
+     * v0.9.92 — BM25F search score from the rank. Only present on
+     * results from `searchSkills`; absent on `listSkills` output
+     * (where the ordering is by id, not by relevance). Lets the
+     * model thresholds "definitely load" vs. "re-search with a
+     * better query".
+     */
+    score?: number;
 }
 /** Failed-validation result from the schema validator. */
 interface SkillValidationError {

package/dist/index.d.ts

@@ -4109,6 +4109,37 @@ declare class PhoneManager {
         query: PhoneOperatorQuery;
         alreadyAnswered: boolean;
     } | null;
+    /**
+     * v0.9.92 — auto-close stale operator queries.
+     *
+     * An operator query is "stale" when:
+     *   - it's unanswered, AND
+     *   - either (a) the mission is no longer live (status in
+     *     {completed, failed, cancelled}), OR (b) the query is older
+     *     than `maxAgeSeconds`.
+     *
+     * The sweeper marks each stale query as answered with a synthetic
+     * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+     * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+     * the bridge's "you have N open questions" hint to the operator,
+     * and (c) leaves a permanent audit trail of WHY the query was
+     * closed.
+     *
+     * Returns the count of queries closed + a per-mission breakdown
+     * for logging.
+     */
+    sweepStaleOperatorQueries(opts?: {
+        maxAgeSeconds?: number;
+        nowMs?: number;
+    }): {
+        closed: number;
+        missionsTouched: number;
+        breakdown: Array<{
+            missionId: string;
+            closed: number;
+            reason: 'mission-terminal' | 'age';
+        }>;
+    };
     /**
      * Flag a mission for callback-on-disconnect: the call dropped while
      * an operator query was still unanswered, so once the operator
@@ -6010,6 +6041,32 @@ interface SkillSummary {
     version: string;
     disclaimer_required: boolean;
     estimated_call_duration_minutes: number;
+    /**
+     * v0.9.92 — surfaced from `context.when_to_use`. This is the field
+     * that actually tells the model "should I load this for the
+     * current situation?" — far more diagnostic than the generic
+     * `description` (which is just a one-liner for browsing). The
+     * realtime `search_skills` tool result includes it so the model
+     * can decide WITHOUT a second `load_skill` round-trip on a wrong
+     * guess.
+     */
+    when_to_use: string;
+    /**
+     * v0.9.92 — the skill's first principle, surfaced for the same
+     * "is this the right playbook" decision. Principles are the
+     * strategic frame ("be calm and friendly — the rep didn't choose
+     * your bill"); seeing one principle tells the model whether the
+     * skill's POSTURE matches the situation, not just its topic.
+     */
+    first_principle: string;
+    /**
+     * v0.9.92 — BM25F search score from the rank. Only present on
+     * results from `searchSkills`; absent on `listSkills` output
+     * (where the ordering is by id, not by relevance). Lets the
+     * model thresholds "definitely load" vs. "re-search with a
+     * better query".
+     */
+    score?: number;
 }
 /** Failed-validation result from the schema validator. */
 interface SkillValidationError {

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   tokenize,
   userSkillsDir,
   validateSkill
-} from "./chunk-J6JINNJ3.js";
+} from "./chunk-FYULLCZX.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";
@@ -7009,6 +7009,73 @@ var PhoneManager = class {
     }]);
     return { mission: updated, query: answered, alreadyAnswered: false };
   }
+  /**
+   * v0.9.92 — auto-close stale operator queries.
+   *
+   * An operator query is "stale" when:
+   *   - it's unanswered, AND
+   *   - either (a) the mission is no longer live (status in
+   *     {completed, failed, cancelled}), OR (b) the query is older
+   *     than `maxAgeSeconds`.
+   *
+   * The sweeper marks each stale query as answered with a synthetic
+   * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+   * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+   * the bridge's "you have N open questions" hint to the operator,
+   * and (c) leaves a permanent audit trail of WHY the query was
+   * closed.
+   *
+   * Returns the count of queries closed + a per-mission breakdown
+   * for logging.
+   */
+  sweepStaleOperatorQueries(opts = {}) {
+    const maxAgeMs = (opts.maxAgeSeconds ?? 3600) * 1e3;
+    const nowMs = opts.nowMs ?? Date.now();
+    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    const rows = this.db.prepare(
+      `SELECT * FROM phone_missions WHERE metadata_json LIKE '%"operatorQueries"%'`
+    ).all();
+    const breakdown = [];
+    let totalClosed = 0;
+    let missionsTouched = 0;
+    for (const row of rows) {
+      const mission = rowToMission(row);
+      const queries = readOperatorQueries(mission);
+      const open = queries.filter((q) => !q.answer);
+      if (open.length === 0) continue;
+      const reason = TERMINAL.has(mission.status) ? "mission-terminal" : null;
+      const closedAt = new Date(nowMs).toISOString();
+      const nextQueries = queries.map((q) => {
+        if (q.answer) return q;
+        const askedAtMs = Date.parse(q.askedAt);
+        const tooOld = Number.isFinite(askedAtMs) && nowMs - askedAtMs >= maxAgeMs;
+        const queryReason = reason ?? (tooOld ? "age" : null);
+        if (!queryReason) return q;
+        return {
+          ...q,
+          answer: queryReason === "mission-terminal" ? `[auto-closed: mission ended (${mission.status}) before this question was answered]` : `[auto-closed: question went unanswered for over ${Math.round(maxAgeMs / 6e4)} minutes]`,
+          answeredAt: closedAt,
+          answeredVia: "auto-sweeper"
+        };
+      });
+      const closedHere = nextQueries.filter(
+        (q, i) => q.answer && !queries[i].answer && q.answeredVia === "auto-sweeper"
+      ).length;
+      if (closedHere === 0) continue;
+      this.updateMissionStatus(mission.id, mission.status, {
+        operatorQueries: nextQueries
+      }, [{
+        at: closedAt,
+        source: "system",
+        text: `Auto-closed ${closedHere} stale operator query(ies): ${reason ?? "aged out"}.`,
+        metadata: { closedCount: closedHere, reason: reason ?? "age" }
+      }]);
+      totalClosed += closedHere;
+      missionsTouched += 1;
+      breakdown.push({ missionId: mission.id, closed: closedHere, reason: reason ?? "age" });
+    }
+    return { closed: totalClosed, missionsTouched, breakdown };
+  }
   // ─── Callback on disconnect (plan §7) ─────────────────
   /**
    * Flag a mission for callback-on-disconnect: the call dropped while
@@ -9021,7 +9088,7 @@ var SEARCH_EMAIL_TOOL = {
 var SEARCH_SKILLS_TOOL = {
   type: "function",
   name: "search_skills",
-  description: "Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns ranked summaries \u2014 pick the best match and pass its id to load_skill. Fast.",
+  description: 'Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns up to 5 ranked matches, each with: id, name, BM25 score, when_to_use (the specific situation the skill is for), first_principle (the playbook\'s strategic frame), and a `recommendation` field. If `recommendation` says LOAD IT NOW or the top score > 0.3, immediately call load_skill with the top id \u2014 do not deliberate. If scores are weak (< 0.15), re-search with a different phrasing instead of loading a poor match. The model that judges "is this the right skill" is YOU \u2014 but the recommendation field will tell you what the right move usually is.',
   parameters: {
     type: "object",
     properties: {
@@ -9676,7 +9743,7 @@ var RealtimeVoiceBridge = class {
     let loadSkill2;
     let renderSkillAsPrompt2;
     try {
-      ({ loadSkill: loadSkill2, renderSkillAsPrompt: renderSkillAsPrompt2 } = await import("./skills-RE3S767B.js"));
+      ({ loadSkill: loadSkill2, renderSkillAsPrompt: renderSkillAsPrompt2 } = await import("./skills-DZVDIMTD.js"));
     } catch (err) {
       return { ok: false, message: `Skill registry unavailable: ${errorText(err)}` };
     }

package/dist/{skills-RE3S767B.js → skills-DZVDIMTD.js}

@@ -8,7 +8,7 @@ import {
   skillFilename,
   userSkillsDir,
   validateSkill
-} from "./chunk-J6JINNJ3.js";
+} from "./chunk-FYULLCZX.js";
 import "./chunk-3RG5ZIWI.js";
 export {
   invalidateSkillCache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.9.37",
+  "version": "0.9.38",
   "description": "Core SDK for AgenticMail — email, SMS, and phone call-control for AI agents",
   "type": "module",
   "main": "dist/index.js",