@arbidocs/sdk 0.1.0 → 0.3.1

package/README.md

@@ -159,62 +159,6 @@ async function main() {
 main()
 ```
 
-### Build an MCP Server or CLI Tool
-
-```typescript
-import 'fake-indexeddb/auto'
-import { createArbiClient, getSession, sealedBoxDecrypt,
-         deriveEncryptionKeypairFromSigning, createWorkspaceKeyHeader } from '@arbidocs/sdk'
-
-// Reusable helper: select a workspace and set up the crypto header
-async function selectWorkspace(arbi, workspaceId, serverSessionKey) {
-  // Fetch workspaces to get the wrapped key
-  const { data: workspaces } = await arbi.fetch.GET('/api/user/workspaces')
-  const ws = workspaces.find(w => w.external_id === workspaceId)
-  if (!ws?.wrapped_key) throw new Error(`Workspace ${workspaceId} not found`)
-
-  const session = await getSession()
-  const pubKey = session.signingPrivateKey.slice(32, 64)
-  const encKP = deriveEncryptionKeypairFromSigning({
-    publicKey: pubKey,
-    secretKey: session.signingPrivateKey,
-  })
-  const wsKey = sealedBoxDecrypt(ws.wrapped_key, encKP.secretKey)
-  const header = await createWorkspaceKeyHeader(wsKey, serverSessionKey)
-
-  arbi.session.setSelectedWorkspace(workspaceId)
-  arbi.session.setCachedWorkspaceHeader(workspaceId, header)
-}
-
-// Example: CLI that searches documents
-async function searchDocuments(query: string) {
-  const arbi = createArbiClient({
-    baseUrl: process.env.ARBI_API_URL!,
-    deploymentDomain: process.env.ARBI_DOMAIN!,
-    credentials: 'omit',
-  })
-
-  const { serverSessionKey } = await arbi.auth.login({
-    email: process.env.ARBI_EMAIL!,
-    password: process.env.ARBI_PASSWORD!,
-  })
-
-  await selectWorkspace(arbi, process.env.ARBI_WORKSPACE!, serverSessionKey)
-
-  // Use the assistant API to ask a question about your documents
-  const { data } = await arbi.fetch.POST('/api/assistant/query', {
-    body: {
-      workspace_ext_id: process.env.ARBI_WORKSPACE!,
-      query,
-    },
-  })
-
-  console.log(data)
-}
-
-searchDocuments('What are the key terms of the contract?')
-```
-
 ### Subscribe to Session State Changes
 
 The SDK's `SessionManager` supports a subscribe pattern for reactive updates:

package/dist/index.d.cts

@@ -1038,6 +1038,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/api/health/mcp-tools': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Mcp Tools
+         * @description Returns available MCP tools registered on the LiteLLM proxy.
+         */
+        get: operations['get_mcp_tools'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/api/tag/': {
         parameters: {
             query?: never;
@@ -1288,24 +1308,32 @@ interface components {
          * @description A single agent step with a sequential index.
          *
          *     Tool call steps have a detail list; lifecycle steps have a step string.
+         *     The focus field carries the agent's current focus: what it's zeroing in on.
+         *     The content field carries extended text (e.g. the research plan).
          *
          *     Examples:
-         *         {"type": "agent_step", "index": 1, "detail": [
+         *         {"type": "agent_step", "index": 1, "step": "planning",
+         *          "content": "1. Search for force majeure clauses across all three contracts\n2. Compare scope and exclusions"}
+         *         {"type": "agent_step", "index": 2,
+         *          "focus": "Searching for force majeure clauses across the selected contracts.",
+         *          "detail": [
          *             {"tool": "search_documents", "query": "force majeure", "search_mode": "hybrid"},
          *             {"tool": "get_table_of_contents", "doc_count": 2}
          *         ]}
-         *         {"type": "agent_step", "index": 2, "detail": [
+         *         {"type": "agent_step", "index": 3,
+         *          "focus": "Comparing the provisions found in Contract A with Contract B.",
+         *          "detail": [
          *             {"tool": "get_document_passages", "doc_ext_id": "doc-abc12345", "from_ref": "5", "to_ref": "8"}
          *         ]}
-         *         {"type": "agent_step", "index": 3, "detail": [
-         *             {"tool": "web_search", "query": "latest arbitration developments 2026"}
-         *         ]}
          *         {"type": "agent_step", "index": 4, "step": "evaluation", "detail": [
          *             {"statement": "Newton prosecuted 28 coiners", "chunk_ids": ["chunk-abc"]},
          *             {"statement": "Counterfeiting was high treason", "chunk_ids": ["chunk-def"]}
          *         ]}
-         *         {"type": "agent_step", "index": 5, "step": "answering"}
-         *         {"type": "agent_step", "index": 6, "step": "reviewing"}
+         *         {"type": "agent_step", "index": 5, "step": "tool_progress", "detail": [
+         *             {"tool": "read_urls", "message": "Fetching 2 pages"}
+         *         ]}
+         *         {"type": "agent_step", "index": 6, "step": "answering"}
+         *         {"type": "agent_step", "index": 7, "step": "reviewing"}
          */
         AgentStepEvent: {
             /**
@@ -1321,9 +1349,19 @@ interface components {
             index: number;
             /**
              * Step
-             * @description Lifecycle step (answering, reviewing). Absent for tool calls.
+             * @description Lifecycle step (planning, answering, reviewing). Absent for tool calls.
              */
             step?: string | null;
+            /**
+             * Focus
+             * @description Agent's current focus (single sentence). Present on tool call steps.
+             */
+            focus?: string | null;
+            /**
+             * Content
+             * @description Extended text content (e.g. research plan). Present on planning step.
+             */
+            content?: string | null;
             /**
              * Detail
              * @description Tool calls list. Each entry has 'tool' key plus tool-specific params.
@@ -1351,10 +1389,34 @@ interface components {
             HUMAN_IN_THE_LOOP: boolean;
             /**
              * Web Search
-             * @description Enable the web_search tool for searching the web.
+             * @description Enable web tools: web_search (find URLs) and read_url (fetch and process webpages).
              * @default false
              */
             WEB_SEARCH: boolean;
+            /**
+             * Mcp Tools
+             * @description MCP tool names to enable from LiteLLM (e.g. ['read_wiki_contents', 'ask_question']).
+             * @default []
+             */
+            MCP_TOOLS: string[];
+            /**
+             * Planning Enabled
+             * @description Run a planning step before the first agent decision. The agent generates a text plan that guides subsequent tool calls.
+             * @default false
+             */
+            PLANNING_ENABLED: boolean;
+            /**
+             * Planning Approval
+             * @description When planning is enabled, pause after generating the plan to allow the user to approve, skip, or comment before proceeding. Requires PLANNING_ENABLED=True to have any effect.
+             * @default false
+             */
+            PLANNING_APPROVAL: boolean;
+            /**
+             * Suggested Queries
+             * @description Generate a single suggested follow-up query after each response.
+             * @default false
+             */
+            SUGGESTED_QUERIES: boolean;
             /**
              * Persona
              * @description Agent persona prepended to the system prompt. Customise to change the agent's identity and tone.
@@ -1411,6 +1473,8 @@ interface components {
              *     - get_document_passages: Read specific pages from a document
              *     - get_table_of_contents: Get headings and page references for documents
              *     - web_search: Search the web for current/external information
+             *     - read_urls: Fetch and index webpages. Always call immediately after web_search
+             *       with the 2-3 most relevant URLs. Then use search_documents to query them.
              *     - ask_user: Ask the user a clarifying question with structured options.
              *       You MUST call this tool to ask the user anything — do NOT write questions
              *       or options as plain text. Only the tool delivers the question to the user.
@@ -1423,7 +1487,8 @@ interface components {
              *     1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)
              *     2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have
              *     3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones
-             *     4. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:
+             *     4. BROAD PASSAGE RANGES: When using get_document_passages, request broad ranges    (5-10+ pages per call). A few large fetches are far better than many small ones
+             *     5. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:
              *        - Multiple sources confirm the same facts
              *        - Key questions from the query are addressed
              *        - Additional searches return redundant information
@@ -1448,6 +1513,10 @@ interface components {
              *       "ENABLED": true,
              *       "HUMAN_IN_THE_LOOP": true,
              *       "WEB_SEARCH": false,
+             *       "MCP_TOOLS": [],
+             *       "PLANNING_ENABLED": false,
+             *       "PLANNING_APPROVAL": false,
+             *       "SUGGESTED_QUERIES": false,
              *       "PERSONA": "You are ARBI, an AI assistant created by ARBI CITY.\n\nYou maintain formal, objective tone appropriate for professional/legal contexts. If any part of the answer is based on general knowledge instead of the supplied sources, you must state so clearly and recognise that it may not be accurate.",
              *       "AGENT_MODEL_NAME": "Q3VL@ARBICITY",
              *       "AGENT_API_TYPE": "remote",
@@ -1455,7 +1524,7 @@ interface components {
              *       "AGENT_MAX_TOKENS": 20000,
              *       "AGENT_MAX_ITERATIONS": 10,
              *       "AGENT_HISTORY_CHAR_THRESHOLD": 8000,
-             *       "AGENT_SYSTEM_PROMPT": "YOUR TASK:\nDetermine which, if any, of the available documents contain information relevant to the user's query. Use your tools to retrieve and examine document content.\n\nTOOLS AVAILABLE:\n- search_documents: Search for relevant passages across documents\n- get_document_passages: Read specific pages from a document\n- get_table_of_contents: Get headings and page references for documents\n- web_search: Search the web for current/external information\n- ask_user: Ask the user a clarifying question with structured options.\n  You MUST call this tool to ask the user anything — do NOT write questions\n  or options as plain text. Only the tool delivers the question to the user.\n  IMPORTANT: Once the user responds, do NOT ask the same question again.\n  Use their answer and proceed with research. If the user's answer is\n  unexpected (e.g. refers to something not in the documents), explain what\n  you found and answer based on available information.\n\nEFFICIENCY GUIDELINES:\n1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)\n2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have\n3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones\n4. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:\n   - Multiple sources confirm the same facts\n   - Key questions from the query are addressed\n   - Additional searches return redundant information\n\nWORKFLOW:\n1. Analyze the query to identify distinct information needs\n2. Execute parallel searches for different aspects when appropriate\n3. Evaluate results - extract learnings, note gaps\n4. Only search again if specific gaps remain unfilled\n5. Answer when confident (no tool call) - do not over-research\n\nIMPORTANT:\n- The document index contains metadata only - you must retrieve actual content\n- Do not add inline citation markers - the system handles citations automatically"
+             *       "AGENT_SYSTEM_PROMPT": "YOUR TASK:\nDetermine which, if any, of the available documents contain information relevant to the user's query. Use your tools to retrieve and examine document content.\n\nTOOLS AVAILABLE:\n- search_documents: Search for relevant passages across documents\n- get_document_passages: Read specific pages from a document\n- get_table_of_contents: Get headings and page references for documents\n- web_search: Search the web for current/external information\n- read_urls: Fetch and index webpages. Always call immediately after web_search\n  with the 2-3 most relevant URLs. Then use search_documents to query them.\n- ask_user: Ask the user a clarifying question with structured options.\n  You MUST call this tool to ask the user anything — do NOT write questions\n  or options as plain text. Only the tool delivers the question to the user.\n  IMPORTANT: Once the user responds, do NOT ask the same question again.\n  Use their answer and proceed with research. If the user's answer is\n  unexpected (e.g. refers to something not in the documents), explain what\n  you found and answer based on available information.\n\nEFFICIENCY GUIDELINES:\n1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)\n2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have\n3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones\n4. BROAD PASSAGE RANGES: When using get_document_passages, request broad ranges    (5-10+ pages per call). A few large fetches are far better than many small ones\n5. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:\n   - Multiple sources confirm the same facts\n   - Key questions from the query are addressed\n   - Additional searches return redundant information\n\nWORKFLOW:\n1. Analyze the query to identify distinct information needs\n2. Execute parallel searches for different aspects when appropriate\n3. Evaluate results - extract learnings, note gaps\n4. Only search again if specific gaps remain unfilled\n5. Answer when confident (no tool call) - do not over-research\n\nIMPORTANT:\n- The document index contains metadata only - you must retrieve actual content\n- Do not add inline citation markers - the system handles citations automatically"
              *     }
              */
             Agents: components['schemas']['AgentsConfig'];
@@ -1570,10 +1639,9 @@ interface components {
              *       "API_TYPE": "remote",
              *       "MODEL_NAME": "Q3VL@ARBICITY",
              *       "ENABLED": true,
-             *       "SKILL_SYSTEM_INSTRUCTION": "You are a skill synthesizer. You analyze work patterns, retrieval results, and conversation learnings to produce reusable procedural documents.\n\nGuidelines:\n- Create well-structured markdown with clear headings and numbered steps\n- Focus on reproducible procedures, not one-off observations\n- Include decision criteria, checklists, and edge cases where relevant\n- Be specific and actionable — another agent should be able to follow this skill\n- Ground everything in the provided context, do not invent information",
-             *       "MEMORY_SYSTEM_INSTRUCTION": "You are a knowledge recorder. You distill factual findings, preferences, and observations into concise reference documents.\n\nOutput format — use this markdown structure:\n```\n# [Descriptive Title]\n\n**Date:** [date from context]\n**Source:** [user query or conversation topic]\n\n## Key Findings\n[bullet points of facts learned]\n\n## Source Documents\n[list any document names referenced in the learnings]\n```\n\nGuidelines:\n- Record facts and observations, not procedures\n- Be concise — this is a reference document, not an essay\n- Always include the date and source query prominently\n- List source documents when learnings reference specific files\n- Distinguish between confirmed facts and inferences",
+             *       "SYSTEM_INSTRUCTION": "You are a knowledge synthesizer. You receive the full agent scratchpad from a completed conversation and decide what, if anything, is worth saving.\n\n## Artifact Types\n- **\"memory\"**: Facts, findings, reference data — for *looking up* information.\n- **\"skill\"**: Procedures, workflows, step-by-step instructions — for *doing* something.\n\nWhen ambiguous, default to memory.\n\n## Rules\n- Return an empty artifacts array if the conversation is trivial or produced nothing substantive.\n- Each artifact must cover ONE coherent topic. Never combine disparate subjects into a single artifact — create separate artifacts for each distinct topic.\n- Ground everything in the provided context. Do not invent information.\n- Be concise. These are reference documents, not essays.\n\n## Output Format\nJSON with an `artifacts` array. Each item has `wp_type`, `title`, and `content` (markdown).\n\nMemory content: `# Title`, date, source, key findings as bullets, source documents.\nSkill content: `# Title`, prerequisites, numbered steps, when to apply.",
              *       "TEMPERATURE": 0.3,
-             *       "MAX_TOKENS": 4000,
+             *       "MAX_TOKENS": 8000,
              *       "MAX_CHAR_CONTEXT": 100000,
              *       "MAX_CONCURRENT": 5
              *     }
@@ -1672,45 +1740,29 @@ interface components {
              */
             ENABLED: boolean;
             /**
-             * Skill System Instruction
-             * @description System instruction for skill synthesis.
-             * @default You are a skill synthesizer. You analyze work patterns, retrieval results, and conversation learnings to produce reusable procedural documents.
-             *
-             *     Guidelines:
-             *     - Create well-structured markdown with clear headings and numbered steps
-             *     - Focus on reproducible procedures, not one-off observations
-             *     - Include decision criteria, checklists, and edge cases where relevant
-             *     - Be specific and actionable — another agent should be able to follow this skill
-             *     - Ground everything in the provided context, do not invent information
-             */
-            SKILL_SYSTEM_INSTRUCTION: string;
-            /**
-             * Memory System Instruction
-             * @description System instruction for memory synthesis.
-             * @default You are a knowledge recorder. You distill factual findings, preferences, and observations into concise reference documents.
+             * System Instruction
+             * @description System instruction for artifact classification and synthesis.
+             * @default You are a knowledge synthesizer. You receive the full agent scratchpad from a completed conversation and decide what, if anything, is worth saving.
              *
-             *     Output format — use this markdown structure:
-             *     ```
-             *     # [Descriptive Title]
+             *     ## Artifact Types
+             *     - **"memory"**: Facts, findings, reference data — for *looking up* information.
+             *     - **"skill"**: Procedures, workflows, step-by-step instructions — for *doing* something.
              *
-             *     **Date:** [date from context]
-             *     **Source:** [user query or conversation topic]
+             *     When ambiguous, default to memory.
              *
-             *     ## Key Findings
-             *     [bullet points of facts learned]
+             *     ## Rules
+             *     - Return an empty artifacts array if the conversation is trivial or produced nothing substantive.
+             *     - Each artifact must cover ONE coherent topic. Never combine disparate subjects into a single artifact — create separate artifacts for each distinct topic.
+             *     - Ground everything in the provided context. Do not invent information.
+             *     - Be concise. These are reference documents, not essays.
              *
-             *     ## Source Documents
-             *     [list any document names referenced in the learnings]
-             *     ```
+             *     ## Output Format
+             *     JSON with an `artifacts` array. Each item has `wp_type`, `title`, and `content` (markdown).
              *
-             *     Guidelines:
-             *     - Record facts and observations, not procedures
-             *     - Be concise — this is a reference document, not an essay
-             *     - Always include the date and source query prominently
-             *     - List source documents when learnings reference specific files
-             *     - Distinguish between confirmed facts and inferences
+             *     Memory content: `# Title`, date, source, key findings as bullets, source documents.
+             *     Skill content: `# Title`, prerequisites, numbered steps, when to apply.
              */
-            MEMORY_SYSTEM_INSTRUCTION: string;
+            SYSTEM_INSTRUCTION: string;
             /**
              * Temperature
              * @description Temperature for synthesis.
@@ -1720,7 +1772,7 @@ interface components {
             /**
              * Max Tokens
              * @description Maximum tokens for artifact content.
-             * @default 4000
+             * @default 8000
              */
             MAX_TOKENS: number;
             /**
@@ -2651,6 +2703,20 @@ interface components {
             /** Detail */
             detail: string;
         };
+        /** McpToolInfo */
+        McpToolInfo: {
+            /** Name */
+            name: string;
+            /** Description */
+            description: string;
+            /** Server Name */
+            server_name: string;
+        };
+        /** McpToolsResponse */
+        McpToolsResponse: {
+            /** Tools */
+            tools: components['schemas']['McpToolInfo'][];
+        };
         /** MessageDeleteResponse */
         MessageDeleteResponse: {
             /**
@@ -5873,6 +5939,26 @@ interface operations {
             };
         };
     };
+    get_mcp_tools: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['McpToolsResponse'];
+                };
+            };
+        };
+    };
     create_tag: {
         parameters: {
             query?: never;

package/dist/index.d.ts

@@ -1038,6 +1038,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/api/health/mcp-tools': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Mcp Tools
+         * @description Returns available MCP tools registered on the LiteLLM proxy.
+         */
+        get: operations['get_mcp_tools'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/api/tag/': {
         parameters: {
             query?: never;
@@ -1288,24 +1308,32 @@ interface components {
          * @description A single agent step with a sequential index.
          *
          *     Tool call steps have a detail list; lifecycle steps have a step string.
+         *     The focus field carries the agent's current focus: what it's zeroing in on.
+         *     The content field carries extended text (e.g. the research plan).
          *
          *     Examples:
-         *         {"type": "agent_step", "index": 1, "detail": [
+         *         {"type": "agent_step", "index": 1, "step": "planning",
+         *          "content": "1. Search for force majeure clauses across all three contracts\n2. Compare scope and exclusions"}
+         *         {"type": "agent_step", "index": 2,
+         *          "focus": "Searching for force majeure clauses across the selected contracts.",
+         *          "detail": [
          *             {"tool": "search_documents", "query": "force majeure", "search_mode": "hybrid"},
          *             {"tool": "get_table_of_contents", "doc_count": 2}
          *         ]}
-         *         {"type": "agent_step", "index": 2, "detail": [
+         *         {"type": "agent_step", "index": 3,
+         *          "focus": "Comparing the provisions found in Contract A with Contract B.",
+         *          "detail": [
          *             {"tool": "get_document_passages", "doc_ext_id": "doc-abc12345", "from_ref": "5", "to_ref": "8"}
          *         ]}
-         *         {"type": "agent_step", "index": 3, "detail": [
-         *             {"tool": "web_search", "query": "latest arbitration developments 2026"}
-         *         ]}
          *         {"type": "agent_step", "index": 4, "step": "evaluation", "detail": [
          *             {"statement": "Newton prosecuted 28 coiners", "chunk_ids": ["chunk-abc"]},
          *             {"statement": "Counterfeiting was high treason", "chunk_ids": ["chunk-def"]}
          *         ]}
-         *         {"type": "agent_step", "index": 5, "step": "answering"}
-         *         {"type": "agent_step", "index": 6, "step": "reviewing"}
+         *         {"type": "agent_step", "index": 5, "step": "tool_progress", "detail": [
+         *             {"tool": "read_urls", "message": "Fetching 2 pages"}
+         *         ]}
+         *         {"type": "agent_step", "index": 6, "step": "answering"}
+         *         {"type": "agent_step", "index": 7, "step": "reviewing"}
          */
         AgentStepEvent: {
             /**
@@ -1321,9 +1349,19 @@ interface components {
             index: number;
             /**
              * Step
-             * @description Lifecycle step (answering, reviewing). Absent for tool calls.
+             * @description Lifecycle step (planning, answering, reviewing). Absent for tool calls.
              */
             step?: string | null;
+            /**
+             * Focus
+             * @description Agent's current focus (single sentence). Present on tool call steps.
+             */
+            focus?: string | null;
+            /**
+             * Content
+             * @description Extended text content (e.g. research plan). Present on planning step.
+             */
+            content?: string | null;
             /**
              * Detail
              * @description Tool calls list. Each entry has 'tool' key plus tool-specific params.
@@ -1351,10 +1389,34 @@ interface components {
             HUMAN_IN_THE_LOOP: boolean;
             /**
              * Web Search
-             * @description Enable the web_search tool for searching the web.
+             * @description Enable web tools: web_search (find URLs) and read_url (fetch and process webpages).
              * @default false
              */
             WEB_SEARCH: boolean;
+            /**
+             * Mcp Tools
+             * @description MCP tool names to enable from LiteLLM (e.g. ['read_wiki_contents', 'ask_question']).
+             * @default []
+             */
+            MCP_TOOLS: string[];
+            /**
+             * Planning Enabled
+             * @description Run a planning step before the first agent decision. The agent generates a text plan that guides subsequent tool calls.
+             * @default false
+             */
+            PLANNING_ENABLED: boolean;
+            /**
+             * Planning Approval
+             * @description When planning is enabled, pause after generating the plan to allow the user to approve, skip, or comment before proceeding. Requires PLANNING_ENABLED=True to have any effect.
+             * @default false
+             */
+            PLANNING_APPROVAL: boolean;
+            /**
+             * Suggested Queries
+             * @description Generate a single suggested follow-up query after each response.
+             * @default false
+             */
+            SUGGESTED_QUERIES: boolean;
             /**
              * Persona
              * @description Agent persona prepended to the system prompt. Customise to change the agent's identity and tone.
@@ -1411,6 +1473,8 @@ interface components {
              *     - get_document_passages: Read specific pages from a document
              *     - get_table_of_contents: Get headings and page references for documents
              *     - web_search: Search the web for current/external information
+             *     - read_urls: Fetch and index webpages. Always call immediately after web_search
+             *       with the 2-3 most relevant URLs. Then use search_documents to query them.
              *     - ask_user: Ask the user a clarifying question with structured options.
              *       You MUST call this tool to ask the user anything — do NOT write questions
              *       or options as plain text. Only the tool delivers the question to the user.
@@ -1423,7 +1487,8 @@ interface components {
              *     1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)
              *     2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have
              *     3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones
-             *     4. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:
+             *     4. BROAD PASSAGE RANGES: When using get_document_passages, request broad ranges    (5-10+ pages per call). A few large fetches are far better than many small ones
+             *     5. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:
              *        - Multiple sources confirm the same facts
              *        - Key questions from the query are addressed
              *        - Additional searches return redundant information
@@ -1448,6 +1513,10 @@ interface components {
              *       "ENABLED": true,
              *       "HUMAN_IN_THE_LOOP": true,
              *       "WEB_SEARCH": false,
+             *       "MCP_TOOLS": [],
+             *       "PLANNING_ENABLED": false,
+             *       "PLANNING_APPROVAL": false,
+             *       "SUGGESTED_QUERIES": false,
              *       "PERSONA": "You are ARBI, an AI assistant created by ARBI CITY.\n\nYou maintain formal, objective tone appropriate for professional/legal contexts. If any part of the answer is based on general knowledge instead of the supplied sources, you must state so clearly and recognise that it may not be accurate.",
              *       "AGENT_MODEL_NAME": "Q3VL@ARBICITY",
              *       "AGENT_API_TYPE": "remote",
@@ -1455,7 +1524,7 @@ interface components {
              *       "AGENT_MAX_TOKENS": 20000,
              *       "AGENT_MAX_ITERATIONS": 10,
              *       "AGENT_HISTORY_CHAR_THRESHOLD": 8000,
-             *       "AGENT_SYSTEM_PROMPT": "YOUR TASK:\nDetermine which, if any, of the available documents contain information relevant to the user's query. Use your tools to retrieve and examine document content.\n\nTOOLS AVAILABLE:\n- search_documents: Search for relevant passages across documents\n- get_document_passages: Read specific pages from a document\n- get_table_of_contents: Get headings and page references for documents\n- web_search: Search the web for current/external information\n- ask_user: Ask the user a clarifying question with structured options.\n  You MUST call this tool to ask the user anything — do NOT write questions\n  or options as plain text. Only the tool delivers the question to the user.\n  IMPORTANT: Once the user responds, do NOT ask the same question again.\n  Use their answer and proceed with research. If the user's answer is\n  unexpected (e.g. refers to something not in the documents), explain what\n  you found and answer based on available information.\n\nEFFICIENCY GUIDELINES:\n1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)\n2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have\n3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones\n4. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:\n   - Multiple sources confirm the same facts\n   - Key questions from the query are addressed\n   - Additional searches return redundant information\n\nWORKFLOW:\n1. Analyze the query to identify distinct information needs\n2. Execute parallel searches for different aspects when appropriate\n3. Evaluate results - extract learnings, note gaps\n4. Only search again if specific gaps remain unfilled\n5. Answer when confident (no tool call) - do not over-research\n\nIMPORTANT:\n- The document index contains metadata only - you must retrieve actual content\n- Do not add inline citation markers - the system handles citations automatically"
+             *       "AGENT_SYSTEM_PROMPT": "YOUR TASK:\nDetermine which, if any, of the available documents contain information relevant to the user's query. Use your tools to retrieve and examine document content.\n\nTOOLS AVAILABLE:\n- search_documents: Search for relevant passages across documents\n- get_document_passages: Read specific pages from a document\n- get_table_of_contents: Get headings and page references for documents\n- web_search: Search the web for current/external information\n- read_urls: Fetch and index webpages. Always call immediately after web_search\n  with the 2-3 most relevant URLs. Then use search_documents to query them.\n- ask_user: Ask the user a clarifying question with structured options.\n  You MUST call this tool to ask the user anything — do NOT write questions\n  or options as plain text. Only the tool delivers the question to the user.\n  IMPORTANT: Once the user responds, do NOT ask the same question again.\n  Use their answer and proceed with research. If the user's answer is\n  unexpected (e.g. refers to something not in the documents), explain what\n  you found and answer based on available information.\n\nEFFICIENCY GUIDELINES:\n1. PARALLEL CALLS: When a query has multiple aspects, call multiple tools in    parallel (e.g., search different keywords simultaneously)\n2. AVOID DUPLICATION: Before searching, review learnings from previous results.    Do not repeat searches for information you already have\n3. TARGETED SEARCHES: Use specific, focused queries rather than broad ones\n4. BROAD PASSAGE RANGES: When using get_document_passages, request broad ranges    (5-10+ pages per call). A few large fetches are far better than many small ones\n5. STOP WHEN READY: Provide your answer when you have sufficient evidence.    Signs you have enough:\n   - Multiple sources confirm the same facts\n   - Key questions from the query are addressed\n   - Additional searches return redundant information\n\nWORKFLOW:\n1. Analyze the query to identify distinct information needs\n2. Execute parallel searches for different aspects when appropriate\n3. Evaluate results - extract learnings, note gaps\n4. Only search again if specific gaps remain unfilled\n5. Answer when confident (no tool call) - do not over-research\n\nIMPORTANT:\n- The document index contains metadata only - you must retrieve actual content\n- Do not add inline citation markers - the system handles citations automatically"
              *     }
              */
             Agents: components['schemas']['AgentsConfig'];
@@ -1570,10 +1639,9 @@ interface components {
              *       "API_TYPE": "remote",
              *       "MODEL_NAME": "Q3VL@ARBICITY",
              *       "ENABLED": true,
-             *       "SKILL_SYSTEM_INSTRUCTION": "You are a skill synthesizer. You analyze work patterns, retrieval results, and conversation learnings to produce reusable procedural documents.\n\nGuidelines:\n- Create well-structured markdown with clear headings and numbered steps\n- Focus on reproducible procedures, not one-off observations\n- Include decision criteria, checklists, and edge cases where relevant\n- Be specific and actionable — another agent should be able to follow this skill\n- Ground everything in the provided context, do not invent information",
-             *       "MEMORY_SYSTEM_INSTRUCTION": "You are a knowledge recorder. You distill factual findings, preferences, and observations into concise reference documents.\n\nOutput format — use this markdown structure:\n```\n# [Descriptive Title]\n\n**Date:** [date from context]\n**Source:** [user query or conversation topic]\n\n## Key Findings\n[bullet points of facts learned]\n\n## Source Documents\n[list any document names referenced in the learnings]\n```\n\nGuidelines:\n- Record facts and observations, not procedures\n- Be concise — this is a reference document, not an essay\n- Always include the date and source query prominently\n- List source documents when learnings reference specific files\n- Distinguish between confirmed facts and inferences",
+             *       "SYSTEM_INSTRUCTION": "You are a knowledge synthesizer. You receive the full agent scratchpad from a completed conversation and decide what, if anything, is worth saving.\n\n## Artifact Types\n- **\"memory\"**: Facts, findings, reference data — for *looking up* information.\n- **\"skill\"**: Procedures, workflows, step-by-step instructions — for *doing* something.\n\nWhen ambiguous, default to memory.\n\n## Rules\n- Return an empty artifacts array if the conversation is trivial or produced nothing substantive.\n- Each artifact must cover ONE coherent topic. Never combine disparate subjects into a single artifact — create separate artifacts for each distinct topic.\n- Ground everything in the provided context. Do not invent information.\n- Be concise. These are reference documents, not essays.\n\n## Output Format\nJSON with an `artifacts` array. Each item has `wp_type`, `title`, and `content` (markdown).\n\nMemory content: `# Title`, date, source, key findings as bullets, source documents.\nSkill content: `# Title`, prerequisites, numbered steps, when to apply.",
              *       "TEMPERATURE": 0.3,
-             *       "MAX_TOKENS": 4000,
+             *       "MAX_TOKENS": 8000,
              *       "MAX_CHAR_CONTEXT": 100000,
              *       "MAX_CONCURRENT": 5
              *     }
@@ -1672,45 +1740,29 @@ interface components {
              */
             ENABLED: boolean;
             /**
-             * Skill System Instruction
-             * @description System instruction for skill synthesis.
-             * @default You are a skill synthesizer. You analyze work patterns, retrieval results, and conversation learnings to produce reusable procedural documents.
-             *
-             *     Guidelines:
-             *     - Create well-structured markdown with clear headings and numbered steps
-             *     - Focus on reproducible procedures, not one-off observations
-             *     - Include decision criteria, checklists, and edge cases where relevant
-             *     - Be specific and actionable — another agent should be able to follow this skill
-             *     - Ground everything in the provided context, do not invent information
-             */
-            SKILL_SYSTEM_INSTRUCTION: string;
-            /**
-             * Memory System Instruction
-             * @description System instruction for memory synthesis.
-             * @default You are a knowledge recorder. You distill factual findings, preferences, and observations into concise reference documents.
+             * System Instruction
+             * @description System instruction for artifact classification and synthesis.
+             * @default You are a knowledge synthesizer. You receive the full agent scratchpad from a completed conversation and decide what, if anything, is worth saving.
              *
-             *     Output format — use this markdown structure:
-             *     ```
-             *     # [Descriptive Title]
+             *     ## Artifact Types
+             *     - **"memory"**: Facts, findings, reference data — for *looking up* information.
+             *     - **"skill"**: Procedures, workflows, step-by-step instructions — for *doing* something.
              *
-             *     **Date:** [date from context]
-             *     **Source:** [user query or conversation topic]
+             *     When ambiguous, default to memory.
              *
-             *     ## Key Findings
-             *     [bullet points of facts learned]
+             *     ## Rules
+             *     - Return an empty artifacts array if the conversation is trivial or produced nothing substantive.
+             *     - Each artifact must cover ONE coherent topic. Never combine disparate subjects into a single artifact — create separate artifacts for each distinct topic.
+             *     - Ground everything in the provided context. Do not invent information.
+             *     - Be concise. These are reference documents, not essays.
              *
-             *     ## Source Documents
-             *     [list any document names referenced in the learnings]
-             *     ```
+             *     ## Output Format
+             *     JSON with an `artifacts` array. Each item has `wp_type`, `title`, and `content` (markdown).
              *
-             *     Guidelines:
-             *     - Record facts and observations, not procedures
-             *     - Be concise — this is a reference document, not an essay
-             *     - Always include the date and source query prominently
-             *     - List source documents when learnings reference specific files
-             *     - Distinguish between confirmed facts and inferences
+             *     Memory content: `# Title`, date, source, key findings as bullets, source documents.
+             *     Skill content: `# Title`, prerequisites, numbered steps, when to apply.
              */
-            MEMORY_SYSTEM_INSTRUCTION: string;
+            SYSTEM_INSTRUCTION: string;
             /**
              * Temperature
              * @description Temperature for synthesis.
@@ -1720,7 +1772,7 @@ interface components {
             /**
              * Max Tokens
              * @description Maximum tokens for artifact content.
-             * @default 4000
+             * @default 8000
              */
             MAX_TOKENS: number;
             /**
@@ -2651,6 +2703,20 @@ interface components {
             /** Detail */
             detail: string;
         };
+        /** McpToolInfo */
+        McpToolInfo: {
+            /** Name */
+            name: string;
+            /** Description */
+            description: string;
+            /** Server Name */
+            server_name: string;
+        };
+        /** McpToolsResponse */
+        McpToolsResponse: {
+            /** Tools */
+            tools: components['schemas']['McpToolInfo'][];
+        };
         /** MessageDeleteResponse */
         MessageDeleteResponse: {
             /**
@@ -5873,6 +5939,26 @@ interface operations {
             };
         };
     };
+    get_mcp_tools: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['McpToolsResponse'];
+                };
+            };
+        };
+    };
     create_tag: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbidocs/sdk",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "TypeScript SDK for the ARBI API — zero-knowledge auth, E2E encryption, and type-safe REST client",
   "type": "module",
   "main": "dist/index.cjs",
@@ -22,11 +22,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "libsodium-wrappers-sumo": "^0.7.15",
+    "libsodium-wrappers-sumo": "^0.8.0",
     "openapi-fetch": "^0.15.0"
   },
   "devDependencies": {
-    "@types/libsodium-wrappers-sumo": "^0.7.8",
+    "@types/libsodium-wrappers-sumo": "^0.8.2",
     "fake-indexeddb": "^6.2.5",
     "tsup": "^8.4.0",
     "typescript": "^5.9.3",
@@ -38,8 +38,16 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/arbitrationcity/ARBI-frontend.git",
+    "url": "git+https://github.com/arbitrationcity/ARBI-frontend.git",
     "directory": "packages/arbi-api-client"
   },
-  "keywords": ["arbi", "api", "sdk", "e2e-encryption", "zero-knowledge", "openapi", "typescript"]
+  "keywords": [
+    "arbi",
+    "api",
+    "sdk",
+    "e2e-encryption",
+    "zero-knowledge",
+    "openapi",
+    "typescript"
+  ]
 }