@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0-rc.604.2

package/dist/shared/agent/utility.tools.js

@@ -1,322 +0,0 @@
-import { z } from "zod";
-import { requestContext } from "../observability/request-context.js";
-import { ActivitySummaryResponseSchema, McpActivityCallerSchema, activitySummaryNetworkId, projectActivitySummary } from "./activity-projection.js";
-import { CANONICAL_GUIDANCE_SUMMARY, CANONICAL_GUIDANCE_TOPICS, CANONICAL_GUIDANCE_TOPICS_CONTENT } from "./canonical-guidance.js";
-import { success, error, normalizeUrl } from "./tool.helpers.js";
-/** Owner-trusted surfaces (REST/chat) receive the full owner view. */
-const HUMAN_OWNER_CALLER = {
-    kind: "human",
-    permissions: [],
-    networkScopeId: null,
-};
-export function createUtilityTools(defineTool, deps, options = {}) {
-    const { scraper } = deps;
-    const isMcpSurface = options.surface === "mcp";
-    // scrape_url is omitted from the MCP tool surface (IND-597). It remains
-    // available via the direct HTTP Tool API and the chat agent.
-    const scrapeUrl = isMcpSurface ? null : defineTool({
-        name: "scrape_url",
-        description: "Extracts text content from a web URL — articles, LinkedIn/GitHub profiles, documentation, project pages, etc. " +
-            "Returns the page's text content (up to 10,000 characters) for use in subsequent tool calls.\n\n" +
-            "**When to use:**\n" +
-            "- Before create_intent: when the user shares a URL and wants to create an intent from it. Scrape first, then synthesize into a description.\n" +
-            "- Before create_user_context or update_user_context: when the user shares a profile URL to update their profile from.\n" +
-            "- When the user asks about content at a URL.\n\n" +
-            "**URL format:** Bare domains work fine (e.g. 'github.com/user/repo') — protocol (https://) is added automatically.\n\n" +
-            "**Returns:** `{ url, contentLength, content }`. Content is truncated at 10,000 chars. " +
-            "Returns an error if the URL is unreachable, requires login, or has no extractable text.",
-        querySchema: z.object({
-            url: z.string().describe("The URL to extract content from. Protocol is optional — 'github.com/user/repo', 'linkedin.com/in/name', and 'https://example.com' all work."),
-            objective: z.string().optional().describe("Why you're scraping — guides content extraction for better results. Examples: 'User wants to create an intent from this project page', 'User wants to update their profile from this LinkedIn page', 'Extract key information about this company'. Omit for generic text extraction."),
-        }),
-        handler: async ({ context: _context, query }) => {
-            const normalizedUrl = normalizeUrl(query.url);
-            if (!normalizedUrl) {
-                return error("Invalid URL format. Please provide a valid URL (e.g. 'github.com/user/repo' or 'https://example.com').");
-            }
-            const content = await scraper.extractUrlContent(normalizedUrl, {
-                objective: query.objective?.trim() || undefined,
-                signal: requestContext.getStore()?.abortSignal,
-            });
-            if (!content) {
-                return error("Couldn't extract content from that URL. It may be blocked, require login, or have no extractable text.");
-            }
-            const truncatedContent = content.length > 10000
-                ? content.substring(0, 10000) + "\n\n[Content truncated...]"
-                : content;
-            return success({
-                url: normalizedUrl,
-                contentLength: content.length,
-                content: truncatedContent,
-            });
-        },
-    });
-    const readDocs = defineTool({
-        name: "read_docs",
-        description: "Returns comprehensive documentation about the Index Network protocol — entity model, workflows, tool usage guidance, and domain concepts. " +
-            "This is the primary way for an external agent to bootstrap understanding of the system.\n\n" +
-            "**When to use:** Call this FIRST when starting a new session.\n" +
-            "Also call when you need to understand identity, context, premises, signals, communities, networks, opportunities, or negotiations.\n\n" +
-            "**Returns:** Markdown documentation. Pass `topic` to get a specific section, or omit for the summary.\n\n" +
-            `**Available canonical topics:** ${CANONICAL_GUIDANCE_TOPICS.join(", ")}`,
-        querySchema: z.object({
-            topic: z.string().optional().describe(`Narrow to a canonical topic: ${CANONICAL_GUIDANCE_TOPICS.join(", ")}. Omit to get the summary.`),
-        }),
-        handler: async ({ context: _context, query }) => {
-            const topic = query.topic?.trim().toLowerCase();
-            // Canonical guidance is the MCP read_docs foundation. When on MCP surface,
-            // legacy supplemental topics (entities, intents, opportunities, etc.) are
-            // omitted to avoid repeating the canonical source (IND-602/603).
-            // REST/chat surfaces retain full topic coverage for backwards compatibility.
-            if (isMcpSurface) {
-                // MCP surface: use canonical guidance only.
-                if (!topic) {
-                    // Return summary of canonical guidance
-                    return success({ content: CANONICAL_GUIDANCE_SUMMARY });
-                }
-                // Try to match canonical topic
-                const normalizedTopic = topic.replace(/_/g, "-").toLowerCase();
-                for (const canonicalTopic of CANONICAL_GUIDANCE_TOPICS) {
-                    if (canonicalTopic === normalizedTopic || normalizedTopic.includes(canonicalTopic.split("-")[0])) {
-                        return success({ topic: canonicalTopic, content: CANONICAL_GUIDANCE_TOPICS_CONTENT[canonicalTopic] });
-                    }
-                }
-                // Unknown topic on MCP surface
-                return success({
-                    content: `Unknown canonical topic "${topic}". Available topics: ${CANONICAL_GUIDANCE_TOPICS.join(", ")}. Request summary for full canonical guidance.`,
-                });
-            }
-            // REST/chat surfaces: provide full legacy documentation alongside canonical.
-            // Contact management tools are not exposed on the MCP surface (IND-596), so
-            // full guidance includes contact workflows. This is for REST/chat only.
-            const contactsSection = `## Contact Management
-
-Contacts are people in a user's personal network, stored as members of their personal network with 'contact' permission.
-
-- **How contacts arise**: Accepting an opportunity puts both people in each other's personal network. There is no import or manual-add path.
-- **Personal network scope**: Approved signals from personal-network contacts are matched in the background. Use list_opportunities only to review persisted results.
-- **Contact data**: Each contact has userId, name, email, and avatar.
-
-### Contact Workflow
-1. list_contacts → view all contacts with userId
-2. create_intent or update_intent → create or refine an approved signal for background matching
-3. list_opportunities → review persisted results when background processing finds matches
-4. remove_contact(contactUserId) → remove from network`;
-            const managingContactsWorkflow = `### Managing Contacts
-1. list_contacts() → view network
-2. create_intent or update_intent → create or refine an approved signal for background matching
-3. list_opportunities → review persisted results
-
-`;
-            const sections = {
-                // Legacy topics (REST/chat only)
-                entities: `## Entity Model & Relationships
-
-- **Users**: People on the platform. Authenticated via API key (X-API-Key header) for MCP/external agents, or session-based (Better Auth) for the web app.
-- **Profiles**: A user's identity — name, bio, skills, interests, location, social links. Generated from account data or social URLs via enrichment. One profile per user.
-- **Indexes** (also called "networks"): Communities or groups where members share intents and discover opportunities. Each has a title, optional prompt (purpose description), join policy (anyone or invite_only), and an owner. The user's **personal network** (isPersonal=true) stores their contacts.
-- **Network Members**: Junction between Users and Indexes. Tracks permissions (owner, member, contact), join date, auto-assign setting, and optional member prompt.
-- **Intents**: Signals of interest/need — what a user is looking for (e.g. "Looking for a React developer in Berlin"). Each has a description (payload), summary, confidence score (0-1), inferenceType (explicit/implicit), source tracking, and vector embedding.
-- **IntentNetworks**: Many-to-many junction between Intents and Indexes. An intent can be in multiple indexes. Has a relevancyScore (0-1) indicating how well the intent fits the index's purpose.
-- **Opportunities**: Discovered connections between users based on complementary intents within shared networks. Have actors with roles (introducer, party), status lifecycle, match reasoning, confidence score, and presentation data.
-- **Contacts**: People in a user's personal network, stored as network members with 'contact' permission on the personal network. Established by accepting an opportunity, which adds both people to each other's personal network. Always real accounts.
-
-### Key Relationships
-- Users → Profiles (1:1)
-- Users → Indexes (many:many via Network Members)
-- Users → Intents (1:many, user owns intents)
-- Intents → Indexes (many:many via IntentNetworks with relevancyScore)
-- Opportunities → Users (many:many via actors with roles)
-- Opportunities → Indexes (scoped to shared network context)
-- Contacts → Personal Network (stored as members with 'contact' permission)`,
-                intents: `## Intent Lifecycle
-
-Intents are the core unit of discovery — they represent what users are seeking and drive semantic matching.
-
-1. **Creation** (create_intent): User describes what they're looking for. The system runs inference (extracting structured intents from free text) and verification (checking specificity, speech-act type). Returns a proposal for user approval.
-2. **Confidence & Classification**: Each intent gets a confidence score (0-1), inferenceType (explicit = user stated directly, implicit = system inferred), and speech act classification (commissive, directive, assertive).
-3. **Index Assignment**: After creation, the intent is automatically evaluated against all networks the user belongs to. The index's prompt is used as criteria. Matching indexes get linked via IntentNetworks with a relevancyScore (0-1).
-4. **Discovery Trigger**: Creating an intent triggers background opportunity detection — the system searches for other users in shared networks whose intents complement this one.
-5. **Source Tracking**: Intents track their origin via sourceType (file, integration, link, discovery_form, enrichment) and sourceId.
-6. **Update** (update_intent): Re-processes through inference/verification, recalculates embeddings and index assignments.
-7. **Archive** (delete_intent): Soft-deletes the intent. It stops participating in discovery but is not permanently removed.
-
-### Intent Best Practices
-- Be specific: "Looking for a senior React developer for a 3-month contract in Berlin" > "Need a developer"
-- One intent per need: don't combine multiple requests into one intent
-- Update rather than delete+create to preserve history`,
-                opportunities: `## Opportunity Lifecycle
-
-Opportunities represent discovered connections between users — potential matches worth pursuing.
-
-1. **Background matching**: The opportunity graph evaluates approved signals whose intents semantically complement each other within shared networks. It uses HyDE embeddings for retrieval and an LLM evaluator for scoring.
-2. **Roles**: Each opportunity assigns roles to actors:
-   - **introducer**: The person who triggered the introduction (may be the system or another user)
-   - **party**: The people being connected (typically 2)
-3. **Status Flow**: draft → pending → accepted/rejected/expired
-   - **draft**: Created but not sent. Only the creator/introducer sees it.
-   - **pending**: Sent to the other party. They're notified and can respond.
-   - **accepted**: Both parties agreed to connect.
-   - **rejected**: One party declined.
-   - **expired**: Timed out without response.
-4. **Creation**: Opportunities are created by background matching after approved signals are created or refined. list_opportunities only reviews persisted cards; it never starts matching or targets a person.
-5. **Presentation**: Each opportunity includes personalized match reasoning, confidence score, and suggested next action.
-
-### Opportunity Workflow
-1. create_intent(description) or update_intent(intentId, description) → create or refine an approved signal
-2. background matching → persists opportunity cards when matches are found
-3. list_opportunities() → review persisted cards
-4. update_opportunity(opportunityId, status="pending") → sends to other party
-5. Other party sees opportunity → calls update_opportunity(status="accepted" or "rejected")`,
-                indexes: `## Index Mechanics
-
-Indexes (also called "networks") are communities where members share what they're looking for and the system discovers connections between them.
-
-- **Purpose prompt**: Each index has an optional prompt describing its purpose (e.g. "AI/ML co-founders in Berlin"). This prompt is used by the intent indexer to evaluate whether an intent belongs in this community. Networks without prompts accept all intents (relevancyScore defaults to 1.0).
-- **Join policy**: "anyone" (open — any user can self-join) or "invite_only" (only the owner can add members).
-- **Personal network**: Each user has exactly one personal network (isPersonal=true) created on registration. It stores their contacts. Cannot be deleted, renamed, or listed publicly.
-- **Membership**: Members can see all intents in the index. The **auto-assign** setting on a membership means new intents by that user are automatically evaluated against the index.
-- **Owner permissions**: Network owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the network (if sole member).
-- **Discovery scope**: Opportunities are discovered within index boundaries — the system matches intents of members who share at least one index.
-
-### Index Workflow
-1. create_network(title, prompt) → creates new community, you become owner
-2. create_network_membership(networkId, userId) → invite members
-3. Members create intents → auto-assigned to the index based on prompt
-4. Members' approved signals are matched in the background; list_opportunities only reviews persisted results`,
-                profiles: `## Profile System
-
-Profiles are the user's identity on the platform, used for semantic matching in opportunity discovery.
-
-- **Structure**: name, bio, location, skills[], interests[], social links (LinkedIn, GitHub, Twitter, websites)
-- **Generation**: Auto-generated from account data (name, email, social links) via web enrichment. Can also be created from explicit user input (bioOrDescription).
-- **Enrichment**: The system scrapes public profiles (LinkedIn, GitHub, Twitter) to build a rich identity with skills, interests, and narrative context.
-- **Embeddings**: HyDE (Hypothetical Document Embedding) generates synthetic documents for semantic matching:
-  - Mirror: self-description of the person
-  - Reciprocal: what this person would look for in others
-  - Neighborhood: related community context
-- **Onboarding flow**: create_user_context() → preview → create_user_context(confirm=true) → complete_onboarding()
-- **Updates**: Use update_user_context for targeted changes, create_user_context for full regeneration.
-
-### Profile Best Practices
-- Richer profiles produce better opportunity matches
-- Social links enable enrichment — encourage users to add LinkedIn/GitHub
-- Profiles are recalculated when updated, which may surface new matches`,
-                contacts: contactsSection,
-                discovery: `## Discovery Mechanics
-
-Discovery is the process of finding meaningful connections between users based on their intents and profiles.
-
-### How Discovery Works
-1. **Trigger**: Runs automatically when an approved signal is created or refined.
-2. **Pipeline**: Preparation (gather user context) → Scope (determine which indexes to search) → Candidate retrieval (semantic matching via HyDE embeddings) → Evaluation (LLM scores relevance and complementarity) → Ranking → Persist as opportunities.
-3. **Semantic matching**: Uses HyDE (Hypothetical Document Embeddings) to find candidate intents that complement the source. This goes beyond keyword matching — it understands conceptual relationships.
-4. **Evaluation**: An LLM evaluator agent scores each candidate match on relevance, complementarity, and actionability. Low-scoring matches are filtered out.
-5. **Results**: Persisted as draft opportunities with roles, reasoning, and confidence scores.
-6. **Background processing**: After intent creation, a queue job continues looking for matches asynchronously.
-7. **Review**: Use list_opportunities to review persisted actionable cards; it does not run matching.
-
-### Discovery Best Practices
-- More specific intents produce more relevant matches
-- Richer profiles improve matching quality
-- Scope to a specific index (networkId) for more targeted results
-- After discovery returns no results, suggest creating an intent to attract future matches`,
-                workflows: `## Common Tool Workflows
-
-### New User Setup
-1. create_user_context(linkedinUrl/githubUrl) → generate profile from social data
-2. complete_onboarding() → unlock full access
-3. read_networks() → see available communities
-4. create_network_membership(networkId) → join a community
-5. create_intent(description) → post what you're looking for
-6. Background matching evaluates the approved signal; list_opportunities reviews persisted results
-
-### Finding Connections
-1. read_networks() → list user's communities (get networkId)
-2. create_intent(description) or update_intent(intentId, description) → create or refine an approved signal in the relevant network
-3. Background matching persists eligible cards; list_opportunities reviews them
-4. update_opportunity(opportunityId, status="pending") → send a persisted card
-
-### Helping Connections Emerge
-1. read_network_memberships(networkId) → understand the shared community
-2. create_intent(description) or update_intent(intentId, description) → capture or refine an approved signal
-3. Background matching evaluates approved signals
-4. list_opportunities() → review persisted results
-
-${managingContactsWorkflow}### Creating a Community
-1. create_network(title, prompt) → create network
-2. create_network_membership(networkId, userId) → invite members
-3. Members create intents → auto-indexed
-4. Members' approved signals are matched in the background; list_opportunities only reviews persisted results`,
-                authentication: `## Authentication & API Access
-
-### For External AI Agents (MCP)
-- Authenticate via **X-API-Key** header with a valid API key
-- The API key is tied to a specific user account
-- All operations execute in the context of the authenticated user
-- Base URL: protocol.index.network/mcp
-
-### Key Constraints
-- Users can only read their own intents globally, or intents in indexes they belong to
-- Users can only read profiles of people in shared networks
-- Network-scoped operations are restricted to that index
-- Personal networks cannot be deleted or renamed
-- Only network owners can update settings, add/remove members (for invite_only networks)
-
-### Rate Limits & Best Practices
-- Avoid unnecessary read_intents/read_networks calls — cache results within a conversation
-- Use pagination (limit/page) for large result sets
-- Call read_docs once at the start to understand the domain`,
-                // Canonical topics (on REST/chat for completeness)
-                "identity-context": CANONICAL_GUIDANCE_TOPICS_CONTENT["identity-context"],
-                premises: CANONICAL_GUIDANCE_TOPICS_CONTENT.premises,
-                signals: CANONICAL_GUIDANCE_TOPICS_CONTENT.signals,
-                "communities-networks": CANONICAL_GUIDANCE_TOPICS_CONTENT["communities-networks"],
-                negotiations: CANONICAL_GUIDANCE_TOPICS_CONTENT.negotiations,
-            };
-            if (topic) {
-                const normalizedTopic = topic.replace(/_/g, "-").toLowerCase();
-                const matched = Object.entries(sections).find(([key]) => key === normalizedTopic || key.includes(normalizedTopic) || normalizedTopic.includes(key));
-                if (matched) {
-                    return success({ topic: matched[0], content: matched[1] });
-                }
-            }
-            // Return full documentation (summary + all topics)
-            const fullDoc = [CANONICAL_GUIDANCE_SUMMARY, ...Object.values(sections)].join("\n\n");
-            return success({ content: fullDoc });
-        },
-    });
-    const readActivitySummary = defineTool({
-        name: "read_activity_summary",
-        description: "Returns grounded, aggregate-only activity for the authenticated user's agent over a recent time window.\n\n" +
-            "**Response domains (permission-projected for agent callers):**\n" +
-            "- signals (`liveSignalsWatched`, `opportunitiesBySignal` with signal IDs/titles) — requires manage:intents.\n" +
-            "- opportunities (`opportunitiesSurfaced`) — requires manage:opportunities.\n" +
-            "- questions (`pendingQuestionsByDomain`, `answeredQuestionsByDomain`) — meta-network counts grouped by the question's affected domain; " +
-            "each domain's counts require that domain's manage:identity/premises/intents/opportunities/negotiations permission; conversational chat-mode counts are human-owner-only.\n" +
-            "- negotiations (`negotiationsStarted`, `negotiationsCompleted`) — requires manage:negotiations.\n" +
-            "Human owners receive every domain. Agent callers receive only the domains their permissions authorize; " +
-            "a network agent's network-bound aggregates are narrowed to its bound community at the query layer.\n\n" +
-            "**Privacy:** the response never returns counterparty identities, chats, turns, transcripts, per-counterparty rows, " +
-            "or any private content — only aggregate counts and (with manage:intents) the owner's own signal IDs/titles.",
-        querySchema: z.object({
-            sinceHours: z.number().int().optional().default(24).describe("Look back this many hours; values are clamped to 1-168 (default 24)."),
-        }).strict(),
-        handler: async ({ context, query }) => {
-            const sinceHours = Math.max(1, Math.min(168, query.sinceHours));
-            // Absent on owner-trusted REST/chat surfaces → full owner view. On MCP the
-            // server binds the typed resolved caller context and the centralized
-            // projection decides every visible domain.
-            const caller = context.mcpCaller
-                ? McpActivityCallerSchema.parse(context.mcpCaller)
-                : HUMAN_OWNER_CALLER;
-            const networkId = activitySummaryNetworkId(caller);
-            const summary = await deps.userDb.getAgentActivitySummary({
-                sinceHours,
-                ...(networkId ? { networkId } : {}),
-            });
-            return success(ActivitySummaryResponseSchema.parse(projectActivitySummary(caller, summary)));
-        },
-    });
-    return [scrapeUrl, readDocs, readActivitySummary].filter((tool) => tool !== null);
-}

package/dist/shared/assignment/network-assignment.policy.d.ts

@@ -1,61 +0,0 @@
-import type { ScopeMembership, ToolScopeEnvelope } from "../agent/tool.scope.js";
-import type { NetworkAssignmentMetadata, NetworkAssignmentMode, NetworkAssignmentPromptPresence, NetworkAssignmentRawScores, NetworkAssignmentResourceType, NetworkAssignmentScope } from "../schemas/network-assignment.schema.js";
-/** Centralized default for unified premises/intent network assignment. */
-export declare const DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD = 0.7;
-export interface PromptPresenceInput {
-    indexPrompt?: string | null;
-    memberPrompt?: string | null;
-}
-export type AssignmentScopeMembership = ScopeMembership | string;
-export interface ResolveAssignmentNetworkScopeArgs extends ToolScopeEnvelope {
-    memberships: AssignmentScopeMembership[];
-    /** @deprecated Use `scopeType: 'network'` + `scopeId`. */
-    networkScopeId?: string;
-}
-export interface BuildNetworkAssignmentDecisionArgs extends PromptPresenceInput {
-    resourceType: NetworkAssignmentResourceType;
-    mode: NetworkAssignmentMode;
-    scope: NetworkAssignmentScope;
-    rawScores?: NetworkAssignmentRawScores | null;
-    threshold?: number;
-    evaluator?: string;
-    source?: string;
-    reason?: string;
-    createdAt?: string;
-}
-export interface NetworkAssignmentDecision {
-    assigned: boolean;
-    finalScore: number;
-    metadata: NetworkAssignmentMetadata;
-}
-/**
- * Classifies whether a network/member prompt pair can filter a resource.
- *
- * @param input - Network and member prompt values to inspect.
- * @returns Prompt-presence classification for assignment policy decisions.
- */
-export declare function classifyPromptPresence(input: PromptPresenceInput): NetworkAssignmentPromptPresence;
-/**
- * Resolves the networks to evaluate: all memberships in global scope, or the
- * focused network plus personal memberships in network scope. The focused
- * network must also be a membership to avoid broadening scope accidentally.
- *
- * @param args - User memberships plus optional active network scope.
- * @returns Network IDs that assignment should evaluate.
- */
-export declare function resolveAssignmentNetworkScope(args: ResolveAssignmentNetworkScopeArgs): string[];
-/**
- * Builds a unified assignment decision and metadata envelope.
- *
- * @param args - Assignment resource, scope, prompt, score, and provenance inputs.
- * @returns Assignment decision and explainability metadata.
- */
-export declare function buildNetworkAssignmentDecision(args: BuildNetworkAssignmentDecisionArgs): NetworkAssignmentDecision;
-/**
- * Combines index/member scores according to available prompt filtration.
- *
- * @param rawScores - Optional normalized index and member scores.
- * @param promptPresence - Which prompts are present for this assignment decision.
- * @returns Final normalized score in the 0..1 range.
- */
-export declare function combineAssignmentScores(rawScores: NetworkAssignmentRawScores, promptPresence: NetworkAssignmentPromptPresence): number;

package/dist/shared/assignment/network-assignment.policy.js

@@ -1,105 +0,0 @@
-import { deriveAllowedNetworkIds, scopeFromNetworkId } from "../agent/tool.scope.js";
-/** Centralized default for unified premises/intent network assignment. */
-export const DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD = 0.7;
-/**
- * Classifies whether a network/member prompt pair can filter a resource.
- *
- * @param input - Network and member prompt values to inspect.
- * @returns Prompt-presence classification for assignment policy decisions.
- */
-export function classifyPromptPresence(input) {
-    const hasIndex = !!input.indexPrompt?.trim();
-    const hasMember = !!input.memberPrompt?.trim();
-    if (hasIndex && hasMember)
-        return "both";
-    if (hasIndex)
-        return "index";
-    if (hasMember)
-        return "member";
-    return "none";
-}
-/**
- * Resolves the networks to evaluate: all memberships in global scope, or the
- * focused network plus personal memberships in network scope. The focused
- * network must also be a membership to avoid broadening scope accidentally.
- *
- * @param args - User memberships plus optional active network scope.
- * @returns Network IDs that assignment should evaluate.
- */
-export function resolveAssignmentNetworkScope(args) {
-    const memberships = args.memberships.map((membership) => (typeof membership === "string"
-        ? { networkId: membership, isPersonal: false }
-        : membership));
-    const scope = args.scopeType && args.scopeId
-        ? { scopeType: args.scopeType, scopeId: args.scopeId }
-        : scopeFromNetworkId(args.networkScopeId);
-    return deriveAllowedNetworkIds({ memberships, ...scope });
-}
-/**
- * Builds a unified assignment decision and metadata envelope.
- *
- * @param args - Assignment resource, scope, prompt, score, and provenance inputs.
- * @returns Assignment decision and explainability metadata.
- */
-export function buildNetworkAssignmentDecision(args) {
-    const threshold = clampScore(args.threshold ?? DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD);
-    const promptPresence = classifyPromptPresence(args);
-    if (args.mode === "manual_override") {
-        const finalScore = 1.0;
-        return buildDecision(args, promptPresence, threshold, finalScore, true, args.reason ?? "Explicit manual override.");
-    }
-    if (promptPresence === "none") {
-        const finalScore = 1.0;
-        return buildDecision(args, promptPresence, threshold, finalScore, true, args.reason ?? "No prompts configured; network has no dynamic filtration.");
-    }
-    const finalScore = combineAssignmentScores(args.rawScores ?? {}, promptPresence);
-    const assigned = finalScore >= threshold;
-    return buildDecision(args, promptPresence, threshold, finalScore, assigned, args.reason);
-}
-/**
- * Combines index/member scores according to available prompt filtration.
- *
- * @param rawScores - Optional normalized index and member scores.
- * @param promptPresence - Which prompts are present for this assignment decision.
- * @returns Final normalized score in the 0..1 range.
- */
-export function combineAssignmentScores(rawScores, promptPresence) {
-    const indexScore = clampScore(rawScores.indexScore ?? 0);
-    const memberScore = clampScore(rawScores.memberScore ?? 0);
-    switch (promptPresence) {
-        case "both":
-            return clampScore(indexScore * 0.6 + memberScore * 0.4);
-        case "index":
-            return indexScore;
-        case "member":
-            return memberScore;
-        case "none":
-            return 1.0;
-    }
-}
-function buildDecision(args, promptPresence, threshold, finalScore, assigned, reason) {
-    return {
-        assigned,
-        finalScore,
-        metadata: {
-            resourceType: args.resourceType,
-            mode: args.mode,
-            scope: args.scope,
-            policy: "unified-threshold-v1",
-            threshold,
-            promptPresence,
-            ...(args.rawScores ? { rawScores: args.rawScores } : {}),
-            finalScore,
-            assigned,
-            ...(reason ? { reason } : {}),
-            ...(args.evaluator ? { evaluator: args.evaluator } : {}),
-            ...(args.source ? { source: args.source } : {}),
-            ...(args.createdAt ? { createdAt: args.createdAt } : {}),
-        },
-    };
-}
-function clampScore(score) {
-    if (!Number.isFinite(score))
-        return 0;
-    return Math.max(0, Math.min(1, score));
-}

package/dist/shared/interfaces/agent-dispatcher.interface.d.ts

@@ -1,100 +0,0 @@
-/**
- * AgentDispatcher interface for the negotiation graph.
- *
- * The graph calls dispatch() per turn and receives a result.
- * It never knows about webhooks, MCP, transports, or agent resolution.
- * The concrete implementation lives in the host application.
- *
- * IND-548: these types are also accessible via agents/ports, which
- * re-exports from here. This file remains the authoritative source to avoid a
- * module cycle through the negotiation capability facade.
- */
-import type { NegotiationTurn, UserNegotiationContext, SeedAssessment } from '../schemas/negotiation-state.schema.js';
-import type { NegotiatorMemoryEntry } from '../../negotiations/negotiation.memory.js';
-import type { AttributedPriorDialogue } from '../../negotiations/negotiation.attribution.js';
-import type { NegotiationPrivateConsultation } from './database.interface.js';
-import type { NegotiationContinuationTimeoutIdentity } from './negotiation-events.interface.js';
-/** Payload sent to the dispatcher for each negotiation turn. */
-export interface NegotiationTurnPayload {
-    negotiationId: string;
-    ownUser: UserNegotiationContext;
-    otherUser: UserNegotiationContext;
-    indexContext: {
-        networkId: string;
-        prompt?: string;
-    };
-    seedAssessment: SeedAssessment;
-    history: NegotiationTurn[];
-    isFinalTurn: boolean;
-    /** Whether ownUser is the party that initiated the discovery. */
-    isDiscoverer: boolean;
-    /** The explicit search query that triggered this discovery (if any). Takes priority over background intents. */
-    discoveryQuery?: string;
-    /** The acting user's seat under the v2 client-advocate protocol (`initiator` | `counterparty`). */
-    seat?: string;
-    /** Negotiation protocol version for this task (`v1` | `v2`). */
-    protocolVersion?: string;
-    /** Actions the acting seat may submit on this turn (seat + version + final-turn scoped). */
-    allowedActions?: string[];
-    /**
-     * The acting user's OWN negotiator memories (P5.3 read path) — private
-     * context for the dispatched agent. Never contains the counterparty's
-     * memory; absent when `NEGOTIATOR_MEMORY_INJECT` is off or nothing was
-     * retrieved.
-     */
-    negotiatorMemory?: NegotiatorMemoryEntry[];
-    /** Recipient-private ask-user consultation, present only for that recipient's turn. */
-    privateConsultation?: NegotiationPrivateConsultation;
-    /**
-     * Prior dialogue with this counterparty, grouped and labeled per opportunity
-     * (IND-569). Present only on continuations; lets an external agent see which
-     * prior turns belonged to already-concluded OTHER opportunities versus the
-     * one under negotiation now. Absent → no attributed prior dialogue available.
-     */
-    priorDialogue?: AttributedPriorDialogue;
-    /** Server-only continuation generation used to fence the delayed park timeout. */
-    timeoutContinuation?: NegotiationContinuationTimeoutIdentity;
-}
-/** Result of a dispatch attempt. */
-export type AgentDispatchResult = {
-    handled: true;
-    turn: NegotiationTurn;
-} | {
-    handled: false;
-    reason: 'no_agent' | 'timeout';
-} | {
-    handled: false;
-    reason: 'waiting';
-    resumeToken: string;
-};
-/**
- * Dispatches a negotiation turn to the appropriate agent.
- * Tries external (poller) agents first, falls back to system agent.
- */
-export interface AgentDispatcher {
-    /**
-     * Attempt to dispatch a negotiation turn to an external (poller) agent.
-     * @param userId - The user whose agent should handle this turn
-     * @param scope - Permission scope for agent resolution
-     * @param payload - Turn context (users, history, seed assessment)
-     * @param options - Timeout configuration
-     * @returns Handled result with turn, or unhandled result with reason
-     */
-    dispatch(userId: string, scope: {
-        action: string;
-        scopeType: string;
-        scopeId?: string;
-    }, payload: NegotiationTurnPayload, options: {
-        timeoutMs: number;
-    }): Promise<AgentDispatchResult>;
-    /**
-     * Check whether a user has an authorized external (poller) agent for the given
-     * scope. Used at init to determine scenario-based turn caps. Type-only by design
-     * (no heartbeat freshness) — see IND-410.
-     */
-    hasExternalAgent(userId: string, scope: {
-        action: string;
-        scopeType: string;
-        scopeId?: string;
-    }): Promise<boolean>;
-}

package/dist/shared/interfaces/agent-dispatcher.interface.js

@@ -1,12 +0,0 @@
-/**
- * AgentDispatcher interface for the negotiation graph.
- *
- * The graph calls dispatch() per turn and receives a result.
- * It never knows about webhooks, MCP, transports, or agent resolution.
- * The concrete implementation lives in the host application.
- *
- * IND-548: these types are also accessible via agents/ports, which
- * re-exports from here. This file remains the authoritative source to avoid a
- * module cycle through the negotiation capability facade.
- */
-export {};

package/dist/shared/interfaces/auth.interface.d.ts

@@ -1,37 +0,0 @@
-import type { McpAuthInput, McpResolvedIdentity } from '../schemas/mcp-auth.schema.js';
-/**
- * Resolves the authenticated MCP identity from an auth input DTO.
- * The DTO is extracted from the transport at the edge (e.g. from HTTP Request
- * headers) before the protocol layer is called. New auth paths stay free of
- * platform-specific `Request` coupling; `resolveUserId` remains only as a
- * deprecated compatibility bridge while callers migrate to `resolveIdentity`.
- */
-export interface McpAuthResolver {
-    /**
-     * Extracts and validates the authenticated identity from the auth input.
-     *
-     * @param input - Transport-neutral auth input DTO with credential fields
-     *   extracted at the MCP transport edge.
-     * @returns The authenticated user's UUID, optional agent UUID, auth method,
-     *   and `networkScopeId` if the caller's API key is bound to a network-scoped
-     *   agent.
-     *
-     *   When `networkScopeId` is set, the MCP server promotes it into the
-     *   canonical `{ scopeType: 'network', scopeId }` envelope. Downstream tools
-     *   derive concrete allowed network IDs from that envelope plus memberships.
-     *
-     *   `isSessionAuth` is true for OAuth/JWT bearer sessions — the agent-
-     *   registration gate in the MCP server is skipped for these callers.
-     *
-     * @throws Error if authentication fails (no token, invalid token, etc.)
-     */
-    resolveIdentity(input: McpAuthInput): Promise<McpResolvedIdentity>;
-    /**
-     * Deprecated HTTP Request bridge retained for compatibility with older
-     * callers. New transport code must extract `McpAuthInput` at the edge and
-     * call `resolveIdentity` instead.
-     *
-     * @deprecated Use resolveIdentity instead.
-     */
-    resolveUserId(request: Request): Promise<string>;
-}

package/dist/shared/interfaces/auth.interface.js

@@ -1 +0,0 @@
-export {};