@indexnetwork/protocol 13.1.0-rc.465.1 → 13.2.1-rc.467.1

package/CHANGELOG.md

@@ -20,6 +20,55 @@ 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`.
 
+## 13.2.1 - 2026-08-16
+
+No public API change: all 441 exported symbols are byte-identical to 13.2.0, and
+`src/index.ts` is untouched. This is internal structure only.
+
+### Removed
+
+- Removed the IND-543 outer shells — `src/public/`, `src/platform/`,
+  `src/runtime/foreground/`, and `src/runtime/background/`. All four were
+  declaration-only placeholders with zero inbound imports; `runtime/background`
+  and `public` consisted of nothing but a header comment. The only thing
+  referencing them was a spec asserting that they existed.
+- Removed eight unused capability barrels (`signals/index.ts`,
+  `communities/index.ts`, `contacts/index.ts`, `questions/index.ts`,
+  `opportunity/index.ts`, `negotiation/index.ts`, `integrations/index.ts`,
+  `participant-agents/index.ts`). Each was `export * from "./public/index.js"`
+  with no importers — every real consumer already went to `public/` directly.
+- Removed `src/shared/ui/`, which contained no source, only a `tests/tsconfig.json`.
+- Removed the `ambient-background`, `neutral-platform`, and
+  `public-compatibility` capability classifications, which existed solely to
+  describe the deleted shells.
+
+### Changed
+
+- Resolved the tool-composition shim inversion. `tool.registry.ts` and
+  `tool.factory.ts` were implemented in `runtime/foreground/composition/` and
+  re-exported from `shared/agent/` through modules marked `@deprecated` — but
+  all 25 importers used the deprecated path. The implementations now live at
+  `shared/agent/tool.registry.ts` and `shared/agent/tool.factory.ts`, and the
+  indirection is gone. `mcp.server.ts` was the one direct consumer of the old
+  location and now resolves to the same single home.
+- `signals/application/intent.tools.ts` is imported directly by the tool
+  factory; the `runtime/foreground/signals/intent.tools.ts` pass-through
+  re-export that sat between them is removed.
+- Replaced `architecture/tests/runtime-shells.spec.ts` with
+  `architecture/tests/package-entry.spec.ts`, which asserts the invariants that
+  outlived the shells: `src/index.ts` is the sole `package.json` export, and the
+  tool composition root has exactly one implementation.
+
+## 13.2.0 - 2026-08-16
+
+### Added
+
+- `retired_mode` to `QuestionVoidedReasonSchema`, marking rows whose generating
+  mode was removed. Written only by the one-time
+  `0127_dismiss_retired_discovery_questions` migration — no runtime path emits
+  it, since a retired mode produces nothing by definition. The marker makes the
+  cleanup auditable and exactly reversible.
+
 ## 13.0.0 - 2026-08-13
 
 ### Removed

package/dist/communities/public/index.d.ts

@@ -4,10 +4,10 @@
  * Re-exports the stable contracts from domain, application, and ports.
  * Runtime adapter creation (graph factories, tool factories) is accessible
  * via capabilities/communities.facade.ts for package consumers and via the
- * foreground shell (runtime/foreground) for internal registries.
+ * tool composition root (shared/agent) for internal registries.
  *
  * Boundary: public-compatibility.  References only communities/domain,
- * communities/application, and communities/ports — never runtime/foreground
+ * communities/application, and communities/ports — never the tool composition root (shared/agent)
  * or host implementations.
  *
  * ## Intentionally excluded from public surface

package/dist/communities/public/index.js

@@ -4,10 +4,10 @@
  * Re-exports the stable contracts from domain, application, and ports.
  * Runtime adapter creation (graph factories, tool factories) is accessible
  * via capabilities/communities.facade.ts for package consumers and via the
- * foreground shell (runtime/foreground) for internal registries.
+ * tool composition root (shared/agent) for internal registries.
  *
  * Boundary: public-compatibility.  References only communities/domain,
- * communities/application, and communities/ports — never runtime/foreground
+ * communities/application, and communities/ports — never the tool composition root (shared/agent)
  * or host implementations.
  *
  * ## Intentionally excluded from public surface

package/dist/contacts/public/index.d.ts

@@ -8,7 +8,7 @@
  * ## Boundary
  *
  * References only contacts/domain, contacts/application, and contacts/ports.
- * Never imports from runtime/foreground, host implementations, or other
+ * Never imports from the tool composition root (shared/agent), host implementations, or other
  * capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/contacts/public/index.js

@@ -8,7 +8,7 @@
  * ## Boundary
  *
  * References only contacts/domain, contacts/application, and contacts/ports.
- * Never imports from runtime/foreground, host implementations, or other
+ * Never imports from the tool composition root (shared/agent), host implementations, or other
  * capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/integrations/public/index.d.ts

@@ -8,7 +8,7 @@
  * ## Boundary
  *
  * References only integrations/domain, integrations/application, and
- * integrations/ports. Never imports from runtime/foreground, host
+ * integrations/ports. Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/integrations/public/index.js

@@ -8,7 +8,7 @@
  * ## Boundary
  *
  * References only integrations/domain, integrations/application, and
- * integrations/ports. Never imports from runtime/foreground, host
+ * integrations/ports. Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/mcp/mcp.server.d.ts

@@ -8,7 +8,7 @@ import { McpServer, fromJsonSchema } from '@modelcontextprotocol/server';
 import type { JsonSchemaType } from '@modelcontextprotocol/server';
 import type { McpAuthResolver } from '../shared/interfaces/auth.interface.js';
 import type { ToolDeps, ResolvedToolContext, RawToolDefinition } from '../shared/agent/tool.helpers.js';
-import type { ToolRegistryDeps } from '../runtime/foreground/composition/tool.registry.js';
+import type { ToolRegistryDeps } from '../shared/agent/tool.registry.js';
 import type { McpAuthorizationObserver, McpCapabilityPolicyOptions } from './mcp.authorization-policy.js';
 /**
  * Static registration metadata for one MCP tool — schema conversion artifacts

package/dist/mcp/mcp.server.js

@@ -10,7 +10,7 @@ import { McpResolvedIdentitySchema } from '../shared/schemas/mcp-auth.schema.js'
 import { CANONICAL_GUIDANCE_SUMMARY } from '../shared/agent/canonical-guidance.js';
 import { resolveChatContext } from '../shared/agent/tool.helpers.js';
 import { deriveAllowedNetworkIds, scopeFromNetworkId } from '../shared/agent/tool.scope.js';
-import { createToolRegistry } from '../runtime/foreground/composition/tool.registry.js';
+import { createToolRegistry } from '../shared/agent/tool.registry.js';
 import { bindOwnerApprovalProvenance } from '../opportunity/application/opportunity.owner-provenance.js';
 import { ToolRuntimeError, invokeToolRuntime, toolRuntimeErrorToResult } from '../shared/agent/tool.runtime.js';
 import { protocolLogger } from '../shared/observability/protocol.logger.js';

package/dist/negotiation/public/index.d.ts

@@ -6,7 +6,7 @@
  * ## Boundary
  *
  * References only negotiation/domain, negotiation/application, and
- * negotiation/ports. Never imports from runtime/foreground, host
+ * negotiation/ports. Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/negotiation/public/index.js

@@ -6,7 +6,7 @@
  * ## Boundary
  *
  * References only negotiation/domain, negotiation/application, and
- * negotiation/ports. Never imports from runtime/foreground, host
+ * negotiation/ports. Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/participant-agents/public/index.d.ts

@@ -9,7 +9,7 @@
  * ## Boundary
  *
  * References only participant-agents/domain, participant-agents/application,
- * and participant-agents/ports.  Never imports from runtime/foreground, host
+ * and participant-agents/ports.  Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/participant-agents/public/index.js

@@ -9,7 +9,7 @@
  * ## Boundary
  *
  * References only participant-agents/domain, participant-agents/application,
- * and participant-agents/ports.  Never imports from runtime/foreground, host
+ * and participant-agents/ports.  Never imports from the tool composition root (shared/agent), host
  * implementations, or other capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/participant-context/application/index.js

@@ -64,7 +64,7 @@ export { EnrichmentGraphFactory, } from "../../enrichment/enrichment.graph.js";
 export { EnrichmentGenerator } from "../../enrichment/enrichment.generator.js";
 export { shouldEnrichGhostDisplayNameFromParallel, isEnrichedNameMeaningful, } from "../../enrichment/enrichment.enricher.js";
 // ── Tool factories (foreground adapters) ──────────────────────────────────────
-// These are foreground adapter entry points consumed by runtime/foreground
+// These are foreground adapter entry points consumed by the tool composition root (shared/agent)
 // composition.  They accept compiled graphs and host deps through the tool-dep
 // ports and produce LangChain-compatible tool arrays.
 export { createEnrichmentTools } from "../../enrichment/enrichment.tools.js";

package/dist/participant-context/domain/index.d.ts

@@ -46,7 +46,7 @@
  * ## Policy separation
  *
  * - **Foreground adapters** (onboarding preview/confirm, explicit enrichment):
- *   managed by the foreground shell (runtime/foreground). They compose the
+ *   managed by the tool composition root (shared/agent). They compose the
  *   EnrichmentGraphFactory and PremiseGraphFactory and pass the compiled graphs
  *   through the tool-dependency ports.
  * - **Ambient adapters** (scrape/decompose, regeneration, indexing, representation

package/dist/participant-context/domain/index.js

@@ -46,7 +46,7 @@
  * ## Policy separation
  *
  * - **Foreground adapters** (onboarding preview/confirm, explicit enrichment):
- *   managed by the foreground shell (runtime/foreground). They compose the
+ *   managed by the tool composition root (shared/agent). They compose the
  *   EnrichmentGraphFactory and PremiseGraphFactory and pass the compiled graphs
  *   through the tool-dependency ports.
  * - **Ambient adapters** (scrape/decompose, regeneration, indexing, representation

package/dist/participant-context/public/index.d.ts

@@ -4,11 +4,11 @@
  * Re-exports the stable contracts from domain, application, and ports.
  * Runtime adapter creation (graph factories, tool factories) is accessible via
  * capabilities/participant-context.facade for package consumers and via
- * the foreground shell (runtime/foreground) for internal registries.
+ * the tool composition root (shared/agent) for internal registries.
  *
  * Boundary: public-compatibility.  References only participant-context/domain,
  * participant-context/application, and participant-context/ports — never
- * runtime/foreground or host implementations.
+ * the tool composition root (shared/agent) or host implementations.
  *
  * ## Intentionally excluded from public surface
  *

package/dist/participant-context/public/index.js

@@ -4,11 +4,11 @@
  * Re-exports the stable contracts from domain, application, and ports.
  * Runtime adapter creation (graph factories, tool factories) is accessible via
  * capabilities/participant-context.facade for package consumers and via
- * the foreground shell (runtime/foreground) for internal registries.
+ * the tool composition root (shared/agent) for internal registries.
  *
  * Boundary: public-compatibility.  References only participant-context/domain,
  * participant-context/application, and participant-context/ports — never
- * runtime/foreground or host implementations.
+ * the tool composition root (shared/agent) or host implementations.
  *
  * ## Intentionally excluded from public surface
  *

package/dist/questions/domain/question.schema.d.ts

@@ -730,7 +730,7 @@ export declare const QuestionRecoverySnapshotSchema: z.ZodObject<{
     rejectedNegotiationCount?: number | undefined;
 }>;
 /** Internal reason a pending question was voided. */
-export declare const QuestionVoidedReasonSchema: z.ZodEnum<["pool_drift", "intent_edit", "recovery_drift", "negotiation_stale"]>;
+export declare const QuestionVoidedReasonSchema: z.ZodEnum<["pool_drift", "intent_edit", "recovery_drift", "negotiation_stale", "retired_mode"]>;
 /** Permanent reasons that terminalize an unclaimed proactive push request. */
 export declare const QuestionPoolPushRequestReasonSchema: z.ZodEnum<["question_lifecycle", "intent_lifecycle", "malformed_source", "malformed_actor", "malformed_pool", "malformed_cycle", "visited", "pool_size", "voi", "cycle_budget"]>;
 export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
@@ -1117,7 +1117,7 @@ export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
         failure?: string | undefined;
     }>>;
     /** Internal reason this question was voided after pool or intent drift. */
-    voidedReason: z.ZodOptional<z.ZodEnum<["pool_drift", "intent_edit", "recovery_drift", "negotiation_stale"]>>;
+    voidedReason: z.ZodOptional<z.ZodEnum<["pool_drift", "intent_edit", "recovery_drift", "negotiation_stale", "retired_mode"]>>;
     /** Authoritative successful-delivery ledger timestamp. Internal only. */
     pushedAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -1212,7 +1212,7 @@ export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
     pushRequestStatus?: "suppressed" | "requested" | undefined;
     pushRequestReason?: "voi" | "question_lifecycle" | "intent_lifecycle" | "malformed_source" | "malformed_actor" | "malformed_pool" | "malformed_cycle" | "visited" | "pool_size" | "cycle_budget" | undefined;
     pushRequestSuppressedAt?: string | undefined;
-    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | undefined;
+    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | "retired_mode" | undefined;
     pushedAt?: string | undefined;
 }, {
     mode: "chat" | "intent" | "negotiation" | "negotiation_inflight" | "pool_discovery";
@@ -1306,7 +1306,7 @@ export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
     pushRequestStatus?: "suppressed" | "requested" | undefined;
     pushRequestReason?: "voi" | "question_lifecycle" | "intent_lifecycle" | "malformed_source" | "malformed_actor" | "malformed_pool" | "malformed_cycle" | "visited" | "pool_size" | "cycle_budget" | undefined;
     pushRequestSuppressedAt?: string | undefined;
-    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | undefined;
+    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | "retired_mode" | undefined;
     pushedAt?: string | undefined;
 }>, {
     mode: "chat" | "intent" | "negotiation" | "negotiation_inflight" | "pool_discovery";
@@ -1400,7 +1400,7 @@ export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
     pushRequestStatus?: "suppressed" | "requested" | undefined;
     pushRequestReason?: "voi" | "question_lifecycle" | "intent_lifecycle" | "malformed_source" | "malformed_actor" | "malformed_pool" | "malformed_cycle" | "visited" | "pool_size" | "cycle_budget" | undefined;
     pushRequestSuppressedAt?: string | undefined;
-    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | undefined;
+    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | "retired_mode" | undefined;
     pushedAt?: string | undefined;
 }, {
     mode: "chat" | "intent" | "negotiation" | "negotiation_inflight" | "pool_discovery";
@@ -1494,7 +1494,7 @@ export declare const QuestionDetectionSchema: z.ZodEffects<z.ZodObject<{
     pushRequestStatus?: "suppressed" | "requested" | undefined;
     pushRequestReason?: "voi" | "question_lifecycle" | "intent_lifecycle" | "malformed_source" | "malformed_actor" | "malformed_pool" | "malformed_cycle" | "visited" | "pool_size" | "cycle_budget" | undefined;
     pushRequestSuppressedAt?: string | undefined;
-    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | undefined;
+    voidedReason?: "pool_drift" | "intent_edit" | "recovery_drift" | "negotiation_stale" | "retired_mode" | undefined;
     pushedAt?: string | undefined;
 }>;
 export declare const QuestionActorSchema: z.ZodObject<{

package/dist/questions/domain/question.schema.js

@@ -262,6 +262,10 @@ export const QuestionVoidedReasonSchema = z.enum([
     "intent_edit",
     "recovery_drift",
     "negotiation_stale",
+    // The generator that produced the row was retired, so the question can no
+    // longer lead anywhere. Written once by a one-time migration, never by
+    // runtime code — nothing produces a retired mode by definition.
+    "retired_mode",
 ]);
 /** Permanent reasons that terminalize an unclaimed proactive push request. */
 export const QuestionPoolPushRequestReasonSchema = z.enum([

package/dist/questions/public/index.d.ts

@@ -9,7 +9,7 @@
  * ## Boundary
  *
  * References only questions/domain, questions/application, and questions/ports.
- * Never imports from runtime/foreground, host implementations, or other
+ * Never imports from the tool composition root (shared/agent), host implementations, or other
  * capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/questions/public/index.js

@@ -9,7 +9,7 @@
  * ## Boundary
  *
  * References only questions/domain, questions/application, and questions/ports.
- * Never imports from runtime/foreground, host implementations, or other
+ * Never imports from the tool composition root (shared/agent), host implementations, or other
  * capability internals.
  *
  * ## Intentionally excluded from public surface

package/dist/shared/agent/tool.factory.d.ts

@@ -1,6 +1,17 @@
+import { type ToolContext, type ResolvedToolContext } from "./tool.helpers.js";
+import type { OpportunityOwnerApprovalDeps } from "../../opportunity/ports/opportunity.tools.port.js";
+export type { ToolContext, ResolvedToolContext, ProtocolDeps } from "./tool.helpers.js";
+export type { ToolDeps } from "./tool.helpers.js";
 /**
- * @deprecated Canonical location: runtime/foreground/composition/tool.factory
- * Retained for backward compatibility during IND-544 migration.
- * Import createChatTools from @indexnetwork/protocol instead.
+ * Creates all chat tools bound to a specific user context.
+ * Resolves user/network identity from DB at init time.
+ * Tools are created fresh for each user session to ensure proper isolation.
+ *
+ * All external dependencies (cache, integration, queue, etc.) are provided
+ * via the `deps` parameter — the protocol lib never imports concrete adapters.
  */
-export { createChatTools, type ChatTools, type ToolContext, type ResolvedToolContext, type ProtocolDeps, type ToolDeps, } from "../../runtime/foreground/composition/tool.factory.js";
+export declare function createChatTools(deps: ToolContext & OpportunityOwnerApprovalDeps, preResolvedContext?: ResolvedToolContext): Promise<any[]>;
+/**
+ * Type for the tools array returned by createChatTools.
+ */
+export type ChatTools = Awaited<ReturnType<typeof createChatTools>>;

package/dist/shared/agent/tool.factory.js

@@ -1,6 +1,235 @@
+import { tool } from "@langchain/core/tools";
+import { IntentGraphFactory } from "../../signals/application/intent.graph.js";
+import { EnrichmentGraphFactory } from "../../enrichment/enrichment.graph.js";
+import { OpportunityGraphFactory } from "../../capabilities/opportunities.facade.js";
+import { HydeGraphFactory } from "../hyde/hyde.graph.js";
+import { HydeGenerator } from "../hyde/hyde.generator.js";
+import { LensInferrer } from "../hyde/lens.inferrer.js";
+import { NetworkGraphFactory, NetworkMembershipGraphFactory, IntentNetworkGraphFactory } from "../../capabilities/communities.facade.js";
+import { IntentIndexer } from "../../signals/application/intent.indexer.js";
+import { NegotiationGraphFactory } from "../../capabilities/negotiation.facade.js";
+import { PremiseGraphFactory } from "../../premise/premise.graph.js";
+import { protocolLogger } from "../observability/protocol.logger.js";
+import { resolveChatContext, error, redactSensitiveFields } from "./tool.helpers.js";
+import { deriveAllowedNetworkIds, focusedIntentId, scopeFromNetworkId } from "./tool.scope.js";
+import { invokeToolRuntime, toolRuntimeErrorToResult } from "./tool.runtime.js";
+import { createEnrichmentTools } from "../../enrichment/enrichment.tools.js";
+import { createIntentTools } from "../../signals/application/intent.tools.js";
+import { createNetworkTools } from "../../capabilities/communities.facade.js";
+import { createOpportunityTools } from "../../capabilities/opportunities.facade.js";
+import { createUtilityTools } from "./utility.tools.js";
+import { createIntegrationTools } from "../../capabilities/integrations.facade.js";
+import { createContactTools } from "../../capabilities/contacts.facade.js";
+import { createAgentTools } from "../../capabilities/participant-agents.tools.facade.js";
+import { createNegotiationTools } from "../../capabilities/negotiation.facade.js";
+import { createPremiseTools } from "../../premise/premise.tools.js";
+import { createQuestionerTools, createAskUserQuestionTools } from "../../capabilities/questions.facade.js";
+import { bindOwnerApprovalProvenance } from "../../opportunity/application/opportunity.owner-provenance.js";
+const logger = protocolLogger("ChatTools");
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL FACTORY
+// ═══════════════════════════════════════════════════════════════════════════════
 /**
- * @deprecated Canonical location: runtime/foreground/composition/tool.factory
- * Retained for backward compatibility during IND-544 migration.
- * Import createChatTools from @indexnetwork/protocol instead.
+ * Creates all chat tools bound to a specific user context.
+ * Resolves user/network identity from DB at init time.
+ * Tools are created fresh for each user session to ensure proper isolation.
+ *
+ * All external dependencies (cache, integration, queue, etc.) are provided
+ * via the `deps` parameter — the protocol lib never imports concrete adapters.
  */
-export { createChatTools, } from "../../runtime/foreground/composition/tool.factory.js";
+export async function createChatTools(deps, preResolvedContext) {
+    const { database, embedder, scraper } = deps;
+    const explicitScope = deps.scopeType && deps.scopeId
+        ? { scopeType: deps.scopeType, scopeId: deps.scopeId }
+        : scopeFromNetworkId(deps.networkId);
+    // ─── Resolve context from DB ───────────────────────────────────────────────
+    // resolveChatContext still accepts a networkId because it loads scoped index
+    // presentation metadata; the canonical request scope is explicitScope.
+    const resolvedContext = preResolvedContext ??
+        (await resolveChatContext({
+            database,
+            userId: deps.userId,
+            networkId: explicitScope.scopeType === 'network' ? explicitScope.scopeId : deps.networkId,
+            sessionId: deps.sessionId,
+            contactsEnabled: deps.contactsEnabled,
+            actionToolsEnabled: deps.actionToolsEnabled,
+        }));
+    if (!preResolvedContext && explicitScope.scopeType && explicitScope.scopeId) {
+        resolvedContext.scopeType = explicitScope.scopeType;
+        resolvedContext.scopeId = explicitScope.scopeId;
+    }
+    // This factory is an orchestrated chat surface, never a direct owner request.
+    // Bind that fact at composition time rather than inferring it from a session
+    // id or a caller-controlled tool argument inside the opportunity handler.
+    bindOwnerApprovalProvenance(resolvedContext, {
+        surface: 'chat',
+        sessionAuthenticated: false,
+    });
+    const allowedNetworkIds = deriveAllowedNetworkIds({
+        memberships: resolvedContext.userNetworks,
+        ...(resolvedContext.scopeType && resolvedContext.scopeId
+            ? { scopeType: resolvedContext.scopeType, scopeId: resolvedContext.scopeId }
+            : {}),
+    });
+    // ─── Tool wrapper ──────────────────────────────────────────────────────────
+    /**
+     * Standardized tool factory. Auto-injects resolved context and
+     * provides uniform logging / error handling for every tool.
+     */
+    function defineTool(opts) {
+        return tool(async (query) => {
+            logger.info('Tool invoked', {
+                toolName: opts.name,
+                context: { userId: resolvedContext.userId, scopeType: resolvedContext.scopeType, scopeId: resolvedContext.scopeId },
+                query: redactSensitiveFields(query),
+            });
+            try {
+                return await invokeToolRuntime({
+                    toolName: opts.name,
+                    tool: { handler: async ({ context, query }) => opts.handler({ context, query: query }) },
+                    context: resolvedContext,
+                    query,
+                });
+            }
+            catch (err) {
+                logger.error('Tool failed', {
+                    toolName: opts.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                const runtimeResult = toolRuntimeErrorToResult(err);
+                if (runtimeResult)
+                    return runtimeResult;
+                const reason = err instanceof Error ? err.message : String(err);
+                return error(`Failed to execute ${opts.name}: ${reason}`);
+            }
+        }, { name: opts.name, description: opts.description, schema: opts.querySchema });
+    }
+    // ─── Compile subgraphs ─────────────────────────────────────────────────────
+    // Wrap questionerEnqueue to include scoped/session context when available.
+    const sessionAwareEnqueue = deps.questionerEnqueue
+        ? (input) => deps.questionerEnqueue({
+            ...input,
+            ...(resolvedContext.scopeType && resolvedContext.scopeId && !input.scopeId
+                ? { scopeType: resolvedContext.scopeType, scopeId: resolvedContext.scopeId }
+                : {}),
+            ...(resolvedContext.sessionId && !input.conversationId ? { conversationId: resolvedContext.sessionId } : {}),
+        })
+        : undefined;
+    const intentGraph = new IntentGraphFactory(database, embedder, deps.intentQueue, sessionAwareEnqueue).createGraph();
+    const premiseGraph = new PremiseGraphFactory(database, embedder).createGraph();
+    const profileGraph = new EnrichmentGraphFactory(database, scraper, deps.enricher, premiseGraph).createGraph();
+    const hydeCache = deps.hydeCache;
+    const lensInferrer = new LensInferrer();
+    const hydeGenerator = new HydeGenerator();
+    const compiledHydeGraph = new HydeGraphFactory(database, embedder, hydeCache, lensInferrer, hydeGenerator).createGraph();
+    const negotiationGraph = deps.agentDispatcher
+        ? new NegotiationGraphFactory(deps.negotiationDatabase, deps.agentDispatcher, deps.negotiationTimeoutQueue, sessionAwareEnqueue).createGraph()
+        : undefined;
+    const opportunityGraph = new OpportunityGraphFactory(database, embedder, compiledHydeGraph, undefined, // evaluator (default)
+    undefined, // queueNotification
+    negotiationGraph, deps.agentDispatcher, deps.queueNegotiateExisting, deps.stampNewbornOpportunities).createGraph();
+    const networkGraph = new NetworkGraphFactory(database).createGraph();
+    const networkMembershipGraph = new NetworkMembershipGraphFactory(database).createGraph();
+    const intentNetworkGraph = new IntentNetworkGraphFactory(database, new IntentIndexer()).createGraph();
+    // ─── Create context-bound databases ────────────────────────────────────────
+    // Use injected instances when provided (e.g. tests). Otherwise create from the same
+    // database used for graphs so that scope checks (e.g. ensureScopedMembership, opportunity
+    // update) use the same adapter as the rest of the tool pipeline.
+    //
+    // The systemDb's DB-level clamp derives concrete allowed network IDs from the
+    // focused scope envelope plus memberships, rather than consuming a transported
+    // legacy indexScope array.
+    const userDb = deps.userDb ?? deps.createUserDatabase(database, resolvedContext.userId);
+    const systemDb = deps.systemDb ?? deps.createSystemDatabase(database, resolvedContext.userId, allowedNetworkIds, embedder);
+    // ─── Assemble dependencies ─────────────────────────────────────────────────
+    const cache = deps.cache;
+    const integration = deps.integration;
+    const toolDeps = {
+        database,
+        userDb,
+        systemDb,
+        scraper,
+        embedder,
+        cache,
+        integration,
+        contactService: deps.contactService,
+        contactsEnabled: deps.contactsEnabled,
+        integrationImporter: deps.integrationImporter,
+        enricher: deps.enricher,
+        negotiationDatabase: deps.negotiationDatabase,
+        negotiationTimeoutQueue: deps.negotiationTimeoutQueue,
+        agentDatabase: deps.agentDatabase,
+        grantDefaultSystemPermissions: deps.grantDefaultSystemPermissions,
+        agentDispatcher: deps.agentDispatcher,
+        stampNewbornOpportunities: deps.stampNewbornOpportunities,
+        deliveryLedger: deps.deliveryLedger,
+        ...(deps.opportunityOwnerApproval && { opportunityOwnerApproval: deps.opportunityOwnerApproval }),
+        enrichmentRuns: deps.enrichmentRuns,
+        enrichmentRunQueue: deps.enrichmentRunQueue,
+        frontendUrl: deps.frontendUrl,
+        apiBaseUrl: deps.apiBaseUrl,
+        ...(deps.chatSummary && { chatSummary: deps.chatSummary }),
+        ...(sessionAwareEnqueue && { questionerEnqueue: sessionAwareEnqueue }),
+        ...(deps.findPendingQuestions && { findPendingQuestions: deps.findPendingQuestions }),
+        ...(deps.answerPendingQuestion && { answerPendingQuestion: deps.answerPendingQuestion }),
+        ...(deps.negotiationSummary && { negotiationSummary: deps.negotiationSummary }),
+        ...(deps.chatQuestions && { chatQuestions: deps.chatQuestions }),
+        ...(deps.chatSession && { chatSession: deps.chatSession }),
+        ...(deps.getUserContextText && { getUserContextText: deps.getUserContextText }),
+        ...(deps.intentProposalStore && { intentProposalStore: deps.intentProposalStore }),
+        graphs: {
+            profile: profileGraph,
+            intent: intentGraph,
+            index: networkGraph,
+            networkMembership: networkMembershipGraph,
+            intentIndex: intentNetworkGraph,
+            opportunity: opportunityGraph,
+            premise: premiseGraph,
+        },
+    };
+    // ─── Create domain tools ──────────────────────────────────────────────────
+    const profileTools = createEnrichmentTools(defineTool, toolDeps);
+    const intentTools = createIntentTools(defineTool, toolDeps);
+    // An intent-scoped conversation exists to refine its selected signal. Keep
+    // creation out of the model-visible registry; the update handler separately
+    // clamps writes to the exact scoped intent as a runtime backstop.
+    const intentToolsForChat = focusedIntentId(resolvedContext)
+        ? intentTools.filter((candidate) => candidate.name !== "create_intent")
+        : intentTools;
+    const networkTools = createNetworkTools(defineTool, toolDeps);
+    const opportunityTools = createOpportunityTools(defineTool, toolDeps);
+    const utilityTools = createUtilityTools(defineTool, toolDeps);
+    const contactTools = createContactTools(defineTool, toolDeps);
+    const agentTools = createAgentTools(defineTool, toolDeps);
+    const integrationTools = createIntegrationTools(defineTool, toolDeps);
+    const negotiationTools = deps.agentDispatcher
+        ? createNegotiationTools(defineTool, toolDeps)
+        : [];
+    const premiseTools = createPremiseTools(defineTool, toolDeps);
+    const questionerTools = createQuestionerTools(defineTool, toolDeps);
+    // Blocking mid-conversation questions — chat-only (never in the MCP registry),
+    // and only when the host provides the ChatQuestionsHost bridge.
+    const askUserQuestionTools = deps.chatQuestions
+        ? createAskUserQuestionTools(defineTool, toolDeps)
+        : [];
+    // confirm_opportunity_delivery is an OpenClaw-delivery ledger write and must not be
+    // callable from regular chat sessions.
+    const chatOpportunityToolExclusions = new Set([
+        "confirm_opportunity_delivery",
+    ]);
+    const opportunityToolsForChat = opportunityTools.filter((t) => !chatOpportunityToolExclusions.has(t.name));
+    return [
+        ...profileTools,
+        ...intentToolsForChat,
+        ...networkTools,
+        ...opportunityToolsForChat,
+        ...utilityTools,
+        ...integrationTools,
+        ...contactTools,
+        ...agentTools,
+        ...negotiationTools,
+        ...premiseTools,
+        ...questionerTools,
+        ...askUserQuestionTools,
+    ];
+}