@mobileaidev/ai-app-bridge 0.3.8 → 0.4.0

package/bin/script/script-sdk.py

@@ -1,9 +1,14 @@
 import asyncio
 import json
 import sys
+import math
+import traceback
+import time
+from types import SimpleNamespace
 
 
 _real_stdout = sys.stdout
+_input_parse_ms = 0
 HELD = {
     "pause_requested",
     "paused_manual",
@@ -20,10 +25,14 @@ def send(message):
 
 
 def read_message():
+    global _input_parse_ms
     line = sys.stdin.readline()
     if not line:
         return None
-    return json.loads(line)
+    started = time.perf_counter()
+    message = json.loads(line)
+    _input_parse_ms = (time.perf_counter() - started) * 1000
+    return message
 
 
 class HostContext:
@@ -120,22 +129,74 @@ class HostContext:
         return checkpoint["state"]
 
 
-def load_namespace(path):
+def load_namespace(path, source_name=None):
     namespace = {}
     with open(path, "r", encoding="utf-8") as handle:
-        exec(handle.read(), namespace, namespace)
+        exec(compile(handle.read(), source_name or path, "exec"), namespace, namespace)
     return namespace
 
 
+def validate_json(value, location="", parents=None):
+    parents = set() if parents is None else parents
+
+    def invalid(reason):
+        error = TypeError(f"{location or '/'}: {reason}")
+        error.code = "extraction_type_error"
+        error.value_path = location
+        raise error
+
+    if value is None or isinstance(value, (str, bool)):
+        return
+    if isinstance(value, (int, float)):
+        if (isinstance(value, int) and abs(value) > 9007199254740991) or (isinstance(value, float) and
+                (not math.isfinite(value) or value.is_integer() and abs(value) > 9007199254740991)):
+            invalid("expected a finite number in the safe integer range")
+        return
+    if type(value) not in (list, dict):
+        invalid(f"unsupported JSON type: {type(value).__name__}")
+    if id(value) in parents:
+        invalid("cyclic value")
+    parents.add(id(value))
+    entries = enumerate(value) if isinstance(value, list) else value.items()
+    for key, item in entries:
+        if isinstance(value, dict) and not isinstance(key, str):
+            invalid("object keys must be strings")
+        suffix = str(key).replace("~", "~0").replace("/", "~1")
+        validate_json(item, f"{location}/{suffix}", parents)
+    parents.remove(id(value))
+
+
+def bounded(value, size):
+    return str(value).encode("utf-8", errors="replace")[:size].decode("utf-8", errors="ignore")
+
+
+def diagnostic(error):
+    frames = traceback.extract_tb(error.__traceback__)
+    stack = "Traceback (most recent call last):\n" + "".join(traceback.format_list(frames[-20:])) + "".join(traceback.format_exception_only(type(error), error))
+    result = {"type": type(error).__name__, "message": bounded(error, 2048),
+              "stack": bounded(stack, 8192), "stackTruncated": len(frames) > 20 or len(stack.encode("utf-8")) > 8192}
+    if isinstance(error, SyntaxError) and error.filename:
+        result["location"] = {"file": bounded(error.filename, 1024), "line": error.lineno, "column": error.offset}
+    elif frames:
+        frame = frames[-1]
+        result["location"] = {"file": bounded(frame.filename, 1024), "line": frame.lineno}
+    if hasattr(error, "value_path"):
+        result["valuePath"] = bounded(error.value_path, 1024)
+    return result
+
+
 def main():
     artifact_path = sys.argv[1]
     send({"type": "ready"})
     start = read_message()
     sys.stdout = sys.stderr
-    ctx = HostContext(start.get("inputs") or {}, start.get("control") or {"status": "running", "pauseReason": None})
+    extraction = start.get("extraction") is not None
+    ctx = SimpleNamespace(inputs=start["inputs"]) if extraction else HostContext(start.get("inputs") or {}, start.get("control") or {"status": "running", "pauseReason": None})
     entry = start.get("entrypoint") or "main"
     try:
-        namespace = load_namespace(artifact_path)
+        execution_started = time.perf_counter()
+        input_parse_ms = _input_parse_ms
+        namespace = load_namespace(artifact_path, start.get("sourceName"))
         loaded = namespace.get(entry)
         if not callable(loaded):
             send({"type": "fail", "error": "unsupported_entrypoint"})
@@ -143,9 +204,20 @@ def main():
         result = loaded(ctx)
         if asyncio.iscoroutine(result):
             result = asyncio.run(result)
-        send({"type": "return", "result": result})
+        if extraction:
+            validate_json(result)
+            if len(json.dumps(result, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")) > 256 * 1024:
+                error = ValueError("Extraction result exceeds 256 KiB.")
+                error.code = "extraction_output_too_large"
+                raise error
+        frame = {"type": "return", "result": result}
+        if extraction:
+            frame["timings"] = {"inputParseMs": input_parse_ms, "executionMs": (time.perf_counter() - execution_started) * 1000}
+        send(frame)
     except Exception as error:
-        send({"type": "fail", "error": str(error)})
+        detail = diagnostic(error)
+        send({"type": "fail", "error": getattr(error, "code", "extraction_failed") if extraction else detail["message"],
+              "message": detail["message"], "diagnostic": detail})
         sys.exit(1)
 
 

package/bin/script/script-session-channel.js

@@ -2,7 +2,8 @@
 
 const MAX_FRAME_BYTES = 1024 * 1024;
 
-function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } = {}) {
+function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES,
+  maxInputFrameBytes = maxFrameBytes, maxOutputFrameBytes = maxFrameBytes, maxDiagnosticBytes = 8192 } = {}) {
   let buffer = '';
   let closed = false;
   let failure = null;
@@ -12,10 +13,18 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
   const pending = [];
   const replies = new Map();
   const maxPending = 32;
+  let stderr = Buffer.alloc(0);
+  let stderrTotalBytes = 0;
 
   if (child.stderr) {
-    child.stderr.on('data', () => {});
+    child.stderr.on('data', chunk => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      stderrTotalBytes += bytes.length;
+      stderr = bytes.length >= maxDiagnosticBytes ? Buffer.from(bytes.subarray(-maxDiagnosticBytes))
+        : Buffer.concat([stderr.subarray(Math.max(0, stderr.length + bytes.length - maxDiagnosticBytes)), bytes]);
+    });
   }
+  child.stdin.on('error', error => fail(error));
   child.stdout.setEncoding('utf8');
   child.stdout.on('data', (chunk) => {
     if (closed) return;
@@ -25,7 +34,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
       const line = buffer.slice(0, index);
       buffer = buffer.slice(index + 1);
       index = buffer.indexOf('\n');
-      if (Buffer.byteLength(line, 'utf8') > maxFrameBytes) {
+      if (Buffer.byteLength(line, 'utf8') + 1 > maxOutputFrameBytes) {
         fail(new Error('frame_too_large'));
         return;
       }
@@ -57,7 +66,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
       }
       pending.push(message);
     }
-    if (Buffer.byteLength(buffer, 'utf8') > maxFrameBytes) {
+    if (Buffer.byteLength(buffer, 'utf8') > maxOutputFrameBytes) {
       fail(new Error('frame_too_large'));
     }
   });
@@ -67,7 +76,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
   function send(message) {
     if (closed || !child.stdin.writable) return;
     const line = `${JSON.stringify(message)}\n`;
-    if (Buffer.byteLength(line, 'utf8') > maxFrameBytes) {
+    if (Buffer.byteLength(line, 'utf8') > maxInputFrameBytes) {
       fail(new Error('frame_too_large'));
       return;
     }
@@ -76,14 +85,11 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
 
   function nextMessage() {
     return new Promise((resolve) => {
-      if (closed) {
-        resolve(failure);
-        return;
-      }
       if (pending.length > 0) {
         resolve(pending.shift());
         return;
       }
+      if (closed) { resolve(failure); return; }
       waiters.push(resolve);
     });
   }
@@ -108,7 +114,9 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
     closed = true;
     const frame = { type: 'fail', error: error.message || String(error) };
     failure = frame;
+    const terminal = error.message === 'channel_closed' ? pending.find(message => ['return', 'fail'].includes(message.type)) : null;
     pending.length = 0;
+    if (terminal) pending.push(terminal);
     buffer = '';
     while (waiters.length > 0) waiters.shift()(frame);
     for (const resolve of replies.values()) resolve(frame);
@@ -121,7 +129,16 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
     if (child.kill('SIGTERM') && !killTimer) killTimer = setTimeout(() => child.kill('SIGKILL'), 250);
   }
 
-  return { send, nextMessage, waitReply, stop };
+  function diagnostics() {
+    if (!stderrTotalBytes) return {};
+    // Invalid bytes expand to replacement characters. Bound delivered UTF-8
+    // text too, starting at a complete character in the retained tail.
+    const text = Buffer.from(stderr.toString('utf8'));
+    let start = Math.max(0, text.length - maxDiagnosticBytes);
+    while (start < text.length && (text[start] & 0xc0) === 0x80) start++;
+    return { stderr: text.subarray(start).toString('utf8'), stderrTruncated: stderrTotalBytes > stderr.length || start > 0 };
+  }
+  return { send, nextMessage, waitReply, stop, diagnostics };
 }
 
 module.exports = { createScriptSessionChannel };

package/bin/script/script-supervisor.js

@@ -174,6 +174,7 @@ function createScriptSupervisor({
       mutationUnknown: false,
       decisionRevision: 0,
       currentRequestId: null,
+      pendingQuestion: null,
       questionRevisions: new Map(),
       decisions: new Map(),
       ledger: scriptLedger,
@@ -431,8 +432,10 @@ function createScriptSupervisor({
       operationId: record.operationId,
       status: record.status,
       pauseReason: record.pauseReason,
+      pendingQuestion: record.status === 'waiting_for_agent' ? record.pendingQuestion : null,
       error: record.error,
       hash: record.hash,
+      ...(record.diagnostics ? { diagnostics: record.diagnostics } : {}),
       resultRef: record.resultRef ?? null,
       eventSequence: record.events.sequence,
       events: record.events.after(args.afterSequence, args.eventLimit ?? args.limit),
@@ -517,6 +520,7 @@ function persistRecord(record, kind, body) {
 }
 
 async function commitTerminal(record, status, error, now, result) {
+  record.diagnostics = status === 'failed' ? result?.diagnostics : undefined;
   let revision = record.checkpointRevision + 1;
   let resultRef = null;
   if (status === 'completed' && record.store) {
@@ -539,6 +543,7 @@ async function commitTerminal(record, status, error, now, result) {
     status,
     error,
     resultRef,
+    ...(record.diagnostics ? { diagnostics: record.diagnostics } : {}),
     ...(record.recording ? { recording: record.recording.info() } : {}),
   };
   let persisted = await persistRecord(record, 'checkpoint', checkpoint);
@@ -777,6 +782,9 @@ function trackAgent(agent, record, now) {
       const requestId = `ask-${record.decisionRevision}`;
       record.questionRevisions.set(requestId, record.decisionRevision);
       record.currentRequestId = requestId;
+      // The unanswered question stays on the record so a filtered event page
+      // cannot hide it from status/wait.
+      record.pendingQuestion = { requestId, revision: record.decisionRevision, request };
       record.status = 'waiting_for_agent';
       emitRecord(record, 'agent_question_created', {
         request,

package/bin/shared-kernel/argument-schema.js

@@ -14,19 +14,16 @@ function validateValue(value, schema, field = '') {
   if (Object.hasOwn(schema, 'const') && value !== schema.const) throw invalid(field, `${label} must be ${JSON.stringify(schema.const)}.`);
   if (schema.enum && !schema.enum.includes(value)) throw invalid(field, `${label} must be one of: ${schema.enum.join(', ')}.`);
   const type = schema.type;
-  const matches = type === undefined || (type === 'array' ? Array.isArray(value)
-    : type === 'null' ? value === null
-    : type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
-    : type === 'integer' ? Number.isSafeInteger(value)
-    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
-    : typeof value === type);
-  if (!matches) throw invalid(field, `${label} must be ${type}; no implicit type conversion is performed.`);
+  if (!matchesType(value, type)) throw invalid(field, `${label} must be ${type}; no implicit type conversion is performed.`);
   if (schema.minLength !== undefined && value.length < schema.minLength) throw invalid(field, `${label} must not be empty.`);
   if (schema.maxLength !== undefined && value.length > schema.maxLength) throw invalid(field, `${label} must contain at most ${schema.maxLength} characters.`);
   if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) throw invalid(field, `${label} must match ${schema.pattern}.`);
-  if (schema.minimum !== undefined && value < schema.minimum) throw invalid(field, `${label} must be >= ${schema.minimum}.`);
-  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) throw invalid(field, `${label} must be > ${schema.exclusiveMinimum}.`);
-  if (schema.maximum !== undefined && value > schema.maximum) throw invalid(field, `${label} must be <= ${schema.maximum}.`);
+  // A range violation quotes the field's documented meaning, so the caller can
+  // correct the call without reading the nested schema.
+  const explained = message => schema.description ? `${message} ${schema.description}` : message;
+  if (schema.minimum !== undefined && value < schema.minimum) throw invalid(field, explained(`${label} must be >= ${schema.minimum}.`));
+  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) throw invalid(field, explained(`${label} must be > ${schema.exclusiveMinimum}.`));
+  if (schema.maximum !== undefined && value > schema.maximum) throw invalid(field, explained(`${label} must be <= ${schema.maximum}.`));
   if (type === 'array') {
     if (schema.minItems !== undefined && value.length < schema.minItems) throw invalid(field, `${label} requires at least ${schema.minItems} item(s).`);
     if (schema.maxItems !== undefined && value.length > schema.maxItems) throw invalid(field, `${label} accepts at most ${schema.maxItems} item(s).`);
@@ -68,6 +65,15 @@ function validateValue(value, schema, field = '') {
   if (Object.keys(schema).every(key => ['description', 'default'].includes(key))) validateJson(value, field);
 }
 
+function matchesType(value, type) {
+  return type === undefined || (type === 'array' ? Array.isArray(value)
+    : type === 'null' ? value === null
+    : type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
+    : type === 'integer' ? Number.isSafeInteger(value)
+    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
+    : typeof value === type);
+}
+
 function accepts(value, schema, field) {
   try { validateValue(value, schema, field); return true; }
   catch (error) { if (!(error instanceof CommandError)) throw error; return false; }
@@ -82,22 +88,48 @@ function validateUnion(value, branches, field, exactlyOne) {
   }
   if (matched && (!exactlyOne || matched === 1)) return;
   if (!matched) {
+    // A branch for another JSON type cannot explain this value, e.g. the null
+    // branch of a nullable target never explains an object missing platform.
+    const explained = failures.filter(({ branch }) => matchesType(value, branch.type));
+    if (!explained.length) {
+      throw invalid(field, `${field || 'arguments'} must be ${[...new Set(failures.map(({ branch }) => branch.type))].join(' or ')}; no implicit type conversion is performed.`);
+    }
     // A tagged branch gives a useful precise error instead of a generic union
     // failure, e.g. decision.action.durationMs for an observed long press.
-    const tagged = failures.filter(({ branch }) => {
+    const tagged = explained.filter(({ branch }) => {
       const tags = Object.entries(branch.properties || {}).filter(([, rule]) => Object.hasOwn(rule, 'const'));
       return tags.some(([key, rule]) => value?.[key] === rule.const)
         && tags.every(([key, rule]) => Object.hasOwn(value || {}, key) ? value[key] === rule.const : !branch.required?.includes(key));
     });
     if (tagged.length === 1) throw tagged[0].error;
-    const candidates = tagged.length ? tagged : failures;
+    const candidates = tagged.length ? tagged : explained;
     if (candidates.every(({ error }) => error.code === candidates[0].error.code && error.field === candidates[0].error.field && error.message === candidates[0].error.message)) throw candidates[0].error;
+    // No branch accepts every supplied tag: name the tag the intended variants
+    // reject and its accepted values instead of listing every variant.
+    const rejected = tagged.length ? null : rejectedDiscriminator(value || {}, explained.map(({ branch }) => branch));
+    if (rejected) {
+      const child = fieldAt(field, rejected.key);
+      throw invalid(child, `${child} must be one of: ${rejected.values.map(item => JSON.stringify(item)).join(', ')}.`);
+    }
     if (branches.length === 1) throw failures[0].error;
   }
   throw new CommandError('invalid_argument', `${field || 'arguments'} must match ${exactlyOne ? 'exactly one' : 'one'} of the documented variants.`,
     { field: field || 'arguments', details: { variants: failures.map(({ error }) => ({ field: error.field, error: error.code, message: error.message })) } });
 }
 
+// The branches agreeing with the most supplied tags are the intended variants,
+// e.g. the two start variants for {operation:"start", mode:"wrong"}. A supplied
+// tag they all reject is the field to correct; its accepted values are theirs.
+function rejectedDiscriminator(value, branches) {
+  const suppliedTags = branch => Object.entries(branch.properties || {}).filter(([key, rule]) => Object.hasOwn(rule, 'const') && Object.hasOwn(value, key));
+  const agreement = branch => suppliedTags(branch).filter(([key, rule]) => value[key] === rule.const).length;
+  const best = Math.max(...branches.map(agreement));
+  const closest = branches.filter(branch => agreement(branch) === best);
+  const key = suppliedTags(closest[0]).map(([name]) => name)
+    .find(name => closest.every(branch => Object.hasOwn(branch.properties[name] || {}, 'const') && value[name] !== branch.properties[name].const));
+  return key === undefined ? null : { key, values: [...new Set(closest.map(branch => branch.properties[key].const))] };
+}
+
 function validateJson(value, field = '', ancestors = new Set(), depth = 0) {
   if (depth > 64) throw invalid(field, 'JSON nesting must not exceed 64 levels.');
   if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return;

package/bin/shared-kernel/evidence-archive.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { checksumOf, canonicalJson, validateArchivedRecord, verifyChecksum } = require('./evidence-schema');
+const { checksumOf, canonicalJson, validateArchivedRecord, verifyChecksum, NAMESPACES } = require('./evidence-schema');
 const { analyzeRecordedPayloads } = require('./recorded-payload-archive');
 const { readRegularFile: readRecordedFile } = require('./evidence-recording');
 
@@ -23,7 +23,7 @@ function textArgument(value, field) {
 }
 
 function namespaceArgument(namespace) {
-  requireValue(namespace === 'intent' || namespace === 'script', 'invalid_argument', 'namespace');
+  requireValue(NAMESPACES.includes(namespace), 'invalid_argument', 'namespace');
 }
 
 async function handle(args = {}, { getFactStore } = {}) {

package/bin/shared-kernel/evidence-schema.js

@@ -3,7 +3,7 @@
 const crypto = require('node:crypto');
 const { sanitizePersistentValue } = require('../fact-codec');
 
-const NAMESPACES = Object.freeze(['script', 'intent']);
+const NAMESPACES = Object.freeze(['script', 'intent', 'response']);
 const PROVIDERS = Object.freeze(['native', 'uia', 'flutter', 'h5']);
 const RECORD_SCHEMA = 'aab.execution-evidence/v1';
 const AGENT_DECISIONS = Object.freeze(['act', 'complete', 'fail', 'inconclusive']);
@@ -17,6 +17,7 @@ const KINDS = Object.freeze([
   'checkpoint',
   'result',
   'attachment',
+  'response',
 ]);
 
 function checksumOf(value) {
@@ -57,6 +58,7 @@ function verifyChecksum(record) {
 }
 
 function requiredFields(kind) {
+  if (kind === 'response') return ['operationId', 'revision', 'snapshotBase64'];
   if (kind === 'observation') {
     return ['operationId', 'revision', 'target', 'provider', 'capturedAtMs'];
   }
@@ -97,6 +99,7 @@ function validateRecord(namespace, kind, record, { archivedUnversioned = false }
   if (!record || typeof record !== 'object') {
     return { ok: false, error: 'invalid_record' };
   }
+  if ((namespace === 'response') !== (kind === 'response')) return { ok: false, error: 'invalid_kind' };
   if (!archivedUnversioned && record.schemaVersion !== undefined && record.schemaVersion !== RECORD_SCHEMA) {
     return { ok: false, error: 'unsupported_record_schema', field: 'schemaVersion' };
   }
@@ -107,6 +110,18 @@ function validateRecord(namespace, kind, record, { archivedUnversioned = false }
       return { ok: false, error: 'invalid_record', field };
     }
   }
+  if (kind === 'response') {
+    const encoded = record.snapshotBase64;
+    if (typeof encoded !== 'string' || Buffer.from(encoded, 'base64').toString('base64') !== encoded
+      || record.revision !== 1) return { ok: false, error: 'invalid_record', field: 'snapshotBase64' };
+    try {
+      const snapshot = JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
+      if (!['json', 'text'].includes(snapshot.kind) || !Object.hasOwn(snapshot, 'value')
+        || !snapshot.execution || !snapshot.control || snapshot.control.source !== undefined
+        || snapshot.identity?.responseId !== record.operationId || typeof snapshot.identity.command !== 'string'
+        || !Number.isSafeInteger(snapshot.identity.capturedAtMs)) throw new Error('invalid_snapshot');
+    } catch { return { ok: false, error: 'invalid_record', field: 'snapshotBase64' }; }
+  }
   if (kind === 'result' && (namespace !== 'script' || !Object.hasOwn(record, 'result')
     || !Number.isSafeInteger(record.bytes) || record.bytes < 1
     || !/^[a-f0-9]{64}$/.test(record.sha256) || !/^[a-f0-9]{64}$/.test(record.originalSha256)

package/bin/shared-kernel/evidence-store.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const { buildEnvelope, verifyChecksum } = require('./evidence-schema');
+const { buildEnvelope, verifyChecksum, NAMESPACES } = require('./evidence-schema');
 
 function createEvidenceStore({ namespace, adapter, now = Date.now, maxBytes = 8 * 1024 * 1024 } = {}) {
-  if (namespace !== 'script' && namespace !== 'intent') {
-    throw new TypeError('namespace must be script or intent');
+  if (!NAMESPACES.includes(namespace)) {
+    throw new TypeError('namespace must be script, intent or response');
   }
   if (!adapter || typeof adapter.record !== 'function' || typeof adapter.readById !== 'function') {
     throw new TypeError('adapter with record/readById is required');

package/bin/shared-kernel/execution-contracts.js

@@ -133,8 +133,15 @@ function scriptSpecSchema(permissionNames) {
 }
 
 function executionCommandSchema(command, permissionNames) {
-  const read = { afterSequence, limit: pageLimit };
-  const scriptRead = { ...read, eventLimit: pageLimit, includeCatalog: boolean };
+  // Script and Intent page with different cursors; the schema states which one.
+  const historyRead = {
+    afterSequence: { ...afterSequence, description: 'History page cursor: the previous response\'s history.lastSequence. Not an eventSequence.' },
+    limit: { ...pageLimit, description: 'History entries per page; it bounds entries, not response bytes.' },
+  };
+  const scriptRead = {
+    afterSequence: { ...afterSequence, description: 'Continuation cursor: the previous status/wait response\'s eventSequence; events and history after it are returned. Not history.lastSequence.' },
+    limit: pageLimit, eventLimit: pageLimit, includeCatalog: boolean,
+  };
   const operation = (name, properties, required = []) => object({ operation: { const: name }, ...properties }, ['operation', ...required]);
   const control = (name, properties = {}) => operation(name, { operationId: text, ...properties }, ['operationId']);
   if (command === 'script') return variants('operation', [
@@ -144,7 +151,8 @@ function executionCommandSchema(command, permissionNames) {
         { if: { required: ['recordingDir'] }, then: { properties: { script: { properties: { policy: { properties: { restartPolicy: { const: 'none' } } } } } } } },
       ] },
     control('result'),
-    control('status', scriptRead), control('wait', { ...scriptRead, waitMs: { ...integer(0, 60000), default: 30000 } }),
+    control('status', scriptRead), control('wait', { ...scriptRead, waitMs: { ...integer(0, 60000), default: 30000,
+      description: 'Upper bound of one wait call in milliseconds. To keep waiting, call wait again with the same operationId and afterSequence set to the last eventSequence.' } }),
     ...['pause', 'resume', 'cancel'].map(name => control(name, scriptRead)),
     operation('decide', { operationId: text, requestId: text, revision, decision: { contentMediaType: 'application/json', description: 'JSON answer to the current ctx.askAgent request; business data is preserved.' }, ...scriptRead }, ['operationId', 'requestId', 'revision', 'decision']),
     operation('runtime-status', {}),
@@ -156,7 +164,7 @@ function executionCommandSchema(command, permissionNames) {
     return variants('operation', [
       operation('start', { ...start, mode: { const: 'supervised', default: 'supervised' } }, ['goal', 'target']),
       operation('start', { ...start, mode: { const: 'autonomous' }, agentModule: text, budget: intentBudget }, ['goal', 'target', 'mode', 'agentModule']),
-      control('status', read), control('observe', { basedOnRevision: revision, observationTarget: observationTargetSchema,
+      control('status', historyRead), control('observe', { basedOnRevision: revision, observationTarget: observationTargetSchema,
         provider: { ...provider, description: 'Observe through this provider on the frozen target. Becomes selected only after the new observation and summary are committed; omitted retains the last committed selection.' } }),
       operation('decide', { operationId: text, decision: intentDecisionSchema() }, ['operationId', 'decision']),
       ...['pause', 'resume', 'cancel'].map(name => control(name)),
@@ -164,7 +172,7 @@ function executionCommandSchema(command, permissionNames) {
     ]);
   }
   if (command === 'evidence') return variants('operation', [
-    operation('export', { namespace: { enum: ['intent', 'script'] }, operationId: text, outputDir: text, includeRecordedPayloads: boolean }, ['namespace', 'operationId', 'outputDir']),
+    operation('export', { namespace: { enum: ['intent', 'script', 'response'] }, operationId: text, outputDir: text, includeRecordedPayloads: boolean }, ['namespace', 'operationId', 'outputDir']),
     operation('verify', { archiveDir: text, manifestSha256: { type: 'string', pattern: '^[a-f0-9]{64}$' } }, ['archiveDir', 'manifestSha256']),
   ]);
   throw new Error(`No execution contract for ${command}`);