agent-ui Package Skill

Package: @epicdm/agent-ui Repository: epic-flowstate-community Path: packages/agent-ui Version: 1.0.8

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Agent UI Cross-App Navigation

Status: Active Purpose: Generate FlowState Chat, Agents, and Org URLs for agent UI actions. Scope: src/links/* helpers and useAgentNavigation. Trigger: A component action should open agent chat, sessions, missions, proposals, worker, profile, or provision pages. Input: Agent, conversation, or mission IDs plus app base URL environment variables. Output: Safe URL strings or browser-open callbacks.

Environment Variables

getAppBaseUrl reads:

If an env var is missing, the helper returns an empty string so routes stay relative.

Route Helpers

Use route helpers from src/links/AgentLinks.ts:

Hook Workflow

1. Ensure the consuming app sets the relevant NEXT_PUBLIC_*_APP_URL variables when cross-origin navigation is required.
2. Call useAgentNavigation() inside React components.
3. Use get*Url helpers when rendering an anchor or passing a URL to a router.
4. Use open* helpers when the desired behavior is a new browser tab.
5. Keep callbacks at the app boundary so presentational components remain reusable.

Example

import { ActiveMissionsBadge, useAgentNavigation } from '@epicdm/agent-ui'

function AgentHeader({ agentId, activeMissionCount }: Props) {
  const nav = useAgentNavigation()

  return (
    <ActiveMissionsBadge
      count={activeMissionCount}
      onClick={() => nav.openMissions(agentId)}
    />
  )
}

Guardrails

• Do not hard-code app hostnames inside reusable components.
• Do not call window.open directly when useAgentNavigation already provides the action.
• Do not assume all FlowState apps are mounted on the same origin.
• For server-rendered code, use pure route helpers instead of useAgentNavigation.

Verification

yarn workspace @epicdm/agent-ui test __tests__/links __tests__/hooks/useAgentNavigation.test.ts
yarn workspace @epicdm/agent-ui typecheck

Composition

• Use with flowstate-agent-ui-profile-status for card, modal, and mission badge actions.
• Use with flowstate-agent-ui-unified-sessions for session row and recent-session deep links.

Package Skill Inventory

Skill Inventory: @epicdm/agent-ui

Package path: packages/agent-ui

Skill Map

Why This Split

The feature inventory lists 45 public features, but most compose into three recurring agent tasks:

• Agent identity and status display.
• Agent session aggregation and browsing.
• Cross-app navigation between Chat, Agents, and Org surfaces.

Creating one skill per component would hide the actual integration decisions an agent needs to make. The five-skill set keeps package usage teachable while still covering the public API groups and recurring maintenance risks.

Publication Notes

• Existing .flowstate/dojo package files are generated prototypes.
• Dojo publication should use these reviewed skills as source, not the generated package summary.

Review Gate

Package Skill Review: @epicdm/agent-ui

Package path: packages/agent-ui

Review Result

Status: source-backed and verified for local package-skill use; Dojo publication deferred until reviewed skill content is packaged for the Dojo API.

The skillset is workflow-shaped around the three real package jobs: present agent identity/status, aggregate/render sessions, and navigate between FlowState apps.

Checks

• Source review: completed from package metadata, source exports, README, tests, feature matrix, and generated Dojo artifacts.
• Skill inventory: completed.
• Skill files: completed.
• Verification: completed with one local lint tooling blocker below.
• Generated Dojo replacement: deferred; existing .flowstate/dojo files are generated prototypes.
• Cloud Dojo publication: deferred until reviewed skills are packaged into Dojo manifests.

Verification Commands

Verification completed before publication:

yarn workspace @epicdm/agent-ui test
yarn workspace @epicdm/agent-ui typecheck
yarn workspace @epicdm/agent-ui build
yarn workspace @epicdm/agent-ui lint
yarn nx build @epicdm/agent-ui

Results:

• ASCII validation passed for .flowstate/skills.
• typecheck passed.
• test --runInBand passed: 24 suites, 289 tests.
• build passed.
• yarn nx build @epicdm/agent-ui passed with cached dependency builds for @epicdm/flowstate-crypto and @epicdm/flowstate-collections; Nx reported the existing cloud workspace setup notice.
• lint could not run because the package script resolved to command not found: eslint.

Publication Gate

Do not publish existing .flowstate/dojo artifacts until they are rebuilt from reviewed package skills.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/agent-ui/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.