@ego-z/contracts 0.15.23 → 0.15.24
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/agents.d.ts +60 -12
- package/src/api-key.d.ts +4 -0
- package/src/ask.d.ts +33 -2
- package/src/index.d.ts +5 -0
- package/src/project-file.d.ts +26 -3
- package/src/stream.d.ts +9 -2
package/package.json
CHANGED
package/src/agents.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* @ego-z/contracts — sub-agents
|
|
2
|
+
* @ego-z/contracts — sub-agents.
|
|
3
3
|
*
|
|
4
4
|
* The main agent of a turn hands a task to a SUB-AGENT and keeps talking.
|
|
5
5
|
* The sub-agent runs in the background inside EgoZ, as its own turn on its
|
|
6
|
-
* own
|
|
7
|
-
* agent (a note on its conversation).
|
|
6
|
+
* own conversation, and its result comes back to you (a webhook) and to the
|
|
7
|
+
* main agent (a note on its conversation).
|
|
8
8
|
*
|
|
9
9
|
* ── The pieces ───────────────────────────────────────────────────────────
|
|
10
10
|
*
|
|
@@ -17,32 +17,68 @@
|
|
|
17
17
|
* - `AgentRunWebhookBody` — POSTed to the project's `agentWebhookUrl` when
|
|
18
18
|
* a run ends, signed like tool calls.
|
|
19
19
|
* - `AskRequestBody.agentCredential` — the credential the runs started in
|
|
20
|
-
* a turn
|
|
20
|
+
* a turn present on their tool calls.
|
|
21
|
+
*
|
|
22
|
+
* Routes (tenant API key, like `/ask`):
|
|
23
|
+
*
|
|
24
|
+
* - `GET /egoz/agent-runs/:runId` → `AgentRunWire`
|
|
25
|
+
* - `GET /egoz/agent-runs?threadId=…` → `AgentRunListResponseData`
|
|
26
|
+
* (or `?externalThreadId=…`)
|
|
27
|
+
* - `POST /egoz/agent-runs/:runId/cancel` → `AgentRunWire`
|
|
28
|
+
*
|
|
29
|
+
* Profiles: `/egoz/tenants/:tenantId/agent-profiles[/:profileId]` (Console)
|
|
30
|
+
* and `/egoz/mcp-admin/agent-profiles[/:profileId]` (MCP:
|
|
31
|
+
* `egoz_list/create/update/delete_agent_profile`). They also travel in the
|
|
32
|
+
* `.egoz` project file (`EgozProjectFile.agentProfiles`).
|
|
21
33
|
*
|
|
22
34
|
* ── Identity ─────────────────────────────────────────────────────────────
|
|
23
35
|
*
|
|
24
36
|
* A run acts for the project, never as the end user: nobody's session token
|
|
25
37
|
* is forwarded, since it may expire before the run ends and the run is not
|
|
26
|
-
* them. Instead your server mints a short-lived `agentCredential` per /ask
|
|
38
|
+
* them. Instead your server mints a short-lived `agentCredential` per /ask.
|
|
27
39
|
* EgoZ keeps it encrypted with each run that turn starts, never shows it to
|
|
28
|
-
* the model, and sends it as `Authorization
|
|
29
|
-
*
|
|
40
|
+
* the model, and sends it verbatim as `Authorization` on the run's tool calls
|
|
41
|
+
* (tools with `authType: 'FORWARD'`), next to EgoZ's usual signature
|
|
30
42
|
* (`X-EgoZ-Signature`, `X-EgoZ-Timestamp`) and:
|
|
31
43
|
*
|
|
32
44
|
* X-EgoZ-Actor: agent
|
|
33
45
|
* X-EgoZ-Run-Id: <runId>
|
|
34
46
|
* Idempotency-Key: <runId>:<hash of tool name + arguments>
|
|
35
47
|
*
|
|
48
|
+
* The run's tool calls also carry the headers the starting turn's tool calls
|
|
49
|
+
* carried (`AskRequestBody.toolHeaders`, and inbound headers a tool's
|
|
50
|
+
* `forwardHeaders` allows), except `Authorization`.
|
|
51
|
+
*
|
|
36
52
|
* Verify both the signature and your credential, and take the tenant from
|
|
37
53
|
* your credential — never from a header the model's arguments could shape.
|
|
38
54
|
* The idempotency key is the same for the same call within a run, so a
|
|
39
|
-
*
|
|
55
|
+
* restarted run doesn't write twice; a different call gets a different key.
|
|
40
56
|
*
|
|
41
57
|
* ── Limits ───────────────────────────────────────────────────────────────
|
|
42
58
|
*
|
|
43
59
|
* One level deep: a sub-agent can't start another. It can't ask the user
|
|
44
60
|
* (`ask_user`): it ends `needs_input` with its question instead, and the
|
|
45
61
|
* main agent asks. It stops at its token budget, round limit or timeout.
|
|
62
|
+
*
|
|
63
|
+
* A turn starts at most 3 runs. A project runs at most
|
|
64
|
+
* `agentMaxConcurrentRuns` at once (default 50), and one end user at most
|
|
65
|
+
* `agentMaxConcurrentRunsPerUser` (default 3) — the end user being the
|
|
66
|
+
* starting turn's `externalTenantId` when it had one, else its
|
|
67
|
+
* `externalUserId`, else its conversation. A run past either cap waits in
|
|
68
|
+
* the queue; it is never refused. Its timeout counts from when it was
|
|
69
|
+
* started, queue time included, so a run still waiting at `deadlineAt` ends
|
|
70
|
+
* `failed: timeout` without having run.
|
|
71
|
+
*
|
|
72
|
+
* ── The note on the main agent's conversation ───────────────────────────
|
|
73
|
+
*
|
|
74
|
+
* When a run ends, EgoZ adds a short note to the conversation that started
|
|
75
|
+
* it, so the main agent's next turn knows — e.g.
|
|
76
|
+
* `[translator finished. It reported: «…»]`, `[translator failed: budget]`,
|
|
77
|
+
* `[translator needs your input: «…» — ask the user]`. The reported text is
|
|
78
|
+
* cut to 500 characters and quoted as data, never as instructions: a
|
|
79
|
+
* sub-agent may have read pages written by anyone. The full result is on the
|
|
80
|
+
* run. EgoZ starts no turn by itself: to have the main agent tell the user
|
|
81
|
+
* unprompted, send the next /ask yourself when the webhook arrives.
|
|
46
82
|
*/
|
|
47
83
|
|
|
48
84
|
import type { TokenUsage } from './envelope';
|
|
@@ -77,7 +113,7 @@ export interface AgentProfileWire {
|
|
|
77
113
|
maxTokens: number;
|
|
78
114
|
/** Most tool rounds one run may take: 1–30. Default 10. */
|
|
79
115
|
maxRounds: number;
|
|
80
|
-
/** Wall-clock limit for one run, in seconds: 30–3,600. Default 600. */
|
|
116
|
+
/** Wall-clock limit for one run, in seconds, counted from when it was started: 30–3,600. Default 600. */
|
|
81
117
|
timeoutSeconds: number;
|
|
82
118
|
/** A disabled profile is not offered to the main agent; its runs already started finish. */
|
|
83
119
|
enabled: boolean;
|
|
@@ -101,6 +137,11 @@ export interface AgentProfileCreateBody {
|
|
|
101
137
|
/** Only the fields you send change. */
|
|
102
138
|
export type AgentProfileUpdateBody = Partial<AgentProfileCreateBody>;
|
|
103
139
|
|
|
140
|
+
/** `data` of the profile list routes. */
|
|
141
|
+
export interface AgentProfileListResponseData {
|
|
142
|
+
profiles: AgentProfileWire[];
|
|
143
|
+
}
|
|
144
|
+
|
|
104
145
|
// ============================================================================
|
|
105
146
|
// start_agent (model-facing)
|
|
106
147
|
// ============================================================================
|
|
@@ -124,7 +165,11 @@ export interface AgentRunStarted {
|
|
|
124
165
|
runId: string;
|
|
125
166
|
agent: string;
|
|
126
167
|
status: 'queued';
|
|
127
|
-
/**
|
|
168
|
+
/**
|
|
169
|
+
* ISO 8601 — the run has ended by then: it was started now, and its
|
|
170
|
+
* timeout counts queue time. If no webhook has come a little after it,
|
|
171
|
+
* treat the run as failed.
|
|
172
|
+
*/
|
|
128
173
|
deadlineAt: string;
|
|
129
174
|
}
|
|
130
175
|
|
|
@@ -137,7 +182,7 @@ export type AgentRunStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancell
|
|
|
137
182
|
export type AgentRunErrorCode =
|
|
138
183
|
/** It hit its token budget or round limit. */
|
|
139
184
|
| 'budget'
|
|
140
|
-
/** It
|
|
185
|
+
/** It reached `deadlineAt` — running, or still waiting in the queue. */
|
|
141
186
|
| 'timeout'
|
|
142
187
|
/** The model call failed (provider error, missing key). */
|
|
143
188
|
| 'model_error'
|
|
@@ -163,6 +208,8 @@ export interface AgentRunWire {
|
|
|
163
208
|
externalThreadId?: string;
|
|
164
209
|
/** Echo of that turn's `externalUserId`, when it had one. */
|
|
165
210
|
externalUserId?: string;
|
|
211
|
+
/** Echo of that turn's `externalTenantId`, when it had one. */
|
|
212
|
+
externalTenantId?: string;
|
|
166
213
|
/** The run's own conversation (its messages), once it has started. */
|
|
167
214
|
childThreadId: string | null;
|
|
168
215
|
/** Set when `status` is `done`. */
|
|
@@ -182,10 +229,11 @@ export interface AgentRunWire {
|
|
|
182
229
|
createdAt: string;
|
|
183
230
|
startedAt: string | null;
|
|
184
231
|
finishedAt: string | null;
|
|
232
|
+
/** `createdAt` + the profile's `timeoutSeconds`. */
|
|
185
233
|
deadlineAt: string;
|
|
186
234
|
}
|
|
187
235
|
|
|
188
|
-
/** `GET /egoz/agent-runs?threadId=…` — the runs a conversation's turns started, newest first. */
|
|
236
|
+
/** `GET /egoz/agent-runs?threadId=…` — the runs a conversation's turns started, newest first (at most 50). */
|
|
189
237
|
export interface AgentRunListResponseData {
|
|
190
238
|
runs: AgentRunWire[];
|
|
191
239
|
}
|
package/src/api-key.d.ts
CHANGED
|
@@ -30,6 +30,9 @@
|
|
|
30
30
|
* - `'tools:read'` — read tool definitions.
|
|
31
31
|
* - `'tools:write'` — create / update / delete tools.
|
|
32
32
|
* - `'threads:read'` — read conversation threads.
|
|
33
|
+
* - `'images:read'` — read the images the project made, by id
|
|
34
|
+
* (`GET /egoz/assets/:assetId`), and nothing else: for
|
|
35
|
+
* a service that only takes images into its own store.
|
|
33
36
|
* - `'admin'` — full access (implies every scope above).
|
|
34
37
|
*/
|
|
35
38
|
export type ApiKeyScope =
|
|
@@ -39,6 +42,7 @@ export type ApiKeyScope =
|
|
|
39
42
|
| 'tools:read'
|
|
40
43
|
| 'tools:write'
|
|
41
44
|
| 'threads:read'
|
|
45
|
+
| 'images:read'
|
|
42
46
|
| 'admin';
|
|
43
47
|
|
|
44
48
|
// ============================================================================
|
package/src/ask.d.ts
CHANGED
|
@@ -9,6 +9,7 @@ import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from '.
|
|
|
9
9
|
import type { InitContextItem, InitContextItemAccepted, InitContextTenant, InitContextUi } from './draft-conv';
|
|
10
10
|
import type { AskQuestionSet } from './questions';
|
|
11
11
|
import type { GeneratedImage } from './images';
|
|
12
|
+
import type { AgentRunStarted } from './agents';
|
|
12
13
|
|
|
13
14
|
// ============================================================================
|
|
14
15
|
// /ask — request
|
|
@@ -232,6 +233,28 @@ export interface AskRequestBody {
|
|
|
232
233
|
*/
|
|
233
234
|
toolHeaders?: Record<string, string>;
|
|
234
235
|
|
|
236
|
+
/**
|
|
237
|
+
* The credential the sub-agent runs started in this turn present on their
|
|
238
|
+
* tool calls (the built-in `start_agent` — see `agents.d.ts`). A run works
|
|
239
|
+
* in the background after this request has ended, so it can't forward the
|
|
240
|
+
* caller's `Authorization`: that token may expire first, and the run acts
|
|
241
|
+
* for the project, not as the user.
|
|
242
|
+
*
|
|
243
|
+
* Mint a short-lived credential on your server that names who the run
|
|
244
|
+
* acts for (your tenant, project, conversation), and send it here. It is
|
|
245
|
+
* the whole `Authorization` value, scheme included — `Bearer <token>`, or
|
|
246
|
+
* a scheme of your own such as `AppDelegation <token>` — at most 4 KB.
|
|
247
|
+
*
|
|
248
|
+
* EgoZ never shows it to the model and never puts it in a trace, a
|
|
249
|
+
* webhook or a response. It is stored encrypted with each run this turn
|
|
250
|
+
* starts, and sent as `Authorization` on that run's `authType: 'FORWARD'`
|
|
251
|
+
* tool calls, beside EgoZ's signature. Make it outlive the runs: a run
|
|
252
|
+
* ends by its `deadlineAt`, at most an hour after it was started.
|
|
253
|
+
* Without it, a run's FORWARD tool calls go out with no `Authorization`.
|
|
254
|
+
* Ignored on turns that start no run.
|
|
255
|
+
*/
|
|
256
|
+
agentCredential?: string;
|
|
257
|
+
|
|
235
258
|
/**
|
|
236
259
|
* The ONLY tools this turn may be offered, by name.
|
|
237
260
|
*
|
|
@@ -688,6 +711,8 @@ export interface AskResponseData {
|
|
|
688
711
|
* `memoryProposed` = the agent proposed at least one new PENDING fact via
|
|
689
712
|
* `remember_fact` this turn. Additive — older consumers ignore them.
|
|
690
713
|
*/
|
|
714
|
+
memoryInjected?: boolean;
|
|
715
|
+
memoryProposed?: boolean;
|
|
691
716
|
/**
|
|
692
717
|
* Images the agent made this turn with the built-in `generate_image` tool
|
|
693
718
|
* (project setting `imageGenerationEnabled`). Present only when it made
|
|
@@ -695,8 +720,14 @@ export interface AskResponseData {
|
|
|
695
720
|
* bytes yourself before `expiresAt` — see `images.d.ts`.
|
|
696
721
|
*/
|
|
697
722
|
images?: GeneratedImage[];
|
|
698
|
-
|
|
699
|
-
|
|
723
|
+
/**
|
|
724
|
+
* The sub-agent runs this turn started with the built-in `start_agent`
|
|
725
|
+
* tool, in the order it started them. Present only when it started at
|
|
726
|
+
* least one. Each is also on that call's `tool.result` as `display`, the
|
|
727
|
+
* moment it starts. A run ends after this response, and you hear of its
|
|
728
|
+
* end on the project's agent webhook — see `agents.d.ts`.
|
|
729
|
+
*/
|
|
730
|
+
agentRuns?: AgentRunStarted[];
|
|
700
731
|
/**
|
|
701
732
|
* What EgoZ actually accepted from `AskRequestBody.contextItems` this
|
|
702
733
|
* turn, in the order the agent saw them.
|
package/src/index.d.ts
CHANGED
|
@@ -91,6 +91,10 @@
|
|
|
91
91
|
* `POST /egoz/images`, `GET /egoz/assets/:assetId`,
|
|
92
92
|
* `AskResponseData.images` and the `done` event),
|
|
93
93
|
* `GenerateImageRequestBody`, `GenerateImageResponseData`.
|
|
94
|
+
* - `agents.d.ts` — sub-agents: `AgentProfileWire` and its bodies,
|
|
95
|
+
* `StartAgentToolInput`, `AgentRunStarted` (on
|
|
96
|
+
* `AskResponseData.agentRuns` and the `done` event),
|
|
97
|
+
* `AgentRunWire`, `AgentRunWebhookBody`.
|
|
94
98
|
*
|
|
95
99
|
* This barrel re-exports everything so existing consumers' import paths
|
|
96
100
|
* (`import type { AskResponseData } from '@ego-z/contracts'`) keep
|
|
@@ -122,3 +126,4 @@ export * from './search';
|
|
|
122
126
|
export * from './controlled';
|
|
123
127
|
export * from './project-file';
|
|
124
128
|
export * from './images';
|
|
129
|
+
export * from './agents';
|
package/src/project-file.d.ts
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* - `POST /egoz/mcp-admin/project-file/import` (same, plus `force`)
|
|
10
10
|
*
|
|
11
11
|
* A `.egoz` file is everything an owner built in a project — settings,
|
|
12
|
-
* prompts, personalities, tools, knowledge base, prices, extensions
|
|
13
|
-
* search sites — as JSON. Importing it into another project makes that
|
|
12
|
+
* prompts, personalities, tools, knowledge base, prices, extensions, web
|
|
13
|
+
* search sites and sub-agent profiles — as JSON. Importing it into another project makes that
|
|
14
14
|
* project's build match the file, one to one.
|
|
15
15
|
*
|
|
16
16
|
* ── What a file never holds ──────────────────────────────────────────────
|
|
@@ -76,6 +76,8 @@ export interface EgozProjectFile {
|
|
|
76
76
|
extensions?: ProjectFileExtension[];
|
|
77
77
|
/** The sites `web_search` answers from when `config.webSearchScope` is `"whitelist"`. */
|
|
78
78
|
webSearchSites?: string[];
|
|
79
|
+
/** Sub-agent profiles, by `name`. */
|
|
80
|
+
agentProfiles?: ProjectFileAgentProfile[];
|
|
79
81
|
}
|
|
80
82
|
|
|
81
83
|
/** Where a file came from. Import never writes any of it. */
|
|
@@ -113,7 +115,7 @@ export interface ProjectFileModelRef {
|
|
|
113
115
|
* project that never picked a model keeps following the default after import.
|
|
114
116
|
*
|
|
115
117
|
* Over MCP, an import leaves `llmProviderEndpoint`, `llmProviderApiVersion`,
|
|
116
|
-
* `embeddingProviderEndpoint` and `
|
|
118
|
+
* `embeddingProviderEndpoint`, `authCallbackUrl` and `agentWebhookUrl` as the project has them
|
|
117
119
|
* (a person sets those in the Console), and refuses a file whose
|
|
118
120
|
* `llmProvider` or `embeddingProvider` differs from the project's.
|
|
119
121
|
*/
|
|
@@ -167,6 +169,13 @@ export interface ProjectFileConfig {
|
|
|
167
169
|
/** `generate_image` calls one answer may make, 1..4. Default 2. */
|
|
168
170
|
imageMaxCallsPerTurn: number;
|
|
169
171
|
|
|
172
|
+
/** Where EgoZ POSTs `agent_run.finished` when a sub-agent run ends. `null` = no webhook. */
|
|
173
|
+
agentWebhookUrl: string | null;
|
|
174
|
+
/** Sub-agent runs the project runs at once, 1..500. Default 50. More wait in the queue. */
|
|
175
|
+
agentMaxConcurrentRuns: number;
|
|
176
|
+
/** Sub-agent runs one end user runs at once, 1..50. Default 3. More wait in the queue. */
|
|
177
|
+
agentMaxConcurrentRunsPerUser: number;
|
|
178
|
+
|
|
170
179
|
voiceEnabled: boolean;
|
|
171
180
|
voiceModel: string | null;
|
|
172
181
|
voiceTtsVoice: string | null;
|
|
@@ -247,6 +256,19 @@ export interface ProjectFilePricing {
|
|
|
247
256
|
completionPerM: number;
|
|
248
257
|
}
|
|
249
258
|
|
|
259
|
+
/** A sub-agent profile (see `AgentProfileWire`). Matched by `name` on import. */
|
|
260
|
+
export interface ProjectFileAgentProfile {
|
|
261
|
+
name: string;
|
|
262
|
+
description: string;
|
|
263
|
+
prompt: string;
|
|
264
|
+
model: string | null;
|
|
265
|
+
tools: string[];
|
|
266
|
+
maxTokens: number;
|
|
267
|
+
maxRounds: number;
|
|
268
|
+
timeoutSeconds: number;
|
|
269
|
+
enabled: boolean;
|
|
270
|
+
}
|
|
271
|
+
|
|
250
272
|
/**
|
|
251
273
|
* An extension's state. `config` is what the project set, without the
|
|
252
274
|
* extension's defaults, so a later change to a default still applies.
|
|
@@ -327,6 +349,7 @@ export interface ProjectFileImportSections {
|
|
|
327
349
|
pricing: ProjectFileSectionChanges;
|
|
328
350
|
extensions: ProjectFileSectionChanges;
|
|
329
351
|
webSearchSites: ProjectFileSectionChanges;
|
|
352
|
+
agentProfiles: ProjectFileSectionChanges;
|
|
330
353
|
}
|
|
331
354
|
|
|
332
355
|
export interface ProjectFileConfigChanges {
|
package/src/stream.d.ts
CHANGED
|
@@ -15,6 +15,7 @@ import type { AskRouting } from './ask';
|
|
|
15
15
|
import type { Intent, TokenUsage } from './envelope';
|
|
16
16
|
import type { AskQuestionSet } from './questions';
|
|
17
17
|
import type { GeneratedImage } from './images';
|
|
18
|
+
import type { AgentRunStarted } from './agents';
|
|
18
19
|
import type { InitContextItemAccepted } from './draft-conv';
|
|
19
20
|
|
|
20
21
|
/**
|
|
@@ -364,13 +365,19 @@ export interface AskStreamDoneEvent {
|
|
|
364
365
|
* terminal event so streaming consumers get the signal without parsing the
|
|
365
366
|
* final payload. Present only when learning was active this turn.
|
|
366
367
|
*/
|
|
368
|
+
memoryInjected?: boolean;
|
|
369
|
+
memoryProposed?: boolean;
|
|
367
370
|
/**
|
|
368
371
|
* Images the agent made this turn. Same semantics as
|
|
369
372
|
* `AskResponseData.images`; present only when it made at least one.
|
|
370
373
|
*/
|
|
371
374
|
images?: GeneratedImage[];
|
|
372
|
-
|
|
373
|
-
|
|
375
|
+
/**
|
|
376
|
+
* The sub-agent runs this turn started. Same semantics as
|
|
377
|
+
* `AskResponseData.agentRuns`; present only when it started at least one.
|
|
378
|
+
* Each was already on its `start_agent` call's `tool.result` as `display`.
|
|
379
|
+
*/
|
|
380
|
+
agentRuns?: AgentRunStarted[];
|
|
374
381
|
/**
|
|
375
382
|
* What EgoZ accepted from this turn's `contextItems`. Same semantics +
|
|
376
383
|
* shape as `AskResponseData.contextItemsAccepted` — surfaced on the
|