@ego-z/contracts 0.15.11 → 0.15.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.15.11",
+  "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

@@ -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;
 }
 
 /**

package/src/draft-conv.d.ts

@@ -113,6 +113,46 @@ export interface InitContextItem {
      * `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;
 }
 
 /**
@@ -159,6 +199,19 @@ export interface InitContextItemAccepted {
      * 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. */