@orboto/mcp 0.221.0 → 0.221.11

package/dist/tools/wiki.js

@@ -7,6 +7,7 @@
  * descriptions per the skill/MCP English rule.
  */
 import { z } from 'zod';
+import { SEMANTIC_DEGRADED_LINE, replacedLines } from './shared.js';
 import { resolveDocId } from './docs.js';
 function text(t, structured) {
     return { content: [{ type: 'text', text: t }], ...(structured ? { structuredContent: structured } : {}) };
@@ -49,7 +50,8 @@ export function makeWikiAskHandler(client) {
             body.limit = input.limit;
         const res = await client.post(`/ai/ask-docs`, body);
         const cites = res.citations.map((c) => `[${c.index}] ${c.title} - ${c.link}`).join('\n');
-        return text(`${res.answer}\n\n${cites ? `Sources:\n${cites}` : ''}`.trim(), { answer: res.answer, citations: res.citations, mode: res.mode });
+        const degraded = res.semanticDegraded ? `\n\n(${SEMANTIC_DEGRADED_LINE})` : '';
+        return text(`${res.answer}\n\n${cites ? `Sources:\n${cites}` : ''}`.trim() + degraded, { answer: res.answer, citations: res.citations, mode: res.mode, semanticDegraded: res.semanticDegraded ?? false });
     };
 }
 export const wikiLintToolConfig = {
@@ -98,17 +100,19 @@ 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), 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.',
+    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. ORB-2468: a patch op that drops more than half of its page refuses the whole plan with 409 (nothing written) unless replace is true; each rewritten page comes back in replaced with the revision and the restore command. 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.'),
+        planId: z.string().uuid().describe('From orboto_wiki_plan_update.'),
+        replace: z.boolean().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeWikiApplyPlanHandler(client) {
     return async (input) => {
-        const res = await client.post(`/spaces/${input.spaceId}/docs/apply-plan`, { planId: input.planId });
-        return text(`Applied plan ${input.planId}: ${res.touchedDocs.length} page(s) updated.`, { touchedDocs: res.touchedDocs });
+        const res = await client.post(`/spaces/${input.spaceId}/docs/apply-plan`, { planId: input.planId, ...(input.replace ? { replace: true } : {}) });
+        const replaced = res.replaced ?? [];
+        return text(`Applied plan ${input.planId}: ${res.touchedDocs.length} page(s) updated.${replacedLines(replaced)}`, { touchedDocs: res.touchedDocs, replaced });
     };
 }
 export const wikiRecordToolConfig = {
@@ -150,21 +154,23 @@ export function makeWikiAppendSectionHandler(client) {
 }
 export const wikiSaveAnswerToolConfig = {
     title: 'Save a Q&A answer as a wiki page',
-    description: 'Turn an answer (e.g. from orboto_wiki_ask) into a curated wiki page with smart-links to its citations. Idempotent per (space, question): re-saving the same question updates the page instead of duplicating it. Wraps POST /ai/save-answer-to-wiki.',
+    description: 'Turn an answer (e.g. from orboto_wiki_ask) into a curated wiki page with smart-links to its citations. Idempotent per (space, question): re-saving the same question updates the page instead of duplicating it. ORB-2468: a re-save that drops more than half of the saved page is refused with 409 unless replace is true; an update names the revision it replaced and the restore command. Wraps POST /ai/save-answer-to-wiki.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         question: z.string().min(3).max(1000),
         answer: z.string().min(1).max(50_000),
-        title: z.string().max(200).optional().describe('Page title; defaults to the question.'),
+        title: z.string().max(200).optional().describe('Defaults to the question.'),
         parentDocId: z.string().uuid().optional(),
-        citations: z.array(z.object({ docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'), title: z.string() })).max(50).optional().describe('Cited docs to smart-link (from orboto_wiki_ask).'),
+        citations: z.array(z.object({ docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'), title: z.string() })).max(50).optional().describe('From orboto_wiki_ask.'),
+        replace: z.boolean().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 export function makeWikiSaveAnswerHandler(client) {
     return async (input) => {
         const res = await client.post(`/ai/save-answer-to-wiki`, { ...input, citations: input.citations ?? [] });
-        return text(res.created ? `Saved as a new wiki page (docId: ${res.docId}).` : `Updated the existing wiki page (docId: ${res.docId}).`, { docId: res.docId, created: res.created });
+        const replaced = res.replaced ? [res.replaced] : [];
+        return text(res.created ? `Saved as a new wiki page (docId: ${res.docId}).` : `Updated the existing wiki page (docId: ${res.docId}).${replacedLines(replaced)}`, { docId: res.docId, created: res.created, replaced: res.replaced ?? null });
     };
 }
 export const wikiFlagStaleToolConfig = {

package/dist/tools/wiki.test.js

@@ -69,6 +69,22 @@ describe('orboto_wiki_plan_update + apply_plan', () => {
         const res = await makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' });
         expect(res.content[0].text).toContain('1 page(s) updated');
     });
+    it('ORB-2468 - apply-plan sends replace only when asked and prints each replaced revision with its restore command', async () => {
+        const replaced = { docId: DOC, revisionId: 'r0000000-0000-4000-8000-000000000001', restoreCommand: 'orboto doc restore KB-D4 r0000000-0000-4000-8000-000000000001' };
+        const calls = stubJSON([{ json: { touchedDocs: [DOC] } }, { json: { touchedDocs: [DOC], replaced: [replaced] } }]);
+        await makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' });
+        expect(calls[0].body).toEqual({ planId: 'p1' });
+        const res = await makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1', replace: true });
+        expect(calls[1].body).toEqual({ planId: 'p1', replace: true });
+        const out = res.content[0].text;
+        expect(out).toContain('Replaced: 1');
+        expect(out).toContain(replaced.restoreCommand);
+        expect(res.structuredContent).toMatchObject({ replaced: [replaced] });
+    });
+    it('ORB-2468 - apply-plan surfaces the 409 shrink refusal as OrbotoApiError', async () => {
+        stubJSON([{ ok: false, status: 409, json: { error: 'This write would drop 90% of the existing page KB-D4', errorKey: 'errors.docs.replace_drops_content' } }]);
+        await expect(makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
     it('apply-plan surfaces a 410 expired plan as OrbotoApiError', async () => {
         stubJSON([{ ok: false, status: 410, json: { error: 'Plan has expired' } }]);
         await expect(makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' })).rejects.toBeInstanceOf(OrbotoApiError);
@@ -100,6 +116,13 @@ describe('orboto_wiki_save_answer', () => {
         expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://orboto.example.com/ai/save-answer-to-wiki', body: { spaceId: SPACE, question: 'how?', answer: 'like this', citations: [] } });
         expect(res.content[0].text).toMatch(/new wiki page/);
     });
+    it('ORB-2468 - a re-save passes replace and names the replaced revision', async () => {
+        const replaced = { docId: DOC, revisionId: 'r0000000-0000-4000-8000-000000000002', restoreCommand: 'orboto doc restore KB-D5 r0000000-0000-4000-8000-000000000002' };
+        const calls = stubJSON([{ json: { docId: DOC, created: false, replaced } }]);
+        const res = await makeWikiSaveAnswerHandler(client)({ spaceId: SPACE, question: 'how?', answer: 'new', replace: true });
+        expect(calls[0].body).toMatchObject({ replace: true });
+        expect(res.content[0].text).toContain(replaced.restoreCommand);
+    });
 });
 describe('orboto_wiki_flag_stale', () => {
     it('defaults stale=true and reports the flag', async () => {

package/dist/toolset.js

@@ -6,10 +6,11 @@
  */
 /** ORB-2210 - no tools: the agent works through the orboto CLI, the server carries the wake channel. */
 export const CHANNEL_TOOLSET_INSTRUCTIONS = [
+    'FIRST ACTION, before anything else: run `orboto session-start` in the shell - it prints the binding workspace rules and your in-progress work; run it again after a context compaction.',
     'orboto is a ticket and project management system; ticket keys look like `PROJ-123`.',
-    'This server carries no tools. Work through the orboto CLI in the shell: `orboto help` lists the commands,',
-    '`orboto session-start` prints the binding workspace rules and your in-progress work (run it first and after a context compaction),',
+    'This server carries no tools. Work through the orboto CLI: `orboto help` lists the commands,',
     'and `orboto agent-heartbeat --role <role> --scope-projects <KEY,KEY>` declares what this session is responsible for.',
+    'Before you send agent mail, `orboto owner "<topic>"` names who owns the topic.',
     'Always: claim or create a ticket before touching code, one commit per ticket with the key in the subject, never mark work done that is not done.',
     'MCP tools come back on request: `?toolset=curated|full` (HTTP) or ORBOTO_MCP_TOOLSET=curated|full (stdio).',
 ].join(' ');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.221.0",
+  "version": "0.221.11",
   "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",