@borgee/agents-host 0.2.101 → 0.2.110

package/README.md

@@ -101,7 +101,7 @@ Rollback and hardening controls stay explicit:
 - `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=<comma-list>` disables shipped gates for rollback
 - `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=copilot:v1` forces Copilot back to the v1 adapter while its v2 gate stays enabled; stale `claude:v1|v2` entries are tolerated as no-ops for compatibility
 - `AGENTS_HOST_INTERNAL_POLICY_MODE=enforce` hardens the shipped `policy-audit-enforcement` gate beyond its default `audit-only` mode
-- `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=provider-idle-shutdown` keeps every provider runtime process resident again; `PROVIDER_IDLE_SHUTDOWN_MINUTES=0` does the same without touching gates
+- `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=provider-idle-shutdown` keeps legacy provider runtime processes resident again; `PROVIDER_IDLE_SHUTDOWN_MINUTES=0` does the same without touching gates
 
 Or with the CLI:
 
@@ -237,13 +237,85 @@ Notes:
 | `AGENTS_HOST_DISABLE_UPDATE_CHECK` | —                                      | no       | off                                           | Set to `1` to skip the advisory startup update check.                                            |
 | `BORGEE_AGENT_NAME`                | `--name`                               | no       | `Assistant`                                   | Display name used in prompts                                                                     |
 | `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude`, `copilot`, or `codex`                                                                  |
+| `PROVIDER_OUTPUT_MODE` | `--provider-output-mode` | no | `legacy` | Select `legacy` or `normalized` explicitly. The selection does not change provider identity. |
+| `NATIVE_PROVIDER_COMMAND` | `--native-provider-command` | no | pinned native executable | Executable path used only by the normalized provider; not a shell command or an ACP argument string. |
 | `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude-agent-acp` / empty                    | Local Claude ACP adapter command + args. The shipped bundled `claude-agent-acp` path requires empty `CLAUDE_ARGS`; non-empty args are only valid when `CLAUDE_COMMAND` points at a custom ACP adapter command. Legacy `claude --print --permission-mode bypassPermissions` is tolerated as a compatibility alias. |
 | `CODEX_COMMAND` / `CODEX_ARGS`     | `--codex-command` / `--codex-args`     | no       | `codex-acp` / empty                           | Local Codex ACP adapter command + args. The default launch resolves the bundled `@agentclientprotocol/codex-acp` entrypoint. |
-| `COPILOT_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored                 | Local Copilot CLI command. The host resolves it to an executable and starts the SDK headless JSON-RPC runtime; legacy `COPILOT_ARGS` remain ignored. |
+| `CODEX_CONNECTION_MODE` | `--codex-connection-mode` | no | `stdio` | Normalized Codex transport: `shared` attaches to a daemon, `stdio` owns a native process. Legacy mode keeps its ACP adapter. |
+| `CODEX_TRUST_SHARED` | local YAML `codexTrustShared` | normalized Codex shared only | unset | Explicit local consent to control the shared Codex daemon with its existing native permissions. |
+| `CODEX_SHARED_SOCKET_PATH` | local YAML `codexSharedSocketPath` | no | native `CODEX_HOME` control socket | Absolute Unix socket path for normalized shared Codex. The daemon must already be running; there is no stdio fallback. Requires explicit shared mode; incompatible with default or explicit stdio mode. |
+| `SESSION_WORKSPACE_ROOT` | local YAML `sessionWorkspaceRoot` | no | unset | Existing absolute directory for explicit independent normalized Codex Session creation. An unset root disables Create only; discovery and opening preserve existing native Workspaces. |
+| `COPILOT_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored                 | Legacy Copilot CLI command. The host resolves it to an executable and starts the SDK headless JSON-RPC runtime; legacy `COPILOT_ARGS` remain ignored. Neither setting selects the normalized executable. |
 | `COPILOT_SESSION_TTL_MINUTES`      | `--copilot-session-ttl-minutes`        | no       | `2880`                                        | Idle TTL for per-channel Copilot SDK sessions                                                    |
-| `PROVIDER_IDLE_SHUTDOWN_MINUTES`   | `--provider-idle-shutdown-minutes`     | no       | `10`                                          | Idle window before the agent's shared provider runtime **process** is shut down and re-spawned on the next turn. Applies to Claude, Codex, and Copilot. `0` keeps the process resident. Must be non-negative and no larger than the Node.js timer limit (~35791.39 minutes); anything else is rejected at startup. |
+| `PROVIDER_IDLE_SHUTDOWN_MINUTES`   | `--provider-idle-shutdown-minutes`     | no       | `10`                                          | Idle window before the legacy provider runtime **process** is shut down and re-spawned on the next turn. Applies to legacy Claude, Codex, and Copilot; normalized adapters do not use this timer. `0` keeps the process resident. Must be non-negative and no larger than the Node.js timer limit (~35791.39 minutes); anything else is rejected at startup. |
 
-`COPILOT_SESSION_TTL_MINUTES` and `PROVIDER_IDLE_SHUTDOWN_MINUTES` are two different layers and do not replace each other. The first evicts an individual idle Copilot SDK *session* inside a running runtime process. The second shuts the shared provider *process* itself down once every channel it hosts is idle, for all three providers, and takes every live session in that process with it. See [Conversation memory](#conversation-memory) for what happens to those sessions afterwards.
+`COPILOT_SESSION_TTL_MINUTES` and `PROVIDER_IDLE_SHUTDOWN_MINUTES` are two different layers and do not replace each other. The first evicts an individual idle Copilot SDK *session* inside a running runtime process. The second shuts the legacy provider *process* itself down once every channel it hosts is idle and takes every live session in that process with it. Normalized Codex does not use this timer: shared mode releases only its attachment, while stdio mode owns the native process lifetime. See [Conversation memory](#conversation-memory) for what happens to those sessions afterwards.
+
+## Choosing legacy or normalized output
+
+Claude, Codex, and Copilot keep legacy output when no mode is configured. Select normalized Copilot explicitly to use the common normalized adapter with the Copilot provider over official SDK stdio:
+
+```bash
+agents-host start https://your-borgee-server bgr_xxxxxxxx --provider copilot --provider-output-mode normalized
+agents-host start-managed https://your-borgee-server bgr_xxxxxxxx --provider copilot --provider-output-mode normalized
+```
+
+Use `--native-provider-command /absolute/path/to/copilot` only when overriding the pinned normalized executable. `--copilot-command`, `--copilot-args`, and the legacy idle timers remain settings for the separate legacy adapter. Select `--provider-output-mode legacy` to return to that adapter; switching adapters does not migrate their session stores.
+
+For positional `start` and full `start-managed`, an explicit CLI flag overrides its environment variable. An omitted flag preserves the environment value. Repeating a full managed start preserves a saved Agent's output mode and native executable unless the flag or environment variable explicitly supplies a replacement. Bare `start-managed <serverUrl>` resumes the saved configuration and rejects Agent flags.
+
+File-based startup owns its provider settings: `start --config` rejects single-agent flags, and ambient `PROVIDER_OUTPUT_MODE` / `NATIVE_PROVIDER_COMMAND` do not override YAML. Agent entries override host `defaults`. The same `providerOutputMode` and `nativeProviderCommand` fields work in JSON specs supplied to `generate-config` and `apply-managed`; neither command needs separate mode flags.
+
+```yaml
+# agents-host.yaml
+borgeeBaseUrl: https://your-borgee-server
+defaults:
+  providerOutputMode: legacy
+```
+
+```yaml
+# agents/copilot.yaml
+key: copilot
+name: Copilot
+apiKey: bgr_xxxxxxxx
+provider: copilot
+providerOutputMode: normalized
+```
+
+The normalized Copilot provider owns its stdio runtime and closes it with the Host lifecycle. Its available controls come from negotiated native capabilities; selecting normalized output does not enable independent native Session management for Copilot.
+
+## Normalized Codex connections
+
+Normalized Codex uses `stdio` mode by default: the Host owns a native `codex app-server` process without requiring a shared daemon or shared trust. The mode may also be selected explicitly:
+
+```bash
+agents-host start https://your-borgee-server bgr_xxxxxxxx --provider codex --provider-output-mode normalized
+agents-host start-managed https://your-borgee-server bgr_xxxxxxxx --provider codex --provider-output-mode normalized --codex-connection-mode stdio
+```
+
+The environment entrypoint accepts `CODEX_CONNECTION_MODE=shared|stdio`; local YAML and generated JSON accept `codexConnectionMode: shared|stdio` in host defaults or Agent entries. CLI flags override environment values, Agent entries override host defaults, and repeated managed startup preserves the saved mode unless explicitly replaced. A mode change restarts that Agent's Host instance while retaining its state root and native session mappings. `--native-provider-command /absolute/path/to/codex` selects the normalized executable; legacy Codex keeps its separate ACP command and ignores native connection selection.
+
+Both connection modes preserve the configured native approval and sandbox policy. Choosing stdio changes process ownership and transport; it does not grant shared-daemon trust or impose additional permission restrictions. A configured `codexSharedSocketPath` / `CODEX_SHARED_SOCKET_PATH` is rejected with default or explicit normalized stdio. Neither socket configuration nor shared trust selects shared mode implicitly; socket-only configurations must add `codexConnectionMode: shared` or `CODEX_CONNECTION_MODE=shared`. In mixed-mode local configurations, put shared socket overrides on the shared Agents rather than in host defaults; an Agent cannot clear an inherited socket with `null` or an empty value.
+
+For shared mode, prepare a daemon with a compatible installed Codex CLI before starting the Host. Select its absolute executable path explicitly; `app-server daemon start` is available in Codex 0.154.0:
+
+```bash
+CODEX_BIN=/absolute/path/to/codex
+"$CODEX_BIN" app-server daemon start
+BORGEE_BASE_URL=https://your-borgee-server.example \
+BORGEE_AGENT_API_KEY=your-agent-key \
+RUNTIME_PROVIDER=codex \
+PROVIDER_OUTPUT_MODE=normalized \
+CODEX_CONNECTION_MODE=shared \
+CODEX_TRUST_SHARED=true \
+node packages/agents-host/dist/index.js
+```
+
+Use the same `CODEX_HOME` as the local native clients. The default control socket is `$CODEX_HOME/app-server-control/app-server-control.sock`, with `~/.codex` as the native home fallback. Set `CODEX_SHARED_SOCKET_PATH` to an absolute socket path when using another daemon. Local YAML accepts `providerOutputMode: normalized`, `codexConnectionMode: shared`, `codexTrustShared: true`, and `codexSharedSocketPath` in defaults or the Agent entry.
+
+Explicit New allocates an exclusive `yyMMdd/HHmmss${rand}` directory beneath `sessionWorkspaceRoot`, using the Host machine's local time. Configure this value in local YAML defaults or the Agent entry, or set `SESSION_WORKSPACE_ROOT` for the environment entrypoint. Discovery is not restricted to this root. Management requires Agent Owner authority, and mutations require a writable channel; independent Sessions never replace the ordinary Messages default. Ownership claims use the existing atomic file-store implementation under `independent-sessions/codex.json`. Only committed claims survive restart; a native creation whose claim cannot be saved stays unconfirmed. Reopening a Session does not create a fallback identity or submit an initial message, and successful admission alone does not guarantee empty-session persistence across native daemon restart.
+
+Trust grants access under the daemon's existing native approval and sandbox policy. Without explicit local trust the Host rejects shared mode; it never falls back to stdio. Closing a shared attachment leaves the daemon and other clients running. A lost shared socket suspends controls while the provider reconnects and restores the same native Session from authoritative state; uncertain inputs are not replayed. Stdio process loss stops observation and rejects pending operations without automatically replacing the process or resubmitting input. Legacy mode retains its existing process and permission behavior.
 
 ## Local-config mode
 
@@ -500,7 +572,7 @@ We keep no transcript or history store of our own — only the native session id
 
 ### Idle adapter shutdown
 
-Each of those subprocesses is shut down once every channel it hosts has been idle for `PROVIDER_IDLE_SHUTDOWN_MINUTES` (default `10`), and a fresh one is spawned lazily on the next turn. "Idle" means the host has no active turn, no queued turn, no provider session start in flight, and nothing still being processed for any channel of that agent; a turn that arrives mid-shutdown waits for the teardown and then starts the replacement rather than failing. Only the provider subprocess is recycled — the agent stays connected to Borgee, the loopback gateway keeps running, and the agents-host process itself is untouched.
+In legacy mode, each of those subprocesses is shut down once every channel it hosts has been idle for `PROVIDER_IDLE_SHUTDOWN_MINUTES` (default `10`), and a fresh one is spawned lazily on the next turn. "Idle" means the host has no active turn, no queued turn, no provider session start in flight, and nothing still being processed for any channel of that agent; a turn that arrives mid-shutdown waits for the teardown and then starts the replacement rather than failing. Only the provider subprocess is recycled — the agent stays connected to Borgee, the loopback gateway keeps running, and the agents-host process itself is untouched.
 
 Conversation memory normally survives the recycle. Before the process goes away the host closes each live provider session, and on the next turn it reopens the persisted session id against the CLI's on-disk store — Claude and Codex through ACP `session/resume`, Copilot through SDK session resume. This is the same restore path a host restart takes, and its ordinary outcome is that the model still remembers the conversation.
 

package/dist/agents-host.d.ts

@@ -9,6 +9,8 @@ import type { AgentsHostConfig } from './types.js';
  */
 export declare class AgentsHost {
     private readonly config;
+    private executionTelemetry?;
+    private readonly normalizedStateOwners;
     private readonly runtime;
     private readonly provider;
     private readonly borgee;
@@ -64,6 +66,7 @@ export declare class AgentsHost {
     private runClaimedExecution;
     private runMessageWithExecutionTelemetry;
     private createExecutionTelemetryReporter;
+    private handleSelectedSessionMessage;
     private dispatchAutonomousReply;
     private handleLegacyMessage;
     private handleCollaborationMessage;
@@ -145,6 +148,11 @@ export declare class AgentsHost {
     private updateMissedCollaborationDiagnostic;
     private noteWakeSuppressedAttentionPolicy;
     private runUngatedTurn;
+    private handleSessionControl;
+    private handleRetainedControl;
+    private handleNativeInput;
+    private postTurnReply;
+    private beginNormalizedExecution;
     private executeTurn;
     /**
      * Opens this turn's report on the activity rail.