@orboto/mcp 0.207.0 → 0.208.0

package/dist/server.js

@@ -28,6 +28,7 @@ import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
 import { agentWakesToolConfig, makeAgentWakesHandler } from './tools/agent-wakes.js';
 import { sessionCheckToolConfig, makeSessionCheckHandler } from './tools/session-check.js';
+import { knowledgeAskToolConfig, makeKnowledgeAskHandler, knowledgeAddToolConfig, makeKnowledgeAddHandler } from './tools/knowledge.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
 import { getProjectToolConfig, makeGetProjectHandler } from './tools/get-project.js';
 import { projectReadinessToolConfig, makeProjectReadinessHandler } from './tools/project-readiness.js';
@@ -45,7 +46,7 @@ import { queryToolConfig, makeQueryHandler } from './tools/query.js';
 import { customerReportToolConfig, makeCustomerReportHandler } from './tools/customer-report.js';
 import { requirementsSpecToolConfig, makeRequirementsSpecHandler } from './tools/requirements-spec.js';
 import { specCheckToolConfig, makeSpecCheckHandler } from './tools/spec-check.js';
-import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, } from './tools/wiki.js';
+import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, wikiRunsToolConfig, makeWikiRunsHandler } from './tools/wiki.js';
 import { personalFactListToolConfig, makePersonalFactListHandler, personalFactAddToolConfig, makePersonalFactAddHandler, personalFactUpdateToolConfig, makePersonalFactUpdateHandler, personalFactDeleteToolConfig, makePersonalFactDeleteHandler, } from './tools/personal-facts.js';
 import { listDocSpacesToolConfig, makeListDocSpacesHandler, getDocToolConfig, makeGetDocHandler, createDocSpaceToolConfig, makeCreateDocSpaceHandler, updateDocSpaceToolConfig, makeUpdateDocSpaceHandler, deleteDocSpaceToolConfig, makeDeleteDocSpaceHandler, listDocsInSpaceToolConfig, makeListDocsInSpaceHandler, createDocToolConfig, makeCreateDocHandler, updateDocToolConfig, makeUpdateDocHandler, deleteDocToolConfig, makeDeleteDocHandler, moveDocToolConfig, makeMoveDocHandler, duplicateDocSpaceToolConfig, makeDuplicateDocSpaceHandler, resolveDocSmartLinksToolConfig, makeResolveDocSmartLinksHandler, } from './tools/docs.js';
 import { searchDocsToolConfig, makeSearchDocsHandler, editDocToolConfig, makeEditDocHandler, editDocSectionToolConfig, makeEditDocSectionHandler, } from './tools/doc-edits.js';
@@ -211,6 +212,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
     reg('orboto_agent_wakes', agentWakesToolConfig, makeAgentWakesHandler(client));
     reg('orboto_session_check', sessionCheckToolConfig, makeSessionCheckHandler(client));
+    reg('orboto_knowledge_ask', knowledgeAskToolConfig, makeKnowledgeAskHandler(client));
+    reg('orboto_knowledge_add', knowledgeAddToolConfig, makeKnowledgeAddHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
     reg('orboto_get_project', getProjectToolConfig, makeGetProjectHandler(client));
@@ -269,6 +272,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_wiki_ingest_url', wikiIngestUrlToolConfig, makeWikiIngestUrlHandler(client));
     reg('orboto_wiki_ask', wikiAskToolConfig, makeWikiAskHandler(client));
     reg('orboto_wiki_lint', wikiLintToolConfig, makeWikiLintHandler(client));
+    reg('orboto_wiki_runs', wikiRunsToolConfig, makeWikiRunsHandler(client));
     reg('orboto_wiki_plan_update', wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler(client));
     reg('orboto_wiki_apply_plan', wikiApplyPlanToolConfig, makeWikiApplyPlanHandler(client));
     reg('orboto_wiki_record', wikiRecordToolConfig, makeWikiRecordHandler(client));

package/dist/tools/agent-drift.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listAgentDriftToolConfig = {
     title: 'List agent drift events',
-    description: 'List agent drift events (commits with no ticket key + no timer, or ticket transitions without a summary comment), newest first, with aggregate metrics. Filter by `userId`, `driftType` (untracked_commit | transition_without_summary), `from`/`to` ISO dates, and `resolved`. The response `enabled` flag is false when the operator has not turned drift detection on. Requires `admin:agent_drift:read`.',
+    description: 'List agent drift events newest first, with aggregate metrics. A drift event is a commit with no ticket key and no timer, or a ticket transition without a summary comment. Filter by `userId`, `driftType` (untracked_commit | transition_without_summary), `from`/`to` ISO dates, and `resolved`. The response `enabled` flag is false when the operator has not turned drift detection on. Requires `admin:agent_drift:read`.',
     inputSchema: z.object({
         userId: z.string().uuid().optional().describe('Filter to one user.'),
         driftType: z.enum(['untracked_commit', 'transition_without_summary']).optional(),

package/dist/tools/agent-instructions.js

@@ -18,7 +18,7 @@ function renderBlock(b) {
 }
 export const listAgentInstructionsToolConfig = {
     title: 'MANAGE the workspace coding-agent rule blocks (admin)',
-    description: 'ADMIN/MANAGEMENT tool - lists the individual rule BLOCKS at a scope (workspace: needs admin:ai:read; project: needs project:edit; personal: your own) so they can be edited/toggled/reordered. This is NOT how you read the rules to follow. To LOAD the rules you must follow as an agent, call orboto_session_start instead - it returns the complete assembled rule set.',
+    description: 'ADMIN tool: lists the rule BLOCKS at a scope for editing, not the rules to follow. Scopes: workspace needs admin:ai:read, project needs project:edit, personal is your own; blocks can be edited, toggled and reordered. This is NOT how you read the rules to follow. To LOAD the rules you must follow as an agent, call orboto_session_start instead - it returns the complete assembled rule set.',
     inputSchema: z.object({
         scope: z.enum(['workspace', 'customer', 'project', 'personal']).default('workspace'),
         projectId: z.string().uuid().optional().describe('Required for scope=project.'),
@@ -72,7 +72,7 @@ export function makeListAgentInstructionsHandler(client) {
 }
 export const createAgentInstructionToolConfig = {
     title: 'Add a custom coding-agent rule block',
-    description: 'Create a custom rule block at a scope: workspace (every agent; admin:ai:write), customer (every project of one customer; customer:write), project (one project; project:edit), or personal (your own). For scope=customer pass customerId; for scope=project pass projectId.'
+    description: 'Create a custom rule block at a scope (workspace, customer, project or personal). Workspace reaches every agent (admin:ai:write), customer every project of one customer (customer:write), project one project (project:edit), personal only you. For scope=customer pass customerId; for scope=project pass projectId.'
         + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         title: z.string().min(1).max(120),

package/dist/tools/agent-messages.js

@@ -13,7 +13,7 @@ import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
+    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),

package/dist/tools/agent-wakes.js

@@ -5,7 +5,7 @@
 import { z } from 'zod';
 export const agentWakesToolConfig = {
     title: 'Wake ledger',
-    description: 'Who woke this account\'s sessions, which visibility rule delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
+    description: 'The wake ledger: who woke this account\'s sessions and at what cost. It names the visibility rule that delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
     inputSchema: z.object({
         stats: z.boolean().default(false).describe('Precision per session and per sender instead of rows.'),
         hours: z.number().int().min(1).max(720).optional().describe('Stats window, default 24.'),

package/dist/tools/backup.js

@@ -69,7 +69,7 @@ export function makeListBackupsHandler(client) {
 }
 export const downloadBackupToolConfig = {
     title: 'Download a stored backup run',
-    description: 'Download a stored backup run by run id (from orboto_list_backups) as a base64 resource attachment; an encrypted run downloads sealed and needs its key to restore. Requires admin:backup:read.',
+    description: 'Download a stored backup run by run id as a base64 resource attachment. The id comes from orboto_list_backups; an encrypted run downloads sealed and needs its key to restore. Requires admin:backup:read.',
     inputSchema: z.object({
         runId: z.string().uuid().describe('Backup run id from orboto_list_backups.'),
     }).shape,

package/dist/tools/bulk-create.js

@@ -22,7 +22,7 @@ const TicketDraftSchema = z.object({
 });
 export const bulkCreateTicketsToolConfig = {
     title: 'Create many tickets in one call',
-    description: 'Create up to 50 tickets in one call - the right tool whenever you are about to create more than ~3 tickets (milestone planning, epic breakdown, import). Per-draft error isolation: a rejected draft (bad label, language block, hard duplicate-block) is reported in `failed` while the rest are still created. Duplicate detection runs per draft and is reported compactly - one line per flagged draft in `duplicateFlags`; review those before treating them as new work. A call-level `milestone` / `parentTicketKey` applies to every draft unless the draft overrides it. Drafts are created in array order, so a draft can NOT reference a sibling draft as parent - create parents first (or in a first call).',
+    description: 'Create up to 50 tickets in one call. It is the right tool whenever you are about to create more than ~3 tickets (milestone planning, epic breakdown, import). Per-draft error isolation: a rejected draft (bad label, language block, hard duplicate-block) is reported in `failed` while the rest are still created. Duplicate detection runs per draft and is reported compactly - one line per flagged draft in `duplicateFlags`; review those before treating them as new work. A call-level `milestone` / `parentTicketKey` applies to every draft unless the draft overrides it. Drafts are created in array order, so a draft can NOT reference a sibling draft as parent - create parents first (or in a first call).',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key - all drafts land here.'),
         tickets: z.array(TicketDraftSchema).min(1).max(50).describe('The ticket drafts, created in order.'),
@@ -137,7 +137,7 @@ export function makeBulkCreateTicketsHandler(client) {
 }
 export const bulkAddTicketDependenciesToolConfig = {
     title: 'Add many ticket dependencies in one call',
-    description: 'Create up to 200 blocked-by edges in one call - use instead of repeated orboto_add_ticket_dependency whenever wiring more than ~3 edges (dependency graphs after a bulk create). Each pair is (ticketKey, dependsOnKey) = "ticket is blocked by dependsOn". Per-pair error isolation; an already-existing edge counts as ok, a cycle rejection lands in `failed` with the API\'s reason.',
+    description: 'Create up to 200 blocked-by edges in one call. Use it instead of repeated orboto_add_ticket_dependency whenever wiring more than ~3 edges (dependency graphs after a bulk create). Each pair is (ticketKey, dependsOnKey) = "ticket is blocked by dependsOn". Per-pair error isolation; an already-existing edge counts as ok, a cycle rejection lands in `failed` with the API\'s reason.',
     inputSchema: z.object({
         pairs: z.array(z.object({
             ticketKey: z.string().min(3).describe('The blocked ticket.'),

package/dist/tools/check-similar.js

@@ -6,7 +6,7 @@ import { trimSimilarEntries } from './similar-projection.js';
 import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
 export const checkSimilarToolConfig = {
     title: 'Check for similar tickets before creating',
-    description: 'Run the duplicate-detection pipeline (tsvector + AI-embedding rerank when configured) against a proposed title + description, without creating anything. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. Only an AI-embedding candidate carries an absolute similarity; a full-text candidate prints as "text match" without a percentage (its rank is relative, so the best text match always scores 1.000) and can never trigger the hard duplicate-block, and neither can a match against a CLOSED ticket (ORB-2185). An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
+    description: 'Run the duplicate check against a proposed title + description without creating anything. The pipeline is tsvector plus an AI-embedding rerank when configured. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. Only an AI-embedding candidate carries an absolute similarity; a full-text candidate prints as "text match" without a percentage (its rank is relative, so the best text match always scores 1.000) and can never trigger the hard duplicate-block, and neither can a match against a CLOSED ticket (ORB-2185). An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
         title: z.string().min(1).describe('Proposed ticket title.'),

package/dist/tools/customer-draft.js

@@ -11,7 +11,7 @@ import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
 export const draftCustomerReplyToolConfig = {
     title: 'Draft a customer-facing reply for a ticket',
-    description: 'Draft a reply or status update for a CUSTOMER / external reader about a ticket (by key), built server-side from customer-safe facts only (key, title, status, due date, customer summary, non-internal comments, your `ask`) - never from internal notes. Returns the draft, the facts used and what was excluded. Never posts: show it to the user, then `orboto_comment` only after approval. Use it for every customer-facing text.',
+    description: 'Draft a customer-facing reply about a ticket (by key). It is built server-side from customer-safe facts only (key, title, status, due date, customer summary, non-internal comments, your `ask`) - never from internal notes. Returns the draft, the facts used and what was excluded. Never posts: show it to the user, then `orboto_comment` only after approval. Use it for every customer-facing text.',
     inputSchema: z.object({
         ticketKey: z.string().describe('Ticket key like "ORB-42".'),
         ask: z.string().min(3).max(1000).describe('What the reply should do, in the user\'s words, e.g. "tell them the fix ships with the next release" or "ask for the browser version".'),

package/dist/tools/get-project-primer.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
 export const getProjectPrimerToolConfig = {
     title: 'Get project primer (AI Context Pack)',
-    description: 'Returns the project\'s auto-generated session primer in a single call: the project vocabulary a create has to get right (ticket type enum, the project\'s labels, its status names per category, its open milestone keys), active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
+    description: 'Returns the project\'s auto-generated session primer in one call. It carries the project vocabulary a create has to get right (ticket type enum, the project\'s labels, its status names per category, its open milestone keys), active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, the Knowledge block (the index of the project wiki and of the Operations wiki, their latest log entries and open lint issues), and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, case-insensitive.'),
         maxTokens: z.number().int().positive().max(200000).optional()

package/dist/tools/help.js

@@ -15,7 +15,7 @@ import { onboardingText } from '../agent-head.js';
 const TOPICS = { connect: connectScriptText, onboarding: onboardingText };
 export const helpToolConfig = {
     title: 'Full guidance for one orboto tool',
-    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up, topic: "onboarding" the first five minutes and the work loop.',
+    description: 'Return the complete guidance text for one orboto tool by name. Manifest descriptions are one-line summaries; this adds the workflows, warnings and edge cases. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up, topic: "onboarding" the first five minutes and the work loop.',
     inputSchema: z.object({
         tool: z.string().min(1).max(128).optional().describe('Tool name, e.g. orboto_create_ticket.'),
         topic: z.enum(['connect', 'onboarding']).optional().describe('Guidance topic instead of a tool.'),

package/dist/tools/knowledge.js

@@ -0,0 +1,35 @@
+/** ORB-2225 - the wiki as the agents' knowledge base: ask it first, file durable facts in it. */
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const knowledgeAskToolConfig = {
+    title: 'Ask the wiki',
+    description: 'Ask your session\'s project wikis and the Operations wiki before asking a person; cite docs by key.',
+    inputSchema: z.object({ question: z.string().min(3).max(1000), projectKeys: z.array(z.string().min(1).max(32)).max(20).optional() }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeKnowledgeAskHandler(client) {
+    return async (input, extra) => {
+        const res = await client.post('/knowledge/ask', input, { instanceToken: mcpInstanceToken(undefined, extra) });
+        const where = res.spaces.map((s) => s.spaceKey ?? s.spaceName).join(', ');
+        const cites = res.citations.map((c) => `[${c.index}] ${c.title} - ${c.link}`).join('\n');
+        return {
+            content: [{ type: 'text', text: [res.answer, cites ? `Sources:\n${cites}` : '', `Asked: ${where}.`].filter(Boolean).join('\n\n') }],
+            structuredContent: res,
+        };
+    };
+}
+export const knowledgeAddToolConfig = {
+    title: 'File a fact in the wiki',
+    description: 'File a durable fact in a project wiki (projectKey) or the Operations wiki, never only in local memory.',
+    inputSchema: z.object({
+        title: z.string().min(1).max(200), content: z.string().min(1).max(50_000),
+        projectKey: z.string().min(1).max(32).optional(), operations: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeKnowledgeAddHandler(client) {
+    return async (input, extra) => {
+        const res = await client.post('/knowledge/add', input, { instanceToken: mcpInstanceToken(undefined, extra) });
+        return { content: [{ type: 'text', text: res.text }], structuredContent: res };
+    };
+}

package/dist/tools/knowledge.test.js

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient as RealClient } from '../orboto-client.js';
+import { knowledgeAddToolConfig, knowledgeAskToolConfig, makeKnowledgeAddHandler, makeKnowledgeAskHandler } from './knowledge.js';
+import { KNOWLEDGE_BLOCK_CHARS, knowledgeLines, makeSessionStartHandler } from './session-start.js';
+import { makeResponseExpandHandler } from './response-expand.js';
+import { makeWikiRunsHandler } from './wiki.js';
+function textOf(result) {
+    return result.content[0].text;
+}
+afterEach(() => { vi.restoreAllMocks(); });
+describe('ORB-2225 orboto_knowledge_ask and orboto_knowledge_add', () => {
+    it('asks the scope and lists the cited docs and the asked spaces', async () => {
+        const post = vi.fn().mockResolvedValue({
+            answer: 'Nightly with restic [1].', citations: [{ index: 1, title: 'Backup chain', link: '/spaces/s/docs/d' }], mode: 'keyword', abstained: false,
+            source: 'session', spaces: [{ spaceKey: 'ACME-S1', spaceName: 'ACME', projectKey: 'ACME' }, { spaceKey: 'SPACE-3', spaceName: 'Operations', projectKey: null }],
+        });
+        const result = await makeKnowledgeAskHandler({ post })({ question: 'where does the backup run?' }, { sessionId: 'abc' });
+        expect(post).toHaveBeenCalledWith('/knowledge/ask', { question: 'where does the backup run?' }, { instanceToken: 'mcp-abc' });
+        expect(textOf(result)).toContain('[1] Backup chain - /spaces/s/docs/d');
+        expect(textOf(result)).toContain('Asked: ACME-S1, SPACE-3.');
+    });
+    it('files a fact and returns the server sentence naming where it landed', async () => {
+        const post = vi.fn().mockResolvedValue({ action: 'recorded', text: 'Recorded in the ACME-S1 wiki: ACME-D7 "Build host". Cite it by key.', pages: [], source: null });
+        const result = await makeKnowledgeAddHandler({ post })({ title: 'Build host', content: 'build.example.org', projectKey: 'ACME' });
+        expect(post.mock.calls[0][0]).toBe('/knowledge/add');
+        expect(textOf(result)).toContain('ACME-D7');
+        expect(result.structuredContent).toMatchObject({ action: 'recorded' });
+    });
+    it('both tools carry a title and annotations; ask is read-only, add is not', () => {
+        expect(knowledgeAskToolConfig.title).toBeTruthy();
+        expect(knowledgeAskToolConfig.annotations.readOnlyHint).toBe(true);
+        expect(knowledgeAddToolConfig.title).toBeTruthy();
+        expect(knowledgeAddToolConfig.annotations.readOnlyHint).toBe(false);
+    });
+});
+describe('ORB-2225 the Knowledge block of orboto_session_start', () => {
+    it('prints the block from GET /knowledge with the session header', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            const headers = new Headers(init?.headers);
+            seen.push({ path: u.pathname, session: headers.get('x-orboto-agent-session') });
+            const body = u.pathname === '/agent-instructions' ? { instructions: 'claim -> commit -> close', rulesHash: 'fixture' } : u.pathname === '/knowledge'
+                ? { source: 'session', spaces: [{ spaceKey: 'ACME-S1', spaceName: 'ACME', projectKey: 'ACME', pages: 3, sources: 1, openLintIssues: 0, indexDoc: { key: 'ACME-D1' } }], missing: [], text: '## Knowledge\nIndex ACME-D1:\n- Build host' }
+                : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const client = new RealClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+        const result = await makeSessionStartHandler(client)({}, { sessionId: 'k1' });
+        expect(seen.find((c) => c.path === '/knowledge')?.session).toBe('mcp-k1');
+        expect(textOf(result)).toContain('## Knowledge\nIndex ACME-D1:\n- Build host');
+        expect(result.structuredContent).toMatchObject({ knowledge: { source: 'session', spaces: [{ spaceKey: 'ACME-S1', indexDocKey: 'ACME-D1', pages: 3 }] } });
+    });
+    it('cuts a long block at a line and serves the rest through a handle', async () => {
+        const text = ['## Knowledge', ...Array.from({ length: 200 }, (_, i) => `- ACME-D${i} Page ${i}`)].join('\n');
+        const block = knowledgeLines(text);
+        expect(block.lines.join('\n').length).toBeLessThan(KNOWLEDGE_BLOCK_CHARS + 200);
+        expect(block.lines.at(-1)).toContain(`handle: "${block.handle}"`);
+        const expanded = await makeResponseExpandHandler()({ handle: block.handle, path: 'knowledge' });
+        expect(textOf(expanded)).toContain('- ACME-D199 Page 199');
+    });
+});
+describe('ORB-2225 orboto_wiki_runs', () => {
+    it('lists the failed runs with their error and retries one by id', async () => {
+        const get = vi.fn().mockResolvedValue({ runs: [{ id: 'r1', sourceKey: 'ACME-D9', sourceTitle: 'Runner notes', status: 'failed', error: 'answer budget spent', createdAt: '2026-09-27T08:00:00Z' }] });
+        const post = vi.fn().mockResolvedValue({ runId: 'r1', status: 'applied', queued: false, error: null });
+        const handler = makeWikiRunsHandler({ get, post });
+        expect(textOf(await handler({ spaceId: 'ACME-S1', status: 'failed' }))).toContain('r1 failed ACME-D9 "Runner notes" 2026-09-27T08:00:00Z - answer budget spent');
+        expect(get).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs?status=failed');
+        expect((await handler({ spaceId: 'ACME-S1', action: 'retry' })).isError).toBe(true);
+        expect(textOf(await handler({ spaceId: 'ACME-S1', action: 'retry', runId: '11111111-0000-4000-8000-000000000000' }))).toContain('ran again: applied');
+        expect(post).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs/11111111-0000-4000-8000-000000000000/retry', {});
+    });
+});

package/dist/tools/sentry.js

@@ -9,7 +9,7 @@ import { mcpInstanceToken, resolveProjectByKey, resolveTicketByKey } from './sha
 const ACTIONS = ['list', 'health', 'connect', 'update', 'rotate_secret', 'disconnect', 'triage_lane', 'verdict'];
 export const sentryToolConfig = {
     title: 'Sentry connector',
-    description: 'Sentry connector (ORB-2123): list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
+    description: 'Sentry connector (ORB-2123). Actions: list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
     inputSchema: z.object({
         action: z.enum(ACTIONS),
         projectKey: z.string().min(1),

package/dist/tools/session-start.js

@@ -21,7 +21,8 @@ import { agentHeadText } from '../agent-head.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136).',
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136). '
+        + 'The digest also carries the Knowledge block (ORB-2225): the wiki index of your declared projects and of the Operations wiki, their latest log entries and open lint issues; ask the wiki with orboto_knowledge_ask before asking a person, file durable facts with orboto_knowledge_add.',
     inputSchema: z.object({
         projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
         ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
@@ -132,6 +133,30 @@ async function buildTicketBundle(client, ticketKey) {
         },
     };
 }
+/** ORB-2225 - the Knowledge block stays small; the rest is one expand away. */
+export const KNOWLEDGE_BLOCK_CHARS = 1500;
+export function knowledgeLines(text) {
+    if (text.length <= KNOWLEDGE_BLOCK_CHARS)
+        return { lines: text.split('\n') };
+    const cut = text.slice(0, KNOWLEDGE_BLOCK_CHARS);
+    const kept = cut.slice(0, Math.max(cut.lastIndexOf('\n'), 0));
+    const handle = storePayload('orboto_session_start', {
+        structuredContent: { knowledge: text }, text,
+        omitted: [{ path: 'knowledge', kind: 'string', omittedChars: text.length - kept.length }],
+    });
+    return {
+        handle,
+        lines: [...kept.split('\n'), `(Knowledge block cut at ${kept.length} of ${text.length} characters: orboto_response_expand { handle: "${handle}", path: "knowledge" }, or GET /knowledge.)`],
+    };
+}
+function knowledgeSummary(index, handle) {
+    return {
+        source: index.source,
+        spaces: index.spaces.map((s) => ({ spaceKey: s.spaceKey ?? s.spaceName, projectKey: s.projectKey, indexDocKey: s.indexDoc?.key ?? null, pages: s.pages, sources: s.sources, openLintIssues: s.openLintIssues })),
+        missing: index.missing,
+        ...(handle ? { handle } : {}),
+    };
+}
 /** ORB-2209 - a declared scope stays with the instance token; the agent declares it once per terminal. */
 export function identityLine(registration) {
     const count = registration.reconnects ?? 0;
@@ -185,7 +210,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
             registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
         }
-        const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
+        const [me, rules, assigned, timer, inboxRaw, knowledge] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
@@ -193,6 +218,9 @@ export function makeSessionStartHandler(client, opts = {}) {
             client.get('/v1/agent/messages?limit=10', { instanceToken })
                 .then((r) => (Array.isArray(r?.messages) ? r.messages : []))
                 .catch(() => []),
+            client.get('/knowledge', { instanceToken })
+                .then((r) => (typeof r?.text === 'string' && Array.isArray(r.spaces) && Array.isArray(r.missing) ? r : null))
+                .catch(() => null),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
@@ -267,6 +295,9 @@ export function makeSessionStartHandler(client, opts = {}) {
         }
         lines.push('', '## Timer');
         lines.push(timer?.ticketId ? `Running on ${timer.ticketKey ?? timer.ticketId} since ${timer.startedAt ?? 'earlier'}.` : 'No timer running.');
+        const knowledgeBlock = knowledge?.text ? knowledgeLines(knowledge.text) : null;
+        if (knowledgeBlock)
+            lines.push('', ...knowledgeBlock.lines);
         lines.push('', '## This session');
         const scopeText = registration?.scope
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
@@ -315,6 +346,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                         .filter((p) => p.connections.length > 0),
                     healthyCount: gitHealthWithConnections.reduce((n, p) => n + p.connections.filter((c) => c.healthy).length, 0),
                 },
+                ...(knowledge ? { knowledge: knowledgeSummary(knowledge, knowledgeBlock?.handle) } : {}),
                 ...(pendingMessages.length > 0 ? { pendingMessages } : {}),
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },

package/dist/tools/wiki.js

@@ -54,7 +54,7 @@ export function makeWikiAskHandler(client) {
 }
 export const wikiLintToolConfig = {
     title: 'Run the LLM-Wiki lint pass on a space',
-    description: 'Scan an LLM-Wiki space for inconsistencies (orphan pages, missing cross-references, stale pages, unprocessed sources, and - when AI is configured - contradictions and undocumented concepts). Returns the open issues, each with a suggested fix. Wraps POST /spaces/:id/llm-wiki/lint.',
+    description: 'Lint an LLM-Wiki space for inconsistencies. It finds orphan pages, missing cross-references, stale pages, unprocessed sources and, when AI is configured, contradictions and undocumented concepts. Returns the open issues, each with a suggested fix. Wraps POST /spaces/:id/llm-wiki/lint.',
     inputSchema: z.object({
         spaceId: z.string().uuid().describe('The LLM-Wiki space to lint.'),
     }).shape,
@@ -91,7 +91,7 @@ export function makeWikiPlanUpdateHandler(client) {
 }
 export const wikiApplyPlanToolConfig = {
     title: 'Apply a previously-planned wiki edit',
-    description: 'Commit the page operations from a plan created by orboto_wiki_plan_update. Applies every op atomically (each page edit is snapshotted for rollback). Fails with 410 if the plan has expired (>15 min) or was already applied. Wraps POST /spaces/:id/docs/apply-plan.',
+    description: 'Commit the page operations from a plan created by orboto_wiki_plan_update. Applies every op atomically (each page edit is snapshotted for rollback), then rebuilds the index doc of the space and appends a line to its log doc. Fails with 410 if the plan has expired (>15 min) or was already applied. Wraps POST /spaces/:id/docs/apply-plan.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         planId: z.string().uuid().describe('The planId returned by orboto_wiki_plan_update.'),
@@ -106,7 +106,7 @@ export function makeWikiApplyPlanHandler(client) {
 }
 export const wikiRecordToolConfig = {
     title: 'Record a wiki update in one step (plan + apply)',
-    description: 'Convenience wrapper that plans an edit from your instruction and immediately applies it - use mid-task to capture a fact or update a page without the two-step review loop. Internally calls plan-update then apply-plan. For a reviewable change, use orboto_wiki_plan_update instead.',
+    description: 'Plan and apply a wiki edit in one step. Use it mid-task to capture a fact or update a page without the two-step review loop. Internally calls plan-update then apply-plan. For a reviewable change, use orboto_wiki_plan_update instead.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         instruction: z.string().min(1).max(4000).describe('What to record, in plain language.'),
@@ -175,3 +175,28 @@ export function makeWikiFlagStaleHandler(client) {
         return text(res.staleFlagged ? 'Page flagged as possibly outdated.' : 'Stale flag cleared.', { staleFlagged: res.staleFlagged });
     };
 }
+export const wikiRunsToolConfig = {
+    title: 'Wiki ingest runs',
+    description: 'List the ingest runs of a wiki space (status failed shows each error) or retry a failed run.',
+    inputSchema: z.object({
+        spaceId: z.string().min(1),
+        action: z.enum(['list', 'retry']).optional(),
+        runId: z.string().uuid().optional(),
+        status: z.enum(['pending_review', 'applied', 'failed', 'skipped']).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWikiRunsHandler(client) {
+    return async (input) => {
+        if (input.action === 'retry') {
+            if (!input.runId)
+                return { isError: true, content: [{ type: 'text', text: 'action retry needs the runId of a failed run (action list, status failed).' }] };
+            const res = await client.post(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs/${input.runId}/retry`, {});
+            return text(res.queued ? `Run ${res.runId} is queued for the ingest worker again.` : `Run ${res.runId} ran again: ${res.status}${res.error ? ` - ${res.error}` : ''}.`, res);
+        }
+        const qs = input.status ? `?status=${input.status}` : '';
+        const res = await client.get(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs${qs}`);
+        const lines = res.runs.map((r) => `- ${r.id} ${r.status} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.error ? ` - ${r.error}` : ''}`);
+        return text(lines.length ? lines.join('\n') : 'No ingest runs.', res);
+    };
+}

package/dist/tools/work-sessions.js

@@ -314,7 +314,7 @@ export function makeWorkSessionStartHandler(client) {
 }
 export const workSessionFinishToolConfig = {
     title: 'Finish a work session (books time, frees the lease)',
-    description: 'End a work session: its timer is stopped and booked, the (ticket, role) lease is released for the next agent, and the evidence you pass (commit sha + which gates you ran) is recorded on the session. Idempotent - finishing an already-finished session succeeds and still absorbs late evidence, so a retrying harness never has to distinguish "already done" from "failed". This does NOT close the ticket; ticket status is a separate, deliberate decision (use orboto_close_ticket once the acceptance criteria are verified). Prefer orboto_work_finish (ORB-1612) for an `implementation` session that is actually done - it does this AND the ticket transition AND the completion note in one call.',
+    description: 'End a work session: timer booked, lease released, evidence recorded. The timer is stopped and booked, the (ticket, role) lease is released for the next agent, and the evidence you pass (commit sha + which gates you ran) is recorded on the session. Idempotent - finishing an already-finished session succeeds and still absorbs late evidence, so a retrying harness never has to distinguish "already done" from "failed". This does NOT close the ticket; ticket status is a separate, deliberate decision (use orboto_close_ticket once the acceptance criteria are verified). Prefer orboto_work_finish (ORB-1612) for an `implementation` session that is actually done - it does this AND the ticket transition AND the completion note in one call.',
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         outcome: z.enum(['finished', 'cancelled']).optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.207.0",
+  "version": "0.208.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",