@opengeni/contracts 0.10.0 → 0.15.0

package/dist/index.js

@@ -1,5 +1,657 @@
 // src/index.ts
 import { z } from "zod";
+
+// src/event-preview.ts
+var SESSION_EVENT_PAYLOAD_MAX_BYTES = 64 * 1024;
+var TARGET_PAYLOAD_BYTES = 60 * 1024;
+var DEFAULT_STRING_BYTES = 8 * 1024;
+var RETRY_STRING_BYTES = 1024;
+var DEFAULT_ARRAY_ENTRIES = 40;
+var RETRY_ARRAY_ENTRIES = 12;
+var DEFAULT_OBJECT_FIELDS = 80;
+var RETRY_OBJECT_FIELDS = 32;
+var MAX_PREVIEW_DEPTH = 12;
+var MAX_PREVIEW_NODES = 512;
+var MAX_MEASUREMENT_NODES = 2048;
+var MAX_MEASUREMENT_DEPTH = 64;
+var MAX_DETAIL_RECORDS = 24;
+var APPROX_BYTES_PER_TOKEN = 4;
+var encoder = new TextEncoder();
+var IDENTITY_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "callId",
+  "call_id",
+  "name",
+  "toolName",
+  "type",
+  "status",
+  "code",
+  "isError",
+  "stream",
+  "commandId",
+  "sequence"
+]);
+function sessionEventJsonBytes(value) {
+  return encoder.encode(stringifyForBoundary(value)).byteLength;
+}
+function measureSessionEventJson(value) {
+  return measureJsonBytes(value);
+}
+function approximateSessionEventTokens(bytes) {
+  return Math.ceil(Math.max(0, bytes) / APPROX_BYTES_PER_TOKEN);
+}
+function sessionEventMediaPreview(mediaType, inlineBytes) {
+  return {
+    type: "media_preview",
+    mediaType: mediaType || "application/octet-stream",
+    inlineBytes: inlineBytes === null ? null : Math.max(0, Math.floor(Number.isFinite(inlineBytes) ? inlineBytes : 0)),
+    fullOutputAvailable: false,
+    preview: "Inline media omitted from the audit timeline; source bytes were not retained."
+  };
+}
+function sessionEventMediaPreviewFromDataUrl(value) {
+  const match = /^data:([^;,]+)(?:;[^,]*)?;base64,/i.exec(value);
+  if (!match) return null;
+  const encodedLength = Math.max(0, value.length - match[0].length);
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  return sessionEventMediaPreview(
+    match[1] ?? "application/octet-stream",
+    Math.max(0, Math.floor(encodedLength * 3 / 4) - padding)
+  );
+}
+function sessionEventPayloadTruncation(payload) {
+  if (!isPlainRecord(payload)) return null;
+  const value = payload.truncation;
+  if (!isPlainRecord(value) || value.truncated !== true) return null;
+  return value;
+}
+function boundSessionEventPayload(payload, options = {}) {
+  const maxBytes = Math.max(1024, Math.floor(options.maxBytes ?? SESSION_EVENT_PAYLOAD_MAX_BYTES));
+  const surface = options.surface ?? "durable_audit";
+  const originalMeasurement = measureJsonBytes(payload);
+  const originalBytes = originalMeasurement.bytes;
+  let state = previewState(DEFAULT_STRING_BYTES, DEFAULT_ARRAY_ENTRIES, DEFAULT_OBJECT_FIELDS);
+  let preview = previewValue(payload, state, "$", 0);
+  if (!state.changed && originalBytes !== null && originalBytes <= maxBytes) {
+    return payload;
+  }
+  let reason = payloadTruncationReason(originalMeasurement, state);
+  let bounded = attachTruncation(preview, boundaryMetadata(surface, reason, originalBytes, state));
+  if (sessionEventJsonBytes(bounded) > Math.min(maxBytes, TARGET_PAYLOAD_BYTES)) {
+    state = previewState(RETRY_STRING_BYTES, RETRY_ARRAY_ENTRIES, RETRY_OBJECT_FIELDS);
+    preview = previewValue(payload, state, "$", 0);
+    reason = payloadTruncationReason(originalMeasurement, state);
+    bounded = attachTruncation(preview, boundaryMetadata(surface, reason, originalBytes, state));
+  }
+  if (sessionEventJsonBytes(bounded) > maxBytes) {
+    const identity = identityPreview(payload);
+    state.changed = true;
+    recordDetail(state, {
+      path: "$",
+      kind: "object",
+      ...originalBytes === null ? {} : { originalBytes }
+    });
+    bounded = attachTruncation(
+      {
+        ...identity,
+        preview: "[event payload omitted: bounded audit preview exceeded the storage envelope]"
+      },
+      boundaryMetadata(surface, reason, originalBytes, state)
+    );
+  }
+  settleDeliveredSizes(bounded, maxBytes);
+  return bounded;
+}
+function previewState(stringBytes, arrayEntries, objectFields) {
+  return {
+    changed: false,
+    sawMedia: false,
+    details: [],
+    stringBytes,
+    arrayEntries,
+    objectFields,
+    remainingNodes: MAX_PREVIEW_NODES
+  };
+}
+function payloadTruncationReason(measurement, state) {
+  if (state.sawMedia) return "inline_media_not_retained";
+  return measurement.bytes === null ? measurement.reason : "payload_bytes_exceeded";
+}
+function previewValue(value, state, path, depth) {
+  if (state.remainingNodes <= 0) {
+    state.changed = true;
+    recordDetail(state, { path, kind: "budget" });
+    return "[nested value omitted at audit preview traversal boundary]";
+  }
+  state.remainingNodes -= 1;
+  if (typeof value === "string") {
+    const media = inlineMediaFact(value);
+    if (media) {
+      state.changed = true;
+      state.sawMedia = true;
+      recordDetail(state, {
+        path,
+        kind: "media",
+        originalBytes: utf8Bytes(value),
+        deliveredBytes: sessionEventJsonBytes(media),
+        mediaType: media.mediaType
+      });
+      return media;
+    }
+    const originalBytes = utf8Bytes(value);
+    if (originalBytes <= state.stringBytes) return value;
+    state.changed = true;
+    const delivered = truncateUtf8Middle(value, state.stringBytes, originalBytes);
+    recordDetail(state, {
+      path,
+      kind: "string",
+      originalBytes,
+      deliveredBytes: utf8Bytes(delivered)
+    });
+    return delivered;
+  }
+  if (typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") {
+    state.changed = true;
+    recordDetail(state, { path, kind: "unserializable" });
+    return `[${typeof value} value omitted at audit serialization boundary]`;
+  }
+  if (value === null || typeof value !== "object") return value;
+  const binary = binaryFact(value);
+  if (binary) {
+    state.changed = true;
+    recordDetail(state, {
+      path,
+      kind: "binary",
+      originalBytes: binary.originalBytes,
+      deliveredBytes: sessionEventJsonBytes(binary.preview)
+    });
+    return binary.preview;
+  }
+  if (depth >= MAX_PREVIEW_DEPTH) {
+    state.changed = true;
+    recordDetail(state, { path, kind: "depth" });
+    return "[nested value omitted at audit preview depth boundary]";
+  }
+  if (Array.isArray(value)) {
+    const keep = Math.max(2, state.arrayEntries);
+    if (value.length <= keep) {
+      return Array.from(
+        { length: value.length },
+        (_, index) => previewArrayEntry(value, index, state, path, depth)
+      );
+    }
+    state.changed = true;
+    const head = Math.ceil(keep / 2);
+    const tail = Math.floor(keep / 2);
+    const omitted2 = value.length - head - tail;
+    recordDetail(state, { path, kind: "array", omittedEntries: omitted2 });
+    return [
+      ...Array.from(
+        { length: head },
+        (_, index) => previewArrayEntry(value, index, state, path, depth)
+      ),
+      { omittedEntries: omitted2, preview: "[middle array entries omitted]" },
+      ...Array.from(
+        { length: tail },
+        (_, index) => previewArrayEntry(value, value.length - tail + index, state, path, depth)
+      )
+    ];
+  }
+  if (value instanceof Date) {
+    if (!hasCanonicalDateSerialization(value)) {
+      state.changed = true;
+      recordDetail(state, { path, kind: "unserializable" });
+      return "[Date value with custom serialization omitted at audit boundary]";
+    }
+    try {
+      const epoch = Date.prototype.getTime.call(value);
+      return Number.isFinite(epoch) ? Date.prototype.toISOString.call(value) : null;
+    } catch {
+      state.changed = true;
+      recordDetail(state, { path, kind: "unserializable" });
+      return "[Date value omitted at audit serialization boundary]";
+    }
+  }
+  const record = value;
+  const { entries, omitted, accessorKeys } = selectObjectEntries(record, state.objectFields);
+  for (const key of accessorKeys) {
+    state.changed = true;
+    recordDetail(state, {
+      path: `${path}.${key}`,
+      kind: "unserializable"
+    });
+  }
+  if (omitted) {
+    state.changed = true;
+    recordDetail(state, {
+      path,
+      kind: "object",
+      // Counting every remaining field would defeat the traversal bound. `null`
+      // is deliberate: at least one field was omitted, but its exact count is
+      // unknown because the source was not fully enumerated.
+      omittedEntries: null
+    });
+  }
+  const out = {};
+  for (const [key, entry] of entries) {
+    out[key] = previewValue(entry, state, `${path}.${key}`, depth + 1);
+  }
+  if (omitted) {
+    out.omittedFields = "additional fields omitted; exact count not measured";
+  }
+  return out;
+}
+function previewArrayEntry(value, index, state, path, depth) {
+  let descriptor;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+  } catch {
+    state.changed = true;
+    recordDetail(state, { path: `${path}[${index}]`, kind: "unserializable" });
+    return "[array element omitted at audit serialization boundary]";
+  }
+  if (descriptor && !("value" in descriptor)) {
+    state.changed = true;
+    recordDetail(state, { path: `${path}[${index}]`, kind: "unserializable" });
+    return "[array accessor value omitted at audit serialization boundary]";
+  }
+  return previewValue(
+    descriptor && "value" in descriptor ? descriptor.value : void 0,
+    state,
+    `${path}[${index}]`,
+    depth + 1
+  );
+}
+function selectObjectEntries(record, maxFields) {
+  const entries = [];
+  const selected = /* @__PURE__ */ new Set();
+  const accessorKeys = [];
+  const select = (key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (!descriptor?.enumerable) return false;
+    selected.add(key);
+    if ("value" in descriptor) {
+      entries.push([key, descriptor.value]);
+    } else {
+      entries.push([key, "[accessor value omitted at audit serialization boundary]"]);
+      accessorKeys.push(key);
+    }
+    return true;
+  };
+  try {
+    for (const key of IDENTITY_FIELDS) {
+      if (entries.length >= maxFields) break;
+      select(key);
+    }
+    for (const key in record) {
+      if (!Object.prototype.hasOwnProperty.call(record, key) || selected.has(key)) continue;
+      if (entries.length >= maxFields) {
+        return { entries, omitted: true, accessorKeys };
+      }
+      select(key);
+    }
+  } catch {
+    return { entries, omitted: true, accessorKeys };
+  }
+  return { entries, omitted: false, accessorKeys };
+}
+function attachTruncation(preview, truncation) {
+  if (isPlainRecord(preview)) {
+    return { ...preview, truncation };
+  }
+  return { value: preview, truncation };
+}
+function boundaryMetadata(surface, reason, originalBytes, state) {
+  return {
+    truncated: true,
+    surface,
+    reason,
+    originalBytes,
+    deliveredBytes: 0,
+    omittedBytes: originalBytes,
+    estimatedOriginalTokens: originalBytes === null ? null : approximateSessionEventTokens(originalBytes),
+    estimatedDeliveredTokens: 0,
+    fullEvidence: { available: false, reason: "not_retained" },
+    details: state.details
+  };
+}
+function settleDeliveredSizes(payload, maxBytes) {
+  const truncation = payload.truncation;
+  convergeDeliveredSizes(payload, truncation);
+  if (sessionEventJsonBytes(payload) > maxBytes) {
+    payload.preview = "[event payload omitted at audit byte boundary]";
+    for (const key of Object.keys(payload)) {
+      if (key !== "preview" && key !== "truncation" && IDENTITY_FIELDS.has(key) === false) {
+        delete payload[key];
+      }
+    }
+    truncation.details = truncation.details.slice(0, 4);
+    convergeDeliveredSizes(payload, truncation);
+  }
+}
+function convergeDeliveredSizes(payload, truncation) {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const deliveredBytes = sessionEventJsonBytes(payload);
+    const omittedBytes = truncation.originalBytes === null ? null : Math.max(0, truncation.originalBytes - deliveredBytes);
+    const estimatedDeliveredTokens = approximateSessionEventTokens(deliveredBytes);
+    if (truncation.deliveredBytes === deliveredBytes && truncation.omittedBytes === omittedBytes && truncation.estimatedDeliveredTokens === estimatedDeliveredTokens) {
+      return;
+    }
+    truncation.deliveredBytes = deliveredBytes;
+    truncation.omittedBytes = omittedBytes;
+    truncation.estimatedDeliveredTokens = estimatedDeliveredTokens;
+  }
+  throw new RangeError("Session event byte accounting did not converge");
+}
+function recordDetail(state, detail) {
+  if (state.details.length < MAX_DETAIL_RECORDS) state.details.push(detail);
+}
+function identityPreview(value) {
+  if (!isPlainRecord(value)) return {};
+  const out = {};
+  for (const key of IDENTITY_FIELDS) {
+    let field;
+    try {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor?.enumerable || !("value" in descriptor)) continue;
+      field = descriptor.value;
+    } catch {
+      continue;
+    }
+    if (typeof field === "string") {
+      out[key] = truncateUtf8Middle(field, 256, utf8Bytes(field));
+    } else if (typeof field === "number" || typeof field === "boolean" || field === null) {
+      out[key] = field;
+    }
+  }
+  return out;
+}
+function inlineMediaFact(value) {
+  return sessionEventMediaPreviewFromDataUrl(value);
+}
+function binaryFact(value) {
+  if (ArrayBuffer.isView(value)) {
+    return {
+      originalBytes: value.byteLength,
+      preview: {
+        type: "binary_preview",
+        byteLength: value.byteLength,
+        fullOutputAvailable: false,
+        preview: "Inline binary value omitted from the audit timeline; bytes were not retained."
+      }
+    };
+  }
+  if (value instanceof ArrayBuffer) {
+    return {
+      originalBytes: value.byteLength,
+      preview: {
+        type: "binary_preview",
+        byteLength: value.byteLength,
+        fullOutputAvailable: false,
+        preview: "Inline binary value omitted from the audit timeline; bytes were not retained."
+      }
+    };
+  }
+  return null;
+}
+function truncateUtf8Middle(value, maxBytes, knownBytes = utf8Bytes(value)) {
+  if (knownBytes <= maxBytes) return value;
+  let omittedBytes = Math.max(0, knownBytes - maxBytes);
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const marker2 = `\u2026[${omittedBytes} bytes omitted]\u2026`;
+    const contentBudget2 = Math.max(0, maxBytes - utf8Bytes(marker2));
+    if (contentBudget2 === 0) return marker2;
+    const left2 = utf8Prefix(value, Math.floor(contentBudget2 / 2));
+    const right2 = utf8Suffix(value, contentBudget2 - left2.bytes);
+    const exactOmittedBytes = Math.max(0, knownBytes - left2.bytes - right2.bytes);
+    if (exactOmittedBytes === omittedBytes) {
+      return `${value.slice(0, left2.end)}${marker2}${value.slice(right2.start)}`;
+    }
+    omittedBytes = exactOmittedBytes;
+  }
+  const marker = `\u2026[${omittedBytes} bytes omitted]\u2026`;
+  const contentBudget = Math.max(0, maxBytes - utf8Bytes(marker));
+  const left = utf8Prefix(value, Math.floor(contentBudget / 2));
+  const right = utf8Suffix(value, contentBudget - left.bytes);
+  return `${value.slice(0, left.end)}${marker}${value.slice(right.start)}`;
+}
+function utf8Prefix(value, maxBytes) {
+  let end = 0;
+  let bytes = 0;
+  while (end < value.length) {
+    const unit = utf8UnitAt(value, end);
+    if (bytes + unit.bytes > maxBytes) break;
+    bytes += unit.bytes;
+    end += unit.codeUnits;
+  }
+  return { end, bytes };
+}
+function utf8Suffix(value, maxBytes) {
+  let start = value.length;
+  let bytes = 0;
+  while (start > 0) {
+    const unit = utf8UnitBefore(value, start);
+    if (bytes + unit.bytes > maxBytes) break;
+    bytes += unit.bytes;
+    start -= unit.codeUnits;
+  }
+  return { start, bytes };
+}
+function utf8UnitAt(value, index) {
+  const code = value.charCodeAt(index);
+  if (code <= 127) return { codeUnits: 1, bytes: 1 };
+  if (code <= 2047) return { codeUnits: 1, bytes: 2 };
+  if (code >= 55296 && code <= 56319) {
+    const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+    if (next >= 56320 && next <= 57343) {
+      return { codeUnits: 2, bytes: 4 };
+    }
+  }
+  return { codeUnits: 1, bytes: 3 };
+}
+function utf8UnitBefore(value, end) {
+  const code = value.charCodeAt(end - 1);
+  if (code >= 56320 && code <= 57343 && end >= 2) {
+    const previous = value.charCodeAt(end - 2);
+    if (previous >= 55296 && previous <= 56319) {
+      return { codeUnits: 2, bytes: 4 };
+    }
+  }
+  if (code <= 127) return { codeUnits: 1, bytes: 1 };
+  if (code <= 2047) return { codeUnits: 1, bytes: 2 };
+  return { codeUnits: 1, bytes: 3 };
+}
+function utf8Bytes(value) {
+  let bytes = 0;
+  for (let index = 0; index < value.length; ) {
+    const unit = utf8UnitAt(value, index);
+    bytes += unit.bytes;
+    index += unit.codeUnits;
+  }
+  return bytes;
+}
+function measureJsonBytes(value) {
+  const state = {
+    remainingNodes: MAX_MEASUREMENT_NODES,
+    seen: /* @__PURE__ */ new WeakSet(),
+    failureReason: null
+  };
+  try {
+    const bytes = measureJsonValue(value, state, "top", 0);
+    return bytes === null ? {
+      bytes: null,
+      reason: state.failureReason ?? "payload_measurement_bounded"
+    } : { bytes, reason: null };
+  } catch {
+    return { bytes: null, reason: "payload_measurement_bounded" };
+  }
+}
+function measureJsonValue(value, state, position, depth) {
+  if (state.remainingNodes <= 0 || depth > MAX_MEASUREMENT_DEPTH) {
+    return failJsonMeasurement(state, "payload_measurement_bounded");
+  }
+  state.remainingNodes -= 1;
+  if (value === null) return 4;
+  if (typeof value === "string") return jsonStringBytes(value);
+  if (typeof value === "boolean") return value ? 4 : 5;
+  if (typeof value === "number") {
+    const serialized = JSON.stringify(value);
+    return serialized === void 0 ? null : serialized.length;
+  }
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
+    return position === "array" ? 4 : failJsonMeasurement(state, "payload_not_serializable");
+  }
+  if (typeof value === "bigint") {
+    return failJsonMeasurement(state, "payload_not_serializable");
+  }
+  if (typeof value !== "object") {
+    return failJsonMeasurement(state, "payload_not_serializable");
+  }
+  if (value instanceof Date) {
+    if (!hasCanonicalDateSerialization(value)) {
+      return failJsonMeasurement(state, "payload_measurement_bounded");
+    }
+    try {
+      const epoch = Date.prototype.getTime.call(value);
+      return Number.isFinite(epoch) ? jsonStringBytes(Date.prototype.toISOString.call(value)) : 4;
+    } catch {
+      return failJsonMeasurement(state, "payload_not_serializable");
+    }
+  }
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return failJsonMeasurement(state, "payload_measurement_bounded");
+  }
+  if (state.seen.has(value)) {
+    return failJsonMeasurement(state, "payload_not_serializable");
+  }
+  state.seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype) {
+        return failJsonMeasurement(state, "payload_measurement_bounded");
+      }
+      const toJson2 = Object.getOwnPropertyDescriptor(value, "toJSON");
+      if (toJson2 && ("get" in toJson2 || typeof toJson2.value === "function")) {
+        return failJsonMeasurement(state, "payload_measurement_bounded");
+      }
+      if (value.length > state.remainingNodes) {
+        return failJsonMeasurement(state, "payload_measurement_bounded");
+      }
+      let bytes2 = 2;
+      for (let index = 0; index < value.length; index += 1) {
+        if (index > 0) bytes2 += 1;
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor && !("value" in descriptor)) {
+          return failJsonMeasurement(state, "payload_measurement_bounded");
+        }
+        const entry = descriptor && "value" in descriptor ? descriptor.value : void 0;
+        const measured = measureJsonValue(entry, state, "array", depth + 1);
+        if (measured === null) return null;
+        bytes2 += measured;
+      }
+      return bytes2;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return failJsonMeasurement(state, "payload_measurement_bounded");
+    }
+    const toJson = Object.getOwnPropertyDescriptor(value, "toJSON");
+    if (toJson && ("get" in toJson || typeof toJson.value === "function")) {
+      return failJsonMeasurement(state, "payload_measurement_bounded");
+    }
+    let bytes = 2;
+    let fields = 0;
+    try {
+      for (const key in value) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
+        if (state.remainingNodes <= 0) {
+          return failJsonMeasurement(state, "payload_measurement_bounded");
+        }
+        state.remainingNodes -= 1;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor)) {
+          return failJsonMeasurement(state, "payload_measurement_bounded");
+        }
+        const entry = descriptor.value;
+        if (typeof entry === "undefined" || typeof entry === "function" || typeof entry === "symbol") {
+          continue;
+        }
+        const measured = measureJsonValue(entry, state, "object", depth + 1);
+        if (measured === null) return null;
+        if (fields > 0) bytes += 1;
+        bytes += jsonStringBytes(key) + 1 + measured;
+        fields += 1;
+      }
+    } catch {
+      return null;
+    }
+    return bytes;
+  } finally {
+    state.seen.delete(value);
+  }
+}
+function hasCanonicalDateSerialization(value) {
+  try {
+    if (Object.getPrototypeOf(value) !== Date.prototype) return false;
+    return Object.getOwnPropertyDescriptor(value, "toJSON") === void 0;
+  } catch {
+    return false;
+  }
+}
+function failJsonMeasurement(state, reason) {
+  state.failureReason ??= reason;
+  return null;
+}
+function jsonStringBytes(value) {
+  let bytes = 2;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) {
+      bytes += 2;
+    } else if (code <= 31) {
+      bytes += 6;
+    } else if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+function serializeForBoundary(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    return {
+      value: serialized === void 0 ? "null" : serialized,
+      serializable: serialized !== void 0
+    };
+  } catch {
+    return {
+      value: JSON.stringify("[unserializable event payload omitted]"),
+      serializable: false
+    };
+  }
+}
+function stringifyForBoundary(value) {
+  return serializeForBoundary(value).value;
+}
+function isPlainRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+// src/index.ts
 var SessionStatus = z.enum([
   "queued",
   "running",
@@ -7,7 +659,6 @@ var SessionStatus = z.enum([
   "requires_action",
   "recovering",
   "waiting_capacity",
-  "paused",
   "failed",
   "cancelled"
 ]);
@@ -386,7 +1037,7 @@ var Permission = z.enum([
   "sessions:create",
   "sessions:read",
   "sessions:control",
-  // Sandbox-surfacing (master-spine §C.3 / crosscut PART 1.2). stream:view is a
+  // sandbox workspace (sandbox contract §C.3 / crosscut PART 1.2). stream:view is a
   // REAL, distinct permission — strictly BROADER than sessions:read — because the
   // pixel plane (Channel B) is UN-REDACTED: a viewer of raw pixels can see cloud
   // creds the agent cat's into a terminal, which the redacted Channel-A event log
@@ -480,25 +1131,255 @@ var Workspace = z.object({
   // validated by WorkspaceSettingsSchema; unknown keys are preserved across
   // PATCH merges so newer settings survive an older server.
   settings: z.record(z.string(), z.unknown()),
-  inferenceState: z.enum(["active", "paused"]),
-  inferenceGeneration: z.number().int().nonnegative(),
-  inferenceReason: z.string().nullable(),
-  inferenceChangedBy: z.string().nullable(),
-  inferenceChangedAt: z.string().nullable(),
+  inferenceControl: z.object({
+    state: z.enum(["active", "paused"]),
+    revision: z.number().int().nonnegative(),
+    reason: z.string().nullable(),
+    changedBy: z.string().nullable(),
+    changedAt: z.string().nullable()
+  }),
   // Workspace default rig used by session/scheduled-task create fallback.
   defaultRigId: z.string().uuid().nullable(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var WorkspaceTranscriptionTarget = z.object({
+  provider: z.string().trim().min(1).max(128),
+  model: z.string().trim().min(1).max(256).nullable(),
+  credentialMode: z.enum(["managed", "byok"]),
+  // A workspace-scoped connection reference, never credential material.
+  credentialConnectionId: z.string().uuid().nullable(),
+  region: z.string().trim().min(1).max(128).nullable()
+}).strict().superRefine((target, context) => {
+  if (target.provider === "azure-speech" && target.credentialMode !== "byok") {
+    context.addIssue({
+      code: "custom",
+      path: ["credentialMode"],
+      message: "Azure Speech is supported only through workspace BYOK"
+    });
+  }
+  if (target.credentialMode === "byok" && target.credentialConnectionId === null) {
+    context.addIssue({
+      code: "custom",
+      path: ["credentialConnectionId"],
+      message: "BYOK transcription targets require a workspace connection reference"
+    });
+  }
+  if (target.credentialMode === "managed" && target.credentialConnectionId !== null) {
+    context.addIssue({
+      code: "custom",
+      path: ["credentialConnectionId"],
+      message: "managed transcription targets cannot name a BYOK connection"
+    });
+  }
+});
+var TranscriptionErrorCode = z.enum([
+  "permission_denied",
+  "not_supported",
+  "network",
+  "provider",
+  "policy_blocked",
+  "timeout",
+  "cancelled",
+  "unknown"
+]);
+var TranscriptionTimeSpan = z.object({
+  startMilliseconds: z.number().finite().nonnegative(),
+  endMilliseconds: z.number().finite().nonnegative()
+}).strict().superRefine((span, context) => {
+  if (span.endMilliseconds < span.startMilliseconds) {
+    context.addIssue({
+      code: "custom",
+      path: ["endMilliseconds"],
+      message: "transcription spans must not end before they start"
+    });
+  }
+});
+var TranscriptionSpeaker = z.object({
+  id: z.string().trim().min(1).max(128),
+  label: z.string().trim().min(1).max(128).optional()
+}).strict();
+var TranscriptionWord = z.object({
+  text: z.string().min(1).max(4096),
+  span: TranscriptionTimeSpan,
+  confidence: z.number().finite().min(0).max(1).optional(),
+  speaker: TranscriptionSpeaker.optional()
+}).strict();
+var TranscriptionResultMetadata = z.object({
+  detectedLanguage: z.string().trim().min(1).max(64).optional(),
+  span: TranscriptionTimeSpan.optional(),
+  confidence: z.number().finite().min(0).max(1).optional(),
+  speaker: TranscriptionSpeaker.optional(),
+  words: z.array(TranscriptionWord).max(1e4).optional()
+}).strict().superRefine((metadata, context) => {
+  let previousStart = -1;
+  for (const [index, word] of (metadata.words ?? []).entries()) {
+    if (word.span.startMilliseconds < previousStart) {
+      context.addIssue({
+        code: "custom",
+        path: ["words", index, "span", "startMilliseconds"],
+        message: "transcription words must be ordered by start time"
+      });
+    }
+    previousStart = word.span.startMilliseconds;
+    if (metadata.span && (word.span.startMilliseconds < metadata.span.startMilliseconds || word.span.endMilliseconds > metadata.span.endMilliseconds)) {
+      context.addIssue({
+        code: "custom",
+        path: ["words", index, "span"],
+        message: "transcription word spans must fall within the result span"
+      });
+    }
+  }
+});
+var TranscriptionEventBase = z.object({
+  localSessionId: z.string().min(1).max(256),
+  sequence: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  occurredAt: z.string().datetime({ offset: true })
+}).strict();
+var TranscriptionEvent = z.discriminatedUnion("type", [
+  TranscriptionEventBase.extend({ type: z.literal("permission.requested") }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.opened"),
+    providerSessionId: z.string().min(1).max(512)
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("transcript.partial"),
+    segmentId: z.string().min(1).max(512),
+    text: z.string().max(1e6),
+    metadata: TranscriptionResultMetadata.optional()
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("transcript.final"),
+    segmentId: z.string().min(1).max(512),
+    text: z.string().max(1e6),
+    providerAcceptanceId: z.string().min(1).max(512),
+    metadata: TranscriptionResultMetadata.optional()
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("usage"),
+    audioMilliseconds: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    costUsd: z.number().finite().nonnegative().max(1e9).nullable()
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.reconnecting"),
+    attempt: z.number().int().nonnegative().max(1e4),
+    reason: z.string().min(1).max(256)
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.error"),
+    code: TranscriptionErrorCode,
+    recoverable: z.boolean()
+  }),
+  TranscriptionEventBase.extend({
+    type: z.literal("session.closed"),
+    reason: z.enum(["completed", "cancelled", "error", "replaced"])
+  })
+]);
+var WorkspaceTranscriptionPolicy = z.object({
+  enabled: z.boolean(),
+  acceptanceId: z.string().uuid().nullable(),
+  primary: WorkspaceTranscriptionTarget.nullable(),
+  language: z.string().trim().min(1).max(64).nullable(),
+  autoDetectLanguage: z.boolean(),
+  diarization: z.object({
+    enabled: z.boolean(),
+    maxSpeakers: z.number().int().min(2).max(100).nullable()
+  }).strict(),
+  retention: z.object({
+    mode: z.enum(["none", "provider-policy"]),
+    maxDays: z.number().int().nonnegative().max(3650).nullable()
+  }).strict(),
+  privacy: z.object({
+    allowProviderLogging: z.boolean(),
+    allowProviderTraining: z.boolean()
+  }).strict(),
+  fallback: z.object({
+    mode: z.enum(["disabled", "explicit"]),
+    targets: z.array(WorkspaceTranscriptionTarget).max(8)
+  }).strict(),
+  cost: z.object({
+    currency: z.literal("USD"),
+    maxPerHour: z.number().finite().nonnegative().max(1e4).nullable(),
+    maxPerMonth: z.number().finite().nonnegative().max(1e6).nullable()
+  }).strict()
+}).strict().superRefine((policy, context) => {
+  if (policy.enabled && policy.acceptanceId === null) {
+    context.addIssue({
+      code: "custom",
+      path: ["acceptanceId"],
+      message: "enabled transcription requires an accepted policy identity"
+    });
+  }
+  if (policy.enabled && policy.primary === null) {
+    context.addIssue({
+      code: "custom",
+      path: ["primary"],
+      message: "enabled transcription requires a primary target"
+    });
+  }
+  if (policy.enabled && !policy.autoDetectLanguage && policy.language === null) {
+    context.addIssue({
+      code: "custom",
+      path: ["language"],
+      message: "enabled transcription requires a language or accepted automatic detection"
+    });
+  }
+  if (policy.autoDetectLanguage && policy.language !== null) {
+    context.addIssue({
+      code: "custom",
+      path: ["language"],
+      message: "automatic language detection and a fixed language are mutually exclusive"
+    });
+  }
+  if (!policy.diarization.enabled && policy.diarization.maxSpeakers !== null) {
+    context.addIssue({
+      code: "custom",
+      path: ["diarization", "maxSpeakers"],
+      message: "disabled diarization cannot retain a speaker limit"
+    });
+  }
+  if (policy.fallback.mode === "disabled" && policy.fallback.targets.length > 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["fallback", "targets"],
+      message: "disabled fallback cannot retain accepted targets"
+    });
+  }
+  if (policy.fallback.mode === "explicit" && policy.fallback.targets.length === 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["fallback", "targets"],
+      message: "explicit fallback requires at least one accepted target"
+    });
+  }
+  const targetKeys = [policy.primary, ...policy.fallback.targets].filter((target) => target !== null).map(
+    (target) => [
+      target.provider,
+      target.model ?? "",
+      target.credentialMode,
+      target.credentialConnectionId ?? "",
+      target.region ?? ""
+    ].join("\0")
+  );
+  if (new Set(targetKeys).size !== targetKeys.length) {
+    context.addIssue({
+      code: "custom",
+      path: ["fallback", "targets"],
+      message: "transcription targets must be unique"
+    });
+  }
+});
 var WorkspaceSettingsSchema = z.object({
-  memoryEnabled: z.boolean().optional()
+  memoryEnabled: z.boolean().optional(),
+  transcription: WorkspaceTranscriptionPolicy.optional()
 }).passthrough();
 function resolveWorkspaceMemoryEnabled(settings) {
   const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
   return parsed.success ? parsed.data.memoryEnabled === true : false;
 }
 var UpdateWorkspaceSettingsRequest = z.object({
-  memoryEnabled: z.boolean().optional()
+  memoryEnabled: z.boolean().optional(),
+  transcription: WorkspaceTranscriptionPolicy.optional()
 }).passthrough();
 var SetWorkspaceDefaultRigRequest = z.object({
   rigId: z.string().uuid().nullable()
@@ -507,6 +1388,52 @@ var UpdateWorkspaceModelPolicyRequest = z.object({
   allowedProviders: z.array(z.string().min(1).max(128)).max(64).nullable().optional(),
   allowedModels: z.array(z.string().min(1).max(256)).max(256).nullable().optional()
 });
+var turnInitiatorIdentityFields = {
+  subjectId: z.string().min(1),
+  /** Immutable display snapshot; never an authorization input. */
+  label: z.string().min(1).optional()
+};
+var UNATTRIBUTED_LEGACY_INITIATOR_SUBJECT_ID = "unattributed-legacy";
+var ServiceTurnInitiator = z.object({
+  kind: z.literal("service"),
+  subjectId: z.string().min(1).max(1024).refine((value) => value !== UNATTRIBUTED_LEGACY_INITIATOR_SUBJECT_ID, {
+    message: "unattributed-legacy is reserved for migrated rows"
+  }),
+  /** Immutable display snapshot; never an authorization input. */
+  label: z.string().min(1).max(256).optional()
+});
+var TurnInitiatorContext = z.record(z.string(), z.unknown());
+var reservedServiceTurnInitiatorContextKeys = /* @__PURE__ */ new Set([
+  "backfill",
+  "label",
+  "provenanceError",
+  "via",
+  "viaTruncated"
+]);
+var ServiceTurnInitiatorContext = TurnInitiatorContext.superRefine((value, ctx) => {
+  for (const key of reservedServiceTurnInitiatorContextKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [key],
+        message: `${key} is reserved OpenGeni initiator context`
+      });
+    }
+  }
+  try {
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > 4096) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "service initiator context exceeds 4096 UTF-8 bytes"
+      });
+    }
+  } catch {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "service initiator context must be JSON-serializable"
+    });
+  }
+});
 var AccountGrant = z.object({
   accountId: z.string().uuid(),
   subjectId: z.string().min(1),
@@ -521,7 +1448,11 @@ var AccessGrant = z.object({
   subjectId: z.string().min(1),
   subjectLabel: z.string().optional(),
   permissions: z.array(Permission),
-  metadata: z.record(z.string(), z.unknown()).optional()
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  // Optional trusted causal principal for a command submitted by an embedding
+  // host. Authorization still uses subjectId + permissions above.
+  serviceInitiator: ServiceTurnInitiator.optional(),
+  serviceInitiatorContext: ServiceTurnInitiatorContext.optional()
 });
 var AccessContext = z.object({
   mode: ProductAccessMode,
@@ -538,6 +1469,11 @@ var DelegatedAccessTokenPayload = z.object({
   subjectId: z.string().min(1),
   subjectLabel: z.string().optional(),
   permissions: z.array(Permission).min(1),
+  // Trusted embedding hosts can sign a causal service principal separately
+  // from the grant subject that authorizes the request. The claim is consumed
+  // only when a command creates a new session/turn.
+  serviceInitiator: ServiceTurnInitiator.optional(),
+  serviceInitiatorContext: ServiceTurnInitiatorContext.optional(),
   // Worker-asserted session scope for first-party MCP calls (HMAC-signed, not
   // agent-controlled); enables session-scoped tools such as goal management.
   sessionId: z.string().uuid().optional(),
@@ -547,36 +1483,71 @@ var DelegatedAccessTokenPayload = z.object({
   // sacred-pause guard must know if the CALLER is a machine child-notification
   // turn, and the active pointer can flip to another turn mid-check.
   turnId: z.string().uuid().optional(),
+  // Exact execution owner. Agent control commands are accepted only while this
+  // attempt still owns the signed turn.
+  attemptId: z.string().uuid().optional(),
+  executionGeneration: z.number().int().positive().optional(),
   exp: z.number().int().positive()
+}).superRefine((payload, ctx) => {
+  if (payload.serviceInitiatorContext && !payload.serviceInitiator) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["serviceInitiatorContext"],
+      message: "serviceInitiatorContext requires serviceInitiator"
+    });
+  }
+  if (payload.serviceInitiator && (payload.turnId !== void 0 || payload.attemptId !== void 0 || payload.executionGeneration !== void 0)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["serviceInitiator"],
+      message: "serviceInitiator cannot replace an exact agent-attempt initiator"
+    });
+  }
 });
+var delegatedAccessTokenPrefix = "ogd_";
+var delegatedServiceAccessTokenPrefix = "ogd2_";
 async function signDelegatedAccessToken(secret, payload) {
-  const encodedPayload = base64UrlEncode(
-    JSON.stringify(DelegatedAccessTokenPayload.parse(payload))
+  const parsed = DelegatedAccessTokenPayload.parse(payload);
+  const prefix = parsed.serviceInitiator ? delegatedServiceAccessTokenPrefix : delegatedAccessTokenPrefix;
+  const encodedPayload = base64UrlEncode(JSON.stringify(parsed));
+  const signature = await hmacSha256Base64Url(
+    secret,
+    prefix === delegatedServiceAccessTokenPrefix ? `${prefix}${encodedPayload}` : encodedPayload
   );
-  const signature = await hmacSha256Base64Url(secret, encodedPayload);
-  return `ogd_${encodedPayload}.${signature}`;
+  return `${prefix}${encodedPayload}.${signature}`;
 }
 async function verifyDelegatedAccessToken(secret, token, nowSeconds = Math.floor(Date.now() / 1e3)) {
-  if (!token.startsWith("ogd_")) {
+  const prefix = token.startsWith(delegatedServiceAccessTokenPrefix) ? delegatedServiceAccessTokenPrefix : token.startsWith(delegatedAccessTokenPrefix) ? delegatedAccessTokenPrefix : null;
+  if (!prefix) {
     return null;
   }
-  const withoutPrefix = token.slice("ogd_".length);
+  const withoutPrefix = token.slice(prefix.length);
   const dot = withoutPrefix.lastIndexOf(".");
   if (dot <= 0) {
     return null;
   }
   const encodedPayload = withoutPrefix.slice(0, dot);
   const signature = withoutPrefix.slice(dot + 1);
-  const expected = await hmacSha256Base64Url(secret, encodedPayload);
+  const expected = await hmacSha256Base64Url(
+    secret,
+    prefix === delegatedServiceAccessTokenPrefix ? `${prefix}${encodedPayload}` : encodedPayload
+  );
   if (!constantTimeEqual(signature, expected)) {
     return null;
   }
-  const payload = DelegatedAccessTokenPayload.safeParse(
-    JSON.parse(base64UrlDecode(encodedPayload))
-  );
+  let decoded;
+  try {
+    decoded = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch {
+    return null;
+  }
+  const payload = DelegatedAccessTokenPayload.safeParse(decoded);
   if (!payload.success || payload.data.exp < nowSeconds) {
     return null;
   }
+  if (prefix === delegatedServiceAccessTokenPrefix !== (payload.data.serviceInitiator !== void 0)) {
+    return null;
+  }
   return payload.data;
 }
 var EnrollmentBearerPayload = z.object({
@@ -865,7 +1836,11 @@ var EntitlementValue = z.union([z.boolean(), z.string(), z.number(), z.array(z.s
 var Entitlements = z.record(z.string().min(1), EntitlementValue);
 var LimitDecision = z.discriminatedUnion("allowed", [
   z.object({ allowed: z.literal(true) }),
-  z.object({ allowed: z.literal(false), code: z.string(), message: z.string() })
+  z.object({
+    allowed: z.literal(false),
+    code: z.string(),
+    message: z.string()
+  })
 ]);
 var EntitlementDecision = z.discriminatedUnion("allowed", [
   z.object({ allowed: z.literal(true), quantity: z.number().optional() }),
@@ -877,9 +1852,13 @@ var EntitlementDecision = z.discriminatedUnion("allowed", [
   })
 ]);
 var GitCredentialProvider = z.enum(["github", "gitlab", "azure_devops"]);
+var GitCredentialBindingId = z.string().min(1).max(256);
+var GitRepositoryAccess = z.enum(["read", "write"]);
 var GitProviderRepositoryId = z.union([z.number().int().positive(), z.string().min(1)]);
 var GitCredentialRepositoryRef = z.object({
   provider: GitCredentialProvider.optional(),
+  credentialBindingId: GitCredentialBindingId.optional(),
+  access: GitRepositoryAccess.optional(),
   uri: z.string().min(1),
   ref: z.string().min(1),
   repositoryId: GitProviderRepositoryId.optional(),
@@ -887,6 +1866,56 @@ var GitCredentialRepositoryRef = z.object({
   projectId: GitProviderRepositoryId.optional(),
   connectionId: z.string().min(1).optional()
 });
+var McpConnectionResourceScope = z.object({
+  /** Provider-stable repository identity, serialized as a string on the wire. */
+  id: z.string().min(1).max(512),
+  kind: z.literal("repository")
+}).strict();
+var McpConnectionResourceScopes = z.array(McpConnectionResourceScope).min(1).max(256).superRefine((resources, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, resource] of resources.entries()) {
+    const key = `${resource.kind}\0${resource.id}`;
+    if (seen.has(key)) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources must not contain duplicates",
+        path: [index]
+      });
+    }
+    seen.add(key);
+  }
+});
+var McpServerConnectionRef = z.object({
+  /** Opaque host or standalone connection identifier. */
+  connectionId: z.string().min(1).optional(),
+  /** Stable provider family (for example github, gitlab, or azure_devops). */
+  provider: z.string().min(1).max(128).optional(),
+  /** Provider host or tenant domain. */
+  providerDomain: z.string().min(1),
+  kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
+  scopes: z.array(z.string().min(1)).optional(),
+  /** OAuth resource indicator. This is distinct from selectedResources. */
+  resource: z.string().min(1).optional(),
+  /** Exact provider resources this MCP binding is allowed to operate on. */
+  selectedResources: McpConnectionResourceScopes.optional(),
+  subjectScope: z.enum(["workspace", "subject"]).optional()
+}).strict().superRefine((reference, context) => {
+  if (!reference.selectedResources) return;
+  if (!reference.connectionId) {
+    context.addIssue({
+      code: "custom",
+      message: "selectedResources requires connectionId",
+      path: ["connectionId"]
+    });
+  }
+  if (!reference.provider) {
+    context.addIssue({
+      code: "custom",
+      message: "selectedResources requires provider",
+      path: ["provider"]
+    });
+  }
+});
 var BillingBalance = z.object({
   accountId: z.string().uuid(),
   balanceMicros: z.number().int(),
@@ -913,6 +1942,8 @@ var RepositoryResourceRef = z.object({
   mountPath: z.string().min(1).optional(),
   subpath: z.string().min(1).optional(),
   provider: GitCredentialProvider.optional(),
+  credentialBindingId: GitCredentialBindingId.optional(),
+  access: GitRepositoryAccess.optional(),
   repositoryId: GitProviderRepositoryId.optional(),
   installationId: GitProviderRepositoryId.optional(),
   projectId: GitProviderRepositoryId.optional(),
@@ -920,12 +1951,91 @@ var RepositoryResourceRef = z.object({
   githubInstallationId: z.number().int().positive().optional(),
   githubRepositoryId: z.number().int().positive().optional()
 });
+function positiveGitProviderInteger(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  if (typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0) {
+    return Number(value);
+  }
+  return null;
+}
+function gitCredentialProviderForRepository(resource) {
+  if (resource.provider) return resource.provider;
+  if (positiveGitProviderInteger(resource.githubInstallationId) && positiveGitProviderInteger(resource.githubRepositoryId)) {
+    return "github";
+  }
+  return null;
+}
+function gitCredentialBindingIdForRepository(resource, provider = gitCredentialProviderForRepository(resource)) {
+  if (!provider) return null;
+  const installationId = provider === "github" ? positiveGitProviderInteger(resource.githubInstallationId ?? resource.installationId) : null;
+  return resource.credentialBindingId ?? resource.connectionId ?? (installationId ? `github-installation:${installationId}` : provider);
+}
 var FileResourceRef = z.object({
   kind: z.literal("file"),
   fileId: z.string().uuid(),
   mountPath: z.string().min(1).optional()
 });
 var ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
+var ResourceMountPathError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ResourceMountPathError";
+  }
+};
+function normalizeResourceMountPath(path) {
+  const normalizedSeparators = path.trim().replace(/\\/g, "/");
+  if (!normalizedSeparators || normalizedSeparators.startsWith("/") || /^[A-Za-z]:\//.test(normalizedSeparators) || normalizedSeparators.includes("\0")) {
+    throw new ResourceMountPathError(`invalid resource mount path: ${path}`);
+  }
+  const segments = normalizedSeparators.split("/");
+  if (segments.some(
+    (segment) => !segment || segment === "." || segment === ".." || /[<>:"|?*\u0000-\u001f]/.test(segment) || /[ .]$/.test(segment) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(segment)
+  )) {
+    throw new ResourceMountPathError(`invalid resource mount path: ${path}`);
+  }
+  return segments.join("/");
+}
+function normalizeRepositorySubpath(path) {
+  const relative = path.trim().replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  return normalizeResourceMountPath(relative);
+}
+function resourceMountPathCollisionKey(path) {
+  return normalizeResourceMountPath(path).normalize("NFKC").toLowerCase();
+}
+function defaultRepositoryMountPath(uri) {
+  let url;
+  try {
+    url = new URL(uri);
+  } catch {
+    throw new ResourceMountPathError(`invalid repository URI for mount path: ${uri}`);
+  }
+  if (url.protocol !== "https:" || !url.host) {
+    throw new ResourceMountPathError(`invalid repository URI for mount path: ${uri}`);
+  }
+  const repositoryPath = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
+  const segments = repositoryPath.split("/").filter(Boolean);
+  if (segments.length < 2) {
+    throw new ResourceMountPathError(`repository URI must include owner and repo: ${uri}`);
+  }
+  return normalizeResourceMountPath(
+    `repos/${encodeURIComponent(url.host.toLowerCase())}/${segments.join("/")}`
+  );
+}
+function resourceMountPath(resource) {
+  if (resource.mountPath) return normalizeResourceMountPath(resource.mountPath);
+  return resource.kind === "file" ? normalizeResourceMountPath(`files/${resource.fileId}`) : defaultRepositoryMountPath(resource.uri);
+}
+function assertUniqueResourceMountPaths(resources) {
+  const mounted = /* @__PURE__ */ new Set();
+  for (const resource of resources) {
+    const path = resourceMountPath(resource);
+    const key = resourceMountPathCollisionKey(path);
+    if (mounted.has(key)) {
+      throw new ResourceRefConflictError(`resource mount path is already attached: ${path}`);
+    }
+    mounted.add(key);
+  }
+}
 var FileStatus = z.enum(["pending_upload", "ready", "failed", "expired", "deleted"]);
 var FileUploadStatus = z.enum([
   "pending",
@@ -1194,7 +2304,10 @@ var SessionMcpServerInput = z.object({
   requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
   // Write-only credential headers. Values are encrypted at rest and never
   // returned in session responses or events; response metadata exposes names.
-  headers: z.record(z.string(), z.string()).optional()
+  headers: z.record(z.string(), z.string()).optional(),
+  // Non-secret opaque pointer resolved at request time by the standalone
+  // connection broker or an embedding host's mcpCredentials port.
+  connectionRef: McpServerConnectionRef.optional()
 });
 var SessionMcpCredentialUpdateInput = z.object({
   id: z.string().min(1).regex(registryId),
@@ -1205,7 +2318,8 @@ var SessionMcpServerMetadata = z.object({
   name: z.string().min(1).nullable(),
   url: httpsUrl,
   headerNames: z.array(z.string()).default([]),
-  credentialVersion: z.number().int().positive()
+  credentialVersion: z.number().int().positive(),
+  connectionRef: McpServerConnectionRef.nullable().default(null)
 }).strict();
 var ResourceRefConflictError = class extends Error {
   constructor(message) {
@@ -1232,10 +2346,13 @@ function mergeToolRefs(existing, additions) {
   return order.map((key) => byKey.get(key));
 }
 function mergeResourceRefs(existing, additions, options = {}) {
+  if (options.rejectConflicts) {
+    assertUniqueResourceMountPaths(existing);
+  }
   const out = [...existing];
   const mountPaths = new Map(
-    existing.flatMap(
-      (resource) => resource.mountPath ? [[resource.mountPath, stableJson(resource)]] : []
+    existing.map(
+      (resource) => [resourceMountPathCollisionKey(resourceMountPath(resource)), stableJson(resource)]
     )
   );
   const identities = new Map(
@@ -1248,11 +2365,10 @@ function mergeResourceRefs(existing, additions, options = {}) {
       continue;
     }
     if (options.rejectConflicts) {
-      const existingAtMount = resource.mountPath ? mountPaths.get(resource.mountPath) : void 0;
+      const mountPath = resourceMountPath(resource);
+      const existingAtMount = mountPaths.get(resourceMountPathCollisionKey(mountPath));
       if (existingAtMount && existingAtMount !== serialized) {
-        throw new ResourceRefConflictError(
-          `resource mount path is already attached: ${resource.mountPath}`
-        );
+        throw new ResourceRefConflictError(`resource mount path is already attached: ${mountPath}`);
       }
       const identity = resourceIdentityKey(resource);
       const existingIdentity = identities.get(identity);
@@ -1265,9 +2381,7 @@ function mergeResourceRefs(existing, additions, options = {}) {
     out.push(resource);
     exact.add(serialized);
     identities.set(resourceIdentityKey(resource), serialized);
-    if (resource.mountPath) {
-      mountPaths.set(resource.mountPath, serialized);
-    }
+    mountPaths.set(resourceMountPathCollisionKey(resourceMountPath(resource)), serialized);
   }
   return out;
 }
@@ -1304,7 +2418,8 @@ var SessionTurnStatus = z.enum([
   "completed",
   "failed",
   "cancelled",
-  "superseded"
+  "superseded",
+  "withdrawn_for_edit"
 ]);
 var SessionTurnSource = z.enum([
   "user",
@@ -1366,7 +2481,9 @@ var ClearSessionContextRequest = z.object({
   confirm: z.literal(true)
 });
 var CLEARED_RUN_STATE_MARKER = "$opengeniCleared";
-var CLEARED_RUN_STATE_BLOB = JSON.stringify({ [CLEARED_RUN_STATE_MARKER]: true });
+var CLEARED_RUN_STATE_BLOB = JSON.stringify({
+  [CLEARED_RUN_STATE_MARKER]: true
+});
 function isClearedRunStateBlob(serialized) {
   if (!serialized) {
     return false;
@@ -1386,6 +2503,104 @@ var CompactSessionContextResult = z.object({
   status: z.enum(["pending", "completed", "noop"]),
   message: z.string()
 });
+var TurnInitiator = z.object({
+  kind: z.enum(["subject", "service"]),
+  ...turnInitiatorIdentityFields
+});
+var SessionAuthorizationSurface = z.enum([
+  "http",
+  "core",
+  "stream",
+  "first_party_mcp",
+  "toolspace"
+]);
+var SessionAuthorizationOperation = z.enum([
+  "session.read",
+  "session.events.read",
+  "session.stream.read",
+  "session.stream.acknowledge",
+  "session.turns.read",
+  "session.append",
+  "session.steer",
+  "session.control",
+  "session.queue.read",
+  "session.queue.control",
+  "session.composer.read",
+  "session.composer.write",
+  "session.lineage.read",
+  "session.capture.read",
+  "session.files.read",
+  "session.files.write",
+  "session.git.read",
+  "session.terminal.read",
+  "session.terminal.control",
+  "session.viewer.read",
+  "session.viewer.control",
+  "session.first_party_mcp.call",
+  "session.toolspace.call",
+  "session.pin.write",
+  "session.codex_account.write",
+  "session.context.write",
+  "session.approval.write",
+  "session.human_input.read",
+  "session.human_input.write",
+  "session.title.write",
+  "session.goal.read",
+  "session.goal.write",
+  "session.child.create"
+]);
+var SessionAuthorizationActor = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("subject"),
+    subjectId: z.string().min(1),
+    subjectLabel: z.string().min(1).optional()
+  }),
+  z.object({
+    kind: z.literal("agent_attempt"),
+    /** Technical, authenticated first-party caller (not the host authority). */
+    subjectId: z.string().min(1),
+    callerSessionId: z.string().uuid(),
+    callerRootSessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    /** Frozen authority that admitted the calling turn. */
+    initiator: TurnInitiator,
+    initiatorContext: TurnInitiatorContext
+  })
+]);
+var SessionAuthorizationTarget = z.object({
+  sessionId: z.string().uuid(),
+  /** Server-resolved workspace lineage root; never accepted from a caller. */
+  rootSessionId: z.string().uuid()
+});
+var SessionAuthorizationDecision = z.discriminatedUnion("allowed", [
+  z.object({
+    allowed: z.literal(true),
+    /**
+     * Whether related-session metadata may be projected with the target.
+     * `target` is the fail-closed default for exact shares; `root` permits the
+     * target's full lineage tree. This does not authorize a separate operation
+     * against another session, which always requires its own decision.
+     */
+    relatedSessionAccess: z.enum(["target", "root"]).optional(),
+    /** A host may request a tighter stream reauthorization bound. */
+    reauthorizeAfterMs: z.number().int().min(1e3).max(6e4).optional()
+  }),
+  z.object({
+    allowed: z.literal(false),
+    reason: z.enum(["not_found", "forbidden", "revoked"])
+  })
+]);
+var SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS = 1e4;
+var SessionAuthorizationListScope = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("all") }),
+  z.object({
+    kind: z.literal("scoped"),
+    rootSessionIds: z.array(z.string().uuid()).max(SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS),
+    sessionIds: z.array(z.string().uuid()).max(SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS)
+  })
+]);
 var SessionTurn = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -1408,6 +2623,8 @@ var SessionTurn = z.object({
   executionGeneration: z.number().int().nonnegative(),
   activeAttemptId: z.string().uuid().nullable(),
   lineage: z.record(z.string(), z.unknown()),
+  initiator: TurnInitiator,
+  initiatorContext: TurnInitiatorContext,
   cancelledBy: z.string().nullable(),
   cancelReason: z.string().nullable(),
   startedAt: z.string().nullable(),
@@ -1415,56 +2632,311 @@ var SessionTurn = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var EffectiveControlBlocker = z.object({
+  kind: z.enum(["session", "workspace"]),
+  sessionId: z.string().uuid().optional(),
+  displayName: z.string().min(1),
+  actor: z.string().nullable(),
+  reason: z.string().nullable(),
+  changedAt: z.string().nullable(),
+  revision: z.number().int().nonnegative()
+});
+var EffectiveControlResumeOption = z.object({
+  scope: z.enum(["selected", "session", "workspace"]),
+  targetId: z.string().uuid().optional(),
+  selectedStateAfter: SessionControlState,
+  remainingPrimaryBlocker: EffectiveControlBlocker.optional(),
+  impactCopy: z.string().min(1)
+});
+var EffectiveSessionControl = z.object({
+  state: SessionControlState,
+  controlVersion: z.number().int().nonnegative(),
+  controlEtag: z.string().min(1),
+  directState: SessionControlState,
+  primaryBlocker: EffectiveControlBlocker.nullable(),
+  additionalBlockerCount: z.number().int().nonnegative(),
+  blockers: z.array(EffectiveControlBlocker),
+  resumeOptions: z.array(EffectiveControlResumeOption),
+  override: z.object({
+    rootSessionId: z.string().uuid(),
+    revision: z.number().int().nonnegative()
+  }).nullable(),
+  settlement: z.object({
+    state: z.literal("stopping"),
+    attemptCount: z.number().int().positive(),
+    interruptionPendingCount: z.number().int().nonnegative(),
+    quiescencePendingCount: z.number().int().nonnegative()
+  }).nullable()
+});
+var SESSION_OPERATION_KEY_MAX_CHARS = 256;
+var SessionOperationKey = z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS);
+var SessionCommandReceipt = z.object({
+  id: z.string().uuid(),
+  action: z.string().min(1),
+  operationKey: z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS),
+  targetSessionId: z.string().uuid().nullable(),
+  targetTurnId: z.string().uuid().nullable(),
+  appliedControlRevision: z.number().int().nonnegative().nullable(),
+  appliedQueueVersion: z.number().int().nonnegative().nullable(),
+  appliedTurnVersion: z.number().int().positive().nullable(),
+  appliedDraftRevision: z.number().int().positive().nullable(),
+  createdAt: z.string()
+});
+var ComposerDraft = z.object({
+  revision: z.number().int().nonnegative(),
+  text: z.string(),
+  resources: z.array(ResourceRef),
+  tools: z.array(ToolRef),
+  model: z.string().min(1),
+  reasoningEffort: ReasoningEffort,
+  sourceTurnId: z.string().uuid().nullable(),
+  sourceTurnVersion: z.number().int().positive().nullable(),
+  updatedAt: z.string().nullable()
+});
 var SessionQueueSnapshot = z.object({
   version: z.number().int().nonnegative(),
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  workspaceInferenceState: WorkspaceInferenceState,
-  workspaceInferenceGeneration: z.number().int().nonnegative(),
-  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
+  effectiveControl: EffectiveSessionControl,
+  /**
+   * True while the latest attempt is interrupted but has not durably proved
+   * quiescence: no more inference, user-visible output, or workspace-persistence
+   * authority. Temporal cancellation/terminalization is not that proof. This is
+   * distinct from ordinary capacity queueing, remains accurate with an empty
+   * visible queue, and is independent of Steer-row metadata or withdrawal.
+   */
+  stoppingPreviousAttempt: z.boolean(),
   items: z.array(SessionTurn)
 });
-var CancelSessionQueueItemRequest = z.object({
+var MoveSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
   expectedQueueVersion: z.number().int().nonnegative(),
-  expectedItemVersion: z.number().int().positive(),
+  beforeTurnId: z.string().uuid().nullable()
+});
+var EditSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
+  expectedDraftRevision: z.number().int().nonnegative(),
+  replaceDraft: z.boolean()
+});
+var SteerSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
+  controlEtag: z.string().min(1).optional()
+});
+var DeleteSessionQueueItemRequest = z.object({
+  clientEventId: SessionOperationKey,
+  expectedTurnVersion: z.number().int().positive(),
   reason: z.string().min(1).optional()
 });
+var SaveComposerDraftRequest = ComposerDraft.pick({
+  text: true,
+  resources: true,
+  tools: true,
+  model: true,
+  reasoningEffort: true
+}).extend({ expectedRevision: z.number().int().nonnegative() });
+var WORKSPACE_CONTROL_REASON_MAX_BYTES = 8 * 1024;
+var WORKSPACE_CONTROL_ACTOR_MAX_BYTES = 1024;
+var WORKSPACE_CONTROL_EVENT_MAX_BYTES = 16 * 1024;
+var WorkspaceControlReason = z.string().min(1).refine((value) => !value.includes("\0"), "reason must not contain NUL bytes").refine(
+  (value) => workspaceControlUtf8Bytes(value) <= WORKSPACE_CONTROL_REASON_MAX_BYTES,
+  `reason must not exceed ${WORKSPACE_CONTROL_REASON_MAX_BYTES} UTF-8 bytes`
+);
 var SessionControlRequest = z.object({
-  mode: z.enum(["pause", "resume"]),
-  reason: z.string().min(1).optional(),
-  clientEventId: z.string().min(1).optional(),
-  expectedControlState: SessionControlState.optional(),
-  expectedControlGeneration: z.number().int().nonnegative().optional(),
-  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional()
+  action: z.enum(["pause", "resume"]),
+  reason: WorkspaceControlReason.optional(),
+  clientEventId: SessionOperationKey,
+  expectedControlEtag: z.string().min(1).optional()
 });
 var WorkspaceInferenceControlRequest = z.object({
-  state: WorkspaceInferenceState,
-  reason: z.string().min(1),
-  clientEventId: z.string().min(1),
-  expectedState: WorkspaceInferenceState,
-  expectedGeneration: z.number().int().nonnegative(),
-  exceptSessionIds: z.array(z.string().uuid()).default([])
+  action: z.enum(["pause", "resume"]),
+  reason: WorkspaceControlReason.optional(),
+  clientEventId: SessionOperationKey,
+  expectedRevision: z.number().int().nonnegative().optional()
 });
 var WorkspaceInferenceControlResponse = z.object({
-  operationId: z.string().uuid(),
-  state: WorkspaceInferenceState,
-  generation: z.number().int().nonnegative(),
-  affectedSessionIds: z.array(z.string().uuid()),
-  controlSessionIds: z.array(z.string().uuid()),
-  exceptionSessionIds: z.array(z.string().uuid())
+  receipt: SessionCommandReceipt,
+  state: SessionControlState,
+  revision: z.number().int().nonnegative(),
+  interruptionCount: z.number().int().nonnegative(),
+  wakeCount: z.number().int().nonnegative()
+});
+var WorkspaceControlEventTruncation = z.object({
+  truncated: z.literal(true),
+  surface: z.enum([
+    "durable_control",
+    "database_guard",
+    "http_projection",
+    "nats_legacy_guard",
+    "sse_legacy_guard"
+  ]),
+  deliveredBytes: z.number().int().nonnegative(),
+  fields: z.array(
+    z.object({
+      field: z.enum(["reason", "actor"]),
+      originalBytes: z.number().int().nonnegative(),
+      deliveredBytes: z.number().int().nonnegative(),
+      omittedBytes: z.number().int().nonnegative()
+    })
+  ),
+  fullEvidence: z.object({
+    available: z.literal(false),
+    reason: z.literal("not_retained")
+  })
+});
+var WorkspaceControlEvent = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sequence: z.number().int().positive(),
+  revision: z.number().int().positive(),
+  type: z.literal("workspace.control.changed"),
+  scope: z.enum(["workspace", "session"]),
+  rootSessionId: z.string().uuid().nullable(),
+  action: z.enum(["pause", "resume"]),
+  automatic: z.boolean(),
+  reason: z.string().nullable(),
+  actor: z.string().min(1),
+  occurredAt: z.string(),
+  truncation: WorkspaceControlEventTruncation.nullable().optional()
 });
+function workspaceControlUtf8Bytes(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function boundWorkspaceControlEvent(event, options = {}) {
+  const existingFields = new Map(
+    (event.truncation?.fields ?? []).map((field) => [field.field, field])
+  );
+  const reason = event.reason === null ? null : boundWorkspaceControlText(event.reason, WORKSPACE_CONTROL_REASON_MAX_BYTES);
+  const actor = boundWorkspaceControlText(event.actor, WORKSPACE_CONTROL_ACTOR_MAX_BYTES);
+  const reasonBytes = reason === null ? 0 : workspaceControlUtf8Bytes(reason);
+  const actorBytes = workspaceControlUtf8Bytes(actor);
+  const reasonOriginalBytes = event.reason === null ? null : Math.max(
+    workspaceControlUtf8Bytes(event.reason),
+    normalizedWorkspaceControlOriginalBytes(options.reasonOriginalBytes),
+    existingFields.get("reason")?.originalBytes ?? 0
+  );
+  const actorOriginalBytes = Math.max(
+    workspaceControlUtf8Bytes(event.actor),
+    normalizedWorkspaceControlOriginalBytes(options.actorOriginalBytes),
+    existingFields.get("actor")?.originalBytes ?? 0
+  );
+  const fields = [];
+  if (reasonOriginalBytes !== null && reasonOriginalBytes > reasonBytes) {
+    fields.push({
+      field: "reason",
+      originalBytes: reasonOriginalBytes,
+      deliveredBytes: reasonBytes,
+      omittedBytes: reasonOriginalBytes - reasonBytes
+    });
+  }
+  if (actorOriginalBytes > actorBytes) {
+    fields.push({
+      field: "actor",
+      originalBytes: actorOriginalBytes,
+      deliveredBytes: actorBytes,
+      omittedBytes: actorOriginalBytes - actorBytes
+    });
+  }
+  if (fields.length === 0 && event.truncation == null) {
+    if (sessionEventJsonBytes(event) > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+      throw new RangeError("Workspace control event exceeds its bounded envelope");
+    }
+    return event;
+  }
+  const truncation = {
+    truncated: true,
+    surface: event.truncation?.surface ?? options.surface ?? "durable_control",
+    deliveredBytes: 0,
+    fields,
+    fullEvidence: { available: false, reason: "not_retained" }
+  };
+  const bounded = {
+    ...event,
+    reason,
+    actor,
+    truncation
+  };
+  settleWorkspaceControlDeliveredBytes(bounded, truncation);
+  const deliveredBytes = sessionEventJsonBytes(bounded);
+  if (deliveredBytes > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+    throw new RangeError(
+      `Bounded workspace control event exceeds its final envelope (${deliveredBytes} > ${WORKSPACE_CONTROL_EVENT_MAX_BYTES} bytes)`
+    );
+  }
+  return bounded;
+}
+function boundWorkspaceControlText(value, maxBytes) {
+  const encoder2 = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder2.encode(value);
+  if (bytes.byteLength <= maxBytes) return value;
+  const marker = "\u2026[truncated]";
+  const prefixBudget = Math.max(0, maxBytes - encoder2.encode(marker).byteLength);
+  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
+  while (prefixEnd > 0 && prefixEnd < bytes.byteLength && (bytes[prefixEnd] & 192) === 128) {
+    prefixEnd -= 1;
+  }
+  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
+}
+function normalizedWorkspaceControlOriginalBytes(value) {
+  return value === null || value === void 0 || !Number.isFinite(value) ? 0 : Math.max(0, Math.floor(value));
+}
+function settleWorkspaceControlDeliveredBytes(event, truncation) {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const deliveredBytes2 = sessionEventJsonBytes(event);
+    if (truncation.deliveredBytes === deliveredBytes2) return;
+    truncation.deliveredBytes = deliveredBytes2;
+  }
+  const deliveredBytes = sessionEventJsonBytes(event);
+  if (truncation.deliveredBytes !== deliveredBytes) {
+    throw new RangeError("Workspace control event byte accounting did not converge");
+  }
+}
 var SystemUpdateClassification = z.enum(["success", "failure", "action_required", "info"]);
 var SessionSystemUpdateKind = z.enum([
-  "child_session_update",
-  "scheduled_wake",
-  "lifecycle_event",
-  "runtime_notice"
+  "scheduled_occurrence",
+  "goal_continuation",
+  "agent_message",
+  "agent_steer_instruction",
+  "child_terminal_result"
+]);
+var SessionSystemUpdatePayload = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("scheduled_occurrence"),
+    text: z.string().min(1),
+    scheduledTaskId: z.string().uuid(),
+    scheduledTaskRunId: z.string().uuid(),
+    resources: z.array(ResourceRef).optional(),
+    tools: z.array(ToolRef).optional()
+  }).passthrough(),
+  z.object({
+    type: z.literal("goal_continuation"),
+    goalId: z.string().uuid(),
+    goalVersion: z.number().int().positive(),
+    prompt: z.string().min(1),
+    reason: z.string().optional()
+  }).passthrough(),
+  z.object({
+    type: z.literal("agent_message"),
+    text: z.string().min(1),
+    operationId: z.string().uuid()
+  }).passthrough(),
+  z.object({
+    type: z.literal("agent_steer_instruction"),
+    instruction: z.string().min(1),
+    operationId: z.string().uuid()
+  }).passthrough(),
+  z.object({
+    type: z.literal("child_terminal_result"),
+    childSessionId: z.string().uuid(),
+    status: z.enum(["idle", "failed"])
+  }).passthrough()
 ]);
 var SessionSystemUpdateState = z.enum([
   "pending",
   "deferred",
   "delivered",
   "cancelled",
+  "superseded",
   "failed"
 ]);
 var SessionSystemUpdate = z.object({
@@ -1475,7 +2947,7 @@ var SessionSystemUpdate = z.object({
   sourceId: z.string(),
   dedupeKey: z.string(),
   summary: z.string(),
-  payload: z.record(z.string(), z.unknown()),
+  payload: SessionSystemUpdatePayload,
   lineage: z.record(z.string(), z.unknown()),
   state: SessionSystemUpdateState,
   deliveredTurnId: z.string().uuid().nullable(),
@@ -1628,7 +3100,10 @@ var RigDefinitionEditPayload = z.object({
 });
 var ProposeRigChangeRequest = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("setup_append"), payload: RigSetupAppendPayload }),
-  z.object({ kind: z.literal("definition_edit"), payload: RigDefinitionEditPayload })
+  z.object({
+    kind: z.literal("definition_edit"),
+    payload: RigDefinitionEditPayload
+  })
 ]);
 var ScheduledTaskStatus = z.enum(["active", "paused"]);
 var ScheduledTaskRunStatus = z.enum(["queued", "dispatched", "failed"]);
@@ -1958,14 +3433,6 @@ var CreateSocialPostRequest = z.object({
 });
 var ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
 var ConnectionStatus = z.enum(["active", "needs_reauth", "revoked", "error"]);
-var McpServerConnectionRef = z.object({
-  connectionId: z.string().uuid().optional(),
-  providerDomain: z.string().min(1),
-  kind: ConnectionKind.optional(),
-  scopes: z.array(z.string().min(1)).optional(),
-  resource: z.string().min(1).optional(),
-  subjectScope: z.enum(["workspace", "subject"]).optional()
-}).strict();
 var ConnectionMetadata = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -2056,6 +3523,7 @@ var MarketingDailyAnalysisTaskRequest = z.object({
 var CapabilityKind = z.enum(["pack", "mcp", "api", "skill", "plugin"]);
 var CapabilitySource = z.enum([
   "built_in",
+  "library",
   "configured",
   "public_registry",
   "registry",
@@ -2183,6 +3651,9 @@ var Session = z.object({
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
   metadata: z.record(z.string(), z.unknown()),
+  /** Frozen creator fact used only for creation attribution/idempotent repair. */
+  createdBy: TurnInitiator,
+  createdByContext: TurnInitiatorContext,
   model: z.string(),
   sandboxBackend: SandboxBackend,
   // The OS the session's box runs. Defaults to 'linux' (today's only OS).
@@ -2232,12 +3703,7 @@ var Session = z.object({
   queueVersion: z.number().int().nonnegative(),
   queueHeadPosition: z.number().int(),
   queueTailPosition: z.number().int(),
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  controlReason: z.string().nullable(),
-  controlChangedBy: z.string().nullable(),
-  controlChangedAt: z.string().nullable(),
-  workspaceRunExceptionGeneration: z.number().int().nonnegative().nullable(),
+  effectiveControl: EffectiveSessionControl,
   lastSequence: z.number().int().nonnegative(),
   // Multi-account Codex (P1). codexPinnedCredentialId: the account this session is
   // manually PINNED to (null ⇒ follow the workspace active pointer).
@@ -2263,13 +3729,20 @@ var Session = z.object({
     queuedDescendants: z.number().int().nonnegative(),
     attentionDescendants: z.number().int().nonnegative(),
     pausedDescendants: z.number().int().nonnegative(),
-    failedDescendants: z.number().int().nonnegative()
+    failedDescendants: z.number().int().nonnegative(),
+    /** Counts are lower bounds rather than exact totals when true. */
+    truncated: z.boolean().default(false)
   }).optional(),
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var CreateSessionResponse = Session.extend({
+  initialTurnId: z.string().uuid().nullable()
+});
 var SessionListResponse = z.object({
   pinned: z.array(Session),
+  /** True when older matching pins were omitted from this bounded page. */
+  pinnedTruncated: z.boolean().optional(),
   sessions: z.array(Session),
   nextCursor: z.string().nullable()
 });
@@ -2286,8 +3759,14 @@ var SessionLineageResponse = z.object({
 });
 var SessionEventType = z.enum([
   "session.created",
+  // Defensive read/transport projection for a malformed or historically
+  // oversized retained event envelope. The original row stays durable; this
+  // explicit synthetic type prevents unbounded free-form envelope fields from
+  // crossing NATS, SSE, REST, or browser boundaries.
+  "session.event.envelope_omitted",
   "session.status.changed",
   "session.requiresAction",
+  "session.humanInput.requested",
   "session.context.compaction.requested",
   "session.context.compacted",
   "session.context.compaction.skipped",
@@ -2295,6 +3774,7 @@ var SessionEventType = z.enum([
   "user.message",
   "user.pause",
   "user.approvalDecision",
+  "user.humanInputResponse",
   "turn.queued",
   "turn.started",
   "turn.completed",
@@ -2310,6 +3790,7 @@ var SessionEventType = z.enum([
   "agent.toolCall.output",
   "agent.model.usage",
   "tool.auth_needed",
+  "credential.auth_needed",
   "agent.updated",
   "rig.setup.started",
   "rig.setup.completed",
@@ -2334,6 +3815,7 @@ var SessionEventType = z.enum([
   "session.control.steer_requested",
   "workspace.inference.paused",
   "workspace.inference.resumed",
+  "session.queue.changed",
   "session.queue.prompt.cancelled",
   "session.queue.history",
   // A terminal/stale activity callback is retained as an audit wrapper rather
@@ -2352,8 +3834,8 @@ var SessionEventType = z.enum([
   // a viewer detached / was reaped
   "stream.revoked",
   // a grant was revoked → connected clients MUST disconnect now
-  // Channel-B recording signals (P4.3 / module 05 §3.4). The "agent films itself
-  // proving the fix" loop: ffmpeg x11grab of the SAME :0 humans watch → artifact
+  // Desktop recording signals. The capture loop records the same display humans
+  // watch, then stores the finalized artifact for replay.
   // → storage. The artifact ref rides the AVAILABLE event (storageKey, NOT a
   // long-lived URL — clients mint a short-TTL signed GET via the route).
   "recording.started",
@@ -2362,8 +3844,8 @@ var SessionEventType = z.enum([
   // finalized: bytes PUT to storage, replayable
   "recording.failed",
   // ffmpeg/box-death/rollover/upload error — no artifact
-  // Channel-A structured-service notifications (P4.4 / modules/08-channel-a.md
-  // §2.2). The A2 reads (fs/git/terminal exec) are SYNCHRONOUS API-direct point
+  // Structured-service notifications. File, Git, and terminal reads are
+  // synchronous API-direct point
   // queries (their result is the HTTP response, NEVER an event). What rides A1
   // here are the side-effect NOTIFICATIONS — a path changed, git state changed,
   // a pty opened/printed/exited — durable, sequenced, gap-filled like every
@@ -2385,10 +3867,10 @@ var SessionEventType = z.enum([
   // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
   // the in-session "Running on:" indicator's live flip.
   "codex.account.switched",
-  // OPE-21 per-turn selection audit. Payload is metadata only: credential row
+  // credential allocator per-turn selection audit. Payload is metadata only: credential row
   // id, bounded strategy/reason, and pool counts — never token material.
   "codex.credential.selected",
-  // OPE-21 durable zero-capacity wait lifecycle. Runtime/system events only;
+  // credential allocator durable zero-capacity wait lifecycle. Runtime/system events only;
   // no synthetic user message is created when capacity returns.
   "codex.capacity.waiting",
   "codex.capacity.resumed",
@@ -2418,12 +3900,12 @@ var SessionEventType = z.enum([
   // target id or command content. Announce-only; hits the timeline projection default
   // (no rendered item) like the other sandbox.* diagnostics.
   "session.route.reconciled",
-  // Workbench v2 turn-end workspace capture (dossier §10.1). ANNOUNCE-ONLY: a new
+  // Workbench v2 turn-end workspace capture. ANNOUNCE-ONLY: a new
   // capture revision was persisted at turn end; the client refetches the latest
   // capture. It carries metadata only (revision/turnId/capturedAt/leaseEpoch/stats),
   // never file content. Hits the timeline projection default case (ignored) — it
   // must NEVER gain a rendered timeline item without regenerating the golden
-  // snapshots (dossier §7.3 golden-grammar gate).
+  // snapshots (golden-grammar gate).
   "workspace.revision.captured",
   // Repository discovery could not prove a complete capture. The worker
   // persisted a failed/degraded revision marker and clients must fall back to
@@ -2463,17 +3945,160 @@ var SessionEventType = z.enum([
   "machine.link.restored",
   "machine.runner.restarted"
 ]);
+var SessionEventSemanticClass = z.enum([
+  "control",
+  "terminal",
+  "failure",
+  "checkpoint",
+  "tool_receipt",
+  "provider_account"
+]);
+var SessionEventPayloadMode = z.enum(["none", "summary", "full"]);
+var SessionEventReadMode = z.enum(["monitoring", "forensic"]);
+var SessionEventReadDirection = z.enum(["after", "before"]);
+var SESSION_EVENT_RAW_DELTA_TYPES = [
+  "agent.message.delta",
+  "agent.reasoning.delta",
+  "sandbox.command.output.delta",
+  "terminal.pty.output.delta"
+];
+var SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
+  control: [
+    "session.status.changed",
+    "session.requiresAction",
+    "session.humanInput.requested",
+    "user.pause",
+    "user.approvalDecision",
+    "user.humanInputResponse",
+    "goal.set",
+    "goal.updated",
+    "goal.completed",
+    "goal.paused",
+    "goal.resumed",
+    "goal.cleared",
+    "goal.continuation",
+    "system.update.pending",
+    "system.update.delivered",
+    "session.control.paused",
+    "session.control.resumed",
+    "session.control.steer_requested",
+    "workspace.inference.paused",
+    "workspace.inference.resumed",
+    "session.queue.changed",
+    "session.queue.prompt.cancelled"
+  ],
+  terminal: [
+    "turn.completed",
+    "turn.failed",
+    "turn.cancelled",
+    "turn.superseded",
+    "goal.completed",
+    "goal.paused",
+    "rig.setup.completed",
+    "rig.setup.skipped",
+    "rig.setup.failed",
+    "sandbox.operation.completed",
+    "sandbox.operation.failed",
+    "recording.available",
+    "recording.failed",
+    "terminal.pty.exited"
+  ],
+  failure: [
+    "session.event.envelope_omitted",
+    "turn.failed",
+    "tool.auth_needed",
+    "credential.auth_needed",
+    "rig.setup.failed",
+    "sandbox.operation.failed",
+    "recording.failed",
+    "sandbox.box.lost",
+    "workspace.revision.degraded",
+    "machine.op.failed",
+    "machine.link.lost"
+  ],
+  checkpoint: [
+    "session.context.compaction.requested",
+    "session.context.compacted",
+    "session.context.compaction.skipped",
+    "session.context.cleared",
+    "turn.recovery.requested",
+    "session.queue.history",
+    "sandbox.box.snapshot",
+    "workspace.revision.captured"
+  ],
+  tool_receipt: [
+    "agent.toolCall.created",
+    "agent.toolCall.output",
+    "tool.auth_needed",
+    "artifact.created"
+  ],
+  provider_account: [
+    "agent.model.usage",
+    "codex.account.switched",
+    "codex.credential.selected",
+    "codex.capacity.waiting",
+    "codex.capacity.resumed",
+    "codex.capacity.superseded",
+    "sandbox.box.created",
+    "sandbox.box.lost",
+    "sandbox.box.terminated",
+    "sandbox.box.snapshot",
+    "sandbox.env.drift",
+    "session.route.reconciled",
+    "machine.op.failed",
+    "machine.op.recovered",
+    "machine.link.lost",
+    "machine.link.restored",
+    "machine.runner.restarted"
+  ]
+};
+function resolveSessionEventTypeFilters(input) {
+  const included = new Set(input.includeTypes ?? []);
+  for (const semanticClass of input.includeClasses ?? []) {
+    for (const type of SESSION_EVENT_SEMANTIC_CLASS_TYPES[semanticClass]) included.add(type);
+  }
+  const excluded = new Set(input.excludeTypes ?? []);
+  for (const semanticClass of input.excludeClasses ?? []) {
+    for (const type of SESSION_EVENT_SEMANTIC_CLASS_TYPES[semanticClass]) excluded.add(type);
+  }
+  for (const type of input.defaultExcludeTypes ?? []) {
+    if (!included.has(type)) excluded.add(type);
+  }
+  for (const type of excluded) included.delete(type);
+  return { includeTypes: [...included], excludeTypes: [...excluded] };
+}
 var ToolAuthNeededPayload = z.object({
   serverId: z.string().min(1),
   toolName: z.string().min(1).nullable().optional(),
   providerDomain: z.string().min(1),
-  connectionId: z.string().uuid().nullable().optional(),
-  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  provider: z.string().min(1).max(128).optional(),
+  // Embedded hosts may use an opaque connection identity; never assume an
+  // OpenGeni UUID on the public event wire.
+  connectionId: z.string().min(1).nullable().optional(),
+  reason: z.enum([
+    "missing_connection",
+    "expired",
+    "insufficient_scope",
+    "refresh_failed",
+    "unsupported_auth",
+    "resource_scope_unavailable"
+  ]),
   scopes: z.array(z.string().min(1)).optional(),
   resource: z.string().min(1).optional(),
+  selectedResources: McpConnectionResourceScopes.optional(),
   authorizationUrl: z.string().url().optional(),
   subjectId: z.string().min(1).nullable().optional()
 });
+var CredentialAuthNeededPayload = z.object({
+  credentialClass: z.literal("run"),
+  providerDomain: z.string().min(1).optional(),
+  connectionId: z.string().min(1).optional(),
+  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  authorizationUrl: z.string().url().optional(),
+  message: z.string().min(1).optional()
+});
 var StreamUrlRotatedPayload = z.object({
   url: z.string().url(),
   token: z.string().nullable(),
@@ -2671,7 +4296,9 @@ var FsDeleteRequest = z.object({
   recursive: z.boolean().default(false)
   // required true to delete a non-empty dir
 });
-var FsDeleteResponse = z.object({ revision: z.number().int().nonnegative() });
+var FsDeleteResponse = z.object({
+  revision: z.number().int().nonnegative()
+});
 var FsMoveRequest = z.object({
   path: z.string(),
   newPath: z.string(),
@@ -2768,6 +4395,9 @@ var GitDiffRequest = z.object({
   // diff selectors, mutually exclusive precedence: refs > staged > worktree
   staged: z.boolean().default(false),
   // --cached (index vs HEAD)
+  // Workspace review includes after-images that ordinary `git diff` omits.
+  // Explicit so commit/staged consumers keep native Git semantics by default.
+  includeUntracked: z.boolean().default(false),
   fromRef: z.string().optional(),
   toRef: z.string().optional(),
   pathspec: z.array(z.string()).default([]),
@@ -2783,7 +4413,7 @@ var WorkspaceCaptureFile = z.object({
   status: GitFileStatusCode,
   // sha256 of the captured after-image bytes; null when deleted / tooLarge.
   hash: z.string().nullable(),
-  // git blob sha of the HEAD version — the wake-on-edit flush guard (dossier
+  // git blob sha of the HEAD version — the wake-on-edit flush guard (design
   // §10.1). null when the path is new/untracked (no HEAD blob).
   baseHash: z.string().nullable(),
   // Content-addressed storage key of the after-image; null when deleted /
@@ -2908,14 +4538,25 @@ var GitCommit = z.object({
   sha: z.string(),
   shortSha: z.string(),
   parents: z.array(z.string()),
-  author: z.object({ name: z.string(), email: z.string(), timestamp: z.number().int() }),
-  committer: z.object({ name: z.string(), email: z.string(), timestamp: z.number().int() }),
+  author: z.object({
+    name: z.string(),
+    email: z.string(),
+    timestamp: z.number().int()
+  }),
+  committer: z.object({
+    name: z.string(),
+    email: z.string(),
+    timestamp: z.number().int()
+  }),
   subject: z.string(),
   body: z.string(),
   refs: z.array(z.string()).default([])
   // decorations: branch/tag pointers
 });
-var GitLogResponse = z.object({ commits: z.array(GitCommit), hasMore: z.boolean() });
+var GitLogResponse = z.object({
+  commits: z.array(GitCommit),
+  hasMore: z.boolean()
+});
 var GitShowRequest = z.object({
   path: z.string().default(""),
   ref: z.string(),
@@ -2972,7 +4613,10 @@ var PtyOpenResponse = z.object({
   supportsInput: z.boolean()
   // false on backends without writeStdin
 });
-var PtyWriteRequest = z.object({ ptyId: z.string().uuid(), data: z.string() });
+var PtyWriteRequest = z.object({
+  ptyId: z.string().uuid(),
+  data: z.string()
+});
 var PtyResizeRequest = z.object({
   ptyId: z.string().uuid(),
   cols: z.number().int().positive(),
@@ -2980,7 +4624,11 @@ var PtyResizeRequest = z.object({
 });
 var PtyCloseRequest = z.object({ ptyId: z.string().uuid() });
 var SessionStructuredCapabilities = z.object({
-  FileSystem: z.object({ available: z.boolean(), readOnly: z.boolean(), root: z.string() }),
+  FileSystem: z.object({
+    available: z.boolean(),
+    readOnly: z.boolean(),
+    root: z.string()
+  }),
   Terminal: z.object({
     events: z.boolean(),
     // command.output firehose (always on if a box exists)
@@ -2999,33 +4647,407 @@ var SessionEvent = z.object({
   type: SessionEventType,
   payload: z.unknown().default({}),
   occurredAt: z.string(),
-  clientEventId: z.string().min(1).nullable().optional(),
+  clientEventId: SessionOperationKey.nullable().optional(),
   turnId: z.string().uuid().nullable().optional(),
   turnGeneration: z.number().int().nonnegative().nullable().optional(),
   turnAttemptId: z.string().uuid().nullable().optional(),
   turnAssociation: z.enum(["current", "late_rejected", "duplicate"]).nullable().optional(),
   duplicateOfEventId: z.string().uuid().nullable().optional(),
-  duplicateReason: z.string().min(1).nullable().optional()
+  duplicateReason: z.string().min(1).max(1024).nullable().optional()
+});
+var OPENGENI_HOST_EXPORT_SCHEMA_REVISION = "2026-07-host-export-v1";
+var HostExportCursor = z.string().regex(/^(0|[1-9][0-9]*)$/);
+var HostExportConsumerId = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+var HostExportInitiator = TurnInitiator.extend({
+  subjectId: z.string().min(1).max(1024),
+  label: z.string().min(1).max(256).optional()
+});
+var HostExportInitiatorContext = TurnInitiatorContext.refine(
+  (value) => {
+    try {
+      return new TextEncoder().encode(JSON.stringify(value)).byteLength <= 4096;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Host export initiator context exceeds 4096 UTF-8 bytes" }
+);
+var HostExportAttribution = {
+  initiator: HostExportInitiator.nullable(),
+  initiatorContext: HostExportInitiatorContext,
+  origin: SessionTurnSource.nullable()
+};
+var HostSessionEvent = SessionEvent.extend({
+  type: z.string().min(1).max(256),
+  clientEventId: z.string().max(1024).nullable().optional(),
+  turnAssociation: z.string().min(1).max(64).nullable().optional(),
+  duplicateReason: z.string().max(4096).nullable().optional()
+});
+var HostUsageEvent = UsageEvent.extend({
+  subjectId: z.string().max(1024).nullable(),
+  eventType: z.string().min(1).max(256),
+  unit: z.string().min(1).max(128),
+  sourceResourceType: z.string().max(256).nullable(),
+  sourceResourceId: z.string().max(2048).nullable(),
+  idempotencyKey: z.string().min(1).max(2048),
+  billingProviderEventId: z.string().max(2048).nullable()
+});
+var HostEventExport = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  cursor: HostExportCursor,
+  idempotencyKey: z.string().min(1).max(2048),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  /**
+   * Immutable root of event.sessionId's session lineage at capture time. Null
+   * only for an unresolved pre-lineage/legacy export row.
+   */
+  rootSessionId: z.string().uuid().nullable(),
+  ...HostExportAttribution,
+  event: HostSessionEvent
 });
+var HostUsageExport = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  cursor: HostExportCursor,
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid().nullable(),
+  /** Null when sessionId is null or an unresolved pre-lineage legacy row. */
+  rootSessionId: z.string().uuid().nullable(),
+  turnId: z.string().uuid().nullable(),
+  turnAttemptId: z.string().uuid().nullable(),
+  ...HostExportAttribution,
+  usage: HostUsageEvent
+});
+var HostEventExportBatch = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  consumerId: HostExportConsumerId,
+  leaseToken: z.string().uuid(),
+  checkpoint: HostExportCursor,
+  throughCursor: HostExportCursor,
+  events: z.array(HostEventExport).min(1).max(256)
+});
+var HostUsageExportBatch = z.object({
+  schemaRevision: z.literal(OPENGENI_HOST_EXPORT_SCHEMA_REVISION),
+  consumerId: HostExportConsumerId,
+  leaseToken: z.string().uuid(),
+  checkpoint: HostExportCursor,
+  throughCursor: HostExportCursor,
+  events: z.array(HostUsageExport).min(1).max(256)
+});
+var SESSION_EVENT_TYPE_MAX_BYTES = 256;
+var SESSION_EVENT_CLIENT_EVENT_ID_MAX_BYTES = SESSION_OPERATION_KEY_MAX_CHARS * 4;
+var SESSION_EVENT_TURN_ASSOCIATION_MAX_BYTES = 64;
+var SESSION_EVENT_DUPLICATE_REASON_MAX_BYTES = 4 * 1024;
+var SESSION_EVENT_ENVELOPE_MAX_BYTES = 80 * 1024;
+function boundSessionEvent(event, options = {}) {
+  const surface = options.surface ?? "durable_audit";
+  const maxBytes = Math.max(8 * 1024, options.maxBytes ?? SESSION_EVENT_ENVELOPE_MAX_BYTES);
+  const originalBytes = measureSessionEventJson(event).bytes;
+  const source = sessionEventOwnDataFields(event);
+  const id = canonicalSessionEventUuid(source.id, SESSION_EVENT_ZERO_UUID);
+  const workspaceId = canonicalSessionEventUuid(source.workspaceId, SESSION_EVENT_ZERO_UUID);
+  const sessionId = canonicalSessionEventUuid(source.sessionId, SESSION_EVENT_ZERO_UUID);
+  const sequence = source.sequence.readable && typeof source.sequence.value === "number" && Number.isSafeInteger(source.sequence.value) && source.sequence.value > 0 ? source.sequence.value : 1;
+  const occurredAt = source.occurredAt.readable && typeof source.occurredAt.value === "string" && sessionEventUtf8Bytes(source.occurredAt.value) <= 256 ? source.occurredAt.value : "1970-01-01T00:00:00.000Z";
+  const rawType = source.type.readable ? source.type.value : void 0;
+  const typeIsSafe = typeof rawType === "string" && sessionEventUtf8Bytes(rawType) <= SESSION_EVENT_TYPE_MAX_BYTES && !rawType.includes("\n") && !rawType.includes("\r");
+  const rawClientEventId = source.clientEventId.readable ? source.clientEventId.value : void 0;
+  const clientEventId = boundOptionalSessionEventText(
+    typeof rawClientEventId === "string" || rawClientEventId === null ? rawClientEventId : void 0,
+    SESSION_EVENT_CLIENT_EVENT_ID_MAX_BYTES
+  );
+  const rawTurnAssociation = source.turnAssociation.readable ? source.turnAssociation.value : void 0;
+  const turnAssociation = rawTurnAssociation === null || rawTurnAssociation === void 0 || rawTurnAssociation === "current" || rawTurnAssociation === "late_rejected" || rawTurnAssociation === "duplicate" ? rawTurnAssociation : null;
+  const rawDuplicateReason = source.duplicateReason.readable ? source.duplicateReason.value : void 0;
+  const duplicateReason = boundOptionalSessionEventText(
+    typeof rawDuplicateReason === "string" || rawDuplicateReason === null ? rawDuplicateReason : void 0,
+    SESSION_EVENT_DUPLICATE_REASON_MAX_BYTES
+  );
+  const turnId = canonicalOptionalSessionEventUuid(source.turnId);
+  const turnGeneration = canonicalSessionEventGeneration(source.turnGeneration);
+  const turnAttemptId = canonicalOptionalSessionEventUuid(source.turnAttemptId);
+  const duplicateOfEventId = canonicalOptionalSessionEventUuid(source.duplicateOfEventId);
+  const envelopeFields = [
+    sessionEventCustomSerializerProjection(event),
+    sessionEventAdditionalTopLevelFieldProjection(event),
+    !typeIsSafe ? sessionEventEnvelopeFieldProjection(
+      "type",
+      rawType,
+      "session.event.envelope_omitted",
+      source.type.readable
+    ) : null,
+    !source.clientEventId.readable || rawClientEventId !== clientEventId ? sessionEventEnvelopeFieldProjection(
+      "clientEventId",
+      rawClientEventId,
+      clientEventId,
+      source.clientEventId.readable
+    ) : null,
+    !source.turnAssociation.readable || rawTurnAssociation !== turnAssociation ? sessionEventEnvelopeFieldProjection(
+      "turnAssociation",
+      rawTurnAssociation,
+      turnAssociation,
+      source.turnAssociation.readable
+    ) : null,
+    !source.duplicateReason.readable || rawDuplicateReason !== duplicateReason ? sessionEventEnvelopeFieldProjection(
+      "duplicateReason",
+      rawDuplicateReason,
+      duplicateReason,
+      source.duplicateReason.readable
+    ) : null,
+    ...sessionEventCanonicalFieldProjections(source, {
+      id,
+      workspaceId,
+      sessionId,
+      sequence,
+      occurredAt
+    }),
+    ...sessionEventOptionalFieldProjections(source, {
+      turnId,
+      turnGeneration,
+      turnAttemptId,
+      duplicateOfEventId
+    }),
+    !source.payload.readable ? sessionEventEnvelopeFieldProjection("payload", void 0, null, false) : null
+  ].filter((field) => field !== null);
+  const rawPayload = source.payload.readable ? source.payload.value : "[event payload accessor omitted at bounded projection boundary]";
+  const payload = envelopeFields.length === 0 ? boundSessionEventPayload(rawPayload, { surface }) : boundSessionEventPayload(
+    {
+      preview: "[legacy event envelope normalized at bounded projection boundary]",
+      originalEventBytes: originalBytes,
+      originalType: typeof rawType === "string" ? boundSessionEventText(rawType, 256) : null,
+      envelopeProjection: {
+        truncated: true,
+        surface,
+        fields: envelopeFields
+      },
+      fullEvidence: { available: false, reason: "not_retained" }
+    },
+    { surface, maxBytes: 8 * 1024 }
+  );
+  const bounded = {
+    id,
+    workspaceId,
+    sessionId,
+    sequence,
+    type: typeIsSafe ? rawType : "session.event.envelope_omitted",
+    payload,
+    occurredAt,
+    ...sessionEventShouldEmitOptionalField(source.clientEventId) ? { clientEventId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnId) ? { turnId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnGeneration) ? { turnGeneration } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnAttemptId) ? { turnAttemptId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnAssociation) ? { turnAssociation } : {},
+    ...sessionEventShouldEmitOptionalField(source.duplicateOfEventId) ? { duplicateOfEventId } : {},
+    ...sessionEventShouldEmitOptionalField(source.duplicateReason) ? { duplicateReason } : {}
+  };
+  if (sessionEventJsonBytes(bounded) <= maxBytes) return bounded;
+  const fallback = {
+    id,
+    workspaceId,
+    sessionId,
+    sequence,
+    type: "session.event.envelope_omitted",
+    payload: boundSessionEventPayload(
+      {
+        preview: "[legacy event envelope omitted at bounded projection boundary]",
+        originalEventBytes: originalBytes,
+        originalType: typeof rawType === "string" ? boundSessionEventText(rawType, 256) : null,
+        fullEvidence: { available: false, reason: "not_retained" }
+      },
+      { surface, maxBytes: 4 * 1024 }
+    ),
+    occurredAt,
+    ...sessionEventShouldEmitOptionalField(source.clientEventId) ? { clientEventId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnId) ? { turnId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnGeneration) ? { turnGeneration } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnAttemptId) ? { turnAttemptId } : {},
+    ...sessionEventShouldEmitOptionalField(source.turnAssociation) ? { turnAssociation } : {},
+    ...sessionEventShouldEmitOptionalField(source.duplicateOfEventId) ? { duplicateOfEventId } : {},
+    ...sessionEventShouldEmitOptionalField(source.duplicateReason) ? { duplicateReason } : {}
+  };
+  const deliveredBytes = sessionEventJsonBytes(fallback);
+  if (deliveredBytes > maxBytes) {
+    throw new RangeError(
+      `Bounded session event exceeds its final envelope (${deliveredBytes} > ${maxBytes} bytes)`
+    );
+  }
+  return fallback;
+}
+function sessionEventEnvelopeFieldProjection(field, original, delivered, originalReadable = true) {
+  return {
+    field,
+    originalBytes: originalReadable ? typeof original === "string" ? sessionEventUtf8Bytes(original) : typeof original === "number" || typeof original === "boolean" ? sessionEventJsonBytes(original) : original === null || original === void 0 ? 0 : null : null,
+    deliveredBytes: typeof delivered === "string" ? sessionEventUtf8Bytes(delivered) : typeof delivered === "number" || typeof delivered === "boolean" ? sessionEventJsonBytes(delivered) : 0
+  };
+}
+function sessionEventCustomSerializerProjection(event) {
+  const projection = {
+    field: "toJSON",
+    originalBytes: null,
+    deliveredBytes: 0
+  };
+  let candidate = event;
+  try {
+    for (let depth = 0; depth <= SESSION_EVENT_PROTOTYPE_MAX_DEPTH; depth += 1) {
+      if (candidate === null) return null;
+      const descriptor = Object.getOwnPropertyDescriptor(candidate, "toJSON");
+      if (descriptor) {
+        return !("value" in descriptor) || typeof descriptor.value === "function" ? projection : null;
+      }
+      candidate = Object.getPrototypeOf(candidate);
+    }
+    return projection;
+  } catch {
+    return projection;
+  }
+}
+var SESSION_EVENT_PROTOTYPE_MAX_DEPTH = 32;
+var SESSION_EVENT_ZERO_UUID = "00000000-0000-4000-8000-000000000000";
+var SESSION_EVENT_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var SESSION_EVENT_OWN_DATA_FIELDS = [
+  "id",
+  "workspaceId",
+  "sessionId",
+  "sequence",
+  "type",
+  "payload",
+  "occurredAt",
+  "clientEventId",
+  "turnId",
+  "turnGeneration",
+  "turnAttemptId",
+  "turnAssociation",
+  "duplicateOfEventId",
+  "duplicateReason"
+];
+var SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS = /* @__PURE__ */ new Set([
+  ...SESSION_EVENT_OWN_DATA_FIELDS,
+  "toJSON"
+]);
+function sessionEventAdditionalTopLevelFieldProjection(event) {
+  const projection = {
+    field: "additionalTopLevelFields",
+    originalBytes: null,
+    deliveredBytes: 0
+  };
+  let inspected = 0;
+  try {
+    for (const key in event) {
+      inspected += 1;
+      if (inspected > SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS.size + 1) return projection;
+      const descriptor = Object.getOwnPropertyDescriptor(event, key);
+      if (descriptor?.enumerable && !SESSION_EVENT_KNOWN_ENUMERABLE_FIELDS.has(key)) {
+        return projection;
+      }
+    }
+    return null;
+  } catch {
+    return projection;
+  }
+}
+function sessionEventOwnDataFields(event) {
+  return Object.fromEntries(
+    SESSION_EVENT_OWN_DATA_FIELDS.map((key) => {
+      try {
+        const descriptor = Object.getOwnPropertyDescriptor(event, key);
+        if (!descriptor) return [key, { readable: true, value: void 0 }];
+        return [
+          key,
+          "value" in descriptor ? { readable: true, value: descriptor.value } : { readable: false }
+        ];
+      } catch {
+        return [key, { readable: false }];
+      }
+    })
+  );
+}
+function canonicalSessionEventUuid(field, fallback) {
+  return field.readable && typeof field.value === "string" && SESSION_EVENT_UUID_PATTERN.test(field.value) ? field.value : fallback;
+}
+function canonicalOptionalSessionEventUuid(field) {
+  return field.readable && typeof field.value === "string" && SESSION_EVENT_UUID_PATTERN.test(field.value) ? field.value : null;
+}
+function canonicalSessionEventGeneration(field) {
+  return field.readable && typeof field.value === "number" && Number.isSafeInteger(field.value) && field.value >= 0 ? field.value : null;
+}
+function sessionEventShouldEmitOptionalField(field) {
+  return !field.readable || field.value !== void 0;
+}
+function sessionEventCanonicalFieldProjections(source, delivered) {
+  return ["id", "workspaceId", "sessionId", "sequence", "occurredAt"].flatMap(
+    (field) => {
+      const original = source[field].readable ? source[field].value : void 0;
+      return source[field].readable && original === delivered[field] ? [] : [
+        sessionEventEnvelopeFieldProjection(
+          field,
+          original,
+          delivered[field],
+          source[field].readable
+        )
+      ];
+    }
+  );
+}
+function sessionEventOptionalFieldProjections(source, delivered) {
+  return ["turnId", "turnGeneration", "turnAttemptId", "duplicateOfEventId"].flatMap(
+    (field) => {
+      const original = source[field].readable ? source[field].value : void 0;
+      const canonicalOriginal = original ?? null;
+      return source[field].readable && canonicalOriginal === delivered[field] ? [] : [
+        sessionEventEnvelopeFieldProjection(
+          field,
+          original,
+          delivered[field],
+          source[field].readable
+        )
+      ];
+    }
+  );
+}
+function boundOptionalSessionEventText(value, maxBytes) {
+  return typeof value === "string" ? boundSessionEventText(value, maxBytes) : value;
+}
+function boundSessionEventText(value, maxBytes) {
+  const encoder2 = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder2.encode(value);
+  if (bytes.byteLength <= maxBytes) return value;
+  const marker = "\u2026[truncated]";
+  const markerBytes = encoder2.encode(marker).byteLength;
+  const prefixBudget = Math.max(0, maxBytes - markerBytes);
+  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
+  while (prefixEnd > 0 && prefixEnd < bytes.byteLength && (bytes[prefixEnd] & 192) === 128) {
+    prefixEnd -= 1;
+  }
+  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
+}
+function sessionEventUtf8Bytes(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
 var SessionQueueMutationResponse = z.object({
+  receipt: SessionCommandReceipt,
   snapshot: SessionQueueSnapshot,
-  events: z.array(SessionEvent),
-  shouldWake: z.boolean()
+  draft: ComposerDraft.optional()
 });
 var SessionControlResponse = z.object({
-  operationId: z.string().uuid(),
-  event: SessionEvent,
-  controlState: SessionControlState,
-  controlGeneration: z.number().int().nonnegative(),
-  expectedActiveTurnId: z.string().uuid().nullable(),
-  expectedExecutionGeneration: z.number().int().nonnegative().nullable(),
-  expectedAttemptId: z.string().uuid().nullable(),
-  deliveryEventId: z.string().uuid().nullable(),
-  shouldSignalControl: z.boolean(),
-  shouldWake: z.boolean()
+  receipt: SessionCommandReceipt,
+  effectiveControl: EffectiveSessionControl,
+  interruptionCount: z.number().int().nonnegative(),
+  wakeCount: z.number().int().nonnegative()
 });
 var CreateSessionRequest = withVariableSetIdAlias({
+  /**
+   * Optional UUID preallocated by an embedding host. This lets the host durably
+   * link its own projection before OpenGeni admits the initial turn. Replays
+   * must pair it with the same idempotency key; OpenGeni never derives host
+   * identity or authorization from the UUID.
+   */
+  requestedSessionId: z.string().uuid().optional(),
   initialMessage: z.string().min(1),
+  // System-level host context for the initial turn only. Unlike `instructions`,
+  // this does not persist into later turns and is never emitted as a user event.
+  turnInstructions: z.string().trim().min(1).max(32768).optional(),
   // Per-session agent persona/system instructions (org-visible metadata, NOT a
   // secret). Rides the SAME system-level instructions channel the per-workspace
   // agentInstructions rides, composed AFTER the workspace persona so it refines
@@ -3035,7 +5057,14 @@ var CreateSessionRequest = withVariableSetIdAlias({
   // matches the codebase's largest free-form string convention (workspace
   // variable set variable values). Absent ⇒ byte-identical to today.
   instructions: z.string().trim().min(1).max(32768).optional(),
+  // For an agent-created child, omission inherits the trusted immediate
+  // parent's repository/file context. An explicit array, including [], is
+  // authoritative. Top-level omission remains []. Presence is resolved from
+  // the raw request because this Zod default erases absent-vs-empty.
   resources: z.array(ResourceRef).default([]),
+  // The same child omission rule applies to selected MCP tool refs. Top-level
+  // omission still applies workspace-default capability MCP tools; explicit []
+  // suppresses those defaults (the first-party OpenGeni server remains added).
   tools: z.array(ToolRef).default([]),
   metadata: z.record(z.string(), z.unknown()).default({}),
   model: z.string().min(1).optional(),
@@ -3062,7 +5091,7 @@ var CreateSessionRequest = withVariableSetIdAlias({
   // behavior). An id that does not name a rig in the workspace is a 422.
   rigId: z.string().uuid().optional(),
   goal: GoalSpec.optional(),
-  clientEventId: z.string().min(1).optional(),
+  clientEventId: SessionOperationKey.optional(),
   // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
   // create calls carrying the same key to a single session (partial unique
   // index on (workspace_id, create_idempotency_key)). Distinct from
@@ -3070,13 +5099,19 @@ var CreateSessionRequest = withVariableSetIdAlias({
   // creation of a brand-new session. Absent means no create-dedup (each call
   // is an independent create).
   idempotencyKey: z.string().min(1).max(200).optional(),
-  // Permissions the session's first-party MCP token should carry instead of
-  // the fixed worker default — how an operator hands a manager-style session
-  // the orchestration/variableSet/github tools. Capped at creation: every
-  // requested permission must be held by the creating grant (no escalation).
+  // Permissions the session's first-party MCP token should carry. A top-level
+  // omission uses the deployment's worker default; a child omission inherits
+  // the creating session's effective grant. An explicit set is capped at
+  // creation: every requested permission must be held by the creating grant.
+  // A goal-bearing session whose explicit/effective set omits goals:manage is
+  // rejected; creation never silently expands a child beyond that set.
   firstPartyMcpPermissions: z.array(Permission).optional(),
-  // Third-party MCP servers attached only to this session. Credential headers are
-  // write-only: create responses and events expose only SessionMcpServerMetadata.
+  // Third-party MCP servers attached only to this session. For an agent-created
+  // child, omission snapshots its trusted immediate parent's server definitions,
+  // policies, connection refs, and encrypted credentials. Explicit arrays,
+  // including [], are authoritative; non-empty explicit arrays require attach
+  // permission. Credential headers are write-only: create responses and events
+  // expose only SessionMcpServerMetadata.
   mcpServers: z.array(SessionMcpServerInput).default([]),
   // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
   // today's behavior (a context-dependent default resolved server-side: from
@@ -3097,16 +5132,148 @@ var CreateSessionRequest = withVariableSetIdAlias({
   // manifest-env guard).
   sandbox: z.union([z.literal("shared"), z.literal("new"), z.object({ groupId: z.string().uuid() })]).optional()
 });
+var HumanInputQuestionKind = z.enum(["text", "single_select", "multi_select"]);
+var HumanInputOption = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(256),
+  description: z.string().max(2048).nullable().optional()
+});
+var HumanInputQuestion = z.object({
+  id: z.string().min(1).max(64),
+  kind: HumanInputQuestionKind,
+  prompt: z.string().min(1).max(4096),
+  label: z.string().min(1).max(128).nullable().optional(),
+  helpText: z.string().max(2048).nullable().optional(),
+  options: z.array(HumanInputOption).max(20).default([]),
+  required: z.boolean().default(true),
+  allowOther: z.boolean().default(false),
+  validation: z.object({
+    minLength: z.number().int().nonnegative().max(8192).nullable().optional(),
+    maxLength: z.number().int().positive().max(8192).nullable().optional(),
+    minSelections: z.number().int().nonnegative().max(20).nullable().optional(),
+    maxSelections: z.number().int().positive().max(20).nullable().optional()
+  }).nullable().optional()
+}).superRefine((question, ctx) => {
+  const optionIds = new Set(question.options.map((option) => option.id));
+  if (optionIds.size !== question.options.length) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["options"],
+      message: "option ids must be unique"
+    });
+  }
+  if (question.kind === "text") {
+    if (question.options.length > 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: "text questions cannot have options"
+      });
+    }
+    if (question.allowOther) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowOther"],
+        message: "text questions do not use Other"
+      });
+    }
+  } else if (question.options.length === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["options"],
+      message: "select questions require options"
+    });
+  }
+  const validation = question.validation;
+  if (validation?.minLength != null && validation?.maxLength != null && validation.minLength > validation.maxLength) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["validation"],
+      message: "minLength exceeds maxLength"
+    });
+  }
+  if (validation?.minSelections != null && validation?.maxSelections != null && validation.minSelections > validation.maxSelections) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["validation"],
+      message: "minSelections exceeds maxSelections"
+    });
+  }
+});
+var HumanInputRequestStatus = z.enum([
+  "pending",
+  "answered",
+  "skipped",
+  "expired",
+  "cancelled"
+]);
+var RequestHumanInputToolInput = z.object({
+  questions: z.array(HumanInputQuestion).min(1).max(20),
+  allowSkip: z.boolean().default(false),
+  expiresInSeconds: z.number().int().positive().max(30 * 24 * 60 * 60).nullable().optional()
+});
+var HumanInputAnswer = z.object({
+  questionId: z.string().min(1).max(64),
+  values: z.array(z.string().max(8192)).max(20),
+  other: z.string().max(8192).nullable().optional()
+});
+var HumanInputResponse = z.discriminatedUnion("outcome", [
+  z.object({
+    outcome: z.literal("answered"),
+    answers: z.array(HumanInputAnswer).max(20)
+  }),
+  z.object({ outcome: z.literal("skipped") }),
+  z.object({ outcome: z.literal("expired") }),
+  z.object({ outcome: z.literal("cancelled") })
+]);
+var SubmitHumanInputResponseRequest = z.discriminatedUnion("outcome", [
+  z.object({
+    outcome: z.literal("answered"),
+    answers: z.array(HumanInputAnswer).max(20)
+  }),
+  z.object({ outcome: z.literal("skipped") })
+]);
+var SessionHumanInputRequest = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  turnId: z.string().uuid(),
+  turnGeneration: z.number().int().positive(),
+  creationAttemptId: z.string().uuid(),
+  toolCallId: z.string().min(1).max(1024),
+  status: HumanInputRequestStatus,
+  questions: z.array(HumanInputQuestion).min(1).max(20),
+  allowSkip: z.boolean(),
+  response: HumanInputResponse.nullable(),
+  respondedBy: z.string().max(1024).nullable(),
+  respondedAt: z.string().nullable(),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+function approvalIdentifier(value) {
+  if (!value || typeof value !== "object") return null;
+  const approval = value;
+  const rawItem = approval.rawItem && typeof approval.rawItem === "object" ? approval.rawItem : null;
+  const candidate = rawItem?.callId ?? rawItem?.id ?? approval.id ?? approval.name;
+  if (typeof candidate !== "string" && typeof candidate !== "number") return null;
+  return String(candidate);
+}
 var ClientSessionEvent = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("user.message"),
-    clientEventId: z.string().min(1).optional(),
+    clientEventId: SessionOperationKey.optional(),
     payload: z.object({
       text: z.string().min(1),
+      // System-level host context for this exact turn only. Persisted on the
+      // turn for retry/recovery, never copied into the visible user message.
+      turnInstructions: z.string().trim().min(1).max(32768).optional(),
       resources: z.array(ResourceRef).default([]),
       tools: z.array(ToolRef).default([]),
       model: z.string().min(1).optional(),
       reasoningEffort: ReasoningEffort.optional(),
+      controlEtag: z.string().min(1).optional(),
+      expectedDraftRevision: z.number().int().nonnegative().optional(),
       // Header-value rotation only. URL/name/tool settings are immutable after
       // session create; persisted events expose metadata, never header values.
       mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional()
@@ -3114,23 +5281,33 @@ var ClientSessionEvent = z.discriminatedUnion("type", [
   }),
   z.object({
     type: z.literal("user.approvalDecision"),
-    clientEventId: z.string().min(1).optional(),
+    clientEventId: SessionOperationKey.optional(),
     payload: z.object({
-      approvalId: z.string().min(1),
+      approvalId: z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS),
       decision: z.enum(["approve", "reject"]),
       message: z.string().optional()
     })
+  }),
+  z.object({
+    type: z.literal("user.humanInputResponse"),
+    clientEventId: SessionOperationKey.optional(),
+    payload: z.object({
+      requestId: z.string().uuid(),
+      response: SubmitHumanInputResponseRequest
+    })
   })
 ]);
 var SteerSessionMessageRequest = z.object({
   text: z.string().min(1),
+  // Same per-turn system-level context as a queued user.message.
+  turnInstructions: z.string().trim().min(1).max(32768).optional(),
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
   model: z.string().min(1).optional(),
   reasoningEffort: ReasoningEffort.optional(),
-  clientEventId: z.string().min(1).optional(),
-  expectedControlGeneration: z.number().int().nonnegative().optional(),
-  expectedWorkspaceInferenceGeneration: z.number().int().nonnegative().optional(),
+  clientEventId: SessionOperationKey.optional(),
+  controlEtag: z.string().min(1).optional(),
+  expectedDraftRevision: z.number().int().nonnegative().optional(),
   mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional()
 });
 var SteerSessionMessageResponse = z.object({
@@ -3160,6 +5337,29 @@ var GitHubRepository = z.object({
   accountLogin: z.string(),
   accountType: z.string().nullable()
 });
+var GitHubRepositoryScope = z.enum(["all", "selected"]);
+var GitHubInstallationBinding = z.object({
+  installationId: z.number().int().positive(),
+  accountLogin: z.string().nullable(),
+  accountType: z.string().nullable(),
+  repositoryScope: GitHubRepositoryScope,
+  repositoryCount: z.number().int().nonnegative(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var GitHubAppInfo = z.object({
+  configured: z.boolean(),
+  appId: z.string().nullable(),
+  clientId: z.string().nullable(),
+  appSlug: z.string().nullable(),
+  installUrl: z.string().nullable(),
+  linkUrl: z.string().nullable(),
+  installations: z.array(GitHubInstallationBinding),
+  missing: z.array(z.string())
+});
+var GitHubRepositoriesResponse = z.object({
+  repositories: z.array(GitHubRepository)
+});
 var ClientAuthConfig = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("none")
@@ -3288,7 +5488,7 @@ var ViewerHolder = z.object({
   leaseEpoch: z.number().int().nonnegative(),
   viewerHeartbeatIntervalMs: z.number().int().positive(),
   // The desktop pixel tunnel URL the viewer connects to directly; null until
-  // P4 mints it (gated until then).
+  // a viewer grant is minted (gated until then).
   dataPlaneUrl: z.string().nullable()
 });
 var AcknowledgeStreamRequest = z.object({
@@ -3549,8 +5749,11 @@ var ClientModel = z.object({
   api: z.enum(["responses", "chat"]),
   contextWindowTokens: z.number().int().positive().optional()
 });
+var OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1";
+var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
 var ClientConfig = z.object({
   deploymentRevision: z.string(),
+  apiContractRevision: z.literal(OPENGENI_API_CONTRACT_REVISION),
   // Release-train version of the server (absent on dev/source builds). The
   // compatibility policy lives in docs/architecture.md — clients within the
   // same major are supported; evolution is additive within a major.
@@ -3641,7 +5844,6 @@ export {
   CAPABILITY_DESCRIPTORS,
   CLEARED_RUN_STATE_BLOB,
   CLEARED_RUN_STATE_MARKER,
-  CancelSessionQueueItemRequest,
   CapabilityCatalogAuthKind,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
@@ -3667,6 +5869,7 @@ export {
   CompactSessionContextRequest,
   CompactSessionContextResult,
   CompleteFileUploadResponse,
+  ComposerDraft,
   ConnectionCredentialBundle,
   ConnectionKind,
   ConnectionMetadata,
@@ -3685,13 +5888,16 @@ export {
   CreateRigRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
+  CreateSessionResponse,
   CreateSocialConnectionRequest,
   CreateSocialPostRequest,
   CreateVariableSetRequest,
   CreateWorkspaceEnvironmentRequest,
   CreateWorkspaceRequest,
+  CredentialAuthNeededPayload,
   DESKTOP_STREAM_PORT,
   DelegatedAccessTokenPayload,
+  DeleteSessionQueueItemRequest,
   DeviceEnrollmentApproveRequest,
   DeviceEnrollmentApproveResponse,
   DeviceEnrollmentDenyRequest,
@@ -3711,6 +5917,10 @@ export {
   DocumentSearchRequest,
   DocumentSearchResult,
   DocumentStatus,
+  EditSessionQueueItemRequest,
+  EffectiveControlBlocker,
+  EffectiveControlResumeOption,
+  EffectiveSessionControl,
   EnableCapabilityRequest,
   EnablePackRequest,
   EnrollTokenExchangeRequest,
@@ -3753,6 +5963,7 @@ export {
   GetWorkspaceCaptureResponse,
   GitChangedPayload,
   GitCommit,
+  GitCredentialBindingId,
   GitCredentialProvider,
   GitCredentialRepositoryRef,
   GitDiffHunk,
@@ -3763,15 +5974,36 @@ export {
   GitFileDiff,
   GitFileStatus,
   GitFileStatusCode,
+  GitHubAppInfo,
   GitHubAppManifestCreate,
+  GitHubInstallationBinding,
+  GitHubRepositoriesResponse,
   GitHubRepository,
+  GitHubRepositoryScope,
   GitLogRequest,
   GitLogResponse,
+  GitRepositoryAccess,
   GitShowRequest,
   GitShowResponse,
   GitStatusRequest,
   GitStatusResponse,
   GoalSpec,
+  HostEventExport,
+  HostEventExportBatch,
+  HostExportConsumerId,
+  HostExportCursor,
+  HostExportInitiator,
+  HostExportInitiatorContext,
+  HostSessionEvent,
+  HostUsageEvent,
+  HostUsageExport,
+  HostUsageExportBatch,
+  HumanInputAnswer,
+  HumanInputOption,
+  HumanInputQuestion,
+  HumanInputQuestionKind,
+  HumanInputRequestStatus,
+  HumanInputResponse,
   IntegrationClientMetadata,
   KnowledgeMemory,
   KnowledgeMemoryKind,
@@ -3792,12 +6024,17 @@ export {
   MachinesResponse,
   ManagedAccount,
   MarketingDailyAnalysisTaskRequest,
+  McpConnectionResourceScope,
   McpServerConnectionRef,
   MetricSample,
   MintEnrollTokenRequest,
   MintEnrollTokenResponse,
+  MoveSessionQueueItemRequest,
   OAuthStartRequest,
   OAuthStartResponse,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_HOST_EXPORT_SCHEMA_REVISION,
   PackInstallation,
   PackInstallationStatus,
   Permission,
@@ -3819,6 +6056,8 @@ export {
   RegisterCapabilityPackRequest,
   RelayTokenPayload,
   RepositoryResourceRef,
+  RequestHumanInputToolInput,
+  ResourceMountPathError,
   ResourceRef,
   ResourceRefConflictError,
   RevokeEnrollmentResponse,
@@ -3833,10 +6072,21 @@ export {
   RigSetupAppendPayload,
   RigVerificationHealth,
   RigVersion,
+  SESSION_AUTHORIZATION_LIST_SCOPE_MAX_IDS,
+  SESSION_EVENT_CLIENT_EVENT_ID_MAX_BYTES,
+  SESSION_EVENT_DUPLICATE_REASON_MAX_BYTES,
+  SESSION_EVENT_ENVELOPE_MAX_BYTES,
+  SESSION_EVENT_PAYLOAD_MAX_BYTES,
+  SESSION_EVENT_RAW_DELTA_TYPES,
+  SESSION_EVENT_SEMANTIC_CLASS_TYPES,
+  SESSION_EVENT_TURN_ASSOCIATION_MAX_BYTES,
+  SESSION_EVENT_TYPE_MAX_BYTES,
+  SESSION_OPERATION_KEY_MAX_CHARS,
   SandboxBackend,
   SandboxCapabilityName,
   SandboxCommandOutputDeltaPayload,
   SandboxOs,
+  SaveComposerDraftRequest,
   ScheduledTask,
   ScheduledTaskAgentConfig,
   ScheduledTaskOverlapPolicy,
@@ -3846,18 +6096,32 @@ export {
   ScheduledTaskScheduleSpec,
   ScheduledTaskStatus,
   ScheduledTaskTriggerType,
+  ServiceTurnInitiator,
+  ServiceTurnInitiatorContext,
   Session,
+  SessionAuthorizationActor,
+  SessionAuthorizationDecision,
+  SessionAuthorizationListScope,
+  SessionAuthorizationOperation,
+  SessionAuthorizationSurface,
+  SessionAuthorizationTarget,
   SessionBusMessage,
   SessionCapabilities,
+  SessionCommandReceipt,
   SessionControlRequest,
   SessionControlResponse,
   SessionControlState,
   SessionEvent,
+  SessionEventPayloadMode,
+  SessionEventReadDirection,
+  SessionEventReadMode,
+  SessionEventSemanticClass,
   SessionEventType,
   SessionGoal,
   SessionGoalCreatedBy,
   SessionGoalPausedReason,
   SessionGoalStatus,
+  SessionHumanInputRequest,
   SessionLineageResponse,
   SessionListResponse,
   SessionMcpCredentialUpdateInput,
@@ -3869,6 +6133,7 @@ export {
   SessionStructuredCapabilities,
   SessionSystemUpdate,
   SessionSystemUpdateKind,
+  SessionSystemUpdatePayload,
   SessionSystemUpdateState,
   SessionTurn,
   SessionTurnSource,
@@ -3883,11 +6148,13 @@ export {
   StaticUsageLimits,
   SteerSessionMessageRequest,
   SteerSessionMessageResponse,
+  SteerSessionQueueItemRequest,
   StreamClosedPayload,
   StreamOpenedPayload,
   StreamRevokedPayload,
   StreamTokenPayload,
   StreamUrlRotatedPayload,
+  SubmitHumanInputResponseRequest,
   SwapActiveSandboxRequest,
   SwapActiveSandboxResponse,
   SystemUpdateClassification,
@@ -3899,7 +6166,16 @@ export {
   TerminalPtyStartedPayload,
   ToolAuthNeededPayload,
   ToolRef,
+  TranscriptionErrorCode,
+  TranscriptionEvent,
+  TranscriptionResultMetadata,
+  TranscriptionSpeaker,
+  TranscriptionTimeSpan,
+  TranscriptionWord,
   TriggerScheduledTaskRequest,
+  TurnInitiator,
+  TurnInitiatorContext,
+  UNATTRIBUTED_LEGACY_INITIATOR_SUBJECT_ID,
   UpdateConnectionRequest,
   UpdateKnowledgeMemoryRequest,
   UpdateRigRequest,
@@ -3922,6 +6198,9 @@ export {
   ViewerHeartbeatRequest,
   ViewerHeartbeatResponse,
   ViewerHolder,
+  WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  WORKSPACE_CONTROL_EVENT_MAX_BYTES,
+  WORKSPACE_CONTROL_REASON_MAX_BYTES,
   Workspace,
   WorkspaceCaptureDegradedReason,
   WorkspaceCaptureFile,
@@ -3929,6 +6208,8 @@ export {
   WorkspaceCaptureRepo,
   WorkspaceCaptureSignedUrl,
   WorkspaceCaptureStats,
+  WorkspaceControlEvent,
+  WorkspaceControlEventTruncation,
   WorkspaceEnvironment,
   WorkspaceEnvironmentVariableMetadata,
   WorkspaceInferenceControlRequest,
@@ -3943,14 +6224,35 @@ export {
   WorkspaceRevisionCapturedPayload,
   WorkspaceRevisionDegradedPayload,
   WorkspaceSettingsSchema,
+  WorkspaceTranscriptionPolicy,
+  WorkspaceTranscriptionTarget,
+  approvalIdentifier,
+  approximateSessionEventTokens,
+  assertUniqueResourceMountPaths,
+  boundSessionEvent,
+  boundSessionEventPayload,
+  boundWorkspaceControlEvent,
+  defaultRepositoryMountPath,
   evaluateWorkspaceModelPolicy,
+  gitCredentialBindingIdForRepository,
+  gitCredentialProviderForRepository,
   isClearedRunStateBlob,
+  measureSessionEventJson,
   mergeResourceRefs,
   mergeToolRefs,
+  normalizeRepositorySubpath,
+  normalizeResourceMountPath,
   prefixedMcpToolName,
   reasoningEffortForMetadata,
+  resolveSessionEventTypeFilters,
   resolveWorkspaceMemoryEnabled,
   resourceIdentityKey,
+  resourceMountPath,
+  resourceMountPathCollisionKey,
+  sessionEventJsonBytes,
+  sessionEventMediaPreview,
+  sessionEventMediaPreviewFromDataUrl,
+  sessionEventPayloadTruncation,
   signDelegatedAccessToken,
   signEnrollToken,
   signEnrollmentBearer,
@@ -3961,6 +6263,7 @@ export {
   verifyEnrollToken,
   verifyEnrollmentBearer,
   verifyRelayToken,
-  verifyStreamToken
+  verifyStreamToken,
+  workspaceControlUtf8Bytes
 };
 //# sourceMappingURL=index.js.map