@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.
@@ -0,0 +1,119 @@
1
+ /**
2
+ * WorkflowGate — Layer 1 server-side workflow enforcement (FEAT-249).
3
+ *
4
+ * Structural, model-agnostic drill-down prerequisites for the GM content-placement
5
+ * workflow: `tacit_gm_approve` (pyramid) requires the four pyramid list tools to have
6
+ * been called since the last `tacit_gm_ingest` (or a validated fast-track target_path);
7
+ * `tacit_kb_promote_from_artifact` requires `tacit_kb_list_collections` — but only
8
+ * while a GM workflow is active AND the artifact_id matches the workflow's artifact.
9
+ * Standalone KB promotion (SOP-03, no active workflow) stays ungated.
10
+ *
11
+ * Scoping (AC-isolation): one instance per server process. State is keyed by caller
12
+ * principal — on the HTTP transport `getRequestPrincipal()` returns the bearer-token
13
+ * principal (AsyncLocalStorage); on stdio it returns null and every call shares the
14
+ * single '__stdio__' slot, which is correct because a stdio server is one connection.
15
+ * NEVER store gate state inside the per-request AsyncLocalStorage context: it would
16
+ * evaporate between HTTP requests and silently no-op the gate.
17
+ *
18
+ * Lifecycle: active from `tacit_gm_ingest` (which supersedes any prior workflow) until
19
+ * the FINAL placement completes — approve for pyramid, promote of the workflow's own
20
+ * artifact for KB (a promote of a DIFFERENT artifact is placement-unrelated and neither
21
+ * gated nor completing). `cross_reference` keeps the workflow active for a second
22
+ * placement cycle. `tacit_gm_reset` clears the call log and rearms ACTIVE whether or
23
+ * not a placement had completed. Nothing persists across process restarts.
24
+ */
25
+ export interface GateVerdict {
26
+ allowed: boolean;
27
+ missing: string[];
28
+ message?: string;
29
+ }
30
+ export interface WorkflowSnapshot {
31
+ active: boolean;
32
+ artifactId: string | null;
33
+ catalogId: string | null;
34
+ crossReference: boolean;
35
+ placementsRemaining: number;
36
+ }
37
+ /** Drill-down tools required before `tacit_gm_approve` (pyramid surface). */
38
+ export declare const PYRAMID_PREREQ_TOOLS: readonly ["tacit_pyramid_list_portfolios", "tacit_pyramid_list_value_streams", "tacit_pyramid_list_programs", "tacit_pyramid_list_dossiers"];
39
+ /** Drill-down tool required before a GM-workflow KB promotion. */
40
+ export declare const KB_PREREQ_TOOL = "tacit_kb_list_collections";
41
+ export declare class WorkflowGate {
42
+ private readonly maxPrincipals;
43
+ /**
44
+ * Safety valve (sec audit): cap distinct principals so the states Map cannot grow
45
+ * unboundedly. A slot requires a valid credential to create, but unbounded is still
46
+ * a leak. FIFO-evicts (Map insertion order) past the cap; constructor-injectable
47
+ * for tests. Process restart clears everything regardless.
48
+ */
49
+ constructor(maxPrincipals?: number);
50
+ private readonly states;
51
+ private keyOf;
52
+ private stateOf;
53
+ /** Record a shared list-tool call. Counting is per tool; startWorkflow clears the log. */
54
+ recordCall(principal: string | null, toolName: string): void;
55
+ /** `tacit_gm_ingest` succeeded — arm the workflow, superseding any prior one. */
56
+ startWorkflow(principal: string | null, opts: {
57
+ artifactId: string;
58
+ catalogId: string;
59
+ crossReference: boolean;
60
+ }): void;
61
+ /** Guidance-attach predicate (Layer 2): true from ingest until the final placement completes. */
62
+ isGuidanceActive(principal: string | null): boolean;
63
+ /** Read-only copy of the workflow state, or null when none exists. */
64
+ getWorkflow(principal: string | null): WorkflowSnapshot | null;
65
+ /**
66
+ * Pyramid gate for `tacit_gm_approve`. Applied whenever an approve is attempted:
67
+ * the drill-down must have happened (call log since last ingest, or a validated
68
+ * fast-track). Re-approving after a completed placement is allowed while the log
69
+ * still satisfies the prerequisites (idempotent retries), but `tacit_gm_reset`
70
+ * or a new ingest re-arms the requirement.
71
+ */
72
+ checkPyramidApprove(principal: string | null): GateVerdict;
73
+ /**
74
+ * KB gate for `tacit_kb_promote_from_artifact` (and the catalog variant, which
75
+ * resolves to the same artifact). Gated ONLY while a GM workflow is active AND
76
+ * artifactId matches the workflow's artifact; a different artifact or a standalone
77
+ * promotion (SOP-03) passes through ungated and does NOT complete the workflow.
78
+ *
79
+ * Restart asymmetry (ADR-202): a process restart mid-KB-workflow silently downgrades
80
+ * to this ungated path (fail-open), while checkPyramidApprove re-requires the
81
+ * drill-down (fail-closed). The gate is workflow hygiene, not a security boundary —
82
+ * backend authorization (workspace scoping, capabilities) is unaffected either way.
83
+ */
84
+ checkKbPromote(principal: string | null, artifactId: string): GateVerdict;
85
+ /**
86
+ * Variation C fast-track: the handler validated target_path server-side against the
87
+ * same endpoints the list tools wrap. Satisfies the drill-down prerequisite for this
88
+ * cycle only; cleared by ingest supersession and by reset.
89
+ */
90
+ markFastTrackValidated(principal: string | null): void;
91
+ /**
92
+ * A final placement succeeded — `tacit_gm_approve` (pyramid) or a promote of the
93
+ * workflow's own artifact (KB). With cross_reference set the workflow stays active
94
+ * for the second cycle; otherwise it deactivates and shared-list guidance stops.
95
+ *
96
+ * `placementKey` makes completion idempotent: the backend is idempotent, so an
97
+ * identical retry of an already-counted placement (same catalog+targets, or same
98
+ * artifact+collection) must not consume a second budget slot — in a cross_reference
99
+ * workflow a double-decrement would deactivate mid-flow and leave the second
100
+ * surface ungated (and able to land PUBLISHED). A DIFFERENT placement still counts.
101
+ */
102
+ completePlacement(principal: string | null, placementKey: string): void;
103
+ /**
104
+ * Variation D reset: clear the call log, rearm ACTIVE whether or not a placement had
105
+ * completed, keep the workflow's artifact/catalog. The next surface starts its own
106
+ * drill-down from scratch (call log is empty; fast-track is invalidated).
107
+ */
108
+ resetWorkflow(principal: string | null): WorkflowSnapshot;
109
+ /** Full teardown for the principal (tests; production teardown is process exit). */
110
+ clear(principal: string | null): void;
111
+ }
112
+ /**
113
+ * Guidance appended to shared list-tool results while a GM workflow is active.
114
+ * Never attached when no workflow is active (Gap G2: COO audits and read-only
115
+ * browses must not see GM placement instructions).
116
+ */
117
+ export declare const GM_LIST_TOOL_NEXT_STEP: Record<string, string>;
118
+ /** Appended to approve results when cross_reference is set and a second cycle remains. */
119
+ export declare const GM_APPROVE_NEXT_STEP: string;
@@ -0,0 +1,250 @@
1
+ /**
2
+ * WorkflowGate — Layer 1 server-side workflow enforcement (FEAT-249).
3
+ *
4
+ * Structural, model-agnostic drill-down prerequisites for the GM content-placement
5
+ * workflow: `tacit_gm_approve` (pyramid) requires the four pyramid list tools to have
6
+ * been called since the last `tacit_gm_ingest` (or a validated fast-track target_path);
7
+ * `tacit_kb_promote_from_artifact` requires `tacit_kb_list_collections` — but only
8
+ * while a GM workflow is active AND the artifact_id matches the workflow's artifact.
9
+ * Standalone KB promotion (SOP-03, no active workflow) stays ungated.
10
+ *
11
+ * Scoping (AC-isolation): one instance per server process. State is keyed by caller
12
+ * principal — on the HTTP transport `getRequestPrincipal()` returns the bearer-token
13
+ * principal (AsyncLocalStorage); on stdio it returns null and every call shares the
14
+ * single '__stdio__' slot, which is correct because a stdio server is one connection.
15
+ * NEVER store gate state inside the per-request AsyncLocalStorage context: it would
16
+ * evaporate between HTTP requests and silently no-op the gate.
17
+ *
18
+ * Lifecycle: active from `tacit_gm_ingest` (which supersedes any prior workflow) until
19
+ * the FINAL placement completes — approve for pyramid, promote of the workflow's own
20
+ * artifact for KB (a promote of a DIFFERENT artifact is placement-unrelated and neither
21
+ * gated nor completing). `cross_reference` keeps the workflow active for a second
22
+ * placement cycle. `tacit_gm_reset` clears the call log and rearms ACTIVE whether or
23
+ * not a placement had completed. Nothing persists across process restarts.
24
+ */
25
+ /** Drill-down tools required before `tacit_gm_approve` (pyramid surface). */
26
+ export const PYRAMID_PREREQ_TOOLS = [
27
+ 'tacit_pyramid_list_portfolios',
28
+ 'tacit_pyramid_list_value_streams',
29
+ 'tacit_pyramid_list_programs',
30
+ 'tacit_pyramid_list_dossiers',
31
+ ];
32
+ /** Drill-down tool required before a GM-workflow KB promotion. */
33
+ export const KB_PREREQ_TOOL = 'tacit_kb_list_collections';
34
+ function staleSurfaceHint(surface) {
35
+ return `A ${surface} drill-down is already recorded for this workflow; to switch surface, call tacit_gm_reset first.`;
36
+ }
37
+ export class WorkflowGate {
38
+ maxPrincipals;
39
+ /**
40
+ * Safety valve (sec audit): cap distinct principals so the states Map cannot grow
41
+ * unboundedly. A slot requires a valid credential to create, but unbounded is still
42
+ * a leak. FIFO-evicts (Map insertion order) past the cap; constructor-injectable
43
+ * for tests. Process restart clears everything regardless.
44
+ */
45
+ constructor(maxPrincipals = 10_000) {
46
+ this.maxPrincipals = maxPrincipals;
47
+ }
48
+ states = new Map();
49
+ keyOf(principal) {
50
+ return principal ?? '__stdio__';
51
+ }
52
+ stateOf(principal) {
53
+ const key = this.keyOf(principal);
54
+ let state = this.states.get(key);
55
+ if (!state) {
56
+ while (this.states.size >= this.maxPrincipals) {
57
+ const oldest = this.states.keys().next().value;
58
+ if (oldest === undefined)
59
+ break;
60
+ this.states.delete(oldest);
61
+ }
62
+ state = {
63
+ active: false,
64
+ artifactId: null,
65
+ catalogId: null,
66
+ crossReference: false,
67
+ placementsRemaining: 0,
68
+ callLog: new Map(),
69
+ fastTrackValidated: false,
70
+ lastPlacementKey: null,
71
+ };
72
+ this.states.set(key, state);
73
+ }
74
+ return state;
75
+ }
76
+ /** Record a shared list-tool call. Counting is per tool; startWorkflow clears the log. */
77
+ recordCall(principal, toolName) {
78
+ const state = this.stateOf(principal);
79
+ state.callLog.set(toolName, (state.callLog.get(toolName) ?? 0) + 1);
80
+ }
81
+ /** `tacit_gm_ingest` succeeded — arm the workflow, superseding any prior one. */
82
+ startWorkflow(principal, opts) {
83
+ const state = this.stateOf(principal);
84
+ state.active = true;
85
+ state.artifactId = opts.artifactId;
86
+ state.catalogId = opts.catalogId;
87
+ state.crossReference = opts.crossReference;
88
+ state.placementsRemaining = opts.crossReference ? 2 : 1;
89
+ state.callLog = new Map();
90
+ state.fastTrackValidated = false;
91
+ state.lastPlacementKey = null;
92
+ }
93
+ /** Guidance-attach predicate (Layer 2): true from ingest until the final placement completes. */
94
+ isGuidanceActive(principal) {
95
+ const state = this.states.get(this.keyOf(principal));
96
+ return state?.active === true;
97
+ }
98
+ /** Read-only copy of the workflow state, or null when none exists. */
99
+ getWorkflow(principal) {
100
+ const state = this.states.get(this.keyOf(principal));
101
+ if (!state)
102
+ return null;
103
+ return {
104
+ active: state.active,
105
+ artifactId: state.artifactId,
106
+ catalogId: state.catalogId,
107
+ crossReference: state.crossReference,
108
+ placementsRemaining: state.placementsRemaining,
109
+ };
110
+ }
111
+ /**
112
+ * Pyramid gate for `tacit_gm_approve`. Applied whenever an approve is attempted:
113
+ * the drill-down must have happened (call log since last ingest, or a validated
114
+ * fast-track). Re-approving after a completed placement is allowed while the log
115
+ * still satisfies the prerequisites (idempotent retries), but `tacit_gm_reset`
116
+ * or a new ingest re-arms the requirement.
117
+ */
118
+ checkPyramidApprove(principal) {
119
+ const state = this.stateOf(principal);
120
+ if (state.fastTrackValidated)
121
+ return { allowed: true, missing: [] };
122
+ const missing = PYRAMID_PREREQ_TOOLS.filter((t) => !state.callLog.has(t));
123
+ if (missing.length === 0)
124
+ return { allowed: true, missing: [] };
125
+ const parts = [
126
+ 'tacit_gm_approve rejected: the pyramid drill-down is incomplete.',
127
+ `Missing: ${missing.join(', ')}.`,
128
+ 'Call every list tool, propose the specific location, and wait for the user to approve it before placing.',
129
+ ];
130
+ if (state.callLog.has(KB_PREREQ_TOOL)) {
131
+ parts.push(staleSurfaceHint('KB'));
132
+ }
133
+ if (!state.active && state.artifactId === null) {
134
+ parts.push('No GM workflow is active — start with tacit_gm_ingest (lake-first).');
135
+ }
136
+ return { allowed: false, missing: [...missing], message: parts.join(' ') };
137
+ }
138
+ /**
139
+ * KB gate for `tacit_kb_promote_from_artifact` (and the catalog variant, which
140
+ * resolves to the same artifact). Gated ONLY while a GM workflow is active AND
141
+ * artifactId matches the workflow's artifact; a different artifact or a standalone
142
+ * promotion (SOP-03) passes through ungated and does NOT complete the workflow.
143
+ *
144
+ * Restart asymmetry (ADR-202): a process restart mid-KB-workflow silently downgrades
145
+ * to this ungated path (fail-open), while checkPyramidApprove re-requires the
146
+ * drill-down (fail-closed). The gate is workflow hygiene, not a security boundary —
147
+ * backend authorization (workspace scoping, capabilities) is unaffected either way.
148
+ */
149
+ checkKbPromote(principal, artifactId) {
150
+ const state = this.states.get(this.keyOf(principal));
151
+ if (!state?.active || state.artifactId !== artifactId) {
152
+ return { allowed: true, missing: [] };
153
+ }
154
+ if (state.callLog.has(KB_PREREQ_TOOL))
155
+ return { allowed: true, missing: [] };
156
+ const parts = [
157
+ 'tacit_kb_promote_from_artifact rejected: this GM workflow has not listed KB collections.',
158
+ `Missing: ${KB_PREREQ_TOOL}.`,
159
+ 'List the collections, propose the specific one, and wait for the user to approve it before promoting.',
160
+ ];
161
+ if (PYRAMID_PREREQ_TOOLS.some((t) => state.callLog.has(t))) {
162
+ parts.push(staleSurfaceHint('pyramid'));
163
+ }
164
+ return { allowed: false, missing: [KB_PREREQ_TOOL], message: parts.join(' ') };
165
+ }
166
+ /**
167
+ * Variation C fast-track: the handler validated target_path server-side against the
168
+ * same endpoints the list tools wrap. Satisfies the drill-down prerequisite for this
169
+ * cycle only; cleared by ingest supersession and by reset.
170
+ */
171
+ markFastTrackValidated(principal) {
172
+ this.stateOf(principal).fastTrackValidated = true;
173
+ }
174
+ /**
175
+ * A final placement succeeded — `tacit_gm_approve` (pyramid) or a promote of the
176
+ * workflow's own artifact (KB). With cross_reference set the workflow stays active
177
+ * for the second cycle; otherwise it deactivates and shared-list guidance stops.
178
+ *
179
+ * `placementKey` makes completion idempotent: the backend is idempotent, so an
180
+ * identical retry of an already-counted placement (same catalog+targets, or same
181
+ * artifact+collection) must not consume a second budget slot — in a cross_reference
182
+ * workflow a double-decrement would deactivate mid-flow and leave the second
183
+ * surface ungated (and able to land PUBLISHED). A DIFFERENT placement still counts.
184
+ */
185
+ completePlacement(principal, placementKey) {
186
+ const state = this.states.get(this.keyOf(principal));
187
+ if (!state?.active)
188
+ return;
189
+ if (state.lastPlacementKey === placementKey)
190
+ return; // idempotent retry — already counted
191
+ state.lastPlacementKey = placementKey;
192
+ state.placementsRemaining = Math.max(0, state.placementsRemaining - 1);
193
+ // The fast-track satisfies the drill-down for THIS cycle only (Variation C).
194
+ state.fastTrackValidated = false;
195
+ if (state.placementsRemaining === 0) {
196
+ state.active = false;
197
+ }
198
+ }
199
+ /**
200
+ * Variation D reset: clear the call log, rearm ACTIVE whether or not a placement had
201
+ * completed, keep the workflow's artifact/catalog. The next surface starts its own
202
+ * drill-down from scratch (call log is empty; fast-track is invalidated).
203
+ */
204
+ resetWorkflow(principal) {
205
+ const state = this.stateOf(principal);
206
+ state.active = state.artifactId !== null;
207
+ state.placementsRemaining = state.active ? (state.crossReference ? 2 : 1) : 0;
208
+ state.callLog = new Map();
209
+ state.fastTrackValidated = false;
210
+ state.lastPlacementKey = null;
211
+ return {
212
+ active: state.active,
213
+ artifactId: state.artifactId,
214
+ catalogId: state.catalogId,
215
+ crossReference: state.crossReference,
216
+ placementsRemaining: state.placementsRemaining,
217
+ };
218
+ }
219
+ /** Full teardown for the principal (tests; production teardown is process exit). */
220
+ clear(principal) {
221
+ this.states.delete(this.keyOf(principal));
222
+ }
223
+ }
224
+ // ─── Layer 2: workflow-scoped NEXT_STEP guidance (attached ONLY while active) ──
225
+ /**
226
+ * Guidance appended to shared list-tool results while a GM workflow is active.
227
+ * Never attached when no workflow is active (Gap G2: COO audits and read-only
228
+ * browses must not see GM placement instructions).
229
+ */
230
+ export const GM_LIST_TOOL_NEXT_STEP = {
231
+ tacit_pyramid_list_portfolios: 'NEXT STEP (GM workflow): portfolios loaded. Continue the mandatory drill-down — ' +
232
+ 'list value streams next, then the programs of the chosen portfolio, then its dossiers. ' +
233
+ 'Do not propose placement before you reach a specific dossier.',
234
+ tacit_pyramid_list_value_streams: 'NEXT STEP (GM workflow): value streams loaded. Identify the best-fit value stream, ' +
235
+ 'then list the programs of the chosen portfolio.',
236
+ tacit_pyramid_list_programs: 'NEXT STEP (GM workflow): programs loaded. Pick the best-fit program, then list its ' +
237
+ 'dossiers — pyramid placement needs a specific dossier.',
238
+ tacit_pyramid_list_dossiers: 'NEXT STEP (GM workflow): dossiers loaded. Propose the specific ' +
239
+ 'portfolio → value stream → program → dossier location to the user and WAIT for their ' +
240
+ 'approval before calling tacit_gm_approve.',
241
+ tacit_kb_list_collections: 'NEXT STEP (GM workflow): collections loaded. Propose the specific collection to the ' +
242
+ 'user and WAIT for their approval. After approval, call tacit_kb_promote_from_artifact ' +
243
+ 'with the workflow artifact_id, the collection UUID, and status "DRAFT" — the article ' +
244
+ 'lands as a draft the user can publish anytime.',
245
+ };
246
+ /** Appended to approve results when cross_reference is set and a second cycle remains. */
247
+ export const GM_APPROVE_NEXT_STEP = 'NEXT STEP (GM workflow): first surface placed. cross_reference is set — run the second ' +
248
+ 'placement cycle for the other surface: drill down (tacit_kb_list_collections for KB, or the ' +
249
+ 'four pyramid list tools for pyramid), propose the specific location, and wait for approval ' +
250
+ 'before placing. No tacit_gm_reset is needed between cycles.';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tacitai/mcp-server",
3
- "version": "0.6.23",
3
+ "version": "0.6.25",
4
4
  "description": "stdio MCP server wrapping Tacit /api/v1 REST/SSE API",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {