@jini-ai/cms 0.4.0 → 0.4.2
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/CHANGELOG.md +7 -0
- package/dist/media/blob-store.fs.d.ts +4 -0
- package/dist/media/blob-store.fs.js +27 -0
- package/dist/media/blob-store.memory.d.ts +3 -0
- package/dist/media/blob-store.memory.js +3 -0
- package/dist/media/created-by.d.ts +15 -0
- package/dist/media/created-by.js +20 -0
- package/dist/media/index.d.ts +1 -0
- package/dist/media/index.js +1 -0
- package/dist/media/media-service.d.ts +1 -1
- package/dist/media/media-service.js +1 -0
- package/dist/media/ports.d.ts +12 -2
- package/dist/media/repo.memory.js +2 -1
- package/dist/media/tool-registrations.js +1 -0
- package/dist/media/types.d.ts +4 -0
- package/dist/navigation/menu-service.js +6 -0
- package/dist/navigation/types.d.ts +5 -0
- package/dist/settings/agent-value-write-tools.js +2 -2
- package/dist/settings/tool-registrations.d.ts +5 -3
- package/dist/taxonomy/write-service.d.ts +4 -2
- package/dist/taxonomy/write-service.js +8 -3
- package/dist/trash/write-service.js +19 -12
- package/package.json +2 -2
- package/dist/core/tools/registration-kit.d.ts +0 -346
- package/dist/core/tools/registration-kit.js +0 -426
- package/dist/server/index.d.ts +0 -28
- package/dist/server/index.js +0 -28
|
@@ -1,426 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @file The cross-domain half of the agent-tool wiring split: everything a domain's own
|
|
3
|
-
* `tool-registrations.ts` needs that is NOT specific to that domain.
|
|
4
|
-
*
|
|
5
|
-
* Why this file exists at all. Every domain's wiring repeats the same five moves — index its
|
|
6
|
-
* catalog by id, read a handful of fields off `ctx.input`, run the tool's permission check,
|
|
7
|
-
* decorate a shape rejection with the published schema, and then loop the handler map into
|
|
8
|
-
* `ToolRegistration`s behind a build-time risk/schema gate. Those five moves were previously copied
|
|
9
|
-
* per domain inside one shared `assistant/tool-registrations.ts`, which is exactly why that file
|
|
10
|
-
* grew past 2000 lines and why three independent domain slices could not be developed in parallel
|
|
11
|
-
* without colliding on it. Each domain now owns a `tool-registrations.ts` next to its own code and
|
|
12
|
-
* imports the shared moves from here; `assistant/tool-registrations.ts` is reduced to the
|
|
13
|
-
* aggregator that assembles them.
|
|
14
|
-
*
|
|
15
|
-
* The membership test for anything in this file is "would a fourth, not-yet-written domain need
|
|
16
|
-
* it?". Domain-shaped things deliberately stay out: each domain's model-facing `to*View`
|
|
17
|
-
* projections, its dependency-bag builder, its own `DERIVED_RISK_BY_TOOL_ID` slice (a claim about
|
|
18
|
-
* that domain's handlers, so it is maintained where those handlers live), and its unwired-tool set.
|
|
19
|
-
*
|
|
20
|
-
* What is deliberately NOT abstracted here is the authorization DECISION. {@link requireToolPermission}
|
|
21
|
-
* performs a check a caller asks for; it never decides that a check is needed. The "one
|
|
22
|
-
* evaluator" rule is a per-tool fact — some domains self-enforce inside their service function and
|
|
23
|
-
* must NOT be double-checked here, others have no service-layer gate at all and must be checked at
|
|
24
|
-
* the handler — and that judgement stays recorded in the domain file next to the handler it
|
|
25
|
-
* describes, where a reviewer reading the handler can see it.
|
|
26
|
-
*/
|
|
27
|
-
import { ToolInputError } from "@jini-ai/core";
|
|
28
|
-
// Imported from `../commands/command` rather than the `../commands` barrel deliberately. The barrel
|
|
29
|
-
// re-exports `appliers.ts`, which names `features/post` and `features/settings` directly, so any file
|
|
30
|
-
// reaching this kit through the barrel inherits a dependency on two specific features. Every domain's
|
|
31
|
-
// `tool-registrations.ts` imports this kit, so that one barrel hop is what welds the tool layer to the
|
|
32
|
-
// content features and makes domains like `identity` non-extractable. Both symbols below are defined
|
|
33
|
-
// in `command.ts`; importing them from there costs nothing and keeps the kit feature-agnostic.
|
|
34
|
-
import { ForbiddenError } from "../commands/command.js";
|
|
35
|
-
/**
|
|
36
|
-
* Audit provenance stamped onto every revision row a tool handler writes.
|
|
37
|
-
*
|
|
38
|
-
* A constant, not `ctx.principal`'s own kind, and that is the point: `ctx.principal.id` is the
|
|
39
|
-
* HUMAN admin's principal id — the host's proxy reads it from the browser session and stamps it
|
|
40
|
-
* into the run's `contextRef`, and the daemon hands it back to the handler. So a content-type change made by the assistant and one the same person made by clicking
|
|
41
|
-
* through the admin UI record an identical `actorId`. What distinguishes them is the path, and
|
|
42
|
-
* reaching a `tool-registrations.ts` handler IS the agent path — those handlers are only ever
|
|
43
|
-
* invoked by `@jini-ai/daemon`'s `ToolExecutor` during a run. `'agent'` is therefore a fact about
|
|
44
|
-
* the call site, not a default.
|
|
45
|
-
*/
|
|
46
|
-
// Typed as the literal "agent" (not the wider `ActorPrincipalKind`/`CommandActor["kind"]` unions
|
|
47
|
-
// each domain declares) so this one constant satisfies both content-types' `principalKind` param
|
|
48
|
-
// and Forms' `CommandActor.kind` param without a cast at either call site.
|
|
49
|
-
export const AGENT_TOOL_PRINCIPAL_KIND = "agent";
|
|
50
|
-
/**
|
|
51
|
-
* Actor-class rules that need a human confirmer.
|
|
52
|
-
*
|
|
53
|
-
* `confirmer-must-equal-own-delegatedBy` means "a human must confirm this, and the confirmer must
|
|
54
|
-
* be the principal who delegated". The kit never delivers that through `descriptor.requiresConfirmation`:
|
|
55
|
-
* without a host `ExecutionDelegate`, that flag parks the execution on a promise only
|
|
56
|
-
* `resumeConfirmation` can settle, and nothing would call it (unbounded, too, because
|
|
57
|
-
* `descriptor.timeoutMs`'s timer is armed only AFTER the confirmation await).
|
|
58
|
-
*
|
|
59
|
-
* So a tool carrying this rule is wirable only when its handler was built with
|
|
60
|
-
* {@link humanConfirmedHandler}, which asks the human through the host's own confirmation transport
|
|
61
|
-
* and runs the action only on an explicit yes. Any other handler fails the build.
|
|
62
|
-
*/
|
|
63
|
-
export const ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT = new Set(["confirmer-must-equal-own-delegatedBy"]);
|
|
64
|
-
const HUMAN_CONFIRMED_HANDLERS = new WeakSet();
|
|
65
|
-
/**
|
|
66
|
-
* Builds the one kind of handler a `confirmer-must-equal-own-delegatedBy` tool may be wired with
|
|
67
|
-
* (see {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}).
|
|
68
|
-
*
|
|
69
|
-
* The order is fixed here, not left to each domain: `prepare` (validate, pre-authorize, derive what
|
|
70
|
-
* the human will see) → `askHuman` (the host's transport, e.g. an MCP-UI dialog) → `run`, only when
|
|
71
|
-
* the answer is exactly `{ confirmed: true }`. The decision never comes from `ctx.input`, so nothing
|
|
72
|
-
* the model sends can stand in for the human. `run` gets the confirmer as the delegating human.
|
|
73
|
-
*
|
|
74
|
-
* @param steps.prepare - Reads input and derives what the human is asked about. May throw.
|
|
75
|
-
* @param steps.askHuman - Asks the human through the host's transport. Throws when no human can be
|
|
76
|
-
* asked; a no-answer returns `{ confirmed: false, result }` and `result` is the tool's result.
|
|
77
|
-
* @param steps.run - Performs the action on a yes.
|
|
78
|
-
* @returns A handler {@link assertToolIsWirable} accepts for a tool carrying the rule.
|
|
79
|
-
* @complexity O(1) plus the three steps.
|
|
80
|
-
*/
|
|
81
|
-
export function humanConfirmedHandler(steps) {
|
|
82
|
-
const handler = async (ctx) => {
|
|
83
|
-
const prepared = await steps.prepare(ctx);
|
|
84
|
-
const answer = await steps.askHuman(ctx, prepared);
|
|
85
|
-
if (answer.confirmed !== true)
|
|
86
|
-
return answer.result;
|
|
87
|
-
return steps.run(ctx, prepared, { id: ctx.principal.id, kind: "user" });
|
|
88
|
-
};
|
|
89
|
-
HUMAN_CONFIRMED_HANDLERS.add(handler);
|
|
90
|
-
return handler;
|
|
91
|
-
}
|
|
92
|
-
/**
|
|
93
|
-
* Indexes a domain catalog by tool id — the single lookup used for descriptors, risk metadata, and
|
|
94
|
-
* schema-bearing error messages.
|
|
95
|
-
*
|
|
96
|
-
* @param catalog - The domain's own `agent-tools.ts` catalog array.
|
|
97
|
-
* @returns The catalog keyed by `name`.
|
|
98
|
-
* @complexity O(n) once at module load, O(1) per subsequent lookup.
|
|
99
|
-
* @overallScore 100
|
|
100
|
-
*/
|
|
101
|
-
export function indexCatalogById(catalog) {
|
|
102
|
-
return new Map(catalog.map((tool) => [tool.name, tool]));
|
|
103
|
-
}
|
|
104
|
-
// ---------------------------------------------------------------------------
|
|
105
|
-
// Input readers — the vocabulary every handler uses to read `ctx.input`.
|
|
106
|
-
// ---------------------------------------------------------------------------
|
|
107
|
-
export function isRecord(value) {
|
|
108
|
-
return typeof value === "object" && value !== null;
|
|
109
|
-
}
|
|
110
|
-
/** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
|
|
111
|
-
export function requireInputRecord(input) {
|
|
112
|
-
if (!isRecord(input))
|
|
113
|
-
throw new ToolInputError("input must be an object");
|
|
114
|
-
return input;
|
|
115
|
-
}
|
|
116
|
-
export function requireString(input, key) {
|
|
117
|
-
const value = input[key];
|
|
118
|
-
if (typeof value !== "string" || value.length === 0) {
|
|
119
|
-
throw new ToolInputError(`'${key}' (non-empty string) is required`);
|
|
120
|
-
}
|
|
121
|
-
return value;
|
|
122
|
-
}
|
|
123
|
-
export function requireNumber(input, key) {
|
|
124
|
-
const value = input[key];
|
|
125
|
-
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
126
|
-
throw new ToolInputError(`'${key}' (number) is required`);
|
|
127
|
-
}
|
|
128
|
-
return value;
|
|
129
|
-
}
|
|
130
|
-
export function requireObject(input, key) {
|
|
131
|
-
const value = input[key];
|
|
132
|
-
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
133
|
-
throw new ToolInputError(`'${key}' (object) is required`);
|
|
134
|
-
}
|
|
135
|
-
return value;
|
|
136
|
-
}
|
|
137
|
-
export function optionalString(input, key) {
|
|
138
|
-
const value = input[key];
|
|
139
|
-
if (value === undefined)
|
|
140
|
-
return undefined;
|
|
141
|
-
if (typeof value !== "string")
|
|
142
|
-
throw new ToolInputError(`'${key}' must be a string`);
|
|
143
|
-
return value;
|
|
144
|
-
}
|
|
145
|
-
export function optionalNumber(input, key) {
|
|
146
|
-
const value = input[key];
|
|
147
|
-
if (value === undefined)
|
|
148
|
-
return undefined;
|
|
149
|
-
if (typeof value !== "number" || !Number.isFinite(value))
|
|
150
|
-
throw new ToolInputError(`'${key}' must be a number`);
|
|
151
|
-
return value;
|
|
152
|
-
}
|
|
153
|
-
export function optionalBoolean(input, key) {
|
|
154
|
-
const value = input[key];
|
|
155
|
-
if (value === undefined)
|
|
156
|
-
return undefined;
|
|
157
|
-
if (typeof value !== "boolean")
|
|
158
|
-
throw new ToolInputError(`'${key}' must be a boolean`);
|
|
159
|
-
return value;
|
|
160
|
-
}
|
|
161
|
-
/**
|
|
162
|
-
* The reader for a parameterless tool: `ctx.input` may be omitted entirely or passed as `{}`,
|
|
163
|
-
* nothing else. Refusing a populated object is deliberate — silently ignoring keys would teach a
|
|
164
|
-
* model that a filter it invented was applied.
|
|
165
|
-
*/
|
|
166
|
-
export function requireNoInput(input) {
|
|
167
|
-
if (input === undefined)
|
|
168
|
-
return;
|
|
169
|
-
if (!isRecord(input) || Object.keys(input).length > 0) {
|
|
170
|
-
throw new ToolInputError("this tool accepts no input — omit 'input' or pass {}");
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
/**
|
|
174
|
-
* Wraps a `Result<T, Error>`-returning domain call as a value: `ToolExecutor` treats a thrown error
|
|
175
|
-
* as a `'failed'` execution, so an `{ok:false}` becomes a throw rather than a silently-swallowed
|
|
176
|
-
* value.
|
|
177
|
-
*/
|
|
178
|
-
export function fromResult(fn) {
|
|
179
|
-
return fn().then((result) => {
|
|
180
|
-
if (!result.ok)
|
|
181
|
-
throw result.error;
|
|
182
|
-
return result.value;
|
|
183
|
-
});
|
|
184
|
-
}
|
|
185
|
-
// ---------------------------------------------------------------------------
|
|
186
|
-
// Authorization
|
|
187
|
-
// ---------------------------------------------------------------------------
|
|
188
|
-
/**
|
|
189
|
-
* Runs the identical inline `authorize()` check the corresponding admin HTTP route performs, for a
|
|
190
|
-
* tool whose own domain function carries no `authorize()` call to inherit.
|
|
191
|
-
*
|
|
192
|
-
* This is NOT a second evaluator alongside another check — that is exactly the single-evaluator
|
|
193
|
-
* rule's concern. For each tool that
|
|
194
|
-
* calls it, this IS the only gate that tool's execution ever reaches, reached by an identical path
|
|
195
|
-
* to the one a human clicking the same admin route reaches. Domains split cleanly on which kind
|
|
196
|
-
* they are: content-types/Forms/Identity mutations and every Widgets write-service call self-enforce
|
|
197
|
-
* inside the domain function and must NOT call this; Comments/Members/Newsletter/Media/Menus/
|
|
198
|
-
* Database/Recovery gate in the route instead, so their handlers call this in the route's place.
|
|
199
|
-
* Which kind a given tool is stays documented next to that tool's handler, not here.
|
|
200
|
-
*
|
|
201
|
-
* Throws `core/commands`'s `ForbiddenError` — the same class `executeCommand` itself throws — so a
|
|
202
|
-
* tool caller and a route caller see the identical error shape for an identical denial. Throw
|
|
203
|
-
* rather than a 403 body because the caller here is `ToolExecutor`, which reads a thrown error as a
|
|
204
|
-
* failed execution and has no response to write to.
|
|
205
|
-
*
|
|
206
|
-
* @param deps - The `authorize()` evaluator and the workspace the run is scoped to.
|
|
207
|
-
* @param required - Who is asking, for what permission, optionally against which entity.
|
|
208
|
-
* @throws {ForbiddenError} If `authorize()` denies.
|
|
209
|
-
* @complexity O(1) beyond the injected `authorize()` call.
|
|
210
|
-
* @overallScore 100
|
|
211
|
-
*/
|
|
212
|
-
export async function requireToolPermission(deps, required) {
|
|
213
|
-
const result = await deps.authorize({
|
|
214
|
-
principalId: required.principalId,
|
|
215
|
-
permission: required.permission,
|
|
216
|
-
workspaceId: deps.workspaceId,
|
|
217
|
-
entityType: required.entityType,
|
|
218
|
-
entityId: required.entityId,
|
|
219
|
-
});
|
|
220
|
-
if (!result.allowed) {
|
|
221
|
-
throw new ForbiddenError(`principal '${required.principalId}' is not authorized for '${required.permission}' (${result.reason})`, required.permission, result.reason);
|
|
222
|
-
}
|
|
223
|
-
}
|
|
224
|
-
// ---------------------------------------------------------------------------
|
|
225
|
-
// Error recovery
|
|
226
|
-
// ---------------------------------------------------------------------------
|
|
227
|
-
/** Appended to every decorated rejection so a model does not burn a turn retrying an identical call. */
|
|
228
|
-
const RETRY_IS_FUTILE = "Fix the input and retry — this will not resolve on retry without an input change.";
|
|
229
|
-
/**
|
|
230
|
-
* Re-throws a rejection with the tool's published `inputSchema` appended, so a model can correct
|
|
231
|
-
* its call in a single turn instead of guessing the rest of the shape from one field's complaint.
|
|
232
|
-
*
|
|
233
|
-
* `isShapeRejection` is the domain's own decision and has no default: only errors a DIFFERENT input
|
|
234
|
-
* would fix are decorated. A `ForbiddenError` or a slug conflict is not a shape problem, and
|
|
235
|
-
* appending a schema to one would be noise the model must read past — worse, it would imply the
|
|
236
|
-
* call is retryable when it is not.
|
|
237
|
-
*
|
|
238
|
-
* @param spec.toolId - The tool whose schema is published with the failure.
|
|
239
|
-
* @param spec.catalog - The domain catalog, consulted for that schema.
|
|
240
|
-
* @param spec.isShapeRejection - Predicate selecting the errors worth decorating.
|
|
241
|
-
* @param fn - The domain call.
|
|
242
|
-
* @throws The original error unchanged when it is not a shape rejection, or a decorated `Error`
|
|
243
|
-
* when it is. A tool whose catalog entry publishes no schema still gets the retry-is-futile note.
|
|
244
|
-
* @complexity O(1) beyond the wrapped call, plus the schema's own serialization on the failure path.
|
|
245
|
-
* @overallScore 100
|
|
246
|
-
*/
|
|
247
|
-
export async function withSchemaOnRejection(spec, fn) {
|
|
248
|
-
try {
|
|
249
|
-
return await fn();
|
|
250
|
-
}
|
|
251
|
-
catch (error) {
|
|
252
|
-
if (!spec.isShapeRejection(error))
|
|
253
|
-
throw error;
|
|
254
|
-
throw decorateWithSchema({ toolId: spec.toolId, catalog: spec.catalog, message: error.message });
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
|
-
/**
|
|
258
|
-
* The synchronous half of {@link withSchemaOnRejection}, for a domain that validates BEFORE the
|
|
259
|
-
* call rather than inside it (content-types parses `fields` at a boundary parser, so its rejection
|
|
260
|
-
* never reaches a `try` around a domain call).
|
|
261
|
-
*
|
|
262
|
-
* @returns The `Error` to throw — returned rather than thrown so the caller's own `throw` keeps
|
|
263
|
-
* TypeScript's control-flow narrowing at the call site.
|
|
264
|
-
* @complexity O(s) in the serialized schema size, on the failure path only.
|
|
265
|
-
* @overallScore 100
|
|
266
|
-
*/
|
|
267
|
-
export function decorateWithSchema(params) {
|
|
268
|
-
const schema = params.catalog.get(params.toolId)?.inputSchema;
|
|
269
|
-
// A `ToolInputError`, not a plain `Error`: every rejection reaching here already passed the
|
|
270
|
-
// caller's own `isShapeRejection` predicate — "a DIFFERENT input would fix this" — which is
|
|
271
|
-
// exactly what the marker means. `@jini-ai/daemon`'s `ToolExecutor` reads it off the thrown error
|
|
272
|
-
// to tag the execution result `errorKind: 'validation'` rather than folding it into the same
|
|
273
|
-
// redacted-500 bucket a genuine internal failure gets.
|
|
274
|
-
return new ToolInputError(schema
|
|
275
|
-
? `${params.message}. ${RETRY_IS_FUTILE} Schema for '${params.toolId}': ${JSON.stringify(schema)}`
|
|
276
|
-
: `${params.message}. ${RETRY_IS_FUTILE}`);
|
|
277
|
-
}
|
|
278
|
-
// ---------------------------------------------------------------------------
|
|
279
|
-
// Build-time gates
|
|
280
|
-
// ---------------------------------------------------------------------------
|
|
281
|
-
/**
|
|
282
|
-
* Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
|
|
283
|
-
* `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
|
|
284
|
-
* whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
|
|
285
|
-
* its handler does not ask for.
|
|
286
|
-
*
|
|
287
|
-
* Throws rather than warning, and at registration time rather than call time: a metadata
|
|
288
|
-
* inconsistency is a developer error that should stop the daemon booting, not a runtime condition
|
|
289
|
-
* to degrade around.
|
|
290
|
-
*
|
|
291
|
-
* @param params.toolId - The wired tool id.
|
|
292
|
-
* @param params.catalogEntry - Its `agent-tools.ts` entry, the declared side of the comparison.
|
|
293
|
-
* @param params.derivedRisk - The wiring layer's independent classification, the derived side.
|
|
294
|
-
* @param params.handler - The handler being wired; checked only for a tool carrying a rule in
|
|
295
|
-
* {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
|
|
296
|
-
* @throws {Error} If the tool is unclassified, misclassified, or needs a human confirmer its handler
|
|
297
|
-
* does not ask for.
|
|
298
|
-
* @complexity O(1) — two map/set lookups.
|
|
299
|
-
* @overallScore 100
|
|
300
|
-
*/
|
|
301
|
-
export function assertToolIsWirable(params) {
|
|
302
|
-
const { toolId, catalogEntry } = params;
|
|
303
|
-
const derived = params.derivedRisk.get(toolId);
|
|
304
|
-
if (!derived) {
|
|
305
|
-
throw new Error(`tool-registrations: '${toolId}' has no entry in DERIVED_RISK_BY_TOOL_ID — classify what its handler actually does before wiring it (unknown operations are refused, never assumed safe)`);
|
|
306
|
-
}
|
|
307
|
-
if (derived !== catalogEntry.sideEffects) {
|
|
308
|
-
throw new Error(`tool-registrations: '${toolId}' declares sideEffects '${catalogEntry.sideEffects}' but this layer derives '${derived}' from what its handler calls — reconcile the two rather than trusting the declaration`);
|
|
309
|
-
}
|
|
310
|
-
const needsHuman = catalogEntry.actorClassRule && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
|
|
311
|
-
if (needsHuman && !(params.handler && HUMAN_CONFIRMED_HANDLERS.has(params.handler))) {
|
|
312
|
-
throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
|
|
313
|
-
}
|
|
314
|
-
}
|
|
315
|
-
/**
|
|
316
|
-
* Turns one domain's handler map into `ToolRegistration`s, applying every build-time gate the
|
|
317
|
-
* wiring layer owes each tool, and tripwiring on any catalog entry that is neither wired nor
|
|
318
|
-
* explicitly declared unwired.
|
|
319
|
-
*
|
|
320
|
-
* The tripwire is the reason this is one shared function rather than a loop each domain copies.
|
|
321
|
-
* "Add a catalog entry, forget to wire it" is the failure this layer is meant to make impossible,
|
|
322
|
-
* and a per-domain copy of the check is a per-domain opportunity to get it subtly wrong — one of
|
|
323
|
-
* the copies this replaced omitted the schema assertion, another omitted the unwired-set escape
|
|
324
|
-
* hatch. Silence is never the outcome: an unwired entry either appears in `unwiredToolIds` with a
|
|
325
|
-
* recorded reason next to it, or the build fails.
|
|
326
|
-
*
|
|
327
|
-
* `policy.authorize` is a pass-through `'allow'` for every registration, and that is by design
|
|
328
|
-
* rather than an omission: each tool's permission is evaluated exactly once — inside its domain
|
|
329
|
-
* function for the self-enforcing domains, or by the handler's own {@link requireToolPermission}
|
|
330
|
-
* call for the domains whose gate lives in the route. A check here would be a SECOND evaluator of
|
|
331
|
-
* the same rule, and a `ToolPolicy`-only check would be bypassable by any future non-tool caller of
|
|
332
|
-
* the same domain function, which is precisely why the chokepoint owns the gate.
|
|
333
|
-
*
|
|
334
|
-
* `descriptor.requiresConfirmation` is deliberately never set — a tool that needs a human confirm
|
|
335
|
-
* asks inside its own {@link humanConfirmedHandler}; see
|
|
336
|
-
* {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
|
|
337
|
-
*
|
|
338
|
-
* @param spec.domain - Human-readable domain name, used only in failure messages.
|
|
339
|
-
* @param spec.catalogModule - Path of the catalog file, named in the drift message so the failure
|
|
340
|
-
* points at the file to edit.
|
|
341
|
-
* @param spec.catalog - That domain's catalog indexed by id (see {@link indexCatalogById}).
|
|
342
|
-
* @param spec.handlers - Tool id to handler. Registration order follows this map's key order.
|
|
343
|
-
* @param spec.derivedRisk - The domain's own risk classification (see {@link DerivedRiskByToolId}).
|
|
344
|
-
* @param spec.unwiredToolIds - Catalog ids deliberately not wired. Omit when the domain wires its
|
|
345
|
-
* entire catalog, which makes ANY unwired entry a build failure.
|
|
346
|
-
* @throws {Error} On catalog drift, an unclassified/misclassified tool, a wired tool publishing no
|
|
347
|
-
* `inputSchema`, or a catalog entry that is neither wired nor declared unwired.
|
|
348
|
-
* @complexity O(h + c) in the handler and catalog counts.
|
|
349
|
-
* @overallScore 100
|
|
350
|
-
*/
|
|
351
|
-
export function buildDomainRegistrations(spec) {
|
|
352
|
-
const registrations = [];
|
|
353
|
-
for (const [id, handler] of Object.entries(spec.handlers)) {
|
|
354
|
-
const catalogEntry = spec.catalog.get(id);
|
|
355
|
-
if (!catalogEntry) {
|
|
356
|
-
throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
|
|
357
|
-
}
|
|
358
|
-
assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk, handler });
|
|
359
|
-
if (!catalogEntry.inputSchema) {
|
|
360
|
-
throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
|
|
361
|
-
}
|
|
362
|
-
registrations.push({
|
|
363
|
-
descriptor: {
|
|
364
|
-
id,
|
|
365
|
-
description: catalogEntry.description,
|
|
366
|
-
inputSchema: catalogEntry.inputSchema,
|
|
367
|
-
// The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
|
|
368
|
-
// reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
|
|
369
|
-
// `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this
|
|
370
|
-
// line is twelve chances for one to say something different. Change what counts as
|
|
371
|
-
// read-only and every domain follows.
|
|
372
|
-
//
|
|
373
|
-
// Safe to derive from the declaration only because `assertToolIsWirable` has ALREADY run
|
|
374
|
-
// two lines above and refused any tool whose declared `sideEffects` disagrees with the
|
|
375
|
-
// wiring layer's own `DERIVED_RISK_BY_TOOL_ID` classification — so by this point the
|
|
376
|
-
// declaration has been independently corroborated, and a catalog entry cannot make itself
|
|
377
|
-
// read-only by editing one word.
|
|
378
|
-
readOnly: catalogEntry.sideEffects === "none",
|
|
379
|
-
},
|
|
380
|
-
handler,
|
|
381
|
-
policy: { authorize: () => "allow" },
|
|
382
|
-
});
|
|
383
|
-
}
|
|
384
|
-
for (const id of spec.catalog.keys()) {
|
|
385
|
-
if (id in spec.handlers)
|
|
386
|
-
continue;
|
|
387
|
-
if (spec.unwiredToolIds?.has(id))
|
|
388
|
-
continue;
|
|
389
|
-
throw new Error(`tool-registrations: ${spec.domain} catalog entry '${id}' is neither wired nor declared unwired — wire a handler for it, or add it to that domain's unwired set with the reason recorded next to it`);
|
|
390
|
-
}
|
|
391
|
-
return registrations;
|
|
392
|
-
}
|
|
393
|
-
/**
|
|
394
|
-
* Folds every domain's risk slice into the one map the assistant-level
|
|
395
|
-
* `assertRiskMetadataIsWirable(toolId, catalogEntry)` consults, refusing any id two domains both
|
|
396
|
-
* claim.
|
|
397
|
-
*
|
|
398
|
-
* That refusal is the structural answer to the failure this restructure was prompted by: three
|
|
399
|
-
* domain slices were developed in parallel, each checking its new ids only against the ids that
|
|
400
|
-
* existed before it started, so a name two of them both picked would have been discovered at
|
|
401
|
-
* runtime as a silently double-registered tool. A cross-domain id collision now fails the build.
|
|
402
|
-
* The one real collision in the current catalogs — `backup_create_restore_point`, declared by both
|
|
403
|
-
* Database and Recovery — passes because Recovery declares it unwired and therefore contributes no
|
|
404
|
-
* risk entry for it, which is exactly the resolution this check is meant to force.
|
|
405
|
-
*
|
|
406
|
-
* @param slices - Each domain's name (for the failure message) and its own risk map.
|
|
407
|
-
* @throws {Error} If two domains classify the same tool id.
|
|
408
|
-
* @complexity O(t) in the total classified-tool count.
|
|
409
|
-
* @overallScore 100
|
|
410
|
-
*/
|
|
411
|
-
export function mergeDerivedRiskMaps(slices) {
|
|
412
|
-
const merged = new Map();
|
|
413
|
-
const ownerByToolId = new Map();
|
|
414
|
-
for (const slice of slices) {
|
|
415
|
-
for (const [toolId, sideEffect] of slice.risk) {
|
|
416
|
-
const owner = ownerByToolId.get(toolId);
|
|
417
|
-
if (owner) {
|
|
418
|
-
throw new Error(`tool-registrations: tool id '${toolId}' is wired by both the ${owner} and ${slice.domain} domains — one id must resolve to exactly one handler; wire it in whichever domain owns the real operation and declare it unwired in the other`);
|
|
419
|
-
}
|
|
420
|
-
ownerByToolId.set(toolId, slice.domain);
|
|
421
|
-
merged.set(toolId, sideEffect);
|
|
422
|
-
}
|
|
423
|
-
}
|
|
424
|
-
return merged;
|
|
425
|
-
}
|
|
426
|
-
//# sourceMappingURL=registration-kit.js.map
|
package/dist/server/index.d.ts
DELETED
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @file `@jini-ai/cms/server` — the Node-bound half of the CMS capability.
|
|
3
|
-
*
|
|
4
|
-
* PLACEHOLDER. Nothing has been ported yet.
|
|
5
|
-
*
|
|
6
|
-
* ## What belongs here
|
|
7
|
-
*
|
|
8
|
-
* Concrete implementations of the ports declared in `../core`: SQLite/Postgres repositories,
|
|
9
|
-
* filesystem blob stores, image transformers — anything that imports `node:*` or a native
|
|
10
|
-
* dependency. This layer depends on `../core`; the reverse is a boundary violation.
|
|
11
|
-
*
|
|
12
|
-
* ## What does NOT belong here
|
|
13
|
-
*
|
|
14
|
-
* HTTP routing and request/response handling. The source repo's `src/server/**` is an Express
|
|
15
|
-
* composition root and is explicitly out of scope for this port — Jini already has
|
|
16
|
-
* `@jini-ai/http-kit` and `@jini-ai/server` for transport. Porting those routes here would
|
|
17
|
-
* reproduce exactly the coupling this package's layer split exists to prevent (see
|
|
18
|
-
* `../core/index.ts`'s header for the measurements).
|
|
19
|
-
*
|
|
20
|
-
* The name of this subpath is `/server` for consistency with `@jini-ai/admin`'s Node layer, which
|
|
21
|
-
* uses the same convention. It means "the Node-bound layer", not "the HTTP server".
|
|
22
|
-
*/
|
|
23
|
-
/**
|
|
24
|
-
* Layer marker — same rationale as `CMS_CORE_LAYER`, and delete it on the same terms: once a real
|
|
25
|
-
* adapter is exported from here, this has no purpose.
|
|
26
|
-
*/
|
|
27
|
-
export declare const CMS_SERVER_LAYER: "server";
|
|
28
|
-
//# sourceMappingURL=index.d.ts.map
|
package/dist/server/index.js
DELETED
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @file `@jini-ai/cms/server` — the Node-bound half of the CMS capability.
|
|
3
|
-
*
|
|
4
|
-
* PLACEHOLDER. Nothing has been ported yet.
|
|
5
|
-
*
|
|
6
|
-
* ## What belongs here
|
|
7
|
-
*
|
|
8
|
-
* Concrete implementations of the ports declared in `../core`: SQLite/Postgres repositories,
|
|
9
|
-
* filesystem blob stores, image transformers — anything that imports `node:*` or a native
|
|
10
|
-
* dependency. This layer depends on `../core`; the reverse is a boundary violation.
|
|
11
|
-
*
|
|
12
|
-
* ## What does NOT belong here
|
|
13
|
-
*
|
|
14
|
-
* HTTP routing and request/response handling. The source repo's `src/server/**` is an Express
|
|
15
|
-
* composition root and is explicitly out of scope for this port — Jini already has
|
|
16
|
-
* `@jini-ai/http-kit` and `@jini-ai/server` for transport. Porting those routes here would
|
|
17
|
-
* reproduce exactly the coupling this package's layer split exists to prevent (see
|
|
18
|
-
* `../core/index.ts`'s header for the measurements).
|
|
19
|
-
*
|
|
20
|
-
* The name of this subpath is `/server` for consistency with `@jini-ai/admin`'s Node layer, which
|
|
21
|
-
* uses the same convention. It means "the Node-bound layer", not "the HTTP server".
|
|
22
|
-
*/
|
|
23
|
-
/**
|
|
24
|
-
* Layer marker — same rationale as `CMS_CORE_LAYER`, and delete it on the same terms: once a real
|
|
25
|
-
* adapter is exported from here, this has no purpose.
|
|
26
|
-
*/
|
|
27
|
-
export const CMS_SERVER_LAYER = 'server';
|
|
28
|
-
//# sourceMappingURL=index.js.map
|