@ego-z/contracts 0.15.22 → 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 +261 -0
- package/src/api-key.d.ts +4 -0
- package/src/ask.d.ts +39 -0
- package/src/images.d.ts +95 -0
- package/src/index.d.ts +11 -0
- package/src/project-file.d.ts +33 -3
- package/src/stream.d.ts +13 -0
package/package.json
CHANGED
package/src/agents.d.ts
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ego-z/contracts — sub-agents.
|
|
3
|
+
*
|
|
4
|
+
* The main agent of a turn hands a task to a SUB-AGENT and keeps talking.
|
|
5
|
+
* The sub-agent runs in the background inside EgoZ, as its own turn on its
|
|
6
|
+
* own conversation, and its result comes back to you (a webhook) and to the
|
|
7
|
+
* main agent (a note on its conversation).
|
|
8
|
+
*
|
|
9
|
+
* ── The pieces ───────────────────────────────────────────────────────────
|
|
10
|
+
*
|
|
11
|
+
* - `AgentProfileWire` — a sub-agent the project defines (Console / MCP):
|
|
12
|
+
* what it's for, its prompt, model, tools, budget.
|
|
13
|
+
* - `start_agent` — the built-in tool the main agent calls. Offered
|
|
14
|
+
* when the project has at least one enabled
|
|
15
|
+
* profile; `StartAgentToolInput` is what it sends.
|
|
16
|
+
* - `AgentRunWire` — one run: status, result, error, usage.
|
|
17
|
+
* - `AgentRunWebhookBody` — POSTed to the project's `agentWebhookUrl` when
|
|
18
|
+
* a run ends, signed like tool calls.
|
|
19
|
+
* - `AskRequestBody.agentCredential` — the credential the runs started in
|
|
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`).
|
|
33
|
+
*
|
|
34
|
+
* ── Identity ─────────────────────────────────────────────────────────────
|
|
35
|
+
*
|
|
36
|
+
* A run acts for the project, never as the end user: nobody's session token
|
|
37
|
+
* is forwarded, since it may expire before the run ends and the run is not
|
|
38
|
+
* them. Instead your server mints a short-lived `agentCredential` per /ask.
|
|
39
|
+
* EgoZ keeps it encrypted with each run that turn starts, never shows it to
|
|
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
|
|
42
|
+
* (`X-EgoZ-Signature`, `X-EgoZ-Timestamp`) and:
|
|
43
|
+
*
|
|
44
|
+
* X-EgoZ-Actor: agent
|
|
45
|
+
* X-EgoZ-Run-Id: <runId>
|
|
46
|
+
* Idempotency-Key: <runId>:<hash of tool name + arguments>
|
|
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
|
+
*
|
|
52
|
+
* Verify both the signature and your credential, and take the tenant from
|
|
53
|
+
* your credential — never from a header the model's arguments could shape.
|
|
54
|
+
* The idempotency key is the same for the same call within a run, so a
|
|
55
|
+
* restarted run doesn't write twice; a different call gets a different key.
|
|
56
|
+
*
|
|
57
|
+
* ── Limits ───────────────────────────────────────────────────────────────
|
|
58
|
+
*
|
|
59
|
+
* One level deep: a sub-agent can't start another. It can't ask the user
|
|
60
|
+
* (`ask_user`): it ends `needs_input` with its question instead, and the
|
|
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.
|
|
82
|
+
*/
|
|
83
|
+
|
|
84
|
+
import type { TokenUsage } from './envelope';
|
|
85
|
+
import type { GeneratedImage } from './images';
|
|
86
|
+
|
|
87
|
+
// ============================================================================
|
|
88
|
+
// Profiles
|
|
89
|
+
// ============================================================================
|
|
90
|
+
|
|
91
|
+
/** A sub-agent profile, as the profile routes return it. */
|
|
92
|
+
export interface AgentProfileWire {
|
|
93
|
+
id: string;
|
|
94
|
+
/**
|
|
95
|
+
* The handle the main agent picks it by, unique per project:
|
|
96
|
+
* lowercase letters, digits, `_` and `-`, 2–40 characters (e.g. `translator`).
|
|
97
|
+
*/
|
|
98
|
+
name: string;
|
|
99
|
+
/** What it's for, in a sentence or two. The main agent reads this to decide when to use it (≤ 500 characters). */
|
|
100
|
+
description: string;
|
|
101
|
+
/** Its system prompt (≤ 20,000 characters). */
|
|
102
|
+
prompt: string;
|
|
103
|
+
/** The chat model it runs on. `null` = the project's default model. */
|
|
104
|
+
model: string | null;
|
|
105
|
+
/**
|
|
106
|
+
* The tools it may call, by name: the project's own tools and the
|
|
107
|
+
* built-ins `search_knowledge_base`, `web_search`, `web_fetch`,
|
|
108
|
+
* `generate_image`. Never `start_agent` or `ask_user`. A tool the project
|
|
109
|
+
* turns off later is simply not offered.
|
|
110
|
+
*/
|
|
111
|
+
tools: string[];
|
|
112
|
+
/** Most tokens (in + out, every round) one run may spend: 1,000–2,000,000. Default 200,000. */
|
|
113
|
+
maxTokens: number;
|
|
114
|
+
/** Most tool rounds one run may take: 1–30. Default 10. */
|
|
115
|
+
maxRounds: number;
|
|
116
|
+
/** Wall-clock limit for one run, in seconds, counted from when it was started: 30–3,600. Default 600. */
|
|
117
|
+
timeoutSeconds: number;
|
|
118
|
+
/** A disabled profile is not offered to the main agent; its runs already started finish. */
|
|
119
|
+
enabled: boolean;
|
|
120
|
+
source: 'manual' | 'mcp';
|
|
121
|
+
createdAt: string;
|
|
122
|
+
updatedAt: string;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export interface AgentProfileCreateBody {
|
|
126
|
+
name: string;
|
|
127
|
+
description: string;
|
|
128
|
+
prompt: string;
|
|
129
|
+
model?: string | null;
|
|
130
|
+
tools?: string[];
|
|
131
|
+
maxTokens?: number;
|
|
132
|
+
maxRounds?: number;
|
|
133
|
+
timeoutSeconds?: number;
|
|
134
|
+
enabled?: boolean;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** Only the fields you send change. */
|
|
138
|
+
export type AgentProfileUpdateBody = Partial<AgentProfileCreateBody>;
|
|
139
|
+
|
|
140
|
+
/** `data` of the profile list routes. */
|
|
141
|
+
export interface AgentProfileListResponseData {
|
|
142
|
+
profiles: AgentProfileWire[];
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// ============================================================================
|
|
146
|
+
// start_agent (model-facing)
|
|
147
|
+
// ============================================================================
|
|
148
|
+
|
|
149
|
+
/** What the main agent sends `start_agent`. */
|
|
150
|
+
export interface StartAgentToolInput {
|
|
151
|
+
/** A profile `name`. */
|
|
152
|
+
agent: string;
|
|
153
|
+
/** The task in plain words, complete enough to do without the conversation (≤ 4,000 characters). */
|
|
154
|
+
task: string;
|
|
155
|
+
/** Facts the task needs (ids, languages, …) — at most 16 KB as JSON. */
|
|
156
|
+
input?: Record<string, unknown>;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* What a turn reports for each run it started: `display` on the
|
|
161
|
+
* `start_agent` call's `tool.result`, and `agentRuns` on the `done` event and
|
|
162
|
+
* the /ask response. Lets you show the run the moment it starts.
|
|
163
|
+
*/
|
|
164
|
+
export interface AgentRunStarted {
|
|
165
|
+
runId: string;
|
|
166
|
+
agent: string;
|
|
167
|
+
status: 'queued';
|
|
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
|
+
*/
|
|
173
|
+
deadlineAt: string;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// ============================================================================
|
|
177
|
+
// Runs
|
|
178
|
+
// ============================================================================
|
|
179
|
+
|
|
180
|
+
export type AgentRunStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancelled' | 'needs_input';
|
|
181
|
+
|
|
182
|
+
export type AgentRunErrorCode =
|
|
183
|
+
/** It hit its token budget or round limit. */
|
|
184
|
+
| 'budget'
|
|
185
|
+
/** It reached `deadlineAt` — running, or still waiting in the queue. */
|
|
186
|
+
| 'timeout'
|
|
187
|
+
/** The model call failed (provider error, missing key). */
|
|
188
|
+
| 'model_error'
|
|
189
|
+
/** A tool it relied on failed and it could not finish without it. */
|
|
190
|
+
| 'tool_failed'
|
|
191
|
+
/** EgoZ failed (e.g. the run was lost twice). */
|
|
192
|
+
| 'internal';
|
|
193
|
+
|
|
194
|
+
/** One run, as `GET /egoz/agent-runs/:runId` and the webhook return it. */
|
|
195
|
+
export interface AgentRunWire {
|
|
196
|
+
runId: string;
|
|
197
|
+
/** The profile's `name` at start. */
|
|
198
|
+
agent: string;
|
|
199
|
+
profileId: string;
|
|
200
|
+
status: AgentRunStatus;
|
|
201
|
+
/** The task the main agent gave. `null` on a no-store project or turn. */
|
|
202
|
+
task: string | null;
|
|
203
|
+
/** `null` on no-store. */
|
|
204
|
+
input: Record<string, unknown> | null;
|
|
205
|
+
/** The conversation whose turn started it. */
|
|
206
|
+
parentThreadId: string;
|
|
207
|
+
/** Echo of that turn's `externalThreadId`, when it had one. */
|
|
208
|
+
externalThreadId?: string;
|
|
209
|
+
/** Echo of that turn's `externalUserId`, when it had one. */
|
|
210
|
+
externalUserId?: string;
|
|
211
|
+
/** Echo of that turn's `externalTenantId`, when it had one. */
|
|
212
|
+
externalTenantId?: string;
|
|
213
|
+
/** The run's own conversation (its messages), once it has started. */
|
|
214
|
+
childThreadId: string | null;
|
|
215
|
+
/** Set when `status` is `done`. */
|
|
216
|
+
result: {
|
|
217
|
+
/** Its final answer. `null` on no-store. */
|
|
218
|
+
text: string | null;
|
|
219
|
+
/** Images it made with `generate_image` — take them before they expire. */
|
|
220
|
+
images?: GeneratedImage[];
|
|
221
|
+
} | null;
|
|
222
|
+
/** Set when `status` is `failed`. The message is EgoZ's, never a tool's or the provider's raw text. */
|
|
223
|
+
error: { code: AgentRunErrorCode; message: string } | null;
|
|
224
|
+
/** Set when `status` is `needs_input`: what it needs to know. The main agent asks the user. */
|
|
225
|
+
needsInput: { question: string } | null;
|
|
226
|
+
usage: TokenUsage;
|
|
227
|
+
/** 1, or 2 when EgoZ restarted a run it lost (a worker died mid-run). */
|
|
228
|
+
attempts: number;
|
|
229
|
+
createdAt: string;
|
|
230
|
+
startedAt: string | null;
|
|
231
|
+
finishedAt: string | null;
|
|
232
|
+
/** `createdAt` + the profile's `timeoutSeconds`. */
|
|
233
|
+
deadlineAt: string;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** `GET /egoz/agent-runs?threadId=…` — the runs a conversation's turns started, newest first (at most 50). */
|
|
237
|
+
export interface AgentRunListResponseData {
|
|
238
|
+
runs: AgentRunWire[];
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// ============================================================================
|
|
242
|
+
// Webhook
|
|
243
|
+
// ============================================================================
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* POSTed to the project's `agentWebhookUrl` when a run ends (`done`,
|
|
247
|
+
* `failed`, `cancelled`, `needs_input`). Signed with the project's webhook
|
|
248
|
+
* secret like tool calls — check it with `@ego-z/client`'s
|
|
249
|
+
* `verifySignature` (signature + timestamp window) before you act on it.
|
|
250
|
+
*
|
|
251
|
+
* Retried with backoff for up to an hour while your server doesn't answer
|
|
252
|
+
* 2xx. `eventId` is the same on every retry: make your handler idempotent on it
|
|
253
|
+
* (or on `run.runId` + `run.status`).
|
|
254
|
+
*/
|
|
255
|
+
export interface AgentRunWebhookBody {
|
|
256
|
+
type: 'agent_run.finished';
|
|
257
|
+
eventId: string;
|
|
258
|
+
/** ISO 8601. */
|
|
259
|
+
occurredAt: string;
|
|
260
|
+
run: AgentRunWire;
|
|
261
|
+
}
|
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
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
|
|
9
9
|
import type { InitContextItem, InitContextItemAccepted, InitContextTenant, InitContextUi } from './draft-conv';
|
|
10
10
|
import type { AskQuestionSet } from './questions';
|
|
11
|
+
import type { GeneratedImage } from './images';
|
|
12
|
+
import type { AgentRunStarted } from './agents';
|
|
11
13
|
|
|
12
14
|
// ============================================================================
|
|
13
15
|
// /ask — request
|
|
@@ -231,6 +233,28 @@ export interface AskRequestBody {
|
|
|
231
233
|
*/
|
|
232
234
|
toolHeaders?: Record<string, string>;
|
|
233
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
|
+
|
|
234
258
|
/**
|
|
235
259
|
* The ONLY tools this turn may be offered, by name.
|
|
236
260
|
*
|
|
@@ -689,6 +713,21 @@ export interface AskResponseData {
|
|
|
689
713
|
*/
|
|
690
714
|
memoryInjected?: boolean;
|
|
691
715
|
memoryProposed?: boolean;
|
|
716
|
+
/**
|
|
717
|
+
* Images the agent made this turn with the built-in `generate_image` tool
|
|
718
|
+
* (project setting `imageGenerationEnabled`). Present only when it made
|
|
719
|
+
* at least one. EgoZ keeps each for 7 days: fetch `url` and store the
|
|
720
|
+
* bytes yourself before `expiresAt` — see `images.d.ts`.
|
|
721
|
+
*/
|
|
722
|
+
images?: GeneratedImage[];
|
|
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[];
|
|
692
731
|
/**
|
|
693
732
|
* What EgoZ actually accepted from `AskRequestBody.contextItems` this
|
|
694
733
|
* turn, in the order the agent saw them.
|
package/src/images.d.ts
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ego-z/contracts — images EgoZ makes.
|
|
3
|
+
*
|
|
4
|
+
* Two ways in, one result shape:
|
|
5
|
+
* - `POST /egoz/images` (tenant API key, like `/ask`) — `GenerateImageRequestBody`
|
|
6
|
+
* → `GenerateImageResponseData`.
|
|
7
|
+
* - The built-in `generate_image` tool inside a turn — each image it made is
|
|
8
|
+
* listed on `AskResponseData.images` and on the stream's `done` event, and
|
|
9
|
+
* carried as `display` on that call's `tool.result`.
|
|
10
|
+
*
|
|
11
|
+
* ── EgoZ keeps the image short-term ──────────────────────────────────────
|
|
12
|
+
*
|
|
13
|
+
* EgoZ holds the bytes for 7 days, then deletes them. Taking the image into
|
|
14
|
+
* your own storage is your job: fetch `url` (signed — no API key needed) and
|
|
15
|
+
* store the bytes before `expiresAt`. Don't put `url` anywhere that has to
|
|
16
|
+
* last, such as a published web page. `GET /egoz/assets/:assetId` re-reads an
|
|
17
|
+
* image's details and a fresh link while it is still kept.
|
|
18
|
+
*
|
|
19
|
+
* Every image follows the same fixed rules, whatever the prompt says: no
|
|
20
|
+
* text, letters, logos, watermarks, brand names or identifiable people. That
|
|
21
|
+
* keeps an image made for one project reusable by others.
|
|
22
|
+
*
|
|
23
|
+
* The project must turn image generation on (`imageGenerationEnabled`), and
|
|
24
|
+
* its plan has a monthly image allowance. Images are made with the project's
|
|
25
|
+
* own provider key: the chat provider's when it makes images (OpenAI, Azure
|
|
26
|
+
* OpenAI), else the project's OpenAI key.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
/** An image EgoZ made, as `POST /egoz/images`, `GET /egoz/assets/:assetId` and a turn return it. */
|
|
30
|
+
export interface GeneratedImage {
|
|
31
|
+
/** Stable id. `GET /egoz/assets/:assetId` reads it again. */
|
|
32
|
+
assetId: string;
|
|
33
|
+
kind: 'image';
|
|
34
|
+
mimeType: 'image/webp' | 'image/png' | 'image/jpeg';
|
|
35
|
+
byteSize: number;
|
|
36
|
+
/** SHA-256 of the bytes, hex — lets you check what you stored, or skip a duplicate. */
|
|
37
|
+
sha256: string;
|
|
38
|
+
/** Pixel size as `WIDTHxHEIGHT`, when the provider reported it. */
|
|
39
|
+
size: string | null;
|
|
40
|
+
/** The image model that made it. */
|
|
41
|
+
model: string;
|
|
42
|
+
/** The alt text you sent, if any. */
|
|
43
|
+
alt: string | null;
|
|
44
|
+
/** The tags you sent, lower-cased. */
|
|
45
|
+
tags: string[];
|
|
46
|
+
/**
|
|
47
|
+
* The prompt EgoZ sent the image model: yours, then EgoZ's fixed rules.
|
|
48
|
+
* `null` on a no-store project or turn.
|
|
49
|
+
*/
|
|
50
|
+
prompt: string | null;
|
|
51
|
+
/** The prompt as the image model rewrote it, when it did. `null` on no-store. */
|
|
52
|
+
revisedPrompt: string | null;
|
|
53
|
+
/** ISO 8601. */
|
|
54
|
+
createdAt: string;
|
|
55
|
+
/** ISO 8601 — when EgoZ deletes the bytes and `url` stops working. */
|
|
56
|
+
expiresAt: string;
|
|
57
|
+
/**
|
|
58
|
+
* Where to fetch the image. Signed: no API key needed. Works until
|
|
59
|
+
* `expiresAt`; `null` once the bytes are gone.
|
|
60
|
+
*/
|
|
61
|
+
url: string | null;
|
|
62
|
+
/** True once EgoZ has deleted the bytes. */
|
|
63
|
+
purged: boolean;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Body of `POST /egoz/images`. */
|
|
67
|
+
export interface GenerateImageRequestBody {
|
|
68
|
+
/** What the image shows, in plain words (1–4000 characters). */
|
|
69
|
+
prompt: string;
|
|
70
|
+
/** `square` (default, 1024×1024), `landscape` (1536×1024), `portrait` (1024×1536), or `auto`. */
|
|
71
|
+
shape?: 'square' | 'landscape' | 'portrait' | 'auto';
|
|
72
|
+
/** Higher costs more. Omitted: the model's own default. */
|
|
73
|
+
quality?: 'low' | 'medium' | 'high' | 'auto';
|
|
74
|
+
/** `transparent` needs `format` `webp` or `png`. */
|
|
75
|
+
background?: 'transparent' | 'opaque' | 'auto';
|
|
76
|
+
/** Default `webp`. Ignored by dall-e models, which make png. */
|
|
77
|
+
format?: 'webp' | 'png' | 'jpeg';
|
|
78
|
+
/** How many images, 1–4 (default 1). Each is billed by your provider and counts toward the monthly allowance. */
|
|
79
|
+
n?: number;
|
|
80
|
+
/** Alt text, kept with the image (at most 300 characters). */
|
|
81
|
+
alt?: string;
|
|
82
|
+
/** Up to 10 words to file the image under (each at most 40 characters). */
|
|
83
|
+
tags?: string[];
|
|
84
|
+
/** Don't keep the prompt with the image. A project that stores no message content never keeps it. */
|
|
85
|
+
noStore?: boolean;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** `data` of a successful `POST /egoz/images`. */
|
|
89
|
+
export interface GenerateImageResponseData {
|
|
90
|
+
images: GeneratedImage[];
|
|
91
|
+
/** The image model used. */
|
|
92
|
+
model: string;
|
|
93
|
+
/** How many you asked for. More than `images.length` when the monthly allowance ran short. */
|
|
94
|
+
requested: number;
|
|
95
|
+
}
|
package/src/index.d.ts
CHANGED
|
@@ -87,6 +87,15 @@
|
|
|
87
87
|
* import routes: `EgozProjectFile` and its sections,
|
|
88
88
|
* `ProjectFileImportBody`, `ProjectFileImportResult`.
|
|
89
89
|
*
|
|
90
|
+
* - `images.d.ts` — images EgoZ makes: `GeneratedImage` (on
|
|
91
|
+
* `POST /egoz/images`, `GET /egoz/assets/:assetId`,
|
|
92
|
+
* `AskResponseData.images` and the `done` event),
|
|
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`.
|
|
98
|
+
*
|
|
90
99
|
* This barrel re-exports everything so existing consumers' import paths
|
|
91
100
|
* (`import type { AskResponseData } from '@ego-z/contracts'`) keep
|
|
92
101
|
* working unchanged. Adding a new family is a single-file change here
|
|
@@ -116,3 +125,5 @@ export * from './user-memory';
|
|
|
116
125
|
export * from './search';
|
|
117
126
|
export * from './controlled';
|
|
118
127
|
export * from './project-file';
|
|
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
|
*/
|
|
@@ -160,6 +162,20 @@ export interface ProjectFileConfig {
|
|
|
160
162
|
webSearchMaxCallsPerTurn: number;
|
|
161
163
|
webFetchMaxCallsPerTurn: number;
|
|
162
164
|
|
|
165
|
+
/** Image generation opt-in: offers `generate_image` and opens `POST /egoz/images`. Default false. */
|
|
166
|
+
imageGenerationEnabled: boolean;
|
|
167
|
+
/** The image model (the deployment name on Azure). `null` = EgoZ's default (`gpt-image-1-mini`). */
|
|
168
|
+
imageModel: string | null;
|
|
169
|
+
/** `generate_image` calls one answer may make, 1..4. Default 2. */
|
|
170
|
+
imageMaxCallsPerTurn: number;
|
|
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
|
+
|
|
163
179
|
voiceEnabled: boolean;
|
|
164
180
|
voiceModel: string | null;
|
|
165
181
|
voiceTtsVoice: string | null;
|
|
@@ -240,6 +256,19 @@ export interface ProjectFilePricing {
|
|
|
240
256
|
completionPerM: number;
|
|
241
257
|
}
|
|
242
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
|
+
|
|
243
272
|
/**
|
|
244
273
|
* An extension's state. `config` is what the project set, without the
|
|
245
274
|
* extension's defaults, so a later change to a default still applies.
|
|
@@ -320,6 +349,7 @@ export interface ProjectFileImportSections {
|
|
|
320
349
|
pricing: ProjectFileSectionChanges;
|
|
321
350
|
extensions: ProjectFileSectionChanges;
|
|
322
351
|
webSearchSites: ProjectFileSectionChanges;
|
|
352
|
+
agentProfiles: ProjectFileSectionChanges;
|
|
323
353
|
}
|
|
324
354
|
|
|
325
355
|
export interface ProjectFileConfigChanges {
|
package/src/stream.d.ts
CHANGED
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
import type { AskRouting } from './ask';
|
|
15
15
|
import type { Intent, TokenUsage } from './envelope';
|
|
16
16
|
import type { AskQuestionSet } from './questions';
|
|
17
|
+
import type { GeneratedImage } from './images';
|
|
18
|
+
import type { AgentRunStarted } from './agents';
|
|
17
19
|
import type { InitContextItemAccepted } from './draft-conv';
|
|
18
20
|
|
|
19
21
|
/**
|
|
@@ -365,6 +367,17 @@ export interface AskStreamDoneEvent {
|
|
|
365
367
|
*/
|
|
366
368
|
memoryInjected?: boolean;
|
|
367
369
|
memoryProposed?: boolean;
|
|
370
|
+
/**
|
|
371
|
+
* Images the agent made this turn. Same semantics as
|
|
372
|
+
* `AskResponseData.images`; present only when it made at least one.
|
|
373
|
+
*/
|
|
374
|
+
images?: GeneratedImage[];
|
|
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[];
|
|
368
381
|
/**
|
|
369
382
|
* What EgoZ accepted from this turn's `contextItems`. Same semantics +
|
|
370
383
|
* shape as `AskResponseData.contextItemsAccepted` — surfaced on the
|