Allow a configurable Agent Profile to power Huabu functional workflows #203

Summary

Allow users to choose an Agent Profile in Global Settings as Huabu's functional Agent: the Agent that executes product-level AI workflows such as Make Summary, memory extraction/maintenance, and future Huabu-assisted operations.

The selected Profile may be Huabu's built-in huabu Profile or a Bring Your Own Agent (BYOA) external Profile. The built-in Agent becomes one selectable implementation rather than a hard-coded execution path.

Motivation

Huabu currently has product features whose orchestration is coupled to the built-in Agent/runtime. Users who prefer an external Agent should be able to use it throughout Huabu, not only in explicit Agent Node conversations. A single configured functional-Agent identity provides a coherent default while retaining the built-in experience as a supported option.

User experience

• Add a Global Setting for the Huabu functional Agent Profile.
• List all eligible Profiles, including the built-in huabu Profile and supported BYOA Profiles.
• Use the selected Profile for supported product workflows, initially including at least:
  • Make Summary and related summarization actions.
  • Memory extraction, organization, retrieval-assisted maintenance, or other Agent-backed memory workflows.
  • Additional built-in-Agent features after they are inventoried and explicitly migrated.
• Clearly distinguish this global functional default from the Profile selected for a specific Agent Node or conversation.
• Show which Profile will execute an action where cost, privacy, placement, latency, or availability may matter.
• Provide an explicit way to return to the built-in huabu Profile.

Required design and inventory

Before implementation, inventory every user-visible and background workflow that currently invokes the built-in Huabu Agent or assumes its model/provider/tooling. For each workflow, classify whether it:

• Can run through the generic Agent Profile contract unchanged.
• Requires Huabu capabilities/tools to be exposed to external Agents.
• Requires structured output, deterministic orchestration, privileged server access, or a specialized fallback.
• Must remain server-owned rather than delegated to an arbitrary Profile.
• Is interactive, background, scheduled, retryable, or attached to a specific Space/Node.

Define one canonical functional-workflow invocation contract rather than adding per-feature Profile switches.

Behavior and lifecycle

• Persist the selected stable Profile ID in Global Settings; do not use display names as identity.
• Define whether the setting is user-, installation-, or deployment-scoped and how it behaves across Web/Desktop clients and remote Servers.
• Resolve the effective Profile when a workflow starts and persist enough execution identity for audit, retry, and recovery.
• Existing in-flight work must not silently switch Profiles when the setting changes.
• Profile rename should preserve selection. Profile deletion, unavailability, disconnected agentlet, unsupported capability, or failed startup must be explicit.
• Do not silently execute with a different Profile. Any fallback to huabu must be a deliberate, visible user policy rather than an implicit success-shaped fallback.
• Read-only UI actions must not realize an external workload. Realization begins only when the functional workflow is invoked.
• Define cancellation, timeout, retry, idempotency, concurrency, and result persistence for background workflows.

Capability and security requirements

• External Profiles must receive only the tools and Space context required by the invoked workflow.
• Preserve Space, tenant, user, and Node authorization boundaries.
• Keep provider credentials and Huabu integration secrets server-side.
• Apply capability allowlists, validation, audit attribution, cost/resource limits, and safe result handling.
• Treat Agent output as untrusted. Validate required structured results before applying them to Space content or memory.
• Make prompt/skill selection explicit and versioned so a Profile change does not bypass workflow-specific instructions or policy.
• Do not grant a functional Agent broader RFS or filesystem authority merely because it is globally selected.

Dependencies and related issues

• Prerequisite: Automatically provision external Agent Profiles from agentlet discovery #174. The BYOA onboarding work must provide discoverable/selectable external Profiles, stable machine/harness identity, execution placement, working-directory semantics, availability state, and lifecycle recovery before an external Profile can reliably become the global functional Agent.
• Capability-enablement sub-workstream: Expose configured Huabu capabilities to external agents #110. External Agents need a secure, capability-scoped way to invoke configured Huabu tools such as web search and image generation. Expose configured Huabu capabilities to external agents #110 is independently useful, but it is part of achieving functional parity for workflows that require those capabilities.
• This issue owns the global Profile selection, workflow inventory, invocation routing, execution identity, migration, UX, and fallback semantics. It should not absorb the full BYOA onboarding implementation or duplicate each capability contract from Expose configured Huabu capabilities to external agents #110.

Acceptance criteria

• Global Settings allows selecting the built-in huabu Profile or an eligible external Profile as the functional Agent.
• The stable selection persists at the documented scope and hydrates consistently across supported clients.
• Make Summary and the agreed memory workflows execute through the selected Profile using one canonical invocation path.
• The workflow records the effective Profile/placement identity and does not change it mid-execution.
• Changing, renaming, deleting, disconnecting, or making the selected Profile unavailable has explicit behavior without silent fallback.
• External Profiles receive only workflow-scoped context and capabilities; secrets remain server-side and structured outputs are validated before mutation.
• Unsupported Profile capabilities are detected before or during invocation with actionable errors.
• Built-in huabu behavior remains available and compatible.
• Regression coverage includes built-in and external Profiles, reload/settings hydration, remote execution placement, Profile lifecycle changes, unavailable capabilities, cancellation/retry, concurrent workflows, invalid Agent output, and authorization boundaries.
• Architecture documentation describes the functional-Agent role, settings ownership, invocation contract, capability boundary, lifecycle, fallback policy, and migrated workflow inventory.