@indexnetwork/protocol 66.0.0-rc.645.1 → 66.0.0-rc.648.1

package/README.md

@@ -31,8 +31,8 @@ flowchart LR
 
     Scope --> CandidateGeneration[Candidate generation]
     CandidateGeneration --> Evaluation[Evaluation]
-    Evaluation -->|plausible but uncertain| Opportunity[Draft or negotiating opportunity]
-    Evaluation -->|clear fit| Opportunity[Draft or pending opportunity]
+    Evaluation -->|plausible but uncertain| Opportunity[Negotiating opportunity]
+    Evaluation -->|clear fit| Opportunity[Pending opportunity]
     Opportunity -->|needs agent clarification| Negotiation[Bounded negotiation]
     Negotiation -->|fit established| Opportunity
     Negotiation -->|human judgment required| Questions[Structured questions]
@@ -238,11 +238,11 @@ Opportunity states are participant-facing as follows:
 
 | State | Participant-facing term | Meaning |
 |---|---|---|
-| **Draft** | Draft | The protocol found a plausible opportunity, but it has not been sent to the other side. |
-| **Sent** | Sent | One side has sent or received the opportunity and a response is pending. |
-| **Connected** | Connected | Required participants accepted and a conversation or introduction may proceed. |
-| **Declined** | Declined | A participant rejected the opportunity. |
-| **Expired** | Expired | The opportunity is no longer actionable. |
+| **negotiating** | Agents talking | The agents are negotiating whether the fit holds. |
+| **pending** | Waiting on you | The agents agreed and the participants decide. A participant who already accepted sees Chat open: the first accept opens the conversation, and the status stays pending until every participant has accepted. |
+| **accepted** | Connected | Every participant accepted. |
+| **rejected** | Passed | An agent declined or a participant rejected the opportunity. |
+| **expired** | Expired | An intent was archived. |
 
 A conforming agent MUST NOT present a received opportunity as **Connected** without explicit approval from the receiving participant. The reference implementation enforces actor authorization and valid source statuses for acceptance, while current-approval capture is handled by the agent or user-interface flow invoking the transition.
 
@@ -250,33 +250,26 @@ A conforming agent MUST NOT present a received opportunity as **Connected** with
 
 ```mermaid
 stateDiagram-v2
-    [*] --> Draft: candidate promoted
-    Draft --> Sent: sender approves send
-    Draft --> Connected: direct acceptance or connection link
-    Draft --> Declined: sender declines
-    Draft --> Expired: TTL or invalidated
-
-    Sent --> Connected: recipient explicitly accepts
-    Sent --> Declined: recipient declines
-    Sent --> Expired: TTL or invalidated
-
-    Connected --> [*]
-    Declined --> [*]
-    Expired --> [*]
-
-    note right of Draft
-      Plausible but not sent.
-      Only visible under role and scope rules.
+    [*] --> negotiating: agent opens it
+    negotiating --> pending: agents agree
+    negotiating --> rejected: agent declines
+    negotiating --> expired: intent archived
+
+    pending --> accepted: every participant accepts
+    pending --> rejected: participant rejects
+    pending --> expired: intent archived
+
+    accepted --> [*]
+    rejected --> [*]
+    expired --> [*]
+
+    note right of pending
+      Waiting on the participants.
+      The first accept opens the chat.
     end note
 
-    note right of Sent
-      One side is waiting.
-      Acceptance requires participant approval.
-    end note
-
-    note right of Connected
-      Relationship boundary crossed.
-      Conversation or introduction may proceed.
+    note right of accepted
+      Every participant accepted.
     end note
 ```
 
@@ -300,11 +293,11 @@ sequenceDiagram
     PR->>PR: Generate candidates inside scope
     PR->>PR: Evaluate role fit and constraints
     alt Fit is clear
-        PR-->>A: Draft opportunity with explanation
+        PR-->>A: Pending opportunity with explanation
     else Fit is uncertain
         PR->>N: Start bounded negotiation
         N-->>PR: Propose, counter, accept, reject, or question
-        PR-->>A: Draft opportunity or structured question
+        PR-->>A: Pending opportunity or structured question
     end
     A->>P: Explain strongest reason and ask for approval
     P-->>A: Approve, decline, or refine intent

package/dist/index.d.ts

@@ -33,7 +33,7 @@ export type { NetworksDeps } from "./capabilities/networks.js";
 export { Intents } from "./capabilities/intents.js";
 export type { PrepareAnswer, PrepareInput, PrepareResult, RecoveryField, RecoveryFieldKind, RecoveryFieldOption, IntentsDeps, IntentSemanticMetadata, PreparedIntent, } from "./capabilities/intents.js";
 export { IntentSuggester } from "./internal/intents/intent.suggester.js";
-export type { IntentSuggestion, IntentSuggestionInput } from "./internal/intents/intent.suggester.js";
+export type { IntentSuggestion, IntentSuggestionInput, IntentSuggestions } from "./internal/intents/intent.suggester.js";
 export { normalizeTelegramHandle } from './internal/shared/utils/telegram-handle.js';
 /**
  * opportunity — the capability's sole cross-capability surface.

package/dist/internal/intents/intent.suggester.d.ts

@@ -2,12 +2,15 @@ import { z } from "zod";
 export declare const IntentSuggestionOutputSchema: z.ZodObject<{
     lookingFor: z.ZodArray<z.ZodString, "many">;
     offering: z.ZodString;
+    examples: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
     lookingFor: string[];
     offering: string;
+    examples: string[];
 }, {
     lookingFor: string[];
     offering: string;
+    examples: string[];
 }>;
 export interface IntentSuggestionInput {
     name: string | null;
@@ -21,6 +24,11 @@ export interface IntentSuggestion {
     kind: "looking_for" | "offering";
     text: string;
 }
+/** The picks, plus the example starters rewritten for this person. */
+export interface IntentSuggestions {
+    suggestions: IntentSuggestion[];
+    examples: string[];
+}
 /**
  * Suggests a new member's first intents from their profile: two they might be
  * looking for and one they could offer. Follows the shared agent pattern:
@@ -31,7 +39,7 @@ export declare class IntentSuggester {
     constructor();
     /**
      * @param input - The person's profile and their active intents.
-     * @returns Two "looking_for" suggestions then one "offering", or null when the call fails.
+     * @returns Two "looking_for" suggestions then one "offering", with the rewritten examples; null when the call fails.
      */
-    invoke(input: IntentSuggestionInput): Promise<IntentSuggestion[] | null>;
+    invoke(input: IntentSuggestionInput): Promise<IntentSuggestions | null>;
 }

package/dist/internal/intents/intent.suggester.js

@@ -22,6 +22,9 @@ export const IntentSuggestionOutputSchema = z.object({
         .array(SuggestionText)
         .describe("Exactly two things they might want: someone to learn from, hire, fund, build with, or meet."),
     offering: SuggestionText.describe("One thing they could offer others: their skills, capital, time, or help."),
+    examples: z
+        .array(z.string().describe("One line, at most 110 characters, lowercase, no trailing period."))
+        .describe("Five to seven of the example starters, rewritten for this person in the same casual shape."),
 });
 // ─── Logger ───────────────────────────────────────────────────────────────────
 const logger = log.lib.from("IntentSuggester");
@@ -39,11 +42,32 @@ RULES:
 - Write each in their voice, first person implied, like they would type it:
   "looking for a technical cofounder who has shipped ml in production",
   "happy to give early founders feedback on their go-to-market".
-- Ground every suggestion in the profile: their work, field, stage, and place. Be concrete
-  enough that the right person would recognize themselves, but do not invent facts.
+- Ground every suggestion in the profile: their role and field. What we found may be old, so
+  stay at that level: never name a company, product, fund, school, or city, and leave out
+  details that go stale (stage, round, team size, dates). Do not invent facts.
 - One line each, at most 90 characters, lowercase, no trailing period, no emoji, no em dashes.
 - Skip anything that repeats one of their existing intents.
 - If the profile says little, still give three plausible, specific starting points.
+
+EXAMPLES:
+Also rewrite these generic starters for this person, keeping their short, casual
+"situation, want ..." shape:
+- traveling soon, want to meet cool people in ai
+- building something, want honest feedback on it
+- just launched, want cool people to try it
+- new in town, want to find my people
+- raising soon, want to meet investors who get it
+- hiring soon, want to meet great people early
+- have an idea, want someone to build it with
+Give each a light touch so it feels like theirs: swap the generic part for their broad field or
+role, nothing more. A founder in agent infrastructure might get "traveling soon, want to meet people
+building or investing in agents". Same limits as above: no company, product, fund, school, or city
+names, and nothing that would go stale. Keep them short and loose; one field word is usually enough.
+Swap any that do not fit their role for one that does: an investor does not raise, so "raising soon"
+becomes something like "deploying capital, want to meet founders in <their broad focus>"; someone who
+is not building does not launch. Drop any you cannot make fit, but always keep the traveling one.
+Return five to seven, each at most 90 characters, lowercase, no trailing period, no emoji, no em
+dashes, and none that repeat the three suggestions above.
 `;
 // ─── Agent class ──────────────────────────────────────────────────────────────
 /**
@@ -59,7 +83,7 @@ export class IntentSuggester {
     }
     /**
      * @param input - The person's profile and their active intents.
-     * @returns Two "looking_for" suggestions then one "offering", or null when the call fails.
+     * @returns Two "looking_for" suggestions then one "offering", with the rewritten examples; null when the call fails.
      */
     async invoke(input) {
         const clean = (text, max) => (text ?? "").replace(/\s+/g, " ").trim().slice(0, max);
@@ -81,10 +105,13 @@ export class IntentSuggester {
             const offering = tidy(parsed.data.offering);
             if (lookingFor.length < 2 || !offering)
                 return null;
-            return [
-                ...lookingFor.map((text) => ({ kind: "looking_for", text })),
-                { kind: "offering", text: offering },
-            ];
+            return {
+                suggestions: [
+                    ...lookingFor.map((text) => ({ kind: "looking_for", text })),
+                    { kind: "offering", text: offering },
+                ],
+                examples: parsed.data.examples.map(tidy).filter((text) => text && text.length <= 140).slice(0, 7),
+            };
         }
         catch (error) {
             logger.error("Error during execution", { error });

package/dist/internal/opportunities/opportunity.presentation.js

@@ -145,8 +145,9 @@ Rules:
 **Negotiation-grounded explanations (ONLY when NEGOTIATION CONTEXT is provided):**
 When NEGOTIATION CONTEXT is provided, this opportunity passed through an agent-to-agent negotiation. Use the transcript to ground your explanation in the concrete reasoning the agents exchanged.
 - Personalize the summary with *why* the negotiation produced this match — reference the roles the agents agreed on, the specific concerns raised, and how they were resolved.
-- For status "accepted": the agents agreed; the card should confidently explain *why* they agreed.
-- For status "rejected": the agents declined. The card should explain the reason briefly so the user understands — not dwell on it.
+- For status "pending": the agents agreed and the viewer decides; the card should confidently explain *why* they agreed.
+- For status "accepted": both people said yes; the card should explain *why* the agents agreed.
+- For status "rejected": say who ended it. If the negotiation says one agent declined, the agents did; otherwise a person passed. The card should explain the reason briefly so the user understands — not dwell on it.
 - Do NOT invent turn content. Only reference what is in the NEGOTIATION CONTEXT block.
 
 `;

package/dist/protocol/protocol.prompt.d.ts

@@ -5,7 +5,7 @@ export declare const NEGOTIATION_GUIDANCE = "You participate in the Index protoc
 export declare const CANONICAL_GUIDANCE_TOPICS: readonly ["identity-context", "intents", "communities-networks", "opportunities", "negotiations", "workflows"];
 export type CanonicalGuidanceTopic = (typeof CANONICAL_GUIDANCE_TOPICS)[number];
 /** Summary served when GET /api/docs has no topic. */
-export declare const CANONICAL_GUIDANCE_SUMMARY = "# Index Network Protocol\n\nIndex Network is a private, intent-driven discovery protocol. Users express intents, agents find matches within shared networks, and decisions proceed through clear gates.\n\n## Core Concepts\n\n**Identity & Context** \u2014 Account and presentation metadata plus scoped runtime state (networks, intents, stage).\n\n**Intents** \u2014 What users seek (intents, opportunities). Drive semantic matching.\n\n**Communities & Networks** \u2014 Private groups where members share intents and discover connections via shared membership.\n\n**Opportunities** \u2014 Discovered matches between users. Matches may be draft or negotiating; agreement advances to pending owner review, then accepted/rejected/expired.\n\n**Negotiations** \u2014 Agents coordinate, users approve. **A2A acceptance is not owner approval.** These are separate gates.\n\n**Workflows** \u2014 H2A (users express intents \u2192 agents discover) and A2A (agents coordinate) over the REST API. External agents use the Index CLI; the personal-agent runtime stays on the server. Human conversations are available through the conversation routes and commands.\n\n## Command interface\n\nUse the Index CLI with an explicit API origin: index --api-url <origin> ... --json.\nAuthenticate with browser login or one environment credential: INDEX_SESSION_TOKEN (Bearer) or INDEX_API_KEY (x-api-key). Keys do not bypass owner-session requirements.\nEvery capability is a named resource: /api/intents, /api/networks, /api/opportunities, /api/negotiations, /api/conversations, /api/scrape, /api/docs. The user's event stream is GET /api/events.\nUse the workflows topic for the resource routes and their CLI commands.\n\n## Canonical Topics\n\nRefer to these for detailed entity facts and lifecycle:\n\n- **identity-context** \u2014 Presentation identity, context scoping, matching inputs\n- **intents** \u2014 Intent inference, classification\n- **communities-networks** \u2014 Membership and explicit intent sharing\n- **opportunities** \u2014 Discovery, roles, reasoning\n- **negotiations** \u2014 Owner approval vs A2A, acceptance gates\n- **workflows** \u2014 H2A and A2A request sequences";
+export declare const CANONICAL_GUIDANCE_SUMMARY = "# Index Network Protocol\n\nIndex Network is a private, intent-driven discovery protocol. Users express intents, agents find matches within shared networks, and decisions proceed through clear gates.\n\n## Core Concepts\n\n**Identity & Context** \u2014 Account and presentation metadata plus scoped runtime state (networks, intents, stage).\n\n**Intents** \u2014 What users seek (intents, opportunities). Drive semantic matching.\n\n**Communities & Networks** \u2014 Private groups where members share intents and discover connections via shared membership.\n\n**Opportunities** \u2014 Discovered matches between users. Matches start negotiating; agreement advances to pending owner review, then accepted/rejected/expired.\n\n**Negotiations** \u2014 Agents coordinate, users approve. **A2A acceptance is not owner approval.** These are separate gates.\n\n**Workflows** \u2014 H2A (users express intents \u2192 agents discover) and A2A (agents coordinate) over the REST API. External agents use the Index CLI; the personal-agent runtime stays on the server. Human conversations are available through the conversation routes and commands.\n\n## Command interface\n\nUse the Index CLI with an explicit API origin: index --api-url <origin> ... --json.\nAuthenticate with browser login or one environment credential: INDEX_SESSION_TOKEN (Bearer) or INDEX_API_KEY (x-api-key). Keys do not bypass owner-session requirements.\nEvery capability is a named resource: /api/intents, /api/networks, /api/opportunities, /api/negotiations, /api/conversations, /api/scrape, /api/docs. The user's event stream is GET /api/events.\nUse the workflows topic for the resource routes and their CLI commands.\n\n## Canonical Topics\n\nRefer to these for detailed entity facts and lifecycle:\n\n- **identity-context** \u2014 Presentation identity, context scoping, matching inputs\n- **intents** \u2014 Intent inference, classification\n- **communities-networks** \u2014 Membership and explicit intent sharing\n- **opportunities** \u2014 Discovery, roles, reasoning\n- **negotiations** \u2014 Owner approval vs A2A, acceptance gates\n- **workflows** \u2014 H2A and A2A request sequences";
 /**
  * Detailed canonical topic content for GET /api/docs.
  * Indexed by topic name; each contains current entity, capability, and lifecycle facts.

package/dist/protocol/protocol.prompt.js

@@ -30,7 +30,7 @@ Index Network is a private, intent-driven discovery protocol. Users express inte
 
 **Communities & Networks** — Private groups where members share intents and discover connections via shared membership.
 
-**Opportunities** — Discovered matches between users. Matches may be draft or negotiating; agreement advances to pending owner review, then accepted/rejected/expired.
+**Opportunities** — Discovered matches between users. Matches start negotiating; agreement advances to pending owner review, then accepted/rejected/expired.
 
 **Negotiations** — Agents coordinate, users approve. **A2A acceptance is not owner approval.** These are separate gates.
 
@@ -131,16 +131,15 @@ Discovery is networked — it only finds matches within shared networks. This pr
 **Opportunity** is a discovered connection between two or more users based on complementary intents and shared network membership. Each opportunity has:
 - Parties (the people being connected)
 - Roles (party)
-- Status (draft or negotiating → pending owner review → accepted/rejected/expired)
+- Status (negotiating → pending owner review → accepted/rejected/expired)
 - Match reasoning (why they're a good fit)
 - Confidence score (0-1 from evaluation)
 
 ### Opportunity Lifecycle
-1. **Draft**: A persisted suggestion awaiting further action.
-2. **Negotiating**: Agents exchange structured turns under the negotiation rules.
-3. **Pending**: Agent agreement recommends a connection for separate owner review.
-4. **Accepted**: The required participant approvals permit the connection.
-5. **Rejected** or **Expired**: The opportunity no longer advances automatically.
+1. **Negotiating**: Agents exchange structured turns under the negotiation rules.
+2. **Pending**: Agent agreement recommends a connection for separate owner review. An owner's accept opens their chat right away; the status stays pending until every participant has accepted.
+3. **Accepted**: Every participant has accepted.
+4. **Rejected** or **Expired**: The opportunity no longer advances automatically. Expired means an intent was archived.
 
 ### Background Matching
 Approved intents are evaluated in the background. GET /api/opportunities only reviews persisted opportunities; it does not start matching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "66.0.0-rc.645.1",
+  "version": "66.0.0-rc.648.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",