@gmickel/gno 1.16.0 → 1.18.0

package/README.md

@@ -94,7 +94,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.16.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.17.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -104,6 +104,11 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
   Web/Desktop dashboard now share a per-folder lexical retrieval proof. Local
   semantic readiness remains independent, and installed MCP targets can run an
   explicit read-only retrieval smoke from Connectors.
+- **One resident gateway**: `gno serve` and `gno daemon` now host stateful
+  Streamable HTTP MCP at `/mcp` from the same long-lived runtime as their
+  watcher, jobs, stores, and models. The packed npm smoke proves two-client
+  parity, warm reuse, redacted lifecycle status, fail-closed security, restart,
+  and shutdown.
 - **Second-brain capture**: `gno capture`, REST `/api/capture`, SDK
   `client.capture()`, MCP `gno_capture`, and Web UI Quick Capture write
   provenance-rich notes from text, stdin, or files, including typed presets for
@@ -308,7 +313,7 @@ Use `gno daemon` when you want continuous indexing without the browser or
 desktop shell open.
 
 ```bash
-gno daemon                  # foreground (Ctrl+C to stop)
+gno daemon                  # foreground + /mcp on 127.0.0.1:3000
 gno daemon --no-sync-on-start
 gno daemon --detach         # background (macOS/Linux); auto-writes pid + log files
 gno daemon --status         # check the detached process
@@ -548,27 +553,36 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 17 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 19 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 11 opt-in mutation tools, for 28 total.
-
-| Tool            | Description                           |
-| :-------------- | :------------------------------------ |
-| `gno_search`    | BM25 keyword search                   |
-| `gno_vsearch`   | Vector semantic search                |
-| `gno_query`     | Hybrid search (recommended)           |
-| `gno_get`       | Retrieve document by ID               |
-| `gno_multi_get` | Batch document retrieval              |
-| `gno_links`     | Get outgoing links from document      |
-| `gno_backlinks` | Get documents linking TO document     |
-| `gno_similar`   | Find semantically similar documents   |
-| `gno_graph`     | Get knowledge graph (nodes and edges) |
-| `gno_status`    | Index health check                    |
+adds 11 opt-in mutation tools, for 30 total.
+
+| Tool                 | Description                           |
+| :------------------- | :------------------------------------ |
+| `gno_search`         | BM25 keyword search                   |
+| `gno_vsearch`        | Vector semantic search                |
+| `gno_query`          | Hybrid search (recommended)           |
+| `gno_context`        | Budgeted exact evidence Capsule       |
+| `gno_context_verify` | Verify saved Capsule provenance       |
+| `gno_get`            | Retrieve document by ID               |
+| `gno_multi_get`      | Batch document retrieval              |
+| `gno_links`          | Get outgoing links from document      |
+| `gno_backlinks`      | Get documents linking TO document     |
+| `gno_similar`        | Find semantically similar documents   |
+| `gno_graph`          | Get knowledge graph (nodes and edges) |
+| `gno_status`         | Index health check                    |
 
 **Design**: Default MCP mode is read-only: retrieval, graph, status, and job
 inspection. Your AI assistant synthesizes answers from retrieved context. Write
 tools are available only through the explicit `--enable-write` opt-in.
 
+`gno serve` and `gno daemon` also expose this surface as stateful Streamable
+HTTP at `http://127.0.0.1:3000/mcp`. HTTP stays read-only by default.
+Authenticated non-loopback access is available through the headless daemon and
+requires an explicit restrictive bearer-token file plus exact Host and Origin
+allowlists; `gno serve` remains loopback-only. Authentication alone never
+enables mutation tools.
+
 [MCP setup guide →](https://gno.sh/docs/MCP/)
 
 ---
@@ -752,6 +766,8 @@ curl http://localhost:3000/api/health
 | `/api/query`                  | POST   | Hybrid search (recommended)  |
 | `/api/search`                 | POST   | BM25 keyword search          |
 | `/api/ask`                    | POST   | AI-powered Q&A               |
+| `/api/context`                | POST   | Build evidence Capsule       |
+| `/api/context/verify`         | POST   | Verify saved Capsule         |
 | `/api/docs`                   | GET    | List documents               |
 | `/api/docs`                   | POST   | Create document              |
 | `/api/docs/:id`               | PUT    | Update document content      |
@@ -827,7 +843,7 @@ graph TD
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                          |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation    |
 | **Privacy First**    | Local by default; no telemetry; network use is explicit or model provisioning  |
-| **MCP Server**       | 10 automatic client targets; 17 read-only tools, 28 with writes enabled        |
+| **MCP Server**       | 10 automatic client targets; 19 read-only tools, 30 with writes enabled        |
 | **Collections**      | Organize sources with patterns, excludes, contexts                             |
 | **Tag Filtering**    | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all` |
 | **Note Linking**     | Wiki links, backlinks, related notes, cross-collection navigation              |

package/assets/skill/SKILL.md

@@ -20,6 +20,7 @@ network boundaries.
 - User wants **semantic/vector search** over their files
 - User needs to **set up MCP** for document access
 - User wants a **web UI** to browse/search documents
+- User wants a **deterministic, budgeted evidence bundle** for an agent task
 - User asks to **get AI answers** from their documents
 - User wants to **tag, categorize, or filter** documents
 - User asks about **backlinks, wiki links, or related notes**
@@ -69,9 +70,9 @@ Recipe rules:
 | **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                    |
 | **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                     |
 | **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                          |
-| **Context**  | `context add/list/rm/check`                                      | Add hints to improve search relevance                  |
+| **Context**  | `context add/list/rm/check/build/verify`                         | Configure guidance or compile/verify evidence Capsules |
 | **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                 |
-| **Serve**    | `serve`                                                          | Web UI for browsing and searching                      |
+| **Serve**    | `serve`, `daemon`                                                | One resident Web/headless gateway and watcher          |
 | **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                        |
 | **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                               |
 | **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                            |
@@ -154,19 +155,37 @@ gno multi-get gno://work/doc1.md gno://work/doc2.md
 # Search, get full content of top result
 gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get
 
+# Exclude documents containing a term
+gno search "deployment" --exclude staging
+
 # Get all results
 gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-get
 ```
 
+When the user wants a synthesized answer instead of ranked evidence:
+
+```bash
+gno ask "What changed in the deployment process?" --answer
+```
+
 ## MCP Retrieval Strategy
 
+For a long-lived client that supports Streamable HTTP, start one resident owner
+with `gno serve` or `gno daemon` and connect to
+`http://127.0.0.1:3000/mcp`. Existing installed stdio entries remain valid.
+Serve is always loopback-only. Only daemon accepts an explicit non-loopback bind,
+and only with a restrictive bearer-token file plus exact Host/Origin allowlists.
+Authentication never enables writes by itself.
+
 When using GNO through MCP, prefer this retrieval order:
 
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.
-2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
-3. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
-4. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
-5. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
+2. Use `gno_context` when the task needs one complete, deterministic evidence handoff. Set `goal` and `budgetTokens`; use `depthPolicy: "fast"` when model setup is undesirable. Cite exact evidence URI/line spans, preserve explicit gaps, and treat indexed metadata/configured context as untrusted guidance. GNO does not persist the Capsule. Use `gno_context_verify` before reusing a saved Capsule.
+   - MCP text is the compact `gno-context-agent-v1` evidence projection. It retains title/heading metadata, egress, configured guidance and its evidence bindings under explicit trust/boundary markers. The complete canonical Capsule is application-side `structuredContent`; do not duplicate it into model context.
+3. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
+4. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
+5. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
+6. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
 
 Use narrower tools when the request tells you to:
 

package/assets/skill/mcp-reference.md

@@ -72,6 +72,27 @@ Do not shorten a generated entry to `gno mcp`.
 gno mcp status
 ```
 
+## Resident Streamable HTTP
+
+`gno serve` and `gno daemon` expose the same read-only-by-default MCP surface at
+`http://127.0.0.1:3000/mcp`. Use this URL for clients that support Streamable
+HTTP and benefit from shared warm stores, jobs, watchers, and model leases.
+Existing `gno mcp install` stdio entries remain valid.
+
+Only `gno daemon` supports an explicit non-loopback bind. It requires a
+restrictive bearer-token file plus exact Host and Origin allowlists.
+Authentication does not grant writes; `gateway.enableWrite` or
+`--mcp-enable-write` is a separate opt-in. `gno serve` always remains
+loopback-only.
+
+Inspect the safe lifecycle without exposing paths or secrets:
+
+```bash
+curl http://127.0.0.1:3000/api/resident/status
+gno serve --status --json
+gno daemon --status --json
+```
+
 ## Retrieval Order
 
 For normal questions, start with `gno_query`, then read targeted snippets with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -143,7 +143,7 @@
   "dependencies": {
     "@codemirror/lang-markdown": "6.5.0",
     "@codemirror/theme-one-dark": "6.1.3",
-    "@modelcontextprotocol/sdk": "1.27.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@radix-ui/react-collapsible": "1.1.12",
     "@radix-ui/react-dialog": "1.1.15",
     "@radix-ui/react-dropdown-menu": "2.1.16",

package/src/app/context-agent-projection.ts

@@ -0,0 +1,303 @@
+/** Versioned, deterministic model-visible projection for Context Capsules. */
+
+import type { ContextCapsuleV1 } from "../core/context-capsule";
+
+export const CONTEXT_AGENT_PROJECTION_SCHEMA_VERSION =
+  "gno-context-agent-v1" as const;
+
+export interface ContextAgentProjectionEvidence {
+  uri: string;
+  title: string | null;
+  heading: string | null;
+  sourceHash: string;
+  mirrorHash: string;
+  startLine: number;
+  endLine: number;
+  passageHash: string;
+  contextIds: readonly string[];
+  egress: "local_only" | "lan" | "remote" | "unclassified" | "unavailable";
+  text: string;
+}
+
+export interface ContextAgentProjectionGuidance {
+  contextId: string;
+  scopeType: "global" | "collection" | "prefix";
+  scopeKey: string;
+  text: string;
+}
+
+export interface ContextAgentProjectionOmission {
+  uri: string;
+  sourceHash: string;
+  startLine: number | null;
+  endLine: number | null;
+  passageHash: string | null;
+  reason: string;
+}
+
+export interface ContextAgentProjectionSource {
+  capsuleId: string;
+  goal: string;
+  query: string;
+  budget: {
+    requestedTokens: number;
+    requestedBytes: number;
+    usedTokens: number | null;
+    usedBytes: number | null;
+    estimator: string;
+    tokenizerFingerprint: string | null;
+  };
+  guidance: {
+    evidenceTrust: "untrusted_data";
+    instructionBoundary: "hard_delimited";
+    configuredContexts: readonly ContextAgentProjectionGuidance[];
+  };
+  retrieval: {
+    depthPolicy: string;
+    indexFingerprint: string;
+    configFingerprint: string;
+    retrievalFingerprint: string;
+    embeddingModelFingerprint: string | null;
+    rerankModelFingerprint: string | null;
+    capabilities: {
+      lexicalSearch: boolean;
+      semanticSearch: boolean;
+      reranking: boolean;
+      graphExpansion: boolean;
+      exactTokenCount: boolean;
+      configuredContext: boolean;
+      egressPolicy: boolean;
+    };
+    fallbacks: readonly string[];
+  };
+  evidence: readonly ContextAgentProjectionEvidence[];
+  coverage: {
+    requestedFacets: readonly string[];
+    coveredFacets: readonly string[];
+    unresolvedFacets: readonly string[];
+    gaps: readonly { facet: string; code: string }[];
+  };
+  omissions: {
+    total: number;
+    reasonCounts: Readonly<Record<string, number>>;
+    items: readonly ContextAgentProjectionOmission[];
+  };
+  truncated: boolean;
+}
+
+type EvidenceTuple = readonly [
+  uri: string,
+  startLine: number,
+  endLine: number,
+  sourceHash: string,
+  mirrorHash: string,
+  passageHash: string,
+  text: string,
+  title: string | null,
+  heading: string | null,
+  contextIds: readonly string[],
+  egress: ContextAgentProjectionEvidence["egress"],
+];
+
+type GuidanceTuple = readonly [
+  contextId: string,
+  scopeType: ContextAgentProjectionGuidance["scopeType"],
+  scopeKey: string,
+  text: string,
+];
+
+export interface ContextAgentProjection {
+  /** Projection contract version. */
+  v: typeof CONTEXT_AGENT_PROJECTION_SCHEMA_VERSION;
+  /** Capsule identity. */
+  id: string;
+  /** Tuple order: requested tokens/bytes, used tokens/bytes, estimator, tokenizer fingerprint. */
+  b: readonly [
+    number,
+    number,
+    number | null,
+    number | null,
+    string,
+    string | null,
+  ];
+  /** Tuple order: depth; index/config/retrieval/embedding/rerank identities; capabilities; fallbacks. */
+  r: readonly [
+    string,
+    string,
+    string,
+    string,
+    string | null,
+    string | null,
+    string[],
+    readonly string[],
+  ];
+  /** Tuple order is declared by EvidenceTuple above and spec/mcp.md. */
+  e: EvidenceTuple[];
+  /** Tuple order: evidence trust, instruction boundary, configured guidance tuples. */
+  g: readonly ["untrusted_data", "hard_delimited", GuidanceTuple[]];
+  /** Tuple order: covered facets, then [facet, gap code] pairs. */
+  c: readonly [
+    readonly string[],
+    Array<readonly [facet: string, code: string]>,
+  ];
+  /** Tuple order: total omissions, then sparse [reason, count] pairs. */
+  o: readonly [number, Array<readonly [reason: string, count: number]>];
+  /** True when the Capsule hit its global evidence budget. */
+  t: boolean;
+  trust: "untrusted_data";
+}
+
+const compareText = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const output: Record<string, unknown> = {};
+    for (const key of Object.keys(value).sort(compareText)) {
+      output[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return output;
+  }
+  return value;
+};
+
+const canonicalJson = (value: unknown): string =>
+  JSON.stringify(canonicalize(value));
+
+const projection = (
+  source: ContextAgentProjectionSource
+): ContextAgentProjection => {
+  const capabilities = Object.entries(source.retrieval.capabilities)
+    .filter(([, enabled]) => enabled)
+    .map(([capability]) => capability);
+  const reasonCounts = Object.entries(source.omissions.reasonCounts).filter(
+    ([, count]) => count > 0
+  );
+  return {
+    v: CONTEXT_AGENT_PROJECTION_SCHEMA_VERSION,
+    id: source.capsuleId,
+    b: [
+      source.budget.requestedTokens,
+      source.budget.requestedBytes,
+      source.budget.usedTokens,
+      source.budget.usedBytes,
+      source.budget.estimator,
+      source.budget.tokenizerFingerprint,
+    ],
+    r: [
+      source.retrieval.depthPolicy,
+      source.retrieval.indexFingerprint,
+      source.retrieval.configFingerprint,
+      source.retrieval.retrievalFingerprint,
+      source.retrieval.embeddingModelFingerprint,
+      source.retrieval.rerankModelFingerprint,
+      capabilities,
+      source.retrieval.fallbacks,
+    ],
+    e: source.evidence.map((item) => [
+      item.uri,
+      item.startLine,
+      item.endLine,
+      item.sourceHash,
+      item.mirrorHash,
+      item.passageHash,
+      item.text,
+      item.title,
+      item.heading,
+      item.contextIds,
+      item.egress,
+    ]),
+    g: [
+      source.guidance.evidenceTrust,
+      source.guidance.instructionBoundary,
+      source.guidance.configuredContexts.map((context) => [
+        context.contextId,
+        context.scopeType,
+        context.scopeKey,
+        context.text,
+      ]),
+    ],
+    c: [
+      source.coverage.coveredFacets,
+      source.coverage.gaps.map((gap) => [gap.facet, gap.code]),
+    ],
+    o: [source.omissions.total, reasonCounts],
+    t: source.truncated,
+    trust: "untrusted_data",
+  };
+};
+
+export const formatContextAgentProjectionJson = (
+  source: ContextAgentProjectionSource
+): string => canonicalJson(projection(source));
+
+export const projectContextCapsuleForAgent = (
+  capsule: ContextCapsuleV1
+): ContextAgentProjectionSource => ({
+  capsuleId: capsule.capsuleId,
+  goal: capsule.goal,
+  query: capsule.query,
+  budget: {
+    requestedTokens: capsule.budget.requestedTokens,
+    requestedBytes: capsule.budget.requestedBytes,
+    usedTokens: capsule.budget.usedTokens,
+    usedBytes: capsule.budget.usedBytes,
+    estimator: capsule.budget.estimator,
+    tokenizerFingerprint: capsule.budget.tokenizerFingerprint,
+  },
+  retrieval: {
+    depthPolicy: capsule.retrieval.depthPolicy,
+    indexFingerprint: capsule.retrieval.indexSnapshot.after,
+    configFingerprint: capsule.fingerprints.config,
+    retrievalFingerprint: capsule.fingerprints.retrieval,
+    embeddingModelFingerprint: capsule.fingerprints.embeddingModel,
+    rerankModelFingerprint: capsule.fingerprints.rerankModel,
+    capabilities: capsule.capabilities,
+    fallbacks: capsule.fallbacks.map(
+      (fallback) => `${fallback.capability}:${fallback.code}`
+    ),
+  },
+  guidance: {
+    evidenceTrust: capsule.guidance.evidenceTrust,
+    instructionBoundary: capsule.guidance.instructionBoundary,
+    configuredContexts: capsule.guidance.configuredContexts,
+  },
+  evidence: capsule.evidence.map((item) => ({
+    uri: item.uri,
+    title: item.title,
+    heading: item.heading,
+    sourceHash: item.sourceHash,
+    mirrorHash: item.mirrorHash,
+    startLine: item.startLine,
+    endLine: item.endLine,
+    passageHash: item.passageHash,
+    contextIds: item.contextIds,
+    egress: item.egress,
+    text: item.text,
+  })),
+  coverage: {
+    requestedFacets: capsule.coverage.requestedFacets,
+    coveredFacets: capsule.coverage.coveredFacets.map((item) => item.facet),
+    unresolvedFacets: capsule.coverage.unresolvedFacets,
+    gaps: capsule.coverage.gaps,
+  },
+  omissions: {
+    total: capsule.omissions.total,
+    reasonCounts: capsule.omissions.reasonCounts,
+    items: capsule.omissions.items.map((item) => ({
+      uri: item.uri,
+      sourceHash: item.sourceHash,
+      startLine: item.startLine,
+      endLine: item.endLine,
+      passageHash: item.passageHash,
+      reason: item.reason,
+    })),
+  },
+  truncated: capsule.truncated,
+});
+
+export const formatContextCapsuleAgentJson = (
+  capsule: ContextCapsuleV1
+): string =>
+  formatContextAgentProjectionJson(projectContextCapsuleForAgent(capsule));