@tacitai/mcp-server 0.6.23 → 0.6.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/tools/gm.js CHANGED
@@ -9,8 +9,9 @@
9
9
  import * as fs from 'fs';
10
10
  import * as path from 'path';
11
11
  import { z } from 'zod';
12
- import { TacitClient, TacitApiError, TokenExpiredError } from '../client.js';
12
+ import { TacitClient, TacitApiError, TokenExpiredError, getRequestPrincipal } from '../client.js';
13
13
  import { featureDisabledResult } from './errors.js';
14
+ import { GM_APPROVE_NEXT_STEP } from '../workflow-gate.js';
14
15
  function apiErrorResult(err, toolName) {
15
16
  if (err instanceof TokenExpiredError) {
16
17
  return {
@@ -181,6 +182,7 @@ export const gmIngestInputSchema = z.object({
181
182
  domain: z.string().optional(),
182
183
  content_type: z.string().optional(),
183
184
  }).optional().describe('Optional hints for the classifier'),
185
+ cross_reference: z.boolean().optional().describe('Set true when the user wants the content placed on two surfaces (pyramid AND KB) — chains a second placement cycle after the first completes'),
184
186
  });
185
187
  export const GM_INGEST_TOOL_DEF = {
186
188
  name: 'tacit_gm_ingest',
@@ -207,6 +209,10 @@ export const GM_INGEST_TOOL_DEF = {
207
209
  },
208
210
  description: 'Optional hints for the classifier',
209
211
  },
212
+ cross_reference: {
213
+ type: 'boolean',
214
+ description: 'Set true when the user wants the content placed on two surfaces (pyramid AND KB) — chains a second placement cycle after the first completes',
215
+ },
210
216
  },
211
217
  required: ['title'],
212
218
  },
@@ -244,6 +250,8 @@ export function buildGmIngestRequest(client, input) {
244
250
  body['content_type'] = input.content_type;
245
251
  if (input.classification_hints !== undefined)
246
252
  body['classification_hints'] = input.classification_hints;
253
+ // cross_reference is deliberately NOT sent: it is an MCP-layer workflow flag
254
+ // (FEAT-249) consumed by the WorkflowGate in registerGmTools, not a backend field.
247
255
  const result = await client.post('/api/v1/gm/ingest', body);
248
256
  return {
249
257
  content: [
@@ -277,6 +285,7 @@ export const gmApproveInputSchema = z.object({
277
285
  surface: z.string(),
278
286
  reason: z.string().optional(),
279
287
  }).strict()).optional().default([]).describe('Targets to explicitly reject'),
288
+ target_path: z.string().min(1).optional().describe('Fast-track: named portfolio/value-stream/program/dossier (name or UUID) whose existence the server validates in place of the drill-down'),
280
289
  }).strict();
281
290
  export const GM_APPROVE_TOOL_DEF = {
282
291
  name: 'tacit_gm_approve',
@@ -284,6 +293,8 @@ export const GM_APPROVE_TOOL_DEF = {
284
293
  'Place an artifact created by tacit_gm_ingest in the pyramid: sets its program (and portfolio) home and, ' +
285
294
  'if dossier_id is given, adds it to that dossier, in one transaction. Exactly one pyramid target per call. ' +
286
295
  'Does NOT place KB content; use tacit_kb_promote_from_artifact (SOP-03). ' +
296
+ 'Optionally pass target_path (a named portfolio/value-stream/program/dossier) to fast-track: the server validates ' +
297
+ 'it in place of the four pyramid list-tool drill-down calls. ' +
287
298
  'Refuses catalog entries that are not ACTIVE and deleted artifacts. ' +
288
299
  'Repeat calls are idempotent for placement and record one PlacementApproved event each. ' +
289
300
  'Route: POST /api/v1/gm/approve.',
@@ -321,6 +332,10 @@ export const GM_APPROVE_TOOL_DEF = {
321
332
  },
322
333
  description: 'Targets to explicitly reject',
323
334
  },
335
+ target_path: {
336
+ type: 'string',
337
+ description: 'Fast-track: named portfolio/value-stream/program/dossier (name or UUID) whose existence the server validates in place of the drill-down',
338
+ },
324
339
  },
325
340
  required: ['catalog_id', 'approved_targets'],
326
341
  },
@@ -352,14 +367,181 @@ export async function handleGmApprove(args) {
352
367
  }
353
368
  return buildGmApproveRequest(new TacitClient(), parsed.data).execute();
354
369
  }
370
+ /** List endpoints return either a bare array or a wrapped object; accept both. */
371
+ function asRowArray(res) {
372
+ if (Array.isArray(res))
373
+ return res;
374
+ if (res && typeof res === 'object') {
375
+ for (const key of ['items', 'data', 'portfolios', 'programs', 'dossiers', 'value_streams']) {
376
+ const v = res[key];
377
+ if (Array.isArray(v))
378
+ return v;
379
+ }
380
+ }
381
+ return [];
382
+ }
383
+ function collectTargetKeys(res, keys) {
384
+ for (const row of asRowArray(res)) {
385
+ for (const field of ['id', 'portfolio_id', 'program_id', 'value_stream_id', 'dossier_id', 'collection_id', 'name', 'display_name']) {
386
+ const v = row[field];
387
+ if (typeof v === 'string' && v)
388
+ keys.add(v.toLowerCase());
389
+ }
390
+ }
391
+ }
392
+ /**
393
+ * Variation C fast-track: validate a named target against the SAME endpoints the four
394
+ * pyramid list tools wrap (GET /portfolios, /alignment/value-streams, /dossiers, and
395
+ * /portfolios/:id/programs — no new backend endpoint). Every path segment (split on
396
+ * →, ->, >, or /) must match an existing portfolio, value stream, program, or dossier —
397
+ * UUID exact or name case-insensitive, at any level.
398
+ */
399
+ async function validateFastTrackTarget(client, targetPath) {
400
+ const segments = targetPath.split(/\s*(?:→|->|>|\/)\s*/).map((s) => s.trim()).filter(Boolean);
401
+ if (segments.length === 0)
402
+ return { ok: false, reason: 'it contains no target segments' };
403
+ const portfolios = await client.get('/api/v1/portfolios');
404
+ const [valueStreams, dossiers] = await Promise.all([
405
+ client.get('/api/v1/alignment/value-streams'),
406
+ client.get('/api/v1/dossiers'),
407
+ ]);
408
+ const known = new Set();
409
+ collectTargetKeys(portfolios, known);
410
+ collectTargetKeys(valueStreams, known);
411
+ collectTargetKeys(dossiers, known);
412
+ // Programs are scoped per portfolio — enumerate under each portfolio like the list tool does.
413
+ for (const p of asRowArray(portfolios)) {
414
+ // Real API returns portfolio_id (E2E catch: p['id'] alone left pid undefined and
415
+ // the programs enumeration never ran — program fast-tracks always failed).
416
+ const pid = p['id'] ?? p['portfolio_id'];
417
+ if (typeof pid === 'string') {
418
+ collectTargetKeys(await client.get(`/api/v1/portfolios/${pid}/programs`), known);
419
+ }
420
+ }
421
+ for (const seg of segments) {
422
+ if (!known.has(seg.toLowerCase())) {
423
+ return { ok: false, reason: `no portfolio, value stream, program, or dossier matching "${sanitizeEcho(seg)}" exists` };
424
+ }
425
+ }
426
+ return { ok: true };
427
+ }
428
+ /**
429
+ * Caller-controlled text echoed into tool results: truncate and strip control
430
+ * characters so a crafted target_path cannot smuggle newlines/escapes into the
431
+ * consuming LLM's context (sec audit LOW — prompt-injection echo surface).
432
+ */
433
+ function sanitizeEcho(value, max = 200) {
434
+ const cleaned = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
435
+ return cleaned.length > max ? cleaned.slice(0, max) + '\u2026' : cleaned;
436
+ }
355
437
  // ─── Registration ───────────────────────────────────────────────────────────
356
- export function registerGmTools(server, getClientFn) {
438
+ export const gmResetInputSchema = z.object({}).strict();
439
+ export const GM_RESET_TOOL_DEF = {
440
+ name: 'tacit_gm_reset',
441
+ description: 'Reset the GM placement workflow: clears the recorded drill-down calls and returns the workflow to the surface-choice step ' +
442
+ 'with the same catalog entry and artifact. Use when the user changes their mind about the surface mid-flow — ' +
443
+ "after a reset, offer the surfaces again and run the new surface's drill-down from scratch.",
444
+ inputSchema: {
445
+ type: 'object',
446
+ properties: {},
447
+ required: [],
448
+ },
449
+ };
450
+ export function registerGmTools(server, getClientFn, gate) {
357
451
  server.tool('tacit_gm_ingest', GM_INGEST_TOOL_DEF.description, gmIngestInputSchema.shape, async (args) => {
358
452
  const client = await getClientFn();
359
- return buildGmIngestRequest(client, args).execute();
453
+ const input = args;
454
+ const res = await buildGmIngestRequest(client, input).execute();
455
+ if (!res.isError) {
456
+ // FEAT-249: arm (or supersede) the GM workflow from the ingest response.
457
+ // cross_reference is an MCP-layer flag — it never reaches the backend POST.
458
+ const principal = getRequestPrincipal();
459
+ try {
460
+ const payload = JSON.parse(res.content[0].text);
461
+ const artifactId = payload['artifact_id'];
462
+ const catalogId = payload['catalog_id'];
463
+ if (typeof artifactId === 'string' && typeof catalogId === 'string') {
464
+ gate.startWorkflow(principal, { artifactId, catalogId, crossReference: input.cross_reference === true });
465
+ }
466
+ else {
467
+ process.stderr.write('[tacit_gm_ingest] GM workflow not armed: ingest response is missing artifact_id/catalog_id\n');
468
+ }
469
+ }
470
+ catch {
471
+ process.stderr.write('[tacit_gm_ingest] GM workflow not armed: could not parse ingest response\n');
472
+ }
473
+ }
474
+ return res;
360
475
  });
361
476
  server.tool('tacit_gm_approve', GM_APPROVE_TOOL_DEF.description, gmApproveInputSchema.shape, async (args) => {
477
+ const parsed = gmApproveInputSchema.safeParse(args);
478
+ if (!parsed.success) {
479
+ return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
480
+ }
481
+ const input = parsed.data;
482
+ const principal = getRequestPrincipal();
483
+ // Fast-track (Variation C): a server-validated target_path stands in for the
484
+ // drill-down — only consulted when the call log does not already satisfy it.
485
+ if (input.target_path !== undefined && !gate.checkPyramidApprove(principal).allowed) {
486
+ const client = await getClientFn();
487
+ let validation;
488
+ try {
489
+ validation = await validateFastTrackTarget(client, input.target_path);
490
+ }
491
+ catch {
492
+ // Infra failure during validation surfaces as the structured drill-down
493
+ // rejection, not an uncaught SDK-level protocol error.
494
+ validation = { ok: false, reason: 'fast-track validation could not reach the pyramid endpoints — run the drill-down instead' };
495
+ }
496
+ if (!validation.ok) {
497
+ return {
498
+ content: [{
499
+ type: 'text',
500
+ text: `tacit_gm_approve rejected: target_path "${sanitizeEcho(input.target_path)}" is not validated — ${validation.reason}. ` +
501
+ 'No placement was attempted. Run the pyramid drill-down (tacit_pyramid_list_portfolios, ' +
502
+ 'tacit_pyramid_list_value_streams, tacit_pyramid_list_programs, tacit_pyramid_list_dossiers) ' +
503
+ 'or correct the target name.',
504
+ }],
505
+ isError: true,
506
+ };
507
+ }
508
+ gate.markFastTrackValidated(principal);
509
+ }
510
+ const verdict = gate.checkPyramidApprove(principal);
511
+ if (!verdict.allowed) {
512
+ return {
513
+ content: [{ type: 'text', text: verdict.message ?? 'tacit_gm_approve rejected: drill-down prerequisite not met.' }],
514
+ isError: true,
515
+ };
516
+ }
362
517
  const client = await getClientFn();
363
- return buildGmApproveRequest(client, args).execute();
518
+ const res = await buildGmApproveRequest(client, input).execute();
519
+ if (!res.isError) {
520
+ // Snapshot BEFORE completing: the cross-reference banner depends on the
521
+ // pre-completion placementsRemaining.
522
+ const before = gate.getWorkflow(principal);
523
+ // Idempotency key: an identical retry of an already-counted approve must not
524
+ // consume a second placement slot (the backend approve is idempotent).
525
+ gate.completePlacement(principal, `py:${input.catalog_id}:${JSON.stringify(input.approved_targets)}`);
526
+ if (before?.active && before.crossReference && before.placementsRemaining > 1) {
527
+ res.content.push({ type: 'text', text: GM_APPROVE_NEXT_STEP });
528
+ }
529
+ }
530
+ return res;
531
+ });
532
+ server.tool('tacit_gm_reset', GM_RESET_TOOL_DEF.description, gmResetInputSchema.shape, async () => {
533
+ const principal = getRequestPrincipal();
534
+ const snapshot = gate.resetWorkflow(principal);
535
+ const rearm = snapshot.active
536
+ ? 'The workflow is rearmed with the same catalog entry and artifact.'
537
+ : 'No GM workflow exists to rearm — start with tacit_gm_ingest.';
538
+ return {
539
+ content: [{
540
+ type: 'text',
541
+ text: `GM workflow reset: the recorded drill-down is cleared. ${rearm} Surface choice starts over — offer the surfaces ` +
542
+ '(workspace structure, knowledge base, both, or data lake) again and run the chosen surface\'s drill-down ' +
543
+ 'from scratch before proposing a location.',
544
+ }],
545
+ };
364
546
  });
365
547
  }
@@ -14,6 +14,7 @@
14
14
  import { z } from 'zod';
15
15
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
16
16
  import { TacitClient } from '../client.js';
17
+ import { WorkflowGate } from '../workflow-gate.js';
17
18
  export interface ToolRequest {
18
19
  execute(): Promise<{
19
20
  content: Array<{
@@ -396,12 +397,15 @@ export declare function handleBrowseTree(args: unknown): Promise<{
396
397
  export declare const promoteFromArtifactInputSchema: z.ZodObject<{
397
398
  artifact_id: z.ZodString;
398
399
  collection_id: z.ZodString;
400
+ status: z.ZodOptional<z.ZodEnum<["DRAFT", "PUBLISHED"]>>;
399
401
  }, "strip", z.ZodTypeAny, {
400
402
  artifact_id: string;
401
403
  collection_id: string;
404
+ status?: "DRAFT" | "PUBLISHED" | undefined;
402
405
  }, {
403
406
  artifact_id: string;
404
407
  collection_id: string;
408
+ status?: "DRAFT" | "PUBLISHED" | undefined;
405
409
  }>;
406
410
  export type PromoteFromArtifactInput = z.infer<typeof promoteFromArtifactInputSchema>;
407
411
  export declare const PROMOTE_FROM_ARTIFACT_TOOL_DEF: {
@@ -418,6 +422,11 @@ export declare const PROMOTE_FROM_ARTIFACT_TOOL_DEF: {
418
422
  type: string;
419
423
  description: string;
420
424
  };
425
+ status: {
426
+ type: string;
427
+ enum: string[];
428
+ description: string;
429
+ };
421
430
  };
422
431
  required: string[];
423
432
  };
@@ -541,4 +550,4 @@ export declare function handleCreateCategory(args: unknown): Promise<{
541
550
  }>;
542
551
  isError?: boolean;
543
552
  }>;
544
- export declare function registerKbTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;
553
+ export declare function registerKbTools(server: McpServer, getClientFn: () => Promise<TacitClient>, gate: WorkflowGate): void;
package/dist/tools/kb.js CHANGED
@@ -12,8 +12,9 @@
12
12
  * GET/POST /knowledge/categories
13
13
  */
14
14
  import { z } from 'zod';
15
- import { getClient, TacitApiError, TokenExpiredError } from '../client.js';
15
+ import { getClient, getRequestPrincipal, TacitApiError, TokenExpiredError } from '../client.js';
16
16
  import { apiErrorResult as sharedApiErrorResult, featureDisabledResult } from './errors.js';
17
+ import { GM_LIST_TOOL_NEXT_STEP } from '../workflow-gate.js';
17
18
  function apiErrorResult(err, toolName) {
18
19
  if (err instanceof TokenExpiredError) {
19
20
  return {
@@ -416,18 +417,22 @@ export async function handleBrowseTree(args) {
416
417
  export const promoteFromArtifactInputSchema = z.object({
417
418
  artifact_id: z.string().min(1).describe('UUID of the artifact to promote into the KB'),
418
419
  collection_id: z.string().min(1).describe('UUID of an existing collection to place the promoted article in'),
420
+ status: z.enum(['DRAFT', 'PUBLISHED']).optional().describe('GM-workflow placement passes DRAFT (the article lands as a draft); standalone promotion defaults to PUBLISHED and is itself the publish action'),
419
421
  });
420
422
  export const PROMOTE_FROM_ARTIFACT_TOOL_DEF = {
421
423
  name: 'tacit_kb_promote_from_artifact',
422
424
  description: 'APPROVAL-TIER: call only after the user approved this specific collection. ' +
423
425
  'This is the KB placement step after tacit_gm_ingest (use the artifact_id it returned). ' +
424
- 'Promote an existing artifact into a published KB article, placing it in the given collection. ' +
426
+ 'Promote an existing artifact into a KB article, placing it in the given collection. ' +
427
+ 'Through a GM workflow pass status "DRAFT" (the article lands as a draft the user can publish anytime); ' +
428
+ 'standalone promotion defaults to PUBLISHED and is itself the publish action. ' +
425
429
  'Idempotent — re-promoting an already-promoted artifact only applies the new placement.',
426
430
  inputSchema: {
427
431
  type: 'object',
428
432
  properties: {
429
433
  artifact_id: { type: 'string', description: 'UUID of the artifact to promote' },
430
434
  collection_id: { type: 'string', description: 'UUID of an existing collection' },
435
+ status: { type: 'string', enum: ['DRAFT', 'PUBLISHED'], description: 'DRAFT for GM-workflow placement; standalone defaults to PUBLISHED' },
431
436
  },
432
437
  required: ['artifact_id', 'collection_id'],
433
438
  },
@@ -441,6 +446,10 @@ export function buildPromoteFromArtifactRequest(client, input) {
441
446
  kb: { collections: [input.collection_id] },
442
447
  },
443
448
  };
449
+ // Top-level status, included only when set: absent means the backend's own
450
+ // default (published) — standalone promotion IS the publish action.
451
+ if (input.status !== undefined)
452
+ body['status'] = input.status;
444
453
  const result = await client.post(`/api/v1/knowledge/articles/from-artifact/${input.artifact_id}`, body);
445
454
  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
446
455
  }
@@ -464,9 +473,12 @@ export const promoteFromCatalogInputSchema = z.object({
464
473
  });
465
474
  export const PROMOTE_FROM_CATALOG_TOOL_DEF = {
466
475
  name: 'tacit_kb_promote_from_catalog',
467
- description: 'Promote a data lake catalog item into a published KB article. ' +
476
+ description: 'Promote a data lake catalog item into a KB article. ' +
468
477
  'Resolves the catalog item\'s artifact_id and delegates to the promote-from-artifact endpoint. ' +
469
- 'The catalog item must have an artifact_id (created via LAKE-17 artifact bridge).',
478
+ 'The catalog item must have an artifact_id (created via LAKE-17 artifact bridge). ' +
479
+ 'Through a GM workflow on the workflow\'s own artifact this is gated exactly like ' +
480
+ 'tacit_kb_promote_from_artifact (requires tacit_kb_list_collections first; lands DRAFT); ' +
481
+ 'standalone promotes with no active workflow publish immediately.',
470
482
  inputSchema: {
471
483
  type: 'object',
472
484
  properties: {
@@ -589,10 +601,19 @@ export async function handleCreateCategory(args) {
589
601
  }
590
602
  return buildCreateCategoryRequest(getClient(), parsed.data).execute();
591
603
  }
592
- export function registerKbTools(server, getClientFn) {
604
+ export function registerKbTools(server, getClientFn, gate) {
593
605
  server.tool('tacit_kb_list_collections', LIST_COLLECTIONS_TOOL_DEF.description, listCollectionsInputSchema.shape, async (args) => {
606
+ const principal = getRequestPrincipal();
594
607
  const client = await getClientFn();
595
- return buildListCollectionsRequest(client, args).execute();
608
+ const res = await buildListCollectionsRequest(client, args).execute();
609
+ if (!res.isError) {
610
+ // FEAT-249: the KB drill-down prerequisite — only successful calls count.
611
+ gate.recordCall(principal, 'tacit_kb_list_collections');
612
+ if (gate.isGuidanceActive(principal)) {
613
+ res.content.push({ type: 'text', text: GM_LIST_TOOL_NEXT_STEP['tacit_kb_list_collections'] });
614
+ }
615
+ }
616
+ return res;
596
617
  });
597
618
  server.tool('tacit_kb_create_collection', CREATE_COLLECTION_TOOL_DEF.description, createCollectionInputSchema.shape, async (args) => {
598
619
  const client = await getClientFn();
@@ -627,12 +648,77 @@ export function registerKbTools(server, getClientFn) {
627
648
  return buildBrowseTreeRequest(client, args).execute();
628
649
  });
629
650
  server.tool('tacit_kb_promote_from_artifact', PROMOTE_FROM_ARTIFACT_TOOL_DEF.description, promoteFromArtifactInputSchema.shape, async (args) => {
651
+ const parsed = promoteFromArtifactInputSchema.safeParse(args);
652
+ if (!parsed.success) {
653
+ return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
654
+ }
655
+ const input = parsed.data;
656
+ const principal = getRequestPrincipal();
657
+ // FEAT-249: gated only while a GM workflow is active AND this is the workflow's
658
+ // own artifact; standalone promotion (SOP-03) passes through ungated.
659
+ const verdict = gate.checkKbPromote(principal, input.artifact_id);
660
+ if (!verdict.allowed) {
661
+ return {
662
+ content: [{ type: 'text', text: verdict.message ?? 'tacit_kb_promote_from_artifact rejected: prerequisite not met.' }],
663
+ isError: true,
664
+ };
665
+ }
630
666
  const client = await getClientFn();
631
- return buildPromoteFromArtifactRequest(client, args).execute();
667
+ const res = await buildPromoteFromArtifactRequest(client, input).execute();
668
+ if (!res.isError) {
669
+ // Complete the workflow only when it was the workflow's own artifact — a promote
670
+ // of a different artifact is placement-unrelated and neither gated nor completing.
671
+ const snap = gate.getWorkflow(principal);
672
+ if (snap?.active && snap.artifactId === input.artifact_id) {
673
+ gate.completePlacement(principal, `kb:${input.artifact_id}:${input.collection_id}`);
674
+ }
675
+ }
676
+ return res;
632
677
  });
633
678
  server.tool('tacit_kb_promote_from_catalog', PROMOTE_FROM_CATALOG_TOOL_DEF.description, promoteFromCatalogInputSchema.shape, async (args) => {
679
+ const parsed = promoteFromCatalogInputSchema.safeParse(args);
680
+ if (!parsed.success) {
681
+ return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
682
+ }
683
+ const input = parsed.data;
684
+ const principal = getRequestPrincipal();
634
685
  const client = await getClientFn();
635
- return buildPromoteFromCatalogRequest(client, args).execute();
686
+ // FEAT-249: the catalog variant resolves the artifact internally — and the ingest
687
+ // response hands the caller the workflow's catalog_id. Without applying the same
688
+ // gate as promote_from_artifact here, promoting the workflow's own catalog entry
689
+ // would bypass the KB chain (drill-down + DRAFT + completion).
690
+ const snap = gate.getWorkflow(principal);
691
+ let detail;
692
+ try {
693
+ detail = (await client.get(`/api/v1/org/lake/catalog/${input.catalog_item_id}`));
694
+ }
695
+ catch (err) {
696
+ return apiErrorResult(err, 'tacit_kb_promote_from_catalog');
697
+ }
698
+ const artifactId = detail?.artifact_id;
699
+ if (typeof artifactId !== 'string') {
700
+ return {
701
+ content: [{ type: 'text', text: `Catalog item ${input.catalog_item_id} has no artifact_id — run a sync first (LAKE-17 artifact bridge creates artifacts on ingest).` }],
702
+ isError: true,
703
+ };
704
+ }
705
+ const verdict = gate.checkKbPromote(principal, artifactId);
706
+ if (!verdict.allowed) {
707
+ return {
708
+ content: [{ type: 'text', text: verdict.message ?? 'tacit_kb_promote_from_catalog rejected: prerequisite not met.' }],
709
+ isError: true,
710
+ };
711
+ }
712
+ const gated = snap?.active === true && snap.artifactId === artifactId;
713
+ const res = await buildPromoteFromArtifactRequest(client, {
714
+ artifact_id: artifactId,
715
+ collection_id: input.collection_id,
716
+ status: gated ? 'DRAFT' : undefined,
717
+ }).execute();
718
+ if (!res.isError && gated) {
719
+ gate.completePlacement(principal, `kb:${artifactId}:${input.collection_id}`);
720
+ }
721
+ return res;
636
722
  });
637
723
  server.tool('tacit_kb_list_categories', LIST_CATEGORIES_TOOL_DEF.description, listCategoriesInputSchema.shape, async (args) => {
638
724
  const client = await getClientFn();
@@ -12,6 +12,7 @@
12
12
  import { z } from 'zod';
13
13
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
14
14
  import { TacitClient } from '../client.js';
15
+ import { WorkflowGate } from '../workflow-gate.js';
15
16
  export interface ToolRequest {
16
17
  execute(): Promise<{
17
18
  content: Array<{
@@ -551,4 +552,4 @@ export declare function handleAssignProgramToVS(args: unknown): Promise<{
551
552
  }>;
552
553
  isError?: boolean;
553
554
  }>;
554
- export declare function registerPyramidTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;
555
+ export declare function registerPyramidTools(server: McpServer, getClientFn: () => Promise<TacitClient>, gate: WorkflowGate): void;
@@ -10,8 +10,9 @@
10
10
  * GET/POST /alignment/value-streams
11
11
  */
12
12
  import { z } from 'zod';
13
- import { getClient, TacitApiError, TokenExpiredError } from '../client.js';
13
+ import { getClient, getRequestPrincipal, TacitApiError, TokenExpiredError } from '../client.js';
14
14
  import { apiErrorResult as sharedApiErrorResult, featureDisabledResult } from './errors.js';
15
+ import { GM_LIST_TOOL_NEXT_STEP } from '../workflow-gate.js';
15
16
  function apiErrorResult(err, toolName) {
16
17
  if (err instanceof TokenExpiredError) {
17
18
  return {
@@ -551,10 +552,27 @@ export async function handleAssignProgramToVS(args) {
551
552
  }
552
553
  return buildAssignProgramToVSRequest(getClient(), parsed.data).execute();
553
554
  }
554
- export function registerPyramidTools(server, getClientFn) {
555
+ /**
556
+ * FEAT-249 Layer 2: record a shared list call and, while a GM placement workflow is
557
+ * active, append the workflow's drill-down guidance to the result. Successful calls
558
+ * only — a failed request must not satisfy the drill-down prerequisite. With no
559
+ * active workflow nothing is recorded or attached (audits and read-only browses stay clean).
560
+ */
561
+ function attachGmGuidance(gate, principal, toolName, res) {
562
+ if (res.isError)
563
+ return res;
564
+ gate.recordCall(principal, toolName);
565
+ const guidance = GM_LIST_TOOL_NEXT_STEP[toolName];
566
+ if (gate.isGuidanceActive(principal) && guidance) {
567
+ res.content.push({ type: 'text', text: guidance });
568
+ }
569
+ return res;
570
+ }
571
+ export function registerPyramidTools(server, getClientFn, gate) {
555
572
  server.tool('tacit_pyramid_list_portfolios', 'List all portfolios in the workspace.', {}, async () => {
573
+ const principal = getRequestPrincipal();
556
574
  const client = await getClientFn();
557
- return buildListPortfoliosRequest(client, {}).execute();
575
+ return attachGmGuidance(gate, principal, 'tacit_pyramid_list_portfolios', await buildListPortfoliosRequest(client, {}).execute());
558
576
  });
559
577
  server.tool('tacit_pyramid_create_portfolio', 'Create a new portfolio.', {
560
578
  name: z.string().min(1).describe('Portfolio name'),
@@ -567,8 +585,9 @@ export function registerPyramidTools(server, getClientFn) {
567
585
  server.tool('tacit_pyramid_list_programs', 'List programs within a portfolio.', {
568
586
  portfolio_id: z.string().min(1).describe('Portfolio UUID'),
569
587
  }, async (args) => {
588
+ const principal = getRequestPrincipal();
570
589
  const client = await getClientFn();
571
- return buildListProgramsRequest(client, args).execute();
590
+ return attachGmGuidance(gate, principal, 'tacit_pyramid_list_programs', await buildListProgramsRequest(client, args).execute());
572
591
  });
573
592
  server.tool('tacit_pyramid_create_program', 'Create a new program within a portfolio.', {
574
593
  portfolio_id: z.string().min(1).describe('Parent portfolio UUID'),
@@ -584,8 +603,9 @@ export function registerPyramidTools(server, getClientFn) {
584
603
  return buildCreateProgramRequest(client, args).execute();
585
604
  });
586
605
  server.tool('tacit_pyramid_list_dossiers', 'List dossiers in the workspace.', {}, async () => {
606
+ const principal = getRequestPrincipal();
587
607
  const client = await getClientFn();
588
- return buildListDossiersRequest(client, {}).execute();
608
+ return attachGmGuidance(gate, principal, 'tacit_pyramid_list_dossiers', await buildListDossiersRequest(client, {}).execute());
589
609
  });
590
610
  server.tool('tacit_pyramid_get_dossier', 'Get a single dossier by ID.', {
591
611
  dossier_id: z.string().min(1).describe('Dossier UUID'),
@@ -628,8 +648,9 @@ export function registerPyramidTools(server, getClientFn) {
628
648
  return buildDeleteDossierRequest(client, args).execute();
629
649
  });
630
650
  server.tool('tacit_pyramid_list_value_streams', 'List all value streams in the workspace.', {}, async () => {
651
+ const principal = getRequestPrincipal();
631
652
  const client = await getClientFn();
632
- return buildListValueStreamsRequest(client, {}).execute();
653
+ return attachGmGuidance(gate, principal, 'tacit_pyramid_list_value_streams', await buildListValueStreamsRequest(client, {}).execute());
633
654
  });
634
655
  server.tool('tacit_pyramid_create_value_stream', 'Create a new value stream under a portfolio.', {
635
656
  portfolio_id: z.string().min(1).describe('Parent portfolio UUID'),
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Compile-time tool classification. Governs which tools may be called over HTTPS.
3
- * Partition: 6 stdio_only + 17 admin_only + 2 gate_only + 125 https = 150.
3
+ * Partition: 6 stdio_only + 18 admin_only + 2 gate_only + 126 https = 152.
4
4
  */
5
5
  export type ToolTransport = 'https' | 'stdio_only' | 'admin_only' | 'gate_only';
6
6
  export type ToolClass = 'read' | 'write' | 'admin' | 'dispatch';
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Compile-time tool classification. Governs which tools may be called over HTTPS.
3
- * Partition: 6 stdio_only + 17 admin_only + 2 gate_only + 125 https = 150.
3
+ * Partition: 6 stdio_only + 18 admin_only + 2 gate_only + 126 https = 152.
4
4
  */
5
5
  const STDIO_ONLY = [
6
6
  'tacit_ingest_file',
@@ -24,6 +24,7 @@ const ADMIN_ONLY = [
24
24
  'tacit_lake_folder_merge',
25
25
  'tacit_lake_folder_remove',
26
26
  'tacit_lake_delete_catalog_item',
27
+ 'tacit_lake_restore_catalog_item',
27
28
  'tacit_github_disconnect_connection',
28
29
  'tacit_github_reconnect_connection',
29
30
  'tacit_compose',
@@ -125,6 +126,7 @@ const WRITE_TOOLS = [
125
126
  'tacit_export_to_git',
126
127
  'tacit_gm_approve',
127
128
  'tacit_gm_ingest',
129
+ 'tacit_gm_reset',
128
130
  'tacit_import_artifact',
129
131
  'tacit_ingest_file',
130
132
  'tacit_ingest_url',
@@ -194,8 +196,8 @@ function build() {
194
196
  if (!exclusive.has(n))
195
197
  add(n, classOf(n), 'https', false);
196
198
  }
197
- if (map.size !== 150)
198
- throw new Error(`tool registry expected 150 tools, got ${map.size}`);
199
+ if (map.size !== 152)
200
+ throw new Error(`tool registry expected 152 tools, got ${map.size}`);
199
201
  return map;
200
202
  }
201
203
  export const TOOL_REGISTRY = build();