@3ngram/server 1.2.7 → 1.4.1
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/mcp/completions.d.ts +13 -0
- package/dist/mcp/completions.js +67 -0
- package/dist/mcp/completions.js.map +1 -0
- package/dist/mcp/prompts.d.ts +4 -3
- package/dist/mcp/prompts.js +34 -16
- package/dist/mcp/prompts.js.map +1 -1
- package/dist/mcp/resources.d.ts +43 -0
- package/dist/mcp/resources.js +156 -0
- package/dist/mcp/resources.js.map +1 -0
- package/dist/mcp/server.d.ts +21 -4
- package/dist/mcp/server.js +58 -5
- package/dist/mcp/server.js.map +1 -1
- package/dist/mcp/tool-annotations.d.ts +11 -0
- package/dist/mcp/tool-annotations.js +15 -0
- package/dist/mcp/tool-annotations.js.map +1 -0
- package/dist/mcp/tools-admin.js +91 -18
- package/dist/mcp/tools-admin.js.map +1 -1
- package/dist/mcp/tools-inspect.js +8 -1
- package/dist/mcp/tools-inspect.js.map +1 -1
- package/dist/mcp/tools-orient.js +9 -1
- package/dist/mcp/tools-orient.js.map +1 -1
- package/dist/mcp/tools-search.js +192 -84
- package/dist/mcp/tools-search.js.map +1 -1
- package/dist/mcp/tools.d.ts +27 -2
- package/dist/mcp/tools.js +104 -14
- package/dist/mcp/tools.js.map +1 -1
- package/dist/middleware/mcp-header-observability.js +23 -0
- package/dist/middleware/mcp-header-observability.js.map +1 -1
- package/dist/middleware/mcp-origin.d.ts +14 -0
- package/dist/middleware/mcp-origin.js +65 -0
- package/dist/middleware/mcp-origin.js.map +1 -0
- package/dist/rest/route-helpers.d.ts +6 -1
- package/dist/rest/route-helpers.js +9 -0
- package/dist/rest/route-helpers.js.map +1 -1
- package/dist/rest/router.js +64 -13
- package/dist/rest/router.js.map +1 -1
- package/dist/rest/search-router.js +22 -8
- package/dist/rest/search-router.js.map +1 -1
- package/dist/routes/mcp.js +15 -0
- package/dist/routes/mcp.js.map +1 -1
- package/package.json +5 -5
package/dist/mcp/tools-admin.js
CHANGED
|
@@ -27,12 +27,18 @@
|
|
|
27
27
|
// action-discriminated unions are registered without a permissive raw-shape
|
|
28
28
|
// bridge. The exact per-action contract is enforced at the transport boundary.
|
|
29
29
|
import { log, mcpToolErrors } from '@3ngram/config';
|
|
30
|
-
import {
|
|
30
|
+
import { acceptProposalAnyKind, createScope, deleteScope, describeEnvironment, listAllProposals, listScopes, rejectProposalAnyKind, renameScope, setRetrievalDefault, setScopeAliases, } from '@3ngram/core';
|
|
31
31
|
import { MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE } from '@3ngram/core/auth';
|
|
32
|
-
import { configureScopeInputV2Schema, configureScopeOutputV2Schema, describeEnvironmentInputSchema, describeEnvironmentOutputV2Schema, reviewProposalsInputSchema,
|
|
32
|
+
import { configureScopeInputV2Schema, configureScopeOutputV2Schema, describeEnvironmentInputSchema, describeEnvironmentOutputV2Schema, reviewProposalsInputSchema, reviewProposalsOutputV2Schema, } from '@3ngram/schema';
|
|
33
33
|
import { parseOutput } from '../output-validation.js';
|
|
34
34
|
import { SERVER_VERSION } from '../version.js';
|
|
35
|
-
|
|
35
|
+
import { READ_ONLY_ANNOTATIONS } from './tool-annotations.js';
|
|
36
|
+
/**
|
|
37
|
+
* Wrap a structured payload as a tool success result (text mirror + structured).
|
|
38
|
+
* The mirror is deliberate and load-bearing: see the `ok` doc comment in
|
|
39
|
+
* tools.ts for why it cannot be dropped and what the >2x duplication costs
|
|
40
|
+
* (issue #75).
|
|
41
|
+
*/
|
|
36
42
|
function ok(structured) {
|
|
37
43
|
return {
|
|
38
44
|
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
@@ -168,11 +174,21 @@ async function runReviewProposals(input, ctx) {
|
|
|
168
174
|
// access is asserted BEFORE the db op (self-host allowAllAccess allows all).
|
|
169
175
|
if (ctx.access)
|
|
170
176
|
await ctx.access.assertRead(ctx.userId);
|
|
171
|
-
const proposals = await
|
|
172
|
-
|
|
177
|
+
const { proposals, factProposals } = await listAllProposals(ctx.userId, {
|
|
178
|
+
status: input.status,
|
|
179
|
+
limit: input.limit,
|
|
180
|
+
});
|
|
181
|
+
return ok(parseOutput('review_proposals', reviewProposalsOutputV2Schema, {
|
|
173
182
|
action: 'list',
|
|
174
183
|
proposals: proposals.map(toProposalOutput),
|
|
184
|
+
// `count` stays the EDGE count: it is the shipped field, and a tenant
|
|
185
|
+
// with no fact proposals must see the identical response it always has.
|
|
175
186
|
count: proposals.length,
|
|
187
|
+
// Key OMITTED when there are none, so an edge-only tenant's response is
|
|
188
|
+
// byte-identical to V1 rather than growing an empty array.
|
|
189
|
+
...(factProposals.length > 0
|
|
190
|
+
? { factProposals: factProposals.map(toFactProposalOutput) }
|
|
191
|
+
: {}),
|
|
176
192
|
}));
|
|
177
193
|
}
|
|
178
194
|
const denied = requireScope('review_proposals', ctx, MEMORY_WRITE_SCOPE);
|
|
@@ -183,18 +199,51 @@ async function runReviewProposals(input, ctx) {
|
|
|
183
199
|
// allowAllAccess allows all).
|
|
184
200
|
if (ctx.access)
|
|
185
201
|
await ctx.access.assertWrite(ctx.userId);
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
202
|
+
// The id alone identifies the kind (uuidv7, disjoint across both tables), so
|
|
203
|
+
// the shipped single-id input is unchanged; core probes edge then fact.
|
|
204
|
+
const decided = input.action === 'accept'
|
|
205
|
+
? await acceptProposalAnyKind(ctx.userId, input.proposalId, 'user_mcp')
|
|
206
|
+
: await rejectProposalAnyKind(ctx.userId, input.proposalId);
|
|
207
|
+
return ok(parseOutput('review_proposals', reviewProposalsOutputV2Schema, toDecisionOutput(decided)));
|
|
208
|
+
}
|
|
209
|
+
/** Shape a core fact-proposal record for the structured output (Dates -> ISO). */
|
|
210
|
+
function toFactProposalOutput(p) {
|
|
211
|
+
return {
|
|
212
|
+
id: p.id,
|
|
213
|
+
memoryId: p.memoryId,
|
|
214
|
+
subject: p.subject,
|
|
215
|
+
predicate: p.predicate,
|
|
216
|
+
value: p.value,
|
|
217
|
+
memoryType: p.memoryType,
|
|
218
|
+
confidence: p.confidence,
|
|
219
|
+
validFrom: p.validFrom === null ? null : p.validFrom.toISOString(),
|
|
220
|
+
validTo: p.validTo === null ? null : p.validTo.toISOString(),
|
|
221
|
+
rationale: p.rationale,
|
|
222
|
+
status: p.status,
|
|
223
|
+
decidedAt: p.decidedAt === null ? null : p.decidedAt.toISOString(),
|
|
224
|
+
createdAt: p.createdAt.toISOString(),
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Map a decided proposal to its output variant. The two kinds get DISTINCT
|
|
229
|
+
* discriminator literals so a client matching on `applied`/`rejected` keeps
|
|
230
|
+
* receiving the edge payload it was written against.
|
|
231
|
+
*/
|
|
232
|
+
function toDecisionOutput(decided) {
|
|
233
|
+
switch (decided.kind) {
|
|
234
|
+
case 'edge':
|
|
235
|
+
return { action: 'rejected', proposal: toProposalOutput(decided.proposal) };
|
|
236
|
+
case 'edge_applied':
|
|
237
|
+
return { action: 'applied', proposal: toProposalOutput(decided.proposal) };
|
|
238
|
+
case 'fact':
|
|
239
|
+
return { action: 'rejected_fact', proposal: toFactProposalOutput(decided.proposal) };
|
|
240
|
+
case 'fact_applied':
|
|
241
|
+
return {
|
|
242
|
+
action: 'applied_fact',
|
|
243
|
+
proposal: toFactProposalOutput(decided.proposal),
|
|
244
|
+
factId: decided.factId,
|
|
245
|
+
};
|
|
192
246
|
}
|
|
193
|
-
const proposal = await rejectProposal(ctx.userId, input.proposalId);
|
|
194
|
-
return ok(parseOutput('review_proposals', reviewProposalsOutputSchema, {
|
|
195
|
-
action: 'rejected',
|
|
196
|
-
proposal: toProposalOutput(proposal),
|
|
197
|
-
}));
|
|
198
247
|
}
|
|
199
248
|
/**
|
|
200
249
|
* Build the three admin tool definitions. `toolNames` is injected by the
|
|
@@ -213,6 +262,18 @@ export function createAdminTools(toolNames) {
|
|
|
213
262
|
description: 'Manage your memory scopes: list, create, rename, set aliases, or delete (registry only — existing memories keep their scope). set_retrieval_default binds your READS to a scope: mode "default" narrows unscoped search/briefing/handoff calls to the given scope (results report appliedScope), "require" rejects unscoped reads until a scope is passed, "off" restores unrestricted reads (scope must be null for require/off). Mutating actions require the write scope.',
|
|
214
263
|
inputSchema: configureScopeInputV2Schema,
|
|
215
264
|
outputSchema: configureScopeOutputV2Schema,
|
|
265
|
+
// Per-action tool, so the hints describe the WORST action it can take —
|
|
266
|
+
// that is how a client uses them (deciding whether to prompt). `delete`
|
|
267
|
+
// removes a scope registry entry, hence destructiveHint: true. It does NOT
|
|
268
|
+
// touch memories (they keep their scope string), so hard rule 1 still
|
|
269
|
+
// holds; the hint is about the registry, not the corpus. `create`/`rename`
|
|
270
|
+
// are not repeatable, so idempotentHint: false.
|
|
271
|
+
annotations: {
|
|
272
|
+
readOnlyHint: false,
|
|
273
|
+
destructiveHint: true,
|
|
274
|
+
idempotentHint: false,
|
|
275
|
+
openWorldHint: false,
|
|
276
|
+
},
|
|
216
277
|
},
|
|
217
278
|
async handler(args, ctx) {
|
|
218
279
|
const input = configureScopeInputV2Schema.parse(args);
|
|
@@ -227,6 +288,7 @@ export function createAdminTools(toolNames) {
|
|
|
227
288
|
description: 'Report server capabilities (tool names, count, version), your registered scopes, your active retrieval-scope policy (retrievalScopePolicy), and bounded memory/commitment counts. Exposes no secrets or configuration values.',
|
|
228
289
|
inputSchema: describeEnvironmentInputSchema,
|
|
229
290
|
outputSchema: describeEnvironmentOutputV2Schema,
|
|
291
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
230
292
|
},
|
|
231
293
|
async handler(args, ctx) {
|
|
232
294
|
describeEnvironmentInputSchema.parse(args);
|
|
@@ -261,9 +323,20 @@ export function createAdminTools(toolNames) {
|
|
|
261
323
|
requiredScope: { anyOf: [MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE] },
|
|
262
324
|
config: {
|
|
263
325
|
title: 'Review Proposals',
|
|
264
|
-
description: 'List
|
|
326
|
+
description: 'List proposals awaiting review (optionally by status), reject one, or accept one. Two kinds are reviewed the same way: consolidation proposals, where accepting materializes the proposed edge and a supersedes/updates edge also closes the predecessor; and extracted-fact proposals, where accepting writes the structured fact so `get_facts` can read it. Accept and reject take the proposal id either way. Reject and accept require the write scope.',
|
|
265
327
|
inputSchema: reviewProposalsInputSchema,
|
|
266
|
-
outputSchema:
|
|
328
|
+
outputSchema: reviewProposalsOutputV2Schema,
|
|
329
|
+
// Per-action (list is a read; reject/accept are writes), so the hints
|
|
330
|
+
// describe the write path. destructiveHint: false: accepting materializes
|
|
331
|
+
// an edge, and a supersedes/updates edge CLOSES the predecessor's validity
|
|
332
|
+
// rather than deleting it — append-and-supersede (hard rule 1). Rejecting
|
|
333
|
+
// records a rejection. Neither is repeatable, so idempotentHint: false.
|
|
334
|
+
annotations: {
|
|
335
|
+
readOnlyHint: false,
|
|
336
|
+
destructiveHint: false,
|
|
337
|
+
idempotentHint: false,
|
|
338
|
+
openWorldHint: false,
|
|
339
|
+
},
|
|
267
340
|
},
|
|
268
341
|
async handler(args, ctx) {
|
|
269
342
|
const input = reviewProposalsInputSchema.parse(args);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools-admin.js","sourceRoot":"","sources":["../../src/mcp/tools-admin.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,0DAA0D;AAC1D,6DAA6D;AAC7D,sDAAsD;AACtD,4EAA4E;AAC5E,yCAAyC;AACzC,EAAE;AACF,oEAAoE;AACpE,+EAA+E;AAC/E,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,EAAE;AACF,6DAA6D;AAC7D,gFAAgF;AAChF,kFAAkF;AAClF,iDAAiD;AACjD,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EACL,
|
|
1
|
+
{"version":3,"file":"tools-admin.js","sourceRoot":"","sources":["../../src/mcp/tools-admin.ts"],"names":[],"mappings":"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"}
|
|
@@ -27,7 +27,13 @@ import { getMemoriesByIds } from '@3ngram/core';
|
|
|
27
27
|
import { MEMORY_READ_SCOPE } from '@3ngram/core/auth';
|
|
28
28
|
import { DEFAULT_GET_CONTENT_CHARS, getMemoriesInputSchema, getMemoriesOutputSchema, MAX_GET_CONTENT_CHARS, MAX_GET_MEMORIES_IDS, MAX_GET_TOTAL_CHARS, } from '@3ngram/schema';
|
|
29
29
|
import { parseOutput } from '../output-validation.js';
|
|
30
|
-
|
|
30
|
+
import { READ_ONLY_ANNOTATIONS } from './tool-annotations.js';
|
|
31
|
+
/**
|
|
32
|
+
* Wrap a structured payload as a tool success result (text mirror + structured).
|
|
33
|
+
* The mirror is deliberate and load-bearing: see the `ok` doc comment in
|
|
34
|
+
* tools.ts for why it cannot be dropped and what the >2x duplication costs
|
|
35
|
+
* (issue #75).
|
|
36
|
+
*/
|
|
31
37
|
function ok(structured) {
|
|
32
38
|
return {
|
|
33
39
|
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
@@ -51,6 +57,7 @@ const getMemoriesTool = {
|
|
|
51
57
|
description: `Fetch the full content of memories by id — use this after search or handoff returns an item with truncated: true to read the complete body. Accepts up to ${MAX_GET_MEMORIES_IDS} ids plus an optional maxContentChars per-item bound (default ${DEFAULT_GET_CONTENT_CHARS}, max ${MAX_GET_CONTENT_CHARS}; ids × maxContentChars may not exceed ${MAX_GET_TOTAL_CHARS} per call); an item still truncated at the cap reports truncated: true with its full contentLength. Ids that do not resolve for you are listed in notFound — never an error.`,
|
|
52
58
|
inputSchema: getMemoriesInputSchema,
|
|
53
59
|
outputSchema: getMemoriesOutputSchema,
|
|
60
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
54
61
|
},
|
|
55
62
|
async handler(args, ctx) {
|
|
56
63
|
const input = getMemoriesInputSchema.parse(args);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools-inspect.js","sourceRoot":"","sources":["../../src/mcp/tools-inspect.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,oEAAoE;AACpE,mEAAmE;AACnE,EAAE;AACF,uEAAuE;AACvE,8EAA8E;AAC9E,+EAA+E;AAC/E,qEAAqE;AACrE,qGAAqG;AACrG,8EAA8E;AAC9E,qEAAqE;AACrE,yEAAyE;AACzE,qBAAqB;AACrB,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,8EAA8E;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;
|
|
1
|
+
{"version":3,"file":"tools-inspect.js","sourceRoot":"","sources":["../../src/mcp/tools-inspect.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp/tools-orient.js
CHANGED
|
@@ -27,7 +27,13 @@ import { briefing, handoff } from '@3ngram/core';
|
|
|
27
27
|
import { MEMORY_READ_SCOPE } from '@3ngram/core/auth';
|
|
28
28
|
import { briefingToolInputV3Schema, briefingToolOutputV4Schema, handoffToolInputV3Schema, handoffToolOutputV4Schema, } from '@3ngram/schema';
|
|
29
29
|
import { parseOutput } from '../output-validation.js';
|
|
30
|
-
|
|
30
|
+
import { READ_ONLY_ANNOTATIONS } from './tool-annotations.js';
|
|
31
|
+
/**
|
|
32
|
+
* Wrap a structured payload as a tool success result (text mirror + structured).
|
|
33
|
+
* The mirror is deliberate and load-bearing: see the `ok` doc comment in
|
|
34
|
+
* tools.ts for why it cannot be dropped and what the >2x duplication costs
|
|
35
|
+
* (issue #75).
|
|
36
|
+
*/
|
|
31
37
|
function ok(structured) {
|
|
32
38
|
return {
|
|
33
39
|
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
@@ -53,6 +59,7 @@ const briefingTool = {
|
|
|
53
59
|
description: 'Structured session orientation: open/overdue commitments, blockers, stale candidates, recent decisions, preferences. Requires an explicit selector (all, scope, project, or scope_project) — no unfiltered default. If a retrieval-scope policy is set (configure_scope set_retrieval_default), a kind: "all" selector may be narrowed to your default scope (the result then reports appliedScope) or rejected until you pass a scope selector. A PROJECT selector only matches memories written WITH that project; a memory written without a project (project IS NULL) never appears through the project lens. The scope_project selector narrows to one scope AND one project together; its includeUnscoped: true additionally opts NULL-project memories of that scope in (default false = strict intersection; the bare project selector is never widened). Active blockers leave this set when resolved (resolve archives the blocker memory). brief mode (default) returns counts plus top items; full returns the bounded lists. Optional sections picks a subset (un-requested sections are skipped and omitted); optional sectionLimit (1-100) tunes the per-section bound. Each section reports its exact count and hasMore when more rows exist than returned.',
|
|
54
60
|
inputSchema: briefingToolInputV3Schema,
|
|
55
61
|
outputSchema: briefingToolOutputV4Schema,
|
|
62
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
56
63
|
},
|
|
57
64
|
async handler(args, ctx) {
|
|
58
65
|
const input = briefingToolInputV3Schema.parse(args);
|
|
@@ -96,6 +103,7 @@ const handoffTool = {
|
|
|
96
103
|
description: 'Export structured context (decisions, open commitments, preferences — with content) for another agent or provider to pick up the thread. Requires an explicit selector (all, scope, project, or scope_project); the payload is bounded. If a retrieval-scope policy is set (configure_scope set_retrieval_default), a kind: "all" selector may be narrowed to your default scope (the result then reports appliedScope) or rejected until you pass a scope selector. A scope_project selector narrows to one scope AND one project; its includeUnscoped: true additionally exports NULL-project memories of that scope (default false). Optional sectionLimit (1-100) tunes the per-section bound. The envelope reports exact per-section counts, and truncated flags a section whose list is incomplete. Item content is a bounded excerpt — when a line reports truncated: true, call get_memories with its id to read the full content.',
|
|
97
104
|
inputSchema: handoffToolInputV3Schema,
|
|
98
105
|
outputSchema: handoffToolOutputV4Schema,
|
|
106
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
99
107
|
},
|
|
100
108
|
async handler(args, ctx) {
|
|
101
109
|
const input = handoffToolInputV3Schema.parse(args);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools-orient.js","sourceRoot":"","sources":["../../src/mcp/tools-orient.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,wCAAwC;AACxC,gFAAgF;AAChF,kEAAkE;AAClE,sDAAsD;AACtD,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,4EAA4E;AAC5E,mEAAmE;AACnE,EAAE;AACF,kGAAkG;AAClG,kFAAkF;AAClF,0EAA0E;AAC1E,6EAA6E;AAC7E,oBAAoB;AACpB,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,+DAA+D;AAC/D,kFAAkF;AAClF,mFAAmF;AACnF,gFAAgF;AAChF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;
|
|
1
|
+
{"version":3,"file":"tools-orient.js","sourceRoot":"","sources":["../../src/mcp/tools-orient.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp/tools-search.js
CHANGED
|
@@ -8,12 +8,18 @@
|
|
|
8
8
|
// (packages/schema Zod), call the COMPLETE core service (which runs withTenant
|
|
9
9
|
// internally), shape the structured result. A read -> requiredScope
|
|
10
10
|
// memory:read; runTool enforces the scope BEFORE the handler runs.
|
|
11
|
-
import { applyPolicyToScopeFilter, searchDashboardPage } from '@3ngram/core';
|
|
11
|
+
import { applyPolicyToScopeFilter, searchChronological, searchDashboardPage, } from '@3ngram/core';
|
|
12
12
|
import { MEMORY_READ_SCOPE } from '@3ngram/core/auth';
|
|
13
|
-
import {
|
|
13
|
+
import { searchQueryV4Schema, searchToolOutputV3Schema, } from '@3ngram/schema';
|
|
14
14
|
import { decodeSearchCursor, encodeCursor, searchFingerprint } from '../cursor.js';
|
|
15
15
|
import { parseOutput } from '../output-validation.js';
|
|
16
|
-
|
|
16
|
+
import { READ_ONLY_ANNOTATIONS } from './tool-annotations.js';
|
|
17
|
+
/**
|
|
18
|
+
* Wrap a structured payload as a tool success result (text mirror + structured).
|
|
19
|
+
* The mirror is deliberate and load-bearing: see the `ok` doc comment in
|
|
20
|
+
* tools.ts for why it cannot be dropped and what the >2x duplication costs
|
|
21
|
+
* (issue #75).
|
|
22
|
+
*/
|
|
17
23
|
function ok(structured) {
|
|
18
24
|
return {
|
|
19
25
|
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
@@ -66,7 +72,13 @@ function toFilters(input) {
|
|
|
66
72
|
* the interesting ids with get_memories.
|
|
67
73
|
*/
|
|
68
74
|
function projectHit(hit, projection) {
|
|
69
|
-
const compact = {
|
|
75
|
+
const compact = {
|
|
76
|
+
id: hit.id,
|
|
77
|
+
memoryType: hit.memoryType,
|
|
78
|
+
topic: hit.topic,
|
|
79
|
+
score: hit.score,
|
|
80
|
+
superseded: hit.superseded,
|
|
81
|
+
};
|
|
70
82
|
if (projection === 'compact')
|
|
71
83
|
return compact;
|
|
72
84
|
return {
|
|
@@ -77,50 +89,186 @@ function projectHit(hit, projection) {
|
|
|
77
89
|
};
|
|
78
90
|
}
|
|
79
91
|
/**
|
|
80
|
-
* search
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
* `cursor` (opaque frozen-ordering token) + `projection` (full/compact). Each
|
|
88
|
-
* filter NARROWS the candidate set BEFORE fusion; none alters the fusion
|
|
89
|
-
* weights or the supersession ranking (docs/concepts/memory-model.mdx
|
|
90
|
-
* live-first stays the default). The tool registers the FULL `.strict()`
|
|
91
|
-
* object (not its raw shape), so the SDK parses inbound args strictly at the
|
|
92
|
-
* transport boundary and an UNKNOWN key is REJECTED there — never silently
|
|
93
|
-
* dropped.
|
|
94
|
-
*
|
|
95
|
-
* PAGINATION routes through the SAME frozen-ordering machinery the dashboard
|
|
96
|
-
* uses (core searchDashboardPage + the shared ../cursor.js codec): page 1 ranks
|
|
97
|
-
* the bounded candidate pool once and freezes the ordering into `nextCursor`;
|
|
98
|
-
* a continuation pages BY POSITION within it (fetchHitsByIds), immune to
|
|
99
|
-
* duplicate/skip under mid-walk corpus drift. Page-1 ranking is identical to
|
|
100
|
-
* the pre-cursor path (returnFullPool ranks the same pool), so the eval floors
|
|
101
|
-
* are untouched. A garbled cursor throws a ZodError -> runTool's ladder labels
|
|
102
|
-
* it invalid input (never a 500); a stale pre-v2 cursor decodes to undefined
|
|
103
|
-
* and restarts at page 1. The cursor is BOUND to the query+filters that issued
|
|
92
|
+
* Ranked (relevance-order) search: the shipped fused-retrieval path, byte-
|
|
93
|
+
* compatible with the pre-V4 tool behavior. PAGINATION routes through the
|
|
94
|
+
* SAME frozen-ordering machinery the dashboard uses (core searchDashboardPage
|
|
95
|
+
* + the shared ../cursor.js codec): page 1 ranks the bounded candidate pool
|
|
96
|
+
* once and freezes the ordering into `nextCursor`; a continuation pages BY
|
|
97
|
+
* POSITION within it (fetchHitsByIds), immune to duplicate/skip under
|
|
98
|
+
* mid-walk corpus drift. The cursor is BOUND to the query+filters that issued
|
|
104
99
|
* it (the shared codec's fingerprint, verified in decodeSearchCursor): a
|
|
105
|
-
* continuation under a CHANGED query/filters is a typed
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
100
|
+
* continuation under a CHANGED query/filters is a typed CursorQueryMismatchError
|
|
101
|
+
* -> invalid_input, never a silent re-page of the old search's frozen
|
|
102
|
+
* ordering. Fingerprint-less cursors minted before the binding stay valid
|
|
103
|
+
* (verify-when-present); the fingerprint computation here is BYTE-IDENTICAL
|
|
104
|
+
* to the pre-V4 tool (no `order` folded in), so a cursor minted before
|
|
105
|
+
* chronological order existed keeps verifying.
|
|
106
|
+
*/
|
|
107
|
+
async function handleRelevanceSearch(input, filters, policyScope, retrievalPolicy, ctx) {
|
|
108
|
+
if (ctx.gateway === undefined) {
|
|
109
|
+
return fail('embedding gateway not configured');
|
|
110
|
+
}
|
|
111
|
+
const fingerprint = searchFingerprint(input.query, filters, policyScope.scope, policyScope.appliedScope !== null);
|
|
112
|
+
const decodedRaw = input.cursor === undefined ? undefined : decodeSearchCursor(input.cursor, fingerprint);
|
|
113
|
+
// Relevance (ranked) search only ever mints/consumes the v2 frozen-ordering
|
|
114
|
+
// cursor — the v3 chronological keyset cursor belongs to order:
|
|
115
|
+
// 'chronological' only. A well-formed v3 token is NEVER reachable here at
|
|
116
|
+
// all: cursorPayloadV3Schema requires `fp` (packages/schema/src/cursor.ts —
|
|
117
|
+
// v3 has no legacy fp-less tokens to carve out, unlike v2), so
|
|
118
|
+
// decodeSearchCursor above has ALREADY thrown a typed mismatch for any real
|
|
119
|
+
// v3 token (its fingerprint folds in `order: 'chronological'`, which a
|
|
120
|
+
// relevance fingerprint never does, so the hashes can never coincidentally
|
|
121
|
+
// collide). This shape guard is therefore UNREACHABLE for any cursor that
|
|
122
|
+
// successfully decodes — it stays purely as defense in depth (the same
|
|
123
|
+
// two-layer posture this codebase applies elsewhere) against a malformed or
|
|
124
|
+
// hand-crafted v3-shaped payload reaching this line: without it, `.ids`/
|
|
125
|
+
// `.scores` below would read as `undefined` off the wrong shape instead of
|
|
126
|
+
// restarting cleanly at page 1.
|
|
127
|
+
const decoded = decodedRaw !== undefined && decodedRaw.v === 2 ? decodedRaw : undefined;
|
|
128
|
+
const frozen = decoded === undefined
|
|
129
|
+
? undefined
|
|
130
|
+
: {
|
|
131
|
+
ids: decoded.ids,
|
|
132
|
+
scores: decoded.scores,
|
|
133
|
+
off: decoded.off,
|
|
134
|
+
...(decoded.policyScope === undefined ? {} : { policyScope: decoded.policyScope }),
|
|
135
|
+
};
|
|
136
|
+
const page = await searchDashboardPage(ctx.userId, input.query, { gateway: ctx.gateway }, defined({
|
|
137
|
+
limit: input.limit,
|
|
138
|
+
filters,
|
|
139
|
+
frozen,
|
|
140
|
+
budget: ctx.budget,
|
|
141
|
+
retrievalPolicy,
|
|
142
|
+
}));
|
|
143
|
+
// Emit a cursor ONLY when a further page exists (searchToolOutputV2Schema
|
|
144
|
+
// ENFORCES nextCursor <-> hasMore, so a drifting pair can never ship).
|
|
145
|
+
const nextCursor = page.hasMore
|
|
146
|
+
? encodeCursor({
|
|
147
|
+
v: 2,
|
|
148
|
+
ids: page.frozen.ids,
|
|
149
|
+
scores: page.frozen.scores,
|
|
150
|
+
off: page.nextOffset,
|
|
151
|
+
fp: fingerprint,
|
|
152
|
+
policyScope: page.frozen.policyScope,
|
|
153
|
+
})
|
|
154
|
+
: undefined;
|
|
155
|
+
const output = parseOutput('search', searchToolOutputV3Schema, defined({
|
|
156
|
+
hits: page.hits.map((hit) => projectHit(hit, input.projection)),
|
|
157
|
+
count: page.hits.length,
|
|
158
|
+
hasMore: page.hasMore,
|
|
159
|
+
nextCursor,
|
|
160
|
+
// Present exactly when the policy narrowed this call (never silent);
|
|
161
|
+
// omitted otherwise so an off/no-policy response stays byte-identical.
|
|
162
|
+
appliedScope: page.appliedScope ?? undefined,
|
|
163
|
+
}));
|
|
164
|
+
return ok(output);
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Chronological (list-mode) search: an exhaustive, unranked recorded_at DESC
|
|
168
|
+
* enumeration (packages/core/src/read/search-list.ts). Skips the embedding
|
|
169
|
+
* gateway ENTIRELY — no gateway call, no query-embed cost row — and skips the
|
|
170
|
+
* abstention path by construction: nothing here ever reads `vectorScore`
|
|
171
|
+
* (that field only exists on the ranked path's hits), so there is no cosine
|
|
172
|
+
* signal to abstain on.
|
|
173
|
+
*
|
|
174
|
+
* The v3 keyset cursor (recordedAt, id) is DRIFT-FREE, unlike the ranked
|
|
175
|
+
* path's frozen-pool cursor, so it needs no frozen candidate set — tiny by
|
|
176
|
+
* comparison. `recordedAt` is OPAQUE full-precision text, never a JS `Date`
|
|
177
|
+
* (packages/db/src/search-list.ts's ChronologicalCursor doc: a `Date` cannot
|
|
178
|
+
* represent Postgres's microsecond resolution, and truncating it can silently
|
|
179
|
+
* strand rows that tie on a same-transaction timestamp). Its fingerprint
|
|
180
|
+
* folds `order: 'chronological'` into the hashed filter set, which the ranked
|
|
181
|
+
* path's fingerprint (byte-identical to pre-V4) does NOT do — so a v2
|
|
182
|
+
* (ranked) cursor carrying `fp`, replayed here, is REJECTED as a typed
|
|
183
|
+
* CursorQueryMismatchError (invalid_input) by decodeSearchCursor, never
|
|
184
|
+
* silently misread. Only a fingerprint-LESS LEGACY v2 token (pre-binding,
|
|
185
|
+
* before `fp` existed) skips that check and reaches the shape guard below —
|
|
186
|
+
* v3 has no fp-less analogue, since `fp` is REQUIRED on cursorPayloadV3Schema
|
|
187
|
+
* (packages/schema/src/cursor.ts: v3 is introduced in this same change, so no
|
|
188
|
+
* legacy fp-less v3 token has ever legitimately existed).
|
|
189
|
+
*/
|
|
190
|
+
async function handleChronologicalSearch(input, filters, policyScope, retrievalPolicy, ctx) {
|
|
191
|
+
const fingerprint = searchFingerprint(
|
|
192
|
+
// PINNED EMPTY, not `input.query ?? ''`: the V4 chronological variant
|
|
193
|
+
// REJECTS a present `query` at the schema boundary, so nothing can reach
|
|
194
|
+
// here with one. Reading the field would imply a query leg this ordering
|
|
195
|
+
// does not have and would let a fingerprint vary on an input that cannot
|
|
196
|
+
// exist — the constant keeps the hashed identity exactly the filter set.
|
|
197
|
+
'', { ...filters, order: 'chronological' }, policyScope.scope, policyScope.appliedScope !== null);
|
|
198
|
+
const decodedRaw = input.cursor === undefined ? undefined : decodeSearchCursor(input.cursor, fingerprint);
|
|
199
|
+
// UNLIKE the relevance handler's symmetric guard, this shape check IS
|
|
200
|
+
// reachable in a legitimate case: a fingerprint-LESS LEGACY v2 token
|
|
201
|
+
// (minted before `fp` existed) skips decodeSearchCursor's mismatch check
|
|
202
|
+
// entirely (verify-when-present) and reaches here with `v: 2` — `decoded`
|
|
203
|
+
// correctly resolves to undefined (restart at page 1) rather than
|
|
204
|
+
// misreading a v2 payload's `ids`/`scores` shape as `recordedAt`/`id`. A
|
|
205
|
+
// well-formed v3 token can never reach this branch already-mismatched: `fp`
|
|
206
|
+
// is required on it (packages/schema/src/cursor.ts), so any real v3 token
|
|
207
|
+
// either matches (falls through, `v: 3`) or was already rejected above.
|
|
208
|
+
const decoded = decodedRaw !== undefined && decodedRaw.v === 3 ? decodedRaw : undefined;
|
|
209
|
+
// recordedAt is OPAQUE full-precision text end to end — NEVER parsed
|
|
210
|
+
// through `new Date()` here, which would floor it to millisecond precision
|
|
211
|
+
// and could silently re-admit rows a same-transaction batch insert already
|
|
212
|
+
// returned (see db/search-list.ts's ChronologicalCursor doc for the full
|
|
213
|
+
// mechanism this must not reintroduce).
|
|
214
|
+
const cursor = decoded === undefined ? undefined : { recordedAt: decoded.recordedAt, id: decoded.id };
|
|
215
|
+
const page = await searchChronological(ctx.userId, defined({
|
|
216
|
+
limit: input.limit,
|
|
217
|
+
filters,
|
|
218
|
+
cursor,
|
|
219
|
+
retrievalPolicy,
|
|
220
|
+
}));
|
|
221
|
+
const nextCursor = page.hasMore && page.nextCursor !== undefined
|
|
222
|
+
? encodeCursor({
|
|
223
|
+
v: 3,
|
|
224
|
+
recordedAt: page.nextCursor.recordedAt,
|
|
225
|
+
id: page.nextCursor.id,
|
|
226
|
+
fp: fingerprint,
|
|
227
|
+
})
|
|
228
|
+
: undefined;
|
|
229
|
+
const output = parseOutput('search', searchToolOutputV3Schema, defined({
|
|
230
|
+
hits: page.hits.map((hit) => projectHit(hit, input.projection)),
|
|
231
|
+
count: page.hits.length,
|
|
232
|
+
hasMore: page.hasMore,
|
|
233
|
+
nextCursor,
|
|
234
|
+
appliedScope: page.appliedScope ?? undefined,
|
|
235
|
+
}));
|
|
236
|
+
return ok(output);
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* search — unified fused retrieval (docs/concepts/mcp-design.mdx JTBD "find what I know"),
|
|
240
|
+
* plus an exhaustive chronological list mode. The input contract is the V4
|
|
241
|
+
* composition ({@link searchQueryV4Schema}, hard rule 2): query + limit, the
|
|
242
|
+
* candidate-narrowing filters (V1 memoryType/scope/project/status/asOf + V2
|
|
243
|
+
* memoryTypes[]/recordedAfter/recordedBefore), the continuation pair —
|
|
244
|
+
* `cursor` (opaque token) + `projection` (full/compact) — and `order`
|
|
245
|
+
* (relevance default | chronological). Each filter NARROWS the candidate set
|
|
246
|
+
* BEFORE fusion/ordering; none alters the fusion weights or the supersession
|
|
247
|
+
* ranking (docs/concepts/memory-model.mdx live-first stays the default). The
|
|
248
|
+
* tool registers the FULL `.strict()` object (not its raw shape), so the SDK
|
|
249
|
+
* parses inbound args strictly at the transport boundary and an UNKNOWN key
|
|
250
|
+
* is REJECTED there — never silently dropped.
|
|
251
|
+
*
|
|
252
|
+
* `order: 'relevance'` (default) requires a gateway-configured embedding
|
|
253
|
+
* source and a `query`; `order: 'chronological'` requires NEITHER — it never
|
|
254
|
+
* calls the gateway, and it REJECTS a `query` outright (this path ranks
|
|
255
|
+
* nothing, so a query could only be ignored) while requiring >=1 filter to
|
|
256
|
+
* bound the scan. The two orders mint DIFFERENT cursor shapes (see
|
|
257
|
+
* {@link handleRelevanceSearch} / {@link handleChronologicalSearch}); each
|
|
258
|
+
* rejects/restarts on the other's cursor rather than misreading it.
|
|
109
259
|
*/
|
|
110
260
|
const searchTool = {
|
|
111
261
|
name: 'search',
|
|
112
262
|
requiredScope: MEMORY_READ_SCOPE,
|
|
113
263
|
config: {
|
|
114
264
|
title: 'Search',
|
|
115
|
-
description: 'Unified semantic + keyword retrieval over your memories, supersession-aware. Accepts a query and an optional result limit, plus optional filters that narrow the candidate set BEFORE fusion (no change to ranking weights): memoryType OR memoryTypes (a list of types, mutually exclusive with memoryType), scope, project, status, asOf (bi-temporal time travel with validAt/asKnownAt), and recordedAfter/recordedBefore (an inclusive recorded-at range over the live view — not time travel). Omit a filter to leave that axis unconstrained. If a retrieval-scope policy is set (configure_scope set_retrieval_default), an unscoped search may be narrowed to your default scope (the result then reports appliedScope) or rejected until you pass a scope filter. Hit content is a bounded excerpt — when a hit reports truncated: true, call get_memories with its id to read the full content. To page: pass nextCursor back as cursor with the SAME query and
|
|
116
|
-
inputSchema:
|
|
265
|
+
description: 'Unified semantic + keyword retrieval over your memories, supersession-aware. Accepts a query and an optional result limit, plus optional filters that narrow the candidate set BEFORE fusion (no change to ranking weights): memoryType OR memoryTypes (a list of types, mutually exclusive with memoryType), scope, project, status, asOf (bi-temporal time travel with validAt/asKnownAt), and recordedAfter/recordedBefore (an inclusive recorded-at range over the live view — not time travel). Omit a filter to leave that axis unconstrained. Set order: "chronological" for an exhaustive, unranked recorded_at-descending listing instead of the fused ranking — no embedding call, no gateway required; query is RELEVANCE-ONLY and is rejected in chronological order (that mode ranks nothing, so a query could only be ignored), and chronological instead REQUIRES at least one filter to bound the scan. Default order "relevance" is the fused ranked search and still requires a query. If a retrieval-scope policy is set (configure_scope set_retrieval_default), an unscoped search may be narrowed to your default scope (the result then reports appliedScope) or rejected until you pass a scope filter. Hit content is a bounded excerpt — when a hit reports truncated: true, call get_memories with its id to read the full content. Superseded predecessors are never filtered out, only ranked below their successor — a hit reports superseded: true when it is one, so you can tell a demoted result from a current one; superseded is recomputed live on every page (including continuations of a frozen relevance walk), so a hit\'s rank and score stay frozen across pages of one walk but its superseded flag can still flip if it is revised mid-session. To page: pass nextCursor back as cursor with the SAME query, filters, and order; pages come from the ordering frozen (relevance) or the keyset position (chronological) on the first page, so a mid-walk write or archive can never duplicate or skip a hit. The cursor is bound to the query, filters, and order that issued it: passing it with any of those changed is rejected as invalid input — omit the cursor to start a new search. The relevance cursor token is a real context cost (~4-6 KB — it carries the frozen ids+scores of the candidate pool); the chronological cursor is tiny (a single row position) by comparison. Paging stops at the frozen pool (relevance) or the live corpus (chronological): hasMore: false means there is nothing more to page to. For broad scans set projection: "compact" to omit content/contentLength/truncated per hit (~5x fewer tokens), then batch-fetch the interesting ids with get_memories.',
|
|
266
|
+
inputSchema: searchQueryV4Schema,
|
|
117
267
|
outputSchema: searchToolOutputV3Schema,
|
|
268
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
118
269
|
},
|
|
119
270
|
async handler(args, ctx) {
|
|
120
|
-
|
|
121
|
-
return fail('embedding gateway not configured');
|
|
122
|
-
}
|
|
123
|
-
const input = searchQueryV3Schema.parse(args);
|
|
271
|
+
const input = searchQueryV4Schema.parse(args);
|
|
124
272
|
const filters = toFilters(input);
|
|
125
273
|
// Assert platform read access before policy resolution performs its tenant
|
|
126
274
|
// lookup. The core call is therefore not given the gate a second time.
|
|
@@ -129,54 +277,14 @@ const searchTool = {
|
|
|
129
277
|
// RETRIEVAL-SCOPE POLICY (issue #47): resolved at most once per request
|
|
130
278
|
// (the route's memoized thunk) and INJECTED into core, which owns the
|
|
131
279
|
// enforcement (default fills a missing scope filter; require throws the
|
|
132
|
-
// typed UnscopedRetrievalError mapped by errors.ts).
|
|
280
|
+
// typed UnscopedRetrievalError mapped by errors.ts). Shared across both
|
|
281
|
+
// order branches so neither pays a second lookup.
|
|
133
282
|
const retrievalPolicy = ctx.retrievalPolicy === undefined ? undefined : await ctx.retrievalPolicy();
|
|
134
283
|
const policyScope = applyPolicyToScopeFilter(retrievalPolicy, filters.scope);
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
// (mapped to invalid_input), never silently paging the old frozen ids.
|
|
140
|
-
// Fingerprint-less cursors stay valid (verify-when-present).
|
|
141
|
-
const fingerprint = searchFingerprint(input.query, filters, policyScope.scope, policyScope.appliedScope !== null);
|
|
142
|
-
const decoded = input.cursor === undefined ? undefined : decodeSearchCursor(input.cursor, fingerprint);
|
|
143
|
-
const frozen = decoded === undefined
|
|
144
|
-
? undefined
|
|
145
|
-
: {
|
|
146
|
-
ids: decoded.ids,
|
|
147
|
-
scores: decoded.scores,
|
|
148
|
-
off: decoded.off,
|
|
149
|
-
...(decoded.policyScope === undefined ? {} : { policyScope: decoded.policyScope }),
|
|
150
|
-
};
|
|
151
|
-
const page = await searchDashboardPage(ctx.userId, input.query, { gateway: ctx.gateway }, defined({
|
|
152
|
-
limit: input.limit,
|
|
153
|
-
filters,
|
|
154
|
-
frozen,
|
|
155
|
-
budget: ctx.budget,
|
|
156
|
-
retrievalPolicy,
|
|
157
|
-
}));
|
|
158
|
-
// Emit a cursor ONLY when a further page exists (searchToolOutputV2Schema
|
|
159
|
-
// ENFORCES nextCursor <-> hasMore, so a drifting pair can never ship).
|
|
160
|
-
const nextCursor = page.hasMore
|
|
161
|
-
? encodeCursor({
|
|
162
|
-
v: 2,
|
|
163
|
-
ids: page.frozen.ids,
|
|
164
|
-
scores: page.frozen.scores,
|
|
165
|
-
off: page.nextOffset,
|
|
166
|
-
fp: fingerprint,
|
|
167
|
-
policyScope: page.frozen.policyScope,
|
|
168
|
-
})
|
|
169
|
-
: undefined;
|
|
170
|
-
const output = parseOutput('search', searchToolOutputV3Schema, defined({
|
|
171
|
-
hits: page.hits.map((hit) => projectHit(hit, input.projection)),
|
|
172
|
-
count: page.hits.length,
|
|
173
|
-
hasMore: page.hasMore,
|
|
174
|
-
nextCursor,
|
|
175
|
-
// Present exactly when the policy narrowed this call (never silent);
|
|
176
|
-
// omitted otherwise so an off/no-policy response stays byte-identical.
|
|
177
|
-
appliedScope: page.appliedScope ?? undefined,
|
|
178
|
-
}));
|
|
179
|
-
return ok(output);
|
|
284
|
+
if (input.order === 'chronological') {
|
|
285
|
+
return handleChronologicalSearch(input, filters, policyScope, retrievalPolicy, ctx);
|
|
286
|
+
}
|
|
287
|
+
return handleRelevanceSearch(input, filters, policyScope, retrievalPolicy, ctx);
|
|
180
288
|
},
|
|
181
289
|
};
|
|
182
290
|
/**
|