ente-cli 0.4.77 → 0.4.79

package/README.md

@@ -107,8 +107,9 @@ ente entity rename "Lorey Georg" "Georg Lorey"
 ente task list --due today
 ente activity create --type note --title "Meeting notes" --entity "Alice" --space "Personal"
 ente activity get <activityId> --json # includes the body, nested agenda, messages/replies, entities, and attachments
-ente agenda create-point --meeting <meetingActivityId> --title "Decisions" --content="- Ship the smaller scope"
+ente agenda create-point --activity <activityId> --title "Decisions" --content="- Ship the smaller scope"
 ente agenda link-task --point <agendaPointId> --task "#12"
+# Agendas work on every activity type; --meeting remains an alias for --activity.
 ente activity message add <activityId> --content "Decision: ship the smaller scope first."
 ente activity content read <activityId> --json
 ente activity content edit <activityId> --expected-version 42 --operations-file edits.json --json
@@ -446,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
@@ -184,8 +187,9 @@ ente activity attachment upload <activityId> ./file.pdf [--name "Contract.pdf"]
 ente activity delete <activityId> [--json]
 ente activity restore <activityId> [--json]
 
-# Meeting agendas
-ente agenda create-point --meeting <meetingActivityId> --title "Decisions" [--content="…"] [--content-file ./decisions.md] [--parent <agendaPointId>] [--after <agendaPointId>] [--json]
+# Activity agendas (all activity types)
+# --meeting remains a compatibility alias for --activity.
+ente agenda create-point --activity <activityId> --title "Decisions" [--content="…"] [--content-file ./decisions.md] [--parent <agendaPointId>] [--after <agendaPointId>] [--json]
 ente agenda link-task --point <agendaPointId> --task <activityId|#N> [--json]
 
 # Excalidraw Canvas HTML prototypes
@@ -623,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.77";
+var VERSION = "0.4.79";
 
 // ente/branding.ts
 var NPM_REGISTRY = "https://registry.npmjs.org";
@@ -4246,7 +4246,7 @@ var EnteClient = class _EnteClient {
       ...spaceId ? { spaceId } : {}
     });
   }
-  // --- meeting agendas ---------------------------------------------------
+  // --- activity agendas ---------------------------------------------------
   createAgendaPoint(body) {
     return this.rest.post("/api/external/agenda-points", body);
   }
@@ -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];
@@ -15742,12 +15759,12 @@ import { readFileSync as readFileSync12 } from "node:fs";
 var AgendaPointCreate = class extends ClientCommand {
   static paths = [["agenda", "create-point"]];
   static usage = Command.Usage({
-    category: "Meeting agenda",
+    category: "Activity agenda",
     description: "Create a titled agenda point with optional markdown content"
   });
-  meeting = options_exports.String("--meeting", {
+  activity = options_exports.String("--activity,--meeting", {
     required: true,
-    description: "Meeting activity ID"
+    description: "Activity ID of any type (--meeting is a compatibility alias)"
   });
   title = options_exports.String("--title", {
     required: true,
@@ -15770,7 +15787,7 @@ var AgendaPointCreate = class extends ClientCommand {
       throw new Error("Use either --content or --content-file, not both.");
     const contentMarkdown = this.content !== void 0 ? this.content : this.contentFile !== void 0 ? readFileSync12(this.contentFile, "utf8") : void 0;
     const result = await this.client().createAgendaPoint({
-      meetingActivityId: this.meeting,
+      meetingActivityId: this.activity,
       title: this.title,
       contentMarkdown,
       parentPointId: this.parent,
@@ -15783,7 +15800,7 @@ var AgendaPointCreate = class extends ClientCommand {
 var agendaPointDocumentId = (pointId) => `agenda-point:${pointId}`;
 var AgendaHtmlList = class extends ProfileCommand {
   static paths = [["agenda", "html", "list"]];
-  static usage = Command.Usage({ category: "Meeting agenda", description: "List interactive HTML blocks in an agenda point" });
+  static usage = Command.Usage({ category: "Activity agenda", description: "List interactive HTML blocks in an agenda point" });
   pointId = options_exports.String();
   async run() {
     const caller = await resolveCaller();
@@ -15794,7 +15811,7 @@ var AgendaHtmlList = class extends ProfileCommand {
 };
 var AgendaHtmlGet = class extends ProfileCommand {
   static paths = [["agenda", "html", "get"]];
-  static usage = Command.Usage({ category: "Meeting agenda", description: "Read one agenda-point HTML block including source" });
+  static usage = Command.Usage({ category: "Activity agenda", description: "Read one agenda-point HTML block including source" });
   pointId = options_exports.String();
   blockId = options_exports.String();
   async run() {
@@ -15807,7 +15824,7 @@ var AgendaHtmlGet = class extends ProfileCommand {
 };
 var AgendaHtmlAdd = class extends ProfileCommand {
   static paths = [["agenda", "html", "add"]];
-  static usage = Command.Usage({ category: "Meeting agenda", description: "Append an interactive HTML block to an agenda point" });
+  static usage = Command.Usage({ category: "Activity agenda", description: "Append an interactive HTML block to an agenda point" });
   pointId = options_exports.String();
   htmlFile = options_exports.String({ required: false, name: "htmlFile" });
   htmlFileFlag = options_exports.String("--html-file", { description: "Read HTML from a file; use - or omit for stdin" });
@@ -15832,7 +15849,7 @@ var AgendaHtmlAdd = class extends ProfileCommand {
 };
 var AgendaHtmlUpdate = class extends ProfileCommand {
   static paths = [["agenda", "html", "update"]];
-  static usage = Command.Usage({ category: "Meeting agenda", description: "Surgically update one agenda-point HTML block" });
+  static usage = Command.Usage({ category: "Activity agenda", description: "Surgically update one agenda-point HTML block" });
   pointId = options_exports.String();
   blockId = options_exports.String();
   htmlFile = options_exports.String("--html-file", { description: "Read HTML from a file; use - for stdin" });
@@ -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
@@ -16225,12 +16242,12 @@ Creating activities:
     --entity "Erik Stahl" --entity "Preclinics" --space "Preclinics" \\
     --content "Discussed QM system. Follow up on export feature."
 
-Meeting agendas:
+Activity agendas (all activity types; --meeting remains an alias):
   ente activity create --type meeting --title "QM system review" ...
-  ente agenda create-point --meeting <meeting-id> --title "Rollout" --content="- Decision ..."
+  ente agenda create-point --activity <activity-id> --title "Rollout" --content="- Decision ..."
   ente agenda link-task --point <point-id> --task "#12"
 
-  Prefer agenda points for structured meeting content when they add useful
+  Prefer agenda points for structured activity content when they add useful
   topic structure. Link meeting-derived tasks to the point they came from.
 
 Golden rule:
@@ -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
@@ -16305,7 +16322,7 @@ Tips:
   1. ente search "person name"         # find entity, check pins
   2. ente activity create --type meeting --title "..." \\
        --entity "person" --entity "their org" --space "..."
-  3. ente agenda create-point --meeting <meeting-id> --title "..." --content="..."
+  3. ente agenda create-point --activity <activity-id> --title "..." --content="..."
   4. If follow-ups: create each task, then:
      ente agenda link-task --point <point-id> --task <task-id|#N>