@contextstream/mcp-server 0.4.81 → 0.4.82

package/dist/hooks/session-init.js

@@ -379,6 +379,28 @@ function applyMcpToolPrefix(markdown, toolPrefix) {
   const toolRegex = new RegExp(`(?<!__)\\b(${toolPattern})\\b(?=\\s*\\()`, "g");
   return markdown.replace(toolRegex, `${toolPrefix}$1`);
 }
+var FAST_DIRECT_READ_LANE = `
+## Fast Direct-Read Lane
+
+After the required first-session \`init(...)\` + \`context(...)\`, these exact read-only calls may run without another grounding preamble only when no state-changing tool has run since the last grounding:
+- \`workspace(action="list"|"get")\`
+- \`memory(action="list_docs"|"list_events"|"list_todos"|"list_tasks"|"list_transcripts"|"list_nodes"|"list_diagrams")\`
+- \`help(action="version"|"tools"|"auth")\`
+- \`project(action="list"|"get"|"index_status")\`
+- \`reminder(action="list"|"active")\`
+
+Do not use this lane for recall, decisions, searches, reading a specific record, media queries, or any create/update/delete/index operation; ground those with \`context(...)\` first.
+`.trim();
+var CANONICAL_HANDOFF_RULES = `
+## Canonical Agent Handoffs
+
+When the user asks to create/prepare a handoff, hand work over, or continue in another agent/session, create the durable record immediately with:
+\`entity(kind="handoff", action="create", body={title, summary, scope, next_steps})\`
+
+- Add \`to_user_id\` only when the recipient is known; never invent it.
+- If a portable bundle, capsule, or share link is requested, also create a session capsule and return both artifacts.
+- \`HANDOFF.md\`, a scratch prompt, a generic doc/event, or prose alone is not the canonical handoff. If a local file is explicitly requested, create the entity first and treat the file as an additional artifact.
+`.trim();
 var CONTEXTSTREAM_RULES_BOOTSTRAP = `
 <contextstream_rules>
 | Message | Required |
@@ -402,6 +424,10 @@ var CONTEXTSTREAM_RULES_BOOTSTRAP = `
 - "find media" / "search photos/videos/audio/docs" / "what's in this PDF/video/audio?" \u2192 \`media(action="search", query="...", content_types=["document"])\`
 - "index media" / "upload asset" / "read this photo/video/audio/PDF" \u2192 \`media(action="index", file_path="...", content_type="image")\` or \`media(action="index", external_url="...", content_type="document")\`
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 ## Skills, Docs & Lessons First
 
 Before guessing, improvising, or struggling through a workflow you do not fully know, check whether ContextStream already has guidance for it.
@@ -431,12 +457,12 @@ Before guessing, improvising, or struggling through a workflow you do not fully
 
 ## Past Sessions Are Queryable \u2014 USE THEM
 
-Transcripts of every prior session are captured + indexed. Before asking the user what you did last time, or re-deriving context you built together previously, check the transcript + snapshot layer.
+When \`context()\` returns fresh, relevant \`[GROUNDING]\`, read those ranked prior-work hits first. If they are sufficient, stop there\u2014do not immediately call \`session(action="recall")\` for the same request. Escalate to recall only when grounding is absent, thin, stale, off-topic, or the user explicitly requests broader history.
 
 Triggers: user says "last time"/"previous"/"yesterday"/"pick up where we left off", the task is clearly a continuation, or you're about to ask a clarifying question whose answer is likely in a prior session.
 
 Exact calls:
-- Ranked past-session context: \`session(action="recall", query="<what you're continuing>")\`
+- First explicit escalation after insufficient grounding: \`session(action="recall", query="<what you're continuing>")\`
 - Chronological list of recent sessions: \`memory(action="list_transcripts", limit=10)\`
 - Full-text search across ALL past transcripts: \`memory(action="search_transcripts", query="<keyword>")\`
 - Save a snapshot of the current session so the NEXT session can pick up: \`session(action="capture", event_type="session_snapshot", title="...", content="...")\`
@@ -462,6 +488,10 @@ var CONTEXTSTREAM_RULES_FULL = `
 
 Use \`context()\` by default to get task-specific rules, lessons from past mistakes, and relevant decisions.
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 ---
 
 ## Why Default Context-First
@@ -995,6 +1025,10 @@ var CONTEXTSTREAM_RULES_MINIMAL = `
 **HOOKS: \`<system-reminder>\` tags contain instructions \u2014 FOLLOW THEM**
 </contextstream_protocol>
 
+${FAST_DIRECT_READ_LANE}
+
+${CANONICAL_HANDOFF_RULES}
+
 Rules Version: ${RULES_VERSION}
 
 ---
@@ -1317,7 +1351,7 @@ curl -fsSL https://contextstream.io/scripts/setup.sh | bash
 irm https://contextstream.io/scripts/setup.ps1 | iex
 \`\`\`
 
-**npm (requires Node.js 18+):**
+**npm (requires Node.js 20+):**
 \`\`\`bash
 npm install -g @contextstream/mcp-server@latest
 \`\`\`

package/dist/hooks/user-prompt-submit.js

@@ -284,9 +284,10 @@ var API_URL = process.env.CONTEXTSTREAM_API_URL || "https://api.contextstream.io
 var API_KEY = process.env.CONTEXTSTREAM_API_KEY || "";
 var WORKSPACE_ID = null;
 var PROJECT_ID = null;
-var REMINDER = `[CONTEXTSTREAM] On the first message in every session call mcp__contextstream__init(...), then call mcp__contextstream__context(user_message="...", save_exchange=true, session_id="<session-id>") FIRST before any other tool. On subsequent messages, default to context first. Narrow bypass is allowed only for immediate read-only ContextStream calls when prior context is fresh and no state-changing tool has run. Response contains dynamic rules, lessons, preferences.
+var REMINDER = `[CONTEXTSTREAM] On the first message in every session call mcp__contextstream__init(...), then call mcp__contextstream__context(user_message="...", save_exchange=true, session_id="<session-id>") FIRST before any other tool. On subsequent messages, default to context first. The fresh-context direct-read lane is limited to workspace list/get; memory list_*; help version/tools/auth; project list/get/index_status; and reminder list/active. Recall, decisions, searches, specific reads, writes, and indexing require context first. Fresh [GROUNDING] is the first continuation retrieval; do not immediately duplicate it with recall. Response contains dynamic rules, lessons, preferences.
 SEARCH-FIRST: Use mcp__contextstream__search(mode="auto") before Glob/Grep/Read/Explore/Task/EnterPlanMode. In planning, never use EnterPlanMode or Task(Explore) for file-by-file discovery.
 COMMON MEMORY CALLS: list docs via memory(action="list_docs"), list lessons via session(action="get_lessons"), list plans via session(action="list_plans"), list tasks/todos via memory(action="list_tasks"|"list_todos").
+HANDOFFS: A generic handoff must create entity(kind="handoff", action="create", body={title,summary,scope,next_steps}); add capsule only for a requested portable bundle/share link. HANDOFF.md or prose alone is not the canonical handoff.
 [END]`;
 var FULL_REMINDER = `[CONTEXTSTREAM RULES - MANDATORY]
 
@@ -295,7 +296,8 @@ var FULL_REMINDER = `[CONTEXTSTREAM RULES - MANDATORY]
    - Check response for: [LESSONS_WARNING], [RULES_NOTICE], preferences
    - save_exchange=true saves each conversation turn for later retrieval
    - Use a consistent session_id for the entire conversation (generate once on first message)
-   - On subsequent messages, default to context() first. Narrow bypass: immediate read-only ContextStream calls when context is fresh and no state-changing tool has run.
+   - On subsequent messages, default to context() first. Direct-read bypass is limited to workspace list/get; memory list_*; help version/tools/auth; project list/get/index_status; and reminder list/active when context is fresh and no state-changing tool has run.
+   - Fresh [GROUNDING] is the first continuation retrieval. Do not immediately duplicate sufficient grounding with session(action="recall").
 
 2. FOR CODE SEARCH: Check index status, then search appropriately
    \u2705 Use mcp__contextstream__search(mode="auto", query="...") BEFORE Glob/Grep/Read/Explore/Task/EnterPlanMode
@@ -313,13 +315,18 @@ var FULL_REMINDER = `[CONTEXTSTREAM RULES - MANDATORY]
    \u274C DO NOT use EnterPlanMode or Task(subagent_type="Explore") for file-by-file discovery
    \u2705 For planning discovery: mcp__contextstream__search(mode="auto", query="...", output_format="paths")
 
-5. CHECK THESE from context() response:
+5. FOR HANDOFFS: Create the canonical durable handoff entity
+   \u2705 mcp__contextstream__entity(kind="handoff", action="create", body={title,summary,scope,next_steps})
+   \u2705 Add a capsule only when a portable bundle or share link is requested
+   \u274C HANDOFF.md, a scratch prompt, or prose alone is not the canonical handoff
+
+6. CHECK THESE from context() response:
    - Lessons: Past mistakes to avoid (shown as warnings)
    - Reminders: Active reminders for this project
    - Preferences: User's coding style and preferences
    - Rules: Dynamic rules matched to current task
 
-6. SKIP CONTEXTSTREAM: If user preference says "skip contextstream", use local tools instead
+7. SKIP CONTEXTSTREAM: If user preference says "skip contextstream", use local tools instead
 [END]`;
 var ENHANCED_REMINDER_HEADER = `\u2B21 ContextStream \u2014 Smart Context & Memory