omp-fabric 1.25.4 → 1.25.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.25.5
+
+### Fixed
+
+- `docs/providers.md` now names the symptom of the one surviving `omp.wait()` failure mode. A session that gains an owner after its provider was built can start an async job it can never collect: a `bash` call naming a `cwd` runs `async: true`, the job is running, and the result still reaches the agent as a follow-up, while `omp.wait()` reports that nothing is running. Nothing errors, and the guidance a program author had was only the general instruction to start a new session. The behaviour is unchanged; the documentation now says how to recognise it.
+- `skills/fabric-exec/SKILL.md` states its job-scope precondition once instead of twice in consecutive sentences.
+
 ## 1.25.4
 
 ### Fixed

package/docs/providers.md

@@ -112,4 +112,4 @@ The shell adapter reaches the host's background-job manager. `omp.bash({ async:
 
 Auto-background is off unless `executor.autoBackground` is enabled. A guest program is straight-line code that reads a command's output on its next line, and a mid-flight handover resolves the call with a job notice in place of that output. `async: true` plus `omp.wait()` reaches the same place without that trade.
 
-Fabric resolves the owner by scanning `AgentRegistry` for the live agent whose session id matches the identity the provider captured, then takes that agent's own `asyncJobManager` (never the process singleton, which the host withholds from secondary sessions on purpose). The registry lookup is re-resolved per call, but the scope object it returns is captured when the tool definition is built, so `wait` captures it when the provider is created and a `bash` call that names a `cwd` captures it when that directory is first used. Where no such agent exists, or where the host gave it no manager, `async.enabled` is forced off: the `async` parameter leaves the advertised schema and the tool description promises no backgrounding. The same owner supplies `omp.wait()`, so a session without one leaves `async` off the advertised schema and leaves `omp.wait()` reporting that nothing is running; start a new session; do not rely on an owner appearing mid-session. A guest `omp.wait()` result is bounded by `executor.maxNestedResultChars`, the same budget every nested result gets, and an oversized one comes back with the truncation marker, not an opaque preview; unlike the shell path there is no on-disk artifact for the rest. The wait that returns a job consumes its result, so a truncated result is not retrievable again through `omp.wait()`; write a job's full output to a file when the program needs all of it. Guest sessions pin `launch.enabled` off, so the host `wait` tool's owned-service probe finds nothing and cannot start a worker broker.
+Fabric resolves the owner by scanning `AgentRegistry` for the live agent whose session id matches the identity the provider captured, then takes that agent's own `asyncJobManager` (never the process singleton, which the host withholds from secondary sessions on purpose). The registry lookup is re-resolved per call, but the scope object it returns is captured when the tool definition is built, so `wait` captures it when the provider is created and a `bash` call that names a `cwd` captures it when that directory is first used. Where no such agent exists, or where the host gave it no manager, `async.enabled` is forced off: the `async` parameter leaves the advertised schema and the tool description promises no backgrounding. The same owner supplies `omp.wait()`, so a session without one leaves `async` off the advertised schema and leaves `omp.wait()` reporting that nothing is running; start a new session; do not rely on an owner appearing mid-session. A session that gains an owner after its provider was built can start an async job it cannot collect: a `bash` call naming a `cwd` runs `async: true` and the job is running, while `omp.wait()` reports "No running background jobs to wait for." Nothing errors, and the result still reaches the agent as a follow-up. A guest `omp.wait()` result is bounded by `executor.maxNestedResultChars`, the same budget every nested result gets, and an oversized one comes back with the truncation marker, not an opaque preview; unlike the shell path there is no on-disk artifact for the rest. The wait that returns a job consumes its result, so a truncated result is not retrievable again through `omp.wait()`; write a job's full output to a file when the program needs all of it. Guest sessions pin `launch.enabled` off, so the host `wait` tool's owned-service probe finds nothing and cannot start a worker broker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-fabric",
-  "version": "1.25.4",
+  "version": "1.25.5",
   "description": "A programmable tool and agent runtime for Oh My Pi (OMP)",
   "type": "module",
   "main": "./dist/index.js",

package/skills/fabric-exec/SKILL.md

@@ -33,7 +33,7 @@ Shell tools reject on an ordinary nonzero exit; pass `settle:true` to get `{ok:f
 
 Aliases are normalized to canonical fields before host validation. Command aliases include `cmd`/`shell`/`cmdline`/`script`/`commandLine`; pattern aliases include `query`/`regex`/`search` plus `q`/`expression`/`text` for grep and `name`/`filename`/`glob`/`include` for find. Path aliases include `file`, `file_path`, camel-case path variants, `dir`/`folder`/`directory`, and target-file variants. Edit text accepts `old`/`from`/`old_string`-style and `new`/`to`/`replacement`/`new_string`-style spellings, including inside `edits`; write content accepts `contents`/`body`/`text`/`data`/`fileContent`. `ic`/`caseInsensitive`→`ignoreCase`, `globPattern`→`glob`, `ctx`→`context`, `max`→`limit`, and `start`→`offset`.
 
-`async:true` starts the command as a host background job: the call resolves at once with `details.async.jobId`, the command keeps running past this program, and its output reaches the agent as a follow-up message. The program never sees that output, and `settle` has nothing to settle on a call that resolved, so await `omp.wait()` when a later step needs its result. `omp.wait()` takes no arguments and returns the next finished background job result owned by this session; never poll it with `sleep`, because every poll is a wasted turn. Foreground calls are never backgrounded on their own, whatever their duration; `executor.autoBackground` is the setting that arms the host handover. Both `async:true` and `omp.wait()` need this session to have a live owning agent with a host job manager, so start a new session; do not rely on one appearing mid-session. Where that owner is missing, parked, or was given no manager, the schema drops `async` and passing it anyway fails with `Async bash execution is disabled`, and `omp.wait()` returns "No running background jobs to wait for."
+`async:true` starts the command as a host background job: the call resolves at once with `details.async.jobId`, the command keeps running past this program, and its output reaches the agent as a follow-up message. The program never sees that output, and `settle` has nothing to settle on a call that resolved, so await `omp.wait()` when a later step needs its result. `omp.wait()` takes no arguments and returns the next finished background job result owned by this session; never poll it with `sleep`, because every poll is a wasted turn. Foreground calls are never backgrounded on their own, whatever their duration; `executor.autoBackground` is the setting that arms the host handover. Both `async:true` and `omp.wait()` need this session to have a live owning agent with a host job manager, so start a new session; do not rely on one appearing mid-session. Where that owner is missing, parked, or has no manager, `async` leaves the schema and passing it anyway fails with `Async bash execution is disabled`, and `omp.wait()` returns "No running background jobs to wait for."
 
 Shell `timeout` is in seconds; `timeoutMs` is converted from milliseconds. Numeric strings in `limit`, `timeout`, `offset`, and `context` coerce to numbers. `null`/`undefined` is omitted only for known optional fields; required fields remain invalid so authoritative host validation still reports them. Canonical fields win when both canonical and alias spellings are present. Unknown keys still fail the excess-property type check.