@ego-z/contracts 0.15.18 → 0.15.20

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ego-z/contracts",
3
- "version": "0.15.18",
3
+ "version": "0.15.20",
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
@@ -530,8 +530,9 @@ export type AutoTier = 'light' | 'default' | 'heavy';
530
530
  */
531
531
  export interface AskRouting {
532
532
  /**
533
- * The tier Auto picked. A conversation keeps the highest tier it has
534
- * reached, so a later turn never gets a lower one.
533
+ * The tier Auto picked. A conversation keeps the highest tier Auto has
534
+ * judged it at, so a later turn never gets a lower one — except after a
535
+ * `fallback`, which the conversation doesn't keep.
535
536
  */
536
537
  tier: AutoTier;
537
538
  /**
@@ -540,7 +541,8 @@ export interface AskRouting {
540
541
  * - `sticky`: the conversation was already at a higher tier, and the turn
541
542
  * kept it (at `heavy`, Auto stops judging);
542
543
  * - `fallback`: Auto couldn't judge this turn in time, so it ran at
543
- * `default`.
544
+ * `default`. The conversation keeps its tier, so the next turn can get
545
+ * a lower one.
544
546
  */
545
547
  source: 'classifier' | 'sticky' | 'fallback';
546
548
  /**
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';