machine-bridge-mcp 0.9.0 → 0.10.0

package/docs/RELEASING.md

@@ -6,7 +6,7 @@ The release invariant is:
 - `v<package version>` points to that same commit locally and on GitHub.
 - A final GitHub Release exists for the tag.
 - The GitHub Release contains the npm tarball generated from that commit.
-- `package.json`, `package-lock.json`, and the Worker-reported version agree.
+- `package.json`, `package-lock.json`, the Worker-reported version, and `browser-extension/manifest.json` (`version`/`version_name`) agree.
 - Every release-relevant change since the prior version tag has a higher package version and matching CHANGELOG section.
 - The same reviewed change is present on GitHub and in a new npm version.
 
@@ -14,7 +14,7 @@ The release invariant is:
 
 ## Prepare a version
 
-1. Set the new version without creating an automatic npm tag:
+1. Set the new version without creating an automatic npm tag. The npm version hook synchronizes the Worker and packaged browser-extension versions:
 
    ```sh
    npm version <version> --no-git-tag-version

package/docs/TESTING.md

@@ -17,7 +17,8 @@ The suite includes:
 - generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
 - syntax validation for every shipped JavaScript entry point;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
-- hierarchical agent-context precedence, custom instruction ordering, local skill discovery/loading, command override/removal, direct argv argument handling, timeout ceilings, and execution-profile denial;
+- global `model_instructions_file` injection in stdio/remote initialization, hierarchical agent-context precedence, live skill rescanning/fingerprints, automatic task ranking/loading, command override/removal, direct argv handling, timeout ceilings, and execution-profile denial;
+- machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, and broker result redaction;
 - canonical path and symbolic-link escape tests;
 - relative-path privacy and error-path redaction tests;
 - atomic create/update, optimistic hash, exact edit, and patch transaction tests;
@@ -42,8 +43,8 @@ The suite includes:
 - deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, retryable Worker handshake errors, fatal protocol errors, autonomous outage-reminder backoff, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
 - shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
 - CLI parsing, policy profiles, and client configuration boundaries;
-- live stdio MCP initialization, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
-- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure.
+- live stdio MCP initialization with session instructions, capability resolution, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
+- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, daemon-backed session bootstrap, dynamic tool advertisement, rich content, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure.
 
 ## Additional release checks
 
@@ -63,7 +64,7 @@ GitHub Actions executes the main suite on Linux, macOS, and Windows using the pi
 ## Test design rules
 
 - Tests should exercise the public boundary rather than only helper functions when practical.
-- Every permission-expanding feature needs a denial test.
+- Every permission-expanding feature needs a denial test. Browser/application features also require a token/value/content non-disclosure assertion.
 - Every bounded resource needs an over-limit test.
 - Every multi-stage mutation needs a no-partial-commit test.
 - Every remote call correlation change needs daemon replacement and cancellation coverage.
@@ -78,7 +79,7 @@ Run `npm run privacy:check` before committing and before packaging. Developers s
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, and verifies that privacy/engineering guidance, the runtime/relay/secure-file modules, contribution discipline, and privacy/release-impact checkers are present in the published package. `npm run install:test` packs the real tarball, installs it into an isolated global prefix with the documented npm 12 options, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, and verifies that privacy/engineering guidance, the runtime/relay/secure-file/browser/app modules, packaged browser extension, contribution discipline, and privacy/release-impact checkers are present in the published package. `npm run install:test` packs the real tarball, installs it into an isolated global prefix with the documented npm 12 options, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI.
 
 The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.9.0",
-  "description": "Cross-client MCP bridge for canonical local automation, files, Git, SSH resources, managed jobs, and processes over stdio or an OAuth-protected remote relay.",
+  "version": "0.10.0",
+  "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -16,6 +16,7 @@
     "mbm",
     "mbm.cmd",
     "bin",
+    "browser-extension",
     "src/local",
     "src/shared",
     "src/worker/index.ts",
@@ -38,13 +39,13 @@
     "self-test": "node tests/local-self-test.mjs",
     "version:sync": "node scripts/sync-worker-version.mjs",
     "version:check": "node scripts/sync-worker-version.mjs --check",
-    "version": "node scripts/sync-worker-version.mjs && git add package.json package-lock.json src/worker/index.ts",
+    "version": "node scripts/sync-worker-version.mjs && git add package.json package-lock.json src/worker/index.ts browser-extension/manifest.json",
     "prepack": "npm run version:check && npm run privacy:check && npm run release-impact:check",
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
-    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/browser-bridge-test.mjs && node --check tests/app-automation-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -67,7 +68,9 @@
     "secure-file:test": "node tests/secure-file-test.mjs",
     "architecture:test": "node tests/architecture-test.mjs",
     "release-state:test": "node tests/release-state-test.mjs",
-    "agent-context:test": "node tests/agent-context-test.mjs"
+    "agent-context:test": "node tests/agent-context-test.mjs",
+    "browser-bridge:test": "node tests/browser-bridge-test.mjs",
+    "app-automation:test": "node tests/app-automation-test.mjs"
   },
   "dependencies": {
     "wrangler": "4.110.0",
@@ -90,7 +93,10 @@
     "cross-platform",
     "ssh",
     "automation",
-    "managed-jobs"
+    "managed-jobs",
+    "browser-automation",
+    "desktop-automation",
+    "agent-skills"
   ],
   "repository": {
     "type": "git",

package/scripts/sync-worker-version.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packagePath = path.join(repoRoot, "package.json");
 const workerPath = path.join(repoRoot, "src", "worker", "index.ts");
+const extensionManifestPath = path.join(repoRoot, "browser-extension", "manifest.json");
 const args = new Set(process.argv.slice(2));
 const checkOnly = args.has("--check");
 const log = message => process.stderr.write(`${message}\n`);
@@ -17,24 +18,38 @@ if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(expected)) {
   fail(`package.json version is not a valid release version: ${JSON.stringify(expected)}`);
 }
 
-const source = readFileSync(workerPath, "utf8");
-const pattern = /const SERVER_VERSION = "([^"]+)";/;
-const match = source.match(pattern);
-if (!match) fail("Could not find `const SERVER_VERSION = \"...\";` in src/worker/index.ts");
+const workerSource = readFileSync(workerPath, "utf8");
+const workerPattern = /const SERVER_VERSION = "([^"]+)";/;
+const workerMatch = workerSource.match(workerPattern);
+if (!workerMatch) fail("Could not find `const SERVER_VERSION = \"...\";` in src/worker/index.ts");
 
-const current = match[1];
-if (current === expected) {
-  log(`Worker version is in sync: ${expected}`);
-  process.exit(0);
+const extension = JSON.parse(readFileSync(extensionManifestPath, "utf8"));
+const extensionVersion = expected.split(/[+-]/, 1)[0];
+const extensionParts = extensionVersion.split(".").map((value) => Number(value));
+if (extensionParts.length < 1 || extensionParts.length > 4 || extensionParts.some((value) => !Number.isInteger(value) || value < 0 || value > 65535)) {
+  fail(`package version cannot be represented as a Chromium extension version: ${expected}`);
 }
+const mismatches = [];
+if (workerMatch[1] !== expected) mismatches.push(`Worker=${workerMatch[1]}`);
+if (String(extension.version || "") !== extensionVersion) mismatches.push(`browser-extension.version=${extension.version || "<missing>"}`);
+if (String(extension.version_name || "") !== expected) mismatches.push(`browser-extension.version_name=${extension.version_name || "<missing>"}`);
 
+if (!mismatches.length) {
+  log(`Runtime versions are in sync: ${expected}`);
+  process.exit(0);
+}
 if (checkOnly) {
-  fail(`Worker version mismatch: package.json=${expected}, src/worker/index.ts=${current}. Run npm run version:sync.`);
+  fail(`Version mismatch: package.json=${expected}; ${mismatches.join(", ")}. Run npm run version:sync.`);
 }
 
-const updated = source.replace(pattern, `const SERVER_VERSION = "${expected}";`);
-writeFileSync(workerPath, updated);
-log(`Updated Worker version: ${current} -> ${expected}`);
+if (workerMatch[1] !== expected) {
+  writeFileSync(workerPath, workerSource.replace(workerPattern, `const SERVER_VERSION = "${expected}";`));
+  log(`Updated Worker version: ${workerMatch[1]} -> ${expected}`);
+}
+extension.version = extensionVersion;
+extension.version_name = expected;
+writeFileSync(extensionManifestPath, `${JSON.stringify(extension, null, 2)}\n`);
+log(`Updated browser extension version: ${extensionVersion} (${expected})`);
 
 function fail(message) {
   console.error(message);

package/src/local/agent-context.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
 import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
@@ -21,7 +22,8 @@ const MAX_COMMANDS = 128;
 const MAX_COMMAND_ARGV = 128;
 const MAX_COMMAND_ARGUMENT_BYTES = 256 * 1024;
 const COMMAND_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
-const CONFIG_KEYS = new Set(["version", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
+const TOKEN_STOP_WORDS = new Set(["the", "and", "for", "with", "from", "this", "that", "use", "using", "into", "of", "to", "a", "an", "in", "on", "is", "are", "or", "及", "和", "的", "了", "在", "用", "使用", "进行", "根据"]);
+const CONFIG_KEYS = new Set(["version", "model_instructions_file", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
 const COMMAND_KEYS = new Set(["description", "argv", "cwd", "timeout_seconds", "allow_extra_args"]);
 
 export class AgentContextManager {
@@ -46,6 +48,12 @@ export class AgentContextManager {
       scope_root: this.displayPath(state.scopeRoot),
       precedence: "global guidance first, then scope root to target directory; each directory contributes the first non-empty instruction_files candidate; later directories have higher precedence",
       config_files: state.configFiles.map((file) => this.displayPath(file)),
+      model_instructions_file: state.modelInstructions ? {
+        path: this.displayPath(state.modelInstructions.path),
+        bytes: state.modelInstructions.bytes,
+        sha256: state.modelInstructions.sha256,
+        ...(includeContent ? { content: state.modelInstructions.content } : {}),
+      } : null,
       instruction_files: state.instructions.map((item) => ({
         scope: item.scope,
         path: this.displayPath(item.path),
@@ -65,10 +73,84 @@ export class AgentContextManager {
         "Prefer run_local_command for registered repeatable commands. Use run_process or exec_command only when no registered command fits and policy permits it.",
       ],
     };
-    if (includeContent) result.effective_instructions = renderEffectiveInstructions(state.instructions, this.displayPath);
+    if (includeContent) result.effective_instructions = renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath);
     return result;
   }
 
+
+  async sessionBootstrap(args = {}, context = {}) {
+    const state = await this.discoverState(args.path || ".", context);
+    const fingerprint = capabilityFingerprint(state, []);
+    return {
+      target: this.displayPath(state.target),
+      instructions: renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath),
+      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
+      capability_refresh: {
+        strategy: "resolve_task_capabilities-rescans-on-every-call",
+        instruction_and_command_fingerprint: fingerprint,
+        skills_scanned: false,
+        generated_at: new Date().toISOString(),
+      },
+      guidance: [
+        "Call resolve_task_capabilities with the current user task before substantive local work or at the start of a reused-host conversation.",
+        "The resolver returns the effective instructions again and rescans skill and command metadata on every call; the runtime supplements application and browser capability metadata.",
+      ],
+    };
+  }
+
+  async resolveTaskCapabilities(args = {}, context = {}) {
+    const task = requiredString(args.task, "task");
+    if (task.length > 20_000) throw new Error("task exceeds 20000 characters");
+    const state = await this.discoverState(args.path || ".", context);
+    const discovered = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
+    const maxSkills = clampInt(args.max_skills, 10, 1, 50);
+    const skillMatches = discovered.skills
+      .map((skill) => ({ skill, score: relevanceScore(task, `${skill.name} ${skill.description}`) }))
+      .filter((item) => item.score > 0)
+      .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+      .slice(0, maxSkills);
+    const commandMatches = [...state.commands.values()]
+      .map((command) => ({ command, score: relevanceScore(task, `${command.name} ${command.description} ${command.argv.join(" ")}`) }))
+      .filter((item) => item.score > 0)
+      .sort((a, b) => b.score - a.score || a.command.name.localeCompare(b.command.name))
+      .slice(0, 20);
+    const selected = skillMatches[0]?.score >= 3 ? skillMatches[0].skill : null;
+    let selectedSkill = null;
+    if (selected && args.include_selected_skill !== false) {
+      const content = await readRegularUtf8(selected.entrypoint, MAX_SKILL_ENTRY_BYTES, "skill entrypoint");
+      selectedSkill = { ...publicSkill(selected, this.displayPath), instructions: content.text };
+    }
+    const recommendedTools = recommendTools(task, commandMatches.length > 0, skillMatches.length > 0);
+    const refresh = capabilityFingerprint(state, discovered.skills);
+    return {
+      task,
+      target: this.displayPath(state.target),
+      effective_instructions: renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath),
+      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
+      instruction_files: state.instructions.map((item) => ({ path: this.displayPath(item.path), scope: item.scope, bytes: item.bytes, sha256: item.sha256, precedence: item.precedence })),
+      instructions_truncated: state.instructionsTruncated,
+      refresh: { strategy: "rescan-on-every-call", fingerprint: refresh, generated_at: new Date().toISOString() },
+      selected_skill: selectedSkill,
+      skill_matches: skillMatches.map(({ skill, score }) => ({ ...publicSkill(skill, this.displayPath), score })),
+      command_matches: commandMatches.map(({ command, score }) => ({ ...publicCommands(new Map([[command.name, command]]), this.displayPath)[0], score })),
+      recommended_tools: recommendedTools,
+      host_semantics: "Machine Bridge can discover, rank, and load capabilities automatically. The MCP host remains responsible for deciding whether to call the recommended tools.",
+      warnings: publicSkillWarnings(discovered.warnings, this.displayPath),
+      truncated: discovered.truncated,
+    };
+  }
+
+  async collectModelInstructions(state, context) {
+    this.throwIfCancelled(context);
+    const path = state.modelInstructionsFile;
+    const info = await lstat(path).catch((error) => error?.code === "ENOENT" ? null : Promise.reject(error));
+    if (!info) throw new Error(`model_instructions_file does not exist: ${path}`);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error(`model_instructions_file must be a regular non-symbolic-link file: ${path}`);
+    const content = await readRegularUtf8(path, MAX_INSTRUCTION_FILE_BYTES, "model instructions file");
+    if (!content.text.trim()) throw new Error(`model_instructions_file is empty: ${path}`);
+    state.modelInstructions = { scope: "model", path, bytes: content.bytes, sha256: sha256(content.text), content: content.text, precedence: 0 };
+  }
+
   async listLocalSkills(args = {}, context = {}) {
     const state = await this.discoverState(args.path || ".", context);
     const result = await this.discoverSkills(state, {
@@ -150,31 +232,44 @@ export class AgentContextManager {
       instructionMaxBytes: DEFAULT_INSTRUCTION_MAX_BYTES,
       skillRoots: defaultSkillRoots(directories, this.home, this.policy.unrestrictedPaths === true),
       commands: new Map(),
+      modelInstructionsFile: "",
+      modelInstructions: null,
       configFiles: [],
       instructions: [],
       instructionBytes: 0,
       instructionsTruncated: false,
     };
 
-    if (this.policy.unrestrictedPaths === true && this.home) {
+    if (this.home) {
       const globalConfig = join(this.home, GLOBAL_CONFIG_RELATIVE_PATH);
       const config = await readOptionalConfig(globalConfig, this.home, false);
-      if (config) this.applyConfig(state, config, globalConfig, this.home);
-      if (this.codexHome) await this.collectDirectoryInstruction(state, this.codexHome, context, "global");
+      if (config) {
+        if (this.policy.unrestrictedPaths === true) this.applyConfig(state, config, globalConfig, this.home, { global: true });
+        else {
+          state.configFiles.push(globalConfig);
+          if (config.modelInstructionsFile) state.modelInstructionsFile = resolveConfiguredPath(config.modelInstructionsFile, this.home, this.home, this.workspace, true);
+        }
+      }
+      if (state.modelInstructionsFile) await this.collectModelInstructions(state, context);
+      if (this.policy.unrestrictedPaths === true && this.codexHome) await this.collectDirectoryInstruction(state, this.codexHome, context, "global");
     }
 
     for (const directory of directories) {
       this.throwIfCancelled(context);
       const configPath = join(directory, CONFIG_RELATIVE_PATH);
       const config = await readOptionalConfig(configPath, directory, true);
-      if (config) this.applyConfig(state, config, configPath, directory);
+      if (config) this.applyConfig(state, config, configPath, directory, { global: false });
       await this.collectDirectoryInstruction(state, directory, context, "project");
     }
     return state;
   }
 
-  applyConfig(state, config, configPath, baseDir) {
+  applyConfig(state, config, configPath, baseDir, { global = false } = {}) {
     state.configFiles.push(configPath);
+    if (config.modelInstructionsFile) {
+      if (!global) throw new Error(`model_instructions_file is only allowed in the global agent config: ${configPath}`);
+      state.modelInstructionsFile = resolveConfiguredPath(config.modelInstructionsFile, baseDir, this.home, this.workspace, true);
+    }
     if (config.instructionFiles) state.instructionFiles = [...config.instructionFiles];
     if (config.instructionMaxBytes !== null) {
       state.instructionMaxBytes = config.instructionMaxBytes;
@@ -385,7 +480,10 @@ function normalizeConfig(value, configPath) {
   if (!isPlainRecord(value)) throw new Error(`agent config must be a JSON object: ${configPath}`);
   for (const key of Object.keys(value)) if (!CONFIG_KEYS.has(key)) throw new Error(`unknown agent config field '${key}': ${configPath}`);
   if (value.version !== 1) throw new Error(`agent config version must be 1: ${configPath}`);
-  const result = { instructionFiles: null, instructionMaxBytes: null, skillRoots: null, commands: new Map() };
+  const result = { modelInstructionsFile: null, instructionFiles: null, instructionMaxBytes: null, skillRoots: null, commands: new Map() };
+  if (value.model_instructions_file !== undefined) {
+    result.modelInstructionsFile = requiredString(value.model_instructions_file, "model_instructions_file");
+  }
   if (value.instruction_files !== undefined) {
     result.instructionFiles = validateInstructionFiles(value.instruction_files, configPath);
   }
@@ -556,6 +654,62 @@ async function listSkillFiles(root, maxFiles, context, throwIfCancelled) {
   return { files, truncated };
 }
 
+function capabilityFingerprint(state, skills) {
+  return sha256(JSON.stringify({
+    configs: state.configFiles,
+    instructions: [state.modelInstructions?.sha256 || "", ...state.instructions.map((item) => item.sha256)],
+    skills: skills.map((skill) => [skill.id, skill.sha256]),
+    commands: [...state.commands.values()].map((command) => [command.name, command.argv]),
+  }));
+}
+
+function relevanceScore(task, candidate) {
+  const taskTokens = tokenize(task);
+  const candidateTokens = tokenize(candidate);
+  if (!taskTokens.size || !candidateTokens.size) return 0;
+  let score = 0;
+  for (const token of taskTokens) {
+    if (candidateTokens.has(token)) score += token.length >= 6 ? 2 : 1;
+  }
+  const taskLower = task.toLowerCase();
+  const candidateLower = candidate.toLowerCase();
+  if (candidateLower.includes(taskLower) || taskLower.includes(candidateLower)) score += 4;
+  return score;
+}
+
+function tokenize(value) {
+  const text = String(value || "").toLowerCase();
+  const tokens = new Set();
+  for (const raw of text.match(/[a-z0-9_][a-z0-9_.-]{1,}/g) || []) {
+    const token = raw.replace(/^[.-]+|[.-]+$/g, "");
+    if (token.length >= 2 && !TOKEN_STOP_WORDS.has(token)) tokens.add(token);
+  }
+  for (const sequence of text.match(/[\p{Script=Han}]{1,}/gu) || []) {
+    if (!TOKEN_STOP_WORDS.has(sequence)) tokens.add(sequence);
+    const minimumSize = sequence.length === 1 ? 1 : 2;
+    for (let size = minimumSize; size <= Math.min(3, sequence.length); size += 1) {
+      for (let index = 0; index + size <= sequence.length; index += 1) {
+        const token = sequence.slice(index, index + size);
+        if (!TOKEN_STOP_WORDS.has(token)) tokens.add(token);
+      }
+    }
+  }
+  return tokens;
+}
+
+function recommendTools(task, hasCommands, hasSkills) {
+  const lower = task.toLowerCase();
+  const tools = ["agent_context"];
+  if (hasSkills) tools.push("load_local_skill");
+  if (hasCommands) tools.push("run_local_command");
+  if (/browser|chrome|edge|brave|网页|浏览器|表单|网站/.test(lower)) tools.push("browser_status", "browser_list_tabs", "browser_inspect_page", "browser_action", "browser_fill_form");
+  if (/app|application|gui|window|应用|软件|窗口|界面/.test(lower)) tools.push("list_local_applications", "inspect_local_application", "operate_local_application");
+  if (/git|commit|branch|diff|仓库|提交|分支/.test(lower)) tools.push("git_status", "git_diff");
+  if (/test|build|lint|command|terminal|测试|构建|命令|终端/.test(lower)) tools.push(hasCommands ? "run_local_command" : "run_process");
+  if (/file|code|source|edit|write|文件|代码|源码|修改|写入/.test(lower)) tools.push("read_file", "search_text", "edit_file", "apply_patch");
+  return [...new Set(tools)];
+}
+
 function publicSkill(skill, displayPath) {
   return {
     id: skill.id,
@@ -626,7 +780,7 @@ async function readOptionalRegularUtf8(filePath, maxBytes, label) {
 }
 
 async function readRegularUtf8(filePath, maxBytes, label) {
-  const handle = await open(filePath, "r");
+  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
   try {
     const info = await handle.stat();
     if (!info.isFile()) throw new Error(`${label} is not a regular file: ${filePath}`);