@ego-z/contracts 0.15.19 → 0.15.21
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/package.json +1 -1
- package/src/ask.d.ts +35 -0
- package/src/index.d.ts +4 -0
- package/src/project-file.d.ts +354 -0
package/package.json
CHANGED
package/src/ask.d.ts
CHANGED
|
@@ -231,6 +231,41 @@ 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
|
+
|
|
234
269
|
/**
|
|
235
270
|
* What the user has on screen RIGHT NOW — sent on every turn, not just
|
|
236
271
|
* when the conversation started.
|
package/src/index.d.ts
CHANGED
|
@@ -83,6 +83,9 @@
|
|
|
83
83
|
* `UpdateUserMemoryFactBody`, list / detail / fact /
|
|
84
84
|
* forget response data, vocabularies (`UserMemoryKind`,
|
|
85
85
|
* `UserMemoryStatus`, `UserMemorySource`).
|
|
86
|
+
* - `project-file.d.ts` — the `.egoz` project file and its export /
|
|
87
|
+
* import routes: `EgozProjectFile` and its sections,
|
|
88
|
+
* `ProjectFileImportBody`, `ProjectFileImportResult`.
|
|
86
89
|
*
|
|
87
90
|
* This barrel re-exports everything so existing consumers' import paths
|
|
88
91
|
* (`import type { AskResponseData } from '@ego-z/contracts'`) keep
|
|
@@ -112,3 +115,4 @@ export * from './personality';
|
|
|
112
115
|
export * from './user-memory';
|
|
113
116
|
export * from './search';
|
|
114
117
|
export * from './controlled';
|
|
118
|
+
export * from './project-file';
|
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ego-z/contracts — the `.egoz` project file, and the routes that make and
|
|
3
|
+
* read it.
|
|
4
|
+
*
|
|
5
|
+
* - `GET /egoz/tenants/:tenantId/project-file` → `ProjectFileExportResponseData`
|
|
6
|
+
* - `POST /egoz/tenants/:tenantId/project-file/import` ← `ProjectFileImportBody`
|
|
7
|
+
* → `ProjectFileImportResult`
|
|
8
|
+
* - `GET /egoz/mcp-admin/project-file` (same, for an MCP token's project)
|
|
9
|
+
* - `POST /egoz/mcp-admin/project-file/import` (same, plus `force`)
|
|
10
|
+
*
|
|
11
|
+
* A `.egoz` file is everything an owner built in a project — settings,
|
|
12
|
+
* prompts, personalities, tools, knowledge base, prices, extensions and web
|
|
13
|
+
* search sites — as JSON. Importing it into another project makes that
|
|
14
|
+
* project's build match the file, one to one.
|
|
15
|
+
*
|
|
16
|
+
* ── What a file never holds ──────────────────────────────────────────────
|
|
17
|
+
*
|
|
18
|
+
* Tokens: API keys, MCP tokens, provider keys, the webhook secret, and the
|
|
19
|
+
* value of every tool header whose name looks like a credential
|
|
20
|
+
* (`Authorization`, `Cookie`, or any name containing `token`, `secret`,
|
|
21
|
+
* `key`, `auth`, `password` or `credential`). Those headers keep their name
|
|
22
|
+
* in `ProjectFileTool.secretHeaders`. A credential written anywhere else —
|
|
23
|
+
* inside an endpoint URL, a description, a document — is not recognised and
|
|
24
|
+
* is exported as written.
|
|
25
|
+
*
|
|
26
|
+
* Nor what a project collected while running: conversations, traces,
|
|
27
|
+
* analytics, learned facts, incidents, alerts. Nor the project itself: its
|
|
28
|
+
* name, compliance settings, plan and integration scope stay the project's
|
|
29
|
+
* own.
|
|
30
|
+
*
|
|
31
|
+
* ── Sections ─────────────────────────────────────────────────────────────
|
|
32
|
+
*
|
|
33
|
+
* Every section is optional. On import, a section the file leaves out leaves
|
|
34
|
+
* that part of the project as it is; a section the file has — even an empty
|
|
35
|
+
* one — replaces that part, so an empty `tools: []` deletes every tool. An
|
|
36
|
+
* export always writes every section, except `webSearchSites` when the search
|
|
37
|
+
* service could not be read.
|
|
38
|
+
*
|
|
39
|
+
* ── Versioning ───────────────────────────────────────────────────────────
|
|
40
|
+
*
|
|
41
|
+
* `version` changes only when an existing field changes meaning. New fields
|
|
42
|
+
* are added within a version, and an import treats a setting missing from an
|
|
43
|
+
* older file as that setting's default.
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
import type { PersonalityTraitsWire } from './personality';
|
|
47
|
+
import type { OrchestrationMode, TenantScope } from './tenant';
|
|
48
|
+
import type { VerifyMode } from './controlled';
|
|
49
|
+
import type { JsonSchemaWire, ToolAuthType, ToolHttpMethod, ToolType } from './tool';
|
|
50
|
+
import type { RagDocumentSourceType } from './rag';
|
|
51
|
+
|
|
52
|
+
// ============================================================================
|
|
53
|
+
// The file
|
|
54
|
+
// ============================================================================
|
|
55
|
+
|
|
56
|
+
/** The contents of a `.egoz` file. */
|
|
57
|
+
export interface EgozProjectFile {
|
|
58
|
+
/** Always `"egoz.project"`. */
|
|
59
|
+
format: 'egoz.project';
|
|
60
|
+
/** File format version. Files made today are version 1. */
|
|
61
|
+
version: 1;
|
|
62
|
+
/** When the file was made, ISO 8601. */
|
|
63
|
+
exportedAt: string;
|
|
64
|
+
/** The project the file was made from. Read-only information. */
|
|
65
|
+
exportedFrom: ProjectFileOrigin;
|
|
66
|
+
|
|
67
|
+
config?: ProjectFileConfig;
|
|
68
|
+
prompts?: ProjectFilePrompts;
|
|
69
|
+
personalities?: ProjectFilePersonality[];
|
|
70
|
+
tools?: ProjectFileTool[];
|
|
71
|
+
/** Knowledge-base documents, oldest first. */
|
|
72
|
+
knowledgeBase?: ProjectFileDocument[];
|
|
73
|
+
/** Per-project price overrides. EgoZ's default prices are not included. */
|
|
74
|
+
pricing?: ProjectFilePricing[];
|
|
75
|
+
/** Extensions this project has turned on or configured. */
|
|
76
|
+
extensions?: ProjectFileExtension[];
|
|
77
|
+
/** The sites `web_search` answers from when `config.webSearchScope` is `"whitelist"`. */
|
|
78
|
+
webSearchSites?: string[];
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Where a file came from. Import never writes any of it. */
|
|
82
|
+
export interface ProjectFileOrigin {
|
|
83
|
+
projectId: string;
|
|
84
|
+
name: string;
|
|
85
|
+
slug: string;
|
|
86
|
+
/**
|
|
87
|
+
* The source project's integration scope. Not imported — a project's
|
|
88
|
+
* scope is its own — but an import warns when it differs, because a
|
|
89
|
+
* gateway's learned facts must not be read as one customer's.
|
|
90
|
+
*/
|
|
91
|
+
tenantScope: TenantScope;
|
|
92
|
+
/**
|
|
93
|
+
* Whether the source project signed its tool calls with a webhook secret.
|
|
94
|
+
* The secret itself is never in the file; an import into a project
|
|
95
|
+
* without one says so, since a backend that checks signatures would then
|
|
96
|
+
* reject every call.
|
|
97
|
+
*/
|
|
98
|
+
signsToolCalls: boolean;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// ============================================================================
|
|
102
|
+
// Sections
|
|
103
|
+
// ============================================================================
|
|
104
|
+
|
|
105
|
+
/** A provider + model pair, as on the switchable-model menu. */
|
|
106
|
+
export interface ProjectFileModelRef {
|
|
107
|
+
provider: string;
|
|
108
|
+
model: string;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The project's settings, as stored — `null` means "EgoZ's default", so a
|
|
113
|
+
* project that never picked a model keeps following the default after import.
|
|
114
|
+
*
|
|
115
|
+
* Over MCP, an import leaves `llmProviderEndpoint`, `llmProviderApiVersion`,
|
|
116
|
+
* `embeddingProviderEndpoint` and `authCallbackUrl` as the project has them
|
|
117
|
+
* (a person sets those in the Console), and refuses a file whose
|
|
118
|
+
* `llmProvider` or `embeddingProvider` differs from the project's.
|
|
119
|
+
*/
|
|
120
|
+
export interface ProjectFileConfig {
|
|
121
|
+
llmProvider: 'openai' | 'azure_openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'custom_openai_compat';
|
|
122
|
+
llmProviderEndpoint: string | null;
|
|
123
|
+
llmProviderApiVersion: string | null;
|
|
124
|
+
/** `null` = the chat provider also embeds. */
|
|
125
|
+
embeddingProvider: 'openai' | 'azure_openai' | 'cohere' | 'voyage' | 'gemini' | 'bedrock' | null;
|
|
126
|
+
embeddingProviderEndpoint: string | null;
|
|
127
|
+
model: string | null;
|
|
128
|
+
embeddingModel: string | null;
|
|
129
|
+
|
|
130
|
+
modelSwitchingEnabled: boolean;
|
|
131
|
+
allowedModels: ProjectFileModelRef[];
|
|
132
|
+
autoMode: 'off' | 'available' | 'default';
|
|
133
|
+
autoShadow: boolean;
|
|
134
|
+
autoLightModel: ProjectFileModelRef | null;
|
|
135
|
+
autoHeavyModel: ProjectFileModelRef | null;
|
|
136
|
+
|
|
137
|
+
temperature: number;
|
|
138
|
+
maxTokens: number | null;
|
|
139
|
+
responseFormat: 'text' | 'json_object';
|
|
140
|
+
historyLength: number;
|
|
141
|
+
orchestrationMode: OrchestrationMode;
|
|
142
|
+
assistModel: string | null;
|
|
143
|
+
verifyMode: VerifyMode;
|
|
144
|
+
verifyThreshold: number;
|
|
145
|
+
|
|
146
|
+
toolsEnabled: boolean;
|
|
147
|
+
ragEnabled: boolean;
|
|
148
|
+
retryAttempts: number;
|
|
149
|
+
retryDelayMs: number;
|
|
150
|
+
authCallbackUrl: string | null;
|
|
151
|
+
toolBaseUrl: string | null;
|
|
152
|
+
|
|
153
|
+
generateConversationTitle: boolean;
|
|
154
|
+
persistMessageContent: boolean;
|
|
155
|
+
learningEnabled: boolean;
|
|
156
|
+
learningRetentionDays: number;
|
|
157
|
+
|
|
158
|
+
webAccessEnabled: boolean;
|
|
159
|
+
webSearchScope: 'global' | 'whitelist';
|
|
160
|
+
webSearchMaxCallsPerTurn: number;
|
|
161
|
+
webFetchMaxCallsPerTurn: number;
|
|
162
|
+
|
|
163
|
+
voiceEnabled: boolean;
|
|
164
|
+
voiceModel: string | null;
|
|
165
|
+
voiceTtsVoice: string | null;
|
|
166
|
+
voiceMinuteLimit: number | null;
|
|
167
|
+
voiceSttVendor: 'openai' | 'deepgram' | null;
|
|
168
|
+
voiceTtsVendor: 'openai' | 'elevenlabs' | null;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** The project's own system prompts. `null` = EgoZ's default prompt. */
|
|
172
|
+
export interface ProjectFilePrompts {
|
|
173
|
+
base: string | null;
|
|
174
|
+
rag: string | null;
|
|
175
|
+
tool: string | null;
|
|
176
|
+
ragTool: string | null;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** A project personality profile. */
|
|
180
|
+
export interface ProjectFilePersonality {
|
|
181
|
+
name: string;
|
|
182
|
+
traits: PersonalityTraitsWire;
|
|
183
|
+
customInstructions: string | null;
|
|
184
|
+
exampleResponses: string[];
|
|
185
|
+
avoidPhrases: string[];
|
|
186
|
+
preferredPhrases: string[];
|
|
187
|
+
agentName: string | null;
|
|
188
|
+
agentRole: string | null;
|
|
189
|
+
agentTone: string | null;
|
|
190
|
+
/** The profile `/ask` uses. At most one per file. */
|
|
191
|
+
isActive: boolean;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** A tool definition. */
|
|
195
|
+
export interface ProjectFileTool {
|
|
196
|
+
toolName: string;
|
|
197
|
+
toolDescription: string;
|
|
198
|
+
apiEndpoint: string;
|
|
199
|
+
toolType: ToolType;
|
|
200
|
+
httpMethod: ToolHttpMethod;
|
|
201
|
+
inputSchema: JsonSchemaWire;
|
|
202
|
+
outputSchema: JsonSchemaWire;
|
|
203
|
+
/** Static headers, without the ones in `secretHeaders`. */
|
|
204
|
+
headers: Record<string, string>;
|
|
205
|
+
/**
|
|
206
|
+
* Static headers whose value was left out because the name looks like a
|
|
207
|
+
* credential. On import each takes the value the project's tool of the
|
|
208
|
+
* same name already has; one the project doesn't have is reported, and
|
|
209
|
+
* the tool is saved without it until someone enters it.
|
|
210
|
+
*/
|
|
211
|
+
secretHeaders: string[];
|
|
212
|
+
authType: ToolAuthType;
|
|
213
|
+
retryAttempts: number;
|
|
214
|
+
retryDelayMs: number;
|
|
215
|
+
enabled: boolean;
|
|
216
|
+
gqlQuery: string | null;
|
|
217
|
+
exampleInput: Record<string, unknown> | null;
|
|
218
|
+
exampleOutput: Record<string, unknown> | null;
|
|
219
|
+
forwardHeaders: string[];
|
|
220
|
+
maxCallsPerTurn: number;
|
|
221
|
+
successPath: string | null;
|
|
222
|
+
displayPath: string | null;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** A knowledge-base document. Imported documents are indexed again in the new project. */
|
|
226
|
+
export interface ProjectFileDocument {
|
|
227
|
+
title: string;
|
|
228
|
+
content: string;
|
|
229
|
+
sourceType: RagDocumentSourceType;
|
|
230
|
+
sourceUrl: string | null;
|
|
231
|
+
tags: string[];
|
|
232
|
+
metadata: Record<string, unknown>;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** A per-project price, USD per 1M tokens. */
|
|
236
|
+
export interface ProjectFilePricing {
|
|
237
|
+
provider: string;
|
|
238
|
+
model: string;
|
|
239
|
+
promptPerM: number;
|
|
240
|
+
completionPerM: number;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* An extension's state. `config` is what the project set, without the
|
|
245
|
+
* extension's defaults, so a later change to a default still applies.
|
|
246
|
+
*/
|
|
247
|
+
export interface ProjectFileExtension {
|
|
248
|
+
extensionId: string;
|
|
249
|
+
enabled: boolean;
|
|
250
|
+
config: Record<string, unknown>;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// ============================================================================
|
|
254
|
+
// Export
|
|
255
|
+
// ============================================================================
|
|
256
|
+
|
|
257
|
+
/** `data` of `GET .../project-file`. */
|
|
258
|
+
export interface ProjectFileExportResponseData {
|
|
259
|
+
/** Save this as `<slug>.egoz`. */
|
|
260
|
+
file: EgozProjectFile;
|
|
261
|
+
/** What the file couldn't include, e.g. web search sites while the search service is down. */
|
|
262
|
+
warnings: string[];
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
// ============================================================================
|
|
266
|
+
// Import
|
|
267
|
+
// ============================================================================
|
|
268
|
+
|
|
269
|
+
/** Body of `POST .../project-file/import`. */
|
|
270
|
+
export interface ProjectFileImportBody {
|
|
271
|
+
/** The parsed contents of a `.egoz` file. */
|
|
272
|
+
file: EgozProjectFile;
|
|
273
|
+
/** Work out and return what the import would change, and change nothing. */
|
|
274
|
+
dryRun?: boolean;
|
|
275
|
+
/**
|
|
276
|
+
* MCP only. Allows the import to overwrite or delete things a person
|
|
277
|
+
* made in the Console (`ProjectFileImportResult.manualChanges`).
|
|
278
|
+
*/
|
|
279
|
+
force?: boolean;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** What an import changed, or — on a dry run — would change. */
|
|
283
|
+
export interface ProjectFileImportResult {
|
|
284
|
+
dryRun: boolean;
|
|
285
|
+
/** True once the changes are saved. Always false on a dry run. */
|
|
286
|
+
applied: boolean;
|
|
287
|
+
/**
|
|
288
|
+
* Problems that stop the import, e.g. a knowledge base bigger than this
|
|
289
|
+
* project's plan allows. A dry run returns them; a real import with any
|
|
290
|
+
* is refused.
|
|
291
|
+
*/
|
|
292
|
+
errors: string[];
|
|
293
|
+
warnings: string[];
|
|
294
|
+
sections: ProjectFileImportSections;
|
|
295
|
+
/**
|
|
296
|
+
* How many things a person made in the Console the import overwrites or
|
|
297
|
+
* deletes. Over MCP, any at all needs `force: true`.
|
|
298
|
+
*/
|
|
299
|
+
manualChanges: number;
|
|
300
|
+
/** What's left to do by hand for the project to work like the original. */
|
|
301
|
+
followUps: ProjectFileFollowUp[];
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/** Per-section changes. Names are tool names, document titles, `provider/model`, URLs… */
|
|
305
|
+
export interface ProjectFileSectionChanges {
|
|
306
|
+
/** False when the file leaves this section out; the project's own is kept. */
|
|
307
|
+
included: boolean;
|
|
308
|
+
created: string[];
|
|
309
|
+
updated: string[];
|
|
310
|
+
deleted: string[];
|
|
311
|
+
unchanged: number;
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
export interface ProjectFileImportSections {
|
|
315
|
+
config: ProjectFileConfigChanges;
|
|
316
|
+
prompts: ProjectFileSectionChanges;
|
|
317
|
+
personalities: ProjectFileSectionChanges;
|
|
318
|
+
tools: ProjectFileSectionChanges;
|
|
319
|
+
knowledgeBase: ProjectFileSectionChanges;
|
|
320
|
+
pricing: ProjectFileSectionChanges;
|
|
321
|
+
extensions: ProjectFileSectionChanges;
|
|
322
|
+
webSearchSites: ProjectFileSectionChanges;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
export interface ProjectFileConfigChanges {
|
|
326
|
+
included: boolean;
|
|
327
|
+
/** Settings whose value changes. */
|
|
328
|
+
changed: string[];
|
|
329
|
+
/** Settings the file has a different value for that stay as they are (MCP: Console-only settings). */
|
|
330
|
+
kept: string[];
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/** One thing to do after an import. */
|
|
334
|
+
export interface ProjectFileFollowUp {
|
|
335
|
+
kind: ProjectFileFollowUpKind;
|
|
336
|
+
/** What to do, in a sentence. */
|
|
337
|
+
message: string;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* - `provider_key` — the imported settings use a provider this project has no key for.
|
|
342
|
+
* - `tool_secret` — a tool header the file left out, which this project's tool didn't have either.
|
|
343
|
+
* - `webhook_secret` — the source signed tool calls; this project has no webhook secret.
|
|
344
|
+
* - `console_only` — MCP kept a setting a person sets in the Console.
|
|
345
|
+
* - `integration_scope` — the source's integration scope differs from this project's.
|
|
346
|
+
* - `web_search_sites` — sites that couldn't be synced with the search service.
|
|
347
|
+
*/
|
|
348
|
+
export type ProjectFileFollowUpKind =
|
|
349
|
+
| 'provider_key'
|
|
350
|
+
| 'tool_secret'
|
|
351
|
+
| 'webhook_secret'
|
|
352
|
+
| 'console_only'
|
|
353
|
+
| 'integration_scope'
|
|
354
|
+
| 'web_search_sites';
|