@ego-z/contracts 0.15.10 → 0.15.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.10",
+  "version": "0.15.12",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/ask.d.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Intent, JsonSchemaDefinition, ResponseFormat, TokenUsage } from './envelope';
-import type { InitContextItem, InitContextUi } from './draft-conv';
+import type { InitContextItem, InitContextItemAccepted, InitContextUi } from './draft-conv';
 import type { AskQuestionSet } from './questions';
 
 // ============================================================================
@@ -211,6 +211,102 @@ export interface AskRequestBody {
      * Optional and additive: omit it and nothing changes.
      */
     contextItems?: InitContextItem[];
+
+    /**
+     * Output a MACHINE produced for this turn — the result of something the
+     * user asked to have run, not anything the user said.
+     *
+     * ── Why this needs a channel of its own ──────────────────────────────
+     *
+     * Before this field there were exactly two ways in, and both are wrong
+     * for a machine:
+     *
+     * - `message` persists as `role: 'user'`. A script that prints a
+     *   customer's CSV row arrives labelled as the account owner speaking,
+     *   and **every protection that keys off who is speaking is bypassed by
+     *   a program printing a sentence.**
+     * - `contextItems` is worse, because it does not merely keep the user's
+     *   voice — it upgrades it. Those items are rendered as things the user
+     *   *chose deliberately* and *likely referents for anything they mention*,
+     *   so routing `stderr` there promotes program output to something
+     *   adjacent to instruction.
+     *
+     * `role: 'tool'` exists internally, but only EgoZ mints those and only
+     * from its own executions; nothing on the wire can produce one. So this
+     * is the channel: it is rendered to the agent as **quoted data with an
+     * explicit statement that a machine produced it**, never as speech and
+     * never as instruction.
+     *
+     * ⚠️ **You are asserting provenance when you send this.** Put here only
+     * what your own system produced. Anything a person typed belongs in
+     * `message`, whatever it is about — mislabelling user text as machine
+     * output is the same failure as the reverse, pointed the other way.
+     *
+     * Optional and additive: omit it and nothing changes.
+     */
+    machineOutput?: AskMachineOutput[];
+}
+
+/**
+ * One piece of output a machine produced for this turn.
+ *
+ * ── Truncated, never dropped — the opposite of `InitContextItem` ─────────
+ *
+ * An over-long `excerpt` on a context item is DROPPED, because a shortened
+ * address is a different valid address and acting on it is worse than not
+ * having it. Output is the other case entirely: **a clipped `stderr` is
+ * still evidence, and a missing one is a lie.** So this is capped by
+ * truncation and the truncation is declared — the agent is told the text was
+ * cut rather than left to conclude a command printed nothing.
+ *
+ * That asymmetry is deliberate and it is the reason these are two shapes
+ * rather than one generous one.
+ *
+ * ── No acceptance receipt, unlike `contextItems` ─────────────────────────
+ *
+ * `contextItemsAccepted` exists because acceptance there is lossy in ways
+ * the caller cannot observe — items vanish, excerpts disappear — so a
+ * "shared with the agent" display would otherwise be confidently wrong.
+ * Nothing here vanishes: an entry is either rendered or the request is
+ * rejected, and the one lossy case declares itself **to the reader who
+ * matters**, in-band, where the agent is told the text was cut. Adding a
+ * receipt would be a second copy of that fact, for a caller that already
+ * holds the full output it just sent.
+ */
+export interface AskMachineOutput {
+    /**
+     * Your own name for whatever produced this — `"terminal"`, `"build"`.
+     *
+     * ⚠️ Free-form, and **never rendered into the prompt**, exactly like
+     * `InitContextItem.kind` and for the same reason: free-form caller text
+     * in the instruction block is an injection surface. Used for grouping
+     * and for your own logs.
+     */
+    source?: string;
+
+    /**
+     * What was run, in the user's terms — a command line, a job name.
+     * Rendered, because output with no statement of what produced it invites
+     * the agent to guess which of its own suggestions ran.
+     */
+    invocation?: string;
+
+    /**
+     * The text the machine produced. Required — an entry with nothing in it
+     * says a program ran and reported nothing, which is a claim, not an
+     * omission. Truncated to a server cap if long; see the header.
+     */
+    output: string;
+
+    /**
+     * The producer's own result status, when it has one — a process exit
+     * code, conventionally 0 for success.
+     *
+     * Worth sending even when `output` is empty, and especially then: it is
+     * the difference between *"it worked and printed nothing"* and *"it
+     * failed silently"*, which no amount of text can express.
+     */
+    exitCode?: number;
 }
 
 /**
@@ -346,4 +442,23 @@ export interface AskResponseData {
      */
     memoryInjected?: boolean;
     memoryProposed?: boolean;
+    /**
+     * What EgoZ actually accepted from `AskRequestBody.contextItems` this
+     * turn, in the order the agent saw them.
+     *
+     * Present whenever the request carried `contextItems` — including as an
+     * empty array, meaning "you sent a list and nothing in it was accepted".
+     *
+     * ⚠️ ABSENT MEANS THE REQUEST CARRIED NO `contextItems`. It never means
+     * "none were accepted". A consumer that reads absence as rejection
+     * reports a failure that did not happen; one that reads an empty array as
+     * absence reports a success that did not either.
+     *
+     * Render this — not the list you sent — anywhere you show the user what
+     * was shared with the agent. See `InitContextItemAccepted` for why the
+     * two can differ and how to join them.
+     *
+     * Additive: consumers that ignore it are unaffected.
+     */
+    contextItemsAccepted?: InitContextItemAccepted[];
 }

package/src/draft-conv.d.ts

@@ -93,11 +93,125 @@ export interface InitContextItem {
     label?: string;
 
     /**
-     * A short description of the item. Optional, and truncated rather than
-     * rejected if long — but keep it to what the thing IS, not its full
-     * record. Everything here displaces conversation from the context window.
+     * A short description of the item. Optional — but keep it to what the
+     * thing IS, not its full record. Everything here displaces conversation
+     * from the context window.
+     *
+     * ⚠️ AN OVER-LONG EXCERPT IS DROPPED, NOT TRUNCATED, and the item still
+     * rides without it. Unlike every other cap here, which truncates or
+     * rejects.
+     *
+     * Because you resolve the item yourself, this is sometimes prose
+     * (`"£45, in stock"`) and sometimes an ADDRESS the agent will act on
+     * (`"projects/api/deploy.sh"`). Shortening prose loses a few words;
+     * shortening an address does not produce an invalid address, it produces
+     * a **different valid one**, which the agent then reads and reports on
+     * with no error anywhere. Nothing server-side can tell the two apart —
+     * `kind` is opaque and never resolved — so one behaviour covers both and
+     * it is the safe one.
+     *
+     * `contextItemsAccepted` on the response tells you when it happened.
      */
     excerpt?: string;
+
+    /**
+     * The exact string a tool needs to act on this item — a file path, a
+     * record id, whatever your tools take. Optional.
+     *
+     * ── Why this is not just an `excerpt` ────────────────────────────────
+     *
+     * Because the two are read differently and fail differently, and until
+     * this field existed they shared one. An excerpt is prose ABOUT the
+     * thing; an address is a HANDLE TO it, and the agent is expected to
+     * carry it verbatim into a tool call. Shortening prose loses a few
+     * words. Shortening an address produces a **different valid address** —
+     * so the caps differ, and so does what a consumer may do with the value.
+     *
+     * ⚠️ AN OVER-LONG ADDRESS IS DROPPED, NOT TRUNCATED, and the item still
+     * rides without it, exactly like `excerpt`. `addressOmitted` on the
+     * receipt tells you it happened — worth reading, because the agent then
+     * has the item's NAME and no way to act on it, which usually reads to a
+     * user as the agent being unable rather than under-informed.
+     *
+     * ── Send the address, or the agent will construct one ────────────────
+     *
+     * Measured, twice, on live traffic: given an item it can name but not
+     * address, an agent does not stop — it produces a plausible-looking
+     * identifier from the meaning it has. A product slug built from the
+     * product's name, a window key passed where a record id was wanted.
+     * Both fail at the tool, and the failure reads as a broken feature.
+     *
+     * So an absent address is not neutral. It is the condition under which
+     * an agent invents one.
+     *
+     * ── It is rendered, and that is a deliberate exception ───────────────
+     *
+     * `kind` and `id` never reach the prompt: free-form caller text in the
+     * instruction block is an injection surface. `address` does reach it,
+     * for the same reason `label` does — a handle nobody can read is not a
+     * handle. Send an identifier or a path, never a sentence, and never
+     * anything a user typed and you did not resolve.
+     */
+    address?: string;
+}
+
+/**
+ * One entry in the response's `contextItemsAccepted` receipt — what EgoZ
+ * actually took from a `contextItems` you sent.
+ *
+ * ── Why a receipt exists at all ──────────────────────────────────────────
+ *
+ * Acceptance is LOSSY BY DESIGN, in three ways you cannot observe from the
+ * caller: an over-long list is truncated from the end, an item with no
+ * `label` is dropped individually, and an over-long `excerpt` is dropped
+ * while its item rides on. Each is the right behaviour — none of them should
+ * fail a user's turn — but each means the list you sent is not necessarily
+ * the list the agent saw.
+ *
+ * So if you display "what was shared with the agent" anywhere, render THIS,
+ * not the list you sent. Rendering your own list produces a display that is
+ * confident and wrong in exactly the cases that matter.
+ *
+ * ⚠️ AN ITEM MISSING FROM THE RECEIPT WAS NOT ACCEPTED. Absence is the only
+ * channel that reports the list truncation and the labelless drop, so a
+ * consumer that treats this as best-effort or partially populated silently
+ * goes back to claiming delivery it cannot verify.
+ *
+ * Match entries to your own items on `kind` + `id`. Do NOT fall back to
+ * matching on `label` — labels are deliberately not unique, so that join is
+ * usually right, and "usually right" is the failure this field exists to
+ * remove. Render an unmatched entry as unmatched instead.
+ */
+export interface InitContextItemAccepted {
+    /** Echo of the item's `kind`. Still never rendered into the prompt. */
+    kind?: string;
+    /** Echo of the item's `id`. */
+    id?: string;
+    /** The label the agent saw. Always present — a labelless item is dropped. */
+    label: string;
+    /**
+     * The item was accepted but its `excerpt` was not — it exceeded the cap
+     * and was dropped rather than truncated (see `InitContextItem.excerpt`).
+     *
+     * Absent means the excerpt survived, or there was never one to carry.
+     * Distinguishing those two is not what this flag is for: it exists so a
+     * "shared with the agent" display can say the agent got a NAME and no
+     * detail, instead of implying it got both.
+     */
+    excerptOmitted?: boolean;
+
+    /**
+     * The item was accepted but its `address` was not — it exceeded the cap
+     * and was dropped rather than truncated (see `InitContextItem.address`).
+     *
+     * ⚠️ Worth surfacing more loudly than `excerptOmitted`. A lost excerpt
+     * costs detail; a lost address costs the agent the only way to ACT on
+     * the item, and what a user sees is not "it knew less about this" but
+     * "it couldn't do it" — or, worse, an invented identifier that fails at
+     * the tool. If you show a "shared with the agent" display at all, this
+     * is the flag that changes what the user should expect.
+     */
+    addressOmitted?: boolean;
 }
 
 /** One open window in the caller's UI. */

package/src/stream.d.ts

@@ -13,6 +13,7 @@
 
 import type { Intent, TokenUsage } from './envelope';
 import type { AskQuestionSet } from './questions';
+import type { InitContextItemAccepted } from './draft-conv';
 
 /**
  * Discriminated union of every event the streaming `/ask` endpoint emits.
@@ -352,6 +353,21 @@ export interface AskStreamDoneEvent {
      */
     memoryInjected?: boolean;
     memoryProposed?: boolean;
+    /**
+     * What EgoZ accepted from this turn's `contextItems`. Same semantics +
+     * shape as `AskResponseData.contextItemsAccepted` — surfaced on the
+     * terminal event so streaming consumers can render "what was shared"
+     * without parsing the final payload separately.
+     *
+     * On the terminal frame rather than mid-stream for the same reason as
+     * `questionSet`: it describes the settled turn, and a consumer would
+     * discard every earlier variant anyway.
+     *
+     * ⚠️ Absent means the request carried no `contextItems` — never that none
+     * were accepted. An empty array is the second thing, and they must not be
+     * collapsed by anything relaying this frame.
+     */
+    contextItemsAccepted?: InitContextItemAccepted[];
 }
 
 export interface AskStreamErrorEvent {