@sunub/obsidian-mcp-server 0.0.10 → 0.1.0

package/README.md

@@ -14,6 +14,8 @@ Obsidian Vault를 이용해 AI가 활용 가능한 지식 베이스(Knowledge Ba
 ## 주요 기능
 
 - **고급 문서 탐색**: `vault` 도구를 통해 키워드 검색, 전체 목록 조회, 특정 문서 읽기, 통계 분석 등 다양한 탐색 기능을 제공합니다.
+- **컨텍스트 수집/기억 패킷 생성**: `vault collect_context`로 문서 배치 수집, 압축, continuation 토큰 발급, 메모리 패킷(JSON canonical)을 생성합니다.
+- **저장된 메모리 재호출**: `vault load_memory`로 `memory/resume_context.v1.md`를 빠르게 로드해 다음 턴 컨텍스트로 재사용할 수 있습니다.
 - **AI 기반 속성 생성**: `generate_property` 도구는 문서 본문을 분석하여 `title`, `tags`, `summary` 등 적절한 frontmatter 속성을 자동으로 생성합니다.
 - **안전한 속성 업데이트**: `write_property` 도구를 사용하여 생성된 속성을 기존 frontmatter와 병합하여 파일에 안전하게 기록합니다.
 - **첨부 파일 자동 정리**: `organize_attachments` 도구는 문서와 연결된 첨부 파일(예: 이미지)을 자동으로 감지하여 문서 제목에 맞는 폴더로 이동시키고 링크를 업데이트합니다.
@@ -32,6 +34,8 @@ Vault 내 문서를 탐색하고 분석하는 핵심 도구입니다. `action`
 - **`search`**: 키워드를 기반으로 문서 제목, 내용, 태그를 검색합니다.
 - **`read`**: 특정 파일의 내용을 읽고 frontmatter와 본문을 반환합니다.
 - **`stats`**: Vault 내 모든 문서의 통계(단어, 글자 수 등)를 제공합니다.
+- **`collect_context`**: 문서를 배치 처리하여 메모리 패킷을 생성하고, 필요 시 `memory/resume_context.v1.md`에 저장합니다.
+- **`load_memory`**: 저장된 메모리 노트의 canonical JSON 블록을 파싱하여 빠른 재주입용 payload를 반환합니다.
 
 ### `generate_property`
 
@@ -49,6 +53,70 @@ Vault 내 문서를 탐색하고 분석하는 핵심 도구입니다. `action`
 
 키워드로 문서를 찾아 해당 문서에 연결된 모든 첨부 파일을 `images/{문서 제목}` 폴더로 이동시키고, 문서 내의 링크를 자동으로 업데이트합니다.
 
+## 메모리 운영 원칙
+
+### 서버와 에이전트 책임 분리
+
+- **MCP 서버(Data Plane)**: 검색, 읽기, 압축, continuation, memory packet 생성/저장까지 담당합니다.
+- **에이전트 런타임(Memory Plane)**: 사용자 의도 감지, `load_memory` 자동 호출, 다음 턴 프롬프트 선주입을 담당합니다.
+
+중요: 서버만으로는 "다음 턴 자동 기억 반영"을 보장할 수 없습니다. 이 동작은 반드시 클라이언트/에이전트 런타임에서 구현해야 합니다.
+
+### 메모리 산출물 포맷
+
+- 기본 저장 경로: `memory/resume_context.v1.md`
+- 구성: 사람이 읽는 Markdown 요약 + AI 파싱용 canonical JSON code block
+- 스키마 키: `schema_version`, `generated_at`, `source_hash`, `documents[].doc_hash`, `memory_packet`
+
+## collect_context 추천 프리셋
+
+| 목적 | 주요 파라미터 | 권장 값 |
+| --- | --- | --- |
+| 빠른 토픽 스캔 | `scope`, `maxDocs`, `maxCharsPerDoc`, `compressionMode` | `topic`, `8`, `700`, `aggressive` |
+| 이력서 컨텍스트 구축 | `scope`, `maxDocs`, `maxCharsPerDoc`, `memoryMode`, `compressionMode` | `all`, `20`, `1200`, `both`, `balanced` |
+| 장문 Vault 단계 처리 | `maxDocs`, `maxCharsPerDoc`, `maxOutputChars` | `10`, `900`, `2800` |
+
+가드레일은 출력 상한 초과 시 다음 순서로 축소됩니다: `backlinks -> per-doc chars -> doc count -> continuation`.
+
+## 예제 MCP 요청 (3개)
+
+아래는 MCP 클라이언트의 `callTool`에 전달하는 `arguments` 예시입니다.
+
+### 1) 전체 Vault에서 메모리 구축 시작
+
+```json
+{
+  "action": "collect_context",
+  "scope": "all",
+  "maxDocs": 20,
+  "maxCharsPerDoc": 1200,
+  "memoryMode": "both",
+  "compressionMode": "balanced"
+}
+```
+
+### 2) continuationToken으로 다음 배치 이어서 수집
+
+```json
+{
+  "action": "collect_context",
+  "continuationToken": "<previous_response.batch.continuation_token>",
+  "compressionMode": "balanced"
+}
+```
+
+### 3) 저장된 메모리 빠른 로드(quiet)
+
+```json
+{
+  "action": "load_memory",
+  "memoryPath": "memory/resume_context.v1.md",
+  "quiet": true
+}
+```
+
+클라이언트 자동 주입 규칙은 `docs/CLIENT_INJECTION_GUIDE.md`를 참고하세요.
+
 ## 설치 및 사용
 
 ### MCP 클라이언트 설정
@@ -138,6 +206,30 @@ npm test
 npm run test:watch
 ```
 
+### 비용 계측(B1)
+
+`VAULT_METRICS_LOG_PATH`를 지정하면 `vault` 도구 응답마다 아래 메트릭이 JSONL로 기록됩니다.
+
+- `estimated_tokens`
+- `mode`
+- `truncated`
+- `doc_count`
+
+예시:
+
+```bash
+# 1) 메트릭 로그 경로 지정
+export VAULT_METRICS_LOG_PATH=.tmp/vault-metrics.jsonl
+
+# 2) 평소처럼 MCP 시나리오 실행 (search/read/collect_context/load_memory)
+npm run inspector
+
+# 3) 시나리오 종료 후 리포트 생성
+npm run metrics:report -- .tmp/vault-metrics.jsonl
+```
+
+리포트는 액션별 `count`, `total_tokens`, `avg/p95_tokens`, `avg_doc_count`, `truncated_rate(%)`를 출력합니다.
+
 ### 코드 품질
 
 ```bash

package/build/server.js

@@ -12,17 +12,18 @@ export default function createMcpServer() {
             tools: { listChanged: false },
         },
         instructions: `
-        This server provides access to Obsidian vault documents and related tools.
-        
-        Available tools:
-        - obsidian_content_getter: Search, read, and analyze vault documents
-        
-        Available resources:
-        - docs://{filename}: Read specific documents from the vault
-        
-        Environment requirements:
-        - VAULT_DIR_PATH: Path to your Obsidian vault directory
-      `,
+	        This server provides access to Obsidian vault documents and related tools.
+	        
+	        Available tools:
+	        - vault: Search, read, and list markdown documents in the vault
+	        - generate_property: Generate frontmatter property suggestions from document content
+	        - write_property: Write frontmatter properties to a markdown file
+	        - create_document_with_properties: Two-step workflow for AI-generated properties and write
+	        - organize_attachments: Move linked attachments and update markdown links
+	        
+	        Environment requirements:
+	        - VAULT_DIR_PATH: Path to your Obsidian vault directory
+	      `,
     });
     for (const tool of Object.values(tools)) {
         tool.register(mcpServer);

package/build/tools/create_document_with_properties/index.js

@@ -9,11 +9,12 @@ export const annotations = {
     openWorldHint: true,
 };
 export const description = `
-  Initiates an integrated workflow to read a document, guide an AI to generate properties, and then write those properties to a file.
+  Starts and completes a two-step workflow for AI-generated frontmatter properties.
 
-  This tool acts as a workflow manager for an AI agent. It reads the content of a specified document and returns a structured, multi-step plan. The AI agent must follow this plan by first calling the 'generate_obsidian_property' tool to get the document's content for analysis, and then, after generating the properties, calling the 'write_obsidian_property' tool to save them.
+  Step 1: Call this tool with sourcePath (and optional outputPath). It returns a structured instruction payload and a content preview for AI analysis.
+  Step 2: Call this same tool again with aiGeneratedProperties. The tool then writes those properties by executing the same write logic used by the 'write_property' tool.
 
-  Use this tool to start the end-to-end process of enriching a document with AI-generated metadata.
+  Use this tool when an AI agent should orchestrate analysis and write in a consistent workflow.
 `;
 export const register = (mcpServer) => {
     mcpServer.registerTool(name, {

package/build/tools/generate_property/index.js

@@ -3,43 +3,19 @@ import { getGlobalVaultManager } from "../../utils/getVaultManager.js";
 import { obsidianPropertyQueryParamsSchema, } from "./params.js";
 export const name = "generate_property";
 export const annotations = {
-    title: "Obsidian Property Writer",
+    title: "Generate Obsidian Property",
     openWorldHint: true,
 };
 export const description = `
-  Analyzes the content of a specified Obsidian Markdown file to automatically generate the most suitable properties (frontmatter) and updates the file directly.
+  Reads a target markdown document and returns an AI-facing payload for generating frontmatter properties.
+
+  This tool does not write to disk. It returns content_preview and a target output schema so an AI can produce a valid property object.
 
   Use Cases:
-  
-  - After Completing a Draft: Use when the body of the text is complete, and you want to generate all properties at once.
-  - Updating Information: Use when you want to update existing properties with more accurate information reflecting the latest content.
-  - Completing Missing Info: Use when you want to automatically add missing properties like tags or a summary to a document that only has a title.
-  
-  Parameters:
-  
-  filename: The name or path of the file to analyze and add properties to (e.g., "my-first-post.md").
-  overwrite: If set to true, existing properties will be overwritten by the AI-generated content. Default: false.
-  
-  Generated Properties:
-  
-  The AI analyzes the context of the content to generate the following properties:
-  
-  - aliases: An array of alternative names or synonyms based on the content.
-  - title: A title that best represents the core topic of the document.
-  - tags: An array of tags extracted from the core keywords of the content (e.g., [AI, Obsidian, productivity]).
-  - summary: A one to two-sentence summary of the entire document.
-  - slug: A hyphenated-string suitable for URLs, containing the core keywords from the content.
-  - date: The event date or creation date inferred from the content (in ISO 8601 format).
-  - completed: A boolean (true or false) indicating whether the content is considered a final version.
-  
-  Return Value:
-  
-  Upon success, returns a JSON object containing a success message that includes the modified filename.
-  { "status": "success", "message": "Successfully updated properties for my-first-post.md" }
-  
-  Requirements:
-  
-  The user's absolute path to the Obsidian vault must be correctly set in an environment variable.
+  - After completing a draft, when you need property suggestions from content.
+  - When missing frontmatter fields (title, tags, summary, slug, date, category, completed) should be generated.
+
+  To apply generated properties to a file, call 'write_property' with the resulting JSON.
 `;
 export const register = (mcpServer) => {
     mcpServer.registerTool(name, {
@@ -68,7 +44,7 @@ export const execute = async (params) => {
             content_preview: `${document.content.substring(0, 300).replace(/\s+/g, " ")}...`,
             instructions: {
                 purpose: "Generate or update the document's frontmatter properties based on its content.",
-                usage: "Analyze the provided content_preview. If more detail is needed to generate accurate properties, you MUST first call the 'obsidian_vault' tool with the 'read' action to get the full document content.",
+                usage: "Analyze the provided content_preview. If more detail is needed to generate accurate properties, you MUST call the 'vault' tool with action='read' to get the full document content.",
                 content_type: "markdown",
                 overwrite: params.overwrite || false,
                 output_format: "Return a JSON object with the following structure",

package/build/tools/vault/index.js

@@ -1,8 +1,9 @@
 import state from "../../config.js";
 import { createToolError } from "../../utils/createToolError.js";
 import { getGlobalVaultManager } from "../../utils/getVaultManager.js";
+import { recordVaultResponseMetric } from "./metrics.js";
 import { obsidianContentQueryParamsZod, } from "./params.js";
-import { listAllDocuments, readSpecificFile, searchDocuments, statsAllDocuments, } from "./utils.js";
+import { collectContext, listAllDocuments, loadMemory, readSpecificFile, searchDocuments, statsAllDocuments, } from "./utils.js";
 export const name = "vault";
 export const annotations = {
     title: "Obsidian Content Getter",
@@ -44,24 +45,37 @@ export const execute = async (params) => {
         return createToolError(e.message);
     }
     try {
+        let result;
         switch (params.action) {
             case "search":
                 if (!params.keyword?.trim()) {
                     return createToolError("keyword parameter is required for search action", 'Provide a keyword, e.g. { action: "search", keyword: "project" }');
                 }
-                return await searchDocuments(vaultManager, params);
+                result = await searchDocuments(vaultManager, params);
+                break;
             case "read":
                 if (!params.filename?.trim()) {
                     return createToolError("filename parameter is required for read action", 'Provide a filename, e.g. { action: "read", filename: "meeting-notes.md" }');
                 }
-                return await readSpecificFile(vaultManager, params);
+                result = await readSpecificFile(vaultManager, params);
+                break;
             case "list_all":
-                return await listAllDocuments(vaultManager, params);
+                result = await listAllDocuments(vaultManager, params);
+                break;
             case "stats":
-                return await statsAllDocuments(vaultManager);
+                result = await statsAllDocuments(vaultManager);
+                break;
+            case "collect_context":
+                result = await collectContext(vaultManager, params);
+                break;
+            case "load_memory":
+                result = await loadMemory(vaultManager, params);
+                break;
             default:
-                return createToolError(`Unknown action: ${params.action}`, "Valid actions are: search, read, list_all, stats");
+                return createToolError(`Unknown action: ${params.action}`, "Valid actions are: search, read, list_all, stats, collect_context, load_memory");
         }
+        await recordVaultResponseMetric(params.action, result);
+        return result;
     }
     catch (error) {
         return createToolError(`Execution failed: ${error instanceof Error ? error.message : String(error)}`);

package/build/tools/vault/metrics.js

@@ -0,0 +1,126 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+function isJsonObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseFirstTextPayload(result) {
+    if (!Array.isArray(result.content)) {
+        return null;
+    }
+    let textPayload = null;
+    for (const chunk of result.content) {
+        if (chunk.type !== "text") {
+            continue;
+        }
+        if (!("text" in chunk) || typeof chunk.text !== "string") {
+            continue;
+        }
+        textPayload = chunk.text;
+        break;
+    }
+    if (!textPayload)
+        return null;
+    try {
+        const parsed = JSON.parse(textPayload);
+        return isJsonObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseCompression(compression) {
+    if (!isJsonObject(compression)) {
+        return null;
+    }
+    const mode = compression.mode;
+    const estimatedTokens = compression.estimated_tokens;
+    const truncated = compression.truncated;
+    const outputChars = compression.output_chars;
+    const sourceChars = compression.source_chars;
+    const maxOutputChars = compression.max_output_chars;
+    if ((mode !== "aggressive" && mode !== "balanced" && mode !== "none") ||
+        typeof estimatedTokens !== "number" ||
+        typeof truncated !== "boolean" ||
+        typeof outputChars !== "number" ||
+        typeof sourceChars !== "number" ||
+        (maxOutputChars !== null && typeof maxOutputChars !== "number")) {
+        return null;
+    }
+    return {
+        mode,
+        estimated_tokens: Math.max(0, Math.floor(estimatedTokens)),
+        truncated,
+        output_chars: Math.max(0, Math.floor(outputChars)),
+        source_chars: Math.max(0, Math.floor(sourceChars)),
+        max_output_chars: maxOutputChars === null ? null : Math.max(0, Math.floor(maxOutputChars)),
+    };
+}
+function inferDocCount(action, payload) {
+    if (Array.isArray(payload.documents)) {
+        return payload.documents.length;
+    }
+    if (typeof payload.documents_count === "number") {
+        return Math.max(0, Math.floor(payload.documents_count));
+    }
+    if (action === "search" && typeof payload.found === "number") {
+        return Math.max(0, Math.floor(payload.found));
+    }
+    if (action === "read" &&
+        (typeof payload.filename === "string" ||
+            typeof payload.fullPath === "string" ||
+            typeof payload.filePath === "string")) {
+        return 1;
+    }
+    return 0;
+}
+function parseCacheHit(payload) {
+    if (!isJsonObject(payload.cache)) {
+        return undefined;
+    }
+    if (typeof payload.cache.hit !== "boolean") {
+        return undefined;
+    }
+    return payload.cache.hit;
+}
+export function buildVaultResponseMetric(action, result) {
+    if (result.isError) {
+        return null;
+    }
+    const payload = parseFirstTextPayload(result);
+    if (!payload) {
+        return null;
+    }
+    const compression = parseCompression(payload.compression);
+    if (!compression) {
+        return null;
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        action,
+        mode: compression.mode,
+        estimated_tokens: compression.estimated_tokens,
+        truncated: compression.truncated,
+        doc_count: inferDocCount(action, payload),
+        output_chars: compression.output_chars,
+        source_chars: compression.source_chars,
+        max_output_chars: compression.max_output_chars,
+        cache_hit: parseCacheHit(payload),
+    };
+}
+export async function recordVaultResponseMetric(action, result) {
+    const logPath = process.env.VAULT_METRICS_LOG_PATH?.trim();
+    if (!logPath) {
+        return;
+    }
+    const metric = buildVaultResponseMetric(action, result);
+    if (!metric) {
+        return;
+    }
+    try {
+        await mkdir(dirname(logPath), { recursive: true });
+        await appendFile(logPath, `${JSON.stringify(metric)}\n`, "utf8");
+    }
+    catch {
+        // Metrics logging should never fail tool execution.
+    }
+}

package/build/tools/vault/params.js

@@ -2,14 +2,30 @@ import { z } from "zod";
 export const responseTypeSchema = z
     .enum(["text", "audio", "image", "resource", "resource_link"])
     .describe("The type of content being returned");
+export const compressionModeSchema = z
+    .enum(["aggressive", "balanced", "none"])
+    .default("balanced")
+    .describe("Compression strategy for tool output. aggressive: smallest output, balanced: default, none: keep as much original content as possible.");
+const maxOutputCharsSchema = z
+    .number()
+    .min(500)
+    .max(12000)
+    .describe("Optional hard cap for output size in characters. Helps control token cost in long responses.");
 const quietMode = z
     .boolean()
     .default(true)
     .describe("If true, suppresses non-error output messages. Default is false.");
 // input properties schema
 export const obsidianContentActions = z
-    .enum(["search", "read", "list_all", "stats"])
-    .describe("The action to perform: search documents, read specific file, list all content, or get stats");
+    .enum([
+    "search",
+    "read",
+    "list_all",
+    "stats",
+    "collect_context",
+    "load_memory",
+])
+    .describe("The action to perform: search documents, read specific file, list all content, get stats, collect contextual memory packets, or load stored memory");
 export const obsidianContentKeyword = z
     .string()
     .describe("Keyword to search for in documents (required for search action)");
@@ -35,6 +51,39 @@ export const obsidianContentExcerptLength = z
     .max(2000)
     .default(500)
     .describe("Length of content excerpt to include in search results (default: 500)");
+export const obsidianContentTopic = z
+    .string()
+    .min(1)
+    .describe("Topic to collect contextual memory for (collect_context action)");
+export const obsidianContentScope = z
+    .enum(["topic", "all"])
+    .default("topic")
+    .describe("Scope for collect_context. topic: collect docs relevant to topic, all: collect from the entire vault.");
+export const obsidianContentMaxDocs = z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Maximum number of documents to process for collect_context");
+export const obsidianContentMaxCharsPerDoc = z
+    .number()
+    .int()
+    .min(200)
+    .max(8000)
+    .default(1800)
+    .describe("Maximum number of characters extracted per document for collect_context");
+export const obsidianContentMemoryMode = z
+    .enum(["response_only", "vault_note", "both"])
+    .default("response_only")
+    .describe("Memory output mode for collect_context. response_only: return packet only, vault_note: save to vault note only, both: return and save.");
+export const obsidianContentContinuationToken = z
+    .string()
+    .min(1)
+    .describe("Continuation token to resume a previous collect_context batch operation");
+export const obsidianContentMemoryPath = z
+    .string()
+    .describe("Path to a stored memory note for load_memory (default: memory/resume_context.v1.md)");
 // input schema
 export const obsidianContentQueryParamsZod = z.object({
     action: obsidianContentActions,
@@ -44,6 +93,15 @@ export const obsidianContentQueryParamsZod = z.object({
     includeContent: obsidianContentIncludeContent.optional(),
     includeFrontmatter: obsidianContentIncludeFrontmatter.optional(),
     excerptLength: obsidianContentExcerptLength.optional(),
+    topic: obsidianContentTopic.optional(),
+    scope: obsidianContentScope.optional(),
+    maxDocs: obsidianContentMaxDocs.optional(),
+    maxCharsPerDoc: obsidianContentMaxCharsPerDoc.optional(),
+    memoryMode: obsidianContentMemoryMode.optional(),
+    continuationToken: obsidianContentContinuationToken.optional(),
+    memoryPath: obsidianContentMemoryPath.optional(),
+    compressionMode: compressionModeSchema.optional(),
+    maxOutputChars: maxOutputCharsSchema.optional(),
     quiet: quietMode.optional(),
 });
 export const aiInstructionsSchema = z

package/build/tools/vault/types/collect_context.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { compressionModeSchema, responseTypeSchema } from "../params.js";
+export const collectContextScopeSchema = z.enum(["topic", "all"]);
+export const collectContextMemoryModeSchema = z.enum([
+    "response_only",
+    "vault_note",
+    "both",
+]);
+export const collectContextRelevanceSchema = z.enum(["high", "medium", "low"]);
+export const collectContextTokenV1Schema = z.object({
+    v: z.literal(1),
+    cursor: z.number().int().min(0),
+    scope: collectContextScopeSchema,
+    topic: z.string().nullable(),
+    maxDocs: z.number().int().min(1),
+    maxCharsPerDoc: z.number().int().min(200),
+    memoryMode: collectContextMemoryModeSchema,
+});
+export const collectContextDocumentSchema = z.object({
+    filename: z.string(),
+    fullPath: z.string(),
+    title: z.string(),
+    tags: z.array(z.string()),
+    doc_hash: z.string(),
+    summary: z.string(),
+    excerpt: z.string(),
+    evidence_snippets: z.array(z.string()),
+    relevance: collectContextRelevanceSchema,
+    stats: z.object({
+        contentLength: z.number().int().nonnegative(),
+        wordCount: z.number().int().nonnegative(),
+        hasContent: z.boolean(),
+    }),
+    backlinks_count: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+});
+export const collectContextMemoryPacketSchema = z.object({
+    topicSummary: z.string(),
+    keyFacts: z.array(z.string()),
+    experienceBullets: z.array(z.string()),
+    sourceRefs: z.array(z.object({
+        filePath: z.string(),
+        title: z.string(),
+        relevance: collectContextRelevanceSchema,
+        evidenceSnippets: z.array(z.string()),
+    })),
+    openQuestions: z.array(z.string()),
+    confidence: z.number().min(0).max(1),
+});
+export const collectContextPayloadSchema = z.object({
+    action: z.literal("collect_context"),
+    scope: collectContextScopeSchema,
+    topic: z.string().nullable(),
+    matched_total: z.number().int().nonnegative(),
+    total_in_vault: z.number().int().nonnegative(),
+    documents: z.array(collectContextDocumentSchema),
+    memory_packet: collectContextMemoryPacketSchema,
+    memory_mode: collectContextMemoryModeSchema,
+    memory_write: z.object({
+        requested: z.boolean(),
+        status: z.enum(["not_requested", "written", "failed"]),
+        note_path: z.string().optional(),
+        generated_at: z.string().optional(),
+        source_hash: z.string().optional(),
+        reason: z.string().optional(),
+    }),
+    cache: z
+        .object({
+        key: z.string(),
+        hit: z.boolean(),
+        schema_version: z.string(),
+        topic: z.string().nullable(),
+        doc_hash: z.string(),
+        mode: collectContextMemoryModeSchema,
+    })
+        .optional(),
+    batch: z.object({
+        start_cursor: z.number().int().nonnegative(),
+        processed_docs: z.number().int().nonnegative(),
+        consumed_candidates: z.number().int().nonnegative(),
+        max_docs: z.number().int().positive(),
+        max_chars_per_doc: z.number().int().min(200),
+        has_more: z.boolean(),
+        continuation_token: z.string().nullable(),
+    }),
+});
+export const collectContextCompressionSchema = z.object({
+    mode: compressionModeSchema,
+    source_chars: z.number().int().nonnegative(),
+    output_chars: z.number().int().nonnegative(),
+    estimated_tokens: z.number().int().nonnegative(),
+    max_output_chars: z.number().int().positive().nullable(),
+    truncated: z.boolean(),
+    expand_hint: z.string(),
+});
+export const collectContextResponseDataSchema = collectContextPayloadSchema.extend({
+    compression: collectContextCompressionSchema,
+});
+export const collectContextResponseSchema = z.object({
+    type: responseTypeSchema,
+    text: collectContextResponseDataSchema,
+});