@indexnetwork/protocol 0.3.3 → 0.4.0-rc.13.1

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

@@ -4,10 +4,18 @@ export function createUtilityTools(defineTool, deps) {
     const { scraper } = deps;
     const scrapeUrl = defineTool({
         name: "scrape_url",
-        description: "Extracts text content from a URL (articles, profiles, documentation, etc.). Use this to read web pages, LinkedIn/GitHub profiles, or any public web content. The URL does not need http:// or https:// — bare domains like github.com/user/repo work fine. Pass 'objective' when you know the downstream use: e.g. 'User wants to create an intent from this link (project/repo).' or 'User wants to update their profile from this page.' — this returns content better suited for that use.",
+        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_profile or update_user_profile: 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 scrape (protocol optional — e.g. 'github.com/user/repo' is fine)"),
-            objective: z.string().optional().describe("Optional: why we're scraping. E.g. 'User wants to create an intent from this link' or 'User wants to update their profile from this page'. Omit for generic extraction."),
+            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);
@@ -32,64 +40,225 @@ export function createUtilityTools(defineTool, deps) {
     });
     const readDocs = defineTool({
         name: "read_docs",
-        description: "Returns the protocol's business logic documentation: entity model, intent lifecycle, opportunity lifecycle, discovery mechanics, and key workflows. Call this when you need to understand how the system works or explain it to the user.",
+        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. MCP agents MUST call read_docs(topic='mcp_agent_guide') at the start of every conversation to learn proper output formatting and workflow rules.\n" +
+            "Also call when you need to understand:\n" +
+            "- What entities exist and how they relate (intents, indexes, opportunities, profiles, contacts)\n" +
+            "- The discovery workflow (how intents become opportunities)\n" +
+            "- Which tools to call in what order for common tasks\n" +
+            "- Authentication and API patterns\n\n" +
+            "**Returns:** Markdown documentation. Pass `topic` to get a specific section, or omit for the full reference.\n\n" +
+            "**Available topics:** 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', 'authentication', 'mcp_agent_guide'",
         querySchema: z.object({
-            topic: z.string().optional().describe("Optional: narrow to a specific topic (e.g. 'opportunities', 'intents', 'indexes', 'profiles', 'discovery')."),
+            topic: z.string().optional().describe("Narrow to a specific topic: 'entities', 'intents', 'opportunities', 'indexes', 'profiles', 'contacts', 'discovery', 'workflows', or 'authentication'. Omit to get the full documentation."),
         }),
         handler: async ({ context: _context, query }) => {
             const topic = query.topic?.trim().toLowerCase();
             const sections = {
-                entities: `## Entity Model
-
-- **Users**: People on the platform. Authenticated via session (Better Auth).
-- **Profiles**: A user's identity — bio, skills, interests, location, social links. Generated from account data or social URLs. Has a vector embedding for semantic matching.
-- **Indexes**: Communities or groups. Each has a title, optional prompt (purpose description), and a join policy (anyone or invite_only). Users join indexes as members; the creator is the owner.
-- **Index Members**: Junction between Users and Indexes. Tracks permissions, join date, auto-assign setting, and optional member prompt.
-- **Intents**: What a user is looking for — wants, needs, and priorities. Each has a description (payload), summary, confidence score, and vector embedding. Intents belong to a user but are linked to networks via IntentNetworks (many-to-many).
-- **IntentNetworks**: Junction between Intents and Networks. An intent can be in multiple networks. When an intent is created, it is evaluated against network prompts and linked to relevant ones.
-- **Opportunities**: Discovered connections between users based on intent overlap. Have roles (introducer, patient, agent, peer), status lifecycle, reasoning, and presentation data.
-- **HyDE Documents**: Hypothetical Document Embeddings — generated synthetic documents used for semantic retrieval of intents and profiles`,
+                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. Has a vector embedding for semantic matching. 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 index** (isPersonal=true) stores their contacts.
+- **Index 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 indexes. 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 index members with 'contact' permission on the personal index. Can be real users or ghost users (placeholder accounts enriched from public data).
+- **Ghost Users**: Placeholder accounts created for contacts who aren't on the platform yet. Enriched with public profile data (LinkedIn, GitHub) and participate in opportunity matching.
+
+### Key Relationships
+- Users → Profiles (1:1)
+- Users → Indexes (many:many via Index 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 index context)
+- Contacts → Personal Index (stored as members with 'contact' permission)`,
                 intents: `## Intent Lifecycle
 
-1. **Creation**: User describes what they're looking for. The IntentClarifier checks if it's specific enough — vague intents get a refinement suggestion before persisting.
-2. **Inference**: The intent graph extracts structured intents from free text. It can infer multiple intents from a single input and reconcile with existing ones (update if similar, create if new).
-3. **Semantic Governance**: Each intent gets a confidence score, semantic entropy measure, speech act type (commissive, directive, assertive), referential anchor, and felicity conditions (sincerity, authority).
-4. **Index Assignment**: After creation, the intent is evaluated against all indexes the user belongs to (using the index prompt as criteria). It's automatically linked to matching indexes via IntentNetworks.
-5. **Discovery**: Creating an intent triggers background opportunity detection — the system looks for other users in shared indexes whose intents complement this one.
-6. **Update/Archive**: Intents can be updated (re-processed through the graph) or archived (soft delete).`,
+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 indexes 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 indexes 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
 
-1. **Detection**: The opportunity graph finds users whose intents semantically complement each other within shared indexes. Uses HyDE embeddings for retrieval and an evaluator agent for scoring.
-2. **Roles**: Each opportunity assigns roles — introducer (who triggered it), patient (seeker), agent (helper), or peer (mutual). The current user's role determines what they see.
-3. **Status Flow**: latent (draft) → pending (sent) → accepted/rejected/expired. Users see "draft", "sent", "connected" in natural language.
-4. **Visibility**: Role-based. The introducer sees the draft first. After sending, the next person in the reveal chain sees it. Not all parties see all details at every stage.
-5. **Presentation**: Each opportunity gets a personalized summary, suggested action, and reasoning — generated by an LLM presenter agent.
-6. **Two Modes**:
-   - **Discovery**: System finds matches for the user's intents in an index (or all indexes). Triggered by create_intent or create_opportunities with searchQuery.
-   - **Introduction**: A user introduces two specific people. The system gathers both profiles and intents from shared indexes and creates the opportunity.`,
+Opportunities represent discovered connections between users — potential matches worth pursuing.
+
+1. **Detection** (create_opportunities): The opportunity graph finds users whose intents semantically complement each other within shared indexes. 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 Modes**:
+   - **Discovery**: Automatic — system finds matches based on intent overlap (create_opportunities with searchQuery)
+   - **Introduction**: Manual — a user introduces two specific people (create_opportunities with partyUserIds + entities)
+   - **Direct**: One-to-one — connect with a specific person (create_opportunities with targetUserId)
+5. **Presentation**: Each opportunity includes personalized match reasoning, confidence score, and suggested next action.
+
+### Opportunity Workflow
+1. create_opportunities(searchQuery="AI engineers") → returns draft opportunity cards
+2. update_opportunity(opportunityId, status="pending") → sends to other party
+3. Other party sees opportunity → calls update_opportunity(status="accepted" or "rejected")`,
                 indexes: `## Index Mechanics
 
-- Indexes are communities where members share what they're looking for.
-- Each index has a **prompt** that describes its purpose (e.g. "AI/ML co-founders in Berlin"). This prompt is used by the intent indexer agent to evaluate whether an intent belongs.
-- **Join policy**: "anyone" (open) or "invite_only" (owner adds members).
-- Members can see all intents in the index (not just their own).
-- The **auto-assign** setting on a membership means new intents by that user are automatically evaluated against the index.
-- Index owners can update settings, add/remove members, and delete the index (if sole member).`,
+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. Indexes 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 index**: Each user has exactly one personal index (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**: Index owners can update settings (title, prompt, joinPolicy), add/remove members, and delete the index (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. create_opportunities(networkId) → discover matches within this community`,
                 profiles: `## Profile System
 
-- Profiles are auto-generated from user account data (name, email, social links).
-- Can be enriched by scraping LinkedIn, GitHub, Twitter, or personal websites.
-- The profile graph generates a structured identity (bio, skills, interests, location), narrative context, and attributes.
-- Profiles have vector embeddings used for semantic matching in opportunity detection.
-- HyDE (Hypothetical Document Embedding) generates synthetic documents from profiles for better retrieval: Mirror (self-description), Reciprocal (what they'd look for), and Neighborhood (related community context).`,
+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**: Profiles have vector embeddings for semantic matching. HyDE (Hypothetical Document Embedding) generates synthetic documents:
+  - Mirror: self-description of the person
+  - Reciprocal: what this person would look for in others
+  - Neighborhood: related community context
+- **Onboarding flow**: create_user_profile() → preview → create_user_profile(confirm=true) → complete_onboarding()
+- **Updates**: Use update_user_profile for targeted changes, create_user_profile 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: `## Contact Management
+
+Contacts are people in a user's personal network, stored as members of their personal index with 'contact' permission.
+
+- **Adding contacts**: Via import_contacts (bulk), add_contact (single email), or import_gmail_contacts (Google integration).
+- **Ghost users**: When a contact email doesn't match an existing account, a ghost user is created. Ghost users are enriched with public profile data and participate in opportunity matching — they can be discovered even before joining the platform.
+- **Personal index scope**: Pass the personal index networkId to create_opportunities to scope discovery to just the user's contacts.
+- **Contact data**: Each contact has userId, name, email, avatar, and isGhost flag.
+
+### Contact Workflow
+1. import_contacts or import_gmail_contacts → bulk add to network
+2. list_contacts → view all contacts with userId
+3. create_opportunities(networkId=personalIndexId) → find matches among contacts
+4. add_contact(email) → add individual contact
+5. remove_contact(contactUserId) → remove from network`,
                 discovery: `## Discovery Mechanics
 
-- Discovery runs when an intent is created (automatic) or when create_opportunities is called explicitly.
-- The opportunity graph pipeline: Preparation (gather context) → Scope (determine indexes) → Discovery (semantic matching of intents) → Evaluation (LLM scores relevance) → Ranking → Persist.
-- Semantic matching uses HyDE embeddings to find candidate intents that complement the source intent.
-- The evaluator agent scores each match on relevance, complementarity, and actionability.
-- Results are persisted as opportunities with appropriate roles and presentation.
-- Background processing: after intent creation, a queue job continues looking for matches asynchronously.`,
+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 intent is created, or explicitly when create_opportunities is called.
+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. **Pagination**: Large result sets are paginated. Use continueFrom with the discoveryId to evaluate more candidates.
+
+### 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_profile(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. create_opportunities(searchQuery) → find matches
+
+### Finding Connections
+1. read_networks() → list user's communities (get networkId)
+2. create_opportunities(searchQuery, networkId) → discover matches
+3. Review opportunity cards → update_opportunity(opportunityId, status="pending") to send
+
+### Making an Introduction
+1. read_network_memberships(networkId) → find members in shared community
+2. read_user_profiles(userId) → get profiles of both parties
+3. read_intents(networkId, userId) → get intents of both parties
+4. create_opportunities(partyUserIds=[id1,id2], entities=[...], hint="reason") → create introduction
+
+### Managing Contacts
+1. import_gmail_contacts() or import_contacts([...]) → add contacts
+2. list_contacts() → view network
+3. create_opportunities(networkId=personalIndexId) → find matches among contacts
+
+### Creating a Community
+1. create_network(title, prompt) → create index
+2. create_network_membership(networkId, userId) → invite members
+3. Members create intents → auto-indexed
+4. create_opportunities(networkId) → discover connections within community`,
+                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 indexes
+- Index-scoped operations are restricted to that index
+- Personal indexes cannot be deleted or renamed
+- Only index owners can update settings, add/remove members (for invite_only indexes)
+
+### 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`,
+                mcp_agent_guide: `## MCP Agent Integration Guide
+
+**IMPORTANT: Read this section if you are an AI agent accessing Index Network via MCP tools.**
+
+### Output Formatting
+- Tool results often contain structured JSON data (proposals, opportunities, cards). **Do NOT dump raw JSON to the user.** Parse the JSON and present information in natural language with clear formatting.
+- Some tool results contain interactive card markup (code blocks with \`intent_proposal\`, \`opportunity_card\` language tags). These are designed for the Index Network web UI. **As an MCP agent, ignore card markup.** Instead, extract the meaningful data from the JSON and present it conversationally.
+- When presenting opportunities or intents, use bullet points or short paragraphs — not raw JSON objects.
+
+### Intent Creation Workflow
+- **Always pass \`autoApprove: true\` when calling \`create_intent\`.** This persists intents directly without returning proposal cards that require manual UI approval.
+- The tool will return a list of created intents with their descriptions and confidence scores. Present these in natural language.
+- Do not tell the user to "click on cards" or "approve above" — there is no UI. Intents are created immediately with autoApprove.
+- After creating intents, proactively suggest or run discovery to find matches.
+
+### Discovery Workflow
+- After creating intents, proactively suggest running discovery: \`create_opportunities(searchQuery=...)\`
+- Present discovered opportunities in natural language with the counterpart's name, match reasoning, and suggested next steps.
+- Do not reference "cards", "panels", or any web UI elements.
+
+### General MCP Agent Rules
+- You are operating via API tools, not a web interface. Never reference clicking, scrolling, cards, panels, or any visual UI elements.
+- Be proactive: if a logical next step exists (e.g., running discovery after creating intents), suggest or execute it.
+- Use \`list_opportunities\` to check existing matches, \`list_negotiations\` for ongoing negotiations.
+- Use \`read_networks\` to understand which communities the user belongs to before scoping operations.
+- When errors occur, provide clear technical context rather than vague "backend issue" messages.`,
             };
             if (topic) {
                 const matched = Object.entries(sections).find(([key]) => key.includes(topic) || topic.includes(key));

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

@@ -1 +1 @@
-{"version":3,"file":"utility.tools.js","sourceRoot":"","sources":["../../../src/shared/agent/utility.tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utility.tools.js","sourceRoot":"","sources":["../../../src/shared/agent/utility.tools.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,176 @@
+/**
+ * Database adapter interface for agent registry operations.
+ * Implemented by the host application and injected via ProtocolDeps.
+ */
+export interface AgentRecord {
+    id: string;
+    ownerId: string;
+    name: string;
+    description: string | null;
+    type: 'personal' | 'system';
+    status: 'active' | 'inactive';
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface AgentTransportRecord {
+    id: string;
+    agentId: string;
+    channel: 'webhook' | 'mcp';
+    config: Record<string, unknown>;
+    priority: number;
+    active: boolean;
+    failureCount: number;
+}
+export interface AgentPermissionRecord {
+    id: string;
+    agentId: string;
+    userId: string;
+    scope: 'global' | 'node' | 'network';
+    scopeId: string | null;
+    actions: string[];
+    createdAt: Date;
+}
+export interface AgentWithRelations extends AgentRecord {
+    transports: AgentTransportRecord[];
+    permissions: AgentPermissionRecord[];
+}
+export interface CreateAgentInput {
+    ownerId: string;
+    name: string;
+    description?: string;
+    type?: 'personal' | 'system';
+    metadata?: Record<string, unknown>;
+}
+export interface CreateTransportInput {
+    agentId: string;
+    channel: 'webhook' | 'mcp';
+    config?: Record<string, unknown>;
+    priority?: number;
+}
+export interface GrantPermissionInput {
+    agentId: string;
+    userId: string;
+    scope?: 'global' | 'node' | 'network';
+    scopeId?: string;
+    actions: string[];
+}
+/**
+ * Database adapter interface for agent registry operations.
+ *
+ * Handles CRUD for agents, their transports, and permission grants.
+ * Implemented by the host application (backend) and injected into the
+ * protocol layer via constructor injection at the composition root.
+ */
+export interface AgentDatabase {
+    /**
+     * Creates a new agent record.
+     * @param input - Agent creation parameters.
+     * @returns The persisted agent record.
+     */
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    /**
+     * Retrieves an agent by its ID.
+     * @param agentId - The agent UUID.
+     * @returns The agent record, or null if not found.
+     */
+    getAgent(agentId: string): Promise<AgentRecord | null>;
+    /**
+     * Retrieves an agent along with its transports and permissions.
+     * @param agentId - The agent UUID.
+     * @returns The agent with relations, or null if not found.
+     */
+    getAgentWithRelations(agentId: string): Promise<AgentWithRelations | null>;
+    /**
+     * Updates mutable fields on an agent.
+     * @param agentId - The agent UUID.
+     * @param updates - Partial set of fields to update.
+     * @returns The updated agent record, or null if not found.
+     */
+    updateAgent(agentId: string, updates: Partial<Pick<AgentRecord, 'name' | 'description' | 'status' | 'metadata'>>): Promise<AgentRecord | null>;
+    /**
+     * Deletes an agent and its associated transports and permissions.
+     * @param agentId - The agent UUID.
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /**
+     * Lists all agents owned by a user, including their relations.
+     * @param userId - The owner's user ID.
+     * @returns Array of agents with transports and permissions.
+     */
+    listAgentsForUser(userId: string): Promise<AgentWithRelations[]>;
+    /**
+     * Creates a transport channel for an agent.
+     * @param input - Transport creation parameters.
+     * @returns The persisted transport record.
+     */
+    createTransport(input: CreateTransportInput): Promise<AgentTransportRecord>;
+    /**
+     * Deletes a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    deleteTransport(transportId: string): Promise<void>;
+    /**
+     * Increments the failure counter for a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportFailure(transportId: string): Promise<void>;
+    /**
+     * Resets the failure counter for a transport channel after a successful delivery.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportSuccess(transportId: string): Promise<void>;
+    /**
+     * Grants a permission to an agent for a given user and scope.
+     * @param input - Permission grant parameters.
+     * @returns The persisted permission record.
+     */
+    grantPermission(input: GrantPermissionInput): Promise<AgentPermissionRecord>;
+    /**
+     * Revokes a permission by its ID.
+     * @param permissionId - The permission UUID.
+     */
+    revokePermission(permissionId: string): Promise<void>;
+    /**
+     * Checks whether an agent holds a specific permission for a user.
+     * @param agentId - The agent UUID.
+     * @param userId - The user whose permission is being checked.
+     * @param action - The action string to verify (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction; defaults to global if omitted.
+     * @returns True if the permission exists, false otherwise.
+     */
+    hasPermission(agentId: string, userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<boolean>;
+    /**
+     * Returns all agents authorized for a user and action, optionally within a scope.
+     * @param userId - The user to check authorization for.
+     * @param action - The action string (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction.
+     * @returns Array of authorized agents with their relations.
+     */
+    findAuthorizedAgents(userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<AgentWithRelations[]>;
+    /**
+     * Returns the well-known IDs for built-in system agents.
+     * @returns Object mapping system agent roles to their fixed UUIDs.
+     */
+    getSystemAgentIds(): {
+        chatOrchestrator: string;
+        negotiator: string;
+    };
+}
+/**
+ * Fixed UUIDs for built-in system agents.
+ *
+ * These are seeded into the database on first run and must never change,
+ * as they are referenced by foreign keys and hard-coded in protocol logic.
+ */
+export declare const SYSTEM_AGENT_IDS: {
+    readonly chatOrchestrator: "00000000-0000-0000-0000-000000000001";
+    readonly negotiator: "00000000-0000-0000-0000-000000000002";
+};
+//# sourceMappingURL=agent.interface.d.ts.map

package/dist/shared/interfaces/agent.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/agent.interface.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+/**
+ * Database adapter interface for agent registry operations.
+ * Implemented by the host application and injected via ProtocolDeps.
+ */
+/**
+ * Fixed UUIDs for built-in system agents.
+ *
+ * These are seeded into the database on first run and must never change,
+ * as they are referenced by foreign keys and hard-coded in protocol logic.
+ */
+export const SYSTEM_AGENT_IDS = {
+    chatOrchestrator: '00000000-0000-0000-0000-000000000001',
+    negotiator: '00000000-0000-0000-0000-000000000002',
+};
+//# sourceMappingURL=agent.interface.js.map

package/dist/shared/interfaces/agent.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.interface.js","sourceRoot":"","sources":["../../../src/shared/interfaces/agent.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4LH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,gBAAgB,EAAE,sCAAsC;IACxD,UAAU,EAAE,sCAAsC;CAC1C,CAAC"}

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

@@ -1,15 +1,22 @@
 /**
- * Resolves the authenticated user ID from an incoming request.
+ * Resolves the authenticated MCP identity from an incoming request.
  * Injected into the MCP server factory so the protocol layer
  * stays independent of any specific auth implementation.
  */
 export interface McpAuthResolver {
     /**
-     * Extracts and validates the authenticated user's ID from the request.
+     * Extracts and validates the authenticated identity from the request.
      * @param request - The incoming HTTP request
-     * @returns The authenticated user's UUID
+     * @returns The authenticated user's UUID and optional agent UUID
      * @throws Error if authentication fails (no token, invalid token, etc.)
      */
+    resolveIdentity(request: Request): Promise<{
+        userId: string;
+        agentId?: string;
+    }>;
+    /**
+     * @deprecated Use resolveIdentity instead.
+     */
     resolveUserId(request: Request): Promise<string>;
 }
 //# sourceMappingURL=auth.interface.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/auth.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD"}
+{"version":3,"file":"auth.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/interfaces/auth.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjF;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD"}

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

@@ -1441,6 +1441,58 @@ export interface NegotiationDatabase {
     }): Promise<{
         id: string;
     }>;
+    /**
+     * Lists negotiation tasks where the given user is source or candidate.
+     * @param userId - The user ID to filter by (matches sourceUserId or candidateUserId in task metadata)
+     * @param options - Optional status filter
+     * @returns Array of task records with metadata
+     */
+    getTasksForUser(userId: string, options?: {
+        state?: string;
+    }): Promise<Array<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    }>>;
+    /**
+     * Gets a specific task by ID.
+     * @param taskId - The task ID to look up
+     * @returns The task record or null if not found
+     */
+    getTask(taskId: string): Promise<{
+        id: string;
+        conversationId: string;
+        state: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Gets all messages for a conversation, ordered by creation time.
+     * @param conversationId - The conversation to fetch messages for
+     * @returns Array of message records
+     */
+    getMessagesForConversation(conversationId: string): Promise<Array<{
+        id: string;
+        senderId: string;
+        role: 'user' | 'agent';
+        parts: unknown[];
+        createdAt: Date;
+    }>>;
+    /**
+     * Gets artifacts for a task (e.g. negotiation outcome).
+     * @param taskId - The task to fetch artifacts for
+     * @returns Array of artifact records
+     */
+    getArtifactsForTask(taskId: string): Promise<Array<{
+        id: string;
+        name: string | null;
+        parts: unknown[];
+        metadata: Record<string, unknown> | null;
+    }>>;
 }
 /**
  * Database interface for opportunity controller (API).