@mobileaidev/ai-app-bridge 0.3.8 → 0.4.1

package/docs/RESPONSE_EXTRACTION.md

@@ -0,0 +1,126 @@
+# Response extraction (0.4.0)
+
+Every CLI/MCP run must state what to return. Use `extract:null` for the original
+result within the body budget, or select the fields needed for the current task.
+`extract` and `output` are top-level request fields, separate from business
+`arguments`. The old request without extract is rejected before dispatch.
+Internal Script `ctx.call(command, args)` stays unchanged (`ok`, `result`).
+
+```json extraction-example
+{"command":"runtime","arguments":{"operation":"status"},"extract":null}
+```
+
+```bash
+ai-app-bridge runtime --operation status --extract null
+```
+
+A small response can be read in full. Large trees, network records and logs are
+better extracted near the Host. This saves response/context bytes, not the
+original collection time. Capture duration, history limit and extraction solve
+different problems; a one-item page can still exceed the byte budget.
+
+## One query, one extraction
+
+Regex requires a string at `inputPath` (JSON Pointer). Empty path selects a text
+response; escape `/` as `~1` and `~` as `~0`. Flags are unique `i`, `m`, `s`, `u`;
+all matches are returned with `match`, `groups` and `namedGroups`.
+Unmatched captures are null. At most 1,000 matches are allowed; overflow fails.
+
+```json extraction-example
+{"command":"runtime","arguments":{"operation":"status"},"extract":{"mode":"regex","pattern":"stopped|running","inputPath":"/status"}}
+```
+
+For structured responses, both languages receive exactly
+`ctx.inputs = {kind, response, execution, control}`. `response` is the original
+command value, including its final feedback. This is a short local transform;
+it has no Script `ctx.call`, agent decisions or assertion API.
+
+```json extraction-example
+{"command":"runtime","arguments":{"operation":"status"},"extract":{"mode":"script","language":"javascript","source":"module.exports.main = ctx => ({status:ctx.inputs.response.status, commandOk:ctx.inputs.execution.ok});"}}
+```
+
+```json extraction-example
+{"command":"runtime","arguments":{"operation":"status"},"extract":{"mode":"script","language":"python","source":"def main(ctx):\n    return {\"status\": ctx.inputs[\"response\"][\"status\"], \"commandOk\": ctx.inputs[\"execution\"][\"ok\"]}\n"}}
+```
+
+Use exactly one of `source` and `sourcePath` for scripts. Relative paths resolve
+from the caller directory; the Host freezes the file before executing the
+command. Syntax checks do not execute top-level code. Source is at most 64 KiB
+UTF-8. Python requires Python 3.9+; ordinary, JS and regex calls need no Python.
+
+Return strict JSON: null, booleans, strings, finite numbers, arrays and objects.
+Integers outside ±9,007,199,254,740,991 are rejected, including Python values
+before serialization. Convert intentionally to a string inside your source.
+Unsupported types, cycles and sparse JS arrays fail rather than being coerced.
+
+## Read the three outcomes separately
+
+The shared compact body is
+`{command, execution, control, extraction, delivery, kind, value?, failureStage?}`.
+`execution` records the original command outcome and dispatch facts. Successful
+extraction cannot convert a failed or unknown command into success. `control`
+preserves operation IDs, receipts, Intent revisions, Script event cursors and
+current pending questions, and capture coverage/pagination. Histories remain in
+value; only their page controls are protected separately.
+
+`extraction.status` is skipped, succeeded or failed. `delivery` reports actual
+UTF-8 body bytes and the limit. `failureStage` gives the first failing stage in
+validation → execution → extraction → delivery order. CLI exit codes are 0 for
+requested delivery, 1 for validation/failed or unknown execution, and 2 when a
+known successful command could not be extracted/delivered. MCP uses `isError`
+consistently. A successful Script execution is separate from its business verdict.
+
+A temporary-directory removal failure after the worker exits is reported as
+`extraction.cleanupError`. It does not replace a successful value or the original
+extraction error, change the exit code, or replay the command.
+
+Preserve source identity, timestamps, state and coverage needed by the actual
+assertion. A selected successful row does not prove complete business coverage.
+
+## Retry extraction without repeating the action
+
+Non-null extraction attempts to retain the original response. A null response
+that would exceed the budget also attempts retention. `control.source` is the
+only ref location. Only `persisted:true` makes that ref readable. Null within
+budget normally reports `persisted:false, reason:not_requested`; offline local
+commands report `offline`. Saving and extraction may fail independently.
+
+On extraction failure or overflow, copy the original ref and change only the
+extraction in a `response read`. The current read execution is separate from
+original facts in `control.origin`; `control.source` still identifies the same
+snapshot. Repeated reads neither replay devices nor create nested snapshots.
+
+```json
+{
+  "command": "response",
+  "arguments": {"operation":"read","ref":{"namespace":"response","evidenceId":"<original evidenceId>","checksum":"<original checksum>","operationId":"<original operationId>"}},
+  "extract": {"mode":"script","language":"javascript","source":"module.exports.main = ctx => ctx.inputs.response;"},
+  "output": {"maxBytes":262144}
+}
+```
+
+A ref is subject to existing evidence retention. Missing/evicted/corrupt sources
+fail explicitly. Reissuing the original action with the same requestId is not a
+substitute for ref recovery: deduplication can expire and does not survive every
+Host lifetime. Snapshot/export JSON preserves original values; binary responses
+are base64 for null delivery and are not extractable in this version.
+
+## Limits and diagnosis
+
+| Limit | Value |
+| --- | --- |
+| Final compact UTF-8 body | 96 KiB default; output.maxBytes 16–256 KiB |
+| Source snapshot / extraction input | 8 MiB original UTF-8 JSON |
+| Returned extraction value | 256 KiB (the enclosing body still has its budget) |
+| Extraction timeout | 2,000 ms default; timeoutMs 1–10,000; includes worker startup/input |
+| Active extractions | 2; no queue; busy still preserves the original action result/ref |
+| Failed worker diagnostics | Most recent 8 KiB stderr; stack at most 20 frames and 8 KiB |
+
+No budget error returns a truncated JSON document or dumps the large original
+value. If the protected controls themselves cannot fit, `controlComplete:false`
+and `control_over_budget` prohibit continuing from incomplete controls. Use a
+real ref when available, with a sufficient budget or a narrower command query.
+Discovery/help has a separate fixed 96 KiB limit; follow its command/operation
+hint. Runtime stop drains active extraction workers; CLI/MCP disconnect alone
+keeps the shared Runtime alive. Extraction is trusted local code, with bounded
+worker/channel lifetime rather than an OS/process-tree sandbox.

package/docs/SCRIPT_AUTHORING.md

@@ -12,6 +12,7 @@ Call MCP `run` with this shape, replacing the target and source path:
 ```json
 {
   "command": "script",
+  "extract": null,
   "arguments": {
     "operation": "start",
     "script": {
@@ -20,10 +21,21 @@ Call MCP `run` with this shape, replacing the target and source path:
       "language": "javascript",
       "sourcePath": "/absolute/flow.js",
       "entrypoint": "main",
-      "target": {"platform":"android", "serial": "explicit-device", "packageName": "explicit.package"},
+      "target": {
+        "platform": "android",
+        "serial": "explicit-device",
+        "packageName": "explicit.package"
+      },
       "inputs": {},
-      "permissions": ["app.read", "app.interact", "capture.read"],
-      "policy": {"timeoutMs": 180000, "restartPolicy": "none"}
+      "permissions": [
+        "app.read",
+        "app.interact",
+        "capture.read"
+      ],
+      "policy": {
+        "timeoutMs": 180000,
+        "restartPolicy": "none"
+      }
     }
   }
 }
@@ -32,9 +44,9 @@ Call MCP `run` with this shape, replacing the target and source path:
 The same request is available through CLI:
 
 ```sh
-ai-app-bridge script --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./flow.js","permissions":["app.read","app.interact","capture.read"]}'
-ai-app-bridge script --operation status --operation-id RETURNED_ID
-ai-app-bridge script --operation result --operation-id RETURNED_ID
+ai-app-bridge script --extract null --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./flow.js","permissions":["app.read","app.interact","capture.read"]}'
+ai-app-bridge script --extract null --operation status --operation-id RETURNED_ID
+ai-app-bridge script --extract null --operation result --operation-id RETURNED_ID
 ```
 
 The CLI returns the operation under `value`. CLI and MCP share a persistent runtime;
@@ -138,6 +150,113 @@ Terminal rolling summaries freeze elapsed and active durations at the terminal
 event. Later status queries do not add idle time. For end-to-end measurement,
 retain the public start timestamp and terminal event timestamp separately.
 
+## Lifecycle: start, wait, result
+
+A fixed regression is one start, a wait loop and one result read. The caller
+drives these three `run` calls; the program owns observation, actions and
+assertions. The repository test suite runs the two sources below against the
+current contract with an injected device, so they match the installed package.
+
+1. Start with `sourcePath` for repeated runs (or `source`), a platform-qualified
+   `target`, and the run's values in `inputs`:
+
+```json lifecycle-example
+{"command":"script","extract":null,"arguments":{"operation":"start","script":{"schemaVersion":"aab.code-script/v1","name":"labels-regression","language":"javascript","sourcePath":"./regression.js","target":{"platform":"android","serial":"<serial>","packageName":"<package>"},"inputs":{"entryText":"Labels","expectedText":"New label"}}}}
+```
+
+2. Wait with the returned `operationId`. `waitMs` is at most 60000 per call.
+   While `status` is `running` or `finishing`, call `wait` again with the
+   previous response's `eventSequence` as `afterSequence`:
+
+```json lifecycle-example
+{"command":"script","extract":null,"arguments":{"operation":"wait","operationId":"<operationId>","waitMs":30000,"afterSequence":0}}
+```
+
+   `finishing` means the program has returned and the result is still being
+   persisted; `result` answers `result_not_ready` until the status is terminal.
+   `waiting_for_agent` means the program called `ctx.askAgent`; the question is
+   the `agent_question_created` event with `requestId`, `revision` and `request`.
+   Answer it with `decide` or end the run with `cancel`. Keep every event page:
+   a later `afterSequence` no longer returns that event. Do not wait it out.
+
+3. When `status` is `completed`, `failed` or `cancelled`, read the value:
+
+```json lifecycle-example
+{"command":"script","extract":null,"arguments":{"operation":"result","operationId":"<operationId>"}}
+```
+
+   `completed` only states that the program returned and its value was
+   persisted; the verdicts inside `result` decide each case. `failed` and
+   `cancelled` return `result_unavailable`; the terminal event and `error`
+   carry the reason.
+
+The JavaScript program. Each case records a device assertion against the
+observation it judges, and the run stops at the first case that is not `passed`:
+
+```javascript regression-example
+'use strict';
+
+// Fixed regression: observe, act once, observe again. Per-run values arrive in
+// ctx.inputs; the returned cases are read with script operation:"result".
+module.exports.main = async function main(ctx) {
+  const cases = [];
+  async function observe(step) {
+    const read = await ctx.call('tree', { compact: true, visibleOnly: true, maxNodes: 1000 });
+    if (!read.ok) throw new Error(`${step}:tree:${read.error}`);
+    return read;
+  }
+  async function check(name, read, condition) {
+    const verdict = await ctx.assert({ name, condition, requiredEvidence: ['tree'], evidence: read.evidence });
+    cases.push({ name, verdict: verdict.verdict, reason: verdict.reason || null });
+    if (verdict.verdict !== 'passed') throw new Error(`${name}:${verdict.verdict}`);
+  }
+  const before = await observe('before');
+  await check('entry control is visible', before,
+    before.result.nodes.some(node => node.text === ctx.inputs.entryText && node.visible === true));
+  const tap = await ctx.call('tap-text', { targetText: ctx.inputs.entryText });
+  if (!tap.ok) throw new Error(`tap-text:${tap.error}`);
+  const after = await observe('after');
+  await check('expected text is shown after the tap', after,
+    after.result.nodes.some(node => node.text === ctx.inputs.expectedText));
+  await ctx.progress({ phase: 'done', cases: cases.length });
+  return { cases, actionId: tap.execution.actionId };
+};
+```
+
+The same program in Python; `ctx.assert_` takes one dictionary and envelopes are
+dictionaries:
+
+```python regression-example
+# Fixed regression: observe, act once, observe again. Per-run values arrive in
+# ctx.inputs; the returned cases are read with script operation:"result".
+def main(ctx):
+    cases = []
+
+    def observe(step):
+        read = ctx.call("tree", {"compact": True, "visibleOnly": True, "maxNodes": 1000})
+        if not read["ok"]:
+            raise Exception(f"{step}:tree:{read['error']}")
+        return read
+
+    def check(name, read, condition):
+        verdict = ctx.assert_({"name": name, "condition": condition, "requiredEvidence": ["tree"], "evidence": read["evidence"]})
+        cases.append({"name": name, "verdict": verdict["verdict"], "reason": verdict.get("reason")})
+        if verdict["verdict"] != "passed":
+            raise Exception(f"{name}:{verdict['verdict']}")
+
+    before = observe("before")
+    check("entry control is visible", before,
+          any(node.get("text") == ctx.inputs["entryText"] and node.get("visible") is True for node in before["result"]["nodes"]))
+    tap = ctx.call("tap-text", {"targetText": ctx.inputs["entryText"]})
+    if not tap["ok"]:
+        raise Exception(f"tap-text:{tap['error']}")
+    after = observe("after")
+    check("expected text is shown after the tap", after,
+          any(node.get("text") == ctx.inputs["expectedText"] for node in after["result"]["nodes"]))
+    ctx.progress({"phase": "done", "cases": len(cases)})
+    return {"cases": cases, "actionId": tap["execution"]["actionId"]}
+```
+
 ## Capability selection
 
 Use `capabilities` to inspect each command's `inputSchema` and `entrypoints.script`.

package/node_modules/@mobileaidev/segmented-fact-store-native/PREBUILDS.md

@@ -0,0 +1,29 @@
+# Release prebuilds
+
+The normal npm install path verifies `prebuilds/manifest.json` and loads the
+selected Node-API 8 artifact. It does not invoke Python, node-gyp or a compiler.
+Unsupported targets and missing/corrupt binaries fail explicitly.
+
+The 0.2.0 native package bundled in Bridge 0.4.0 includes macOS arm64/x64
+(deployment target 13.5), and Linux glibc arm64/x64 (target glibc 2.28).
+The Bridge Host still requires Node >=26.3.0 <27. Windows and musl Linux are
+outside this release's native support matrix.
+
+Maintainers can recreate all four artifacts on macOS with Apple clang,
+the official Node 26.3.0 headers and Zig 0.15.2:
+
+```sh
+node scripts/build-release-prebuilds.js /absolute/path/to/include/node /absolute/path/to/zig
+```
+
+Verify the Node and Zig downloads against their official checksums before
+building. The script compiles `src/sfs.c` and `bindings/node/sfs_node.c` and
+regenerates SHA-256 metadata. Check the diff, then run the native tests and
+Bridge's `verify:package` on every target before release. Compiler/platform
+differences may change binary hashes; the manifest must describe the files
+actually tested and packaged.
+
+`npm run build` is an explicit developer-only node-gyp build for the current
+host. Its staging step marks that artifact as `sourceBuild` and records the
+host glibc version. Such a build is not evidence for the lower release glibc
+baseline. Never substitute it for release matrix testing.

package/node_modules/@mobileaidev/segmented-fact-store-native/binding-path.js

@@ -0,0 +1,29 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+function resolveBinding() {
+  const platform = process.platform, arch = process.arch, napi = Number(process.versions.napi);
+  const glibc = platform === 'linux' ? process.report.getReport().header.glibcVersionRuntime : undefined;
+  const target = `${platform}-${arch}${platform === 'linux' ? '-glibc' : ''}`;
+  const description = `${platform}/${arch}, Node ${process.versions.node}, Node-API ${napi}, libc ${glibc || 'not-glibc'}`;
+  const manifest = require('./prebuilds/manifest.json');
+  const artifact = manifest.artifacts[target];
+  const minimum = artifact?.minGlibc;
+  const reject = (code, message) => { throw Object.assign(new Error(`${message} (${description}). No automatic source build is attempted.`), { code }); };
+  if (artifact && platform === 'linux' && !/^\d+\.\d+$/.test(minimum)) reject('native_prebuild_corrupt', 'The packaged Linux artifact has no valid minimum glibc version');
+  const olderGlibc = glibc && minimum && (Number(glibc.split('.')[0]) < Number(minimum.split('.')[0]) ||
+    (Number(glibc.split('.')[0]) === Number(minimum.split('.')[0]) && Number(glibc.split('.')[1]) < Number(minimum.split('.')[1])));
+  if (!artifact || napi < manifest.napi || (platform === 'linux' && (!glibc || olderGlibc))) {
+    reject('native_platform_unsupported', 'Supported prebuilds require macOS 13.5+ arm64/x64 or Linux glibc 2.28+ arm64/x64, and Node-API 8+');
+  }
+  const file = path.join(__dirname, 'prebuilds', target, 'segmented_fact_store.node');
+  let bytes;
+  try { bytes = fs.readFileSync(file); }
+  catch (error) { reject('native_prebuild_missing', `Cannot read packaged native artifact ${file}: ${error.code}`); }
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  if (sha256 !== artifact.sha256) reject('native_prebuild_corrupt', `Checksum mismatch for ${file}; reinstall this package`);
+  return { path: file, target, sha256, napi: manifest.napi, ...artifact };
+}
+module.exports = { resolveBinding };

package/node_modules/@mobileaidev/segmented-fact-store-native/binding.gyp

@@ -19,6 +19,7 @@
         "-Wpedantic"
       ],
       "xcode_settings": {
+        "MACOSX_DEPLOYMENT_TARGET": "13.5",
         "GCC_C_LANGUAGE_STANDARD": "c11",
         "WARNING_CFLAGS": [
           "-Wall",

package/node_modules/@mobileaidev/segmented-fact-store-native/index.js

@@ -1,5 +1,3 @@
 'use strict';
 
-const path = require('node:path');
-
-module.exports = require(path.join(__dirname, 'build', 'Release', 'segmented_fact_store.node'));
+module.exports = require(require('./binding-path').resolveBinding().path);

package/node_modules/@mobileaidev/segmented-fact-store-native/install.js

@@ -0,0 +1,5 @@
+'use strict';
+// Validate the bundled binary; never invoke a compiler or download a substitute.
+require('./index');
+const info = require('./binding-path').resolveBinding();
+process.stdout.write(`FactStore prebuild ${info.target} ${info.sha256}\n`);

package/node_modules/@mobileaidev/segmented-fact-store-native/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@mobileaidev/segmented-fact-store-native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Portable segmented mmap fact-store core and Node-API binding for AI App Bridge.",
   "main": "index.js",
-  "gypfile": true,
+  "gypfile": false,
   "files": [
     "binding.gyp",
     "index.js",
@@ -11,11 +11,17 @@
     "src",
     "bindings/node/sfs_node.c",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "binding-path.js",
+    "install.js",
+    "prebuilds",
+    "scripts",
+    "PREBUILDS.md"
   ],
   "scripts": {
-    "build": "node-gyp rebuild",
-    "test": "node --test bindings/node/test/*.test.js"
+    "build": "node-gyp rebuild && node scripts/stage-prebuild.js",
+    "test": "node --test bindings/node/test/*.test.js",
+    "install": "node install.js"
   },
   "engines": {
     "node": ">=18"

package/node_modules/@mobileaidev/segmented-fact-store-native/prebuilds/manifest.json

@@ -0,0 +1,27 @@
+{
+  "napi": 8,
+  "artifacts": {
+    "darwin-arm64": {
+      "sha256": "04c0ce98f12b8628cb6c24dd9193c147fed94ad1b99eae8da4c0abe9aa3825a8",
+      "minSystem": "macOS 13.5",
+      "compiler": "Apple clang, -O2 -mmacosx-version-min=13.5"
+    },
+    "darwin-x64": {
+      "sha256": "ed95bc5f818de53d479a842125316ac8c2447ab9d80a1c7903384e6818e7d8d8",
+      "minSystem": "macOS 13.5",
+      "compiler": "Apple clang, -O2 -mmacosx-version-min=13.5"
+    },
+    "linux-arm64-glibc": {
+      "sha256": "f476465bc0e7b8025fb3f92cfc2dc47b2d62f57aa43b48eb2f71f892f92abd59",
+      "minGlibc": "2.28",
+      "minSystem": "Linux glibc 2.28",
+      "compiler": "zig cc 0.15.2, -O2 -target *-linux-gnu.2.28"
+    },
+    "linux-x64-glibc": {
+      "sha256": "dc3d0ab106164a861c2781e7bb6771ea52e35b3735b7a87e87dfcfc5c77ae647",
+      "minGlibc": "2.28",
+      "minSystem": "Linux glibc 2.28",
+      "compiler": "zig cc 0.15.2, -O2 -target *-linux-gnu.2.28"
+    }
+  }
+}

package/node_modules/@mobileaidev/segmented-fact-store-native/scripts/build-release-prebuilds.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// Maintainer-only cross-build on macOS. Normal installation only verifies and
+// loads the checked-in artifact; it never runs a compiler.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { createHash } = require('node:crypto');
+
+const [headers, zig] = process.argv.slice(2);
+if (process.platform !== 'darwin' || !headers || !zig) {
+  throw new Error('Usage on macOS: node scripts/build-release-prebuilds.js <Node include/node directory> <Zig 0.15.2 executable>');
+}
+if (execFileSync(zig, ['version'], { encoding: 'utf8' }).trim() !== '0.15.2') throw new Error('Zig 0.15.2 is required');
+const root = path.resolve(__dirname, '..');
+const common = ['-O2', '-std=c11', '-DNAPI_VERSION=8', '-D_POSIX_C_SOURCE=200809L',
+  '-I', path.resolve(headers), '-I', path.join(root, 'include'),
+  path.join(root, 'src/sfs.c'), path.join(root, 'bindings/node/sfs_node.c')];
+const manifest = { napi: 8, artifacts: {} };
+for (const [target, compiler, args, metadata] of [
+  ['darwin-arm64', 'clang', ['-arch', 'arm64', '-mmacosx-version-min=13.5', '-bundle', '-undefined', 'dynamic_lookup'], { minSystem: 'macOS 13.5', compiler: 'Apple clang, -O2 -mmacosx-version-min=13.5' }],
+  ['darwin-x64', 'clang', ['-arch', 'x86_64', '-mmacosx-version-min=13.5', '-bundle', '-undefined', 'dynamic_lookup'], { minSystem: 'macOS 13.5', compiler: 'Apple clang, -O2 -mmacosx-version-min=13.5' }],
+  ...[['arm64', 'aarch64'], ['x64', 'x86_64']].map(([arch, triple]) => [
+    `linux-${arch}-glibc`, zig, ['cc', '-target', `${triple}-linux-gnu.2.28`, '-fPIC', '-shared', '-lpthread'],
+    { minGlibc: '2.28', minSystem: 'Linux glibc 2.28', compiler: 'zig cc 0.15.2, -O2 -target *-linux-gnu.2.28' },
+  ]),
+]) {
+  const file = path.join(root, 'prebuilds', target, 'segmented_fact_store.node');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  execFileSync(compiler, [...args, ...common, '-o', file], { stdio: 'inherit' });
+  manifest.artifacts[target] = { sha256: createHash('sha256').update(fs.readFileSync(file)).digest('hex'), ...metadata };
+}
+fs.writeFileSync(path.join(root, 'prebuilds/manifest.json'), JSON.stringify(manifest, null, 2) + '\n');

package/node_modules/@mobileaidev/segmented-fact-store-native/scripts/stage-prebuild.js

@@ -0,0 +1,17 @@
+'use strict';
+// Explicit developer build only. The release script assembles all matrix artifacts.
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const root = path.resolve(__dirname, '..');
+const target = `${process.platform}-${process.arch}${process.platform === 'linux' ? '-glibc' : ''}`;
+if (!['darwin-arm64', 'darwin-x64', 'linux-arm64-glibc', 'linux-x64-glibc'].includes(target)) throw new Error(`Unsupported release target: ${target}`);
+const bytes = fs.readFileSync(path.join(root, 'build/Release/segmented_fact_store.node'));
+const directory = path.join(root, 'prebuilds', target); fs.mkdirSync(directory, { recursive: true });
+fs.writeFileSync(path.join(directory, 'segmented_fact_store.node'), bytes);
+const file = path.join(root, 'prebuilds/manifest.json');
+const manifest = JSON.parse(fs.readFileSync(file));
+manifest.artifacts[target] = { sha256: createHash('sha256').update(bytes).digest('hex'),
+  ...(process.platform === 'linux' ? { minGlibc: process.report.getReport().header.glibcVersionRuntime } : {}),
+  minSystem: process.platform === 'darwin' ? 'macOS 13.5' : `glibc ${process.report.getReport().header.glibcVersionRuntime}`, sourceBuild: true };
+fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.3.8",
+  "version": "0.4.1",
   "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
@@ -37,6 +37,9 @@
     "bin/device-provider.js",
     "bin/command-discovery.js",
     "bin/command-request.js",
+    "bin/public-reply.js",
+    "bin/response-store.js",
+    "bin/extraction",
     "bin/execution-runtime.js",
     "bin/runtime-client.js",
     "bin/runtime-directory.js",
@@ -74,12 +77,16 @@
     "runtime/ios-wda",
     "LICENSE",
     "NOTICE",
-    "docs/RELEASE.md"
+    "docs/RELEASE.md",
+    "docs/RESPONSE_EXTRACTION.md",
+    "docs/INSTALLATION.md"
   ],
   "scripts": {
-    "check": "node -c bin/ai-app-bridge.js && node -c bin/mcp-server.js && node -c bin/ios-provider.js && node --import ./test-support/ownership-test-sandbox.js --test",
-    "test": "node --import ./test-support/ownership-test-sandbox.js --test",
-    "verify:package": "node scripts/validation/verify-package.js"
+    "check": "node -c bin/ai-app-bridge.js && node -c bin/mcp-server.js && node -c bin/ios-provider.js && node scripts/validation/test-suite.js",
+    "test": "node scripts/validation/test-suite.js",
+    "verify:package": "node scripts/validation/verify-package.js",
+    "test:functional": "node scripts/validation/test-suite.js functional",
+    "test:performance": "node scripts/validation/test-suite.js performance"
   },
   "license": "Apache-2.0",
   "dependencies": {

package/runtime/executors/android/prepare.init.gradle

@@ -31,6 +31,28 @@ gradle.beforeProject { consumer ->
         }
         consumer.pluginManager.apply(io.github.mobileaidev.aiappbridge.gradle.AiAppBridgeTestGradlePlugin)
         consumer.extensions.getByName('androidComponents').finalizeDsl { android ->
+            // Only requirements of the dependencies selected by this preparer.
+            // Read evaluated DSL; never rewrite compileSdk or guess from text.
+            def agp = consumer.plugins.getPlugin('com.android.application').class.classLoader
+                .loadClass('com.android.Version').getField('ANDROID_GRADLE_PLUGIN_VERSION').get(null).toString()
+            def actual = [compileSdk: android.compileSdk, compileSdkPreview: android.compileSdkPreview,
+                agp: agp, gradle: consumer.gradle.gradleVersion, java: System.getProperty('java.version')]
+            def issues = []
+            def unresolved = actual.compileSdk == null || actual.compileSdkPreview != null || !(agp ==~ /\d+\.\d+\.\d+/)
+            if (actual.compileSdk == null || actual.compileSdkPreview != null) issues.add('A numeric stable compileSdk is required to check the selected dependencies')
+            else if (actual.compileSdk < config.requirements.minCompileSdk) issues.add('compileSdk ' + actual.compileSdk + ' < required ' + config.requirements.minCompileSdk)
+            if (!(agp ==~ /\d+\.\d+\.\d+/)) issues.add('AGP version could not be compared: ' + agp)
+            else {
+                def got = agp.tokenize('.').collect { it.toInteger() }
+                def need = config.requirements.minAgp.tokenize('.').collect { it.toInteger() }
+                def different = (0..2).find { got[it] != need[it] }
+                if (different != null && got[different] < need[different]) issues.add('AGP ' + agp + ' < required ' + config.requirements.minAgp)
+            }
+            def report = [module: consumer.path, variant: config.variant, actual: actual, requirements: config.requirements,
+                status: issues.empty ? 'compatible' : (unresolved ? 'unresolved' : 'incompatible'), issues: issues,
+                impact: 'Selected application module and its androidTest variant; temporary runner, test sources and dependencies are added for this invocation. compileSdk is unchanged.']
+            new File(config.directory, 'android-preflight.json').text = groovy.json.JsonOutput.toJson(report)
+            if (!issues.empty) throw new GradleException('[AiAppBridge] Executor preflight: ' + issues.join('; ') + '. No project configuration was upgraded.')
             if (!android.defaultConfig.testInstrumentationRunner) {
                 android.defaultConfig.testInstrumentationRunner = 'androidx.test.runner.AndroidJUnitRunner'
             }

package/runtime/executors/playwright/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ai-app-bridge-playwright-runtime",
-  "version": "0.3.8",
+  "version": "0.4.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ai-app-bridge-playwright-runtime",
-      "version": "0.3.8",
+      "version": "0.4.1",
       "dependencies": {
         "playwright": "1.63.0"
       },

package/runtime/executors/playwright/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-app-bridge-playwright-runtime",
-  "version": "0.3.8",
+  "version": "0.4.1",
   "private": true,
   "description": "Optional, isolated browser runtime managed by AI App Bridge.",
   "engines": { "node": ">=26.3.0 <27" },