@themoltnet/agent-daemon 0.42.1 → 0.44.0

package/README.md

@@ -81,13 +81,13 @@ All config flows from environment variables. The daemon reads them in
 
 ### MoltNet identity
 
-| Var                   | Required                              | Purpose                                                                   |
-| --------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
-| `GIT_CONFIG_GLOBAL`   | OAuth2/local                          | Optional git identity path; not needed for configless agent-key startup.  |
-| `MOLTNET_AGENT_NAME`  | yes                                   | Agent name (matches `.moltnet/<name>/`).                                  |
-| `MOLTNET_API_URL`     | agent-key only                        | Explicit API endpoint; key mode never reads it from `moltnet.json`.       |
-| `MOLTNET_AGENT_KEY`   | no                                    | Team-bound agent key. Set to authenticate with the key instead of OAuth2. |
-| `MOLTNET_PRIVATE_KEY` | agent-key `once`, `poll`, and `drain` | Base64 Ed25519 seed used by daemon-owned executor attestation.            |
+| Var                   | Required                              | Purpose                                                                    |
+| --------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
+| `GIT_CONFIG_GLOBAL`   | OAuth2/local                          | Optional git identity path; not needed for configless agent-key startup.   |
+| `MOLTNET_AGENT_NAME`  | yes                                   | Agent name (matches `.moltnet/<name>/`).                                   |
+| `MOLTNET_API_URL`     | agent-key only                        | Explicit API endpoint; key mode never reads it from `moltnet.json`.        |
+| `MOLTNET_AGENT_KEY`   | no                                    | Team- or identity-scoped agent key. Set to authenticate instead of OAuth2. |
+| `MOLTNET_PRIVATE_KEY` | agent-key `once`, `poll`, and `drain` | Base64 Ed25519 seed used by daemon-owned executor attestation.             |
 
 For OAuth2/local mode, the agent's `moltnet.json` and gitconfig live next to
 each other in `.moltnet/<agent>/`. Provision them once via
@@ -96,24 +96,47 @@ each other in `.moltnet/<agent>/`. Provision them once via
 **Auth mode.** When `MOLTNET_AGENT_KEY` is set the daemon authenticates with
 that key as an opaque bearer token (no OAuth2 exchange); otherwise it uses the
 OAuth2 client-credentials from `moltnet.json`. The key is read from the
-environment only — never store it in `moltnet.json`. Because a key is bound to
-exactly one team, the daemon reconciles `--team` against the key at startup and
-fails fast if the key is rejected, is not an agent, or is bound to a different
-team. See
+environment only — never store it in `moltnet.json`. The daemon reconciles a
+team-bound key against `--team` at startup; an identity-scoped key may select
+any team where the agent is authorized. It fails fast if the key is rejected,
+is not an agent, or a team binding mismatches. See
 [Run the daemon with an agent key](../../docs/operate/running-agents.md#run-the-daemon-with-an-agent-key).
 
-Agent-key Pi guests always default to the `host-authenticated` boundary,
-regardless of local files: no `.moltnet` file, gitconfig, SSH signing key,
-GitHub App PEM, or MoltNet environment credential is read from the host or
-injected into Gondolin. Mounted `.moltnet` paths are hidden as well. Operators
-may explicitly opt into the legacy credential-bearing boundary with
-`--guest-credential-mode guest-config`; that mode requires a complete local
-`moltnet.json` + `env` pair. This compatibility mode copies the complete agent
-configuration and signing credentials into the guest; reserve it for local or
-otherwise operator-trusted execution. For unattended automation, shared
-runners, and remote deployments, prefer agent-key authentication with the
-default `host-authenticated` guest boundary. OAuth2 currently defaults to and
-requires `guest-config`.
+Daemon authentication and guest credential projection are two separate
+boundaries. How the daemon authenticates (an agent key, or OAuth2 resolved
+from `.moltnet/<agent>/moltnet.json` through the host secret provider) decides
+how the host-side SDK `Agent` is built. `--guest-credential-mode` decides
+whether the local agent credential tree is copied into Gondolin. Pi guests
+default to the `host-authenticated` boundary in **both** auth modes, regardless
+of local files: no `.moltnet` file, gitconfig, SSH signing key, GitHub App PEM,
+or MoltNet environment credential is injected into Gondolin, and mounted
+`.moltnet` paths are hidden. Structured MoltNet tools execute through the
+host-side `Agent`. Operators may explicitly opt into the legacy
+credential-bearing boundary with `--guest-credential-mode guest-config`; that
+mode requires a complete local `moltnet.json` + `env` pair and copies the
+complete agent configuration and signing credentials into the guest. Reserve it
+for local or otherwise operator-trusted tasks that genuinely need guest-shell
+MoltNet CLI, Git signing, or GitHub authentication. OAuth2 daemons that relied
+on the previous `guest-config` default for such tasks must now pass the flag
+explicitly.
+
+Trusted custom runtimes can deliver destination-bound HTTP credentials without
+switching to `guest-config`: the guest receives an opaque placeholder and the
+Gondolin host proxy substitutes the value only for the attested protocol,
+hostname pattern, and port (HTTPS/443 by default). See
+[Host-brokered HTTP credentials](../../docs/operate/running-agents.md#host-brokered-http-credentials).
+This does not provide diary or Git commit signing; private-key operations remain
+host capabilities.
+
+Host capabilities replace the last reason for `guest-config`: the stock runtime
+declares `agent-signing`, so `git commit -S` and `moltnet entry create-signed`
+work inside the guest while the seed stays on the host (the daemon injects a
+signer bound to the authenticated identity and projects a non-secret gitconfig,
+an `SSH_AUTH_SOCK` service, and `MOLTNET_SIGNER_URL`). Grant
+`capability:agent-signing` (or per-operation `capability:agent-signing:<op>`)
+in the tool policy. `--git-author "Name <email>"` / `MOLTNET_GIT_AUTHOR`
+overrides the projected git identity. See
+[Host capabilities](../../docs/operate/running-agents.md#host-capabilities).
 
 `sync-sessions` does not prepare or attest executors, so it remains independent
 of `MOLTNET_PRIVATE_KEY`.