# Distinct local agent

This package is a small, standard-library-first worker boundary. It provides a
bounded FIFO, five-second snapshots, cooperative cancellation, signed request
envelopes, local GGUF discovery, a `llama.cpp` subprocess runner, optional
CPU-package energy meters, and an injectable server transport.

## Security boundary

Generated model text is returned as data and is never evaluated by the host.
The default `dspy-rlm` harness may execute generated Python only inside DSPy's
Deno/Pyodide interpreter. Its command is lock-pinned and cached-only, and the
interpreter receives no filesystem, network, environment, subprocess, FFI,
system or dynamic-import grants. That boundary is meaningful, but it is not a
substitute for isolating the native `llama.cpp`, Python and Deno processes.

The controller necessarily needs outbound HTTPS to poll the server. Inference
and generated-code children should receive neither its credential nor its
environment. `distinct_tools` is imported lazily; missing tools or versions
fail closed. The default inference runner has no tools and no internet.

Production launchers must add an OS boundary before accepting untrusted work:

- Windows: create a restricted token/AppContainer, attach children to a Job
  Object for process, memory and lifetime limits, use explicit ACLs and a
  scratch directory, and enforce network policy separately. A Job Object alone
  does not block network access. These hooks are documented but not yet
  implemented here.
- Linux: use a dedicated unprivileged UID, user/mount/PID/network namespaces,
  read-only root, private scratch `tmpfs`, dropped capabilities,
  `no_new_privs`, seccomp, and cgroup v2 limits. A rootless OCI container,
  gVisor, or a microVM can supply these hooks. They are not implemented here.

HMAC envelopes require TLS and a unique per-agent secret. Nonces are stored in
a bounded, fail-closed replay cache. The MVP keeps credentials only in process
memory and strips them from inference-child environments; restart and pair
again. A persistent future client must use the OS keychain, never source,
command-line arguments, task payloads or logs.

An installable worker should be published as an immutable, versioned artifact
with a platform code signature plus a separately signed manifest containing
its SHA-256 digest. The server should offer only supported releases. Pairing
should use a short-lived, one-use code after login, exchanged over TLS for a
random per-agent credential; no reusable user or agent secret belongs in the
download, page source, URL, or log. Updates must re-check both signatures and
digests before activation and retain the previous binary for rollback.

Workers remain outside the server trust boundary: outputs, capability claims,
queue positions, timings, and energy readings are assertions, not trusted
billing evidence. Conversely, a worker treats every prompt and model-produced
tool request as hostile input, applies local resource limits, and never passes
its controller credential into inference, tools, or generated-code children.

## Energy scope

`pyRAPL` and Windows `Energy Meter(RAPL_Package0_PKG)` are optional and measure
the CPU package only. They do not measure the GPU, display, charger loss, or
whole PC. Unsupported and failed measurements contain `available: false` and
`joules: null`; the worker never substitutes TDP or utilization estimates.

## Models and runner

Discovery recognizes local GGUF files for OLMoE-1B-7B-0924-Instruct,
OLMo-2-1124-7B-Instruct. It performs no download and
executes no remote model code. `LlamaCppRunner` invokes an installed
`llama-cli` with an argument array and `shell=False`.

The catalogue is short on purpose. Every model in it has a published,
model-specific assessment of its training, recorded with its primary source in
`model_assessments.json`; a release nobody has published anything about is not
offered, because measured and disclosed environmental cost is the only claim
this project makes. The two OLMo entries are first party end to end -- Ai2
trained the models, measured the training, quantised the weights and published
the digests -- and both are pinned by repository, revision and SHA-256.


An explicit deterministic smoke test is:

```console
python -m distinct_agent --model olmoe-1b-7b-0924-instruct=/models/olmoe.gguf --demo-prompt "hello"
```

To pair with a server, log in there, generate a one-use code, and run:

```console
python -m distinct_agent --server https://owner-space.hf.space --pair XXXX-XXXX-XXXX-XXXX --name "My efficient worker" --model olmoe-1b-7b-0924-instruct=/models/olmoe.gguf --llama-cli /opt/llama/llama-cli
```

The default harness is `dspy-rlm`; startup performs its cached-only
Deno/Pyodide readiness probe and refuses to pair if that sandbox is not ready.
`--harness structured` selects the bounded structured tool loop instead.
`--demo-runner` is an explicit test mode and defaults to the structured
harness; it must not be presented as real model inference.

For a source installation, prepare the exact lock-pinned runtime once before
starting the worker:

```console
python -m distinct_agent --prepare-rlm
```

That command may fetch dependencies. Ordinary inference cannot. Release builds
embed the prepared cache and managed Deno executable.

The Gradio transport calls only `/agent_pair`, `/agent_sync`, `/agent_accept`,
and `/agent_complete`. Signed calls use canonical JSON, a fresh nonce, and the
server-compatible HMAC body digest. Sync responses are schema-checked before
jobs reach the local FIFO; both admission and rejection are acknowledged.
Credentials remain memory-only in this MVP, so restarting requires a fresh
pairing code. `AgentTransport` remains injectable for tests or future native
HTTP transports.