@mono-agent/agent-app 0.19.0 → 0.20.0

package/README.md

@@ -36,16 +36,40 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
 - Expose the request-scoped read-only `RunHistory` tool for safe normalized
   search and paged evidence from completed prior runs in the logical
   conversation, independent of daily rollover buckets.
+- Expose the sibling request-scoped read-only `SessionHistory` tool over the
+  harness's canonical retained managed-tool lifecycle sidecar.
+- Opt in to Pi-native Exec/Bash process jobs through `processJobs.*`: keep the
+  owner-private queue/store/process-group lifecycle, exact Slack/Telegram/web
+  wake with age-bounded busy deferrals, bounded pending/store materialization,
+  stable secret-free safety errors, native same-message lifecycle surfaces,
+  fail-closed live store health, a bounded monotonic registry that seals every
+  retained state root even after disable or reconfiguration, bounded locked
+  recovery through a fixed-name owner-private sibling directory while request
+  loading stays read-only and fail-closed, cooperative
+  official-process ownership, true-settlement generation barriers, provider-zero
+  for configured routes and direct memory LLM/embedding calls, restart interruption,
+  all-root separation from every clear-sessions purge, doctor section, operator
+  routes, and `mono-agent jobs` CLI at the app boundary. This
+  local contract does not resist a hostile same-UID provider; use OS privilege
+  separation when that is in the threat model.
 - Drive each channel through a uniform driver contract with per-channel
   `disabled` / `waiting_for_config` / `running` / `degraded` / `failed` status.
   `degraded` means a temporarily unavailable transport owns its recovery while
   the responder remains alive; `failed` is terminal until the host restarts or
   reloads that channel.
+- Own cron control truth in owner-private `.mono-agent/cron-control-v1/`:
+  durable per-job admission order, bounded run/event history, runtime enable
+  overrides, idempotency receipts, and audit. An absent store is initialized;
+  a present corrupt, insecure, or lease-conflicted store arms no cron jobs and
+  surfaces a degraded lifecycle/discovery reason plus an error log. Operator
+  actions are config-opt-in, API-key-protected, and explicitly confirmed; they
+  never rewrite config, environment, or Markdown job sources.
 - Register the host as a traceability source. Config edits are made directly in
   `mono-agent.config.json`, or proposed through the OS-owner-managed macOS
   configuration TUI; direct edits take effect on the next `mono-agent restart`.
-- Reconcile installed macOS LaunchAgents at login and every five minutes, and
-  make `status` require agreement between the cached trace and launchd's live PID.
+- Check managed launchd logs with bounded metadata reads every five minutes,
+  reconcile installed macOS LaunchAgents at login and hourly, and make `status`
+  require agreement between the cached trace and launchd's live PID.
 - Resolve and surface any configured `observability.exporters` (the Phoenix
   preset): `start`/`status` report the configured endpoint and a note that JSONL
   artifacts remain local; `validate` performs the live reachability probe. Export
@@ -61,12 +85,15 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
   lifecycle.
 - Operate the machine-wide `@mono-agent/web` assistant-ui console through
   `mono-agent web`, including persisted curated host themes and hostname
-  identity; publish a bounded, refreshable skill registry through each running
-  operator endpoint so the web composer can discover valid `$skill-name`
-  references; use `mono-agent tui` for bounded recorded-run replay.
-- Discover and expose one exact running agent through the Worklab-oriented ACP
-  core-session profile with `mono-agent bridge acp` while preserving agent-owned
-  configuration, workspace, sandbox, tools, MCP servers, and credentials.
+  identity; on macOS pair its worker with one helper-only, stopped-writer log
+  controller while the worker remains wake-only; publish a bounded, refreshable
+  skill registry through each running operator endpoint so the web composer can
+  discover valid `$skill-name` references; use `mono-agent tui` for bounded
+  recorded-run replay.
+- Discover and expose one exact running agent through the ACP core-session
+  profile with `mono-agent bridge acp`, including durable session resume, while
+  preserving agent-owned configuration, workspace, sandbox, tools, MCP servers,
+  and credentials.
 
 ## Install / Usage
 
@@ -264,15 +291,45 @@ preflight (`liveness: false`) skips both probes without changing structural
 validation.
 
 Managed launchd stdout/stderr use a fixed automatic policy: each active file
-and each of three retained generations is capped at 5 MiB. A separate one-shot
-LaunchAgent runs at login and every five minutes with no `KeepAlive` and
-`/dev/null` output. It first authenticates its exact launchd-owned PID,
-reconstructs the durable worker environment, validates config, and captures a
-fresh snapshot. It compares the strictly parsed loaded main definition and its
-verified runtime proof with the original controller CLI's inert version/digest;
-it never executes mutable source bytes. If the source disappeared, it can repair
-an inactive or snapshot-drifted worker from its private helper closure without
-claiming an upgrade or downgrading a healthy worker.
+and each of three retained generations is capped at 5 MiB. Once ready, the
+managed worker performs one overlap-guarded, read-only inventory immediately and
+every five minutes. The healthy below-threshold path ends there: it does not
+reconstruct the durable environment, validate config, capture a snapshot, or
+start another Node process. The immediate pass is observational: helper wakeups
+have a five-minute startup floor. A worker may wake only for a safely inspected
+per-agent active/retained log above 5 MiB or a safe owner-matching regular log
+whose permissions need repair. Shared-directory repair and pending lifecycle,
+journal, or preparation artifacts never wake the fleet; the scheduled helper
+owns those recovery cases.
+
+The separate controller keeps `RunAtLoad` for login recovery and runs once per
+hour at a stable minute: the unsigned big-endian first four bytes of SHA-256 of
+the canonical main LaunchAgent label, modulo 60. Login therefore deliberately
+retains N/N `RunAtLoad` recovery coverage, while recurring runs are staggered.
+The lightweight entries may start together, but each waits SHA-256(canonical
+main label)[0..3] unsigned-big-endian modulo 120 seconds before PID
+authentication, locking, or heavy import. This disperses the login heavy-work
+boundary without an account-wide admission lock or stale-owner state; a
+worker-requested wake can likewise wait at most 119 seconds. It has no `KeepAlive`
+and sends output to `/dev/null`. It then authenticates its exact launchd-owned
+PID and takes the per-config lifecycle lock without waiting,
+before attestation or importing the controller graph. A same-agent loser exits
+without expensive work. The helper plist enters through the managed closure's
+attested `dist/launchd-maintenance-entry.js`; the per-agent lock winner verifies
+that sibling entry against the shared path-free runtime proof and dynamically
+imports the heavy controller graph. It reconstructs the durable environment, captures a fresh snapshot,
+and compares the strictly parsed loaded main definition and its existing path-free
+managed-runtime launch proof with the original controller CLI's inert version/digest;
+it never executes mutable source bytes. A healthy pass does not run full structural
+validation or traverse the immutable closure. Full validation and managed-runtime
+installation/verification run only after those fast proofs identify drift, while
+the per-agent lock remains held. After runtime installation and all read-only
+rechecks, the helper takes the per-account shared-chain lock without waiting only
+for stopped-writer/shared-directory mutation; contention defers cleanly. Healthy
+log-only maintenance takes that shared lock separately. If the source
+disappeared, it can repair an inactive or snapshot-drifted worker from its
+private helper closure without claiming an upgrade or downgrading a healthy
+worker.
 
 The helper executes with a closed system `PATH` while carrying the worker's
 non-secret durable `PATH` as a private argument. Recovery therefore preserves
@@ -280,9 +337,11 @@ the worker's toolchain lookup without letting it shadow the helper's own system
 commands.
 
 When reconciliation is needed, the existing worker stays loaded through runtime
-installation. The helper then stops only the main job, refreshes both plists,
-bootstraps the main job, and waits for the normal 60-second readiness proof. A
-failure preserves the helper and both definitions for the next scheduled retry;
+installation. Under the shared mutation lock the helper then stops only the main
+job, repairs the shared log chain, refreshes both plists, and bootstraps the main
+job. It releases the shared lock before waiting for the normal 60-second readiness
+proof, while retaining the per-agent lifecycle lock. A
+failure preserves the helper and both definitions for the next hourly retry;
 explicit stop unloads the helper and removes both definitions after PID-death
 proof, so it cannot resurrect a stopped service. When log maintenance is needed,
 the helper takes the
@@ -296,13 +355,55 @@ removed only after the exact plist is rechecked and its worker is live. An
 interrupted pre-proof pass whose launchd PID is gone fails closed; durable
 `stopped` rotation can resume without authorizing another agent or an intentionally
 stopped service.
+Recurring drift recovery and shared-only repair therefore have a worst-case
+60-minute latency between logins; explicit start/restart remain synchronous.
+Worker requests use a process-local monotonic 5/10/20/40/60-minute cooldown,
+skip an unloaded or already-running helper, and recheck the shutdown latch
+immediately before `launchctl kickstart`. A pathological worker crash loop can
+still request about once per five minutes per agent after each new process.
+For an 11-agent pathological simultaneous crash loop, that residual bound is
+11 requests per five minutes.
+Every shared log-chain mutation takes one PID/incarnation-aware owner-private
+per-account lock after the per-agent lifecycle lock. Helpers defer immediately;
+interactive start/restart/stop wait up to 18 seconds, then fail visibly with
+the holder identity.
 Start and restart perform
 the same stopped-writer maintenance before loading helper then worker; stop
 unloads the helper first and removes both definitions. Unsafe paths or a changed
 plist fail closed without following links or resurrecting a stopped service.
 `mono-agent validate` / `doctor` only inspect metadata and report exact active,
 retained, and total bytes for safely inspected files; unsafe or unreadable byte
-inventory is unavailable. They never rotate or chmod logs.
+inventory is unavailable. They also render the owner-private monitor's last
+inspection, cumulative wake count, last outcome, and wall-clock rendering of
+the monotonic cooldown deadline. They never rotate or chmod logs.
+
+The loaded launchd definition, not the plist bytes on disk, is authoritative
+for migration. Existing agents retain their previously loaded interval until
+each agent is explicitly restarted after upgrade; a fleet restart is not
+performed automatically.
+
+The machine-wide web console uses the same rotation transaction over its exact
+`~/.mono-agent/web/logs/web.{out,err}.log` paths but a deliberately separate
+control domain. `com.mono-agent-web-maintenance` is a no-`KeepAlive`, `/dev/null`
+one-shot helper with `RunAtLoad`, a deterministic hourly minute, and the same
+0–119-second pre-import dispersion. The managed worker's five-minute monitor is
+wake-only and never stops or rotates the writer. The helper authenticates its
+launchd PID, cached private definition, attested runtime entry, exact helper
+bytes, and the main plist's composite `dev:ino:size:sha256` identity before and
+after taking the web lifecycle lock. Because web logs are outside the shared
+agent log directory chain, it never takes the agents' shared mutation lock.
+
+Every main-plist publication or restoration regenerates the helper from the
+fresh composite identity before either definition can be bootstrapped. Start
+and restart unload helper before worker, perform proven stopped-window
+maintenance, then bootstrap helper before worker. Stop unloads helper first and
+removes both plists only after death proof; reset requires both jobs stopped,
+both plists absent, and the same lifecycle lock. The fixed policy remains one
+active file plus three 5 MiB retained generations per stream. Refused legacy
+rollover artifacts are preserved while core rotation proceeds, and bounded
+owner-private monitor/maintenance status lets `mono-agent web status`
+distinguish active maintenance, routine `due`, durable failure, and abandoned
+recovery. `mono-agent web logs` tails only active names with `tail -F`.
 
 Guided readiness uses a worker-reproducible environment rather than the launching
 shell: durable `.env` values, entered selected secrets, the resolved Pi auth path,
@@ -368,22 +469,105 @@ projected values first pass through the shared observability redactor:
 non-numeric values under sensitive-looking object keys
 are redacted; numeric values under matched keys are retained; free text is not
 content-scanned or scrubbed. `RunHistory` then applies an additional projection
-sanitizer. In that second pass, numeric values under `credential`, `private_key`,
+sanitizer to object keys as well as string values, with deterministic
+collision-safe key disambiguation. In that second pass, numeric values under `credential`, `private_key`,
 and `bearer` can remain visible; numeric values under `apiKey`, `token`,
 `client_secret`, `password`, `authorization`, and `cookie` are redacted.
 Assignment-shaped password or secret prose is content-scanned and replaced with
 the diagnostic or tool-result omission sentinel. An optionally quoted assignment
 value is exempt only when its complete value is exactly `[redacted]`; any prefix
-or suffix is omitted. Results exclude the current/running run, unrelated
+or suffix is omitted. Ordinary filesystem spans are sanitized in place to
+`[host-path]` plus a bounded non-sensitive suffix, so surrounding commands,
+tool results, and assistant diagnostics remain visible; credentials and private
+run-artifact content are still omitted, and absolute roots or private run paths
+never survive. Results exclude the current/running run, unrelated
 conversations or threads, system prompts, reasoning, recalled memory,
 turn-context payloads, and raw artifact paths; historical text is marked
 untrusted.
 
+### Session tool history
+
+`SessionHistory` requires no config key. It is available under allow-all on
+request-scoped MCP-capable routes; a restrictive `tools.allowedTools` must name
+`SessionHistory` (`session_history` is also accepted by policy), and deny policy
+can remove it. Each request constructs a fresh stateless MCP server and transport
+on a host-bound loopback capability path. Direct OpenCode and ACP routes have no
+compatible host-tool seam for `SessionHistory`, so they still persist and
+cold-project tool records but suppress that new tool; `validate` reports
+`unsupported_route` rather than pretending coverage exists. Issue #626 does not
+change `RunHistory`'s pre-existing direct-ACP route wiring.
+
+The canonical data is not run JSONL, Pi JSONL, web SQLite, or message-history
+JSON. The harness incrementally writes every managed-tool start and terminal
+result to `history/tool-history/tool-lifecycles.sqlite`, independently of
+successful-turn commit. A lifecycle record may therefore exist without a
+canonical message-history entry. Stable conversation/run/tool-call keys and
+writer-assigned per-run start/end sequences make retries idempotent; process
+recovery closes dangling starts as `interrupted` without rerunning a tool.
+Arguments/results are securely pre-bounded, redacted, and byte-bounded, with truncation metadata and
+opaque artifact ids. Filesystem-shaped spans in object keys and string values use an opaque host-root token plus
+at most two non-sensitive trailing components, so commands and results remain
+inspectable without exposing an absolute root, account/home prefix, artifact
+root, or private run path. Only regular files beneath the configured run-specific
+`tool-output` root are accepted or checked for availability; provider-supplied
+outside or symlinked paths are dropped. Isolated/proactive
+runs persist but search excludes them unless explicitly requested.
+
+`{ "action": "search" }` returns at most 10 bounded previews with text,
+tool/state/run/time filters and a query-bound opaque cursor.
+`{ "action": "get", "recordId": "..." }` (or `toolCallId`) returns bounded
+chunks up to 8 KiB, with tombstones when retention removed known records.
+Only the exact physical `(conversationId, runId)` for the active turn is
+unavailable; an older rollover bucket that reused the same opaque run id remains
+readable. Unrelated-conversation records stay unavailable, daily rollover
+buckets remain one logical scope, nested history-tool result
+bodies are omitted, and every response is labelled untrusted. Cold context
+reseed receives the newest fitting chronological suffix in a neutralized UTF-8
+projection capped at 64 KiB including its truncation marker; warm provider resume
+continues natively and receives no replay. A zero-byte fresh sidecar is absent
+for automatic projection; another corrupt/unsafe projection emits a structured
+warning and continues the turn, while explicit SessionHistory reads fail closed.
+Lazy writer acquisition keeps one at-most-10-second restart-handoff attempt.
+After failure, writes from every already-created turn reuse that rejection and
+new turns fail immediately during an initial 30-second backoff. Each failed
+probe doubles that window up to five minutes, preventing ordinary consecutive
+turns during a sustained outage from repeatedly paying the full acquisition
+ceiling. The first later probe re-arms one full acquisition, while serialized
+explicit reset may bypass only the cooldown. A cached handle is retired after
+worker closure/death, one turn never reacquires mid-turn, and the recovered
+handle is shared; recovery resets the backoff. The outage emits one warning plus
+one later recovery warning.
+
+Telegram `/new` clears message records and tool records across the same logical
+session, including prior daily rollover buckets that canonical replay,
+SessionHistory, and cold projection can expose. A custom history store used with
+daily rollover must implement logical-session reset or the reset fails closed.
+The durable store holds one cross-process logical-session fence across discovery
+and every bucket reset, and appends take that same fence before their physical
+bucket lock.
+`restart --clear-sessions` purges all provider transcripts, message history, and
+tool history while reporting message/tool counts and bytes separately. Doctor
+audits schema, ownership, journal/integrity state, recovery, quota, and distinct
+unresolved fail-soft incidents. Repeating the same failed lifecycle retry does
+not inflate the count, and unrelated writes or run finalization cannot hide lost
+evidence; only the matching tool phase, its durable synthetic terminal closure,
+or canonical run-binding retry clears its incident while it remains retryable.
+Reset and retention clear only incidents whose exact run/call/record identity
+they make unretryable. A crash-stale zero-byte content database is reported as
+pristine and recoverable even when its protected DELETE journal remains; a live
+initialization and stale next-writer recovery are reported distinctly. A
+zero-byte owner database is also a recoverable initialization window, not a
+missing-table corruption report. A delayed real result supersedes that synthetic
+terminal record in place. A newer tool-history schema hard-fails downgrade until
+persisted conversation state is purged; an older compatible version is reported
+as upgrade-pending for the next writer.
+
 ### Channel interactions and conversation history
 
 For missing context, the agent should use active conversation history first,
-`MemoryRecall` for intentionally captured durable facts, and `RunHistory` for
-exact prior-run/tool evidence. Answered or expired blocking `AskUser` exchanges
+`MemoryRecall` for intentionally captured durable facts, `RunHistory` for exact
+prior-run evidence, and `SessionHistory` for retained managed-tool calls and
+results. Answered or expired blocking `AskUser` exchanges
 are written into the assistant history copy before the final response;
 cancelled asks are not journaled. The copy is explicitly labelled as untrusted
 historical data and bounded by newest whole interactions. If the newest valid
@@ -394,7 +578,7 @@ questions, each with two or three described options and an optional multi-select
 mode. Slack and Telegram present the questions sequentially with native buttons
 plus a typed custom reply; the web console renders the whole question set as one
 form. The built-in Telegram `/new` command uses the configured responder's
-host-owned reset surface to clear only that conversation and force
+host-owned reset surface to clear only that logical conversation and force
 skill/startup-context reload on its next turn.
 
 ### Memory health and maintenance
@@ -482,6 +666,71 @@ console.log(app.channelStatuses());
 await app.stop();
 ```
 
+### Reply files and MCP Apps
+
+The configured responder adds a request-scoped `PublishReplyFile` MCP tool when
+the tool policy and runtime route can carry it. The tool copies one generated
+ordinary-workspace file or one file from the exact current run's outbound root
+into owner-private artifact storage, hashes it, and returns only an opaque
+reference. The app composition explicitly treats its configured artifact root,
+the artifact-dir-derived durable conversation-history/session store,
+continuation state, memory, trace registry, provider sessions/auth, config,
+identity, skill, and MCP roots as private. Only the exact current run's outbound
+directory is admitted as a narrow artifact-root exception. Hidden path
+components, mono-agent/MCP/auth/credential/secret/token
+files, npmrc, private keys, certificates, key stores, state databases, and
+Unicode-disguised variants are rejected at every depth, including under the
+run-output exception. Publication rejects traversal, symlinks, multiply linked
+inodes, directory swaps, and source changes detected through the pinned file
+descriptor. Display names are NFC-normalized, stripped of Unicode bidi
+controls, and bounded at UTF-8/code-point boundaries; errors expose neither
+source paths nor bytes.
+
+Files are limited to 20 MiB, and files plus MCP Apps share one 20-part run
+budget. Their durable payloads and MCP audit files stay within a fixed 256 MiB
+aggregate file-byte ceiling: configured composition reserves 1 MiB for
+independently admitted audit files, leaving 255 MiB to the model-fillable shared
+budget.
+Admission is serialized, re-inventories both payload namespaces after restart,
+and fails only the new part explicitly when full; it does not evict active
+staging, current-run, or authorized in-flight content. Retried identities are
+deduplicated. A manifest
+that cannot accept its delivery-conversation binding becomes one bounded failed
+part while answer text and other valid parts survive. Terminal failure,
+cancellation, or missing run metadata removes uncommitted state. The sealed
+local self-configuration override excludes this publisher.
+
+Audit storage performs one root inventory for a process/root lifecycle, then
+maintains exact owner byte counts under a global append gate. Reclamation uses
+rotated history first, then inactive and unprotected owners' active files as a
+last resort; a live or protected owner's active `audit.jsonl` is never a
+candidate. Foreign read failures receive bounded conservative accounting and
+remain quarantined for the process lifetime; recovery requires a process
+restart and fresh root inventory. Every append, rotation,
+cleanup, and quota-reclamation mutation revalidates the audit root, owner
+directory, and singly linked file identities after the operation hook and before
+using the child path. Admission that cannot safely create room fails closed
+without changing unrelated or out-of-root history. Unsafe target files,
+symlinks, hard links, and directories fail that owner closed, while oversized
+target rotations receive the same safe bounded cleanup as foreign history.
+Audit records contain host identity, method,
+timestamp, and phase only—not model-filled tool names, arguments, resource URIs,
+URLs, or results. Tool confirmation reserves both its confirmation and bounded
+completion record before execution. A failed pre-execution admission returns
+`app_audit_failed` and refuses the tool call; a real completion write failure
+after a successful tool call remains `app_audit_incomplete` through operator
+and web transport because the side effect may have occurred and must not be
+retried automatically.
+
+Pi-native routes can retain MCP App resources negotiated at either supported
+ext-apps revision. The whole primary/fallback route must support the bridge;
+otherwise neither the runtime extension nor operator capability is exposed.
+Stored resources follow `artifacts.retention.maxAgeDays` within that aggregate
+ceiling; live connections are separately bounded by an eight-entry LRU and
+ten-minute idle timeout. See
+[Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
+for native channel behavior, fallbacks, browser security, and limits.
+
 ## Architecture
 
 ### Data flow
@@ -496,13 +745,21 @@ path:
    recorder, and request-scoped extensions.
 3. Start every driver in parallel. Each driver normalizes transport input into
    the shared request/stream contract and returns a `RunningChannel` handle. The
-   TUI driver primes its skill registry before binding and refreshes changed
-   `SKILL.md` metadata in memory while it runs.
-4. Publish traceability, exporter, sandbox, continuation, and memory-health
+   cron driver registers configured and disabled jobs but arms only their
+   effective runtime-enabled subset; its operator service feeds the TUI/web
+   capability lane. Process-job operator authority bypasses the generic channel
+   input and enters only the exact app-owned TUI driver through a private
+   composition hook. The TUI driver primes its skill registry before binding
+   and refreshes changed `SKILL.md` metadata in memory while it runs.
+4. Publish traceability, exporter, sandbox, process-job, continuation, and memory-health
    state while the controller tracks channel states as `disabled`,
    `waiting_for_config`, `running`, `degraded`, or `failed`.
 5. On stop or reload, stop the transport first, then dispose its responder so
    queued turns and warm provider sessions cannot outlive the config snapshot.
+6. For the managed macOS web console, publish the main and helper LaunchAgent
+   definitions as one composite-identity pair. The worker only wakes the helper;
+   the helper alone rotates after stopped-writer proof under the web lifecycle
+   lock and persists bounded recovery status.
 
 ### Package structure
 
@@ -512,8 +769,8 @@ path:
 | Configured agent | `configured-agent.ts`, `app-controller-responder.ts` | Runtime, harness, memory, history, tools, and recorder composition. |
 | Channel integration | `channels.ts`, `channel-drivers/` | Built-in drivers plus config-loaded plugin resolution. |
 | Interaction and send tools | `interaction-bridge.ts`, `adapter-send-tools*.ts` | Structured `AskUser` state, channel sinks, progress, adapter-send tools, and bounded interaction-history projection. |
-| Operator CLI | `cli*.ts`, `init.ts`, `doctor.ts`, `doctor-observability.ts`, `background*.ts`, `managed-web-logs.ts` | Setup, focused validation sections, managed service/log lifecycle, and diagnostics. |
-| Host services | `run-history.ts`, `continuation*.ts`, `memory-*.ts` | Bounded prior-run evidence, durable continuations, and memory operations. |
+| Operator CLI | `cli*.ts`, `jobs-command.ts`, `init.ts`, `doctor.ts`, `doctor-observability.ts`, `background*.ts`, `launchd*.ts`, `managed-web-logs.ts`, `web-*.ts` | Setup, focused validation sections, paired managed service/log lifecycle, process-job operation, and diagnostics. |
+| Host services | `run-history.ts`, `session-history.ts`, `request-scoped-mcp.ts`, `process-jobs*.ts`, `continuation*.ts`, `memory-*.ts` | Shared request-scoped guards, bounded prior-run/tool-lifecycle evidence, local process-job ownership/wake/recovery, durable continuations, and memory operations. |
 
 ## Public API
 
@@ -526,7 +783,12 @@ path:
 | Embed selected built-in channels | `defaultChannelDrivers`, `resolveChannelDrivers`, `createTelegramChannelDriver`, `createSlackChannelDriver`, `createWebhookChannelDriver`, `createOpenAIApiChannelDriver`, `createCronChannelDriver` |
 | Scaffold or validate an agent folder | `initMonoAgentFolder`, `validateMonoAgentFolder` |
 | Add bounded prior-run inspection | `createRunHistoryRuntimeExtension`, `isRunHistoryToolAllowed` |
-| Operate the CLI programmatically | `runCli`, `parseCliArgs`, `renderHelp` |
+| Add bounded retained-tool inspection | `createSessionHistoryRuntimeExtension`, `isSessionHistoryToolAllowed` |
+| Operate the CLI programmatically, including process jobs and the managed web lifecycle | `runCli`, `runJobsCommand`, `parseCliArgs`, `renderHelp` |
+
+The web maintenance controller and publication helpers remain private CLI
+implementation details; this change adds no new package-level public API for
+that lifecycle.
 
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
@@ -616,8 +878,11 @@ RunContinuationCommandOptions
 RunHistoryBinding
 RunHistoryRuntimeExtension
 RunHistoryRuntimeExtensionOptions
+RunJobsCommandOptions
 RunningChannel
 RunningRituals
+SESSION_HISTORY_MCP_SERVER_NAME
+SESSION_HISTORY_TOOL_NAME
 SandboxCheckResult
 SandboxCommandDependencies
 SandboxFunctionalCheck
@@ -626,6 +891,8 @@ SandboxRuntimeStatus
 SecretEnvRefusalCode
 SecretPersistenceOutcome
 SecretPersistenceStatus
+SessionHistoryBinding
+SessionHistoryRuntimeExtensionOptions
 SlackChannelOverrides
 StartMemoryRitualsInput
 TERMINAL_CONTINUATION_STATES
@@ -655,6 +922,8 @@ createCronChannelDriver
 createOpenAIApiChannelDriver
 createRunHistoryRuntimeExtension
 createRunHistoryServer
+createSessionHistoryRuntimeExtension
+createSessionHistoryServer
 createSlackChannelDriver
 createTelegramChannelDriver
 createWebhookChannelDriver
@@ -669,6 +938,7 @@ isColorEnabled
 isContinuationMode
 isContinuationState
 isRunHistoryToolAllowed
+isSessionHistoryToolAllowed
 keyValue
 loadAppCoreConfig
 loadCliEnvFile
@@ -690,6 +960,7 @@ resolveChannelDrivers
 rule
 runCli
 runContinuationCommand
+runJobsCommand
 runSandboxCommand
 runtimeUsesFallbackRouter
 sandboxRuntimeStatus
@@ -728,6 +999,7 @@ compose communication adapters; adapters never depend on it.
 - [Programmatic composition](https://mono-agent-docs.vercel.app/programmatic/composition/)
 - [Channels](https://mono-agent-docs.vercel.app/channels/)
 - [Local-first web research](https://mono-agent-docs.vercel.app/tools/web-research/)
+- [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
 - [Package source and generated API inventory](https://github.com/robertsreberski/mono-agent/tree/main/packages/agent-app)
 
 ## Verification

package/dist/acp-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-bridge.d.ts","sourceRoot":"","sources":["../src/acp-bridge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0DjD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;CAC3C;AAaD,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4FhF"}
+{"version":3,"file":"acp-bridge.d.ts","sourceRoot":"","sources":["../src/acp-bridge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAiEjD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;CAC3C;AAeD,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+GhF"}