ente-cli 0.4.78 → 0.4.79

package/README.md

@@ -447,3 +447,17 @@ Use the external operator command. Whole-history panel sharing does not grant
 access to diagnostics, and diagnostic reads do not append to chat history.
 
 Identify your connection with `ente agent set-icon fish` (or `--reset`), then find its icon in `/agents`. Requires write scope and always targets your own bound agent.
+
+
+Raw evidence retrieval supports `ente query "question" --mode hybrid --json` and
+`--mode semantic`. Omitted/lexical mode keeps deterministic retrieval without
+provider calls. Hybrid preserves typed structured evidence; semantic is indexed
+own Personal activity passages only. Both return evidence without an answer.
+Inspect execution, coverage, fallback and truncation metadata; vector ranks are
+not answer confidence. Semantic availability requires the separate default-off
+Personal retrieval pilot, not an Ask synthesis slot. See `ente guide activity` and
+the shipped skill for scope and citation details.
+
+Explicit vector modes report the selected provider, model, region, embedding identity and generation in `retrieval.vector`. Optional OpenAI embeddings use `text-embedding-3-small` at 512 dimensions. A provider/model/region change requires renewed account consent and a new empty generation; it does not select history or future activities. No automatic provider fallback runs. Omitted/lexical query remains zero-egress.
+
+Hybrid ordering uses RRF plus semantic branch coverage. Returned rank is authoritative; scores are not calibrated confidence or a pure sort contract.

package/dist/SKILL.md

@@ -150,6 +150,9 @@ ente auth logout
 ente auth profiles
 
 # Search & ask
+# Ask keeps scoped evidence on synthesis failure; check synthesisStatus.
+# Optional sourceHash/sourceFingerprint/passage metadata binds citations to a source version.
+# query remains deterministic and never starts embedding/indexing. See guide ask-the-graph.
 ente search "Alice" [--type person] [--json]
 ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # AI answer + citations
 ente query "QM system export" [--space <name>] [--entity <name>] [--since <epoch-ms>] [--until <epoch-ms>] [--limit 12] [--verbose] [--json]         # evidence only, no AI
@@ -624,3 +627,32 @@ icon, then find it in `/agents`. Use `ente agent set-icon --reset` to restore th
 default. Run `ente agent set-icon --help` for curated IDs. Write scope is required;
 there is no agent-ID option. Connections shows last recorded external access,
 which can have historical gaps and excludes hosted/scheduled activity.
+
+
+### Raw retrieval modes
+
+`ente query "question" --json` keeps deterministic entity, activity title/body,
+task and relationship retrieval without provider calls. `--mode lexical` is the
+same default. Keep `ente search` for fuzzy entity lookup and `ente activity search`
+for ordinary title/body keyword search.
+
+Use `ente query "question" --mode hybrid --space Personal --json` only when semantic
+retrieval is wanted and consented. Hybrid retains typed deterministic structured
+results and combines lexical/vector activity passages. `--mode semantic` returns
+vector activity passages only, for inspection/comparison. Initial vectors cover
+only the caller's own Personal notes, conversations, meetings and calls. Related
+entity IDs/names are authorized context, not semantic entity matches.
+
+Neither mode generates an answer or needs an Ask synthesis slot. Read
+`retrieval.requestedMode`, `usedMode`, `status`, `vector`, `coverage`, `counts` and
+`truncation`. Hybrid may explicitly fall back to lexical. Unavailable semantic
+returns no evidence and exits1. Counts describe bounded candidates, not complete
+account totals; original lexical truncation flags still apply. Vector ranks are
+not answer confidence. Use source hashes, passage offsets and sourceUrl to check
+an activity revision before citing it. Indexing remains default off; future
+activity opt-in and reviewed historical selection are independent. Own-model
+accounts do not send data to the hosted embedding pilot.
+
+Explicit vector modes report the selected provider, model, region, embedding identity and generation in `retrieval.vector`. Optional OpenAI embeddings use `text-embedding-3-small` at 512 dimensions. A provider/model/region change requires renewed account consent and a new empty generation; it does not select history or future activities. No automatic provider fallback runs. Omitted/lexical query remains zero-egress.
+
+Hybrid ranking uses RRF plus early semantic branch coverage. Use returned `rank` for order; numeric scores are neither a pure sort contract nor calibrated confidence.

package/dist/cli.mjs

@@ -3800,7 +3800,7 @@ async function runCli(cli2, argv, context) {
 }
 
 // ente/version.ts
-var VERSION = "0.4.78";
+var VERSION = "0.4.79";
 
 // ente/branding.ts
 var NPM_REGISTRY = "https://registry.npmjs.org";
@@ -14604,7 +14604,8 @@ function parseIntFlag(flag, raw, min) {
 // ente/commands/ask.ts
 var askActionRun = makeFunctionReference("askAction:run");
 function formatCitation(c) {
-  return `[${c.evidenceId ?? ""}] ${c.kind ?? ""}: ${c.title ?? ""}`.trim();
+  const passage = c.passage ? ` (chars ${c.passage.start}\u2013${c.passage.end}; ${c.passage.sourceHash.slice(0, 12)})` : "";
+  return `[${c.evidenceId ?? ""}] ${c.kind ?? ""}: ${c.title ?? ""}${passage}`.trim();
 }
 function formatAskResult(data, includeEvidence) {
   const lines = [data.answer ?? ""];
@@ -14627,6 +14628,7 @@ function formatAskResult(data, includeEvidence) {
       for (const item of evidence) {
         lines.push(`- [${item.id ?? ""}] ${item.kind ?? ""}: ${item.title ?? ""}`);
         if (item.text) lines.push(`  ${item.text}`);
+        if (item.metadataText) lines.push(`  ${item.metadataText}`);
       }
     }
   }
@@ -14654,8 +14656,16 @@ var AskCmd = class extends ProfileCommand {
 };
 var ASK_COMMANDS = [AskCmd];
 
+// ente/queryModes.ts
+var QUERY_MODES = ["lexical", "semantic", "hybrid"];
+
 // ente/commands/query.ts
 var askQuery = makeFunctionReference("ask:query");
+var rawQuery = makeFunctionReference("retrieval/raw:run");
+async function retrieveEvidenceC(caller, body, mode) {
+  if (mode !== void 0 && !QUERY_MODES.includes(mode)) throw new Error("--mode must be lexical, hybrid or semantic");
+  return mode === "hybrid" || mode === "semantic" ? caller.action(rawQuery, { ...body, mode }) : caller.query(askQuery, body);
+}
 function formatEvidence(item, verbose) {
   const lines = [`[${item.id ?? ""}] ${item.kind ?? ""}: ${item.title ?? ""}`];
   const details = [];
@@ -14670,8 +14680,12 @@ function formatEvidence(item, verbose) {
 }
 function formatQueryResult(data, verbose) {
   const evidence = data.evidence ?? [];
-  if (evidence.length === 0) return "No evidence found.";
   const lines = [];
+  if (data.retrieval && data.retrieval.requestedMode !== "lexical") {
+    const retrieval = data.retrieval;
+    lines.push(`Retrieval: ${retrieval.requestedMode} \u2192 ${retrieval.usedMode}; vectors ${retrieval.vector.searchExecuted ? retrieval.vector.provider : "not executed"}${retrieval.fallbackReason ? ` (${retrieval.fallbackReason})` : ""}`);
+  }
+  if (!evidence.length) lines.push("No evidence found.");
   for (const item of evidence) lines.push(...formatEvidence(item, verbose));
   const warnings = data.warnings ?? [];
   if (warnings.length) {
@@ -14682,10 +14696,11 @@ function formatQueryResult(data, verbose) {
 var QueryCmd = class extends ProfileCommand {
   static paths = [["query"]];
   static usage = Command.Usage({
-    category: "Ask",
-    description: "Run ente's deterministic evidence retrieval without AI synthesis"
+    category: "Retrieval",
+    description: "Retrieve raw evidence; default lexical, optional hybrid or semantic activity passages"
   });
   question = options_exports.String();
+  mode = options_exports.String("--mode", { description: "lexical (default, no provider calls), hybrid, or semantic (own Personal activity passages only)" });
   space = options_exports.String("--space", { description: "Restrict evidence to a space (name or ID)" });
   entity = options_exports.String("--entity", { description: "Use an entity (name or ID) as the main graph anchor" });
   limit = options_exports.String("--limit", { description: "Maximum evidence items to return" });
@@ -14693,10 +14708,12 @@ var QueryCmd = class extends ProfileCommand {
   until = options_exports.String("--until", { description: "Only include activity evidence before this epoch ms" });
   verbose = options_exports.Boolean("--verbose,-v", false, { description: "Print full evidence snippets" });
   async run() {
+    if (this.mode !== void 0 && !QUERY_MODES.includes(this.mode)) throw new Error("--mode must be lexical, hybrid or semantic");
     const caller = await resolveCaller();
     const body = await buildEvidenceBodyC(caller, this);
-    const res = await caller.query(askQuery, body);
+    const res = await retrieveEvidenceC(caller, body, this.mode);
     this.emitText({ data: res }, () => formatQueryResult(res, this.verbose));
+    if (res.retrieval?.status === "unavailable") return 1;
   }
 };
 var QUERY_COMMANDS = [QueryCmd];
@@ -16108,7 +16125,7 @@ ancestors redundantly.
 Commands:
   ente search <query>          Fuzzy search entities
   ente ask <question>          Natural-language answer (AI synthesis + citations)
-  ente query <question>        Deterministic evidence retrieval (no synthesis)
+  ente query <question>        Raw evidence; default lexical, optional --mode hybrid|semantic
   ente entity create|get|update|duplicate|rename|archive|restore|pin|unpin
   ente entity list [--archived]
   ente pins list <entity>      List pins for an entity
@@ -16265,7 +16282,7 @@ Archiving (trash):
     content: `Resolve entities globally first: ente search "Apollo" --json
 Use an explicit space when the task specifies one:
   ente query "launch decisions" --space "Work" --entity "Apollo" --since 1791763200000 --until 1792368000000 --limit 8 --json
-Time filters apply to activity evidence; query uses no model.
+Time filters apply to activity evidence. Default/lexical query uses no provider. Explicit hybrid uses the separately consented embedding provider; semantic returns indexed own Personal activity passages only. Neither mode generates an answer. Inspect requested/used mode, vector execution, coverage, truncation and fallback in --json output. Vector metadata also names provider/model/region and index generation. Optional OpenAI text-embedding-3-small uses 512 dimensions. A provider/model/region change needs renewed consent and an empty generation; future/history must be selected again. No automatic provider fallback runs. Hybrid uses RRF plus semantic branch coverage: rank is authoritative, not a pure score sort or calibrated confidence.
 
 Read one compact entity-history page:
   ente activity list --entity <id> --after 1791763200000 --min-count 0 --limit 10 --compact --json