@indexnetwork/protocol 14.3.2-rc.477.1 → 17.0.0-rc.479.1

package/CHANGELOG.md

@@ -20,6 +20,146 @@ went 6.7.1 → 8.0.2 with no 7.x in between because the whole 7.x line shipped a
 prereleases between the two promotions. To track every change, read `rc`; to
 pin a supported release, use `latest`.
 
+## 17.0.0 - 2026-08-17
+
+### Removed
+
+- **BREAKING**: Remove the `integrations` capability entirely
+  (`src/integrations/`) and its public exports: `IntegrationAdapter`,
+  `IntegrationConnection`, `IntegrationSession`, `IntegrationSessionOptions`,
+  `ToolActionResponse`. Hosts that typed a Composio adapter against these
+  should declare the shape locally — `services/api` already carries a
+  structurally identical copy in `adapters/integration.adapter.ts`.
+- **BREAKING**: Remove `generateInviteMessage` (and `InviteInput` /
+  `InviteOutput`). It generated outreach copy for ghost-user counterparts and
+  required `recipient.isGhost`; with ghost users retired it can never fire.
+- **BREAKING**: Remove the `import_gmail_contacts`, `import_contacts` and
+  `add_contact` tools. These were the only paths that minted ghost users.
+  Contacts are now established solely by accepting an opportunity, which writes
+  the mutual `contact` memberships. `list_contacts`, `remove_contact` and
+  `search_contacts` are unchanged.
+- **BREAKING**: Remove `contactsEnabled` from `ToolDeps`, the tool-registry
+  composition deps, and `resolveChatContext`. The `CONTACTS_ENABLED` flag gated
+  only the removed write paths and no longer exists.
+- **BREAKING**: Remove `integration` and `integrationImporter` from `ToolDeps`.
+  Nothing in the protocol consumed them once the integration tools were removed.
+- Remove `createGhostUser` from the database interface. No protocol code path
+  creates users any more.
+
+### Changed
+
+- `ContactServiceAdapter` narrows to `listContacts` / `removeContact` /
+  `searchContacts`; `importContacts` and `addContact` are gone, along with the
+  `ContactInput`, `ContactResult` and `ContactImportResult` domain types.
+- Orchestrator, negotiator, signal and onboarding prompt surfaces no longer
+  advertise contact import or Gmail import.
+
+## 16.1.0 - 2026-08-17
+
+### Removed
+
+- Remove the eval harnesses (`eval/`) and the 13 `eval:*` package scripts. No
+  public API change: `src/` never imported `eval/`, so the package build,
+  architecture gates and source tests are unaffected. The final state is
+  preserved in the `archive/eval-2026-08-16` tag; restore with
+  `git checkout archive/eval-2026-08-16 -- packages/protocol/eval`.
+
+## 16.0.0 - 2026-08-17
+
+### Removed
+
+- **Breaking:** MCP no longer gates on web/CLI onboarding. Incomplete
+  onboarding does not restrict the MCP inventory, `onboarding_human` and
+  `onboarding_required` are gone, and `complete_onboarding` is omitted from
+  the MCP registry. `read_user_contexts` no longer returns
+  `onboardingComplete` on MCP. Web onboarding chat and the REST Tool API
+  keep the existing completion flow.
+
+## 15.0.0 - 2026-08-17
+
+Public-surface prune. `src/index.ts` goes from 443 exported symbols across 164
+export statements to 312 across 143. No implementation changed: every removed
+symbol still exists and still works inside the package — it is simply no longer
+re-exported from the barrel.
+
+A symbol was kept whenever a retained export could not be *used* without it —
+parameter and member types of exported functions, interfaces, and unions stay
+public even with no direct importer, because an exported symbol whose members
+cannot be named is not usable.
+
+The removal set was derived by parsing every barrel export and resolving it
+against every consumer reference in `services/`, `apps/`, `packages/*`,
+`docs/`, `.claude/`, and the protocol's own `eval/` and `skills/` trees —
+covering static named imports, `import type` queries, `import('...').Sym` type
+positions, `await import()` destructuring, namespace aliases, and `mock.module`
+shapes. A symbol was removed only when nothing outside the package imported it
+from the package root.
+
+### Removed from the public API (BREAKING)
+
+131 symbols. None were deleted; all remain internal. The largest groups:
+
+- **Capability tool factories** — `createChatTools`, `createAgentTools`,
+  `createIntentTools`, `createNetworkTools`, `createOpportunityTools`,
+  `createNegotiationTools`, `createQuestionerTools`,
+  `createAskUserQuestionTools`, `createContactTools`, `createIntegrationTools`,
+  `createPremiseTools`, and their `*ToolDeps` types. These are composed
+  internally by `createMcpServer` / `createToolRegistry`, which remain public.
+  `createEnrichmentTools` and `EnrichmentToolDeps` stay exported — the API
+  service calls them directly from its enrichment-run worker.
+- **MCP authorization policy** — 27 symbols from `mcp/mcp.authorization-policy.ts`
+  (`MCP_AGENT_ADMIN_TOOLS`, `McpCapabilityPolicy`, `McpToolAccessRuleSchema`,
+  `defineMcpToolAccessRules`, the `Mcp*` policy types, …). Four stay public
+  because a host cannot type its own `createMcpServer` call without them:
+  `CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS`, `McpCapabilityPolicyOptions` (the
+  fourth parameter), `McpAuthorizationObserver`, and
+  `McpAuthorizationDenialEvent` (the observer callback's only argument).
+- **Activity projection** — 15 symbols from `shared/agent/activity-projection.ts`
+  (`projectActivitySummary`, `ActivitySummaryResponseSchema`,
+  `QUESTION_MODE_TO_DOMAIN`, `READ_ACTIVITY_SUMMARY_TOOL_NAME`, …).
+- **Persona helpers** — the `filter*Tools` / `narrow*Tools` helpers, the
+  `*_TOOL_NAMES` constants, and the `SIGNAL_NEW_SIGNAL_KICKOFF` /
+  `ONBOARDING_PROFILE_KICKOFF` constants. The persona IDs, the prompt
+  constants, and `REPORTER_BRIEFING_KICKOFF` stay — `apps/web` imports the
+  latter.
+- **Discovery env accessors** — `discoveryAllowedTypes`, `discoveryMinSimilarity`,
+  `discoveryProfileSource`, `discoveryIntentMatchingEnabled`,
+  `discoveryProfileMatchingEnabled`, the `validate*` helpers, and the
+  `DISCOVERY_*_DEFAULT` constants. `discoveryEvaluatorMinScore` stays: its one
+  importer is `services/api/src/cli/discovery-env-matrix.main.ts`. That CLI is
+  slated for removal with the eval harnesses, and this accessor should be
+  pruned in the same change. These back live Railway configuration and are
+  unchanged in behaviour; only the re-export is gone.
+- **Signal-intake types** — `IntakePack`, `IntakePackInput`, `SynthesisInput`,
+  `SynthesisResult`, `FollowUpPlan`, `answerLabel`, `normalizeIntakePack`, …
+
+Two of the removed symbols (`createAgentTools` and
+`CANONICAL_MCP_TOOL_ACCESS_RULES`) are referenced by `services/api` tests
+through deep source paths rather than the package root, so those tests are
+unaffected by the barrel change.
+
+### Changed
+
+- `IMPLEMENTATION.md` §1 no longer documents a `modelConfig` override on
+  `ToolDeps` — that field does not exist there. `modelConfig` lives on the
+  internal `ToolContext` / `ProtocolDeps` composition, which is not exported, so
+  the section now documents the environment variables as the supported
+  configuration path and states plainly that programmatic override is outside
+  the public contract.
+- `IMPLEMENTATION.md` §3 now documents `createMcpServer` and
+  `createToolRegistry` + `invokeToolRuntime` as the supported tool entry points,
+  replacing the `createChatTools` walkthrough.
+- `STABILITY.md` — the **Capability tools** tier now covers
+  `createEnrichmentTools` only; the **Public API** row names `createToolRegistry`
+  and corrects `ToolContext` to the actually-exported `ResolvedToolContext`.
+
+### Migration
+
+Hosts composing tools by capability should call `createMcpServer` (full MCP
+server, policy applied) or `createToolRegistry` (raw handler map, invoked via
+`invokeToolRuntime`). Both take the same dependency object the individual
+factories did.
+
 ## 14.3.2 - 2026-08-16
 
 No source change. The public contract in `src/index.ts` is untouched; only
@@ -419,6 +559,7 @@ No public API change: all 441 exported symbols are byte-identical to 13.2.0, and
 ## [Unreleased]
 
 ### Changed
+- Behaviour-neutral internal refactor (16.1.1): split the six largest modules and hoist every graph node to a top-level function. The opportunity graph is now the discovery pipeline only — its eight non-pipeline modes (read, update, delete, send, negotiate_existing, approve_introduction, and the two introduction stages) are plain functions on `OpportunityGraphFactory` instead of `operationMode` conditional-edge routing. `database.interface.ts` becomes a barrel over entity, query-group, and capability-view modules; every `Pick<Database, ...>` resolves as before. The opportunity presentation cluster is one module. `opportunity.graph.ts` 4167 → 250 lines, `database.interface.ts` 2925 → 17, `negotiation.graph.ts` 1619 → 111, `opportunity.tools.ts` 1200 → 354, `enrichment.tools.ts` 1198 → 178, `intent.graph.ts` 1091 → 174. No public export, feature flag, or environment variable changed.
 - Move the opportunity-presentation review checklist into `src/opportunity/AGENTS.md` and repoint the `opportunity.safe-presentation.ts` and `discriminator.adjustments.ts` comments at it. Comment-only; no runtime change.
 
 ### Removed

package/IMPLEMENTATION.md

@@ -10,7 +10,7 @@ supported entry point is the package root (`import { ... } from "@indexnetwork/p
 deep imports are not part of the contract. Every symbol is re-exported explicitly from
 `src/index.ts` and tagged with a stability tier:
 
-- **Stable** — interfaces, graph factories, agents, `createChatTools`, the
+- **Stable** — interfaces, graph factories, agents, `createMcpServer`, the
   tool/runtime helpers, and shared schemas. Breaking changes require a major bump.
 - **Experimental** (`@experimental`) — advanced graph-state types and internal
   helpers; may change in a minor release.
@@ -35,27 +35,15 @@ npm install @indexnetwork/protocol
 
 The package reads `OPENROUTER_API_KEY` (required), `CHAT_MODEL`, and `CHAT_REASONING_EFFORT` from environment variables. No startup call is needed.
 
-To override the chat model or reasoning effort when using the built-in chat runtime (`ChatGraphFactory` / `ChatAgent`), pass `modelConfig` on `ToolContext`. `ChatAgent` reads these fields when the chat graph runs; the tools themselves do not consume `modelConfig`:
+Environment variables are the supported way to configure models. `CHAT_MODEL` and `CHAT_REASONING_EFFORT` (`minimal | low | medium | high | xhigh`) drive the built-in chat runtime (`ChatGraphFactory` / `ChatAgent`); every other protocol agent — evaluators, generators, miners — reads `OPENROUTER_API_KEY` from the environment.
 
-```typescript
-import { createChatTools } from "@indexnetwork/protocol";
-
-const tools = await createChatTools({
-  // ... other deps ...
-  modelConfig: {
-    chatModel: "google/gemini-2.5-flash",       // optional — has a default
-    chatReasoningEffort: "low",                  // optional: minimal | low | medium | high | xhigh
-  },
-});
-```
-
-`apiKey` and `baseURL` can also be overridden this way. All other protocol agents (evaluators, generators, etc.) rely on `OPENROUTER_API_KEY` set in the environment regardless of `modelConfig`.
+There is a per-instance `modelConfig` (chat model, reasoning effort, `apiKey`, `baseURL`) that `ChatAgent` reads off the resolved tool context, but it lives on the internal composition types (`ToolContext` / `ProtocolDeps`), not on `ToolDeps`, and those types are not exported. **Programmatic model override is therefore not part of the public contract in 15.0.0** — use the environment variables. If you need a typed override path, open an issue rather than reaching through a deep import.
 
 ### 2. Implement the adapters
 
 The package defines interfaces — your application provides the concrete implementations.
 
-**Required** (always needed by `createChatTools`):
+**Required** (always needed by the tool registry):
 
 | Interface | Responsibility |
 |---|---|
@@ -90,50 +78,60 @@ All interfaces are exported from the package root — import them with `import t
 
 ### 3. Create tools
 
-Pass your adapter implementations to `createChatTools` to get a set of LangChain-compatible tools bound to a user session:
+Two entry points are supported, both taking a single dependency object built
+from the adapters above.
+
+`createMcpServer` is the complete integration: it composes every capability's
+tools internally, applies the authorization policy, and returns a ready MCP
+server.
 
 ```typescript
-import { createChatTools } from "@indexnetwork/protocol";
+import { createMcpServer, CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS } from "@indexnetwork/protocol";
 
-const tools = await createChatTools({
-  userId: "user-uuid",
+const server = createMcpServer(
+  deps,                // ToolDeps + the opportunity owner-approval port
+  authResolver,        // McpAuthResolver
+  scopedDepsFactory,   // ScopedDepsFactory — builds per-user scoped userDb/systemDb
+  CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS,
+  authorizationObserver, // optional McpAuthorizationObserver
+);
+```
+
+`createToolRegistry` is the lower-level surface for hosts running their own
+runtime. It returns a `Map` of tool name to `RawToolDefinition` — raw async
+handlers taking `{ context, query }` — which you invoke through
+`invokeToolRuntime`:
+
+```typescript
+import { createToolRegistry, invokeToolRuntime, resolveChatContext } from "@indexnetwork/protocol";
 
-  // ── Required adapters ──
-  database,             // ChatGraphCompositeDatabase
-  embedder,             // Embedder
-  scraper,              // Scraper
-  cache,                // Cache
-  hydeCache,            // HydeCache
-  integration,          // IntegrationAdapter
-  intentQueue,          // IntentGraphQueue
-  contactService,       // ContactServiceAdapter
-  chatSession,          // ChatSessionReader
-  enricher,             // ProfileEnricher
-  negotiationDatabase,  // NegotiationGraphDatabase
-  integrationImporter,  // bulk contact import
-  createUserDatabase,   // (db, userId) => UserDatabase
-  createSystemDatabase, // (db, userId, indexScope, embedder?) => SystemDatabase
-
-  // ── Optional scoping ──
-  networkId: "optional-network-uuid", // scope tools to a specific index/network
-  sessionId: "chat-session-id",       // enables draft opportunities with conversation context
-
-  // ── Optional capabilities (enable when the host supports them) ──
-  agentDatabase,        // AgentDatabase — agent registry
-  agentDispatcher,      // AgentDispatcher — routes negotiation turns to personal agents
-  deliveryLedger,       // DeliveryLedger — OpenClaw delivery commits
-  enrichmentRuns,       // EnrichmentRunStore (+ enrichmentRunQueue) — async MCP enrichment runs
-  mintConnectLink,      // short connect links for opportunity accepts
-  modelConfig,          // override chat model / reasoning effort (see above)
+const registry = createToolRegistry(deps, { surface: "mcp" }); // omit `surface` for the full REST set
+
+const context = await resolveChatContext({
+  database,                 // the ChatGraphCompositeDatabase reads listed above
+  userId: "user-uuid",
+  networkId,                // optional — scopes tools to one network
+  sessionId,                // optional — enables draft opportunities
 });
 
-// tools is an array of LangChain Tool objects ready to bind to an agent
+const tool = registry.get("search_intents")!;
+const result = await invokeToolRuntime({
+  toolName: tool.name,
+  tool,
+  context,
+  query: { /* validated against tool.schema */ },
+});
 ```
 
-`createChatTools` accepts a single `ToolContext` object. The required adapters
-above are always needed; optional capabilities default to a degraded-but-
-functional mode when omitted (for example, without `agentDispatcher` the
-negotiation tools are not registered).
+The dependency object carries the required adapters listed above; optional
+capabilities default to a degraded-but-functional mode when omitted (for
+example, without `agentDispatcher` the negotiation tools are not registered).
+
+The per-capability tool factories behind these entry points
+(`createChatTools`, `createIntentTools`, `createNegotiationTools`, …) are
+package-internal as of 15.0.0 and are not part of the supported surface.
+`createEnrichmentTools` remains exported for hosts that run enrichment on its
+own worker, separately from the chat runtime.
 
 ## Graphs
 

package/STABILITY.md

@@ -30,13 +30,13 @@ Covered by SemVer below. Breaking changes require a **major** bump.
 
 | Barrel section | What it is |
 |---|---|
-| **Public API** | `createChatTools`, model config helpers, tool/runtime helpers (`ToolContext`, `ToolDeps`, `invokeToolRuntime`, …), `requestContext`. |
+| **Public API** | `createToolRegistry`, model config helpers, tool/runtime helpers (`ResolvedToolContext`, `ToolDeps`, `invokeToolRuntime`, …), `requestContext`. |
 | **Interfaces** | Every `*.interface.ts` port you implement to inject infrastructure (databases, embedder, cache, scraper, queues, integration, agent dispatcher, …). |
 | **Shared schemas** | Zod schemas + inferred types that cross the boundary (questions, identity, network-assignment, chat-context, …). |
 | **Graph factories** | `*GraphFactory` classes (`ChatGraphFactory`, `OpportunityGraphFactory`, `NegotiationGraphFactory`, …). |
 | **Agents** | Structured LLM agents (`UserContextGenerator`, `IndexNegotiator`, `OpportunityEvaluator`, …). |
-| **MCP** | `createMcpServer` and its supporting types. |
-| **Capability tools** | Named tool-factory entry points for Signals, Participant context, Communities, Opportunities, Negotiation, Questions, Participant agents, Contacts, and Integrations. |
+| **MCP** | `createMcpServer` plus the types needed to call it: `ScopedDepsFactory`, `McpCapabilityPolicyOptions`, `CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS`, `McpAuthorizationObserver`, `McpAuthorizationDenialEvent`. The rest of `mcp.authorization-policy.ts` is package-internal as of 15.0.0. |
+| **Capability tools** | `createEnrichmentTools` only. The other per-capability tool factories became package-internal in 15.0.0 — compose them through `createMcpServer` or `createToolRegistry`. |
 
 ### Experimental
 

package/dist/chat/chat.agent.js

@@ -204,7 +204,6 @@ export class ChatAgent {
             userId: context.userId,
             networkId: scopedNetworkId,
             sessionId: context.sessionId,
-            contactsEnabled: context.contactsEnabled,
             actionToolsEnabled: context.actionToolsEnabled,
         });
         if (explicitScope.scopeType && explicitScope.scopeId) {
@@ -327,8 +326,8 @@ export class ChatAgent {
             }
             try {
                 logger.verbose("Executing tool", { name: tc.name, args: tc.args });
-                let result = await tool.invoke(tc.args);
-                let resultStr = typeof result === "string" ? result : JSON.stringify(result);
+                const result = await tool.invoke(tc.args);
+                const resultStr = typeof result === "string" ? result : JSON.stringify(result);
                 logger.debug("Tool response", { name: tc.name, result: resultStr });
                 logger.verbose("Tool completed", {
                     name: tc.name,

package/dist/chat/chat.graph.d.ts

@@ -1,5 +1,6 @@
-import { BaseCheckpointSaver } from "@langchain/langgraph";
+import { BaseCheckpointSaver, type LangGraphRunnableConfig } from "@langchain/langgraph";
 import { BaseMessage } from "@langchain/core/messages";
+import { ChatGraphState } from "./chat.state.js";
 import type { ChatPersonaConfig } from "./chat.persona.js";
 import type { ChatGraphCompositeDatabase } from "../shared/interfaces/database.interface.js";
 import type { Embedder } from "../shared/interfaces/embedder.interface.js";
@@ -21,6 +22,16 @@ import type { ProtocolDeps } from "../shared/agent/tool.helpers.js";
  * with a flexible, LLM-driven approach that can handle multi-step
  * reasoning and self-correction.
  */
+/** The graph's channel state, as the agent loop sees it. */
+export type ChatState = typeof ChatGraphState.State;
+/** Everything the agent loop node reaches for. */
+export interface ChatGraphNodeDeps {
+    database: ChatGraphCompositeDatabase;
+    embedder: Embedder;
+    scraper: Scraper;
+    protocolDeps: ProtocolDeps;
+    persona: ChatPersonaConfig;
+}
 export declare class ChatGraphFactory {
     private database;
     private embedder;
@@ -382,3 +393,32 @@ export declare class ChatGraphFactory {
      */
     private buildGraph;
 }
+/**
+ * The main agent loop node.
+ * Runs a ReAct-style agent that calls tools until it decides to respond.
+ *
+ * Uses `agent.streamRun()` + `config.writer` so that text tokens and
+ * tool-activity events are pushed into the graph's custom stream in
+ * real-time rather than batched at the end.
+ */
+export declare function agentLoopNode(state: ChatState, config: LangGraphRunnableConfig, deps: ChatGraphNodeDeps): Promise<{
+    messages: BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>[];
+    responseText: string;
+    iterationCount: number;
+    shouldContinue: boolean;
+    debugMeta: {
+        graph: string;
+        iterations: number;
+        tools: import("./chat-streaming.types.js").DebugMetaToolCall[];
+        llm: import("./chat-streaming.types.js").DebugMetaLlm;
+        orchestratorNegotiations?: import("./chat-streaming.types.js").DebugMetaOrchestratorNegotiations;
+    };
+    error?: undefined;
+} | {
+    error: string;
+    responseText: string;
+    shouldContinue: boolean;
+    messages?: undefined;
+    iterationCount?: undefined;
+    debugMeta?: undefined;
+}>;