@ego-z/contracts 0.15.22 → 0.15.23

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.22",
3
+ "version": "0.15.23",
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": {
@@ -0,0 +1,213 @@
1
+ /**
2
+ * @ego-z/contracts — sub-agents (DRAFT for review, ego-z workspace #13).
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 thread, and its result comes back to you (a webhook) and to the main
7
+ * 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 use on their tool calls.
21
+ *
22
+ * ── Identity ─────────────────────────────────────────────────────────────
23
+ *
24
+ * A run acts for the project, never as the end user: nobody's session token
25
+ * 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;
27
+ * EgoZ keeps it encrypted with each run that turn starts, never shows it to
28
+ * the model, and sends it as `Authorization: Bearer …` on the run's tool
29
+ * calls (tools with `authType: 'FORWARD'`), next to EgoZ's usual signature
30
+ * (`X-EgoZ-Signature`, `X-EgoZ-Timestamp`) and:
31
+ *
32
+ * X-EgoZ-Actor: agent
33
+ * X-EgoZ-Run-Id: <runId>
34
+ * Idempotency-Key: <runId>:<hash of tool name + arguments>
35
+ *
36
+ * Verify both the signature and your credential, and take the tenant from
37
+ * your credential — never from a header the model's arguments could shape.
38
+ * The idempotency key is the same for the same call within a run, so a
39
+ * retried run doesn't write twice.
40
+ *
41
+ * ── Limits ───────────────────────────────────────────────────────────────
42
+ *
43
+ * One level deep: a sub-agent can't start another. It can't ask the user
44
+ * (`ask_user`): it ends `needs_input` with its question instead, and the
45
+ * main agent asks. It stops at its token budget, round limit or timeout.
46
+ */
47
+
48
+ import type { TokenUsage } from './envelope';
49
+ import type { GeneratedImage } from './images';
50
+
51
+ // ============================================================================
52
+ // Profiles
53
+ // ============================================================================
54
+
55
+ /** A sub-agent profile, as the profile routes return it. */
56
+ export interface AgentProfileWire {
57
+ id: string;
58
+ /**
59
+ * The handle the main agent picks it by, unique per project:
60
+ * lowercase letters, digits, `_` and `-`, 2–40 characters (e.g. `translator`).
61
+ */
62
+ name: string;
63
+ /** What it's for, in a sentence or two. The main agent reads this to decide when to use it (≤ 500 characters). */
64
+ description: string;
65
+ /** Its system prompt (≤ 20,000 characters). */
66
+ prompt: string;
67
+ /** The chat model it runs on. `null` = the project's default model. */
68
+ model: string | null;
69
+ /**
70
+ * The tools it may call, by name: the project's own tools and the
71
+ * built-ins `search_knowledge_base`, `web_search`, `web_fetch`,
72
+ * `generate_image`. Never `start_agent` or `ask_user`. A tool the project
73
+ * turns off later is simply not offered.
74
+ */
75
+ tools: string[];
76
+ /** Most tokens (in + out, every round) one run may spend: 1,000–2,000,000. Default 200,000. */
77
+ maxTokens: number;
78
+ /** Most tool rounds one run may take: 1–30. Default 10. */
79
+ maxRounds: number;
80
+ /** Wall-clock limit for one run, in seconds: 30–3,600. Default 600. */
81
+ timeoutSeconds: number;
82
+ /** A disabled profile is not offered to the main agent; its runs already started finish. */
83
+ enabled: boolean;
84
+ source: 'manual' | 'mcp';
85
+ createdAt: string;
86
+ updatedAt: string;
87
+ }
88
+
89
+ export interface AgentProfileCreateBody {
90
+ name: string;
91
+ description: string;
92
+ prompt: string;
93
+ model?: string | null;
94
+ tools?: string[];
95
+ maxTokens?: number;
96
+ maxRounds?: number;
97
+ timeoutSeconds?: number;
98
+ enabled?: boolean;
99
+ }
100
+
101
+ /** Only the fields you send change. */
102
+ export type AgentProfileUpdateBody = Partial<AgentProfileCreateBody>;
103
+
104
+ // ============================================================================
105
+ // start_agent (model-facing)
106
+ // ============================================================================
107
+
108
+ /** What the main agent sends `start_agent`. */
109
+ export interface StartAgentToolInput {
110
+ /** A profile `name`. */
111
+ agent: string;
112
+ /** The task in plain words, complete enough to do without the conversation (≤ 4,000 characters). */
113
+ task: string;
114
+ /** Facts the task needs (ids, languages, …) — at most 16 KB as JSON. */
115
+ input?: Record<string, unknown>;
116
+ }
117
+
118
+ /**
119
+ * What a turn reports for each run it started: `display` on the
120
+ * `start_agent` call's `tool.result`, and `agentRuns` on the `done` event and
121
+ * the /ask response. Lets you show the run the moment it starts.
122
+ */
123
+ export interface AgentRunStarted {
124
+ runId: string;
125
+ agent: string;
126
+ status: 'queued';
127
+ /** ISO 8601 — the run ends by then (its timeout); if no webhook has come, treat it as failed. */
128
+ deadlineAt: string;
129
+ }
130
+
131
+ // ============================================================================
132
+ // Runs
133
+ // ============================================================================
134
+
135
+ export type AgentRunStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancelled' | 'needs_input';
136
+
137
+ export type AgentRunErrorCode =
138
+ /** It hit its token budget or round limit. */
139
+ | 'budget'
140
+ /** It ran past its timeout. */
141
+ | 'timeout'
142
+ /** The model call failed (provider error, missing key). */
143
+ | 'model_error'
144
+ /** A tool it relied on failed and it could not finish without it. */
145
+ | 'tool_failed'
146
+ /** EgoZ failed (e.g. the run was lost twice). */
147
+ | 'internal';
148
+
149
+ /** One run, as `GET /egoz/agent-runs/:runId` and the webhook return it. */
150
+ export interface AgentRunWire {
151
+ runId: string;
152
+ /** The profile's `name` at start. */
153
+ agent: string;
154
+ profileId: string;
155
+ status: AgentRunStatus;
156
+ /** The task the main agent gave. `null` on a no-store project or turn. */
157
+ task: string | null;
158
+ /** `null` on no-store. */
159
+ input: Record<string, unknown> | null;
160
+ /** The conversation whose turn started it. */
161
+ parentThreadId: string;
162
+ /** Echo of that turn's `externalThreadId`, when it had one. */
163
+ externalThreadId?: string;
164
+ /** Echo of that turn's `externalUserId`, when it had one. */
165
+ externalUserId?: string;
166
+ /** The run's own conversation (its messages), once it has started. */
167
+ childThreadId: string | null;
168
+ /** Set when `status` is `done`. */
169
+ result: {
170
+ /** Its final answer. `null` on no-store. */
171
+ text: string | null;
172
+ /** Images it made with `generate_image` — take them before they expire. */
173
+ images?: GeneratedImage[];
174
+ } | null;
175
+ /** Set when `status` is `failed`. The message is EgoZ's, never a tool's or the provider's raw text. */
176
+ error: { code: AgentRunErrorCode; message: string } | null;
177
+ /** Set when `status` is `needs_input`: what it needs to know. The main agent asks the user. */
178
+ needsInput: { question: string } | null;
179
+ usage: TokenUsage;
180
+ /** 1, or 2 when EgoZ restarted a run it lost (a worker died mid-run). */
181
+ attempts: number;
182
+ createdAt: string;
183
+ startedAt: string | null;
184
+ finishedAt: string | null;
185
+ deadlineAt: string;
186
+ }
187
+
188
+ /** `GET /egoz/agent-runs?threadId=…` — the runs a conversation's turns started, newest first. */
189
+ export interface AgentRunListResponseData {
190
+ runs: AgentRunWire[];
191
+ }
192
+
193
+ // ============================================================================
194
+ // Webhook
195
+ // ============================================================================
196
+
197
+ /**
198
+ * POSTed to the project's `agentWebhookUrl` when a run ends (`done`,
199
+ * `failed`, `cancelled`, `needs_input`). Signed with the project's webhook
200
+ * secret like tool calls — check it with `@ego-z/client`'s
201
+ * `verifySignature` (signature + timestamp window) before you act on it.
202
+ *
203
+ * Retried with backoff for up to an hour while your server doesn't answer
204
+ * 2xx. `eventId` is the same on every retry: make your handler idempotent on it
205
+ * (or on `run.runId` + `run.status`).
206
+ */
207
+ export interface AgentRunWebhookBody {
208
+ type: 'agent_run.finished';
209
+ eventId: string;
210
+ /** ISO 8601. */
211
+ occurredAt: string;
212
+ run: AgentRunWire;
213
+ }
package/src/ask.d.ts CHANGED
@@ -8,6 +8,7 @@
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';
11
12
 
12
13
  // ============================================================================
13
14
  // /ask — request
@@ -687,6 +688,13 @@ export interface AskResponseData {
687
688
  * `memoryProposed` = the agent proposed at least one new PENDING fact via
688
689
  * `remember_fact` this turn. Additive — older consumers ignore them.
689
690
  */
691
+ /**
692
+ * Images the agent made this turn with the built-in `generate_image` tool
693
+ * (project setting `imageGenerationEnabled`). Present only when it made
694
+ * at least one. EgoZ keeps each for 7 days: fetch `url` and store the
695
+ * bytes yourself before `expiresAt` — see `images.d.ts`.
696
+ */
697
+ images?: GeneratedImage[];
690
698
  memoryInjected?: boolean;
691
699
  memoryProposed?: boolean;
692
700
  /**
@@ -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,11 @@
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
+ *
90
95
  * This barrel re-exports everything so existing consumers' import paths
91
96
  * (`import type { AskResponseData } from '@ego-z/contracts'`) keep
92
97
  * working unchanged. Adding a new family is a single-file change here
@@ -116,3 +121,4 @@ export * from './user-memory';
116
121
  export * from './search';
117
122
  export * from './controlled';
118
123
  export * from './project-file';
124
+ export * from './images';
@@ -160,6 +160,13 @@ export interface ProjectFileConfig {
160
160
  webSearchMaxCallsPerTurn: number;
161
161
  webFetchMaxCallsPerTurn: number;
162
162
 
163
+ /** Image generation opt-in: offers `generate_image` and opens `POST /egoz/images`. Default false. */
164
+ imageGenerationEnabled: boolean;
165
+ /** The image model (the deployment name on Azure). `null` = EgoZ's default (`gpt-image-1-mini`). */
166
+ imageModel: string | null;
167
+ /** `generate_image` calls one answer may make, 1..4. Default 2. */
168
+ imageMaxCallsPerTurn: number;
169
+
163
170
  voiceEnabled: boolean;
164
171
  voiceModel: string | null;
165
172
  voiceTtsVoice: string | null;
package/src/stream.d.ts CHANGED
@@ -14,6 +14,7 @@
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';
17
18
  import type { InitContextItemAccepted } from './draft-conv';
18
19
 
19
20
  /**
@@ -363,6 +364,11 @@ export interface AskStreamDoneEvent {
363
364
  * terminal event so streaming consumers get the signal without parsing the
364
365
  * final payload. Present only when learning was active this turn.
365
366
  */
367
+ /**
368
+ * Images the agent made this turn. Same semantics as
369
+ * `AskResponseData.images`; present only when it made at least one.
370
+ */
371
+ images?: GeneratedImage[];
366
372
  memoryInjected?: boolean;
367
373
  memoryProposed?: boolean;
368
374
  /**