@ego-z/contracts 0.15.20 → 0.15.22

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.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/src/ask.d.ts +70 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ego-z/contracts",
3
- "version": "0.15.20",
3
+ "version": "0.15.22",
4
4
  "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
5
5
  "types": "./src/index.d.ts",
6
6
  "exports": {
package/src/ask.d.ts CHANGED
@@ -231,6 +231,76 @@ export interface AskRequestBody {
231
231
  */
232
232
  toolHeaders?: Record<string, string>;
233
233
 
234
+ /**
235
+ * The ONLY tools this turn may be offered, by name.
236
+ *
237
+ * - omitted → every tool the project offers today (unchanged).
238
+ * - a list → the project's enabled tools whose `toolName` is listed,
239
+ * and each built-in only when its function name is listed:
240
+ * `search_knowledge_base`, `remember_fact`, `ask_user`,
241
+ * `web_fetch`, `web_search`.
242
+ * - `[]` → no tools at all.
243
+ *
244
+ * ── Why it exists ────────────────────────────────────────────────────
245
+ *
246
+ * A project's chat agent and a narrow program job can share one project.
247
+ * When the job's input is a stranger's text (an email answered with
248
+ * nobody watching), the turn must not be able to reach a write tool,
249
+ * remember a "fact" for later, or fetch a page the text names, while the
250
+ * same project's chat keeps all of them.
251
+ *
252
+ * ── What it does NOT do ──────────────────────────────────────────────
253
+ *
254
+ * It never adds a tool: a listed name the project has not enabled, or a
255
+ * built-in its config leaves off, stays off. An unknown name is ignored
256
+ * rather than refused, because a tool can be disabled after the caller
257
+ * was written. A classic project's pre-fetched knowledge-base context is
258
+ * not a tool and is unaffected; memory the project already injects is
259
+ * still read.
260
+ *
261
+ * An array of non-empty strings, at most 64; anything else is a 400, and
262
+ * so is `tools` together with `completion: true` (a completion offers no
263
+ * tools). `null` is treated as omitted.
264
+ *
265
+ * Optional and additive: omit it and nothing changes.
266
+ */
267
+ tools?: string[];
268
+
269
+ /**
270
+ * Tools a turn narrowed by `tools` may still load, by group.
271
+ *
272
+ * - omitted → the turn has exactly `tools` (unchanged).
273
+ * - a map → each key names a group, each value lists the tool names it
274
+ * adds. The turn is offered one more built-in,
275
+ * `load_tools({ groups })`; when the model calls it, the
276
+ * named groups' tools join the turn for its remaining steps.
277
+ * The next turn starts from `tools` again.
278
+ *
279
+ * ── Why it exists ────────────────────────────────────────────────────
280
+ *
281
+ * A caller that narrows each turn to the tools it most likely needs, to
282
+ * keep every model call small, can guess wrong. Without a way out, the
283
+ * narrowed turn cannot reach the tool it turns out to need and answers
284
+ * that it can't. With one, the model loads that group and carries on in
285
+ * the same turn, at the cost of one step.
286
+ *
287
+ * ── What it does NOT do ──────────────────────────────────────────────
288
+ *
289
+ * The same rule as `tools`: it never adds a tool the project has not
290
+ * enabled, and an unknown name is ignored. Tenant tools only: a built-in
291
+ * is reached through `tools`, never through a group.
292
+ *
293
+ * Needs `tools` (without it the turn already has every tool). At most 16
294
+ * groups; a group name is 1 to 40 letters, digits, `_` or `-`, and the
295
+ * model reads it, so name groups by what they are for (`website`,
296
+ * `orders`); each group lists 1 to 64 non-empty names. Anything else is a
297
+ * 400, and so is `toolGroups` with `completion: true`. `null` is treated
298
+ * as omitted.
299
+ *
300
+ * Optional and additive: omit it and nothing changes.
301
+ */
302
+ toolGroups?: Record<string, string[]>;
303
+
234
304
  /**
235
305
  * What the user has on screen RIGHT NOW — sent on every turn, not just
236
306
  * when the conversation started.