Metadata-Version: 2.4
Name: automas-maafw-runner
Version: 0.4.0
Summary: Isolated MaaFW runner service plugin for AUTO-MAS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: automas-maafw-agent-env>=0.1.4
Requires-Dist: automas-maafw-interface>=0.2.0
Requires-Dist: automas-maafw-runtime-pool>=0.2.0
Requires-Dist: json5>=0.9
Requires-Dist: packaging>=23
Requires-Dist: pydantic>=2

# automas-maafw-runner

Isolated MaaFW runner service for AUTO-MAS.

It provides `maafw.runner.v1`. The service builds run plans in the host process
and runs MaaFW through a worker subprocess so importing the service does not load
`maa` into the AUTO-MAS main process.

The wheel includes the MaaFW runtime worker code. `maa` is imported only by the
worker subprocess entrypoint, not by `MaaFWRunnerService`.

Runner environments are now selected from `maafw.runtime_pool.v1` by a
canonical requirement selector rather than by project path. The returned
environment holds a lease for the worker lifetime; callers must invoke
`MaaFWRunnerService.release_environment()` in their worker cleanup path.
Runtime Pool keeps selector venvs isolated while uv reuses a pool-local package
cache with hardlinks. Runner 0.4.0 requires Agent Env 0.1.4+ and Runtime Pool
0.2.0+, which record
installer/cache/link metadata, never composes environments through
`PYTHONPATH`, and prunes the pool-local uv cache after collecting stale
runtimes. Successful reclaim statistics and explicit unavailable/unsafe/error
states are written to the runner log.

`MaaFWRunnerService.prepare_project_environment()` prewarms both the exact
canonical Runtime Pool identity used by the first real run and the project
Agent environments. Its short preflight lease is always released; the later
worker run reacquires the same runtime without reinstalling unchanged
requirements. Optional progress events expose deterministic runtime/Agent
stages and do not invent dependency-download byte counts.

For a Managed project, the caller supplies the Store-authoritative complete
selector, `runtimeId`, `poolId`, and `runtime.python` constraint. Runner checks
the bound Pool manifest and Python identity, then reuses that trusted binding;
it does not recompute a CP313 runtime ID from the AUTO-MAS host's CP312
interpreter. Preparation and execution therefore acquire the same runtime.

Managed projects may declare `runtime.constraint`, `runtime.binding`,
`runtime.python`, and `nativePluginPaths` in
`.auto_mas_maafw_project.json`. An isolated Python Agent
reuses the worker interpreter only when the manifest explicitly sets
`runtime.sharedAgentDependenciesComplete` to `true`. Legacy, incomplete,
binary, and external Agents keep their previous routing behavior.

Runner 0.3.0 also implements ProjectInterface v2.8 hotkey substitution for
AUTO-MAS Direct:

- saved values stay readable (`E`, `Ctrl+A`, `Ctrl+Shift+A`);
- `{Name}` and `{Name}.primary` become one integer virtual key code;
- `{Name}.modifier1` and `{Name}.modifier2` follow the saved modifier order;
- Win32 uses Windows Virtual-Key codes and Adb uses Android `KeyEvent` codes;
- unsupported controller types, unknown keys and missing referenced modifiers
  fail the run-plan build with an actionable error.
