Agent Architecture Review, Snapshot di validazione

Optimise for steering, not only initiating

The workflow can be initiated and streamed, but it is not steerable while underway. `AIClient.queryStream` passes options such as `maxTurns` and `resume`, but there is no abort controller, pause/resume command, dynamic constraint update, or side-effect checkpoint in this layer. `ListenersManager.checkEvent` runs matching listeners to completion once triggered, and email mutation helpers do not check for cancellation or changed policy before acting. `ActionsManager.executeAction` executes a handler once and returns a result; retry, rollback, reprioritisation, and mid-run correction are not represented.

Establish trust through inspectability

The code has partial inspectability through `LogWriter.appendLog`, `ActionsManager.logExecution`, `UIStateManager.logStateUpdate`, and `search_inbox` log files, but the audit boundary is insufficient for accountable autonomous work. There is no persistent `run_id` correlating `AIClient.queryStream` messages, listener invocations, email mutations, UI state updates, and action executions. `callAgent()` does not record the prompt, model, schema, response, or tool-use rationale; listener log writes are fire-and-forget; and JSONL files are not tamper-evident. `custom-tools.ts` also writes full formatted email results, including `body`, to local log files, which improves traceability but creates a…

Design for delegation rather than direct manipulation

The code supports delegation mechanically through `ListenersManager.checkEvent`, `ActionsManager.executeAction`, and the prompt’s listener/action creation model, but delegated authority is not represented as a governed scope. `createContext()` hands every enabled listener helpers such as `archiveEmail`, `starEmail`, `markAsRead`, `addLabel`, `callAgent`, and `uiState.set` without a persistent authority envelope, per-listener permission scope, or lifecycle controls beyond `config.enabled`. `AIClient.defaultOptions.allowedTools` also grants broad tools including `Task`, `Bash`, `Edit`, `Write`, `WebFetch`, and `WebSearch` without tying them to user-stated constraints.

Ensure that background work remains perceptible

Background work is only partially perceptible. `ListenersManager` writes a `ListenerLogEntry` after a handler finishes and optionally calls `logBroadcastCallback`, while `ActionsManager.logExecution` appends JSONL logs, but there is no persistent run record showing `queued`, `active`, `blocked`, `awaiting approval`, or `failed` while work is in progress. `this.logWriter.appendLog(...).catch(...)` is fire-and-forget, so audit/status failures are not part of task state. `MessageQueue.close()` sets `closed = true` and drops `resolvers` without resolving pending `next()` calls, which can strand waiters silently.

Replace implied magic with clear mental models

The prompt in `EMAIL_AGENT_PROMPT` gives a helpful high-level mental model and distinguishes `Listeners = Automatic/event-triggered` from `Actions = User-triggered/on-demand`, but the actual runtime capabilities are much broader than that model. `AIClient.defaultOptions.allowedTools` includes `Bash`, `Edit`, `Write`, `Task`, `WebFetch`, and `WebSearch`; `custom-tools.ts` returns untrusted email `body` content into the agent context; and listener handlers receive email mutation functions without an explicit permissions explanation. Users can therefore underestimate what the agent can execute and what conditions govern automation.

Represent delegated work as a system, not merely as a conversation

The code represents parts of the system as managers (`ListenersManager`, `ActionsManager`, `ComponentManager`, `UIStateManager`) rather than only as chat, but delegated work is not modeled as a coherent execution system. `AIClient.queryStream` yields SDK messages, `ActionsManager.instances` and `ComponentManager.instances` are in-memory maps, listener invocations are per-event loops, and logs are separate JSONL files. There is no run graph, task timeline, dependency model, or shared orchestration record tying an agent session to listener-created actions, component state, email reads, and email mutations.

Expose meaningful operational state, not internal complexity

Operational state is mixed with implementation details. `ListenerLogEntry` includes user-relevant fields such as `emailSubject`, `emailFrom`, `executed`, and `reason`, but action logs expose `instanceId`, `templateId`, `sessionId`, raw `params`, and `result` without a user-facing state model. The code does not define stable operational statuses such as `queued`, `active`, `awaiting_approval`, `blocked`, `complete`, or `failed`; instead, state is inferred from logs, console errors, in-memory maps such as `instances`, and SDK message streams.

Align feedback with the user’s level of attention

Feedback is not calibrated to user attention. `notify()` accepts `options?.priority` but only forwards a generic `listener_notification`; listener execution always emits the same log shape regardless of risk, uncertainty, or required intervention. Most failures are written to `console.error` in `loadAllListeners`, `loadListener`, `watchListeners`, `loadTemplate`, and tool handlers rather than being escalated as user-actionable states. There is no distinction between foreground monitoring, passive background operation, and absent-user escalation.

Apply progressive disclosure to system agency

There are some disclosure building blocks, such as `search_inbox` returning a summary plus `logFilePath` and listener/action JSONL logs preserving details, but the layer does not consistently separate primary outcome from diagnostic detail. `read_emails` returns full email bodies directly to the agent, `logBroadcastCallback` receives raw `actions` and `error`, and there is no structured user-facing summary/detail boundary for tool usage, decision logic, or confidence-sensitive inspection.