@abot-ai/runtime 1.7.0 → 1.8.1

package/docs/plugins.md

@@ -237,12 +237,71 @@ options, or skill lists in `runtime.config.json`. Installing or changing a
 plugin means changing its package under `plugins/`; runtime config only decides
 whether that installed capability is available.
 
+## Runtime Platform Compatibility
+
+A plugin can declare where its code can run using a separate manifest extension:
+`extensions["ai.abot.compatibility"] = { "version": 1, "runtimePlatforms": ["linux", "darwin"] }`.
+The executable `ai.abot.runtime` extension remains at version 1.
+
+`runtimePlatforms` is a non-empty, duplicate-free list of Node platform names:
+`linux`, `darwin` (macOS), or `win32` (Windows). Unsupported versions, platform
+names and fields are rejected. Declare only platforms on which the complete
+plugin can safely load; individual operations may still require permissions,
+external programs or a connected computer.
+
+The declaration describes the **Runtime host**, not the browser or the computer
+controlled by a tool. A Linux Runtime in WSL or a Linux Docker container remains
+`linux`, including when SYSTEM controls a Windows Companion. It does not grant
+permissions or replace the tool's request-time target checks.
+
+Hosts with this compatibility support apply the following policy before resolving
+plugin settings/secrets or importing executable plugin code:
+
+- A declared matching platform can load, subject to the existing saved selection.
+- A declared non-matching platform cannot load.
+- Without a declaration, existing non-Windows behavior is preserved. Native
+  Windows reports **Compatibility not declared** and does not load the plugin.
+
+Installed, onboarding and model-selection views show compatibility separately
+from saved plugin/tool selection. Changing hosts does not rewrite saved selection
+or erase settings and keys. An incompatible package remains inspectable,
+configurable and removable. It can be installed for later use on a supported
+host; the review and installation result explain that it will not load here.
+Applying configuration cannot bypass the loader gate.
+
+**Older hosts:** ABot 1.7.0 accepts and preserves additional extension namespaces
+but does not enforce this declaration. Its existing behavior remains unchanged.
+This metadata is not an enforcement guarantee on older hosts, nor a claim that
+ABot 1.7.0 or its bundled plugins support native Windows. Existing bundled plugin
+manifests are not certified for Windows by this contract change.
+
+The required `windows-compatibility` CI job builds the Runtime, checks types and
+plugin packages, and runs the focused platform contract and loader suites on
+Windows with Node 24. It complements the Linux validation and macOS Companion
+checks; it does not certify all native Windows tool operations or Store packaging.
+
 ## Manifest Contract
 
 `@abot-ai/runtime/plugin-sdk` is the single public plugin-authoring entrypoint. It
 exports the manifest constants and types, entrypoint contract, and bounded
 authoring helpers consumed by plugin implementations.
 
+The SDK's `readBoundedRegularFile(path, { rootPath, maxBytes, signal })` reads one
+regular file within its authorized root and returns bounded bytes or a typed
+refusal. On native Windows, it uses the same C# handle primitives as `filesystem`,
+compiled by the built-in Windows PowerShell for each read. Root and file identity
+are checked before reading; traversal rejects reparse points beneath the root,
+including junctions. Binary content and documents up to 10 MiB are covered by
+native tests; each caller still sets its own size limit. Linux/macOS retain the
+existing no-follow file-descriptor path.
+
+A Windows policy or compiler restriction returns `safe_open_unsupported`. Plugins
+must report that safe reading is unavailable and avoid automatic retries or a
+less restricted fallback. Cancellation stops the helper and throws `AbortError`;
+a helper deadline (15 seconds) or ordinary I/O failure remains an explicit error.
+This SDK support does not enable Windows compatibility in a plugin manifest.
+Each plugin must still declare and validate its own Windows support.
+
 The manifest follows the Agent Plugins 1.0 package shape and keeps the local
 executable contract under `extensions.ai.abot.runtime`:
 
@@ -328,25 +387,34 @@ and exposes the OR-union of matching capabilities. The Worker still selects
 the concrete capability and controls.
 
 Supervisor routing and delegated Planner each receive one optional, passive
-text brief through the same shared projection from the
-request-filtered registry used by `capability-brief`. It first includes every
-offered operation's tool name, operation id, summary and catalog groups when
-that complete description set fits the existing context headroom. Request-bound
-facts already present in summaries, such as available execution targets, remain
-intact. Admission reserves each consumer's existing context, configured
-instructions, calibration, output and safety headroom and stays below the
-existing compaction threshold. Root steering is reserved only for Supervisor;
-it does not enter the bounded Planner call.
-
-When complete descriptions cannot fit, the existing compact representations
-remain available under a 512-token ceiling: tool names with operation ids and
-groups, tool names by group, group counts and effects, or no brief. The declared
-level makes omitted detail explicit; it never implies that omitted detail means
-an operation is unavailable. Group ids remain in the response schema in every
-mode. No subset of tools is selected, no summary is truncated, and no model call
-summarizes the catalog. The brief carries no input schemas, execution authority
-or completion evidence. It is confined to delegation decisions; Worker selection,
-Execution Agent context, approval and terminal-response contracts are unchanged.
+brief from the request-filtered registry. They share EA's plain-text discovery
+catalog, organized by selectable group id with ` | ` between group entries:
+
+```text
+Tool groups: scheduling: schedules | write: filesystem [edit_file, write_file]
+Plugin descriptions: filesystem: Inspect, read, write, and edit files within configured agent-work and workspace roots.
+```
+
+Each group lists its plugins and their tool names as `group: plugin [tool names]`.
+Native tools appear by name without a plugin wrapper; groups without tool entries
+remain bare ids. A plugin may span groups, and a group may contain several plugins.
+Reserved characters in tool names are percent-encoded. Each optional plugin
+description appears once on the separate `Plugin descriptions:` line, with
+whitespace normalized, `|` displayed as `/`, and at most 160 Unicode code points
+plus `....` when truncated. Missing descriptions leave the tool bindings intact;
+the description line is omitted when none are available. This index lists tool
+names, not individual operations, summaries or parameter schemas. Worker still
+receives the exact operations and controls from the selected groups.
+
+Admission preserves the existing context, configured instructions, calibration,
+output and safety reserves and compaction threshold. Root steering is reserved
+only for Supervisor; it does not enter the bounded Planner call. When the whole
+plugin catalog cannot fit, complete group counts and effects remain available
+under the existing 512-token ceiling, or the optional brief is omitted. Legal
+group ids remain in the response schema. Neither fallback restores operation
+details, selects a partial set of plugins, or adds a model decision. The brief
+carries no execution authority or completion evidence. EA's output and the
+Worker, approval and terminal-response contracts remain unchanged.
 Before each Supervisor routing or Planner attempt, including structured-output repairs,
 the optional brief is reselected against the actual projected messages plus
 current consumer-specific calibration and context. It retains its reference position or is
@@ -364,15 +432,15 @@ receive it. Planner uses this same brief instead of a separate aggregate-tag
 catalog. Its existing group-selection schema and Worker scope enforcement stay
 unchanged; descriptions do not select a group or execute an operation.
 
-Under `execution-agent-v1`, the canonical root receives group descriptions
-generated from member capability ids and summaries, and may mechanically open
-or extend its own RoleCall scope.
-It then selects a concrete capability only from that active scope. Scope
-updates, capability binding, payload authoring, adapter execution, and
-settlement use the same ledger and capability engine as delegated Worker
-execution. Unknown, empty, invalid, repeated, or no-op scopes are rejected
-rather than widened to the full catalog. A request with no Worker capabilities
-may still invoke an unscoped Worker for a knowledge-only result.
+Under `execution-agent-v1`, the canonical root receives the same plain-text
+discovery catalog shown above. Descriptions supply discovery context, not
+instructions or authority. The root may mechanically open or extend
+its RoleCall scope. Only then does the active catalog expose each capability's
+id, exact summary, and effect, with selection controls in the decision schema.
+It selects concrete capabilities only from that active scope. Scope updates,
+binding, payload authoring, execution, and settlement retain the shared engine
+and ledger. Unknown, empty, invalid, repeated, or no-op scopes are rejected. Requests
+without Worker capabilities may still invoke an unscoped knowledge-only Worker.
 
 Skill ids resolve only inside the same plugin package. For the example above,
 the loader reads:
@@ -492,6 +560,36 @@ they must not include secrets and they never act as instructions, new user
 intent, or proof that the whole request completed. See
 [tool-execution-result-evidence-contract.md](tool-execution-result-evidence-contract.md).
 
+### Reporting a confirmed mutation
+
+Use `successResult()` for ordinary successful observations. After the owning
+plugin has confirmed a completed mutation, use `mutationSuccessResult()` to
+preserve its receipt and add the Runtime's required `data.mutationEvidence: true`:
+
+```ts
+import { mutationSuccessResult } from "@abot-ai/runtime/plugin-sdk";
+
+// apiReceipt is the result of a completed write already confirmed by this handler.
+return mutationSuccessResult({
+  output: "The article was published.",
+  data: apiReceipt,
+}, context.resultBudget);
+```
+
+The helper does not execute the operation or independently verify its effect.
+Do not use it for a failed, ambiguous, pending, or no-op operation. It retains
+the same JSON and result-size bounds as `successResult()`; a rejected receipt
+returns a failure without asserting mutation evidence. The existing generic
+helper does not infer a mutation from `ok`, `progress`, prose, or the presence of
+arbitrary data. Explicit `actions`, `progress`, and other result fields remain
+available to the owning plugin.
+
+The adapter records operation outcome separately from observed effect.
+For a `mutating` operation, `ok: true` without `mutationEvidence: true` is
+classified as `mutation_evidence_missing`. The new helper supplies that marker
+after the plugin has established the evidence; it does not change the Runtime's
+classification rules or prove completion of the user's whole request.
+
 ### EXEC output storage
 
 EXEC captures stdout and stderr in private files under its injected `stateDir`.
@@ -654,6 +752,54 @@ counts imply full-file coverage.
 
 No concrete tool or skill mapping should be added anywhere under `src/runtime`.
 
+### Native Windows plugin support
+
+The native Windows group contains `capability-brief`, `code-outline`,
+`document-reader`, `exec`, `filesystem`, `json-inspector`, `local-search`, `memory`, `web`,
+`project-orientation`, `system-probe`, and `system`.
+Each declares `win32` in its versioned
+`ai.abot.compatibility` extension, alongside its existing Linux and macOS support.
+Compatibility uses the Runtime process OS, not the browser or a paired computer.
+A Windows-only plugin should declare only `win32`; other hosts will not load it.
+
+On native Windows, SYSTEM provides `system_targets`, `system_command`,
+`system_applications`, and `system_launch`. Commands run in local PowerShell and
+retain existing approvals, cancellation, and protected output handling. Desktop
+observation and input (`computer_*`) are excluded from the request catalog in
+this phase. Linux/macOS Runtime and WSL/Docker Companion routes retain their
+existing capabilities. This phase does not add screenshot OCR.
+
+`system-probe` reports Windows load averages as unsupported instead of presenting
+the OS's placeholder zeros as measured load. Its default disk probe uses the
+Runtime installation's filesystem; an explicit path selects that path's volume.
+
+`code-outline` uses the SDK's bounded file reader on Windows, with the same
+authorized roots, parser and output limits as Linux/macOS. If safe reading is
+unavailable, it reports the restriction explicitly and tells the model not to
+retry or bypass it. See [Code Outline](../plugins/code-outline/README.md).
+
+`document-reader` uses the SDK's bounded Windows reader for configured paths
+and request attachments, with shared text, Office and PDF parsers and limits.
+A blocked reader reports an explicit no-retry restriction.
+See [Document Reader](../plugins/document-reader/README.md).
+
+`json-inspector` uses the SDK's bounded Windows reader with the existing path,
+UTF-8, size and summary limits. A blocked reader reports an explicit no-retry
+restriction. See [JSON Inspector](../plugins/json-inspector/README.md).
+
+`project-orientation` uses the SDK's bounded Windows reader for package
+metadata and retains its existing directory-tree and result limits. Blocked
+manifest reads return an explicit no-retry restriction.
+See [Project Orientation](../plugins/project-orientation/README.md).
+
+`local-search` uses native Windows ripgrep through a PowerShell/C# helper that
+pins the selected path and owns the child process through a Job Object. Existing
+query, output, timeout and cancellation limits still apply. A blocked helper
+fails explicitly without a retry or policy bypass.
+See [Local Search](../plugins/local-search/README.md).
+
+Enabling manifests alone is not a validation step.
+
 ### Shared Computer access
 
 Plugins that need host facilities can import the opt-in

package/docs/tool-execution-result-evidence-contract.md

@@ -96,6 +96,63 @@ secrets. Secret acquisition and redaction remain responsibilities of the
 owning tool/host boundary; core orchestration must not guess sensitive field
 semantics from arbitrary JSON keys.
 
+### Observed-content secret protection, version 1
+
+Companion and the internal passive collector own host-side protection. The same
+collector protects SPARK whether it runs inside Companion or locally in Runtime.
+SYSTEM owns a separate implementation for its independent native operations.
+The implementations share conformance cases, not a runtime detector dependency.
+
+Required text checks preserve the existing SPARK whole-field detector: credential
+labels, authorization/userinfo, supported provider tokens, private-key indicators
+and compact JOSE tokens, including the supported escaped and encoded forms.
+Successful checking means no known indicator was found; it is not a claim that
+the content contains no secrets. Unknown encodings and arbitrary unlabelled
+secrets remain outside detection. SPARK's existing collection semantics stay intact.
+
+Check full observed fields before excerpts or delivery. A suspected field is
+replaced with `[REDACTED]`; unchecked content must not reach logs, model evidence,
+continuation snapshots or cross-host transport. Desktop frame/media retention
+also follows these checks. Temporary local acquisition belongs inside the checking
+boundary; checking must not use a remote model.
+An incomplete required check, malformed encoding or scanner failure withholds
+the affected content and preserves only a non-sensitive technical receipt.
+
+Command capture may write unchecked bytes to private local files using the existing
+disk-backed capture mechanism. After natural EOF, both full streams must pass
+checking before any read or delivery is admitted. Suspected content is replaced
+with checked text; failed checking withholds output and attempts to remove the raw
+capture. Existing retention cleanup handles leftovers after failure or interruption.
+This permits temporary raw disk storage, not model access before checking; the
+compaction model must also receive only checked text. Deletion is ordinary file
+cleanup, not a claim of forensic erasure.
+
+There is no new logical total-output quota: admitted complete stdout/stderr retain
+the existing context-text handoff, canonical evidence and core compaction path.
+Full-text checking and delivery still materialize text in memory. Capture/storage
+failure does not erase an already dispatched action or justify replaying it for
+output. Published byte counts and digests describe admitted bytes only.
+
+Version 1 desktop checks cover descriptive metadata and accessibility text.
+Suspicion in those fields also withholds the associated image before frame or
+media retention. Control bindings, coordinates and dispatch receipts keep their
+mechanical meaning; sensitive actionable catalog identities are withheld rather
+than replaced by a synthetic actionable identifier. Pixel-only content is not
+inspected: OCR and its deployment requirements are explicitly deferred.
+
+SYSTEM requires `host_secret_protection_v1` before dispatching protected Companion
+operations, and the existing complete-output capability for commands. A missing
+capability is an upgrade-required failure before dispatch, not a fallback to an
+unprotected path. Installed Companion and independently distributed SYSTEM bundles
+must be validated separately; changing Runtime source does not update either.
+
+Conformance covers known indicators, ordinary text, encodings and chunk boundaries,
+late suspicion, scanner/transport failure, pre-admission storage and frame sinks,
+and preservation of exact clean large output and accepted action receipts. Both
+supported implementations must pass the same applicable cases before release.
+This contract does not sandbox an arbitrary third-party plugin's own filesystem
+or network access, nor retroactively remove previously retained observations.
+
 ## Canonical Lifecycle
 
 ```text

package/docs/windows-companion-store.md

@@ -10,6 +10,11 @@ The Store app and Runtime have separate releases.
 
 ## Connection experience
 
+A Runtime running directly on Windows uses local access and collection without
+Companion pairing. The Store connection remains available for a Windows computer
+used with a WSL or Docker Runtime. Spark also requires an installation-wide
+collection acknowledgment in the Web UI; accepting it does not start collection.
+
 The Web UI links to the Store for one installation. The user returns to ABot,
 requests a connection link and explicitly opens Companion. Companion shows the
 Runtime address and asks for confirmation before pairing. Users who already

package/package.json

@@ -18,12 +18,14 @@
   },
   "description": "Open runtime for local AI agents.",
   "devDependencies": {
+    "@actions/expressions": "^0.3.61",
     "@types/node": "^25.5.2",
     "esbuild": "^0.28.2",
     "prettier": "^3.8.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.1"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
@@ -181,5 +183,5 @@
   },
   "type": "module",
   "types": "./dist/src/runtime/index.d.ts",
-  "version": "1.7.0"
+  "version": "1.8.1"
 }

package/plugins/capability-brief/plugin.json

@@ -2,8 +2,12 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "capability-brief",
   "version": "1.0.0",
-  "description": "Describe the request-effective ABot tool catalog on demand.",
+  "description": "Describe the tools and operations available to the current request.",
   "extensions": {
+    "ai.abot.compatibility": {
+      "version": 1,
+      "runtimePlatforms": ["linux", "darwin", "win32"]
+    },
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",

package/plugins/code-outline/README.md

@@ -0,0 +1,20 @@
+# Code Outline
+
+Extracts a bounded structural outline from one source file on Linux, macOS,
+or native Windows. Relative paths use the configured agent work directory;
+`workspace/...` uses configured workspace sources. Absolute host paths must
+remain inside an authorized root. Request path restrictions still apply.
+
+The existing parser and limits are shared across platforms: at most 512 KiB
+of source, 160 symbols, 40 imports and 6,000 output characters. JavaScript and
+TypeScript use the syntax parser; other supported formats use the existing
+pattern-based outline. The tool does not execute the source.
+
+## Windows requirements
+
+Windows uses the SDK's built-in Windows PowerShell/C# reader. No Companion,
+WSL, Docker, administrator elevation or execution-policy bypass is required.
+If computer policy blocks the reader, the tool reports
+`code_outline_safe_read_unavailable` and tells the model not to retry or
+bypass the restriction. Cancellation stops the read. Reparse-point escapes
+and files larger than the limit are rejected without returning source.

package/plugins/code-outline/plugin.json

@@ -2,8 +2,9 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "code-outline",
   "version": "0.1.1",
-  "description": "Extract a bounded structural outline from one source file.",
+  "description": "Read the structure, imports, and symbols of a source file.",
   "extensions": {
+    "ai.abot.compatibility": { "version": 1, "runtimePlatforms": ["linux", "darwin", "win32"] },
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",

package/plugins/code-outline/source/index.ts

@@ -13,6 +13,7 @@ import {
 } from "../../../src/plugin-sdk/index.js";
 
 import { buildCodeOutline } from "./parser.js";
+import { codeOutlineReadFailure } from "./read-failure.js";
 
 const MAX_FILE_BYTES = 512 * 1024;
 const DEFAULT_MAX_SYMBOLS = 160;
@@ -36,7 +37,8 @@ export default defineRuntimePlugin((context) => {
         const pathContext = {
           ...context,
           runtimePathResolver:
-            executionContext?.runtimePathResolver ?? context.runtimePathResolver,
+            executionContext?.runtimePathResolver ??
+            context.runtimePathResolver,
         };
         try {
           const requestedPath = readRequiredString(params.path, "path");
@@ -47,26 +49,9 @@ export default defineRuntimePlugin((context) => {
           const file = await readBoundedRegularFile(target.absolutePath, {
             maxBytes: MAX_FILE_BYTES,
             rootPath: target.rootPath,
+            signal: executionContext?.abortSignal,
           });
-          if (!file.ok && file.reason === "not_regular_file") {
-            return failureResult({
-              errorCode: "code_outline_target_not_file",
-              message:
-                "The requested code-outline target is not a regular file.",
-            });
-          }
-          if (!file.ok && file.reason === "too_large") {
-            return failureResult({
-              errorCode: "code_outline_file_too_large",
-              message: `The requested file exceeds the ${MAX_FILE_BYTES}-byte outline limit.`,
-            });
-          }
-          if (!file.ok) {
-            return failureResult({
-              errorCode: "code_outline_file_changed",
-              message: "The requested file changed while it was being read.",
-            });
-          }
+          if (!file.ok) return codeOutlineReadFailure(file, MAX_FILE_BYTES);
           const source = file.bytes.toString("utf8");
           const maxSymbols = readBoundedInteger(params.maxSymbols, {
             defaultValue: defaultMaxSymbols,
@@ -118,6 +103,17 @@ export default defineRuntimePlugin((context) => {
             },
           });
         } catch (error) {
+          const readWasAborted =
+            executionContext?.abortSignal?.aborted &&
+            error instanceof Error &&
+            error.name === "AbortError";
+          if (readWasAborted) {
+            return failureResult({
+              errorCode: "code_outline_cancelled",
+              message: "Code outline inspection was cancelled.",
+              interruption: "aborted",
+            });
+          }
           return failureFromError(error, {
             fallbackCode: "code_outline_failed",
             fallbackMessage: "Code outline inspection failed.",

package/plugins/code-outline/source/read-failure.ts

@@ -0,0 +1,40 @@
+import {
+  failureResult,
+  type BoundedRegularFileReadFailure,
+} from "../../../src/plugin-sdk/index.js";
+
+export function codeOutlineReadFailure(
+  file: BoundedRegularFileReadFailure,
+  maxBytes: number,
+) {
+  switch (file.reason) {
+    case "not_regular_file":
+      return failureResult({
+        errorCode: "code_outline_target_not_file",
+        message: "The requested code-outline target is not a regular file.",
+      });
+    case "too_large":
+      return failureResult({
+        errorCode: "code_outline_file_too_large",
+        message:
+          "The requested file exceeds the " + maxBytes + "-byte outline limit.",
+      });
+    case "outside_root":
+      return failureResult({
+        errorCode: "code_outline_outside_root",
+        message:
+          "The requested file resolves outside its authorized root. Do not retry this target or bypass the path restriction.",
+      });
+    case "safe_open_unsupported":
+      return failureResult({
+        errorCode: "code_outline_safe_read_unavailable",
+        message:
+          "Safe file reading is unavailable on this system. On Windows, computer policy may block the required PowerShell/C# helper. Do not retry or bypass this restriction with another tool; ask the user to check the system requirements or contact their administrator.",
+      });
+    case "changed_during_read":
+      return failureResult({
+        errorCode: "code_outline_file_changed",
+        message: "The requested file changed while it was being read.",
+      });
+  }
+}